From: Ilya Dryomov Date: Mon, 20 Jul 2015 14:22:54 +0000 (+0300) Subject: rbd: import doesn't require image-spec arg, ditto for export and path X-Git-Tag: v9.0.3~14^2~4 X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=bbc5c71284f978b41e64f8703c4288d04cff0d82;p=ceph.git 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 --- diff --git a/doc/man/8/rbd.rst b/doc/man/8/rbd.rst index 1f3964fb8f73..3e11875db9d5 100644 --- 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 d2f6dac2a2fb..685ebcc509e8 100644 --- a/src/rbd.cc +++ b/src/rbd.cc @@ -108,12 +108,15 @@ void usage() " (make it independent)\n" " resize --size resize (expand or contract) image\n" " rm delete an image\n" -" export ( | ) export image to file\n" +" export ( | ) []\n" +" export image to file\n" " \"-\" for stdout\n" " import [--image-features ] [--image-shared]\n" -" import image from file (dest\n" -" defaults as the filename part\n" -" of file). \"-\" for stdin\n" +" [] import image from file\n" +" \"-\" for stdin\n" +" \"rbd/$(basename )\" is\n" +" assumed for if\n" +" omitted\n" " diff [--from-snap ] [--object-extents]\n" " | 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 d38c28e6969f..8e69fe6f2a25 100644 --- a/src/test/cli/rbd/help.t +++ b/src/test/cli/rbd/help.t @@ -18,12 +18,15 @@ (make it independent) resize --size resize (expand or contract) image rm delete an image - export ( | ) export image to file + export ( | ) [] + export image to file "-" for stdout import [--image-features ] [--image-shared] - import image from file (dest - defaults as the filename part - of file). "-" for stdin + [] import image from file + "-" for stdin + "rbd/$(basename )" is + assumed for if + omitted diff [--from-snap ] [--object-extents] | print extents that differ since a previous snap, or image creation