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