rbd: import doesn't require image-spec arg, ditto for export and path

Mark those as such in help and clarify what image-spec defaults to.

Related, all command args in our man page are enclosed into brackets.
I suppose the reason is that they are optional in the sense that you
can have commands like

    $ rbd clone --pool a --image b --snap -c --dest-pool d --dest e

with no args.  Given that we are trying to push people towards

    $ rbd clone a/b@c d/e

undo that so that real optional arguments can be marked optional.
While at it, add synopsis for each command and use backticks for
denoting commands more consistently.

Signed-off-by: Ilya Dryomov <idryomov@gmail.com>

diff --git a/doc/man/8/rbd.rst b/doc/man/8/rbd.rst
index 1f3964fb8f73332378fc6ff79be9427960e8e631..3e11875db9d55139204a12293723be4125654762 100644 (file)
--- a/doc/man/8/rbd.rst
+++ b/doc/man/8/rbd.rst
@@ -48,7 +48,7 @@ Options
 Parameters
 ==========
 
-.. option:: --image-format format
+.. option:: --image-format format-id
 
    Specifies which object layout to use. The default is 1.
 
@@ -98,7 +98,7 @@ Parameters
    to use with the map command.  If not specified, the default keyring
    locations will be searched.
 
-.. option:: --shared tag
+.. option:: --shared lock-tag
 
    Option for `lock add` that allows multiple clients to lock the
    same image if they use the same tag. The tag is an arbitrary
@@ -125,18 +125,18 @@ Parameters
 
    Map the image read-only.  Equivalent to -o ro.
 
-.. option:: --image-feature feature
+.. option:: --image-feature feature-name
 
    Specifies which RBD format 2 feature should be enabled when creating
    an image. Multiple features can be enabled by repeating this option
    multiple times. The following features are supported:
 
-   layering: layering support
-   striping: striping v2 support
-   exclusive-lock: exclusive locking support
-   object-map: object map support (requires exclusive-lock)
-   fast-diff: fast diff calculations (requires object-map)
-   deep-flatten: snapshot flatten support
+   * layering: layering support
+   * striping: striping v2 support
+   * exclusive-lock: exclusive locking support
+   * object-map: object map support (requires exclusive-lock)
+   * fast-diff: fast diff calculations (requires object-map)
+   * deep-flatten: snapshot flatten support
 
 .. option:: --image-shared
 
@@ -158,7 +158,7 @@ Commands
 
 .. TODO rst "option" directive seems to require --foo style options, parsing breaks on subcommands.. the args show up as bold too
 
-:command:`ls` [-l | --long] [pool-name]
+:command:`ls` [-l | --long] [*pool-name*]
   Will list all rbd images listed in the rbd_directory object.  With
   -l, also show snapshots, and use longer-format output including
   size, parent (if clone), format, etc.
@@ -171,16 +171,16 @@ Commands
   If the RBD fast-diff feature isn't enabled on images, this operation will
   require querying the OSDs for every potential object within the image.
 
-:command:`info` [*image-spec*] | [*snap-spec*]
+:command:`info` *image-spec* | *snap-spec*
   Will dump information (such as size and order) about a specific rbd image.
   If image is a clone, information about its parent is also displayed.
   If a snapshot is specified, whether it is protected is shown as well.
 
-:command:`create` [*image-spec*]
+:command:`create` (-s | --size *size-in-M/G/T*) [--image-format *format-id*] [--order *bits*] [--stripe-unit *size-in-bytes* --stripe-count *num*] [--image-feature *feature-name*]... [--image-shared] *image-spec*
   Will create a new rbd image. You must also specify the size via --size.  The
   --stripe-unit and --stripe-count arguments are optional, but must be used together.
 
-:command:`clone` [*parent-snap-spec*] [*child-image-spec*]
+:command:`clone` [--order *bits*] [--stripe-unit *size-in-bytes* --stripe-count *num*] [--image-feature *feature-name*]... [--image-shared] *parent-snap-spec* *child-image-spec*
   Will create a clone (copy-on-write child) of the parent snapshot.
   Object order will be identical to that of the parent image unless
   specified. Size will be the same as the parent snapshot. The --stripe-unit
@@ -189,7 +189,7 @@ Commands
   The parent snapshot must be protected (see `rbd snap protect`).
   This requires image format 2.
 
-:command:`flatten` [*image-spec*]
+:command:`flatten` *image-spec*
   If image is a clone, copy all shared blocks from the parent snapshot and
   make the child independent of the parent, severing the link between
   parent snap and child.  The parent snapshot can be unprotected and
@@ -197,24 +197,24 @@ Commands
 
   This requires image format 2.
 
-:command:`children` [*snap-spec*]
+:command:`children` *snap-spec*
   List the clones of the image at the given snapshot. This checks
   every pool, and outputs the resulting poolname/imagename.
 
   This requires image format 2.
 
-:command:`resize` [*image-spec*] [--allow-shrink]
+:command:`resize` (-s | --size *size-in-M/G/T*) [--allow-shrink] *image-spec*
   Resizes rbd image. The size parameter also needs to be specified.
   The --allow-shrink option lets the size be reduced.
 
-:command:`rm` [*image-spec*]
+:command:`rm` *image-spec*
   Deletes an rbd image (including all data blocks). If the image has
   snapshots, this fails and nothing is deleted.
 
-:command:`export` ([*image-spec*] | [*snap-spec*]) [*dest-path*]
+:command:`export` (*image-spec* | *snap-spec*) [*dest-path*]
   Exports image to dest path (use - for stdout).
 
-:command:`import` [*path*] [*image-spec*]
+:command:`import` [--image-format *format-id*] [--order *bits*] [--stripe-unit *size-in-bytes* --stripe-count *num*] [--image-feature *feature-name*]... [--image-shared] *src-path* [*image-spec*]
   Creates a new image and imports its data from path (use - for
   stdin).  The import operation will try to create sparse rbd images 
   if possible.  For import from stdin, the sparsification unit is
@@ -223,7 +223,7 @@ Commands
   The --stripe-unit and --stripe-count arguments are optional, but must be
   used together.
 
-:command:`export-diff` ([*image-spec*] | [*snap-spec*]) [*dest-path*] [--from-snap *snap-name*] [--object-extents]
+:command:`export-diff` [--from-snap *snap-name*] [--object-extents] (*image-spec* | *snap-spec*) *dest-path*
   Exports an incremental diff for an image to dest path (use - for stdout).  If
   an initial snapshot is specified, only changes since that snapshot are included; otherwise,
   any regions of the image that contain data are included.  The end snapshot is specified
@@ -231,7 +231,7 @@ Commands
   metadata about image size changes, and the start and end snapshots.  It efficiently represents
   discarded or 'zero' regions of the image.
 
-:command:`merge-diff` [*first-diff-path*] [*second-diff-path*] [*merged-diff-path*]
+:command:`merge-diff` *first-diff-path* *second-diff-path* *merged-diff-path*
   Merge two continuous incremental diffs of an image into one single diff. The
   first diff's end snapshot must be equal with the second diff's start snapshot.
   The first diff could be - for stdin, and merged diff could be - for stdout, which
@@ -239,59 +239,59 @@ Commands
   'rbd merge-diff first second - | rbd merge-diff - third result'. Note this command
   currently only support the source incremental diff with stripe_count == 1
 
-:command:`import-diff` [*src-path*] [*image-spec*]
+:command:`import-diff` *src-path* *image-spec*
   Imports an incremental diff of an image and applies it to the current image.  If the diff
   was generated relative to a start snapshot, we verify that snapshot already exists before
   continuing.  If there was an end snapshot we verify it does not already exist before
   applying the changes, and create the snapshot when we are done.
 
-:command:`diff` [*image-spec*] | [*snap-spec*] [--from-snap *snap-name*] [--object-extents]
+:command:`diff` [--from-snap *snap-name*] [--object-extents] *image-spec* | *snap-spec*
   Dump a list of byte extents in the image that have changed since the specified start
   snapshot, or since the image was created.  Each output line includes the starting offset
   (in bytes), the length of the region (in bytes), and either 'zero' or 'data' to indicate
   whether the region is known to be zeros or may contain other data.
 
-:command:`cp` ([*src-image-spec*] | [*src-snap-spec*]) [*dest-image-spec*]
+:command:`cp` (*src-image-spec* | *src-snap-spec*) *dest-image-spec*
   Copies the content of a src-image into the newly created dest-image.
   dest-image will have the same size, order, and image format as src-image.
 
-:command:`mv` [*src-image-spec*] [*dest-image-spec*]
+:command:`mv` *src-image-spec* *dest-image-spec*
   Renames an image.  Note: rename across pools is not supported.
 
-:command:`image-meta list` [*image-spec*]
+:command:`image-meta list` *image-spec*
   Show metadata held on the image. The first column is the key
   and the second column is the value.
 
-:command:`image-meta get` [*image-spec*] [*key*]
+:command:`image-meta get` *image-spec* *key*
   Get metadata value with the key.
 
-:command:`image-meta set` [*image-spec*] [*key*] [*value*]
-  Set metadata key with the value. They will displayed in `metadata-list`
+:command:`image-meta set` *image-spec* *key* *value*
+  Set metadata key with the value. They will displayed in `image-meta list`.
 
-:command:`image-meta remove` [*image-spec*] [*key*]
+:command:`image-meta remove` *image-spec* *key*
   Remove metadata key with the value.
 
-:command:`object-map` rebuild [*image-spec*] | [*snap-spec*]
+:command:`object-map rebuild` *image-spec* | *snap-spec*
   Rebuilds an invalid object map for the specified image. An image snapshot can be
   specified to rebuild an invalid object map for a snapshot.
 
-:command:`snap` ls [*image-spec*]
+:command:`snap ls` *image-spec*
   Dumps the list of snapshots inside a specific image.
 
-:command:`snap` create [*snap-spec*]
+:command:`snap create` *snap-spec*
   Creates a new snapshot. Requires the snapshot name parameter specified.
 
-:command:`snap` rollback [*snap-spec*]
+:command:`snap rollback` *snap-spec*
   Rollback image content to snapshot. This will iterate through the entire blocks
   array and update the data head content to the snapshotted version.
 
-:command:`snap` rm [*snap-spec*]
+:command:`snap rm` *snap-spec*
   Removes the specified snapshot.
 
-:command:`snap` purge [*image-spec*]
+:command:`snap purge` *image-spec*
   Removes all snapshots from an image.
 
-:command:`snap` protect [*snap-spec*]
+:command:`snap protect` *snap-spec*
   Protect a snapshot from deletion, so that clones can be made of it
   (see `rbd clone`).  Snapshots must be protected before clones are made;
   protection implies that there exist dependent cloned children that
@@ -300,38 +300,38 @@ Commands
 
   This requires image format 2.
 
-:command:`snap` unprotect [*snap-spec*]
+:command:`snap unprotect` *snap-spec*
   Unprotect a snapshot from deletion (undo `snap protect`).  If cloned
   children remain, `snap unprotect` fails.  (Note that clones may exist
   in different pools than the parent snapshot.)
 
   This requires image format 2.
 
-:command:`map` [*image-spec*] | [*snap-spec*] [-o | --options *map-options* ] [--read-only]
+:command:`map` [-o | --options *map-options* ] [--read-only] *image-spec* | *snap-spec*
   Maps the specified image to a block device via the rbd kernel module.
 
-:command:`unmap` [*image-spec*] | [*snap-spec*] | [*device-path*]
+:command:`unmap` *image-spec* | *snap-spec* | *device-path*
   Unmaps the block device that was mapped via the rbd kernel module.
 
 :command:`showmapped`
   Show the rbd images that are mapped via the rbd kernel module.
 
-:command:`status` [*image-spec*]
+:command:`status` *image-spec*
   Show the status of the image, including which clients have it open.
 
-:command:`feature` disable [*image-spec*] [*feature*]
+:command:`feature disable` *image-spec* *feature-name*...
   Disables the specified feature on the specified image. Multiple features can
   be specified.
 
-:command:`feature` enable [*image-spec*] [*feature*]
+:command:`feature enable` *image-spec* *feature-name*...
   Enables the specified feature on the specified image. Multiple features can
   be specified.
 
-:command:`lock` list [*image-spec*]
+:command:`lock list` *image-spec*
   Show locks held on the image. The first column is the locker
   to use with the `lock remove` command.
 
-:command:`lock` add [*image-spec*] [*lock-id*]
+:command:`lock add` [--shared *lock-tag*] *image-spec* *lock-id*
   Lock an image. The lock-id is an arbitrary name for the user's
   convenience. By default, this is an exclusive lock, meaning it
   will fail if the image is already locked. The --shared option
@@ -339,14 +339,14 @@ Commands
   any operation other than adding a lock. It does not
   protect an image from being deleted.
 
-:command:`lock` remove [*image-spec*] [*lock-id*] [*locker*]
+:command:`lock remove` *image-spec* *lock-id* *locker*
   Release a lock on an image. The lock id and locker are
   as output by lock ls.
 
-:command:`bench-write` [*image-spec*] --io-size [*io-size-in-bytes*] --io-threads [*num-ios-in-flight*] --io-total [*total-bytes-to-write*]
-  Generate a series of sequential writes to the image and measure the
-  write throughput and latency.  Defaults are: --io-size 4096, --io-threads 16, 
-  --io-total 1GB
+:command:`bench-write` [--io-size *size-in-bytes*] [--io-threads *num-ios-in-flight*] [--io-total *total-bytes-to-write*] [--io-pattern seq | rand] *image-spec*
+  Generate a series of writes to the image and measure the write throughput and
+  latency.  Defaults are: --io-size 4096, --io-threads 16, --io-total 1GB,
+  --io-pattern seq.
 
 Image and snap specs
 ====================

diff --git a/src/rbd.cc b/src/rbd.cc
index d2f6dac2a2fb5589cc8c1e21e6fceb4b613331a5..685ebcc509e80fcc61346354677836e95ee37ec9 100644 (file)
--- a/src/rbd.cc
+++ b/src/rbd.cc
@@ -108,12 +108,15 @@ void usage()
 "                                              (make it independent)\n"
 "  resize --size <M/G/T> <image-spec>          resize (expand or contract) image\n"
 "  rm <image-spec>                             delete an image\n"
-"  export (<image-spec> | <snap-spec>) <path>  export image to file\n"
+"  export (<image-spec> | <snap-spec>) [<path>]\n"
+"                                              export image to file\n"
 "                                              \"-\" for stdout\n"
 "  import [--image-features <features>] [--image-shared]\n"
-"         <path> <image-spec>                  import image from file (dest\n"
-"                                              defaults as the filename part\n"
-"                                              of file). \"-\" for stdin\n"
+"         <path> [<image-spec>]                import image from file\n"
+"                                              \"-\" for stdin\n"
+"                                              \"rbd/$(basename <path>)\" is\n"
+"                                              assumed for <image-spec> if\n"
+"                                              omitted\n"
 "  diff [--from-snap <snap-name>] [--object-extents]\n"
 "         <image-spec> | <snap-spec>           print extents that differ since\n"
 "                                              a previous snap, or image creation\n"
@@ -3434,13 +3437,16 @@ if (!set_conf_param(v, p1, p2, p3)) { \
       cerr << "rbd: second diff was not specified" << std::endl;
       return EXIT_FAILURE;
     }
-    if (!path) {
+  }
+  if ((opt_cmd == OPT_EXPORT || opt_cmd == OPT_EXPORT_DIFF ||
+      opt_cmd == OPT_MERGE_DIFF) && !path) {
+    if (opt_cmd == OPT_EXPORT) {
+      path = imgname;
+    } else {
       cerr << "rbd: path was not specified" << std::endl;
       return EXIT_FAILURE;
     }
   }
-  if (opt_cmd == OPT_EXPORT && !path)
-    path = imgname;
 
   if ((opt_cmd == OPT_COPY || opt_cmd == OPT_CLONE || opt_cmd == OPT_RENAME) &&
       !destname ) {
@@ -3737,10 +3743,6 @@ if (!set_conf_param(v, p1, p2, p3)) { \
     break;
 
   case OPT_EXPORT:
-    if (!path) {
-      cerr << "rbd: export requires pathname" << std::endl;
-      return EINVAL;
-    }
     r = do_export(image, path);
     if (r < 0) {
       cerr << "rbd: export error: " << cpp_strerror(-r) << std::endl;
@@ -3757,10 +3759,6 @@ if (!set_conf_param(v, p1, p2, p3)) { \
     break;
 
   case OPT_EXPORT_DIFF:
-    if (!path) {
-      cerr << "rbd: export-diff requires pathname" << std::endl;
-      return EINVAL;
-    }
     r = do_export_diff(image, fromsnapname, snapname, diff_object_extents, path);
     if (r < 0) {
       cerr << "rbd: export-diff error: " << cpp_strerror(-r) << std::endl;
@@ -3777,10 +3775,6 @@ if (!set_conf_param(v, p1, p2, p3)) { \
     break;
 
   case OPT_IMPORT:
-    if (!path) {
-      cerr << "rbd: import requires pathname" << std::endl;
-      return EINVAL;
-    }
     r = do_import(rbd, dest_io_ctx, destname, &order, path,
                  format, features, size, stripe_unit, stripe_count);
     if (r < 0) {
@@ -3790,7 +3784,6 @@ if (!set_conf_param(v, p1, p2, p3)) { \
     break;
 
   case OPT_IMPORT_DIFF:
-    assert(path);
     r = do_import_diff(image, path);
     if (r < 0) {
       cerr << "rbd: import-diff failed: " << cpp_strerror(-r) << std::endl;

diff --git a/src/test/cli/rbd/help.t b/src/test/cli/rbd/help.t
index d38c28e6969f0e36e23728d7ac8966840d59c915..8e69fe6f2a2542855330bb2a8ec62bb00902355b 100644 (file)
--- a/src/test/cli/rbd/help.t
+++ b/src/test/cli/rbd/help.t
@@ -18,12 +18,15 @@
                                                 (make it independent)
     resize --size <M/G/T> <image-spec>          resize (expand or contract) image
     rm <image-spec>                             delete an image
-    export (<image-spec> | <snap-spec>) <path>  export image to file
+    export (<image-spec> | <snap-spec>) [<path>]
+                                                export image to file
                                                 "-" for stdout
     import [--image-features <features>] [--image-shared]
-           <path> <image-spec>                  import image from file (dest
-                                                defaults as the filename part
-                                                of file). "-" for stdin
+           <path> [<image-spec>]                import image from file
+                                                "-" for stdin
+                                                "rbd/$(basename <path>)" is
+                                                assumed for <image-spec> if
+                                                omitted
     diff [--from-snap <snap-name>] [--object-extents]
            <image-spec> | <snap-spec>           print extents that differ since
                                                 a previous snap, or image creation