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