1 .TH lfs-find 1 "2018-01-24" Lustre "user utilities"
3 lfs-find \- Lustre client utility to list files with specific attributes
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--attrs\fR=\fI[^]ATTR[,...]\fR]
8 [[\fB!\fR] \fB--blocks\fR|\fB-b\fR [\fB+-\fR]\fIn\fR]
9 [[\fB!\fR] \fB--btime\fR|\fB-B\fR [\fB+-\fR]\fIn[smhdwy]\fR]
10 [[\fB!\fR] \fB--ctime\fR|\fB-C\fR [\fB+-\fR]\fIn[smhdwy]\fR]
11 [[\fB!\fR] \fB--component-count|\fB--comp-count\fR [\fB+-\fR]\fIn\fR]
12 [[\fB!\fR] \fB--component-end|\fB--comp-end\fR|\fB-E\fR [\fB+-\fR]\fIn\fR[\fBKMGTPE\fR]]
13 [[\fB!\fR] \fB--component-flags|\fB--comp-flags\fR [^]\fIFLAG\fB,\fR...]
14 [[\fB!\fR] \fB--component-start|\fB--comp-start\fR [\fB+-\fR]\fIn\fR[\fBKMGTPE\fR]]
15 [[\fB!\fR] \fB--extension-size|\fB-z\fR [\fB+-\fR]\fIn\fR[\fBKMG\fR]]
16 [[\fB!\fR] \fB--foreign\fR [\fITYPE\fR]]
17 [[\fB!\fR] \fB--gid\fR|\fB-g\fR|\fB--group\fR|\fB-G\fR \fIGNAME\fR|\fIGID\fR>]
18 [\fB--help\fR|\fB-h\fR]
19 [[\fB!\fR] \fB--layout\fR|\fB-L mdt\fR,\fBraid0\fR,\fBreleased\fR]
21 [[\fB!\fR] \fB--links\fR [\fB+-\fR]\fIn\fR] [\fB--maxdepth\fR|\fB-D\fI n\fR]
22 [[\fB!\fR] \fB--mdt\fR|\fB--mdt-index\fR|\fB-m\fR \fIUUID\fR|\fIINDEX\fR,...]
23 [[\fB!\fR] \fB--mdt-count\fR|\fB-T\fR [\fB+-\fR]\fIn\fR]
24 [[\fB!\fR] \fB--mdt-hash\fR|\fB-H \fR<[^]\fIHASHFLAG\fR,[^]\fIHASHTYPE\fR,...>]
25 [[\fB!\fR] \fB--mirror-count|\fB-N\fR [\fB+-\fR]\fIn\fR]
26 [[\fB!\fR] \fB--mirror-state\fR [^]\fISTATE\fR]
27 [[\fB!\fR] \fB--mtime\fR|\fB-M\fR [\fB-+\fR]\fIn[smhdwy]\fR]
28 [[\fB!\fR] \fB--name\fR|\fB-n \fIPATTERN\fR]
29 [[\fB!\fR] \fB--newer\fR[\fBXY\fR] \fIREFERENCE\fR]
30 [[\fB!\fR] \fB--ost\fR|\fB-O\fR \fIINDEX\fR,...]
31 [[\fB!\fR] \fB--perm\fR [\fB/-\fR]\fIMODE\fR ]
32 [[\fB!\fR] \fB--pool\fR \fIPOOL\fR]
33 [\fB--print\fR|\fB-P\fR]
34 [\fB--print0\fR|\fB-0\fR]
35 [\fB--printf\fR \fIFORMAT\fR]
36 [[\fB!\fR] \fB--projid\fR \fIPROJID\fR]
37 [[\fB!\fR] \fB--size|\fB-s\fR [\fB-+\fR]\fIn\fR[\fBKMGTPE\fR]]
38 [[\fB!\fR] \fB--stripe-count|\fB-c\fR [\fB+-\fR]\fIn\fR]
39 [[\fB!\fR] \fB--stripe-index|\fB-i\fR \fIn\fR,...]
40 [[\fB!\fR] \fB--stripe-size|\fB-S\fR [\fB+-\fR]\fIn\fR[\fBKMG\fR]]
41 [[\fB!\fR] \fB--type\fR|\fB-t\fR {\fBbcdflps\fR}]
42 [[\fB!\fR] \fB--uid\fR|\fB-u\fR|\fB--user\fR|\fB-U \fIUNAME\fR|\fIUID\fR]
45 is similar to the standard
47 utility and is used to list files and directories with specific attributes,
48 both regular POSIX attributes such as ownership, timestamps, and size using
51 as well as Lustre-specific attributes such as stripe count and size,
52 OST and MDT location, and composite layout attributes.
56 File was last accessed \fIn\fR*24 hours ago (if no units are given),
57 or \fIn\fR*\fBs\fReconds, \fBm\fRinutes, \fBh\fRours, \fBd\fRays,
58 \fBw\fReeks, or \fBy\fRears ago within a margin of error of 24h
59 if no unit is specified. Multiple units can be specified,
60 for example \fB8h20m\fR is equivalent to \fB500m\fR. If multiple units
61 are specified, the margin of error is based on the smallest unit used, so
63 has a margin of error of one day, while
65 has a margin of error of one hour.
68 File has ATTRS attribute flags. Supported attributes are (non exhaustive list):
69 Compressed (c), Immutable (i), Append_Only (a), No_Dump (d), Encrypted (E),
73 Blocks allocated by the file is \fIn\fR Kibibytes (if no units are given),
74 \fIn\fR 512-byte \fBb\fRlocks, or \fBK\fRibi-, \fBM\fRebi-, \fBG\fRibi-,
75 \fBT\fRebi-, \fBP\fRebi-, or \fBE\fRbi-bytes if that suffix is given.
77 .BR --btime | --Btime | -B
78 File was created \fIn\fR*24 hours ago, see
80 for full details and options.
83 File's status was last changed \fIn\fR*24 hours ago, see
85 for full details and options.
87 .BR --component-count | --comp-count
88 The file has \fIn\fR components in its layout.
90 .BR --component-end | --comp-end
91 The file has component end offset \fIn\fR (in bytes) for any component.
93 .BR --component-flags | --comp-flags
94 The file has components with the specified
98 is used, print only components not matching
100 Multiple flags can be specified, separated by commas. Valid flag names are:
104 Component has been initialized (has allocated OST objects).
107 Replicated (mirrored) components that do not have up-to-date data. Stale
108 components will not be used for read or write operations, and need to be
111 before they can be accessed again.
114 Replicated (mirrored) components that are preferred for read or write.
115 For example, because they are located on SSD-based OSTs, or are more
116 local on the network to clients.
119 Replicated (mirrored) components that are preferred for read.
122 Replicated (mirrored) components that are preferred for write.
125 .BR --component-start | --comp-start
126 The file has component start offset \fIn\fR (in bytes) for any component.
129 File has a foreign (non-Lustre/free format) layout and is of the given
131 if specified. Presently only
135 are defined types, though 32-bit numeric types can also be used.
138 File has specified numeric group ID.
141 File belongs to specified group, numeric group ID allowed.
147 File has a layout of the given type, one of:
151 Traditional Lustre RAID-0 striping format.
154 HSM-archived files that are not resident in the filesystem.
157 Files that have the first data component on an MDT.
161 Use file size and blocks from MDT, if available, to avoid extra RPCs.
164 File has \fIn\fR links.
167 Limits find to decend at most \fIn\fR levels of directory tree.
169 .BR --mdt | --mdt-index | -m
170 File or directory inode is located on the specified MDT(s).
173 DNE striped directory uses the given filename hashing function, one of:
177 The CRUSH consistent hash function, added in Lustre 2.14, minimizes
178 entry migration if the directory stripe count changes during migration.
181 The Fowler\-Noll\-Vo hash function, which is a simple and efficient hash.
184 Simple hash function that sums all of the characters in the filename.
185 This is mostly for testing, or if it is known that filenames will use
186 sequential filenames.
188 This implicitly selects only directories to be matched, like
190 and not other file types.
193 The DNE striped directory has the given number of MDT shards. This
194 implicitly selects only directories to be matched, like
196 and not other file types.
198 .BR --mirror-count | -N
199 The file has \fIn\fR mirrors in its layout.
202 The file has a state of
206 is used, print only files not matching
208 Only one state can be specified. Valid state name is:
212 The mirrored file is in read-only state. All of the mirrors contain
216 The mirrored file is in a state of being written.
219 The mirrored file is in a state of being resynchronized.
223 File's data was last modified \fIn\fR*24 hours ago, see
225 for full details and options.
228 Filename matches the given filename, or regular expression using
231 file name regular expressions and wildcards.
233 .BR --newer [ XY "] " \fIreference
234 Succeeds if timestamp \fIX\fR of the file being considered is newer
235 than timestamp \fIY\fR of the file
237 The letters \fIX\fR and \fIY\fR can be any of the following letters:
245 a The access time of the file \fIreference\fR
246 b|B The birth time of the file \fIreference\fR
247 c The inode status change time of \fIreference\fR
248 m The modification time of the file \fIreference\fR
249 t \fIreference\fR is interpreted directly as a time
252 Some combinations are invalid; for example, it is invalid for
262 is interpreted directly as a time, currently it must be in one of the
263 following formats: "%Y-%m-%d %H:%M:%S", "%Y-%m-%d %H:%M", "%Y-%m-%d",
264 "%H:%M:%S", "%H:%M", to represent year, month, day, hour, minute, seconds,
265 with unspecified times at the start of that minute or day, unspecified dates
266 being "today", and "@%s" or "%s" the seconds since the Unix epoch (see
268 for details of the time formats). Otherwise, it will report an error.
269 If you try to use the birth time of a reference file, and the birth
270 time cannot be determined, a fatal error message results. If you
271 specify a test which refers to the birth time of files being examined,
272 this test will fail for any files where the birth time is unknown.
275 File has an object on the specified OST(s). The OST names can be specified
276 using the whole OST target name, or just the OST index number. If multiple
277 OSTs are given in a comma-separated list, the file may have an object on
278 any of the given OSTs. Specifying multiple OSTs allows scanning the
279 filesystem only once when migrating objects off multiple OSTs for evacuation
280 and replacement using
283 .BR "--perm \fImode\fR"
284 File's permission are exactly \fImode\fR (octal or symbolic).
286 .BR "--perm /\fImode\fR"
287 All of the permission bits \fImode\fR are set for the file.
289 .BR "--perm -\fImode\fR"
290 Any of the permission bits \fImode\fR are set for the file. If no permission
291 bits in \fImode\fR are set, this test matches any file.
294 Layout was created with the specified
296 name. For composite files, this may match the pool of any component.
298 Prints the file or directory name to standard output if it matches
299 all specified parameters, one file per line with a trailing linefeed.
300 This is the default behaviour for any matching files.
303 Print full file name to standard output if it matches the specified
304 parameters, followed by a NUL character. This is for use together with
308 option to handle filenames with embedded spaces or other special characters.
310 .BR "--printf \fIformat\fR"
311 Print \fIformat\fR to standard output for each matching file, interpreting
312 `\' escapes and `%' directives. Unlike \fB--print\fR, the \fB--printf\fR option
313 does not automatically add a newline to the end of the string. The escapes and
327 A literal percent sign.
330 File\'s last access time in the format returned by the C \`ctime\' function.
333 File\'s last access time in seconds since Jan. 1, 1970, 00:00 GMT.
336 The amount of disk space used for the file (in 512-byte blocks).
339 File\'s last status change time in the format returned by the C \`ctime\' function.
342 File\'s last status change time in seconds since Jan. 1, 1970, 00:00 GMT.
345 File\'s numeric group ID.
348 File permission bits (in octal).
351 Number of hard links to file.
360 File\'s last modification time in the format returned by the C \`ctime\' function.
363 File\'s last modification time in seconds since Jan. 1, 1970, 00:00 GMT.
366 File's numeric user ID.
369 File\'s birth time in the format returned by the C \`ctime\' function.
372 File\'s birth time in seconds since Jan. 1, 1970, 00:00 GMT.
375 File's type (f=file, d=directory, p=pipe, b=block device, c=character device,
376 s=socket l=symbolic link)
378 Lustre-specific information about a file can be printed using these directives:
381 Comma-separated list of file's named attribute flags in short form (letter), or
382 hex value of any unknown attributes.
386 Comma-separated list of file's named attribute flags, or hex value of any
391 File\'s stripe count. For a composite file, this is the stripe count of the last
392 instantiated component.
395 File Identifier (FID) associated with the file.
398 Directory's hash type (or \`none\' for an unstriped directory).
401 File\'s starting OST index (or starting MDT index for a directory).
402 For a composite file, this is the starting OST index of the last instantiated
406 List of all OST/MDT indices associated with a file or directory.
409 File\'s OST pool name. For a composite file, this is the pool associated
410 with the last instantiated component. (NOTE: This can also be used for
411 directories, but since MDT pools are not currently implemented, nothing will
415 Numeric project ID assigned to the file or directory.
418 File's stripe size. For a composite file, this is the stripe size of the last
419 instantiated component.
422 File has specified numeric project ID.
425 File size is \fIn\fR bytes, or \fBK\fRibi-, \fBM\fRebi-,
426 \fBG\fRibi-, \fBT\fRebi-, \fBP\fRebi-, or \fBE\fRbi-bytes if a
429 .BR --stripe-count | -c
430 File has \fIn\fR stripes allocated. For composite files, this
431 matches the stripe count of the last initialized component.
433 .BR --stripe-index | -i
434 File has stripe on OST index \fIn\fR. Multiple OST indices can be
435 specified in a comma-separated list, which indicates that the file
436 has a stripe on \fIany\fR of the specified OSTs. This allows a
437 single namespace scan for files on multiple different OSTs, if there
438 are multiple OSTs that are being replaced.
440 .BR --stripe-size | -S
441 Stripe size is \fIn\fR bytes, or \fBK\fRibi-, \fBM\fRebi-,
442 \fBG\fRibi-, \fBT\fRebi-, \fBP\fRebi-, or \fBE\fRbi-abytes if a
443 suffix is given. For composite files, this matches the stripe
444 size of the last initialized non-extension component.
446 .BR --extension-size | --ext-size | -z
447 Extension size is \fIn\fR bytes, or \fBK\fRibi-, \fBM\fRebi-,
448 \fBG\fRibi-, \fBT\fRebi-, \fBP\fRebi-, or \fBE\fRbi-abytes if a
449 suffix is given. For composite files, this matches the extension
450 size of any extension component.
453 File has type: \fBb\fRlock, \fBc\fRharacter, \fBd\fRirectory,
454 \fBf\fRile, \fBp\fRipe, sym\fBl\fRink, or \fBs\fRocket.
457 File has specified numeric user ID.
460 File owned by specified user, numeric user ID also allowed.
462 Specifying \fB!\fR before an option negates its meaning (\fIfiles
463 NOT matching the parameter\fR). Using \fB+\fR before a numeric
464 value means 'more than \fIn\fR', while \fB-\fR before a numeric value
465 means 'less than \fIn\fR'. If neither is used, it means 'equal to
466 \fIn\fR', within the bounds of the unit specified (if any).
468 Numeric suffixes are in binary SI (power-of-two) units.
470 For compatibility with
472 it is possible to specify long options with either a single or double
475 The order of parameters does not affect how the files are matched.
477 will first scan the directory for any specified filename, and then fetch
478 MDT inode attributes for each matching filename. If it can make a
479 positive or negative decision for a file based only on the MDT attributes
480 (e.g. newer than specified time, user/group/project ID) it will not fetch
481 the OST object attributes for that file.
484 .B $ lfs find /mnt/lustre
485 Efficiently lists all files in a given directory and its subdirectories,
486 without fetching any file attributes.
488 .B $ lfs find /mnt/lustre -mtime +30 -type f -print
489 Recursively list all regular files in given directory more than 30 days old.
491 .B $ lfs find /mnt/lustre/test -o OST0002,OST0003 -print0 | lfs_migrate -y
492 Recursively find all files in
494 that have objects on OST0002 or OST0003 and migrate them to other OSTs. See
498 .B $ lfs find -name "*.mpg" --component-count +3 /mnt/lustre
499 Recursively list all files ending with
501 that have more than 3 components.
503 .B $ lfs find --component-flags=init,prefer,^stale /mnt/lustre
504 Recursively list all files that have at least one component with both 'init'
505 and 'prefer' flags set, and doesn't have flag 'stale' set.
507 .B $ lfs find --mirror-count +2 /mnt/lustre
508 Recursively list all mirrored files that have more than 2 mirrors.
510 .B $ lfs find ! --mirror-state=ro /mnt/lustre
511 Recursively list all out-of-sync mirrored files.
513 .B $ lfs find ! --foreign=symlink /mnt/lustre
514 Recursively list all but foreign files/dirs of
520 command isn't as comprehensive as
522 In particular, it doesn't support complex boolean expressions with
524 (logical OR), only logical AND of all expressions. The order that parameters
525 are specified does not affect how the files are matched.
529 command is part of the Lustre filesystem.
532 .BR lfs-getstripe (1),
533 .BR lfs-getdirstripe (1),