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