From: Andreas Dilger Date: Sat, 9 Dec 2017 11:26:54 +0000 (-0700) Subject: LU-9378 utils: split getstripe and find from lfs.1 X-Git-Tag: 2.10.58~12 X-Git-Url: https://git.whamcloud.com/?a=commitdiff_plain;h=refs%2Fchanges%2F64%2F30464%2F10;p=fs%2Flustre-release.git LU-9378 utils: split getstripe and find from lfs.1 Split the getstripe and find commands from the lfs.1 man page into their own lfs-getstripe.1 and lfs-find.1 man pages. While updating the lfs-find.1 man page I realized that the short options for "-print" and "-print0" were incorrectly documented in both the usage message as well as the man page, which implies that the short options were rarely, if ever, used. Fix the "--print" option to be correctly documented as "-P" instead of "-p", and deprecate the usage of "-p" for "--print0" in favour of "-0". This gives us the opportunity to reclaim "-p" for "--pool", which is already used as such for "lfs df", "lfs getstripe", and "lfs setstripe", after some period of printing a deprecation warning. Test-Parameters: trivial Signed-off-by: Andreas Dilger Change-Id: I9aa7a415d109d269c646fd034ea77785a94cab07 Reviewed-on: https://review.whamcloud.com/30464 Tested-by: Jenkins Tested-by: Maloo Reviewed-by: James Nunez Reviewed-by: Emoly Liu Reviewed-by: Oleg Drokin --- diff --git a/lustre/doc/Makefile.am b/lustre/doc/Makefile.am index 1d586c1..ffdba26 100644 --- a/lustre/doc/Makefile.am +++ b/lustre/doc/Makefile.am @@ -39,6 +39,8 @@ MANFILES = \ ldev.conf.5 \ lfs.1 \ lfs-df.1 \ + lfs-find.1 \ + lfs-getstripe.1 \ lfs-getdirstripe.1 \ lfs-hsm.1 \ lfs-ladvise.1 \ diff --git a/lustre/doc/lfs-find.1 b/lustre/doc/lfs-find.1 new file mode 100644 index 0000000..a65a860 --- /dev/null +++ b/lustre/doc/lfs-find.1 @@ -0,0 +1,261 @@ +.TH lfs-find 1 "2018-01-24" Lustre "user utilities" +.SH NAME +lfs-find \- Lustre client utility to list files with specific attributes +.SH SYNOPSIS +.B lfs find \fR<\fIdirectory\fR|\fIfilename \fR...> + [[\fB!\fR] \fB--atime\fR|\fB-A\fR [\fB-+\fR]\fIn\fR] +[[\fB!\fR] \fB--ctime\fR|\fB-C\fR [\fB+-\fR]\fIn\fR] + [[\fB!\fR] \fB--component-count|\fB--comp-count\fR [\fB+-\fR]\fIn\fR] + [[\fB!\fR] \fB--component-end|\fB--comp-end\fR|\fB-E\fR [\fB+-\fR]\fIn\fR[\fBKMGTPE\fR]] + [[\fB!\fR] \fB--component-flags|\fB--comp-flags\fR <[^]\fIflag\fB,\fR...>] + [[\fB!\fR] \fB--component-start|\fB--comp-start\fR [\fB+-\fR]\fIn\fR[\fBKMGTPE\fR]] + [[\fB!\fR] \fB--gid\fR|\fB-g\fR|\fB--group\fR|\fB-G\fR <\fIgname\fR>|<\fIgid\fR>] + [[\fB!\fR] \fB--layout\fR|\fB-L mdt\fR,\fBraid0\fR,\fBreleased\fR] +[\fB--maxdepth\fR|\fB-D\fI n\fR] + [[\fB!\fR] \fB--mdt\fR|\fB--mdt-index\fR|\fB-m\fR <\fIuuid\fR|\fIindex\fR,...>] + [[\fB!\fR] \fB--mdt-count\fR|\fB-T\fR [\fB+-\fR]\fIn\fR] +[[\fB!\fR] \fB--mdt-hash\fR|\fB-H <\fIhashtype\fR>] + [[\fB!\fR] \fB--mtime\fR|\fB-M\fR [\fB-+\fR]\fIn\fR] +[[\fB!\fR] \fB--name\fR|\fB-n <\fIpattern\fR>] + [[\fB!\fR] \fB--ost\fR|\fB-O\fR <\fIuuid\fR|\fIindex\fR,...>] +[[\fB!\fR] \fB--pool\fR <\fIpool\fR>] +[\fB--print\fR|\fB-P\fR] + [\fB--print0\fR|\fB-0\fR] +[[\fB!\fR] \fB--projid\fR |<\fIprojid\fR>] + [[\fB!\fR] \fB--size|\fB-s\fR [\fB-+\fR]\fIn\fR[\fBKMGTPE\fR]] +[[\fB!\fR] \fB--stripe-count|\fB-c\fR [\fB+-\fR]\fIn\fR] + [[\fB!\fR] \fB--stripe-index|\fB-i\fR \fIn\fR,...] +[[\fB!\fR] \fB--stripe-size|\fB-S\fR [\fB+-\fR]\fIn\fR[\fBKMG\fR]] + [[\fB!\fR] \fB--type\fR|\fB-t\fR {\fBbcdflps\fR}] +[[\fB!\fR] \fB--uid\fR|\fB-u\fR|\fB--user\fR|\fB-U +<\fIuname\fR>|<\fIuid>\fR] +.SH DESCRIPTION +.B lfs find +is similar to the standard +.BR find (1) +utility and is used to list files and directories with specific attributes, +both regular POSIX attributes such as ownership, timestamps, and size using +the same options as +.BR find (1), +as well as Lustre-specific attributes such as stripe count and size, +OST and MDT location, and composite layout attributes. +.SH OPTIONS +.TP +.BR --atime | -A +File was last accessed \fIn\fR*24 hours ago. +.TP +.BR --ctime | -C +File's status was last changed \fIn\fR*24 hours ago. +.TP +.BR --component-count | --comp-count +The file has \fIn\fR components in its layout. +.TP +.BR --component-end | --comp-end +The file has component end offset \fIn\fR (in bytes) for any component. +.TP +.BR --component-flags | --comp-flags +The file has components with the specified +.I flag +set. If +.BI ^ flag +is used, print only components not matching +.IR flag . +Multiple flags can be specified, separated by commas. Valid flag names are: +.RS 1.2i +.TP +.B init +Component has been initialized (has allocated OST objects). +.TP +.B stale +Replicated (mirrored) components that do not have up-to-date data. Stale +components will not be used for read or write operations, and need to be +resynched using +.B lfs mirror resync +before they can be accessed again. +.TP +.B prefer +Replicated (mirrored) components that are preferred for read or write. +For example, because they are located on SSD-based OSTs, or are more +local on the network to clients. +.TP +.BR --component-start | --comp-start +The file has component start offset \fIn\fR (in bytes) for any component. +.TP +.BR --gid | -g +File has specified numeric group ID. +.TP +.BR --group | -G +File belongs to specified group, numeric group ID allowed. +.TP +.BR --layout +File has a layout of the given type, one of: +.RS 1.2i +.TP +.B raid0 +Traditional Lustre RAID-0 striping format. +.TP +.B released +HSM-archived files that are not resident in the filesystem. +.TP +.B mdt +Files that have the first data component on an MDT. +.RE +.TP +.BR --maxdepth +Limits find to decend at most \fIn\fR levels of directory tree. +.TP +.BR --mdt | --mdt-index | -m +File or directory inode is located on the specified MDT(s). +.TP +.BR --mdt-hash | -H +DNE striped directory uses the given filename hashing function, one of: +.RS 1.2i +.TP +.B fnv_1a_64 +The Fowler\-Noll\-Vo hash function, which is a simple and efficient hash. +.TP +.B all_char +Simple hash function that sums all of the characters in the filename. +This is mostly for testing, or if it is known that filenames will use +sequential filenames. +.RE +.TP +.BR --mdt-count | -T +The DNE striped directory has the given number of MDT shards. +.TP +.BR --mtime | -M +File's data was last modified \fIn\fR*24 hours ago. +.TP +.BR --name | -n +Filename matches the given filename, or regular expression using +standard +.BR glob (7) +file name regular expressions and wildcards. +.TP +.BR --ost | -O +File has an object on the specified OST(s). The OST names can be specified +using the whole OST target name, or just the OST index number. If multiple +OSTs are given in a comma-separated list, the file may have an object on +any of the given OSTs. Specifying multiple OSTs allows scanning the +filesystem only once when migrating objects off the OSTs for evacuation +and replacement using +.BR lfs-migrate (1). +.TP +.BR --pool +Layout was created with the specified +.I pool +name. For composite files, this may match the pool of any component. +.TP +.BR --print | -P +Prints the file or directory name to standard output if it matches +all specified parameters, one file per line with a trailing linefeed. +This is the default behaviour for any matching files. +.TP +.BR --print0 | -0 +Print full file name to standard output if it matches the specified +parameters, followed by a NUL character. This is for use together with +.BR xargs (1) +with the +.B -0 +option to handle filenames with embedded spaces or other special characters. +.TP +.BR --projid +File has specified numeric project ID. +.TP +.BR --size | -s +File size is \fIn\fR bytes, or \fBK\fRibi-, \fBM\fRebi-, +\fBG\fRibi-, \fBT\fRebi-, \fBP\fRebi-, or \fBE\fRbi-bytes if a +suffix is given. +.TP +.BR --stripe-count | -c +File has \fIn\fR stripes allocated. For composite files, this +matches the stripe count of the last initialized component. +.TP +.BR --stripe-index | -i +File has stripe on OST index \fIn\fR. Multiple OST indices can be +specified in a comma-separated list, which indicates that the file +has a stripe on \fIany\fR of the specified OSTs. This allows a +single namespace scan for files on multiple different OSTs, if there +are multiple OSTs that are being replaced. +.TP +.BR --stripe-size | -S +Stripe size is \fIn\fR bytes, or \fBK\fRibi-, \fBM\fRebi-, +\fBG\fRibi-, \fBT\fRebi-, \fBP\fRebi-, or \fBE\fRbi-abytes if a +suffix is given. For composite files, this matches the stripe +size of the last initialized component. +.TP +.BR --type | -t +File has type: \fBb\fRlock, \fBc\fRharacter, \fBd\fRirectory, +\fBf\fRile, \fBp\fRipe, sym\fBl\fRink, or \fBs\fRocket. +.TP +.BR --uid | -u +File has specified numeric user ID. +.TP +.BR --user | -U +File owned by specified user, numeric user ID also allowed. +.SH NOTES +Specifying \fB!\fR before an option negates its meaning (\fIfiles +NOT matching the parameter\fR). Using \fB+\fR before a numeric +value means 'more than \fIn\fR', while \fB-\fR before a numeric value +means 'less than \fIn\fR'. If neither is used, it means 'equal to +\fIn\fR', within the bounds of the unit specified (if any). +.PP +Numeric suffixes are in binary SI (power-of-two) units. +.PP +For compatibility with +.BR find (1) +it is possible to specify long options with either a single or double +leading dash. +.PP +The order of parameters does not affect how the files are matched. +.B lfs find +will first scan the directory for any specified filename, and then fetch +MDT inode attributes for each matching filename. If it can make a +positive or negative decision for a file based only on the MDT attributes +(e.g. newer than specified time, user/group/project ID) it will not fetch +the OST object attributes for that file. +.SH EXAMPLES +.TP +.B $ lfs find /mnt/lustre +Efficiently lists all files in a given directory and its subdirectories, +without fetching any file attributes. +.TP +.B $ lfs find /mnt/lustre -mtime +30 -type f -print +Recursively list all regular files in given directory more than 30 days old. +.TP +.B $ lfs find /mnt/lustre/test -o OST0002,OST0003 -print0 | lfs_migrate -y +Recursively find all files in +.B test +that have objects on OST0002 or OST0003 and migrate them to other OSTs. See +.BR lfs_migrate (1) +for more details. +.TP +.B $ lfs find -name "*.mpg" --component-count +3 /mnt/lustre +Recursively list all files ending with +.B .mpg +that have more than 3 components. +.TP +.B $ lfs find --component-flags=init,prefer,^stale /mnt/lustre +Recursively list all files that have at least one component with both 'init' +and 'prefer' flags set, and doesn't have flag 'stale' set. +.SH BUGS +The +.B lfs find +command isn't as comprehensive as +.BR find (1). +In particular, it doesn't support complex boolean expressions with +.B -o +(logical OR), only logical AND of all expressions. The order that parameters +are specified does not affect how the files are matched. +.SH AUTHOR +The +.B lfs +command is part of the Lustre filesystem. +.SH SEE ALSO +.BR lfs (1), +.BR lfs-getstripe (1), +.BR lfs-getdirstripe (1), +.BR lfs-migrate (1), +.BR lfs_migrate (1), +.BR lustre (7) +.BR xargs (1) diff --git a/lustre/doc/lfs-getstripe.1 b/lustre/doc/lfs-getstripe.1 new file mode 100644 index 0000000..46d3e6b --- /dev/null +++ b/lustre/doc/lfs-getstripe.1 @@ -0,0 +1,223 @@ +.TH lfs-getstripe 1 "2018-01-24" Lustre "user utilities" +.SH NAME +lfs getstripe \- Lustre client command to print layout parameters of a file +.SH SYNOPSIS +.B lfs getstripe +[\fB--component-count\fR|\fB--comp-count\fR] + [\fB--component-end\fR|\fB--comp-end\fR|\fB-E\fR[\fB=\fR[\fB+-\fR]\fIend\fR[\fBKMGTPE\fR]] + [\fB--component-flags\fR|\fB--comp-flags\fR[\fB=\fIflags\fR]] + [\fB--component-id\fR|\fB--comp-id\fR[=\fIid\fR]|\fB-I\fR[\fIid\fR]] + [\fB--component-start\fR[\fB=\fR[\fB+-\fR]\fIstart\fR[\fBKMGTPE\fR]]] + [\fB--directory\fR|\fB-d\fR] +[\fB--fid\fR|\fB-F\fR] +[\fB--generation\fR|\fB-g\fR] + [\fB--layout\fR|\fB-L\fR] +[\fB--mdt\fR|\fB--mdt-index\fR|\fB-m\fR] +[\fB--ost\fR|\fB-O\fR <\fIuuid\fR>] + [\fB--pool\fR|\fB-p\fR] +[\fB--quiet\fR|\fB-q\fR] +[\fB--recursive\fR|\fB-r\fR] + [\fB--raw\fR|\fB-R\fR] +[\fB--stripe-count\fR|\fB-c\fR] +[\fB--stripe-index\fR|\fB-i\fR] + [\fB--stripe-size\fR|\fB-S\fR] +[\fB--verbose\fR|\fB-v\fR] +[\fB--yaml\fR|\fB-y\fR] + <\fIdirname\fR|\fIfilename\fR> ... +.SH DESCRIPTION +.B lfs getstripe +is used to list the layout/striping information for a given filename or +directory tree. By default the stripe_count, stripe_size, stripe_offset, +and allocated OST objects for each file will be shown. If you only want +specific layout information to be printed, then the +.BR --stripe-count , +.BR --stripe-size , +.BR --stripe-index , +.BR --layout , +.BR --fid , +.BR --generation , +.BR --component-id , +.BR --component-flags , +.BR --component-count , +.BR --component-start , +.BR --component-end , +or +.BR --pool +options, or equivalent single-character options, can be used without an +argument to return only the specified field(s). +.PP +You can limit the displayed content to one or more specific components of +a composite file layout by specifying the matching parameter(s) for the +.BR --component-id , +.BR --component-flags , +.BR --component-start , +and +.BR --component-end , +or their single-character options. For single-character options, the +argument must follow the option without a space, and for long options an +.RB ' = ' +sign must be used. +.br +The default behavior when a directory is specified is to list the striping +information for all files within the specified directory (like +.RB ' "ls -l" '). +.SH OPTIONS +.TP +.BR --component-count | --comp-count +Print only the number of components in the file's layout. +.TP +.BR --component-end | --comp-end [ = [ +- ] \fIend [ KMGTPE ]]| -E [[ +- ] \fIend [ KMGTPE ]] +Print only the component end offset (in bytes) for the component(s). +If the component +.I end +offset is specified (with optional suffix for SI units), print only the +attributes of the component(s) with the given end offset. If +.BI + end +or +.BI - end +is used, print components with respectively a larger or smaller +.I end +offset. +.TP +.BR --component-flags | --comp-flags [ = [ ^ ] \fIflag ,...]] +Print only the component flags. If +.I flag +is specified, print only components matching the specified +.I flag +set. If +.BI ^ flag +is used, print only components not matching +.IR flag . +Multiple flags may be specified, separated by commas. Valid flag names are: +.RS 1.2i +.TP +.B init +Component has been initialized (has allocated OST objects). +.TP +.B stale +Replicated (mirrored) components that do not have up-to-date data. Stale +components will not be used for read or write operations, and need to be +resynched using +.B lfs mirror resync +before they can be accessed again. +.TP +.B prefer +Replicated (mirrored) components that are preferred for read or write. +For example, because they are located on SSD-based OSTs, or are more +local on the network to clients. +.RE +.TP +.BR --component-id | --comp-id [ =\fIid ]| -I [ \fIid ] +Print only the component ID number for the component(s). The file-unique +component ID is assigned as each component is created, and is not re-used. +The ID is +.B not +necessarily related to the offset of the component within the file, in +particular since replicated file layouts may have overlapping extents. +If +.I id +is specified, then print only the fields for the matching component. +.TP +.BR --component-start | --comp-start [ = [ +- ] \fIstart [ KMGTPE ]] +Print only the component start offset (in bytes) for the component(s). +If the component +.I start +offset is specified (with optional suffix for SI units), print only the +attributes of the component(s) with the given starting offset. If +.BI + start +or +.BI - start +is used, print components with respectively a larger or smaller +.I start +offset. +.TP +.BR --directory | -d +Get striping information for only the specified directory, like +.RB ' "ls -d" '. +.TP +.BR --fid | -F +Show only the 128-bit unique Lustre File Identifier (FID). +.TP +.B --generation | -g +Print only the layout generation number. +.TP +.BR --layout +Show only the file layout, which is one of: +.RS 1.2i +.TP +.B raid0 +Traditional Lustre RAID-0 striping format. +.TP +.B released +HSM-archived files that are not resident in the filesystem. +.TP +.B mdt +Files that have the first data component on an MDT. +.RE +.TP +.BR --mdt | --mdt-index | -m +Show the MDT index on which the file or directory inode is located. +.TP +.BR --ost | -O +Print the starting OST index for the file layout. +.TP +.BR --pool | -p +Print only the OST pool name on which the file was created. +.TP +.BR --quiet | -q +Print only allocated objects for each file, not other layout parameters. +.TP +.BR --raw | -R +Print layout information without substituting the filesystem's default values +for unspecified fields. If the file layout is not set, 0, 0, and -1 will be +printed for the stripe_count, stripe_size, and stripe_offset respectively. +.TP +.BR --recursive | -r +Recurse into all subdirectories. +.TP +.BR --stripe-count | -c +Print the number of stripes in the file. For composite files this is +the stripe count of the last initialized component. +.TP +.BR --stripe-index | -i +Print the starting OST index for the file layout. +.TP +.BR --stripe-size | -S +Print the stripe size in bytes. For composite files this is the stripe +size of the last initialized component. +.TP +.BR --verbose | -v +Also print the layout magic, FID sequence, FID object ID, and FID, in +addition to the normally-printed attributes. +.TP +.BR --yaml | -y +Always print the layout in YAML format, rather than only using this +format for composite files. +.br +.SH EXAMPLES +.TP +.B $ lfs getstripe -v /mnt/lustre/file1 +List the detailed object allocation of the given file. +.TP +.B $ lfs getstripe -v -I2 /mnt/lustre/file1 +List the detailed information of only component with ID 2 of the given file. +.TP +.B $ lfs getstripe --component-flags=^init -I /mnt/lustre/file1 +Print only the component IDs for all the uninitialized components. +.TP +.B $ lfs getstripe --component-flags=init,^stale -I /mnt/lustre/file1 +Print only the component(s) that are instantiated but not stale +.TP +.B $ lfs getstripe -E-64M /mnt/lustre/file1 +List information of components in a file with extent end less than 64MiB. +.TP +.B $ lfs getstripe -I3 --component-start /mnt/lustre/file1 +Print only the component start for the component with ID of 3 +.SH AUTHOR +The lfs command is part of the Lustre filesystem. +.SH SEE ALSO +.BR lfs (1), +.BR lfs-find (1), +.BR lfs-getdirstripe (1), +.BR lfs-setstripe (1), +.BR lustre (7) diff --git a/lustre/doc/lfs.1 b/lustre/doc/lfs.1 index 469b4ae..2c72790 100644 --- a/lustre/doc/lfs.1 +++ b/lustre/doc/lfs.1 @@ -1,10 +1,8 @@ -.TH lfs 1 "2017 Jan 12" Lustre "user utilities" +.TH lfs 1 "2018-01-24" Lustre "user utilities" .SH NAME -lfs \- Lustre utility to create a file with specific striping pattern, find the striping pattern of existing files, do certain quota operations, and manage distributed namespace options for directories +lfs \- client utility for Lustre-specific file layout and other attributes .SH SYNOPSIS .br -.B lfs -.br .B lfs changelog [--follow] [startrec [endrec]] .br .B lfs changelog_clear @@ -17,59 +15,80 @@ lfs \- Lustre utility to create a file with specific striping pattern, find the .br .B lfs fid2path [--link ] ... .br -.B lfs find - \fB[[!] --atime|-A [-+]N] [[!] --mtime|-M [-+]N] [[!] --ctime|-C [+-]N] - \fB[--maxdepth|-D N] [[!] --mdt|-m ] [--name|-n pattern] - \fB[[!] --ost|-O ] [--print|-p] [--print0|-P] - \fB[[!] --size|-s [-+]N[kMGTPE]] - \fB[[!] --stripe-count|-c [+-]] - \fB[[!] --stripe-index|-i ] - \fB[[!] --stripe-size|-S [+-]N[kMG]] - \fB[[!] --layout|-L raid0,released] - \fB[[!] --component-count [+-]comp_cnt] - \fB[[!] --component-start [+-]N[kMGTPE]] - \fB[[!] --component-end|-E [+-]N[kMGTPE]] - \fB[[!] --component-flags ] - \fB[--type |-t {bcdflpsD}] [[!] --gid|-g|--group|-G |] - \fB[[!] --uid|-u|--user|-U|--projid ||] [[!] --pool ]\fR +.B lfs find \fR<\fIdirectory\fR|\fIfilename \fR...> + [[\fB!\fR] \fB--atime\fR|\fB-A\fR [\fB-+\fR]\fIn\fR] +[[\fB!\fR] \fB--ctime\fR|\fB-C\fR [\fB+-\fR]\fIn\fR] + [[\fB!\fR] \fB--mtime\fR|\fB-M\fR [\fB-+\fR]\fIn\fR] + [[\fB!\fR] \fB--component-count|\fB--comp-count\fR [\fB+-\fR]\fIn\fR] + [[\fB!\fR] \fB--component-flags|\fB--comp-flags\fR <[\fB^\fR]\fIflag\fB,\fR...>] + [[\fB!\fR] \fB--component-end|\fB--comp-end\fR|\fB-E\fR [\fB+-\fR]\fIn\fR[\fBKMGTPE\fR]] + [[\fB!\fR] \fB--component-start|\fB--comp-start\fR [\fB+-\fR]\fIn\fR[\fBKMGTPE\fR]] + [[\fB!\fR] \fB--gid\fR|\fB-g\fR|\fB--group\fR|\fB-G\fR <\fIgname\fR>|<\fIgid\fR>] + [[\fB!\fR] \fB--layout\fR|\fB-L mdt\fR,\fBraid0\fR,\fBreleased\fR] +[\fB--maxdepth\fR|\fB-D\fI n\fR] + [[\fB!\fR] \fB--mdt\fR|\fB--mdt-index\fR|\fB-m\fR <\fIuuid\fR|\fIindex\fR,...>] + [[\fB!\fR] \fB--mdt-count\fR|\fB-T\fR [\fB+-\fR]\fIn\fR] +[[\fB!\fR] \fB--mdt-hash\fR|\fB-H \fI\fR] + [[\fB!\fR] \fB--name\fR|\fB-n \fI\fR] +[[\fB!\fR] \fB--ost\fR|\fB-O\fR <\fIuuid\fR|\fIindex\fR,...>] + [[\fB!\fR] \fB--pool\fR <\fIpool\fR>] +[\fB--print\fR|\fB-P\fR] [\fB--print0\fR|\fB-0\fR] + [[\fB!\fR] \fB--projid\fR |<\fIprojid\fR>] +[[\fB!\fR] \fB--size|\fB-s\fR [\fB-+\fR]\fIn\fR[\fBKMGTPE\fR]] + [[\fB!\fR] \fB--stripe-count|\fB-c\fR [\fB+-\fR]\fIn\fR] + [[\fB!\fR] \fB--stripe-index|\fB-i\fR \fIn\fR,...] + [[\fB!\fR] \fB--stripe-size|\fB-S\fR [\fB+-\fR]\fIn\fR[\fBKMG\fR]] +[[\fB!\fR] \fB--type\fR|\fB-t\fR {\fBbcdflps\fR}] + [[\fB!\fR] \fB--uid\fR|\fB-u\fR|\fB--user\fR|\fB-U +<\fIuname\fR>|<\fIuid>\fR] .br .B lfs getname [-h]|[path ...] .br -.B lfs getstripe [\fB--obd\fR|\fB-O\fR <\fIuuid\fR>] [\fB--quiet\fR|\fB-q\fR] - [\fB--verbose\fR|\fB-v\fR] [\fB--stripe-count\fR|\fB-c\fR] - [\fB--stripe-index\fR|\fB-i\fR] [\fB--mdt-index\fR|\fB-m\fR] - [\fB--fid\fR|\fB-F\fR] [\fB--stripe-size\fR|\fB-S\fR] - [\fB--directory\fR|\fB-d\fR] [\fB--layout\fR|\fB-L\fR] - [\fB--generation\fR|\fB-g\fR] - [\fB--component-id\fR[=\fIcomp_id\fR]|\fB-I\fR[\fIcomp_id\fR]] - [\fB--component-flags\fR[=\fIcomp_flags\fR]] [\fB--component-count\fR] - [\fB--component-start\fR[=[+-]\fIN\fR[kMGTPE]]] - [\fB--component-end\fR[=[+-]\fIN\fR[kMGTPE]]|\fB-E\fR[[+-]\fIN\fR[kMGTPE]]] - [\fB--pool\fR|\fB-p\fR] [\fB--recursive\fR|\fB-r\fR] [\fB--raw\fR|\fB-R\fR] +.B lfs getstripe +[\fB--component-count\fR|\fB--comp-count\fR] + [\fB--component-end\fR[=[\fB+-\fR]\fIN\fR[kMGTPE]]|\fB-E\fR[[+-]\fIN\fR[kMGTPE]]] + [\fB--component-flags\fR[=[\fB^\fR]\fIflag\fB,\fR...]] + [\fB--component-id\fR[=\fIcomp_id\fR]|\fB-I\fR[<\fIcomp_id\fR>]] + [\fB--component-start\fR[=[\fB+-\fR]\fIN\fR[kMGTPE]]] + [\fB--directory\fR|\fB-d\fR] +[\fB--fid\fR|\fB-F\fR] +[\fB--generation\fR|\fB-g\fR] + [\fB--layout\fR|\fB-L\fR] +[\fB--mdt\fR|\fB--mdt-index\fR|\fB-m\fR] +[\fB--ost\fR|\fB-O\fR <\fIuuid\fR>] + [\fB--pool\fR|\fB-p\fR] +[\fB--quiet\fR|\fB-q\fR] +[\fB--recursive\fR|\fB-r\fR] + [\fB--raw\fR|\fB-R\fR] +[\fB--stripe-count\fR|\fB-c\fR] +[\fB--stripe-index\fR|\fB-i\fR] + [\fB--stripe-size\fR|\fB-S\fR] +[\fB--verbose\fR|\fB-v\fR] +[\fB--yaml\fR|\fB-y\fR] <\fIdirname\fR|\fIfilename\fR> ... .br -.B lfs migrate \fB-m \fR +.B lfs migrate { --mdt-index | -m } \fI\fR .IR directory .br .B lfs migrate [\fB-c | --stripe-count \fR] - [\fB-i | --stripe-index \fR] - [\fB-S | --stripe-size \fR] - [\fB-p | --pool \fR] - [\fB-o | --ost-list \fR] - [\fB-b | --block\fR] - [\fB-n | --non-block\fR] + [\fB-i | --stripe-index \fR] + [\fB-S | --stripe-size \fR] + [\fB-p | --pool \fR] + [\fB-o | --ost-list \fR] + [\fB-b | --block\fR] + [\fB-n | --non-block\fR] .IR file|directory .br .B lfs migrate <\fB-E | --component-end comp_end1\fR> [\fBSTRIPE_OPTIONS\fR] - <\fB-E | --component-end comp_end2\fR> [\fBSTRIPE_OPTIONS\fR] - \fB...\fR + <\fB-E | --component-end comp_end2\fR> [\fBSTRIPE_OPTIONS\fR] + \fB...\fR .IR filename .br .B lfs mkdir [\fB-c | --count \fR] - [\fB-i | --index \fR] - [\fB-h | --hash-type \fR] - [\fB-m | --mode \fR] - [\fB-D | --default\fR] + [\fB-i | --index \fR] + [\fB-h | --hash-type \fR] + [\fB-m | --mode \fR] + [\fB-D | --default\fR] .IR directory .br .B lfs osts @@ -92,19 +111,20 @@ lfs \- Lustre utility to create a file with specific striping pattern, find the .br .B lfs quotaoff [-ug] .br -.B lfs setstripe [--stripe-size|-S stripe_size] [--stripe-count|-c stripe_count] - \fB[--stripe-index|-i start_ost_index] [--pool|-p ] +.B lfs setstripe [--stripe-size|-S ] [--stripe-count|-c ] + \fB[--stripe-index|-i ] [--pool|-p ] \fB[--ost-list|-o ] \fR .br .B lfs setstripe -d .br -.B lfs setstripe <--component-end|-E end1> [STRIPE_OPTIONS] - \fB<--component-end|-E end2> [STRIPE_OPTIONS] ... \fR +.B lfs setstripe --component-end|-E [STRIPE_OPTIONS] + [\fB--component-end|-E [STRIPE_OPTIONS]] ... \fR .br -.B lfs setstripe --component-add <--component-end|-E end1> [STRIPE_OPTIONS] - \fB<--component-end|-E end2> [STRIPE_OPTIONS] ... \fR +.B lfs setstripe --component-add --component-end|-E [STRIPE_OPTIONS] + \fB<--component-end|-E > [STRIPE_OPTIONS]] ... \fR .br -.B lfs setstripe --component-del <--component-id|-I id | --component-flags flags> +.B lfs setstripe --component-del {--component-id|-I id | + \fB--component-flags } .br .B lfs --version .br @@ -117,32 +137,6 @@ can be used to create a new file with a specific striping pattern, determine the default striping pattern, gather the extended attributes (object numbers and location) for a specific file. It can be invoked interactively without any arguments or in a non-interactive mode with one of the arguments supported. -.TP -.B Component Flags -.br -Component flags can be set by option \fB--component-flags\fR<=\fIflags\fR>. - -.br -The following component flags are supported so far: -.RS -.TP -.B init -indicates the object(s) of this component has been instantiated. -.TP -.B stale -means the data contained in this component is stale. Data in a stale component -won't be returned by reading. Used only by FLR. -.TP -.B prefer -is a hint to Lustre that means this components will likely be chosen for read -and write. Used only by FLR. -.LP -The same set of flag can be set in \fBgetstripe\fR to list the component(s) -that matches the \fIflags\fR, or doesn't match the \fIflags\fR if it has a caret '^' -in front. It can also be applied to \fBfind\fR so that only the files that have -the components described by \fBflags\fR will be listed. -.RE -.LP .SH OPTIONS The various options supported by lfs are listed and explained below: .TP @@ -168,20 +162,6 @@ Even without -n, race conditions are possible and data version should be checked before and after an operation to be confident the data did not change during it. .TP -.B df -See -.BR lfs-df (1) -for details of -.B lfs df -usage. -.TP -.B find -To search the directory tree rooted at the given dir/file name for the files that match the given parameters: \fB--atime\fR (file was last accessed N*24 hours ago), \fB--ctime\fR (file's status was last changed N*24 hours ago), \fB--mtime\fR (file's data was last modified N*24 hours ago), \fB--obd\fR (file has an object on a specific OST or OSTs), \fB--size\fR (file has size in bytes, or \fBk\fRilo-, \fBM\fRega-, \fBG\fRiga-, \fBT\fRera-, \fBP\fReta-, or \fBE\fRxabytes if a suffix is given), \fB--type\fR (file has the type: \fBb\fRlock, \fBc\fRharacter, \fBd\fRirectory, \fBp\fRipe, \fBf\fRile, sym\fBl\fRink, \fBs\fRocket, or \fBD\fRoor (Solaris)), \fB--uid\fR (file has specific numeric user ID), \fB--user\fR (file owned by specific user, numeric user ID allowed), \fB--gid\fR (file has specific group ID), \fB--group\fR (file belongs to specific group, numeric group ID allowed),\fB--projid\fR (file has specific numeric project ID), \fB--layout\fR (file has a raid0 layout or is released). The option \fB--maxdepth\fR limits find to decend at most N levels of directory tree. The options \fB--print\fR and \fB--print0\fR print full file name, followed by a newline or NUL character correspondingly. Using \fB!\fR before an option negates its meaning (\fIfiles NOT matching the parameter\fR). Using \fB+\fR before a numeric value means 'more than n', while \fB-\fR before a numeric value means 'less than n'. - -.br -\fBlfs find\fR command allows to use component flags to list files that have -specified \fIflags\fR matched(See \fB Component Flags\fR). -.TP .B getname [-h]|[path ...] Report all the Lustre mount points and the corresponding Lustre filesystem instance. If one or more \fBpath\fR entries are provided, then only the @@ -194,79 +174,6 @@ List all the OSTs for all mounted filesystems. If a \fBpath\fR is provided that is located on a lustre mounted file system then only the OSTs belonging to that filesystem are displayed. .TP -.B getstripe [\fB--obd\fR|\fB-O\fR <\fIuuid\fR>] [\fB--quiet\fR|\fB-q\fR] - [\fB--verbose\fR|\fB-v\fR] [\fB--stripe-count\fR|\fB-c\fR] - [\fB--stripe-index\fR|\fB-i\fR] [\fB--mdt-index\fR|\fB-M\fR] - [\fB--fid\fR|\fB-F\fR] [\fB--stripe-size\fR|\fB-S\fR] - [\fB--directory\fR|\fB-d\fR] [\fB--layout\fR|\fB-L\fR] - [\fB--generation\fR|\fB-g\fR] - [\fB--component-id\fR[=\fIcomp_id\fR]|\fB-I\fR[\fIcomp_id\fR]] - [\fB--component-flags\fR[=\fIcomp_flags\fR]] [\fB--component-count\fR] - [\fB--component-start\fR[=[+-]\fIN\fR[kMGTPE]]] - [\fB--component-end\fR[=[+-]\fIN\fR[kMGTPE]]|\fB-E\fR[[+-]\fIN\fR[kMGTPE]]] - [\fB--pool\fR|\fB-p\fR] [\fB--recursive\fR|\fB-r\fR] [\fB--raw\fR|\fB-R\fR] - <\fIdirname\fR|\fIfilename\fR> ... -.br -List the striping information for a given filename or directory tree. -By default the stripe count, size, and offset will be returned. If you -only want specific striping information then the options of -.BR --count , -.BR --size , -.BR --index , -.BR --offset , -.BR --layout , -.BR --fid , -.BR --generation , -.BR --component-id , -.BR --component-flags , -.BR --component-count , -.BR --component-start , -.BR --component-end , -or -.B --pool -can be used to return only the specific fields. -.br -If the -.B --raw -option is specified, the stripe information is printed without substituting the -filesystem's default values for unspecified fields. If the striping EA is not -set, 0, 0, and -1 will be printed for the stripe count, size, and offset -respectively. -In the case where you only want details about the files' object id -information then the -.B --quiet -option is used. Additional information available about striping can be -displayed with -.BR --verbose . -The default behavior when a directory is specified is to list the striping -information for all files within the specified directory (like -.RB ' "ls -l" ') . -This can be expanded with -.B --recursive -which will recurse into all subdirectories. -If you wish to get striping information for only the specified directory, then -.B --directory -can be used to limit the information, like -.RB ' "ls -d" '). -You can limit the returned files to those with objects on a specific OST with -.BR --obd . -To show only the FID use -.BR --fid . -The layout generation can be printed with the -.B --generation -option. -You can limit the displayed content by specifing argument for -.B --component-id|-I -.B --component-flags -.B --component-start -.B --component-end|-E -options. For example, "--component-id=2" or "-I2" will only display the layout -attributes for the component with id equal to 2. - -.br -\fBlfs getstripe\fR command allows to use component flags to list files that -have specified \fIflags\fR matched(See \fB Component Flags\fR). -.TP .B fid2path [--link ] ... Print out the pathname(s) for the specified \fIfid\fR(s) from the filesystem mounted at \fBrootpath\fR or named \fBfsname\fR. If a file has multiple @@ -343,40 +250,6 @@ Provides brief help on the various arguments Quit the interactive lfs session .SH EXAMPLES .TP -.B $ lfs getstripe -v /mnt/lustre/file1 -Lists the detailed object allocation of a given file -.TP -.B $ lfs getstripe -v -I2 /mnt/lustre/file1 -Lists the detailed information of the component 2 in a given file -.TP -.B $ lfs getstripe --component-flags=^init -I /mnt/lustre/file1 -Print only the component IDs for all the uninstantiated components -.TP -.B $ lfs getstripe --component-flags=init,^stale -I /mnt/lustre/file1 -Print only the component(s) that are instantiated but not stale -.TP -.B $ lfs getstripe -E-64M /mnt/lustre/file1 -Lists the information of the components in a file which has less than 64M extent end -.TP -.B $ lfs getstripe -I3 --component-start /mnt/lustre/file1 -Print only the component start for the component with ID of 3 -.TP -.B $ lfs find /mnt/lustre -Efficiently lists all files in a given directory and its subdirectories -.TP -.B $ lfs find /mnt/lustre -mtime +30 -type f -print -Recursively list all regular files in given directory more than 30 days old -.TP -.B $ lfs find --obd OST2-UUID /mnt/lustre/ -Recursively list all files in a given directory that have objects on OST2-UUID. -.TP -.B $ lfs find --component-count +3 /mnt/lustre -Recursively list all files that have more than 3 components. -.TP -.B $ lfs find --component-flags=init,prefer,^stale /mnt/lustre -Recursively list all files that have at least one component with both 'init' and -\'prefer' flags set, and doesn't have flag 'stale' set. -.TP .B $ lfs check servers Check the status of all servers (MDT, OST) .TP @@ -404,20 +277,22 @@ Turn quotas of user and group on .B $ lfs quotaoff -ug /mnt/lustre Turn quotas of user and group off .SH NOTES -The usage of \fBlfs hsm_*\fR, \fBlfs setstripe\fR, \fBlfs migrate\fR, \fBlfs setdirstripe\fR, -\fBlfs getdirstripe\fR, \fBlfs mkdir\fR and \fBlfs project\fR are explained in separate -man pages. -.SH BUGS -The \fBlfs find\fR command isn't as comprehensive as \fBfind\fR(1). +The usage of \fBlfs find\fR, \fBlfs getstripe\fR, \fBlfs hsm_*\fR, +\fBlfs setstripe\fR, \fBlfs migrate\fR, \fBlfs getdirstripe\fR, +\fBlfs setdirstripe\fR, \fBlfs mkdir\fR, and \fBlfs project\fR are explained +in separate man pages. .SH AUTHOR The lfs command is part of the Lustre filesystem. .SH SEE ALSO .BR lctl (8), .BR lfs-df (1), +.BR lfs-find (1), +.BR lfs-getstripe (1), .BR lfs-getdirstripe (1), .BR lfs-hsm (1), .BR lfs-mkdir (1), .BR lfs-migrate (1), +.BR lfs_migrate (1), .BR lfs-project (1), .BR lfs-setdirstripe (1), .BR lfs-setquota (1), diff --git a/lustre/utils/lfs.c b/lustre/utils/lfs.c index cc0738b..89ade08 100644 --- a/lustre/utils/lfs.c +++ b/lustre/utils/lfs.c @@ -327,22 +327,22 @@ command_t cmdlist[] = { "will become inaccessable after this command. This can only be done\n" "by the administrator\n" "usage: rm_entry \n"}, - {"pool_list", lfs_poollist, 0, - "List pools or pool OSTs\n" - "usage: pool_list [.] | \n"}, - {"find", lfs_find, 0, - "find files matching given attributes recursively in directory tree.\n" - "usage: find ...\n" - " [[!] --atime|-A [+-]N] [[!] --ctime|-C [+-]N]\n" - " [[!] --mtime|-M [+-]N] [[!] --mdt|-m ]\n" - " [--maxdepth|-D N] [[!] --name|-n ]\n" - " [[!] --ost|-O ] [--print|-p] [--print0|-P]\n" - " [[!] --size|-s [+-]N[bkMGTPE]]\n" - " [[!] --stripe-count|-c [+-]]\n" - " [[!] --stripe-index|-i ]\n" - " [[!] --stripe-size|-S [+-]N[kMGT]] [[!] --type|-t ]\n" - " [[!] --gid|-g|--group|-G |]\n" - " [[!] --uid|-u|--user|-U |] [[!] --pool ]\n" + {"pool_list", lfs_poollist, 0, + "List pools or pool OSTs\n" + "usage: pool_list [.] | \n"}, + {"find", lfs_find, 0, + "find files matching given attributes recursively in directory tree.\n" + "usage: find ...\n" + " [[!] --atime|-A [+-]N] [[!] --ctime|-C [+-]N]\n" + " [[!] --mtime|-M [+-]N] [--maxdepth|-D N]\n" + " [[!] --mdt-index|--mdt|-m ]\n" + " [[!] --name|-n ] [[!] --ost|-O ]\n" + " [--print|-P] [--print0|-0] [[!] --size|-s [+-]N[bkMGTPE]]\n" + " [[!] --stripe-count|-c [+-]]\n" + " [[!] --stripe-index|-i ]\n" + " [[!] --stripe-size|-S [+-]N[kMGT]] [[!] --type|-t ]\n" + " [[!] --gid|-g|--group|-G |]\n" + " [[!] --uid|-u|--user|-U |] [[!] --pool ]\n" " [[!] --projid ]\n" " [[!] --layout|-L released,raid0,mdt]\n" " [[!] --component-count [+-]]\n" @@ -354,7 +354,7 @@ command_t cmdlist[] = { "\t !: used before an option indicates 'NOT' requested attribute\n" "\t -: used before a value indicates less than requested value\n" "\t +: used before a value indicates more than requested value\n" - "\tmdt-hash: hash type of the striped directory.\n" + "\thashtype: hash type of the striped directory.\n" "\t fnv_1a_64 FNV-1a hash algorithm\n" "\t all_char sum of characters % MDT_COUNT\n"}, {"check", lfs_check, 0, @@ -2896,10 +2896,10 @@ static int lfs_find(int argc, char **argv) /* find { .val = 'o' .name = "or", .has_arg = no_argument }, like find(1) */ { .val = 'O', .name = "obd", .has_arg = required_argument }, { .val = 'O', .name = "ost", .has_arg = required_argument }, - /* no short option for pool, p/P already used */ + /* no short option for pool yet, can be 'p' after 2.18 */ { .val = LFS_POOL_OPT, .name = "pool", .has_arg = required_argument }, - { .val = 'p', .name = "print0", .has_arg = no_argument }, + { .val = '0', .name = "print0", .has_arg = no_argument }, { .val = 'P', .name = "print", .has_arg = no_argument }, { .val = LFS_PROJID_OPT, .name = "projid", .has_arg = required_argument }, @@ -2928,7 +2928,7 @@ static int lfs_find(int argc, char **argv) /* when getopt_long_only() hits '!' it returns 1, puts "!" in optarg */ while ((c = getopt_long_only(argc, argv, - "-A:c:C:D:E:g:G:H:i:L:m:M:n:O:Ppqrs:S:t:T:u:U:v", + "-0A:c:C:D:E:g:G:H:i:L:m:M:n:O:Ppqrs:S:t:T:u:U:v", long_opts, NULL)) >= 0) { xtime = NULL; xsign = NULL; @@ -3138,22 +3138,6 @@ static int lfs_find(int argc, char **argv) param.fp_exclude_uid = !!neg_opt; param.fp_check_uid = 1; break; - case LFS_POOL_OPT: - if (strlen(optarg) > LOV_MAXPOOLNAME) { - fprintf(stderr, - "Pool name %s is too long" - " (max is %d)\n", optarg, - LOV_MAXPOOLNAME); - ret = -1; - goto err; - } - /* we do check for empty pool because empty pool - * is used to find V1 lov attributes */ - strncpy(param.fp_poolname, optarg, LOV_MAXPOOLNAME); - param.fp_poolname[LOV_MAXPOOLNAME] = '\0'; - param.fp_exclude_pool = !!neg_opt; - param.fp_check_pool = 1; - break; case 'n': param.fp_pattern = (char *)optarg; param.fp_exclude_pattern = !!neg_opt; @@ -3235,10 +3219,35 @@ err_free: free(buf); break; } +#if LUSTRE_VERSION_CODE >= OBD_OCD_VERSION(2, 18, 53, 0) case 'p': +#endif + case LFS_POOL_OPT: + if (strlen(optarg) > LOV_MAXPOOLNAME) { + fprintf(stderr, + "Pool name %s is too long (max %d)\n", + optarg, LOV_MAXPOOLNAME); + ret = -1; + goto err; + } + /* + * We do check for empty pool because empty pool + * is used to find V1 LOV attributes + */ + strncpy(param.fp_poolname, optarg, LOV_MAXPOOLNAME); + param.fp_poolname[LOV_MAXPOOLNAME] = '\0'; + param.fp_exclude_pool = !!neg_opt; + param.fp_check_pool = 1; + break; +#if LUSTRE_VERSION_CODE < OBD_OCD_VERSION(2, 14, 53, 0) + case 'p': /* want this for --pool, to match getstripe/find */ + fprintf(stderr, + "warning: -p deprecated, use --print0 or -0\n"); +#endif + case '0': param.fp_zero_end = 1; break; - case 'P': + case 'P': /* we always print, this option is a no-op */ break; case LFS_PROJID_OPT: rc = name2projid(¶m.fp_projid, optarg);