Details

    • Type: Bug
    • Status: Open
    • Priority: Minor
    • Resolution: Unresolved
    • Affects Version/s: Lustre 2.6.0
    • Fix Version/s: None
    • Labels:
    • Severity:
      3
    • Rank (Obsolete):
      14249

      Description

      lfs usability needs attention.

      Command output

      1. Structured command output should be clear, unambiguous, minimalist, and easily parsed (by awk).

      Errors and Error Messages

      1. Except for unrecognized/bad command/option usage, error messages must be one line only and prefixed by 'lfs COMMAND: '. Text that follows 'lfs COMMAND: ' should start with a lowercase word like cannot. A period should not be used at the end of an error message.
      2. There must be a strong reason not to use an error message of the form
        lfs COMMAND: cannot VERB 'ARG': STRERROR
        
        
        
        
        
        
      1. Commands that take multiple (file) arguments should continue on error but report the error. Note that using touch the second file is not created but the third is. This is unix convention and should be followed by lfs.  A patch has been submitted at https://review.whamcloud.com/#/c/30663/.
      # cd /mnt/lustre
      # ls
      # touch f0 d1/f1 f2
      touch: cannot touch `d1/f1': No such file or directory
      # echo $?
      1
      # ls
      f0  f2
      #
      # rm f0 f2
      # lfs setstripe -c4 f0 d1/f1 f2
      unable to open 'd1/f1': No such file or directory (2)
      error: setstripe: create stripe file 'd1/f1' failed
      # echo $?
      2
      # ls
      f0
      
      
      
      
      
      

      Commands and Options

      1. Passing unrecognized commands and options should generate a two line error message. We shouldn't "spam the console" since these are usually just simple typos and printing a long error message may scroll away something the user cared about.
        # lfs setstrip
        Try interactive use without arguments or use one of:
        "setstripe"
        "getstripe"
        "setdirstripe"
        "getdirstripe"
        "mkdir"
        "rm_entry"
        "pool_list"
        "find"
        "check"
        "join"
        "osts"
        "mdts"
        "df"
        "getname"
        "quotacheck"
        "quotaon"
        "quotaoff"
        "setquota"
        "quota"
        "flushctx"
        "lsetfacl"
        "lgetfacl"
        "rsetfacl"
        "rgetfacl"
        "cp"
        "ls"
        "changelog"
        "changelog_clear"
        "fid2path"
        "path2fid"
        "data_version"
        "hsm_state"
        "hsm_set"
        "hsm_clear"
        "hsm_action"
        "hsm_archive"
        "hsm_restore"
        "hsm_release"
        "hsm_remove"
        "hsm_cancel"
        "swap_layouts"
        "migrate"
        "mv"
        "help"
        "exit"
        "quit"
        as argument.
        
        

        Should be:

        # lfs setstrip
        lfs: unrecognized command 'setstrip'
        Try 'lfs --help' for more information
        
        

        A patch has been submitted at https://review.whamcloud.com/#/c/28569/.

      1. 'lfs --help' should generate a short help message, not a list of subcommands.
        # lfs --help
        Try interactive use without arguments or use one of:
        "setstripe"
        "getstripe"
        "setdirstripe"
        "getdirstripe"
        "mkdir"
        "rm_entry"
        "pool_list"
        ...
        
        
        
        
        
        

        Should be:

        usage: lfs COMMAND [OPTIONS]... ARGS
        ...
        
        
        
        
        
        

        Note also that 'lfs setstrip -c11 xyzzy' prints nothing to stderr.

      1. 'lfs help COMMAND' should print help to stdout and not to stderr.
        Wrong:
        # lfs help setstripe > /dev/null
        setstripe: Create a new file with a specific striping pattern or
        set the default striping pattern on an existing directory or
        delete the default striping pattern from an existing directory
        usage: setstripe -d <directory>   (to delete default striping)
         or
        usage: setstripe [--stripe-count|-c <stripe_count>]
                         [--stripe-index|-i <start_ost_idx>]
                         [--stripe-size|-S <stripe_size>]
                         [--pool|-p <pool_name>]
                         [--block|-b] <directory|filename>
        ...
        
        
        
        
        
        

        A patch has been submitted at https://review.whamcloud.com/#/c/28569/.

      1. 'lfs help COMMAND' should be equivalent to 'lfs COMMAND --help'
        Wrong:
        # lfs setdirstripe --help
        setdirstripe: unrecognized option '--help'
        error: setdirstripe: option '--help' unrecognized
        To create a remote directory on a specified MDT.
        usage: setdirstripe <--count|-c stripe_count>
        [--index|-i mdt_index] [--hash-type|-t hash_type]
        [--default_stripe|-D ] <dir>
        	stripe_count: stripe count of the striped directory
        	mdt_index:	MDT index of first stripe
        	hash_type:	hash type of the striped directory. Hash types:
        	-t fnv_1a_64 FNV-1a hash algorithm(default)
        	-t all_char  sum of characters % MDT_COUNT. (not recommended)
        	default_stripe: set default dirstripe of the directory
        
        
        
        
        
        
      1. Options must use dashes (instead of underscores) to separate words.
        Wrong: --stripecount
        Wrong: --stripe_count
        Right: --stripe-count
        
        
        
        
        
        

        Existing options that use underscores should be accepted in future versions of lfs. But s/_/-/ equivalents should be added and help messages and manpages should be updated to use these forms.

      1. Paths (and other string argumenst) used in error messages must be enclosed in single quotes.
      2. Help messages should look more unixy.
        # lfs help setstripe
        setstripe: Create a new file with a specific striping pattern or
        set the default striping pattern on an existing directory or
        delete the default striping pattern from an existing directory
        usage: setstripe -d <directory>   (to delete default striping)
         or
        usage: setstripe [--stripe-count|-c <stripe_count>]
                         [--stripe-index|-i <start_ost_idx>]
                         [--stripe-size|-S <stripe_size>]
                         [--pool|-p <pool_name>]
                         [--block|-b] <directory|filename>
        	stripe_size:  Number of bytes on each OST (0 filesystem default)
        	              Can be specified with k, m or g (in KB, MB and GB
        	              respectively)
        	start_ost_idx: OST index of first stripe (-1 default)
        	stripe_count: Number of OSTs to stripe over (0 default, -1 all)
        	pool_name:    Name of OST pool to use (default none)
        	block:	 Block file access during data migration
        
        
        
        
        
        
      1. Error messages should be groomed.
        Wrong:
        unable to open 'd1/f1': No such file or directory (2)
        error: setstripe: create stripe file 'd1/f1' failed
        Right:
        lfs setstripe: cannot open 'd1/f1': No such file or directory
        
        
        
        
        
        
      1. Help messages (and manpages) should be checked for correctness and completeness.
      2. Help messages should use conventional unix style. DIR, FILE, --mode=MODE instead of <dir>, <file>, --mode=<mode>.
      3. Commands that accept multiple files should advertise this by using FILE... in help messages.
      4. 'lfs --usage' and 'lfs --version' should be supported.
      5. 'lfs --list-commands' should be supported.
        A patch has already landed.

      These and other standards for usability should be expanded, refined, made available to the development community, and used to validate additions/changes to lfs and other command line utilities.

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                sguminsx Steve Guminski (Inactive)
                Reporter:
                jhammond John Hammond
              • Votes:
                0 Vote for this issue
                Watchers:
                10 Start watching this issue

                Dates

                • Created:
                  Updated: