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