From 76989cc4aef1e14b1466b3c7644e2453515dc946 Mon Sep 17 00:00:00 2001 From: Ilya Dryomov Date: Fri, 17 Jul 2015 12:41:29 +0300 Subject: [PATCH] doc: use spec syntax in rbd docs Use spec syntax instead of --pool, --image and --snap to hopefully push people towards the former. Signed-off-by: Ilya Dryomov --- doc/man/8/rbd.rst | 8 ++------ doc/rados/operations/erasure-code.rst | 2 +- doc/rados/operations/user-management.rst | 2 +- doc/rbd/rados-rbd-cmds.rst | 20 ++++++++++---------- doc/rbd/rbd-ko.rst | 8 ++++---- doc/rbd/rbd-snapshot.rst | 21 +-------------------- doc/start/quick-rbd.rst | 2 +- 7 files changed, 20 insertions(+), 43 deletions(-) diff --git a/doc/man/8/rbd.rst b/doc/man/8/rbd.rst index b20a5f1a7e540..1f3964fb8f733 100644 --- a/doc/man/8/rbd.rst +++ b/doc/man/8/rbd.rst @@ -448,10 +448,6 @@ Examples To create a new rbd image that is 100 GB:: - rbd -p mypool create myimage --size 102400 - -or alternatively:: - rbd create mypool/myimage --size 102400 To use a non-default object size (8 MB):: @@ -489,13 +485,13 @@ To unmap an image:: To create an image and a clone from it:: rbd import --image-format 2 image mypool/parent - rbd snap create --snap snapname mypool/parent + rbd snap create mypool/parent@snap rbd snap protect mypool/parent@snap rbd clone mypool/parent@snap otherpool/child To create an image with a smaller stripe_unit (to better distribute small writes in some workloads):: - rbd -p mypool create myimage --size 102400 --stripe-unit 65536 --stripe-count 16 + rbd create mypool/myimage --size 102400 --stripe-unit 65536 --stripe-count 16 To change an image from one image format to another, export it and then import it as the desired image format:: diff --git a/doc/rados/operations/erasure-code.rst b/doc/rados/operations/erasure-code.rst index b55cd6312134a..9925e21b2f1fb 100644 --- a/doc/rados/operations/erasure-code.rst +++ b/doc/rados/operations/erasure-code.rst @@ -137,7 +137,7 @@ because it requires partial writes. It is however possible to create an RBD image on an erasure coded pools when a replicated pool tier set a cache tier:: - $ rbd --pool ecpool create --size 10 myvolume + $ rbd create --size 10G ecpool/myvolume More information can be found in the `cache tiering <../cache-tiering>`_ documentation. diff --git a/doc/rados/operations/user-management.rst b/doc/rados/operations/user-management.rst index 287fb333b47f2..4257dc5ed2956 100644 --- a/doc/rados/operations/user-management.rst +++ b/doc/rados/operations/user-management.rst @@ -601,7 +601,7 @@ Ceph supports the following usage for user name and secret: preferred approach, because you can switch user names without switching the keyring path. For example:: - sudo rbd map foo --pool rbd myimage --id client.foo --keyring /path/to/keyring + sudo rbd map --id foo --keyring /path/to/keyring mypool/myimage .. _pools: ../pools diff --git a/doc/rbd/rados-rbd-cmds.rst b/doc/rbd/rados-rbd-cmds.rst index 32c65092890ab..37a70a3d4ad6b 100644 --- a/doc/rbd/rados-rbd-cmds.rst +++ b/doc/rbd/rados-rbd-cmds.rst @@ -21,18 +21,18 @@ Before you can add a block device to a node, you must create an image for it in the :term:`Ceph Storage Cluster` first. To create a block device image, execute the following:: - rbd create {image-name} --size {megabytes} --pool {pool-name} + rbd create --size {megabytes} {pool-name}/{image-name} For example, to create a 1GB image named ``bar`` that stores information in a pool named ``swimmingpool``, execute the following:: - rbd create bar --size 1024 --pool swimmingpool + rbd create --size 1024 swimmingpool/bar If you don't specify pool when creating an image, it will be stored in the default pool ``rbd``. For example, to create a 1GB image named ``foo`` stored in the default pool ``rbd``, execute the following:: - rbd create foo --size 1024 + rbd create --size 1024 foo .. note:: You must create a pool first before you can specify it as a source. See `Storage Pools`_ for details. @@ -60,21 +60,21 @@ Retrieving Image Information To retrieve information from a particular image, execute the following, but replace ``{image-name}`` with the name for the image:: - rbd --image {image-name} info + rbd info {image-name} For example:: - rbd --image foo info + rbd info foo To retrieve information from an image within a pool, execute the following, but replace ``{image-name}`` with the name of the image and replace ``{pool-name}`` with the name of the pool:: - rbd --image {image-name} -p {pool-name} info + rbd info {pool-name}/{image-name} For example:: - rbd --image bar -p swimmingpool info + rbd info swimmingpool/bar Resizing a Block Device Image ============================= @@ -85,7 +85,7 @@ a maximum capacity that you set with the ``--size`` option. If you want to increase (or decrease) the maximum size of a Ceph Block Device image, execute the following:: - rbd resize --image foo --size 2048 + rbd resize --size 2048 foo Removing a Block Device Image @@ -104,11 +104,11 @@ To remove a block device from a pool, execute the following, but replace ``{image-name}`` with the name of the image to remove and replace ``{pool-name}`` with the name of the pool:: - rbd rm {image-name} -p {pool-name} + rbd rm {pool-name}/{image-name} For example:: - rbd rm bar -p swimmingpool + rbd rm swimmingpool/bar diff --git a/doc/rbd/rbd-ko.rst b/doc/rbd/rbd-ko.rst index 3b5a236b94e76..5514a963624b5 100644 --- a/doc/rbd/rbd-ko.rst +++ b/doc/rbd/rbd-ko.rst @@ -20,17 +20,17 @@ Use ``rbd`` to map an image name to a kernel module. You must specify the image name, the pool name, and the user name. ``rbd`` will load RBD kernel module on your behalf if it's not already loaded. :: - sudo rbd map {image-name} --pool {pool-name} --id {user-name} + sudo rbd map {pool-name}/{image-name} --id {user-name} For example:: - sudo rbd map --pool rbd myimage --id admin + sudo rbd map rbd/myimage --id admin If you use `cephx`_ authentication, you must also specify a secret. It may come from a keyring or a file containing the secret. :: - sudo rbd map --pool rbd myimage --id admin --keyring /path/to/keyring - sudo rbd map --pool rbd myimage --id admin --keyfile /path/to/file + sudo rbd map rbd/myimage --id admin --keyring /path/to/keyring + sudo rbd map rbd/myimage --id admin --keyfile /path/to/file Show Mapped Block Devices diff --git a/doc/rbd/rbd-snapshot.rst b/doc/rbd/rbd-snapshot.rst index 62a7b98b54192..0f6fa39e1541b 100644 --- a/doc/rbd/rbd-snapshot.rst +++ b/doc/rbd/rbd-snapshot.rst @@ -58,12 +58,10 @@ Create Snapshot To create a snapshot with ``rbd``, specify the ``snap create`` option, the pool name and the image name. :: - rbd --pool {pool-name} snap create --snap {snap-name} {image-name} rbd snap create {pool-name}/{image-name}@{snap-name} For example:: - rbd --pool rbd snap create --snap snapname foo rbd snap create rbd/foo@snapname @@ -72,12 +70,10 @@ List Snapshots To list snapshots of an image, specify the pool name and the image name. :: - rbd --pool {pool-name} snap ls {image-name} rbd snap ls {pool-name}/{image-name} For example:: - rbd --pool rbd snap ls foo rbd snap ls rbd/foo @@ -87,12 +83,10 @@ Rollback Snapshot To rollback to a snapshot with ``rbd``, specify the ``snap rollback`` option, the pool name, the image name and the snap name. :: - rbd --pool {pool-name} snap rollback --snap {snap-name} {image-name} rbd snap rollback {pool-name}/{image-name}@{snap-name} For example:: - rbd --pool rbd snap rollback --snap snapname foo rbd snap rollback rbd/foo@snapname @@ -110,12 +104,10 @@ Delete a Snapshot To delete a snapshot with ``rbd``, specify the ``snap rm`` option, the pool name, the image name and the snap name. :: - rbd --pool {pool-name} snap rm --snap {snap-name} {image-name} rbd snap rm {pool-name}/{image-name}@{snap-name} For example:: - rbd --pool rbd snap rm --snap snapname foo rbd snap rm rbd/foo@snapname @@ -128,12 +120,10 @@ Purge Snapshots To delete all snapshots for an image with ``rbd``, specify the ``snap purge`` option and the image name. :: - rbd --pool {pool-name} snap purge {image-name} rbd snap purge {pool-name}/{image-name} For example:: - rbd --pool rbd snap purge foo rbd snap purge rbd/foo @@ -236,12 +226,10 @@ Clones access the parent snapshots. All clones would break if a user inadvertent deleted the parent snapshot. To prevent data loss, you **MUST** protect the snapshot before you can clone it. :: - rbd --pool {pool-name} snap protect --image {image-name} --snap {snapshot-name} rbd snap protect {pool-name}/{image-name}@{snapshot-name} For example:: - rbd --pool rbd snap protect --image my-image --snap my-snapshot rbd snap protect rbd/my-image@my-snapshot .. note:: You cannot delete a protected snapshot. @@ -253,8 +241,7 @@ To clone a snapshot, specify you need to specify the parent pool, image and snapshot; and, the child pool and image name. You must protect the snapshot before you can clone it. :: - rbd --pool {pool-name} --image {parent-image} --snap {snap-name} --dest-pool {pool-name} --dest {child-image} - rbd clone {pool-name}/{parent-image}@{snap-name} {pool-name}/{child-image-name} + rbd clone {pool-name}/{parent-image}@{snap-name} {pool-name}/{child-image-name} For example:: @@ -271,12 +258,10 @@ Before you can delete a snapshot, you must unprotect it first. Additionally, you may *NOT* delete snapshots that have references from clones. You must flatten each clone of a snapshot, before you can delete the snapshot. :: - rbd --pool {pool-name} snap unprotect --image {image-name} --snap {snapshot-name} rbd snap unprotect {pool-name}/{image-name}@{snapshot-name} For example:: - rbd --pool rbd snap unprotect --image my-image --snap my-snapshot rbd snap unprotect rbd/my-image@my-snapshot @@ -285,12 +270,10 @@ Listing Children of a Snapshot To list the children of a snapshot, execute the following:: - rbd --pool {pool-name} children --image {image-name} --snap {snap-name} rbd children {pool-name}/{image-name}@{snapshot-name} For example:: - rbd --pool rbd children --image my-image --snap my-snapshot rbd children rbd/my-image@my-snapshot @@ -303,12 +286,10 @@ the image by copying the information from the snapshot to the clone. The time it takes to flatten a clone increases with the size of the snapshot. To delete a snapshot, you must flatten the child images first. :: - rbd --pool {pool-name} flatten --image {image-name} rbd flatten {pool-name}/{image-name} For example:: - rbd --pool rbd flatten --image my-image rbd flatten rbd/my-image .. note:: Since a flattened image contains all the information from the snapshot, diff --git a/doc/start/quick-rbd.rst b/doc/start/quick-rbd.rst index ecdbf9bdea86b..a7fb0d9b33459 100644 --- a/doc/start/quick-rbd.rst +++ b/doc/start/quick-rbd.rst @@ -57,7 +57,7 @@ Configure a Block Device #. On the ``ceph-client`` node, map the image to a block device. :: - sudo rbd map foo --pool rbd --name client.admin [-m {mon-IP}] [-k /path/to/ceph.client.admin.keyring] + sudo rbd map foo --name client.admin [-m {mon-IP}] [-k /path/to/ceph.client.admin.keyring] #. Use the block device by creating a file system on the ``ceph-client`` node. :: -- 2.39.5