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--blocks\fR|\fB-b\fR [\fB+-\fR]\fIn\fR]
8 [[\fB!\fR] \fB--ctime\fR|\fB-C\fR [\fB+-\fR]\fIn[smhdwy]\fR]
9 [[\fB!\fR] \fB--component-count|\fB--comp-count\fR [\fB+-\fR]\fIn\fR]
10 [[\fB!\fR] \fB--component-end|\fB--comp-end\fR|\fB-E\fR [\fB+-\fR]\fIn\fR[\fBKMGTPE\fR]]
11 [[\fB!\fR] \fB--component-flags|\fB--comp-flags\fR <[^]\fIflag\fB,\fR...>]
12 [[\fB!\fR] \fB--component-start|\fB--comp-start\fR [\fB+-\fR]\fIn\fR[\fBKMGTPE\fR]]
13 [[\fB!\fR] \fB--extension-size|\fB-z\fR [\fB+-\fR]\fIn\fR[\fBKMG\fR]]
14 [[\fB!\fR] \fB--gid\fR|\fB-g\fR|\fB--group\fR|\fB-G\fR <\fIgname\fR>|<\fIgid\fR>]
15 [[\fB!\fR] \fB--layout\fR|\fB-L mdt\fR,\fBraid0\fR,\fBreleased\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!\fR] \fB--layout\fR|\fB-L mdt\fR,\fBraid0\fR,\fBreleased\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 <\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--ost\fR|\fB-O\fR <\fIindex\fR,...>]
29 [[\fB!\fR] \fB--pool\fR <\fIpool\fR>]
30 [\fB--print\fR|\fB-P\fR]
31 [\fB--print0\fR|\fB-0\fR]
32 [[\fB!\fR] \fB--projid\fR |<\fIprojid\fR>]
33 [[\fB!\fR] \fB--size|\fB-s\fR [\fB-+\fR]\fIn\fR[\fBKMGTPE\fR]]
34 [[\fB!\fR] \fB--stripe-count|\fB-c\fR [\fB+-\fR]\fIn\fR]
35 [[\fB!\fR] \fB--stripe-index|\fB-i\fR \fIn\fR,...]
36 [[\fB!\fR] \fB--stripe-size|\fB-S\fR [\fB+-\fR]\fIn\fR[\fBKMG\fR]]
37 [[\fB!\fR] \fB--type\fR|\fB-t\fR {\fBbcdflps\fR}]
38 [[\fB!\fR] \fB--uid\fR|\fB-u\fR|\fB--user\fR|\fB-U
39 <\fIuname\fR>|<\fIuid>\fR]
42 is similar to the standard
44 utility and is used to list files and directories with specific attributes,
45 both regular POSIX attributes such as ownership, timestamps, and size using
48 as well as Lustre-specific attributes such as stripe count and size,
49 OST and MDT location, and composite layout attributes.
53 File was last accessed \fIn\fR*24 hours ago (if no units are given),
54 or \fIn\fR*\fBs\fReconds, \fBm\fRinutes, \fBh\fRours, \fBd\fRays,
55 \fBw\fReeks, or \fBy\fRears ago within a margin of error of 24h,
56 or smaller if a unit is specified. Multiple units can be specified,
57 for example \fB8h20m\fR is equivalent to \fB500m\fR. If multipe units
58 are specified, the margin of error is based on the smallest unit used, so
60 has a margin of error of one day, while
62 has a margin of error of one hour.
65 Blocks allocated by the file is \fIn\fR Kibibytes (if no units are given),
66 \fIn\fR 512-byte \fBb\fRlocks, or \fBK\fRibi-, \fBM\fRebi-, \fBG\fRibi-,
67 \fBT\fRebi-, \fBP\fRebi-, or \fBE\fRbi-bytes if that suffix is given.
70 File's status was last changed \fIn\fR*24 hours ago, see
72 for full details and options.
74 .BR --component-count | --comp-count
75 The file has \fIn\fR components in its layout.
77 .BR --component-end | --comp-end
78 The file has component end offset \fIn\fR (in bytes) for any component.
80 .BR --component-flags | --comp-flags
81 The file has components with the specified
85 is used, print only components not matching
87 Multiple flags can be specified, separated by commas. Valid flag names are:
91 Component has been initialized (has allocated OST objects).
94 Replicated (mirrored) components that do not have up-to-date data. Stale
95 components will not be used for read or write operations, and need to be
98 before they can be accessed again.
101 Replicated (mirrored) components that are preferred for read or write.
102 For example, because they are located on SSD-based OSTs, or are more
103 local on the network to clients.
106 .BR --component-start | --comp-start
107 The file has component start offset \fIn\fR (in bytes) for any component.
110 File has a foreign (non-Lustre/free format) layout and is of the given
112 if specified. Presently only
116 are defined types, though 32-bit numeric types can also be used.
119 File has specified numeric group ID.
122 File belongs to specified group, numeric group ID allowed.
125 File has a layout of the given type, one of:
129 Traditional Lustre RAID-0 striping format.
132 HSM-archived files that are not resident in the filesystem.
135 Files that have the first data component on an MDT.
139 Use file size and blocks from MDT, if available, to avoid extra RPCs.
142 Limits find to decend at most \fIn\fR levels of directory tree.
144 .BR --mdt | --mdt-index | -m
145 File or directory inode is located on the specified MDT(s).
148 DNE striped directory uses the given filename hashing function, one of:
152 The Fowler\-Noll\-Vo hash function, which is a simple and efficient hash.
155 Simple hash function that sums all of the characters in the filename.
156 This is mostly for testing, or if it is known that filenames will use
157 sequential filenames.
161 The DNE striped directory has the given number of MDT shards.
163 .BR --mirror-count | -N
164 The file has \fIn\fR mirrors in its layout.
167 The file has a state of
171 is used, print only files not matching
173 Only one state can be specified. Valid state name is:
177 The mirrored file is in read-only state. All of the mirrors contain
181 The mirrored file is in a state of being written.
184 The mirrored file is in a state of being resynchronized.
188 File's data was last modified \fIn\fR*24 hours ago, see
190 for full details and options.
193 Filename matches the given filename, or regular expression using
196 file name regular expressions and wildcards.
199 File has an object on the specified OST(s). The OST names can be specified
200 using the whole OST target name, or just the OST index number. If multiple
201 OSTs are given in a comma-separated list, the file may have an object on
202 any of the given OSTs. Specifying multiple OSTs allows scanning the
203 filesystem only once when migrating objects off multiple OSTs for evacuation
204 and replacement using
208 Layout was created with the specified
210 name. For composite files, this may match the pool of any component.
212 Prints the file or directory name to standard output if it matches
213 all specified parameters, one file per line with a trailing linefeed.
214 This is the default behaviour for any matching files.
217 Print full file name to standard output if it matches the specified
218 parameters, followed by a NUL character. This is for use together with
222 option to handle filenames with embedded spaces or other special characters.
225 File has specified numeric project ID.
228 File size is \fIn\fR bytes, or \fBK\fRibi-, \fBM\fRebi-,
229 \fBG\fRibi-, \fBT\fRebi-, \fBP\fRebi-, or \fBE\fRbi-bytes if a
232 .BR --stripe-count | -c
233 File has \fIn\fR stripes allocated. For composite files, this
234 matches the stripe count of the last initialized component.
236 .BR --stripe-index | -i
237 File has stripe on OST index \fIn\fR. Multiple OST indices can be
238 specified in a comma-separated list, which indicates that the file
239 has a stripe on \fIany\fR of the specified OSTs. This allows a
240 single namespace scan for files on multiple different OSTs, if there
241 are multiple OSTs that are being replaced.
243 .BR --stripe-size | -S
244 Stripe size is \fIn\fR bytes, or \fBK\fRibi-, \fBM\fRebi-,
245 \fBG\fRibi-, \fBT\fRebi-, \fBP\fRebi-, or \fBE\fRbi-abytes if a
246 suffix is given. For composite files, this matches the stripe
247 size of the last initialized non-extension component.
249 .BR --extension-size | --ext-size | -z
250 Extension size is \fIn\fR bytes, or \fBK\fRibi-, \fBM\fRebi-,
251 \fBG\fRibi-, \fBT\fRebi-, \fBP\fRebi-, or \fBE\fRbi-abytes if a
252 suffix is given. For composite files, this matches the extension
253 size of any extension component.
256 File has type: \fBb\fRlock, \fBc\fRharacter, \fBd\fRirectory,
257 \fBf\fRile, \fBp\fRipe, sym\fBl\fRink, or \fBs\fRocket.
260 File has specified numeric user ID.
263 File owned by specified user, numeric user ID also allowed.
265 Specifying \fB!\fR before an option negates its meaning (\fIfiles
266 NOT matching the parameter\fR). Using \fB+\fR before a numeric
267 value means 'more than \fIn\fR', while \fB-\fR before a numeric value
268 means 'less than \fIn\fR'. If neither is used, it means 'equal to
269 \fIn\fR', within the bounds of the unit specified (if any).
271 Numeric suffixes are in binary SI (power-of-two) units.
273 For compatibility with
275 it is possible to specify long options with either a single or double
278 The order of parameters does not affect how the files are matched.
280 will first scan the directory for any specified filename, and then fetch
281 MDT inode attributes for each matching filename. If it can make a
282 positive or negative decision for a file based only on the MDT attributes
283 (e.g. newer than specified time, user/group/project ID) it will not fetch
284 the OST object attributes for that file.
287 .B $ lfs find /mnt/lustre
288 Efficiently lists all files in a given directory and its subdirectories,
289 without fetching any file attributes.
291 .B $ lfs find /mnt/lustre -mtime +30 -type f -print
292 Recursively list all regular files in given directory more than 30 days old.
294 .B $ lfs find /mnt/lustre/test -o OST0002,OST0003 -print0 | lfs_migrate -y
295 Recursively find all files in
297 that have objects on OST0002 or OST0003 and migrate them to other OSTs. See
301 .B $ lfs find -name "*.mpg" --component-count +3 /mnt/lustre
302 Recursively list all files ending with
304 that have more than 3 components.
306 .B $ lfs find --component-flags=init,prefer,^stale /mnt/lustre
307 Recursively list all files that have at least one component with both 'init'
308 and 'prefer' flags set, and doesn't have flag 'stale' set.
310 .B $ lfs find --mirror-count +2 /mnt/lustre
311 Recursively list all mirrored files that have more than 2 mirrors.
313 .B $ lfs find ! --mirror-state=ro /mnt/lustre
314 Recursively list all out-of-sync mirrored files.
316 .B $ lfs find ! --foreign=daos /mnt/lustre
317 Recursively list all but foreign files/dirs of
323 command isn't as comprehensive as
325 In particular, it doesn't support complex boolean expressions with
327 (logical OR), only logical AND of all expressions. The order that parameters
328 are specified does not affect how the files are matched.
332 command is part of the Lustre filesystem.
335 .BR lfs-getstripe (1),
336 .BR lfs-getdirstripe (1),