From 99093881718d17eaf4119ea74a310f20d9d07157 Mon Sep 17 00:00:00 2001 From: Vikhyat Umrao Date: Thu, 16 Jul 2015 21:39:54 +0530 Subject: [PATCH] rbd: use image-spec and snap-spec in rbd help This patch changes image-name instances to image-spec and snap-name instances to snap-spec to try to clarify usage for some commands and disambiguate the term {image,snap}-name, which has been used to denote both simple names and compound names (specs). is []/ is []/@ This patch also removes duplicate checks for image-name and snap-name. Signed-off-by: Vikhyat Umrao [idryomov@gmail.com: some commands take either image-spec or snap-spec, other fixes, formatting, changelog] Signed-off-by: Ilya Dryomov --- doc/man/8/rbd.rst | 89 ++++++++++++------------- src/common/ceph_argparse.cc | 2 +- src/rbd.cc | 127 ++++++++++++++---------------------- src/test/cli/rbd/help.t | 94 +++++++++++++------------- 4 files changed, 146 insertions(+), 166 deletions(-) diff --git a/doc/man/8/rbd.rst b/doc/man/8/rbd.rst index e7724146e561..b20a5f1a7e54 100644 --- a/doc/man/8/rbd.rst +++ b/doc/man/8/rbd.rst @@ -35,7 +35,7 @@ Options Connect to specified monitor (instead of looking through ceph.conf). -.. option:: -p pool, --pool pool +.. option:: -p pool-name, --pool pool-name Interact with the given pool. Required by most commands. @@ -170,16 +170,17 @@ 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-name*] + +: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-name*] +:command:`create` [*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-snapname*] [*image-name*] +:command:`clone` [*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 @@ -188,7 +189,7 @@ Commands The parent snapshot must be protected (see `rbd snap protect`). This requires image format 2. -:command:`flatten` [*image-name*] +: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 @@ -196,24 +197,24 @@ Commands This requires image format 2. -:command:`children` [*image-name*] +: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-name*] [--allow-shrink] +:command:`resize` [*image-spec*] [--allow-shrink] Resizes rbd image. The size parameter also needs to be specified. The --allow-shrink option lets the size be reduced. -:command:`rm` [*image-name*] +: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-name*] [*dest-path*] +:command:`export` ([*image-spec*] | [*snap-spec*]) [*dest-path*] Exports image to dest path (use - for stdout). -:command:`import` [*path*] [*dest-image*] +:command:`import` [*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 @@ -222,7 +223,7 @@ Commands The --stripe-unit and --stripe-count arguments are optional, but must be used together. -:command:`export-diff` [*image-name*] [*dest-path*] [--from-snap *snapname*] [--object-extents] +:command:`export-diff` ([*image-spec*] | [*snap-spec*]) [*dest-path*] [--from-snap *snap-name*] [--object-extents] 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 @@ -238,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-name*] +: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-name*] [--from-snap *snapname*] [--object-extents] +:command:`diff` [*image-spec*] | [*snap-spec*] [--from-snap *snap-name*] [--object-extents] 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*] [*dest-image*] +: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*] [*dest-image*] +:command:`mv` [*src-image-spec*] [*dest-image-spec*] Renames an image. Note: rename across pools is not supported. -:command:`image-meta list` [*image-name*] +: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-name*] [*key*] +:command:`image-meta get` [*image-spec*] [*key*] Get metadata value with the key. -:command:`image-meta set` [*image-name*] [*key*] [*value*] +:command:`image-meta set` [*image-spec*] [*key*] [*value*] Set metadata key with the value. They will displayed in `metadata-list` -:command:`image-meta remove` [*image-name*] [*key*] +:command:`image-meta remove` [*image-spec*] [*key*] Remove metadata key with the value. -:command:`object-map` rebuild [*image-name*] +: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-name*] +:command:`snap` ls [*image-spec*] Dumps the list of snapshots inside a specific image. -:command:`snap` create [*image-name*] +:command:`snap` create [*snap-spec*] Creates a new snapshot. Requires the snapshot name parameter specified. -:command:`snap` rollback [*image-name*] +: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 [*image-name*] +:command:`snap` rm [*snap-spec*] Removes the specified snapshot. -:command:`snap` purge [*image-name*] +:command:`snap` purge [*image-spec*] Removes all snapshots from an image. -:command:`snap` protect [*image-name*] +: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 @@ -299,38 +300,38 @@ Commands This requires image format 2. -:command:`snap` unprotect [*image-name*] +: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-name*] [-o | --options *map-options* ] [--read-only] +:command:`map` [*image-spec*] | [*snap-spec*] [-o | --options *map-options* ] [--read-only] Maps the specified image to a block device via the rbd kernel module. -:command:`unmap` [*image-name*] | [*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-name*] +:command:`status` [*image-spec*] Show the status of the image, including which clients have it open. -:command:`feature` disable [*image-name*] [*feature*] +:command:`feature` disable [*image-spec*] [*feature*] Disables the specified feature on the specified image. Multiple features can be specified. -:command:`feature` enable [*image-name*] [*feature*] +:command:`feature` enable [*image-spec*] [*feature*] Enables the specified feature on the specified image. Multiple features can be specified. -:command:`lock` list [*image-name*] +: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-name*] [*lock-id*] +:command:`lock` add [*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 @@ -338,26 +339,26 @@ Commands any operation other than adding a lock. It does not protect an image from being deleted. -:command:`lock` remove [*image-name*] [*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-name*] --io-size [*io-size-in-bytes*] --io-threads [*num-ios-in-flight*] --io-total [*total-bytes-to-write*] +: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 -Image name -========== - -In addition to using the --pool and the --snap options, the image name can include both -the pool name and the snapshot name. The image name format is as follows:: +Image and snap specs +==================== - [pool/]image-name[@snap] +| *image-spec* is [*pool-name*]/*image-name* +| *snap-spec* is [*pool-name*]/*image-name*\ @\ *snap-name* -Thus an image name that contains a slash character ('/') requires specifying the pool -name explicitly. +The default for *pool-name* is "rbd". If an image name contains a slash +character ('/'), *pool-name* is required. +You may specify each name individually, using --pool, --image and --snap +options, but this is discouraged in favor of the above spec syntax. Striping ======== diff --git a/src/common/ceph_argparse.cc b/src/common/ceph_argparse.cc index 924b68077f2b..858882baf0ef 100644 --- a/src/common/ceph_argparse.cc +++ b/src/common/ceph_argparse.cc @@ -367,7 +367,7 @@ static int va_ceph_argparse_witharg(std::vector &args, else if (first[strlen_a] == '\0') { // find second part (or not) if (i+1 == args.end()) { - oss << "Option " << *i << " requires an argument."; + oss << "Option " << *i << " requires an argument." << std::endl; i = args.erase(i); return -EINVAL; } diff --git a/src/rbd.cc b/src/rbd.cc index ca8bb3c21129..d2f6dac2a2fb 100644 --- a/src/rbd.cc +++ b/src/rbd.cc @@ -91,82 +91,88 @@ void usage() cout << "usage: rbd [-n ] [OPTIONS] ...\n" "where 'pool' is a rados pool name (default is 'rbd') and 'cmd' is one of:\n" -" (ls | list) [-l | --long ] [pool-name] list rbd images\n" +" (ls | list) [-l | --long ] [pool-name] list rbd images\n" " (-l includes snapshots/clones)\n" " (du | disk-usage) [--image ] [pool-name]\n" " show pool image disk usage stats\n" -" info show information about image size,\n" +" info | show information about image size,\n" " striping, etc.\n" " create [--order ] [--image-features ] [--image-shared]\n" -" --size create an empty image\n" +" --size create an empty image\n" " clone [--order ] [--image-features ] [--image-shared]\n" -" clone a snapshot into a COW\n" +" \n" +" clone a snapshot into a COW\n" " child image\n" -" children display children of snapshot\n" -" flatten fill clone with parent data\n" +" children display children of snapshot\n" +" flatten fill clone with parent data\n" " (make it independent)\n" -" resize --size resize (expand or contract) image\n" -" rm delete an image\n" -" export export image to file\n" +" resize --size resize (expand or contract) image\n" +" rm delete an image\n" +" export ( | ) export image to file\n" " \"-\" for stdout\n" " import [--image-features ] [--image-shared]\n" -" import image from file (dest\n" +" import image from file (dest\n" " defaults as the filename part\n" " of file). \"-\" for stdin\n" -" diff [--from-snap ] [--object-extents] \n" -" print extents that differ since\n" +" diff [--from-snap ] [--object-extents]\n" +" | print extents that differ since\n" " a previous snap, or image creation\n" -" export-diff [--from-snap ] [--object-extents] \n" -" export an incremental diff to\n" +" export-diff [--from-snap ] [--object-extents]\n" +" ( | ) export an incremental diff to\n" " path, or \"-\" for stdout\n" " merge-diff merge and into\n" " , could be \"-\"\n" " for stdin, and could be \"-\"\n" " for stdout\n" -" import-diff import an incremental diff from\n" +" import-diff import an incremental diff from\n" " path or \"-\" for stdin\n" -" (cp | copy) copy src image to dest\n" -" (mv | rename) rename src image to dest\n" -" image-meta list image metadata list keys with values\n" -" image-meta get image metadata get the value associated with the key\n" -" image-meta set image metadata set key with value\n" -" image-meta remove image metadata remove the key and value associated\n" -" object-map rebuild rebuild an invalid object map\n" -" snap ls dump list of image snapshots\n" -" snap create create a snapshot\n" -" snap rollback rollback image to snapshot\n" -" snap rm deletes a snapshot\n" -" snap purge deletes all snapshots\n" -" snap protect prevent a snapshot from being deleted\n" -" snap unprotect allow a snapshot to be deleted\n" -" watch watch events on image\n" -" status show the status of this image\n" -" map map image to a block device\n" +" (cp | copy) ( | ) \n" +" copy src image to dest\n" +" (mv | rename) \n" +" rename src image to dest\n" +" image-meta list image metadata list keys with values\n" +" image-meta get image metadata get the value associated with the key\n" +" image-meta set image metadata set key with value\n" +" image-meta remove image metadata remove the key and value associated\n" +" object-map rebuild | \n" +" rebuild an invalid object map\n" +" snap ls dump list of image snapshots\n" +" snap create create a snapshot\n" +" snap rollback rollback image to snapshot\n" +" snap rm deletes a snapshot\n" +" snap purge deletes all snapshots\n" +" snap protect prevent a snapshot from being deleted\n" +" snap unprotect allow a snapshot to be deleted\n" +" watch watch events on image\n" +" status show the status of this image\n" +" map | map image to a block device\n" " using the kernel\n" -" unmap | unmap a rbd device that was\n" +" unmap | | unmap a rbd device that was\n" " mapped by the kernel\n" " showmapped show the rbd images mapped\n" " by the kernel\n" -" feature disable disable the specified image feature\n" -" feature enable enable the specified image feature\n" -" lock list show locks held on an image\n" -" lock add [--shared ] take a lock called id on an image\n" -" lock remove release a lock on an image\n" -" bench-write simple write benchmark\n" +" feature disable disable the specified image feature\n" +" feature enable enable the specified image feature\n" +" lock list show locks held on an image\n" +" lock add [--shared ] take a lock called id on an image\n" +" lock remove release a lock on an image\n" +" bench-write simple write benchmark\n" " --io-size write size\n" " --io-threads ios in flight\n" " --io-total total bytes to write\n" " --io-pattern write pattern\n" "\n" -", are [pool/]name[@snap], or you may specify\n" -"individual pieces of names with -p/--pool, --image, and/or --snap.\n" +" is []/,\n" +" is []/@,\n" +"or you may specify individual pieces of names with -p/--pool ,\n" +"--image and/or --snap .\n" "\n" "Other input options:\n" -" -p, --pool source pool name\n" +" -p, --pool source pool name\n" +" --dest-pool destination pool name\n" " --image image name\n" -" --dest destination [pool and] image name\n" +" --dest destination image name\n" " --snap snapshot name\n" -" --dest-pool destination pool name\n" " --path path name for import/export\n" " -s, --size size of image for create and resize\n" " --order the object size in bits; object size will be\n" @@ -3294,11 +3300,6 @@ if (!set_conf_param(v, p1, p2, p3)) { \ } } - if (opt_cmd == OPT_EXPORT && !imgname) { - cerr << "rbd: image name was not specified" << std::endl; - return EXIT_FAILURE; - } - if ((opt_cmd == OPT_IMPORT || opt_cmd == OPT_IMPORT_DIFF) && !path) { cerr << "rbd: path was not specified" << std::endl; return EXIT_FAILURE; @@ -3663,10 +3664,6 @@ if (!set_conf_param(v, p1, p2, p3)) { \ break; case OPT_SNAP_LIST: - if (!imgname) { - cerr << "rbd: snap list requires an image parameter" << std::endl; - return EXIT_FAILURE; - } r = do_list_snaps(image, formatter.get()); if (r < 0) { cerr << "rbd: failed to list snapshots: " << cpp_strerror(-r) @@ -3676,10 +3673,6 @@ if (!set_conf_param(v, p1, p2, p3)) { \ break; case OPT_SNAP_CREATE: - if (!imgname || !snapname) { - cerr << "rbd: snap create requires image and snapname" << std::endl; - return EINVAL; - } r = do_add_snap(image, snapname); if (r < 0) { cerr << "rbd: failed to create snapshot: " << cpp_strerror(-r) @@ -3689,10 +3682,6 @@ if (!set_conf_param(v, p1, p2, p3)) { \ break; case OPT_SNAP_ROLLBACK: - if (!imgname) { - cerr << "rbd: snap rollback requires image name" << std::endl; - return EINVAL; - } r = do_rollback_snap(image, snapname); if (r < 0) { cerr << "rbd: rollback failed: " << cpp_strerror(-r) << std::endl; @@ -3701,10 +3690,6 @@ if (!set_conf_param(v, p1, p2, p3)) { \ break; case OPT_SNAP_REMOVE: - if (!imgname) { - cerr << "rbd: snap remove requires image name" << std::endl; - return EINVAL; - } r = do_remove_snap(image, snapname); if (r < 0) { if (r == -EBUSY) { @@ -3719,10 +3704,6 @@ if (!set_conf_param(v, p1, p2, p3)) { \ break; case OPT_SNAP_PURGE: - if (!imgname) { - cerr << "rbd: snap purge requires image name" << std::endl; - return EINVAL; - } r = do_purge_snaps(image); if (r < 0) { cerr << "rbd: removing snaps failed: " << cpp_strerror(-r) << std::endl; @@ -3731,10 +3712,6 @@ if (!set_conf_param(v, p1, p2, p3)) { \ break; case OPT_SNAP_PROTECT: - if (!imgname) { - cerr << "rbd: snap protect requires image name" << std::endl; - return EINVAL; - } r = do_protect_snap(image, snapname); if (r < 0) { cerr << "rbd: protecting snap failed: " << cpp_strerror(-r) << std::endl; @@ -3743,10 +3720,6 @@ if (!set_conf_param(v, p1, p2, p3)) { \ break; case OPT_SNAP_UNPROTECT: - if (!imgname) { - cerr << "rbd: snap unprotect requires image name" << std::endl; - return EINVAL; - } r = do_unprotect_snap(image, snapname); if (r < 0) { cerr << "rbd: unprotecting snap failed: " << cpp_strerror(-r) diff --git a/src/test/cli/rbd/help.t b/src/test/cli/rbd/help.t index 19b4879fb5f4..d38c28e6969f 100644 --- a/src/test/cli/rbd/help.t +++ b/src/test/cli/rbd/help.t @@ -1,82 +1,88 @@ $ rbd --help usage: rbd [-n ] [OPTIONS] ... where 'pool' is a rados pool name (default is 'rbd') and 'cmd' is one of: - (ls | list) [-l | --long ] [pool-name] list rbd images + (ls | list) [-l | --long ] [pool-name] list rbd images (-l includes snapshots/clones) (du | disk-usage) [--image ] [pool-name] show pool image disk usage stats - info show information about image size, + info | show information about image size, striping, etc. create [--order ] [--image-features ] [--image-shared] - --size create an empty image + --size create an empty image clone [--order ] [--image-features ] [--image-shared] - clone a snapshot into a COW + + clone a snapshot into a COW child image - children display children of snapshot - flatten fill clone with parent data + children display children of snapshot + flatten fill clone with parent data (make it independent) - resize --size resize (expand or contract) image - rm delete an image - export export image to file + resize --size resize (expand or contract) image + rm delete an image + export ( | ) export image to file "-" for stdout import [--image-features ] [--image-shared] - import image from file (dest + import image from file (dest defaults as the filename part of file). "-" for stdin - diff [--from-snap ] [--object-extents] - print extents that differ since + diff [--from-snap ] [--object-extents] + | print extents that differ since a previous snap, or image creation - export-diff [--from-snap ] [--object-extents] - export an incremental diff to + export-diff [--from-snap ] [--object-extents] + ( | ) export an incremental diff to path, or "-" for stdout merge-diff merge and into , could be "-" for stdin, and could be "-" for stdout - import-diff import an incremental diff from + import-diff import an incremental diff from path or "-" for stdin - (cp | copy) copy src image to dest - (mv | rename) rename src image to dest - image-meta list image metadata list keys with values - image-meta get image metadata get the value associated with the key - image-meta set image metadata set key with value - image-meta remove image metadata remove the key and value associated - object-map rebuild rebuild an invalid object map - snap ls dump list of image snapshots - snap create create a snapshot - snap rollback rollback image to snapshot - snap rm deletes a snapshot - snap purge deletes all snapshots - snap protect prevent a snapshot from being deleted - snap unprotect allow a snapshot to be deleted - watch watch events on image - status show the status of this image - map map image to a block device + (cp | copy) ( | ) + copy src image to dest + (mv | rename) + rename src image to dest + image-meta list image metadata list keys with values + image-meta get image metadata get the value associated with the key + image-meta set image metadata set key with value + image-meta remove image metadata remove the key and value associated + object-map rebuild | + rebuild an invalid object map + snap ls dump list of image snapshots + snap create create a snapshot + snap rollback rollback image to snapshot + snap rm deletes a snapshot + snap purge deletes all snapshots + snap protect prevent a snapshot from being deleted + snap unprotect allow a snapshot to be deleted + watch watch events on image + status show the status of this image + map | map image to a block device using the kernel - unmap | unmap a rbd device that was + unmap | | unmap a rbd device that was mapped by the kernel showmapped show the rbd images mapped by the kernel - feature disable disable the specified image feature - feature enable enable the specified image feature - lock list show locks held on an image - lock add [--shared ] take a lock called id on an image - lock remove release a lock on an image - bench-write simple write benchmark + feature disable disable the specified image feature + feature enable enable the specified image feature + lock list show locks held on an image + lock add [--shared ] take a lock called id on an image + lock remove release a lock on an image + bench-write simple write benchmark --io-size write size --io-threads ios in flight --io-total total bytes to write --io-pattern write pattern - , are [pool/]name[@snap], or you may specify - individual pieces of names with -p/--pool, --image, and/or --snap. + is []/, + is []/@, + or you may specify individual pieces of names with -p/--pool , + --image and/or --snap . Other input options: - -p, --pool source pool name + -p, --pool source pool name + --dest-pool destination pool name --image image name - --dest destination [pool and] image name + --dest destination image name --snap snapshot name - --dest-pool destination pool name --path path name for import/export -s, --size size of image for create and resize --order the object size in bits; object size will be -- 2.47.3