From: Alexandre Ioffe Date: Fri, 5 Jan 2024 04:54:11 +0000 (-0800) Subject: LU-17370 utils: simplify lfs-mirror-extend help text X-Git-Url: https://git.whamcloud.com/?a=commitdiff_plain;h=66a53793e286ad113df97db57cc5137c8898f256;p=fs%2Flustre-release.git LU-17370 utils: simplify lfs-mirror-extend help text Add list of lfs setstripe command line options to help text of lfs mirror extend. Simplify syntax of lfs mirror extend help text. Update corresponding lfs-mirror-extend man page. On man pages make left side adjustment and disable hyphenation: '.nh', '.ad l' to prevent hyphenation of keywords Lustre-change: https://review.whamcloud.com/53719 Lustre-commit: TBD (from 2a71d159d4ac98a3252f12796b8688bfa4d6df50) Signed-off-by: Alexandre Ioffe Test-Parameters: trivial Change-Id: I6cffcdb9651062e169f53868827646b876a82cb5 Reviewed-on: https://review.whamcloud.com/c/ex/lustre-release/+/53598 Reviewed-by: Andreas Dilger Tested-by: jenkins Tested-by: Maloo --- diff --git a/lustre/doc/lfs-mirror-extend.1 b/lustre/doc/lfs-mirror-extend.1 index 5f51bb6..f3e67a7 100644 --- a/lustre/doc/lfs-mirror-extend.1 +++ b/lustre/doc/lfs-mirror-extend.1 @@ -2,42 +2,43 @@ .SH NAME lfs-mirror-extend \- add mirror(s) to an existing file .SH SYNOPSIS +.nh +.ad l .B lfs mirror extend [\fB\-\-no\-verify\fR] -<\fB\-\-mirror\-count\fR|\fB\-N\fR[\fImirror_count\fR]> -<\fB\-\-bandwidth\-limit=\fR|\fB\-W\fR[\fIbandwidth_limit\fR]> -[\fB\-\-stats\fR] -<\fB\-\-stats\-interval\fR=\fIinterval_in_sec\fR> -[\fIsetstripe_options\fR|\fB\-f\fR <\fIvictim_file\fR>] ... -<\fIfilename\fR> +\fB\-\-mirror\-count\fR|\fB\-N\fR[\fIMIRROR_COUNT\fR] +[\fB\-\-bandwidth\-limit\fR|\fB\-W\fR \fIBANDWIDTH\fR] +[\fB\-\-stats\fR|\fB\-\-stats\-interval\fR=\fISTATS_INTERVAL\fR] +[\fISETSTRIPE_OPTIONS\fR|\fB\-f\fR \fIVICTIM_FILE\fR] +\fIFILENAME\fR ... .SH DESCRIPTION This command adds mirror(s) to an existing file specified by the path name -\fIfilename\fR. +\fIFILENAME\fR. .br -The file \fIfilename\fR can already be a mirrored file, or just a regular +The file \fIFILENAME\fR can already be a mirrored file, or just a regular non-mirrored file. If it's a non-mirrored file, then the command will convert it to a mirrored file. .br The \fB\-\-mirror\-count\fR|\fB\-N\fR option is required and indicates how many mirrors that have the same layout will be added. It can be repeated multiple -times to separate mirrors that have different layouts. The \fImirror_count\fR +times to separate mirrors that have different layouts. The \fIMIRROR_COUNT\fR argument is optional and defaults to 1 if it's not specified; if specified, it must follow the option without a space. .br -The \fIsetstripe_options\fR specify the specific layout for the mirror. It can +The \fISETSTRIPE_OPTIONS\fR specify the specific layout for the mirror. It can be a plain layout with specific striping pattern or a composite layout like Progressive File Layout (PFL), including specifying compression component (see \fBlfs-setstripe\fR(1)). -If \fIsetstripe_options\fR are not specified, +If \fISETSTRIPE_OPTIONS\fR are not specified, then the stripe options inherited from the previous component will be used. -If \fIvictim_file\fR exists, then the +If \fIVICTIM_FILE\fR exists, then the command will merge the layout from that file as a mirror added to the mirrored file. After the command is finished, the victim file will be -removed. The \fIsetstripe_options\fR cannot be specified with -\fB\-f\fR <\fIvictim_file\fR> option in one command line. +removed. The \fISETSTRIPE_OPTIONS\fR cannot be specified with +\fB\-f\fR \fIVICTIM_FILE\fR option in one command line. .br -If \fIvictim_file\fR is specified, the utility will verify that the file contents -from \fIvictim_file\fR are the same as \fIfilename\fR. Otherwise the command +If \fIVICTIM_FILE\fR is specified, the utility will verify that the file contents +from \fIVICTIM_FILE\fR are the same as \fIFILENAME\fR. Otherwise the command will return failure. However, option \fB\-\-no\-verify\fR can be used to override this verification. The option can save siginificant time on file comparison if the file size is large, but use it only when the file contents @@ -46,23 +47,22 @@ are known to be the same. If no option is specified, then the command will return an error. .SH OPTIONS .TP -.BR \-\-mirror\-count\fR|\fB\-N\fR[\fImirror_count\fR] +.BR \-\-mirror\-count\fR|\fB\-N\fR[\fIMIRROR_COUNT\fR] The number of mirrors that have the same layout to be added. The option can be repeated multiple times to separate mirrors that have different layouts. The -\fImirror_count\fR argument is optional and defaults to 1 if it's not specified; +\fIMIRROR_COUNT\fR argument is optional and defaults to 1 if it's not specified; if specified, it must follow the option without a space. .TP -.I setstripe_options +.I SETSTRIPE_OPTIONS The layout of one mirror. The options are the same as those for -\fBlfs-setstripe\fR(1) command, including options for setting compression -component. -If \fIsetstripe_options\fR are not specified, then the stripe options inherited +\fBlfs-setstripe\fR(1) command, including options for setting compression component. +If \fISETSTRIPE_OPTIONS\fR are not specified, then the stripe options inherited from the previous component will be used. This option cannot be specified with -\fB\-f\fR <\fIvictim_file\fR> option. +\fB\-f\fR \fIVICTIM_FILE\fR option. .TP -.BR \-f\fR\ <\fIvictim_file\fR> -The layout of \fIvictim_file\fR will be merged as a mirror added to the -mirrored file. This option cannot be specified with \fIsetstripe_options\fR +.BR \-f\fR\ \fIVICTIM_FILE\fR +The layout of \fIVICTIM_FILE\fR will be merged as a mirror added to the +mirrored file. This option cannot be specified with \fISETSTRIPE_OPTIONS\fR option. .TP .BR \-\-no\-verify @@ -72,12 +72,12 @@ the victim file(s) contains the same data as the original mirrored file. .BR \-\-stats This option enables progress updates every 5 seconds, in YAML format. .TP -.BR \-\-stats-interval=\fIstats_interval -This option enables progress updates every \fIstats_interval\fR seconds, in YAML format. +.BR \-\-stats-interval=\fISTATS_INTERVAL +This option enables progress updates every \fISTATS_INTERVAL\fR seconds, in YAML format. .TP -.BR \-\-bandwidth\-limit\fR|\fB\-W\fR\fIbandwidth_limit\fR +.BR \-\-bandwidth\-limit\fR|\fB\-W\fR\fIBANDWIDTH\fR This option enables throttling so that mirror extending writes no more than -\fIbandwidth_limit\fR bytes a second. An optional suffix can be used to +\fIBANDWIDTH\fR bytes a second. An optional suffix can be used to specify the units in .BR K ilobytes, .BR M egabytes diff --git a/lustre/utils/lfs.c b/lustre/utils/lfs.c index d0338f3..84d2baf 100644 --- a/lustre/utils/lfs.c +++ b/lustre/utils/lfs.c @@ -199,83 +199,27 @@ static inline int lfs_mirror_delete(int argc, char **argv) return lfs_setstripe_internal(argc, argv, SO_MIRROR_DELETE); } -/* Setstripe and migrate share mostly the same parameters */ -#define SSM_CMD_COMMON(cmd) \ - "usage: "cmd" [--component-end|-E ]\n" \ - " [--stripe-count|-c ]\n" \ - " [--overstripe-count|-C ]\n" \ - " [--stripe-index|-i ]\n" \ - " [--stripe-size|-S ]\n" \ - " [--compress|-Z [:]\n"\ - " [--compress-type=\n" \ - " [--compress-level=\n" \ - " [--compress-chunk=]\n" \ - " [--extension-size|--ext-size|-z]\n" \ - " [--layout|-L ]\n" \ - " [--mirror-count|-N[mirror_count]]\n" \ - " [--ost|-o ]\n" \ - " [--pool|-p ]\n" \ - " [--yaml|-y ]\n" \ - " [--copy=]\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" \ - " [--mirror-count|-N[MIRROR_COUNT]] [--component-end|-E END_OFFSET]\n" \ - " [--stripe-count|-c STRIPE_COUNT|--overstripe-count|-C STRIPE_COUNT]\n" \ - " [--stripe-index|-i START_OST_IDX] [--stripe-size|-S STRIPE_SIZE]\n" \ - " [--compress|-Z COMPR_TYPE[:COMPR_LEVEL]]\n" \ - " [--compress-type=COMPR_TYPE] [--compress-level=COMPR_LEVEL]\n" \ - " [--compress-chunk=CHUNK_SIZE]\n" \ - " [--extension-size|--ext-size|-z EXT_SIZE]\n" \ - " [--foreign=FOREIGN_TYPE --xattr|-x LAYOUT]\n" \ - " [--layout|-L PATTERN] [--mode FILE_MODE]\n" \ - " [--ost|-o OST_INDEX[,OST_INDEX,...]] [--pool|-p POOL_NAME]\n" \ - " [--copy=SOURCE_LAYOUT_FILE|--yaml|-y YAML_TEMPLATE_FILE]\n" \ - " FILENAME|DIRECTORY\n" - -#define SSM_HELP_COMMON \ - "\tstripe_count: Number of OSTs to stripe on (0=fs default, -1 all)\n" \ - "\t Using -C instead of -c allows overstriping, which\n" \ - "\t will place more than one stripe per OST if\n" \ - "\t stripe_count is greater than the number of OSTs.\n" \ - "\tstart_ost_idx: OST index of first stripe (-1=default round robin)\n"\ - "\tstripe_size: Number of bytes on each OST (0=fs default)\n" \ - "\t Optional K, M, or G suffix (for KB, MB, GB\n" \ - "\t respectively). Must be a multiple of 64KiB.\n" \ - "\tcompress:\n" \ - "\t Compression algorithm and compress .\n" \ - "\t The compress level showed in getstripe could be \n" \ - "\t not exactly the one input here.\n" \ - "\tcompress-chunk:\n" \ - "\t Compression data chunk size in KiB, the value\n" \ - "\t will be adjusted to power-of-two multiples of the\n"\ - "\t base 64KiB.\n" \ - "\textension_size:\n" \ - "\t Number of bytes the previous component is extended\n" \ - "\t each time. Optional K, M, or G suffix (for KB,\n" \ - "\t MB, GB respectively)\n" \ - "\tpool_name: Name of OST pool to use (default none)\n" \ - "\tlayout: stripe pattern type: raid0, mdt (default raid0)\n" \ - "\tost_indices: List of OST indices, can be repeated multiple times\n"\ - "\t Indices be specified in a format of:\n" \ - "\t -o ,-,\n" \ - "\t Or:\n" \ - "\t -o -o - -o \n" \ - "\t If --pool is set with --ost then the OSTs\n" \ - "\t must be the members of the pool.\n" \ - "\tcomp_end: Extent end of component, start after previous end.\n" \ - "\t Optional K, M, or G suffix (for KiB, MiB, GiB), or\n" \ - "\t -1 or 'eof' for max file size). Must be a multiple\n" \ - "\t of stripe_size and a multiple of 64KiB.\n" \ - "\tyaml_template_file:\n" \ - "\t YAML layout template file, can't be used with -c,\n" \ - "\t -i, -S, -p, -o, or -E arguments.\n" \ - "\tlustre_src: Lustre file/dir whose layout info is used to set\n" \ - "\t another lustre file or directory, can't used with\n" \ - "\t -c, -i, -S, -p, -o, or -E arguments.\n" +#define SSM_SETSTRIPE_OPT \ + "[--component-add|--component-del|--delete|-d]\n" \ + "\t\t[--comp-set --comp-id|-I COMP_ID|--comp-flags=COMP_FLAGS]\n" \ + "\t\t[--component-end|-E END_OFFSET]\n" \ + "\t\t[--copy=SOURCE_LAYOUT_FILE]|--yaml|-y YAML_TEMPLATE_FILE]\n" \ + "\t\t[--extension-size|--ext-size|-z EXT_SIZE]\n" \ + "\t\t[--help|-h]\n" \ + "\t\t[--foreign=FOREIGN_TYPE --xattr|-x LAYOUT]\n" \ + "\t\t[--layout|-L PATTERN] [--mode FILE_MODE]\n" \ + "\t\t[--mirror-count|-N[MIRROR_COUNT]]\n" \ + "\t\t[--ost|-o OST_INDEX[,OST_INDEX,...]]\n" \ + "\t\t[--overstripe-count|-C STRIPE_COUNT]\n" \ + "\t\t[--pool|-p POOL_NAME]\n" \ + "\t\t[--stripe-count|-c STRIPE_COUNT]\n" \ + "\t\t[--stripe-index|-i START_OST_IDX]\n" \ + "\t\t[--stripe-size|-S STRIPE_SIZE]\n" \ + "\t\t[--compress|-Z COMPR_TYPE[:COMPR_LEVEL]]\n" \ + "\t\t[--compress-type=COMPR_TYPE] [--compress-level=COMPR_LEVEL]\n" \ + "\t\t[--compress-chunk=CHUNK_SIZE]" +/* Setstripe and migrate share mostly the same parameters */ #define MIRROR_CREATE_HELP \ "\tmirror_count: Number of mirrors to be created with the upcoming\n" \ "\t setstripe layout options\n" \ @@ -290,31 +234,14 @@ static inline int lfs_mirror_delete(int argc, char **argv) "\tflags: set flags to the component of the current mirror.\n" \ "\t Only \"prefer\" flag is supported so far.\n" -#define MIRROR_EXTEND_HELP \ - MIRROR_CREATE_HELP \ - "\tvictim_file: The layout of victim_file will be split and used\n" \ - "\t as a mirror added to the mirrored file.\n" \ - "\tno-verify: This option indicates not to verify the mirror(s)\n" \ - "\t from victim file(s) in case the victim file(s)\n" \ - "\t contains the same data as the original mirrored\n" \ - "\t file.\n" - -#define MIRROR_EXTEND_USAGE \ - " {--mirror-count|-N[mirror_count]}\n" \ - " [SETSTRIPE_OPTIONS|-f|--file ]\n" \ - " [--no-verify]\n" - -#define MIGRATE_USAGE \ - SSM_CMD_COMMON("migrate ") \ - " [--block|-b] [--non-block|-n]\n" \ - " [--non-direct|-D] [--verbose|-v]\n" \ - " \n" \ - SSM_HELP_COMMON \ - "\n" \ - "\tblock: Block file access during data migration (default)\n" \ - "\tnon-block: Abort migrations if concurrent access is detected\n" \ - "\tnon-direct: Do not use direct I/O to copy file contents\n" \ - "\tverbose: Print each filename as it is migrated\n" \ + +#define SSM_CMD_COMMON(cmd) \ + "Usage: " cmd \ + " " SSM_SETSTRIPE_OPT "\n" + +#define SETSTRIPE_USAGE \ + SSM_CMD_COMMON("setstripe ") \ + "\t\tFILENAME|DIRECTORY\n" #define SETDIRSTRIPE_USAGE \ " [--mdt-count|-c stripe_count>\n" \ @@ -355,12 +282,13 @@ command_t mirror_cmdlist[] = { }, { .pc_name = "extend", .pc_func = lfs_mirror_extend, .pc_help = "Extend a mirrored file.\n" - "usage: lfs mirror extend " - "{--mirror-count|-N[MIRROR_COUNT]} [--no-verify]|\n" - "\t\t--stats|--stats-interval=|\n" - "\t\t--W |--bandwidth-limit=\n" - "\t\t[SETSTRIPE_OPTIONS|-f VICTIM_FILE] ... FILENAME ...\n" - MIRROR_EXTEND_HELP }, + "Usage: lfs mirror extend " + "--mirror-count|-N[MIRROR_COUNT] [--no-verify]|\n" + "\t\t[--stats|--stats-interval=STATS_INTERVAL]|\n" + "\t\t[--bandwidth-limit|--W BANDWIDTH]\n" + "\t\t[[-f VICTIM_FILE] |\n" + "\t\t" SSM_SETSTRIPE_OPT "]" + " FILENAME ...\n" }, { .pc_name = "split", .pc_func = lfs_mirror_split, .pc_help = "Split a mirrored file.\n" "usage: lfs mirror split <--mirror-id |\n" @@ -461,7 +389,7 @@ command_t cmdlist[] = { {"setstripe", lfs_setstripe, 0, "Create a file with specified striping/composite layout, or\n" "set the default layout on an existing directory.\n" - SSM_CMD_COMMON_1("setstripe")}, + SETSTRIPE_USAGE}, {"getstripe", lfs_getstripe, 0, "List the layout pattern for a given file or files in a\n" "directory or recursively for all files in a directory tree.\n"