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-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--help\fR|\fB-h\fR]
  18 [[\fB!\fR] \fB--layout\fR|\fB-L mdt\fR,\fBraid0\fR,\fBreleased\fR]
  19 [\fB--lazy\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 \fR<[^]\fIHASHFLAG\fR,[^]\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--newer\fR[\fBXY\fR] \fIREFERENCE\fR]
  29       [[\fB!\fR] \fB--ost\fR|\fB-O\fR \fIINDEX\fR,...]
  30       [[\fB!\fR] \fB--perm\fR [\fB/-\fR]\fIMODE\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--printf\fR \fIFORMAT\fR]
  35 [[\fB!\fR] \fB--projid\fR \fIPROJID\fR]
  36       [[\fB!\fR] \fB--size|\fB-s\fR [\fB-+\fR]\fIn\fR[\fBKMGTPE\fR]]
  37 [[\fB!\fR] \fB--stripe-count|\fB-c\fR [\fB+-\fR]\fIn\fR]
  38       [[\fB!\fR] \fB--stripe-index|\fB-i\fR \fIn\fR,...]
  39 [[\fB!\fR] \fB--stripe-size|\fB-S\fR [\fB+-\fR]\fIn\fR[\fBKMG\fR]]
  40       [[\fB!\fR] \fB--type\fR|\fB-t\fR {\fBbcdflps\fR}]
  41 [[\fB!\fR] \fB--uid\fR|\fB-u\fR|\fB--user\fR|\fB-U  \fIUNAME\fR|\fIUID\fR]
  42 .SH DESCRIPTION
  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.
  52 .SH OPTIONS
  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 symlink
 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 --help | -h
 132 Print usage message.
 133 .TP
 134 .BR --layout | -L
 135 File has a layout of the given type, one of:
 136 .RS 1.2i
 137 .TP
 138 .B raid0
 139 Traditional Lustre RAID-0 striping format.
 140 .TP
 141 .B released
 142 HSM-archived files that are not resident in the filesystem.
 143 .TP
 144 .B mdt
 145 Files that have the first data component on an MDT.
 146 .RE
 147 .TP
 148 .BR --lazy
 149 Use file size and blocks from MDT, if available, to avoid extra RPCs.
 150 .TP
 151 .BR --maxdepth
 152 Limits find to decend at most \fIn\fR levels of directory tree.
 153 .TP
 154 .BR --mdt | --mdt-index | -m
 155 File or directory inode is located on the specified MDT(s).
 156 .TP
 157 .BR --mdt-hash | -H
 158 DNE striped directory uses the given filename hashing function, one of:
 159 .RS 1.2i
 160 .TP
 161 .B crush
 162 The CRUSH consistent hash function, added in Lustre 2.14, minimizes
 163 entry migration if the directory stripe count changes during migration.
 164 .TP
 165 .B fnv_1a_64
 166 The Fowler\-Noll\-Vo hash function, which is a simple and efficient hash.
 167 .TP
 168 .B all_char
 169 Simple hash function that sums all of the characters in the filename.
 170 This is mostly for testing, or if it is known that filenames will use
 171 sequential filenames.
 172 .RE
 173 This implicitly selects only directories to be matched, like
 174 .B -type d
 175 and not other file types.
 176 .TP
 177 .BR --mdt-count | -T
 178 The DNE striped directory has the given number of MDT shards.  This
 179 implicitly selects only directories to be matched, like
 180 .B -type d
 181 and not other file types.
 182 .TP
 183 .BR --mirror-count | -N
 184 The file has \fIn\fR mirrors in its layout.
 185 .TP
 186 .BR --mirror-state
 187 The file has a state of
 188 .I state.
 189 If
 190 .BI ^ state
 191 is used, print only files not matching
 192 .IR state.
 193 Only one state can be specified. Valid state name is:
 194 .RS 1.2i
 195 .TP
 196 .B ro
 197 The mirrored file is in read-only state. All of the mirrors contain
 198 the up-to-date data.
 199 .TP
 200 .B wp
 201 The mirrored file is in a state of being written.
 202 .TP
 203 .B sp
 204 The mirrored file is in a state of being resynchronized.
 205 .RE
 206 .TP
 207 .BR --mtime | -M
 208 File's data was last modified \fIn\fR*24 hours ago, see
 209 --atime
 210 for full details and options.
 211 .TP
 212 .BR --name | -n
 213 Filename matches the given filename, or regular expression using
 214 standard
 215 .BR glob (7)
 216 file name regular expressions and wildcards.
 217 .TP
 218 .BR --newer [ XY "] " \fIreference
 219 Succeeds if timestamp \fIX\fR of the file being considered is newer
 220 than timestamp \fIY\fR of the file
 221 .IR reference .
 222 The letters \fIX\fR and \fIY\fR can be any of the following letters:
 223
 224 .TS
 225 ll
 226 ll
 227 ll
 228 ll
 229 llw(2i).
 230 a       The access time of the file \fIreference\fR
 231 b|B     The birth time of the file \fIreference\fR
 232 c       The inode status change time of \fIreference\fR
 233 m       The modification time of the file \fIreference\fR
 234 t       \fIreference\fR is interpreted directly as a time
 235 .TE
 236
 237 Some combinations are invalid; for example, it is invalid for
 238 .I X
 239 to be
 240 .IR t .
 241 Specifying
 242 .B -newer
 243 is equivalent to
 244 .BR -newermm .
 245 When
 246 .IR reference
 247 is interpreted directly as a time, currently it must be in one of the
 248 following formats: "%Y-%m-%d %H:%M:%S", "%Y-%m-%d %H:%M", "%Y-%m-%d",
 249 "%H:%M:%S", "%H:%M", to represent year, month, day, hour, minute, seconds,
 250 with unspecified times at the start of that minute or day, unspecified dates
 251 being "today", and "@%s" or "%s" the seconds since the Unix epoch (see
 252 .BR strftime (3)
 253 for details of the time formats).  Otherwise, it will report an error.
 254 If you try to use the birth time of a reference file, and the birth
 255 time cannot be determined, a fatal error message results.  If you
 256 specify a test which refers to the birth time of files being examined,
 257 this test will fail for any files where the birth time is unknown.
 258 .TP
 259 .BR --ost | -O
 260 File has an object on the specified OST(s).  The OST names can be specified
 261 using the whole OST target name, or just the OST index number. If multiple
 262 OSTs are given in a comma-separated list, the file may have an object on
 263 any of the given OSTs.  Specifying multiple OSTs allows scanning the
 264 filesystem only once when migrating objects off multiple OSTs for evacuation
 265 and replacement using
 266 .BR lfs-migrate (1).
 267 .TP
 268 .BR "--perm \fImode\fR"
 269 File's permission are exactly \fImode\fR (octal or symbolic).
 270 .TP
 271 .BR "--perm /\fImode\fR"
 272 All of the permission bits \fImode\fR are set for the file.
 273 .TP
 274 .BR "--perm -\fImode\fR"
 275 Any of the permission bits \fImode\fR are set for the file. If no permission
 276 bits in \fImode\fR are set, this test matches any file.
 277 .TP
 278 .BR --pool
 279 Layout was created with the specified
 280 .I pool
 281 name.  For composite files, this may match the pool of any component.
 282 .BR --print | -P
 283 Prints the file or directory name to standard output if it matches
 284 all specified parameters, one file per line with a trailing linefeed.
 285 This is the default behaviour for any matching files.
 286 .TP
 287 .BR --print0 | -0
 288 Print full file name to standard output if it matches the specified
 289 parameters, followed by a NUL character.  This is for use together with
 290 .BR xargs (1)
 291 with the
 292 .B -0
 293 option to handle filenames with embedded spaces or other special characters.
 294 .TP
 295 .BR "--printf \fIformat\fR"
 296 Print \fIformat\fR to standard output for each matching file, interpreting
 297 `\' escapes and `%' directives.  Unlike \fB--print\fR, the \fB--printf\fR option
 298 does not automatically add a newline to the end of the string. The escapes and
 299 directives are:
 300 .RS 1.2i
 301 .TP
 302 .B \en
 303 Newline.
 304 .TP
 305 .B \et
 306 Horizontal tab.
 307 .TP
 308 .B \e\e
 309 A literal backslash.
 310 .TP
 311 .B %%
 312 A literal percent sign.
 313 .TP
 314 .B %a
 315 File\'s last access time in the format returned by the C \`ctime\' function.
 316 .TP
 317 .B %A@
 318 File\'s last access time in seconds since Jan. 1, 1970, 00:00 GMT.
 319 .TP
 320 .B %b
 321 The amount of disk space used for the file (in 512-byte blocks).
 322 .TP
 323 .B %c
 324 File\'s last status change time in the format returned by the C \`ctime\' function.
 325 .TP
 326 .B %C@
 327 File\'s last status change time in seconds since Jan. 1, 1970, 00:00 GMT.
 328 .TP
 329 .B %G
 330 File\'s numeric group ID.
 331 .TP
 332 .B %m
 333 File permission bits (in octal).
 334 .TP
 335 .B %p
 336 File's name.
 337 .TP
 338 .B %s
 339 File size in bytes.
 340 .TP
 341 .B %t
 342 File\'s last modification time in the format returned by the C \`ctime\' function.
 343 .TP
 344 .B %T@
 345 File\'s last modification time in seconds since Jan. 1, 1970, 00:00 GMT.
 346 .TP
 347 .B %U
 348 File's numeric user ID.
 349 .TP
 350 .B %w
 351 File\'s birth time in the format returned by the C \`ctime\' function.
 352 .TP
 353 .B %W@
 354 File\'s birth time in seconds since Jan. 1, 1970, 00:00 GMT.
 355 .TP
 356 .B %y
 357 File's type (f=file, d=directory, p=pipe, b=block device, c=character device,
 358 s=socket l=symbolic link)
 359 .TP
 360 Lustre-specific information about a file can be printed using these directives:
 361 .TP
 362 .B %Lc
 363 File\'s stripe count.  For a composite file, this is the stripe count of the last
 364 instantiated component.
 365 .TP
 366 .B %LF
 367 File Identifier (FID) associated with the file.
 368 .TP
 369 .B %Lh
 370 Directory's hash type (or \`none\' for an unstriped directory).
 371 .TP
 372 .B %Li
 373 File\'s starting OST index (or starting MDT index for a directory).
 374 For a composite file, this is the starting OST index of the last instantiated
 375 component.
 376 .TP
 377 .B %Lo
 378 List of all OST/MDT indices associated with a file or directory.
 379 .TP
 380 .B %Lp
 381 File\'s OST pool name.  For a composite file, this is the pool associated
 382 with the last instantiated component.  (NOTE: This can also be used for
 383 directories, but since MDT pools are not currently implemented, nothing will
 384 be printed.)
 385 .TP
 386 .B %LP
 387 Numeric project ID assigned to the file or directory.
 388 .TP
 389 .B %LS
 390 File's stripe size.  For a composite file, this is the stripe size of the last
 391 instantiated component.
 392 .RE
 393 .TP
 394 .BR --projid
 395 File has specified numeric project ID.
 396 .TP
 397 .BR --size | -s
 398 File size is \fIn\fR bytes, or \fBK\fRibi-, \fBM\fRebi-,
 399 \fBG\fRibi-, \fBT\fRebi-, \fBP\fRebi-, or \fBE\fRbi-bytes if a
 400 suffix is given.
 401 .TP
 402 .BR --stripe-count | -c
 403 File has \fIn\fR stripes allocated.  For composite files, this
 404 matches the stripe count of the last initialized component.
 405 .TP
 406 .BR --stripe-index | -i
 407 File has stripe on OST index \fIn\fR.  Multiple OST indices can be
 408 specified in a comma-separated list, which indicates that the file
 409 has a stripe on \fIany\fR of the specified OSTs.  This allows a
 410 single namespace scan for files on multiple different OSTs, if there
 411 are multiple OSTs that are being replaced.
 412 .TP
 413 .BR --stripe-size | -S
 414 Stripe size is \fIn\fR bytes, or \fBK\fRibi-, \fBM\fRebi-,
 415 \fBG\fRibi-, \fBT\fRebi-, \fBP\fRebi-, or \fBE\fRbi-abytes if a
 416 suffix is given.  For composite files, this matches the stripe
 417 size of the last initialized non-extension component.
 418 .TP
 419 .BR --extension-size | --ext-size | -z
 420 Extension size is \fIn\fR bytes, or \fBK\fRibi-, \fBM\fRebi-,
 421 \fBG\fRibi-, \fBT\fRebi-, \fBP\fRebi-, or \fBE\fRbi-abytes if a
 422 suffix is given.  For composite files, this matches the extension
 423 size of any extension component.
 424 .TP
 425 .BR --type | -t
 426 File has type: \fBb\fRlock, \fBc\fRharacter, \fBd\fRirectory,
 427 \fBf\fRile, \fBp\fRipe, sym\fBl\fRink, or \fBs\fRocket.
 428 .TP
 429 .BR --uid | -u
 430 File has specified numeric user ID.
 431 .TP
 432 .BR --user | -U
 433 File owned by specified user, numeric user ID also allowed.
 434 .SH NOTES
 435 Specifying \fB!\fR before an option negates its meaning (\fIfiles
 436 NOT matching the parameter\fR). Using \fB+\fR before a numeric
 437 value means 'more than \fIn\fR', while \fB-\fR before a numeric value
 438 means 'less than \fIn\fR'.  If neither is used, it means 'equal to
 439 \fIn\fR', within the bounds of the unit specified (if any).
 440 .PP
 441 Numeric suffixes are in binary SI (power-of-two) units.
 442 .PP
 443 For compatibility with
 444 .BR find (1)
 445 it is possible to specify long options with either a single or double
 446 leading dash.
 447 .PP
 448 The order of parameters does not affect how the files are matched.
 449 .B lfs find
 450 will first scan the directory for any specified filename, and then fetch
 451 MDT inode attributes for each matching filename.  If it can make a
 452 positive or negative decision for a file based only on the MDT attributes
 453 (e.g.  newer than specified time, user/group/project ID) it will not fetch
 454 the OST object attributes for that file.
 455 .SH EXAMPLES
 456 .TP
 457 .B $ lfs find /mnt/lustre
 458 Efficiently lists all files in a given directory and its subdirectories,
 459 without fetching any file attributes.
 460 .TP
 461 .B $ lfs find /mnt/lustre -mtime +30 -type f -print
 462 Recursively list all regular files in given directory more than 30 days old.
 463 .TP
 464 .B $ lfs find /mnt/lustre/test -o OST0002,OST0003 -print0 | lfs_migrate -y
 465 Recursively find all files in
 466 .B test
 467 that have objects on OST0002 or OST0003 and migrate them to other OSTs.  See
 468 .BR lfs_migrate (1)
 469 for more details.
 470 .TP
 471 .B $ lfs find -name "*.mpg" --component-count +3 /mnt/lustre
 472 Recursively list all files ending with
 473 .B .mpg
 474 that have more than 3 components.
 475 .TP
 476 .B $ lfs find --component-flags=init,prefer,^stale /mnt/lustre
 477 Recursively list all files that have at least one component with both 'init'
 478 and 'prefer' flags set, and doesn't have flag 'stale' set.
 479 .TP
 480 .B $ lfs find --mirror-count +2 /mnt/lustre
 481 Recursively list all mirrored files that have more than 2 mirrors.
 482 .TP
 483 .B $ lfs find ! --mirror-state=ro /mnt/lustre
 484 Recursively list all out-of-sync mirrored files.
 485 .TP
 486 .B $ lfs find ! --foreign=symlink /mnt/lustre
 487 Recursively list all but foreign files/dirs of
 488 .B symlink
 489 type.
 490 .SH BUGS
 491 The
 492 .B lfs find
 493 command isn't as comprehensive as
 494 .BR find (1).
 495 In particular, it doesn't support complex boolean expressions with
 496 .B -o
 497 (logical OR), only logical AND of all expressions.  The order that parameters
 498 are specified does not affect how the files are matched.
 499 .SH AUTHOR
 500 The
 501 .B lfs
 502 command is part of the Lustre filesystem.
 503 .SH SEE ALSO
 504 .BR lfs (1),
 505 .BR lfs-getstripe (1),
 506 .BR lfs-getdirstripe (1),
 507 .BR lfs-migrate (1),
 508 .BR lfs_migrate (1),
 509 .BR lustre (7),
 510 .BR xargs (1)