From b6deb420a81f86a70312ae1de507066a89f92268 Mon Sep 17 00:00:00 2001 From: Alexandre Ioffe Date: Thu, 28 Dec 2023 21:42:41 -0800 Subject: [PATCH] LU-17370 utils: simplify lfs help text Simplify help text for lfs getstripe and lfs setstripe. Update corresponding man pages lfs-getstripe and lfs-setstripe. On man pages make left side adjustment and disable hyphenation: '.nh', '.ad l' to prevent hyphenation of keywords Signed-off-by: Alexandre Ioffe Test-Parameters: trivial Change-Id: Iae9d3534230ee7d325fbeffd78b5c12632a4a161 Reviewed-on: https://review.whamcloud.com/c/fs/lustre-release/+/53564 Tested-by: jenkins Tested-by: Maloo Reviewed-by: Oleg Drokin Reviewed-by: Andreas Dilger Reviewed-by: Jian Yu Reviewed-by: Arshad Hussain --- lustre/doc/lfs-getstripe.1 | 128 ++++++++++++++-------------- lustre/doc/lfs-setstripe.1 | 203 +++++++++++++++++++++++---------------------- lustre/utils/lfs.c | 72 +++++++--------- 3 files changed, 196 insertions(+), 207 deletions(-) diff --git a/lustre/doc/lfs-getstripe.1 b/lustre/doc/lfs-getstripe.1 index 992f73b..844b80d 100644 --- a/lustre/doc/lfs-getstripe.1 +++ b/lustre/doc/lfs-getstripe.1 @@ -4,10 +4,10 @@ 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--component-end\fR|\fB--comp-end\fR|\fB-E\fR[\fB=\fR[\fB+-\fR]\fIEND_OFFSET\fR[\fBKMGTPE\fR]] + [\fB--component-flags\fR|\fB--comp-flags\fR[\fB=\fICOMP_FLAGS\fR]] + [\fB--component-id\fR|\fB--comp-id\fR[=\fICOMP_ID\fR]|\fB-I\fR[\fICOMP_ID\fR]] + [\fB--component-start\fR[\fB=\fR[\fB+-\fR]\fISTART_OFFSET\fR[\fBKMGTPE\fR]]] [\fB--extension-size\fR|\fB--ext-size\fR|\fB-z\fR] [\fB--directory\fR|\fB-d\fR] [\fB--fid\fR|\fB-F\fR] @@ -16,7 +16,7 @@ lfs-getstripe \- Lustre client command to print layout parameters of a file [\fB--hex-idx\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--ost\fR|\fB-O\fR \fIOST_NAME\fR] [\fB--pool\fR|\fB-p\fR] [\fB--quiet\fR|\fB-q\fR] [\fB--recursive\fR|\fB-r\fR] @@ -24,12 +24,14 @@ lfs-getstripe \- Lustre client command to print layout parameters of a file [\fB--stripe-count\fR|\fB-c\fR] [\fB--stripe-index\fR|\fB-i\fR] [\fB--stripe-size\fR|\fB-S\fR] [\fB--mirror-count\fR|\fB-N\fR] - [[\fB!\fR] \fB--mirror-index\fR=[\fB+-\fR]\fI\fR | [\fB!\fR] \fB--mirror-id\fR=[\fB+-\fR]\fI\fR] + [[\fB!\fR] \fB--mirror-index\fR=[\fB+-\fR]\fIMIRROR_INDEX\fR | [\fB!\fR] \fB--mirror-id\fR=[\fB+-\fR]\fIMIRROR_ID\fR] [\fB--verbose\fR|\fB-v\fR] [\fB--yaml\fR|\fB-y\fR][\fB--no-follow\fR] -<\fIdirname\fR|\fIfilename\fR> ... +\fIFILENAME\fR|\fIDIRECTORY\fR ... .SH DESCRIPTION +.nh +.ad l .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, @@ -72,34 +74,34 @@ sign must be used. .PP 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 " '). +.RB ' "ls -l \fIDIRECTORY\fR" '). .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 ]] +.BR --component-end | --comp-end | -E \fR[[ +- \fR] \fIEND_OFFSET\fR [ 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 +.BI + END_OFFSET or -.BI - end +.BI - END_OFFSET is used, print components with respectively a larger or smaller -.I end +.I END_OFFSET offset. .TP -.BR --component-flags | --comp-flags [ = [ ^ ] \fIflag ,...]] +.BR --component-flags \fR| --comp-flags \fR[ \fB^ \fR] \fICOMP_FLAG\fR ,... Print only the component flags. If -.I flag +.I COMP_FLAG is specified, print only components matching the specified -.I flag +.I COMP_FLAG set. If -.BI ^ flag +.BI ^ COMP_FLAG is used, print only components not matching -.IR flag . +.IR COMP_FLAG . Multiple flags may be specified, separated by commas. Valid flag names are: .RS 1.2i .TP @@ -130,28 +132,28 @@ lfs mirror resync\fR. Files with the \fBnosync\fR flag will also print the timestamp when the flag was set on the replica. .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 +.BR --component-id | --comp-id | -I \fR[ \fICOMP_ID\fR ] +Print only the component COMP_ID number for the component(s). The file-unique +component COMP_ID is assigned as each component is created, and is not re-used. +The COMP_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 +.I COMP_ID is specified, then print only the fields for the matching component. .TP -.BR --component-start | --comp-start [ = [ +- ] \fIstart [ KMGTPE ]] +.BR --component-start \fR| --comp-start \fR[ +- \fR] \fISTART_OFFSET\fR [ KMGTPE ] Print only the component start offset (in bytes) for the component(s). If the component -.I start +.I START_OFFSET 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 +.BI + START_OFFSET or -.BI - start +.BI - START_OFFSET is used, print components with respectively a larger or smaller -.I start +.I START_OFFSET offset. .TP .BR --directory | -d @@ -161,7 +163,7 @@ Get striping information for only the specified directory, like .BR --fid | -F Show only the 128-bit unique Lustre File Identifier (FID). .TP -.BR --generation | -g +.BR --generation \fR| -g Print only the layout generation number. .TP .BR --help | -h @@ -184,86 +186,88 @@ HSM-archived files that are not resident in the filesystem. Files that have the first data component on an MDT. .RE .TP -.BR --mdt | --mdt-index | -m +.BR --mdt \fR| --mdt-index \fR| -m Show the MDT index on which the file or directory inode is located. .TP -.BR --mirror-count | -N +.BR --mirror-count \fR| -N Print the number of mirrors on the file. .TP -.BR --mirror-index = [\fB+-\fR]\fR<\fIindex\fR> -Print only the components of \fI\fR-th mirror, based on the order -that the mirror components are stored in the file layout. The \fIindex\fR +.BR --mirror-index=\fR[\fB+-\fR]\fR\fIMIRROR_INDEX\fR +Print only the components of \fIMIRROR_INDEX\fR-th mirror, based on the order +that the mirror components are stored in the file layout. The \fIMIRROR_INDEX\fR starts at 1. If -.BI + index +.BI + MIRROR_INDEX or -.BI - index +.BI - MIRROR_INDEX is used, print components of mirror(s) respectively later or earlier than -the \fIindex\fR-th mirror. +the \fIMIRROR_INDEX\fR-th mirror. .RS 1.2i .TP .B ! -Negates the meaning. Using + before \fIindex\fR means mirror appears 'later -than \fIindex\fR', -- before \fIindex\fR means mirror appears 'earlier than \fIindex\fR'. If -neither is used, it means 'equal to \fIindex\fR'. +Negates the meaning. Using + before \fIMIRROR_INDEX\fR means mirror appears 'later +than \fIMIRROR_INDEX\fR', +- before \fIMIRROR_INDEX\fR means mirror appears 'earlier +than \fIMIRROR_INDEX\fR'. If +neither is used, it means 'equal to \fIMIRROR_INDEX\fR'. .RE .TP -.BR --mirror-id = [\fB+-\fR]\fR<\fIid\fR> -Print only the components of the mirror with ID of \fIid\fR. The mirror IDs -are assigned to new mirrors as they are created, but may not be sequential -if some mirrors are removed. If -.BI + id +.B --mirror-id=\fR[\fB+-\fR]\fR\fIMIRROR_ID\fR +Print only the components of the mirror with ID of \fIMIRROR_ID\fR. +The mirror IDs are assigned to new mirrors as they are created, +but may not be sequential if some mirrors are removed. If +.BI + MIRROR_ID or -.BI - id +.BI - MIRROR_ID is used, print components of mirror(s) with respectively a larger or smaller mirror ID of -.I id +.I MIRROR_ID . .RS 1.2i .TP .B ! -Negates the meaning. Using + before \fIid\fR means mirror with ID 'larger -than \fIid\fR', - before \fIid\fR means mirror with ID 'smaller than \fIid\fR'. -If neither is used, it means 'equal to \fIid\fR'. +Negates the meaning. Using \fB+\fR before \fIMIRROR_ID\fR means mirror with ID +'larger than \fIMIRROR_ID\fR', \fB-\fR before \fIMIRROR_ID\fR means mirror +with ID 'smaller than \fIMIRROR_ID\fR'. If neither is used, +it means 'equal to \fIMIRROR_ID\fR'. .RE .TP -.BR --ost | -O -Print only the components located on a specific OST. +.BR --ost \fR| -O \fIOST_NAME\fR +Print only file layouts and OST objects on the specified \fIOST_NAME\fR. .TP -.BR --pool | -p +.BR --pool \fR| -p Print only the OST pool name on which the file was created. .TP -.BR --quiet | -q +.BR --quiet \fR| -q Print only allocated objects for each file, not other layout parameters. .TP -.BR --raw | -R +.BR --raw \fR| -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 +.BR --recursive \fR| -r Recurse into all subdirectories. .TP -.BR --stripe-count | -c +.BR --stripe-count \fR| -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 +.BR --stripe-index \fR| -i Print the starting OST index for the file layout. .TP -.BR --stripe-size | -S +.BR --stripe-size \fR| -S Print the stripe size in bytes. For composite files this is the stripe size of the last initialized component. .TP -.BR --extension-size | --ext-size | -z +.BR --extension-size \fR| --ext-size \fR| -z Print the extension size in bytes. For composite files this is the extension size of the first extension component. .TP -.BR --verbose | -v +.BR --verbose \fR| -v Also print the layout magic, FID sequence, FID object ID, and FID, in addition to the normally-printed attributes. .TP -.BR --yaml | -y +.BR --yaml \fR| -y Always print the layout in YAML format, rather than only using this format for composite files. .TP diff --git a/lustre/doc/lfs-setstripe.1 b/lustre/doc/lfs-setstripe.1 index 3b073a8..a3a831e 100644 --- a/lustre/doc/lfs-setstripe.1 +++ b/lustre/doc/lfs-setstripe.1 @@ -2,40 +2,42 @@ .SH NAME lfs-setstripe \- set striping pattern of a file or directory default .SH SYNOPSIS -.B lfs setstripe \fR[\fISTRIPE_OPTIONS\fR] <\fIdirectory\fR|\fIfile\fR> +.B lfs setstripe \fR[\fISTRIPE_OPTIONS\fR] \fIDIRECTORY\fR|\fIFILENAME\fR .br -.B lfs setstripe -E \fIend1\fR [\fISTRIPE_OPTIONS\fR] ... \ -<\fIdirectory\fR|\fIfile\fR> +.B lfs setstripe -E \fICOMP_END\fR [\fISTRIPE_OPTIONS\fR] ... \ +\fIDIRECTORY\fR|\fIFILENAME\fR .br -.B lfs setstripe --comp-add -E \fIend1\fR [\fISTRIPE_OPTIONS\fR] ... \ -<\fIfile\fR> +.B lfs setstripe --comp-add -E \fICOMP_END\fR [\fISTRIPE_OPTIONS\fR] ... \ +\fIFILENAME\fR .br -.B lfs setstripe --comp-del \fR{\fB-I \fIcomp_id\fR|\ -\fB--comp-flags=\fIcomp_flags\fR} <\fIfile\fR> +.B lfs setstripe --comp-del \fR[\fB-I \fICOMP_ID\fR|\ +\fB--comp-flags=\fICOMP_FLAGS\fR] \fIFILENAME\fR .br -.B lfs setstripe --comp-set \fR{-I \fIcomp_id\fR|\ -\fB--comp-flags=\fIcomp_flags\fR} <\fIfile\fR> +.B lfs setstripe --comp-set \fR[\fB-I \fICOMP_ID\fR|\ +\fB--comp-flags=\fICOMP_FLAGS\fR] \fIFILENAME\fR .br -.B lfs setstripe -N\fR[\fImirror_count\fR] \fR[\fISTRIPE_OPTIONS\fR] <\fIdirectory\fR|\fIfilename\fR> +.B lfs setstripe -N\fR[\fIMIRROR_COUNT\fR] \fR[\fISTRIPE_OPTIONS\fR] \fIDIRECTORY\fR|\fIFILENAME\fR .br -.B lfs setstripe -d \fR<\fIdirectory\fR> +.B lfs setstripe -d \fR\fIDIRECTORY\fR .br -.B lfs setstripe --yaml=\fR<\fIyaml_template_file.lyl\fR> <\fIfile\fR> +.B lfs setstripe --yaml=\fR\fIYAML_TEMPLATE_FILE.LYL\fR \fIFILENAME\fR .br -.B lfs setstripe --copy=\fR<\fIsource_template_file\fR> <\fIfile\fR> +.B lfs setstripe --copy=\fR\fISOURCE_TEMPLATE_FILE\fR \fIFILENAME\fR .br -.B lfs setstripe --foreign[=\fR<\fIforeign_type\fR>\fB] \ -[--flags=\fR<\fIhex\fR>\fB] --xattr=\fR<\fIlayout_string\fR> <\fIfile\fR> +.B lfs setstripe --foreign\fR[\fB=\fR\fIFOREIGN_TYPE\fR] \ +\fR[\fB--flags=\fR\fIHEX\fR] \fB--xattr=\fR\fILAYOUT_STRING\fR \fIFILENAME\fR .SH DESCRIPTION +.nh +.ad l The .B lfs setstripe command is used to create a new -.I file +.I FILENAME in a Lustre filesystem with the specified layout, or to specify the default layout for new files created in -.IR directory , +.IR DIRECTORY , or anywhere in the filesystem if -.I directory +.I DIRECTORY is the filesystem root and no other layout takes precedence. .PP Files with composite layouts allow different @@ -49,161 +51,159 @@ default layout at runtime. The default layout set on a non-root directory will be copied to any new subdirectories created within that directory at the time they are created. .TP -.B lfs setstripe \fR[\fISTRIPE_OPTIONS\fR ...] <\fIdirectory\fR|\fIfile\fR> +.B lfs setstripe \fR[\fISTRIPE_OPTIONS\fR ...] \fIDIRECTORY\fR|\fIFILENAME\fR Create a new -.I file +.I FILENAME with specified plain layout using the specified .IR STRIPE_OPTIONS , or replace the default file layout on an existing -.IR directory . +.IR DIRECTORY . .TP -.B lfs setstripe -E \fIend\fR [\fISTRIPE_OPTIONS\fR] ... \ -<\fIdirectory\fR|\fIfile\fR> +.B lfs setstripe -E \fIEND_OFFSET\fR [\fISTRIPE_OPTIONS\fR] ... \ +\fIDIRECTORY\fR|\fIFILENAME\fR .br Create a new composite -.I file -with one or more component layouts (where \fIend\fR marks the end of the +.I FILENAME +with one or more component layouts (where \fIEND_OFFSET\fR marks the end of the current component), or set or replace the default file layout on an existing -.IR directory. +.IR DIRECTORY. .TP -.B lfs setstripe --component-add -E \fIend1\fR [\fISTRIPE_OPTIONS\fR] \ -... <\fIfile\fR> +.B lfs setstripe --component-add -E \fIEND_OFFSET\fR [\fISTRIPE_OPTIONS\fR] \ +... \fIFILENAME\fR .br Add one or more components after the last component of an existing composite file that does not yet have a component at .BR eof . .TP -.B lfs setstripe --comp-del \fR{\fB-I \fIcomp_id\fR | \ -\fB--comp-flags \fIcomp_flags\fR} <\fIfile\fR> +.B lfs setstripe --comp-del \fR[\fB-I \fICOMP_ID\fR | \ +\fB--comp-flags \fICOMP_FLAGS\fR] \fIFILENAME\fR Remove the component(s) specified by component ID or flags from -.IR file . +.IR FILENAME . .TP -.B lfs setstripe --comp-set \fR{\fB-I \fIcomp_id\fR | \ -\fB--comp-flags \fIcomp_flags\fR} <\fIfile\fR> +.B lfs setstripe --comp-set \fR[\fB-I \fICOMP_ID\fR | \ +\fB--comp-flags \fICOMP_FLAGS\fR] \fIFILENAME\fR Set or clear -.I flags +.I COMP_FLAGS on the specified component. This command can be only be applied to mirrored files. .TP -.B lfs setstripe -N \fR[\fImirror_count\fR] \fR[\fICOMPONENT_OPTIONS\fR] <\fIdirectory\fR|\fIfile\fR> +.B lfs setstripe -N \fR[\fIMIRROR_COUNT\fR] \fR[\fICOMPONENT_OPTIONS\fR] \fIDIRECTORY\fR|\fIFILENAME\fR Create a new -.I file +.I FILENAME with the specified number of mirrors and other specified layout options, or set or replace the default file layout on an existing -.IR directory . +.IR DIRECTORY . .TP -.B lfs setstripe -d \fR<\fIdirectory\fR> +.B lfs setstripe -d \fR\fIDIRECTORY\fR .br Delete the default layout on the specified directory. It is not necessary to delete the default layout on a directory before replacing it, only if the directory should revert from a directory-specific default layout to using the global filesystem default layout stored on the root directory. .TP -.B lfs setstripe --yaml=\fR<\fIyaml_template_file.lyl\fR> <\fIfile\fR> +.B lfs setstripe --yaml=\fR\fIYAML_TEMPLATE_FILE.LYL\fR \fIFILENAME\fR .br Create a new -.I file +.I FILENAME using the Lustre YAML Layout template -.IR yaml_template_file.lyl , +.IR YAML_TEMPLATE_FILE.LYL , created from -.I existing_file +.I EXISTING_FILE via: .br -.B lfs getstripe --yaml \fR<\fIexisting_file\fR> > <\fIyaml_template_file.lyl\fR> +.B lfs getstripe --yaml \fR\fIEXISTING_FILE\fR > \fIYAML_TEMPLATE_FILE.LYL\fR .br -.I yaml_template_file.lyl +.I YAML_TEMPLATE_FILE.LYL is a plain-text file that may be saved and/or modified after creation. This allows complex file layouts to be created once and re-used later. .TP -.B lfs setstripe --copy=\fR<\fIsource_template_file\fR> <\fIfile\fR> +.B lfs setstripe --copy=\fR\fISOURCE_TEMPLATE_FILE\fR \fIFILENAME\fR .br Create a new .I file using the same layout as an existing -.IR source_template_file . +.IR SOURCE_TEMPLATE_FILE . This is similar to the .B --yaml option but avoids the need for the intermediate .B .lyl file. .TP -.B lfs setstripe --foreign[=\fR<\fIforeign_type\fR>\fB] \ -[--flags=\fR<\fIhex\fR>\fB] --xattr=\fR<\fIlayout_string\fR> <\fIfile\fR> +.B lfs setstripe --foreign[=\fR\fIFOREIGN_TYPE\fR\fB] \ +[--flags=\fR\fIHEX\fR\fB] --xattr=\fR\fILAYOUT_STRING\fR \fIFILENAME\fR .br Create a new -.I file +.I FILENAME with a foreign/non-lustre layout of type -.I foreign_type \fR(\fBnone\fR, \fBsymlink\fR, ...) +.I FOREIGN_TYPE \fR(\fBnone\fR, \fBdaos\fR, ...) with flags -.I hex +.I HEX and a free-format layout value of -.I layout_string. +.I LAYOUT_STRING. .SH STRIPE_OPTIONS The various OST stripe related options are listed and explained below: .TP -.B -c\fR, \fB--stripe-count \fR<\fIstripe_count\fR> +.B -c\fR, \fB--stripe-count \fR\fISTRIPE_COUNT\fR The number of OSTs to stripe a file over. \fB0 \fRmeans to use the filesystem-wide default stripe count (default 1), and \fB-1 \fRmeans to stripe over all available OSTs. .TP -.B -C\fR, \fB--overstripe-count \fR<\fIstripe_count\fR> +.B -C\fR, \fB--overstripe-count \fR\fISTRIPE_COUNT\fR The number of stripes to create, creating > 1 stripe per OST if count exceeds the number of OSTs in the file system. \fB0 \fRmeans to use the filesystem-wide default stripe count (default 1), and \fB-1 \fRmeans to stripe over all available OSTs. .TP -.B -S\fR, \fB--stripe-size \fR<\fIstripe_size\fR> +.B -S\fR, \fB--stripe-size \fR\fISTRIPE_SIZE\fR The number of bytes to store on each OST before moving to the next OST. A stripe size of .B 0 -means the file should use the filesystem-wide default stripe_size +means the file should use the filesystem-wide default stripe size (default 4MiB). An optional suffix can be used to specify the units in .BR K ibi-, .BR M "ebi-, or" .BR G ibibytes. The -.I stripe_size +.I STRIPE_SIZE must be a multiple of 64KiB. Values below 4096 are assumed to be in KiB units. .TP -.B -i\fR, \fB--stripe-index \fR<\fIstart_ost_index\fR> +.B -i\fR, \fB--stripe-index \fR\fISTART_OST_IDX\fR The OST index (starting at 0) on which to start striping for this file. A -.I start_ost_index +.I START_OST_IDX of .B -1 allows the MDS to choose the starting index and it is strongly recommended, as this allows space and load balancing to be done by the MDS as needed. .TP -.B -L\fR, \fB--layout \fR<\fIlayout_type\fR> + The type of layout for that component, which can be one of: .RS .B raid0\fR - stripe the file data across -.B stripe_count -OST objects in units of -.B stripe_size -chunks. This is the default layout if not specified. +\fISTRIPE_COUNT\fR OST objects in units of +\fISTRIPE_SIZE\fR chunks. This is the default layout if not specified. .RE .RS .B mdt\fR - place the first component of the file data on the MDT for faster access where the inode is located. This can be used for small files, and with -composite file layouts. The +composite file layouts. The .B mdt type may only be used for first component of a file. The -.IR stripe_size +.IR STRIPE_SIZE of the MDT component is always equal to the component size. There is also a per-MDT tunable parameter .IR lod.dom_stripesize that limits the maximum size of a DoM stripe. It can be changed on the MDS via -.B lctl set_param lod.*.dom_stripesize=\fR<\fIstripe_size\fR> , +.B lctl set_param lod.*.dom_stripesize=\fR\fISTRIPE_SIZE\fR , where -.I stripe_size +.I STRIPE_SIZE must be a multiple of 64KiB in size, see also .BR lctl (8) for details. .RE .TP -.B -o\fR, \fB--ost \fR<\fIost_indices\fR> -Used to specify the exact stripe layout on the file system. \fIost_indices\fR +.B -o\fR, \fB--ost \fR\fIOST_IDX\fR +Used to specify the exact stripe layout on the file system. \fIOST_IDX\fR is a list of OSTs referenced by their indices, which are specified in decimal or hex form and can be obtained using the .B lfs osts @@ -216,29 +216,29 @@ OSTs. If the option is combined with .B -o the -.I stripe_count +.I STRIPE_COUNT must agree with the number of OSTs in -.IR ost_indices . +.IR OST_IDX . If the .B -i option is combined with .B -o the -.I start_ost_index +.I START_OST_IDX must be in the OST list, and it will be used as the index on which to start striping the file. Otherwise the striping will occur in the order specified in -.IR ost_indices . +.IR OST_IDX . .TP -.B -p\fR, \fB--pool \fR<\fIpool_name\fR> +.B -p\fR, \fB--pool \fR\fIPOOL_NAME\fR Allocate objects from the predefined OST pool -.I pool_name +.I POOL_NAME for the layout of this file or component. The -.IR stripe_count , -.IR stripe_size , +.IR STRIPE_COUNT , +.IR STRIPE_SIZE , and -.I start_ost_index +.I START_OST_IDX can be used to select a subset of the OSTs within the pool; the -.I start_ost_index +.I START_OST_IDX must be part of the pool or an error will be returned. It is possible to specify a different pool for each component of a file. If no pool is specified, it will be inherited from the previous component (for @@ -257,10 +257,10 @@ or (since Lustre 2.15) to force a component to inherit the pool from the parent or root directory instead of the previous component. .TP -.B --foreign \fR[<\fIforeign_type\fR>] -file layout is non-lustre/free-format and of type < -.IR foreign_type ->, if specified (see also +.B --foreign \fR[\fIFOREIGN_TYPE\fR] +file layout is non-lustre/free-format and of type +.IR FOREIGN_TYPE +, if specified (see also .IR --xattr and .IR --flags @@ -272,12 +272,12 @@ and , default is .BR none . -.B -x\fR, \fB--xattr \fR<\fIlayout_string\fR> +.B -x\fR, \fB--xattr \fR\fILAYOUT_STRING\fR Mandatory non-lustre/free-format layout/LOV EA content for .I foreign file. .TP -.B -F\fR, \fB--flags \fR<\fIhex\fR> +.B -F\fR, \fB--flags \fR\fIHEX\fR Optional bitmap of flags for foreign type. .SH COMPONENT_OPTIONS The various component related options are listed and explained below. The @@ -286,13 +286,13 @@ options can be shortened to .B --comp-* if desired. .TP -.B -E\fR, \fB--component-end \fR<\fIend\fR> +.B -E\fR, \fB--component-end \fR\fIEND_OFFSET\fR Add a new component to a file using the .I STRIPE_OPTIONS following the .B -E argument. These options apply to the component ending at offset -.I end +.I END_OFFSET in bytes, or by using a suffix (KMGTP) to specify base-two units, such as 256M for 2^28 bytes. An offset of .B -1 @@ -303,7 +303,7 @@ component starts at offset 0, and each subsequent component starts at the end of the previous component, so they must be specified in increasing file offset order, and must be a multiple of 64KiB to align with the minimum -.I stripe_size +.I STRIPE_SIZE value. Values below 4096 are assumed to be in KiB units. .PP .RS @@ -328,23 +328,24 @@ specified component, or use to add more components to the end of the file. .RE .TP -.B -z, --extension-size, ext-size\fR <\fIext_size\fR> +.B -z, --extension-size, --ext-size\fR \fIEXT_SIZE\fR This option modifies the \fB-E\fR option, components which have this option specified are created as pairs of components, extendable and extension ones. .PP .RS The extendable component starts at offset 0 if this is the first -component of the file. In this case it ends at offset \fIext_size\fR and +component of the file. In this case it ends at offset \fIEXT_SIZE\fR and it gets the flag \fBinit\fR (initialized). The extendable component starts at the end of the previous component if this is not the first component of the file. In this case it ends at the same offset (0-length component). .PP The extension component covers the rest of the specified region up to -the \fIend\fR specified by \fB-E\fR option and gets the flag \fBextension\fR. +the \fIEND_OFFSET\fR specified by \fB-E\fR option and gets +the flag \fBextension\fR. This component covers the space reserved for the extendable component but not used immediately, the later extension of the extendable component is done -by \fIext_size\fR each time until the extension component is used up. This is +by \fIEXT_SIZE\fR each time until the extension component is used up. This is used to control the space on OSTs the stripe is located on, in case one of them is low on space, the remaining extension component region is added to the next component. @@ -379,7 +380,7 @@ mirrored files is not currently allowed, see the .BR lfs-mirror-split (1) command. .TP -.B --component-flags \fR<\fIflags\fR> +.B --component-flags \fR\fICOMP_FLAGS\fR Find, set, or clear .B flags on a specific component. Allowed @@ -418,14 +419,14 @@ A leading '^' before \fIflags\fR clears the flags, or finds components not matching the flags. Multiple flags can be separated by comma(s). .RE .TP -.B -I\fR, \fB--component-id \fR<\fIcomp_id\fR> +.B -I\fR, \fB--component-id \fR\fICOMP_ID\fR The numerical unique component ID to identify a component to be modified. .TP -.BR -N "[\fImirror_count\fR], " --mirror-count=" [\fImirror_count\fR] +.BR -N, \fB--mirror-count \fR[\fIMIRROR_COUNT\fR] Create a file with -.I mirror_count +.I MIRROR_COUNT identical replicas on the file or directory. The -.I mirror_count +.I MIRROR_COUNT argument is optional and defaults to 1 if it's not specified; if specified, it must follow the .B -N @@ -435,11 +436,11 @@ The \fISTRIPE_OPTIONS\fR specify the specific layout for the mirror. It can be a plain layout with specific striping pattern or a composite layout. If not specified, the stripe options are inherited from the previous component. If there is no previous component, the -.I stripe_count +.I STRIPE_COUNT and -.I stripe_size +.I STRIPE_SIZE options are inherited from filesystem-wide default values, and OST -.I pool_name +.I POOL_NAME will be inherited from the parent directory. .br Multiple diff --git a/lustre/utils/lfs.c b/lustre/utils/lfs.c index 42e03b0..c0dbbc9 100644 --- a/lustre/utils/lfs.c +++ b/lustre/utils/lfs.c @@ -209,16 +209,30 @@ static inline int lfs_mirror_delete(int argc, char **argv) " [--stripe-size|-S STRIPE_SIZE]\n" \ " [--yaml|-y YAML_TEMPLATE_FILE]\n" +/* XXX: A temporary solution for transition to help text update */ +#define SSM_CMD_COMMON_1(cmd) \ + "usage: "cmd" [--component-add|--component-del|--delete|-d]\n" \ + " [--comp-set --comp-id|-I COMP_ID|--comp-flags=COMP_FLAGS]\n" \ + " [--component-end|-E END_OFFSET]\n" \ + " [--copy=SOURCE_LAYOUT_FILE]|--yaml|-y YAML_TEMPLATE_FILE]\n" \ + " [--extension-size|--ext-size|-z EXT_SIZE]\n" \ + " [--help|-h]\n" \ + " [--foreign=FOREIGN_TYPE --xattr|-x LAYOUT]\n" \ + " [--layout|-L PATTERN] [--mode FILE_MODE]\n" \ + " [--mirror-count|-N[MIRROR_COUNT]]\n" \ + " [--ost|-o OST_INDEX[,OST_INDEX,...]]\n" \ + " [--overstripe-count|-C STRIPE_COUNT]\n" \ + " [--pool|-p POOL_NAME]\n" \ + " [--stripe-count|-c STRIPE_COUNT]\n" \ + " [--stripe-index|-i START_OST_IDX]\n" \ + " [--stripe-size|-S STRIPE_SIZE]\n" \ + " FILENAME|DIRECTORY\n" + #define MIRROR_EXTEND_USAGE \ " {--mirror-count|-N[MIRROR_COUNT]}\n" \ " [SETSTRIPE_OPTIONS|-f|--file VICTIM_FILE]\n" \ " [--no-verify]\n" -#define SETSTRIPE_USAGE \ - SSM_CMD_COMMON("setstripe") \ - MIRROR_EXTEND_USAGE \ - " DIRECTORY|FILENAME\n" - #define MIGRATE_USAGE \ SSM_CMD_COMMON("migrate ") \ " [--block|-b] [--non-block|-n]\n" \ @@ -315,43 +329,13 @@ command_t pcc_cmdlist[] = { /* all available commands */ command_t cmdlist[] = { {"setstripe", lfs_setstripe, 0, - "To create a file with specified striping/composite layout, or\n" - "create/replace the default layout on an existing directory:\n" - SSM_CMD_COMMON("setstripe") - " [--mode MODE]\n" - " \n" - " or\n" - "To add component(s) to an existing composite file:\n" - SSM_CMD_COMMON("setstripe --component-add") - "To totally delete the default striping from an existing directory:\n" - "usage: setstripe [--delete|-d] \n" - " or\n" - "To create a mirrored file or set s default mirror layout on a directory:\n" - "usage: setstripe {--mirror-count|-N}[MIRROR_COUNT] [SETSTRIPE_OPTIONS] \n" - " or\n" - "To delete the last component(s) from an existing composite file\n" - "(note that this will also delete any data in those components):\n" - "usage: setstripe --component-del [--component-id|-I COMP_ID]\n" - " [--component-flags|-F COMP_FLAGS]\n" - " \n" - "\tCOMP_ID: Unique component ID to delete\n" - "\tCOMP_FLAGS: 'init' indicating all instantiated components\n" - "\t '^init' indicating all uninstantiated components\n" - "\t-I and -F cannot be specified at the same time\n" - " or\n" - "To set or clear flags on a specific component\n" - "(note that this command can only be applied to mirrored files:\n" - "usage: setstripe --comp-set {-I COMP_ID|--comp-flags=COMP_FLAGS}\n" - " \n" - " or\n" - "To create a file with a foreign (free format) layout:\n" - "usage: setstripe --foreign[=FOREIGN_TYPE]\n" - " --xattr|-x LAYOUT_STRING [--flags HEX]\n" - " [--mode MODE] \n"}, + "Create a file with specified striping/composite layout, or\n" + "set the default layout on an existing directory.\n" + SSM_CMD_COMMON_1("setstripe")}, {"getstripe", lfs_getstripe, 0, - "To list the layout pattern for a given file or files in a\n" + "List the layout pattern for a given file or files in a\n" "directory or recursively for all files in a directory tree.\n" - "usage: getstripe [--ost|-O UUID] [--quiet|-q] [--verbose|-v]\n" + "Usage: getstripe [--ost|-O OST_NAME] [--quiet|-q] [--verbose|-v]\n" " [--stripe-count|-c] [--stripe-index|-i] [--fid|-F]\n" " [--pool|-p] [--stripe-size|-S] [--directory|-d]\n" " [--mdt-index|-m] [--recursive|-r] [--raw|-R]\n" @@ -361,12 +345,12 @@ command_t cmdlist[] = { " [--component-flags[=COMP_FLAGS]]\n" " [--component-count]\n" " [--extension-size|--ext-size|-z]\n" - " [--component-start[=[+-]COMP_START]]\n" - " [--component-end[=[+-]COMP_END]|-E[[+-]comp_end]]\n" - " [[!] --mirror-index=[+-]INDEX |\n" + " [--component-start[=[+-]START_OFFSET]]\n" + " [--component-end|-E[[+-]END_OFFSET]]\n" + " [[!] --mirror-index=[+-]MIRROR_INDEX |\n" " [!] --mirror-id=[+-]MIRROR_ID] [--mirror-count|-N]\n" " [--no-follow]\n" - " ..."}, + " FILENAME|DIRECTORY"}, {"setdirstripe", lfs_setdirstripe, 0, "Create striped directory on specified MDT, same as mkdir.\n" "May be restricted to root or group users, depending on settings.\n" -- 1.8.3.1