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