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