lustre/doc/lfs-find.1

   1 .TH lfs-find 1 "2018-01-24" Lustre "user utilities"
   2 .SH NAME
   3 lfs-find \- Lustre client utility to list files with specific attributes
   4 .SH SYNOPSIS
   5 .B lfs find \fR<\fIdirectory\fR|\fIfilename \fR...>
   6       [[\fB!\fR] \fB--atime\fR|\fB-A\fR [\fB-+\fR]\fIn[smhdwy]\fR]
   7 [[\fB!\fR] \fB--blocks\fR|\fB-b\fR [\fB+-\fR]\fIn\fR]
   8       [[\fB!\fR] \fB--btime\fR|\fB-B\fR [\fB+-\fR]\fIn[smhdwy]\fR]
   9 [[\fB!\fR] \fB--ctime\fR|\fB-C\fR [\fB+-\fR]\fIn[smhdwy]\fR]
  10       [[\fB!\fR] \fB--component-count|\fB--comp-count\fR [\fB+-\fR]\fIn\fR]
  11       [[\fB!\fR] \fB--component-end|\fB--comp-end\fR|\fB-E\fR [\fB+-\fR]\fIn\fR[\fBKMGTPE\fR]]
  12       [[\fB!\fR] \fB--component-flags|\fB--comp-flags\fR [^]\fIFLAG\fB,\fR...]
  13       [[\fB!\fR] \fB--component-start|\fB--comp-start\fR [\fB+-\fR]\fIn\fR[\fBKMGTPE\fR]]
  14       [[\fB!\fR] \fB--extension-size|\fB-z\fR [\fB+-\fR]\fIn\fR[\fBKMG\fR]]
  15       [[\fB!\fR] \fB--foreign\fR [\fITYPE\fR]]
  16 [[\fB!\fR] \fB--gid\fR|\fB-g\fR|\fB--group\fR|\fB-G\fR \fIGNAME\fR|\fIGID\fR>]
  17       [\fB--help\fR|\fB-h\fR]
  18 [[\fB!\fR] \fB--layout\fR|\fB-L mdt\fR,\fBraid0\fR,\fBreleased\fR]
  19 [\fB--lazy\fR]
  20       [\fB--maxdepth\fR|\fB-D\fI n\fR]
  21 [[\fB!\fR] \fB--mdt\fR|\fB--mdt-index\fR|\fB-m\fR \fIUUID\fR|\fIINDEX\fR,...]
  22       [[\fB!\fR] \fB--mdt-count\fR|\fB-T\fR [\fB+-\fR]\fIn\fR]
  23 [[\fB!\fR] \fB--mdt-hash\fR|\fB-H \fR<[^]\fIHASHFLAG\fR,[^]\fIHASHTYPE\fR,...>]
  24       [[\fB!\fR] \fB--mirror-count|\fB-N\fR [\fB+-\fR]\fIn\fR]
  25 [[\fB!\fR] \fB--mirror-state\fR [^]\fISTATE\fR]
  26       [[\fB!\fR] \fB--mtime\fR|\fB-M\fR [\fB-+\fR]\fIn[smhdwy]\fR]
  27 [[\fB!\fR] \fB--name\fR|\fB-n \fIPATTERN\fR]
  28       [[\fB!\fR] \fB--newer\fR[\fBXY\fR] \fIREFERENCE\fR]
  29       [[\fB!\fR] \fB--ost\fR|\fB-O\fR \fIINDEX\fR,...]
  30       [[\fB!\fR] \fB--perm\fR [\fB/-\fR]\fIMODE\fR ]
  31 [[\fB!\fR] \fB--pool\fR \fIPOOL\fR]
  32 [\fB--print\fR|\fB-P\fR]
  33       [\fB--print0\fR|\fB-0\fR]
  34 [[\fB!\fR] \fB--projid\fR \fIPROJID\fR]
  35       [[\fB!\fR] \fB--size|\fB-s\fR [\fB-+\fR]\fIn\fR[\fBKMGTPE\fR]]
  36 [[\fB!\fR] \fB--stripe-count|\fB-c\fR [\fB+-\fR]\fIn\fR]
  37       [[\fB!\fR] \fB--stripe-index|\fB-i\fR \fIn\fR,...]
  38 [[\fB!\fR] \fB--stripe-size|\fB-S\fR [\fB+-\fR]\fIn\fR[\fBKMG\fR]]
  39       [[\fB!\fR] \fB--type\fR|\fB-t\fR {\fBbcdflps\fR}]
  40 [[\fB!\fR] \fB--uid\fR|\fB-u\fR|\fB--user\fR|\fB-U  \fIUNAME\fR|\fIUID\fR]
  41 .SH DESCRIPTION
  42 .B lfs find
  43 is similar to the standard
  44 .BR find (1)
  45 utility and is used to list files and directories with specific attributes,
  46 both regular POSIX attributes such as ownership, timestamps, and size using
  47 the same options as
  48 .BR find (1),
  49 as well as Lustre-specific attributes such as stripe count and size,
  50 OST and MDT location, and composite layout attributes.
  51 .SH OPTIONS
  52 .TP
  53 .BR --atime | -A
  54 File was last accessed \fIn\fR*24 hours ago (if no units are given),
  55 or \fIn\fR*\fBs\fReconds, \fBm\fRinutes, \fBh\fRours, \fBd\fRays,
  56 \fBw\fReeks, or \fBy\fRears ago within a margin of error of 24h
  57 if no unit is specified.  Multiple units can be specified,
  58 for example \fB8h20m\fR is equivalent to \fB500m\fR.  If multiple units
  59 are specified, the margin of error is based on the smallest unit used, so
  60 .B -atime 3d
  61 has a margin of error of one day, while
  62 .B -atime 72h
  63 has a margin of error of one hour.
  64 .TP
  65 .BR --blocks | -b
  66 Blocks allocated by the file is \fIn\fR Kibibytes (if no units are given),
  67 \fIn\fR 512-byte \fBb\fRlocks, or \fBK\fRibi-, \fBM\fRebi-, \fBG\fRibi-,
  68 \fBT\fRebi-, \fBP\fRebi-, or \fBE\fRbi-bytes if that suffix is given.
  69 .TP
  70 .BR --btime | --Btime | -B
  71 File was created \fIn\fR*24 hours ago, see
  72 --atime
  73 for full details and options.
  74 .TP
  75 .BR --ctime | -C
  76 File's status was last changed \fIn\fR*24 hours ago, see
  77 --atime
  78 for full details and options.
  79 .TP
  80 .BR --component-count | --comp-count
  81 The file has \fIn\fR components in its layout.
  82 .TP
  83 .BR --component-end | --comp-end
  84 The file has component end offset \fIn\fR (in bytes) for any component.
  85 .TP
  86 .BR --component-flags | --comp-flags
  87 The file has components with the specified
  88 .I flag
  89 set.  If
  90 .BI ^ flag
  91 is used, print only components not matching
  92 .IR flag .
  93 Multiple flags can be specified, separated by commas.  Valid flag names are:
  94 .RS 1.2i
  95 .TP
  96 .B init
  97 Component has been initialized (has allocated OST objects).
  98 .TP
  99 .B stale
 100 Replicated (mirrored) components that do not have up-to-date data.  Stale
 101 components will not be used for read or write operations, and need to be
 102 resynched using
 103 .B lfs mirror resync
 104 before they can be accessed again.
 105 .TP
 106 .B prefer
 107 Replicated (mirrored) components that are preferred for read or write.
 108 For example, because they are located on SSD-based OSTs, or are more
 109 local on the network to clients.
 110 .RE
 111 .TP
 112 .BR --component-start | --comp-start
 113 The file has component start offset \fIn\fR (in bytes) for any component.
 114 .TP
 115 .BR --foreign
 116 File has a foreign (non-Lustre/free format) layout and is of the given
 117 .IR type ,
 118 if specified.  Presently only
 119 .B none
 120 or
 121 .B symlink
 122 are defined types, though 32-bit numeric types can also be used.
 123 .TP
 124 .BR --gid | -g
 125 File has specified numeric group ID.
 126 .TP
 127 .BR --group | -G
 128 File belongs to specified group, numeric group ID allowed.
 129 .TP
 130 .BR --help | -h
 131 Print usage message.
 132 .TP
 133 .BR --layout | -L
 134 File has a layout of the given type, one of:
 135 .RS 1.2i
 136 .TP
 137 .B raid0
 138 Traditional Lustre RAID-0 striping format.
 139 .TP
 140 .B released
 141 HSM-archived files that are not resident in the filesystem.
 142 .TP
 143 .B mdt
 144 Files that have the first data component on an MDT.
 145 .RE
 146 .TP
 147 .BR --lazy
 148 Use file size and blocks from MDT, if available, to avoid extra RPCs.
 149 .TP
 150 .BR --maxdepth
 151 Limits find to decend at most \fIn\fR levels of directory tree.
 152 .TP
 153 .BR --mdt | --mdt-index | -m
 154 File or directory inode is located on the specified MDT(s).
 155 .TP
 156 .BR --mdt-hash | -H
 157 DNE striped directory uses the given filename hashing function, one of:
 158 .RS 1.2i
 159 .TP
 160 .B crush
 161 The CRUSH consistent hash function, added in Lustre 2.14, minimizes
 162 entry migration if the directory stripe count changes during migration.
 163 .TP
 164 .B fnv_1a_64
 165 The Fowler\-Noll\-Vo hash function, which is a simple and efficient hash.
 166 .TP
 167 .B all_char
 168 Simple hash function that sums all of the characters in the filename.
 169 This is mostly for testing, or if it is known that filenames will use
 170 sequential filenames.
 171 .RE
 172 This implicitly selects only directories to be matched, like
 173 .B -type d
 174 and not other file types.
 175 .TP
 176 .BR --mdt-count | -T
 177 The DNE striped directory has the given number of MDT shards.  This
 178 implicitly selects only directories to be matched, like
 179 .B -type d
 180 and not other file types.
 181 .TP
 182 .BR --mirror-count | -N
 183 The file has \fIn\fR mirrors in its layout.
 184 .TP
 185 .BR --mirror-state
 186 The file has a state of
 187 .I state.
 188 If
 189 .BI ^ state
 190 is used, print only files not matching
 191 .IR state.
 192 Only one state can be specified. Valid state name is:
 193 .RS 1.2i
 194 .TP
 195 .B ro
 196 The mirrored file is in read-only state. All of the mirrors contain
 197 the up-to-date data.
 198 .TP
 199 .B wp
 200 The mirrored file is in a state of being written.
 201 .TP
 202 .B sp
 203 The mirrored file is in a state of being resynchronized.
 204 .RE
 205 .TP
 206 .BR --mtime | -M
 207 File's data was last modified \fIn\fR*24 hours ago, see
 208 --atime
 209 for full details and options.
 210 .TP
 211 .BR --name | -n
 212 Filename matches the given filename, or regular expression using
 213 standard
 214 .BR glob (7)
 215 file name regular expressions and wildcards.
 216 .TP
 217 .BR --newer [ XY "] " \fIreference
 218 Succeeds if timestamp \fIX\fR of the file being considered is newer
 219 than timestamp \fIY\fR of the file
 220 .IR reference .
 221 The letters \fIX\fR and \fIY\fR can be any of the following letters:
 222
 223 .TS
 224 ll
 225 ll
 226 ll
 227 ll
 228 llw(2i).
 229 a       The access time of the file \fIreference\fR
 230 b|B     The birth time of the file \fIreference\fR
 231 c       The inode status change time of \fIreference\fR
 232 m       The modification time of the file \fIreference\fR
 233 t       \fIreference\fR is interpreted directly as a time
 234 .TE
 235
 236 Some combinations are invalid; for example, it is invalid for
 237 .I X
 238 to be
 239 .IR t .
 240 Specifying
 241 .B -newer
 242 is equivalent to
 243 .BR -newermm .
 244 When
 245 .IR reference
 246 is interpreted directly as a time, currently it must be in one of the
 247 following formats: "%Y-%m-%d %H:%M:%S", "%Y-%m-%d %H:%M", "%Y-%m-%d",
 248 "%H:%M:%S", "%H:%M", to represent year, month, day, hour, minute, seconds,
 249 with unspecified times at the start of that minute or day, unspecified dates
 250 being "today", and "@%s" or "%s" the seconds since the Unix epoch (see
 251 .BR strftime (3)
 252 for details of the time formats).  Otherwise, it will report an error.
 253 If you try to use the birth time of a reference file, and the birth
 254 time cannot be determined, a fatal error message results.  If you
 255 specify a test which refers to the birth time of files being examined,
 256 this test will fail for any files where the birth time is unknown.
 257 .TP
 258 .BR --ost | -O
 259 File has an object on the specified OST(s).  The OST names can be specified
 260 using the whole OST target name, or just the OST index number. If multiple
 261 OSTs are given in a comma-separated list, the file may have an object on
 262 any of the given OSTs.  Specifying multiple OSTs allows scanning the
 263 filesystem only once when migrating objects off multiple OSTs for evacuation
 264 and replacement using
 265 .BR lfs-migrate (1).
 266 .TP
 267 .BR "--perm \fImode\fR"
 268 File's permission are exactly \fImode\fR (octal or symbolic).
 269 .TP
 270 .BR "--perm /\fImode\fR"
 271 All of the permission bits \fImode\fR are set for the file.
 272 .TP
 273 .BR "--perm -\fImode\fR"
 274 Any of the permission bits \fImode\fR are set for the file. If no permission
 275 bits in \fImode\fR are set, this test matches any file.
 276 .TP
 277 .BR --pool
 278 Layout was created with the specified
 279 .I pool
 280 name.  For composite files, this may match the pool of any component.
 281 .BR --print | -P
 282 Prints the file or directory name to standard output if it matches
 283 all specified parameters, one file per line with a trailing linefeed.
 284 This is the default behaviour for any matching files.
 285 .TP
 286 .BR --print0 | -0
 287 Print full file name to standard output if it matches the specified
 288 parameters, followed by a NUL character.  This is for use together with
 289 .BR xargs (1)
 290 with the
 291 .B -0
 292 option to handle filenames with embedded spaces or other special characters.
 293 .TP
 294 .BR --projid
 295 File has specified numeric project ID.
 296 .TP
 297 .BR --size | -s
 298 File size is \fIn\fR bytes, or \fBK\fRibi-, \fBM\fRebi-,
 299 \fBG\fRibi-, \fBT\fRebi-, \fBP\fRebi-, or \fBE\fRbi-bytes if a
 300 suffix is given.
 301 .TP
 302 .BR --stripe-count | -c
 303 File has \fIn\fR stripes allocated.  For composite files, this
 304 matches the stripe count of the last initialized component.
 305 .TP
 306 .BR --stripe-index | -i
 307 File has stripe on OST index \fIn\fR.  Multiple OST indices can be
 308 specified in a comma-separated list, which indicates that the file
 309 has a stripe on \fIany\fR of the specified OSTs.  This allows a
 310 single namespace scan for files on multiple different OSTs, if there
 311 are multiple OSTs that are being replaced.
 312 .TP
 313 .BR --stripe-size | -S
 314 Stripe size is \fIn\fR bytes, or \fBK\fRibi-, \fBM\fRebi-,
 315 \fBG\fRibi-, \fBT\fRebi-, \fBP\fRebi-, or \fBE\fRbi-abytes if a
 316 suffix is given.  For composite files, this matches the stripe
 317 size of the last initialized non-extension component.
 318 .TP
 319 .BR --extension-size | --ext-size | -z
 320 Extension size is \fIn\fR bytes, or \fBK\fRibi-, \fBM\fRebi-,
 321 \fBG\fRibi-, \fBT\fRebi-, \fBP\fRebi-, or \fBE\fRbi-abytes if a
 322 suffix is given.  For composite files, this matches the extension
 323 size of any extension component.
 324 .TP
 325 .BR --type | -t
 326 File has type: \fBb\fRlock, \fBc\fRharacter, \fBd\fRirectory,
 327 \fBf\fRile, \fBp\fRipe, sym\fBl\fRink, or \fBs\fRocket.
 328 .TP
 329 .BR --uid | -u
 330 File has specified numeric user ID.
 331 .TP
 332 .BR --user | -U
 333 File owned by specified user, numeric user ID also allowed.
 334 .SH NOTES
 335 Specifying \fB!\fR before an option negates its meaning (\fIfiles
 336 NOT matching the parameter\fR). Using \fB+\fR before a numeric
 337 value means 'more than \fIn\fR', while \fB-\fR before a numeric value
 338 means 'less than \fIn\fR'.  If neither is used, it means 'equal to
 339 \fIn\fR', within the bounds of the unit specified (if any).
 340 .PP
 341 Numeric suffixes are in binary SI (power-of-two) units.
 342 .PP
 343 For compatibility with
 344 .BR find (1)
 345 it is possible to specify long options with either a single or double
 346 leading dash.
 347 .PP
 348 The order of parameters does not affect how the files are matched.
 349 .B lfs find
 350 will first scan the directory for any specified filename, and then fetch
 351 MDT inode attributes for each matching filename.  If it can make a
 352 positive or negative decision for a file based only on the MDT attributes
 353 (e.g.  newer than specified time, user/group/project ID) it will not fetch
 354 the OST object attributes for that file.
 355 .SH EXAMPLES
 356 .TP
 357 .B $ lfs find /mnt/lustre
 358 Efficiently lists all files in a given directory and its subdirectories,
 359 without fetching any file attributes.
 360 .TP
 361 .B $ lfs find /mnt/lustre -mtime +30 -type f -print
 362 Recursively list all regular files in given directory more than 30 days old.
 363 .TP
 364 .B $ lfs find /mnt/lustre/test -o OST0002,OST0003 -print0 | lfs_migrate -y
 365 Recursively find all files in
 366 .B test
 367 that have objects on OST0002 or OST0003 and migrate them to other OSTs.  See
 368 .BR lfs_migrate (1)
 369 for more details.
 370 .TP
 371 .B $ lfs find -name "*.mpg" --component-count +3 /mnt/lustre
 372 Recursively list all files ending with
 373 .B .mpg
 374 that have more than 3 components.
 375 .TP
 376 .B $ lfs find --component-flags=init,prefer,^stale /mnt/lustre
 377 Recursively list all files that have at least one component with both 'init'
 378 and 'prefer' flags set, and doesn't have flag 'stale' set.
 379 .TP
 380 .B $ lfs find --mirror-count +2 /mnt/lustre
 381 Recursively list all mirrored files that have more than 2 mirrors.
 382 .TP
 383 .B $ lfs find ! --mirror-state=ro /mnt/lustre
 384 Recursively list all out-of-sync mirrored files.
 385 .TP
 386 .B $ lfs find ! --foreign=symlink /mnt/lustre
 387 Recursively list all but foreign files/dirs of
 388 .B symlink
 389 type.
 390 .SH BUGS
 391 The
 392 .B lfs find
 393 command isn't as comprehensive as
 394 .BR find (1).
 395 In particular, it doesn't support complex boolean expressions with
 396 .B -o
 397 (logical OR), only logical AND of all expressions.  The order that parameters
 398 are specified does not affect how the files are matched.
 399 .SH AUTHOR
 400 The
 401 .B lfs
 402 command is part of the Lustre filesystem.
 403 .SH SEE ALSO
 404 .BR lfs (1),
 405 .BR lfs-getstripe (1),
 406 .BR lfs-getdirstripe (1),
 407 .BR lfs-migrate (1),
 408 .BR lfs_migrate (1),
 409 .BR lustre (7),
 410 .BR xargs (1)