lustre/doc/lfs-find.1

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