Uploaded image for project: 'Lustre'
  1. Lustre
  2. LU-17370

simplify 'lfs --help' text output

    XMLWordPrintable

Details

    • Improvement
    • Resolution: Fixed
    • Minor
    • Lustre 2.16.0
    • None
    • None
    • 3
    • 9223372036854775807

    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.

      Attachments

        Issue Links

          Activity

            People

              aioffe Alexandre Ioffe
              adilger Andreas Dilger
              Votes:
              0 Vote for this issue
              Watchers:
              4 Start watching this issue

              Dates

                Created:
                Updated:
                Resolved: