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