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