Whamcloud - gitweb
[fs/lustre-release.git] / lustre / doc / lfs-find.1
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--btime\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!\fR] \fB--layout\fR|\fB-L mdt\fR,\fBraid0\fR,\fBreleased\fR]
18 [\fB--lazy\fR]
19       [\fB--maxdepth\fR|\fB-D\fI n\fR]
20 [[\fB!\fR] \fB--mdt\fR|\fB--mdt-index\fR|\fB-m\fR <\fIuuid\fR|\fIindex\fR,...>]
21       [[\fB!\fR] \fB--mdt-count\fR|\fB-T\fR [\fB+-\fR]\fIn\fR]
22 [[\fB!\fR] \fB--mdt-hash\fR|\fB-H \fR<[^]\fIhashflag\fR,[^]\fIhashtype\fR,...>]
23       [[\fB!\fR] \fB--mirror-count|\fB-N\fR [\fB+-\fR]\fIn\fR]
24 [[\fB!\fR] \fB--mirror-state\fR <[^]\fIstate\fR>]
25       [[\fB!\fR] \fB--mtime\fR|\fB-M\fR [\fB-+\fR]\fIn[smhdwy]\fR]
26 [[\fB!\fR] \fB--name\fR|\fB-n <\fIpattern\fR>]
27       [[\fB!\fR] \fB--newer\fR[\fBXY\fR] <\fIreference\fR>]
28       [[\fB!\fR] \fB--ost\fR|\fB-O\fR <\fIindex\fR,...>]
29       [[\fB!\fR] \fB--perm\fR [\fB/-\fR]<\fImode\fR> ]
30 [[\fB!\fR] \fB--pool\fR <\fIpool\fR>]
31 [\fB--print\fR|\fB-P\fR]
32       [\fB--print0\fR|\fB-0\fR]
33 [[\fB!\fR] \fB--projid\fR |<\fIprojid\fR>]
34       [[\fB!\fR] \fB--size|\fB-s\fR [\fB-+\fR]\fIn\fR[\fBKMGTPE\fR]]
35 [[\fB!\fR] \fB--stripe-count|\fB-c\fR [\fB+-\fR]\fIn\fR]
36       [[\fB!\fR] \fB--stripe-index|\fB-i\fR \fIn\fR,...]
37 [[\fB!\fR] \fB--stripe-size|\fB-S\fR [\fB+-\fR]\fIn\fR[\fBKMG\fR]]
38       [[\fB!\fR] \fB--type\fR|\fB-t\fR {\fBbcdflps\fR}]
39 [[\fB!\fR] \fB--uid\fR|\fB-u\fR|\fB--user\fR|\fB-U
40 <\fIuname\fR>|<\fIuid>\fR]
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.
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 --layout | -L
131 File has a layout of the given type, one of:
132 .RS 1.2i
133 .TP
134 .B raid0
135 Traditional Lustre RAID-0 striping format.
136 .TP
137 .B released
138 HSM-archived files that are not resident in the filesystem.
139 .TP
140 .B mdt
141 Files that have the first data component on an MDT.
142 .RE
143 .TP
144 .BR --lazy
145 Use file size and blocks from MDT, if available, to avoid extra RPCs.
146 .TP
147 .BR --maxdepth
148 Limits find to decend at most \fIn\fR levels of directory tree.
149 .TP
150 .BR --mdt | --mdt-index | -m
151 File or directory inode is located on the specified MDT(s).
152 .TP
153 .BR --mdt-hash | -H
154 DNE striped directory uses the given filename hashing function, one of:
155 .RS 1.2i
156 .TP
157 .B crush
158 The CRUSH consistent hash function, added in Lustre 2.14, minimizes
159 entry migration if the directory stripe count changes during migration.
160 .TP
161 .B fnv_1a_64
162 The Fowler\-Noll\-Vo hash function, which is a simple and efficient hash.
163 .TP
164 .B all_char
165 Simple hash function that sums all of the characters in the filename.
166 This is mostly for testing, or if it is known that filenames will use
167 sequential filenames.
168 .RE
169 .TP
170 .BR --mdt-count | -T
171 The DNE striped directory has the given number of MDT shards.
172 .TP
173 .BR --mirror-count | -N
174 The file has \fIn\fR mirrors in its layout.
175 .TP
176 .BR --mirror-state
177 The file has a state of
178 .I state.
179 If
180 .BI ^ state
181 is used, print only files not matching
182 .IR state.
183 Only one state can be specified. Valid state name is:
184 .RS 1.2i
185 .TP
186 .B ro
187 The mirrored file is in read-only state. All of the mirrors contain
188 the up-to-date data.
189 .TP
190 .B wp
191 The mirrored file is in a state of being written.
192 .TP
193 .B sp
194 The mirrored file is in a state of being resynchronized.
195 .RE
196 .TP
197 .BR --mtime | -M
198 File's data was last modified \fIn\fR*24 hours ago, see
199 --atime
200 for full details and options.
201 .TP
202 .BR --name | -n
203 Filename matches the given filename, or regular expression using
204 standard
205 .BR glob (7)
206 file name regular expressions and wildcards.
207 .TP
208 .BR --newer [ XY "] " \fIreference
209 Succeeds if timestamp \fIX\fR of the file being considered is newer
210 than timestamp \fIY\fR of the file
211 .IR reference .
212 The letters \fIX\fR and \fIY\fR can be any of the following letters:
214 .TS
215 ll
216 ll
217 ll
218 ll
219 llw(2i).
220 a       The access time of the file \fIreference\fR
221 b|B     The birth time of the file \fIreference\fR
222 c       The inode status change time of \fIreference\fR
223 m       The modification time of the file \fIreference\fR
224 t       \fIreference\fR is interpreted directly as a time
225 .TE
227 Some combinations are invalid; for example, it is invalid for
228 .I X
229 to be
230 .IR t .
231 Specifying
232 .B -newer
233 is equivalent to
234 .BR -newermm .
235 When
236 .IR reference
237 is interpreted directly as a time, currently it must be in one of the
238 following formats: "%Y-%m-%d %H:%M:%S", "%Y-%m-%d %H:%M", "%Y-%m-%d",
239 "%H:%M:%S", "%H:%M", to represent year, month, day, hour, minute, seconds,
240 with unspecified times at the start of that minute or day, unspecified dates
241 being "today", and "@%s" or "%s" the seconds since the Unix epoch (see
242 .BR strftime (3)
243 for details of the time formats).  Otherwise, it will report an error.
244 If you try to use the birth time of a reference file, and the birth
245 time cannot be determined, a fatal error message results.  If you
246 specify a test which refers to the birth time of files being examined,
247 this test will fail for any files where the birth time is unknown.
248 .TP
249 .BR --ost | -O
250 File has an object on the specified OST(s).  The OST names can be specified
251 using the whole OST target name, or just the OST index number. If multiple
252 OSTs are given in a comma-separated list, the file may have an object on
253 any of the given OSTs.  Specifying multiple OSTs allows scanning the
254 filesystem only once when migrating objects off multiple OSTs for evacuation
255 and replacement using
256 .BR lfs-migrate (1).
257 .TP
258 .BR "--perm \fImode\fR"
259 File's permission are exactly \fImode\fR (octal or symbolic).
260 .TP
261 .BR "--perm /\fImode\fR"
262 All of the permission bits \fImode\fR are set for the file.
263 .TP
264 .BR "--perm -\fImode\fR"
265 Any of the permission bits \fImode\fR are set for the file. If no permission
266 bits in \fImode\fR are set, this test matches any file.
267 .TP
268 .BR --pool
269 Layout was created with the specified
270 .I pool
271 name.  For composite files, this may match the pool of any component.
272 .BR --print | -P
273 Prints the file or directory name to standard output if it matches
274 all specified parameters, one file per line with a trailing linefeed.
275 This is the default behaviour for any matching files.
276 .TP
277 .BR --print0 | -0
278 Print full file name to standard output if it matches the specified
279 parameters, followed by a NUL character.  This is for use together with
280 .BR xargs (1)
281 with the
282 .B -0
283 option to handle filenames with embedded spaces or other special characters.
284 .TP
285 .BR --projid
286 File has specified numeric project ID.
287 .TP
288 .BR --size | -s
289 File size is \fIn\fR bytes, or \fBK\fRibi-, \fBM\fRebi-,
290 \fBG\fRibi-, \fBT\fRebi-, \fBP\fRebi-, or \fBE\fRbi-bytes if a
291 suffix is given.
292 .TP
293 .BR --stripe-count | -c
294 File has \fIn\fR stripes allocated.  For composite files, this
295 matches the stripe count of the last initialized component.
296 .TP
297 .BR --stripe-index | -i
298 File has stripe on OST index \fIn\fR.  Multiple OST indices can be
299 specified in a comma-separated list, which indicates that the file
300 has a stripe on \fIany\fR of the specified OSTs.  This allows a
301 single namespace scan for files on multiple different OSTs, if there
302 are multiple OSTs that are being replaced.
303 .TP
304 .BR --stripe-size | -S
305 Stripe size is \fIn\fR bytes, or \fBK\fRibi-, \fBM\fRebi-,
306 \fBG\fRibi-, \fBT\fRebi-, \fBP\fRebi-, or \fBE\fRbi-abytes if a
307 suffix is given.  For composite files, this matches the stripe
308 size of the last initialized non-extension component.
309 .TP
310 .BR --extension-size | --ext-size | -z
311 Extension size is \fIn\fR bytes, or \fBK\fRibi-, \fBM\fRebi-,
312 \fBG\fRibi-, \fBT\fRebi-, \fBP\fRebi-, or \fBE\fRbi-abytes if a
313 suffix is given.  For composite files, this matches the extension
314 size of any extension component.
315 .TP
316 .BR --type | -t
317 File has type: \fBb\fRlock, \fBc\fRharacter, \fBd\fRirectory,
318 \fBf\fRile, \fBp\fRipe, sym\fBl\fRink, or \fBs\fRocket.
319 .TP
320 .BR --uid | -u
321 File has specified numeric user ID.
322 .TP
323 .BR --user | -U
324 File owned by specified user, numeric user ID also allowed.
326 Specifying \fB!\fR before an option negates its meaning (\fIfiles
327 NOT matching the parameter\fR). Using \fB+\fR before a numeric
328 value means 'more than \fIn\fR', while \fB-\fR before a numeric value
329 means 'less than \fIn\fR'.  If neither is used, it means 'equal to
330 \fIn\fR', within the bounds of the unit specified (if any).
331 .PP
332 Numeric suffixes are in binary SI (power-of-two) units.
333 .PP
334 For compatibility with
335 .BR find (1)
336 it is possible to specify long options with either a single or double
337 leading dash.
338 .PP
339 The order of parameters does not affect how the files are matched.
340 .B lfs find
341 will first scan the directory for any specified filename, and then fetch
342 MDT inode attributes for each matching filename.  If it can make a
343 positive or negative decision for a file based only on the MDT attributes
344 (e.g.  newer than specified time, user/group/project ID) it will not fetch
345 the OST object attributes for that file.
347 .TP
348 .B $ lfs find /mnt/lustre
349 Efficiently lists all files in a given directory and its subdirectories,
350 without fetching any file attributes.
351 .TP
352 .B $ lfs find /mnt/lustre -mtime +30 -type f -print
353 Recursively list all regular files in given directory more than 30 days old.
354 .TP
355 .B $ lfs find /mnt/lustre/test -o OST0002,OST0003 -print0 | lfs_migrate -y
356 Recursively find all files in
357 .B test
358 that have objects on OST0002 or OST0003 and migrate them to other OSTs.  See
359 .BR lfs_migrate (1)
360 for more details.
361 .TP
362 .B $ lfs find -name "*.mpg" --component-count +3 /mnt/lustre
363 Recursively list all files ending with
364 .B .mpg
365 that have more than 3 components.
366 .TP
367 .B $ lfs find --component-flags=init,prefer,^stale /mnt/lustre
368 Recursively list all files that have at least one component with both 'init'
369 and 'prefer' flags set, and doesn't have flag 'stale' set.
370 .TP
371 .B $ lfs find --mirror-count +2 /mnt/lustre
372 Recursively list all mirrored files that have more than 2 mirrors.
373 .TP
374 .B $ lfs find ! --mirror-state=ro /mnt/lustre
375 Recursively list all out-of-sync mirrored files.
376 .TP
377 .B $ lfs find ! --foreign=symlink /mnt/lustre
378 Recursively list all but foreign files/dirs of
379 .B symlink
380 type.
381 .SH BUGS
382 The
383 .B lfs find
384 command isn't as comprehensive as
385 .BR find (1).
386 In particular, it doesn't support complex boolean expressions with
387 .B -o
388 (logical OR), only logical AND of all expressions.  The order that parameters
389 are specified does not affect how the files are matched.
391 The
392 .B lfs
393 command is part of the Lustre filesystem.
395 .BR lfs (1),
396 .BR lfs-getstripe (1),
397 .BR lfs-getdirstripe (1),
398 .BR lfs-migrate (1),
399 .BR lfs_migrate (1),
400 .BR lustre (7),
401 .BR xargs (1)