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