Whamcloud - gitweb
LU-11367 som: integrate LSOM with lfs find
[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--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--gid\fR|\fB-g\fR|\fB--group\fR|\fB-G\fR <\fIgname\fR>|<\fIgid\fR>]
14       [[\fB!\fR] \fB--layout\fR|\fB-L mdt\fR,\fBraid0\fR,\fBreleased\fR]
15 [\fB--lazy\fR|\fB-z\fR]
16 [\fB--maxdepth\fR|\fB-D\fI n\fR]
17       [[\fB!\fR] \fB--mdt\fR|\fB--mdt-index\fR|\fB-m\fR <\fIuuid\fR|\fIindex\fR,...>]
18       [[\fB!\fR] \fB--mdt-count\fR|\fB-T\fR [\fB+-\fR]\fIn\fR]
19 [[\fB!\fR] \fB--mdt-hash\fR|\fB-H <\fIhashtype\fR>]
20       [[\fB!\fR] \fB--mirror-count|\fB-N\fR [\fB+-\fR]\fIn\fR]
21 [[\fB!\fR] \fB--mirror-state\fR <[^]\fIstate\fR>]
22       [[\fB!\fR] \fB--mtime\fR|\fB-M\fR [\fB-+\fR]\fIn[smhdwy]\fR]
23 [[\fB!\fR] \fB--name\fR|\fB-n <\fIpattern\fR>]
24       [[\fB!\fR] \fB--ost\fR|\fB-O\fR <\fIindex\fR,...>]
25 [[\fB!\fR] \fB--pool\fR <\fIpool\fR>]
26 [\fB--print\fR|\fB-P\fR]
27       [\fB--print0\fR|\fB-0\fR]
28 [[\fB!\fR] \fB--projid\fR |<\fIprojid\fR>]
29       [[\fB!\fR] \fB--size|\fB-s\fR [\fB-+\fR]\fIn\fR[\fBKMGTPE\fR]]
30 [[\fB!\fR] \fB--stripe-count|\fB-c\fR [\fB+-\fR]\fIn\fR]
31       [[\fB!\fR] \fB--stripe-index|\fB-i\fR \fIn\fR,...]
32 [[\fB!\fR] \fB--stripe-size|\fB-S\fR [\fB+-\fR]\fIn\fR[\fBKMG\fR]]
33       [[\fB!\fR] \fB--type\fR|\fB-t\fR {\fBbcdflps\fR}]
34 [[\fB!\fR] \fB--uid\fR|\fB-u\fR|\fB--user\fR|\fB-U
35 <\fIuname\fR>|<\fIuid>\fR]
37 .B lfs find
38 is similar to the standard
39 .BR find (1)
40 utility and is used to list files and directories with specific attributes,
41 both regular POSIX attributes such as ownership, timestamps, and size using
42 the same options as
43 .BR find (1),
44 as well as Lustre-specific attributes such as stripe count and size,
45 OST and MDT location, and composite layout attributes.
47 .TP
48 .BR --atime | -A
49 File was last accessed \fIn\fR*24 hours ago (if no units are given),
50 or \fIn\fR*\fBs\fReconds, \fBm\fRinutes, \fBh\fRours, \fBd\fRays,
51 \fBw\fReeks, or \fBy\fRears ago within a margin of error of 24h,
52 or smaller if a unit is specified.  Multiple units can be specified,
53 for example \fB8h20m\fR is equivalent to \fB500m\fR.  If multipe units
54 are specified, the margin of error is based on the smallest unit used, so
55 .B -atime 3d
56 has a margin of error of one day, while
57 .B -atime 72h
58 has a margin of error of one hour.
59 .TP
60 .BR --blocks | -b
61 Blocks allocated by the file is \fIn\fR Kibibytes (if no units are given),
62 \fIn\fR 512-byte \fBb\fRlocks, or \fBK\fRibi-, \fBM\fRebi-, \fBG\fRibi-,
63 \fBT\fRebi-, \fBP\fRebi-, or \fBE\fRbi-bytes if that suffix is given.
64 .TP
65 .BR --ctime | -C
66 File's status was last changed \fIn\fR*24 hours ago, see
67 --atime
68 for full details and options.
69 .TP
70 .BR --component-count | --comp-count
71 The file has \fIn\fR components in its layout.
72 .TP
73 .BR --component-end | --comp-end
74 The file has component end offset \fIn\fR (in bytes) for any component.
75 .TP
76 .BR --component-flags | --comp-flags
77 The file has components with the specified
78 .I flag
79 set.  If
80 .BI ^ flag
81 is used, print only components not matching
82 .IR flag .
83 Multiple flags can be specified, separated by commas.  Valid flag names are:
84 .RS 1.2i
85 .TP
86 .B init
87 Component has been initialized (has allocated OST objects).
88 .TP
89 .B stale
90 Replicated (mirrored) components that do not have up-to-date data.  Stale
91 components will not be used for read or write operations, and need to be
92 resynched using
93 .B lfs mirror resync
94 before they can be accessed again.
95 .TP
96 .B prefer
97 Replicated (mirrored) components that are preferred for read or write.
98 For example, because they are located on SSD-based OSTs, or are more
99 local on the network to clients.
100 .RE
101 .TP
102 .BR --component-start | --comp-start
103 The file has component start offset \fIn\fR (in bytes) for any component.
104 .TP
105 .BR --gid | -g
106 File has specified numeric group ID.
107 .TP
108 .BR --group | -G
109 File belongs to specified group, numeric group ID allowed.
110 .TP
111 .BR --layout
112 File has a layout of the given type, one of:
113 .RS 1.2i
114 .TP
115 .B raid0
116 Traditional Lustre RAID-0 striping format.
117 .TP
118 .B released
119 HSM-archived files that are not resident in the filesystem.
120 .TP
121 .B mdt
122 Files that have the first data component on an MDT.
123 .RE
124 .TP
125 .BR --lazy | -z
126 Use LSOM xattr as file size and blocks if LSOM is valid.
127 .TP
128 .BR --maxdepth
129 Limits find to decend at most \fIn\fR levels of directory tree.
130 .TP
131 .BR --mdt | --mdt-index | -m
132 File or directory inode is located on the specified MDT(s).
133 .TP
134 .BR --mdt-hash | -H
135 DNE striped directory uses the given filename hashing function, one of:
136 .RS 1.2i
137 .TP
138 .B fnv_1a_64
139 The Fowler\-Noll\-Vo hash function, which is a simple and efficient hash.
140 .TP
141 .B all_char
142 Simple hash function that sums all of the characters in the filename.
143 This is mostly for testing, or if it is known that filenames will use
144 sequential filenames.
145 .RE
146 .TP
147 .BR --mdt-count | -T
148 The DNE striped directory has the given number of MDT shards.
149 .TP
150 .BR --mirror-count | -N
151 The file has \fIn\fR mirrors in its layout.
152 .TP
153 .BR --mirror-state
154 The file has a state of
155 .I state.
156 If
157 .BI ^ state
158 is used, print only files not matching
159 .IR state.
160 Only one state can be specified. Valid state name is:
161 .RS 1.2i
162 .TP
163 .B ro
164 The mirrored file is in read-only state. All of the mirrors contain
165 the up-to-date data.
166 .TP
167 .B wp
168 The mirrored file is in a state of being written.
169 .TP
170 .B sp
171 The mirrored file is in a state of being resynchronized.
172 .RE
173 .TP
174 .BR --mtime | -M
175 File's data was last modified \fIn\fR*24 hours ago, see
176 --atime
177 for full details and options.
178 .TP
179 .BR --name | -n
180 Filename matches the given filename, or regular expression using
181 standard
182 .BR glob (7)
183 file name regular expressions and wildcards.
184 .TP
185 .BR --ost | -O
186 File has an object on the specified OST(s).  The OST names can be specified
187 using the whole OST target name, or just the OST index number. If multiple
188 OSTs are given in a comma-separated list, the file may have an object on
189 any of the given OSTs.  Specifying multiple OSTs allows scanning the
190 filesystem only once when migrating objects off multiple OSTs for evacuation
191 and replacement using
192 .BR lfs-migrate (1).
193 .TP
194 .BR --pool
195 Layout was created with the specified
196 .I pool
197 name.  For composite files, this may match the pool of any component.
198 .TP
199 .BR --print | -P
200 Prints the file or directory name to standard output if it matches
201 all specified parameters, one file per line with a trailing linefeed.
202 This is the default behaviour for any matching files.
203 .TP
204 .BR --print0 | -0
205 Print full file name to standard output if it matches the specified
206 parameters, followed by a NUL character.  This is for use together with
207 .BR xargs (1)
208 with the
209 .B -0
210 option to handle filenames with embedded spaces or other special characters.
211 .TP
212 .BR --projid
213 File has specified numeric project ID.
214 .TP
215 .BR --size | -s
216 File size is \fIn\fR bytes, or \fBK\fRibi-, \fBM\fRebi-,
217 \fBG\fRibi-, \fBT\fRebi-, \fBP\fRebi-, or \fBE\fRbi-bytes if a
218 suffix is given.
219 .TP
220 .BR --stripe-count | -c
221 File has \fIn\fR stripes allocated.  For composite files, this
222 matches the stripe count of the last initialized component.
223 .TP
224 .BR --stripe-index | -i
225 File has stripe on OST index \fIn\fR.  Multiple OST indices can be
226 specified in a comma-separated list, which indicates that the file
227 has a stripe on \fIany\fR of the specified OSTs.  This allows a
228 single namespace scan for files on multiple different OSTs, if there
229 are multiple OSTs that are being replaced.
230 .TP
231 .BR --stripe-size | -S
232 Stripe size is \fIn\fR bytes, or \fBK\fRibi-, \fBM\fRebi-,
233 \fBG\fRibi-, \fBT\fRebi-, \fBP\fRebi-, or \fBE\fRbi-abytes if a
234 suffix is given.  For composite files, this matches the stripe
235 size of the last initialized component.
236 .TP
237 .BR --type | -t
238 File has type: \fBb\fRlock, \fBc\fRharacter, \fBd\fRirectory,
239 \fBf\fRile, \fBp\fRipe, sym\fBl\fRink, or \fBs\fRocket.
240 .TP
241 .BR --uid | -u
242 File has specified numeric user ID.
243 .TP
244 .BR --user | -U
245 File owned by specified user, numeric user ID also allowed.
247 Specifying \fB!\fR before an option negates its meaning (\fIfiles
248 NOT matching the parameter\fR). Using \fB+\fR before a numeric
249 value means 'more than \fIn\fR', while \fB-\fR before a numeric value
250 means 'less than \fIn\fR'.  If neither is used, it means 'equal to
251 \fIn\fR', within the bounds of the unit specified (if any).
252 .PP
253 Numeric suffixes are in binary SI (power-of-two) units.
254 .PP
255 For compatibility with
256 .BR find (1)
257 it is possible to specify long options with either a single or double
258 leading dash.
259 .PP
260 The order of parameters does not affect how the files are matched.
261 .B lfs find
262 will first scan the directory for any specified filename, and then fetch
263 MDT inode attributes for each matching filename.  If it can make a
264 positive or negative decision for a file based only on the MDT attributes
265 (e.g.  newer than specified time, user/group/project ID) it will not fetch
266 the OST object attributes for that file.
268 .TP
269 .B $ lfs find /mnt/lustre
270 Efficiently lists all files in a given directory and its subdirectories,
271 without fetching any file attributes.
272 .TP
273 .B $ lfs find /mnt/lustre -mtime +30 -type f -print
274 Recursively list all regular files in given directory more than 30 days old.
275 .TP
276 .B $ lfs find /mnt/lustre/test -o OST0002,OST0003 -print0 | lfs_migrate -y
277 Recursively find all files in
278 .B test
279 that have objects on OST0002 or OST0003 and migrate them to other OSTs.  See
280 .BR lfs_migrate (1)
281 for more details.
282 .TP
283 .B $ lfs find -name "*.mpg" --component-count +3 /mnt/lustre
284 Recursively list all files ending with
285 .B .mpg
286 that have more than 3 components.
287 .TP
288 .B $ lfs find --component-flags=init,prefer,^stale /mnt/lustre
289 Recursively list all files that have at least one component with both 'init'
290 and 'prefer' flags set, and doesn't have flag 'stale' set.
291 .TP
292 .B $ lfs find --mirror-count +2 /mnt/lustre
293 Recursively list all mirrored files that have more than 2 mirrors.
294 .TP
295 .B $ lfs find ! --mirror-state=ro /mnt/lustre
296 Recursively list all out-of-sync mirrored files.
297 .SH BUGS
298 The
299 .B lfs find
300 command isn't as comprehensive as
301 .BR find (1).
302 In particular, it doesn't support complex boolean expressions with
303 .B -o
304 (logical OR), only logical AND of all expressions.  The order that parameters
305 are specified does not affect how the files are matched.
307 The
308 .B lfs
309 command is part of the Lustre filesystem.
311 .BR lfs (1),
312 .BR lfs-getstripe (1),
313 .BR lfs-getdirstripe (1),
314 .BR lfs-migrate (1),
315 .BR lfs_migrate (1),
316 .BR lustre (7)
317 .BR xargs (1)