[LU-17370] simplify 'lfs --help' text output

• Type: Improvement
• Resolution: Fixed
• Priority: Minor
• Fix Version/s: Lustre 2.16.0
• Severity: 3
• Assignee: Alexandre Ioffe
• Reporter: Andreas Dilger

Description

Currently, the usage and --help text output for "lfs COMMAND" is inconsistent and can produce a lot of output. This often includes detailed descriptions of the options, their parameters, and different usage modes. For example, if a bad parameter is given to "lfs setstripe" it will generate 104 lines of output:

$ lfs setstripe --bad foo
lfs setstripe setstripe: unrecognized option '--bad'
To create a file with specified striping/composite layout, or
create/replace the default layout on an existing directory:
usage: setstripe [--component-end|-E <comp_end>]
                 [--stripe-count|-c <stripe_count>]
                 [--overstripe-count|-C <stripe_count>]
                 [--stripe-index|-i <start_ost_idx>]
                 [--stripe-size|-S <stripe_size>]
                 [--compress|-Z <compr_type>[:<compr_level>]
                 [--compress-type=<compress_type>
                 [--compress-level=<compress_level>
                 [--compress-chunk=<chunk_size>]
                 [--extension-size|--ext-size|-z]
                 [--layout|-L <pattern>]
                 [--mirror-count|-N[mirror_count]]
                 [--ost|-o <ost_indices>]
                 [--pool|-p <pool_name>]
                 [--yaml|-y <yaml_template_file>]
                 [--copy=<lustre_src>]
                 [--mode <mode>]
                 <directory|filename>
 or
To add component(s) to an existing composite file:
usage: setstripe --component-add [--component-end|-E <comp_end>]
                 [--stripe-count|-c <stripe_count>]
                 [--overstripe-count|-C <stripe_count>]
                 [--stripe-index|-i <start_ost_idx>]
                 [--stripe-size|-S <stripe_size>]
                 [--compress|-Z <compr_type>[:<compr_level>]
                 [--compress-type=<compress_type>
                 [--compress-level=<compress_level>
                 [--compress-chunk=<chunk_size>]
                 [--extension-size|--ext-size|-z]
                 [--layout|-L <pattern>]
                 [--mirror-count|-N[mirror_count]]
                 [--ost|-o <ost_indices>]
                 [--pool|-p <pool_name>]
                 [--yaml|-y <yaml_template_file>]
                 [--copy=<lustre_src>]
	stripe_count: Number of OSTs to stripe on (0=fs default, -1 all)
	              Using -C instead of -c allows overstriping, which
	              will place more than one stripe per OST if
	              stripe_count is greater than the number of OSTs.
	start_ost_idx: OST index of first stripe (-1=default round robin)
	stripe_size:  Number of bytes on each OST (0=fs default)
	              Optional K, M, or G suffix (for KB, MB, GB
	              respectively).  Must be a multiple of 64KiB.
	compress:
	              Compression algorithm <type> and compress <level>.
	              The compress level showed in getstripe could be 
	              not exactly the one input here.
	compress-chunk:
	              Compression data chunk size in KiB, the value
	              will be adjusted to power-of-two multiples of the
	              base 64KiB.
	extension_size:
	              Number of bytes the previous component is extended
	              each time. Optional K, M, or G suffix (for KB,
	              MB, GB respectively)
	pool_name:    Name of OST pool to use (default none)
	layout:       stripe pattern type: raid0, mdt (default raid0)
	ost_indices:  List of OST indices, can be repeated multiple times
	              Indices be specified in a format of:
	                -o <ost_1>,<ost_i>-<ost_j>,<ost_n>
	              Or:
	                -o <ost_1> -o <ost_i>-<ost_j> -o <ost_n>
	              If --pool is set with --ost then the OSTs
	              must be the members of the pool.
	comp_end:     Extent end of component, start after previous end.
	              Optional K, M, or G suffix (for KiB, MiB, GiB), or
	              -1 or 'eof' for max file size). Must be a multiple
	              of stripe_size and a multiple of 64KiB.
	yaml_template_file:
	              YAML layout template file, can't be used with -c,
	              -i, -S, -p, -o, or -E arguments.
	lustre_src:   Lustre file/dir whose layout info is used to set
	              another lustre file or directory, can't used with
	              -c, -i, -S, -p, -o, or -E arguments.
To totally delete the default striping from an existing directory:
usage: setstripe [--delete|-d] <directory>
 or
To create a mirrored file or set s default mirror layout on a directory:
usage: setstripe {--mirror-count|-N}[mirror_count] [SETSTRIPE_OPTIONS] <directory|filename>
 or
To delete the last component(s) from an existing composite file
(note that this will also delete any data in those components):
usage: setstripe --component-del [--component-id|-I <comp_id>]
                               [--component-flags|-F <comp_flags>]
                               <filename>
	comp_id:     Unique component ID to delete
	comp_flags:  'init' indicating all instantiated components
	             '^init' indicating all uninstantiated components
	-I and -F cannot be specified at the same time
 or
To set or clear flags on a specific component
(note that this command can only be applied to mirrored files:
usage: setstripe --comp-set {-I comp_id|--comp-flags=comp_flags}
                            <filename>
 or
To create a file with a foreign (free format) layout:
usage: setstripe --foreign[=<foreign_type>]
                 --xattr|-x <layout_string> [--flags <hex>]
                 [--mode <mode>] <filename>

Unfortunately, this large number of lines will scroll the important error message off the top of the terminal screen and show only relatively useless information about obscure usage options at the end.

The "lfs" commands usage/help text should be changed to print a single line description of the command and a list of all command-line options. This will keep the important usage error message visible on the screen, and makes the rest of the text much more readable.

Also, the bash_completion functionality (LU-13225) runs the command with "help" to generate a list of short/long options for tab completion (e.g. "lfs setstripe --<TAB><TAB>") so having the command-line options shown properly for all commands (in particular "lfs mirror" and "lfs migrate") instead of by reference (e.g. "SETSTRIPE_OPTIONS") simplifies the implementation of these tools.

Issue Links

• is related to: LU-5170 lfs usability
• is related to: LU-13225 add bash completion for lfs
• is related to: LU-930 Update or improvement to a Lustre man page, documentation, or messages

Comments

[Peter Jones]

Merged for 2.16

[Gerrit Updater]

"Oleg Drokin <[e-mail]>" merged in patch https://review.whamcloud.com/c/fs/lustre-release/+/53719/
Subject: LU-17370 utils: simplify lfs-mirror-extend help text
Project: fs/lustre-release
Branch: master
Current Patch Set:
Commit: bac650ff56f95cc81d1ce6571ef78cbb065b6f2e

[Gerrit Updater]

"Alexandre Ioffe <[e-mail]>" uploaded a new patch: https://review.whamcloud.com/c/fs/lustre-release/+/53719
Subject: LU-17370 utils: simplify lfs-mirror-extend help text
Project: fs/lustre-release
Branch: master
Current Patch Set: 1
Commit: 2a71d159d4ac98a3252f12796b8688bfa4d6df50

[Gerrit Updater]

"Oleg Drokin <[e-mail]>" merged in patch https://review.whamcloud.com/c/fs/lustre-release/+/53564/
Subject: LU-17370 utils: simplify lfs help text
Project: fs/lustre-release
Branch: master
Current Patch Set:
Commit: b6deb420a81f86a70312ae1de507066a89f92268

[Gerrit Updater]

"Alexandre Ioffe <[e-mail]>" uploaded a new patch: https://review.whamcloud.com/c/fs/lustre-release/+/53583
Subject: LU-17370 utils: simplify lfs help text
Project: fs/lustre-release
Branch: master
Current Patch Set: 1
Commit: afd12210a559467eca417d732e17ccbcbecf2cb9

[Gerrit Updater]

"Alexandre Ioffe <[e-mail]>" uploaded a new patch: https://review.whamcloud.com/c/fs/lustre-release/+/53564
Subject: LU-17370 utils: simplify lfs help text
Project: fs/lustre-release
Branch: master
Current Patch Set: 1
Commit: 6c3dae58eddc2e3c7caf35599733b2e59ebeb657

[Andreas Dilger]

It would be useful to have separate patches to clean up the usage messages for other sub-commands, such as "lfs getstripe", "lfs setdirstripe", "lfs find", etc. to remove excess descriptive text, and to capitalize the arguments for each option.

Please confirm that argument descriptions that are removed from the "lfs SUBCOMMAND" usage message are included in the corresponding "lfs-SUBCOMMAND.1" man page, if not already present.

[Andreas Dilger]

For "lfs setstripe", I think a reasonable output would be:

Create a file with specified striping/composite layout, or
set the default layout on an existing directory:
usage: setstripe [--component-add|--component-del|--delete|-d]
                 [--component-set --component-id|-I COMP_ID|--component-flags=COMP_FLAGS]
                 [--mirror-count|-N[MIRROR_COUNT]] [--component-end|-E COMP_END]
                 [--stripe-count|-c STRIPE_COUNT|--overstripe-count|-C STRIPE_COUNT]
                 [--stripe-index|-i START_OST_IDX] [--stripe-size|-S STRIPE_SIZE]
                 [--compress|-Z COMPR_TYPE[:COMPR_LEVEL]]
                 [--compress-type=COMPR_TYPE] [--compress-level=COMPR_LEVEL]
                 [--compress-chunk=CHUNK_SIZE]
                 [--extension-size|--ext-size|-z EXT_SIZE] 
                 [--foreign=FOREIGN_TYPE --xattr|-x LAYOUT]
                 [--layout|-L PATTERN] [--mode FILE_MODE]
                 [--ost|-o OST_INDEX,[OST_INDEX,...]] [--pool|-p POOL_NAME]
                 [--copy=SOURCE_LAYOUT_FILE|--yaml|-y YAML_TEMPLATE_FILE]
                 FILENAME|DIRECTORY

All of the variable arguments should be displayed in UPPERCASE instead of in angle brackets (i.e. use "STRIPE_COUNT" instead of "<stripe_count").

The full set of command-line options should also be printed for "lfs mirror create/extend" and "lfs migrate", and remove the special case for mirror and migrate in lustre/scripts/bash-completion/lustre.

This should be done by modifying the SSM_CMD_COMMON() macro to print all of the common options, and related macros MIRROR_EXTEND_USAGE and MIGRATE_USAGE to print options specific to those commands.