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