doc/rbd: refine rbd-snapshot.rst

Refine the text in rbd-snapshot.rst

https://tracker.ceph.com/issues/57001

Signed-off-by: Zac Dover <zac.dover@gmail.com>

1 files changed, 189 insertions, 137 deletions

diff --git a/doc/rbd/rbd-snapshot.rst b/doc/rbd/rbd-snapshot.rst
index 96dec81c87c..120dd8ec125 100644
--- a/doc/rbd/rbd-snapshot.rst
+++ b/doc/rbd/rbd-snapshot.rst
@@ -5,26 +5,29 @@
 .. index:: Ceph Block Device; snapshots
 
 A snapshot is a read-only logical copy of an image at a particular point in
-time: a checkpoint. One of the advanced features of Ceph block devices is
-that you can create snapshots of images to retain point-in-time state history.
-Ceph also supports snapshot layering, which allows you to clone images (e.g., a
-VM image) quickly and easily. Ceph block device snapshots are managed using the
-``rbd``  command and multiple higher level interfaces, including `QEMU`_,
-`libvirt`_, `OpenStack`_ and `CloudStack`_.
+time: a checkpoint. One of the advanced features of Ceph block devices is that
+you can create snapshots of images to retain point-in-time state history.  Ceph
+also supports snapshot layering, which allows you to clone images (for example,
+VM images) quickly and easily. Ceph block device snapshots are managed using
+the ``rbd`` command and several higher-level interfaces, including `QEMU`_,
+`libvirt`_, `OpenStack`_, and `CloudStack`_.
 
 .. important:: To use RBD snapshots, you must have a running Ceph cluster.
 
-.. note:: Because RBD does not know about any filesystem within an image
-          (volume), snapshots are only `crash-consistent` unless they are
-          coordinated within the mounting (attaching) operating system.
-          We therefore recommend that you pause or stop I/O before taking a snapshot.
-          If the volume contains a filesystem, it should be in an internally
-          consistent state before taking a snapshot.  Snapshots taken without
-          write quiescing may need an `fsck` pass before subsequent
-          mounting.  To quiesce `I/O` you can use `fsfreeze` command. See
-	  `fsfreeze(8)` man page for more details.
-	  For virtual machines, `qemu-guest-agent` can be used to automatically
-	  freeze file systems when creating a snapshot.
+
+.. note:: Because RBD is unaware of any file system within an image (volume),
+   snapshots are merely `crash-consistent` unless they are coordinated within
+   the mounting (attaching) operating system. We therefore recommend that you
+   pause or stop I/O before taking a snapshot.  
+   
+   If the volume contains a file system, the file system should be in an
+   internally consistent state before a snapshot is taken. Snapshots taken
+   without write quiescing could need an `fsck` pass before they are mounted
+   again. To quiesce I/O you can use `fsfreeze` command. See the `fsfreeze(8)`
+   man page for more details. 
+   
+   For virtual machines, `qemu-guest-agent` can be used to automatically freeze
+   file systems when creating a snapshot.
 
 .. ditaa::
 
@@ -41,19 +44,22 @@ Cephx Notes
 
 When `cephx`_ authentication is enabled (it is by default), you must specify a
 user name or ID and a path to the keyring containing the corresponding key. See
-:ref:`User Management <user-management>` for details. You may also set the
-``CEPH_ARGS`` environment variable to avoid re-entry of these parameters. ::
+:ref:`User Management <user-management>` for details. 
+
+.. prompt:: bash $
+
+	rbd --id {user-ID} --keyring /path/to/secret [commands]
+	rbd --name {username} --keyring /path/to/secret [commands]
 
-	rbd --id {user-ID} --keyring=/path/to/secret [commands]
-	rbd --name {username} --keyring=/path/to/secret [commands]
+For example:
 
-For example:: 
+.. prompt:: bash $
 
-	rbd --id admin --keyring=/etc/ceph/ceph.keyring [commands]
-	rbd --name client.admin --keyring=/etc/ceph/ceph.keyring [commands]
+	rbd --id admin --keyring /etc/ceph/ceph.keyring [commands]
+	rbd --name client.admin --keyring /etc/ceph/ceph.keyring [commands]
 
-.. tip:: Add the user and secret to the ``CEPH_ARGS`` environment 
-   variable so that you don't need to enter them each time.
+.. tip:: Add the user and secret to the ``CEPH_ARGS`` environment variable to
+   avoid re-entry of these parameters.
 
 
 Snapshot Basics
@@ -65,76 +71,97 @@ snapshots using the ``rbd`` command.
 Create Snapshot
 ---------------
 
-To create a snapshot with ``rbd``, specify the ``snap create`` option, the pool
-name and the image name.  ::
+To create a snapshot, use the ``rbd snap create`` command and specify the pool
+name, the image name, and the snap name:
 
-	rbd snap create {pool-name}/{image-name}@{snap-name}
+.. prompt:: bash $
 
-For example:: 
+   rbd snap create {pool-name}/{image-name}@{snap-name}
 
-	rbd snap create rbd/foo@snapname
+For example:
+
+.. prompt:: bash $
+
+   rbd snap create rbd/foo@snapname
 	
 
 List Snapshots
 --------------
 
-To list snapshots of an image, specify the pool name and the image name. ::
+To list the snapshots of an image, use the ``rbd snap ls`` command and specify
+the pool name and the image name:
 
-	rbd snap ls {pool-name}/{image-name}
+.. prompt:: bash $
 
-For example::
+   rbd snap ls {pool-name}/{image-name}
 
-	rbd snap ls rbd/foo
+For example:
 
+.. prompt:: bash $
 
-Rollback Snapshot
------------------
+   rbd snap ls rbd/foo
 
-To rollback to a snapshot with ``rbd``, specify the ``snap rollback`` option, the
-pool name, the image name and the snap name. ::
 
-	rbd snap rollback {pool-name}/{image-name}@{snap-name}
+Roll back Snapshot
+------------------
 
-For example::
+To roll back to a snapshot,  use the ``rbd snap rollback`` command and specify
+the pool name, the image name, and the snap name:
 
-	rbd snap rollback rbd/foo@snapname
+.. prompt:: bash $
 
+   rbd snap rollback {pool-name}/{image-name}@{snap-name}
 
-.. note:: Rolling back an image to a snapshot means overwriting 
-   the current version of the image with data from a snapshot. The 
-   time it takes to execute a rollback increases with the size of the 
-   image. It is **faster to clone** from a snapshot **than to rollback** 
-   an image to a snapshot, and is the preferred method of returning
-   to a pre-existing state.
+For example:
+
+.. prompt:: bash $
+
+   rbd snap rollback rbd/foo@snapname
+
+
+.. note:: Rolling back an image to a snapshot means overwriting the current
+   version of the image with data from a snapshot. The time it takes to execute
+   a rollback increases with the size of the image. It is **faster to clone**
+   from a snapshot **than to roll back** an image to a snapshot. Cloning from a
+   snapshot is the preferred method of returning to a pre-existing state.
 
 
 Delete a Snapshot
 -----------------
 
-To delete a snapshot with ``rbd``, specify the ``snap rm`` subcommand, the pool
-name, the image name and the snap name. ::
+To delete a snapshot, use the ``rbd snap rm`` command and specify the pool
+name, the image name, and the snap name:
 
-	rbd snap rm {pool-name}/{image-name}@{snap-name}
+.. prompt:: bash $
+
+   rbd snap rm {pool-name}/{image-name}@{snap-name}
 	
-For example:: 
+For example:
+
+.. prompt:: bash $
 
-	rbd snap rm rbd/foo@snapname
+   rbd snap rm rbd/foo@snapname
 
 
-.. note:: Ceph OSDs delete data asynchronously, so deleting a snapshot 
-   doesn't immediately free up the underlying OSDs' capacity.
+.. note:: Ceph OSDs delete data asynchronously, so deleting a snapshot  does
+   not immediately free up the capacity of the underlying OSDs. This process is
+   known as "snaptrim", and is referred to as such in ``ceph status`` output.
 
 Purge Snapshots
 ---------------
 
-To delete all snapshots for an image with ``rbd``, specify the ``snap purge``
-subcommand and the image name. ::
+To delete all snapshots, use the ``rbd snap purge`` command and specify the
+pool name and the image name:
+
+.. prompt:: bash $
+
+   rbd snap purge {pool-name}/{image-name}
 
-	rbd snap purge {pool-name}/{image-name}
+For example:
 
-For example:: 
+.. prompt:: bash $
 
-	rbd snap purge rbd/foo
+   rbd snap purge rbd/foo
 
 
 .. index:: Ceph Block Device; snapshot layering
@@ -145,10 +172,9 @@ Layering
 Ceph supports the ability to create many copy-on-write (COW) clones of a block
 device snapshot. Snapshot layering enables Ceph block device clients to create
 images very quickly. For example, you might create a block device image with a
-Linux VM written to it; then, snapshot the image, protect the snapshot, and
-create as many copy-on-write clones as you like. A snapshot is read-only, 
-so cloning a snapshot simplifies semantics--making it possible to create
-clones rapidly.
+Linux VM written to it, snapshot the image, protect the snapshot, and create as
+many copy-on-write clones as you like. A snapshot is read-only, so cloning a
+snapshot simplifies semantics, making it possible to create clones rapidly.
 
 
 .. ditaa::
@@ -163,29 +189,30 @@ clones rapidly.
            
                Parent                        Child
 
-.. note:: The terms "parent" and "child" refer to a Ceph block device snapshot (parent),
-   and the corresponding image cloned from the snapshot (child). These terms are
-   important for the command line usage below.
+.. note:: The terms "parent" and "child" refer to a Ceph block device snapshot
+   (parent) and the corresponding image cloned from the snapshot (child).
+   These terms are important for the command line usage below.
    
 Each cloned image (child) stores a reference to its parent image, which enables
-the cloned image to open the parent snapshot and read it.   
+the cloned image to open the parent snapshot and read it.
 
-A COW clone of a snapshot behaves exactly like any other Ceph block device
-image. You can read to, write from, clone, and resize cloned images. There are
-no special restrictions with cloned images. However, the copy-on-write clone of
-a snapshot depends on the snapshot, so you **MUST** protect the snapshot before
-you clone it. The following diagram depicts the process.
+A copy-on-write clone of a snapshot behaves exactly like any other Ceph
+block device image. You can read to, write from, clone, and resize cloned
+images. There are no special restrictions with cloned images. However, the
+copy-on-write clone of a snapshot depends on the snapshot, so you must 
+protect the snapshot before you clone it. The diagram below depicts this
+process.
 
-.. note:: Ceph only supports cloning of RBD format 2 images (i.e., created with
-   ``rbd create --image-format 2``).  The kernel client supports cloned images
-   beginning with the 3.10 release.
+.. note:: Ceph supports the cloning of only "RBD format 2" images (that is,
+   images created without specifying ``--image-format 1``). The Linux kernel
+   client supports cloned images beginning with the 3.10 release.
 
 Getting Started with Layering
 -----------------------------
 
-Ceph block device layering is a simple process. You must have an image. You must
-create a snapshot of the image. You must protect the snapshot. Once you have 
-performed these steps, you can begin cloning the snapshot.
+Ceph block device layering is a simple process. You must have an image. You
+must create a snapshot of the image. You must protect the snapshot. After you
+have performed these steps, you can begin cloning the snapshot.
 
 .. ditaa::
 
@@ -206,107 +233,132 @@ performed these steps, you can begin cloning the snapshot.
 
 
 The cloned image has a reference to the parent snapshot, and includes the pool
-ID,  image ID and snapshot ID. The inclusion of the pool ID means that you may
-clone snapshots  from one pool to images in another pool.
-
-
-#. **Image Template:** A common use case for block device layering is to create a
-   master image and a snapshot that serves as a template for clones. For example, 
-   a user may create an image for a Linux distribution (e.g., Ubuntu 12.04), and 
-   create a snapshot for it. Periodically, the user may update the image and create
-   a new snapshot (e.g., ``sudo apt-get update``, ``sudo apt-get upgrade``,
-   ``sudo apt-get dist-upgrade`` followed by ``rbd snap create``). As the image
-   matures, the user can clone any one of the snapshots.
-
-#. **Extended Template:** A more advanced use case includes extending a template
-   image that provides more information than a base image. For example, a user may
-   clone an image (e.g., a VM template) and install other software (e.g., a database,
-   a content management system, an analytics system, etc.) and then snapshot the 
-   extended image, which itself may be updated just like the base image.
-
-#. **Template Pool:** One way to use block device layering is to create a 
-   pool that contains master images that act as templates, and snapshots of those
-   templates. You may then extend read-only privileges to users so that they 
-   may clone the snapshots without the ability to write or execute within the pool.
-
-#. **Image Migration/Recovery:** One way to use block device layering is to migrate
-   or recover data from one pool into another pool.
+ID, the image ID, and the snapshot ID. The inclusion of the pool ID means that
+you may clone snapshots from one pool to images in another pool.
+
+#. **Image Template:** A common use case for block device layering is to create
+   a base image and a snapshot that serves as a template for clones. For
+   example: a user may create an image for a Linux distribution (for example,
+   Ubuntu 22.04) and create a snapshot of it. The user may occasionally update
+   the image and create a new snapshot (by using such commands as ``sudo
+   apt-get update``, ``sudo apt-get upgrade``, or ``sudo apt-get dist-upgrade``
+   followed by ``rbd snap create``). As the image matures, the user can clone
+   any one of the snapshots.
+
+#. **Extended Template:** A more advanced use case includes extending a
+   template image to provide more information than a base image. For
+   example, a user may clone an image (for example, a VM template) and install
+   other software (for example, a database, a content management system, an
+   analytics system) and then snapshot the extended image, which may itself be
+   updated just like the base image.
+
+#. **Template Pool:** One way to use block device layering is to create a pool
+   that contains (1) base images that act as templates and (2) snapshots of
+   those templates. You may then extend read-only privileges to users so that
+   they may clone the snapshots even though they do not have permissions that
+   allow them to write or execute within the pool.
+
+#. **Image Migration/Recovery:** One way to use block device layering is to
+   migrate or recover data from one pool into another pool.
 
 Protecting a Snapshot
 ---------------------
 
-Clones access the parent snapshots. All clones would break if a user inadvertently 
-deleted the parent snapshot. To prevent data loss, you **MUST** protect the
-snapshot before you can clone it. ::
+Clones access the parent snapshots. All clones would break if a user
+inadvertently deleted the parent snapshot. To prevent data loss, you must 
+protect the snapshot before you can clone it:
+
+.. prompt:: bash $
 
-	rbd snap protect {pool-name}/{image-name}@{snapshot-name}
+   rbd snap protect {pool-name}/{image-name}@{snapshot-name}
 
-For example::
+For example:
 
-	rbd snap protect rbd/my-image@my-snapshot
+.. prompt:: bash $
+
+   rbd snap protect rbd/foo@snapname
 
 .. note:: You cannot delete a protected snapshot.
 
 Cloning a Snapshot
 ------------------
 
-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. ::
+To clone a snapshot, specify the parent pool, the parent image, and the parent
+snapshot; and also the child pool together with the image name. You must
+protect the snapshot before you can clone it:
+
+.. prompt:: bash $
 
-	rbd clone {pool-name}/{parent-image}@{snap-name} {pool-name}/{child-image-name}
+   rbd clone {pool-name}/{parent-image-name}@{snap-name} {pool-name}/{child-image-name}
 	
-For example:: 
+For example:
 
-	rbd clone rbd/my-image@my-snapshot rbd/new-image
+.. prompt:: bash $
+
+   rbd clone rbd/foo@snapname rbd/bar
 	
-.. note:: You may clone a snapshot from one pool to an image in another pool. For example, 
-   you may maintain read-only images and snapshots as templates in one pool, and writeable
-   clones in another pool.
+
+.. note:: You may clone a snapshot from one pool to an image in another pool.
+   For example, you may maintain read-only images and snapshots as templates in
+   one pool, and writeable clones in another pool.
 
 Unprotecting a Snapshot
 -----------------------
 
-Before you can delete a snapshot, you must unprotect it first. Additionally,
+Before you can delete a snapshot, you must first unprotect it. 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. :: 
+flatten or delete each clone of a snapshot before you can unprotect the
+snapshot:
+
+.. prompt:: bash $
+
+   rbd snap unprotect {pool-name}/{image-name}@{snapshot-name}
 
-	rbd snap unprotect {pool-name}/{image-name}@{snapshot-name}
+For example:
 
-For example::
+.. prompt:: bash $
 
-	rbd snap unprotect rbd/my-image@my-snapshot
+   rbd snap unprotect rbd/foo@snapname
 
 
 Listing Children of a Snapshot
 ------------------------------
 
-To list the children of a snapshot, execute the following::
+To list the children of a snapshot, use the ``rbd children`` command and
+specify the pool name, the image name, and the snap name:
 
-	rbd children {pool-name}/{image-name}@{snapshot-name}
+.. prompt:: bash $
 
-For example::
+   rbd children {pool-name}/{image-name}@{snapshot-name}
 
-	rbd children rbd/my-image@my-snapshot
+For example:
+
+.. prompt:: bash $
+
+   rbd children rbd/foo@snapname
 
 
 Flattening a Cloned Image
 -------------------------
 
 Cloned images retain a reference to the parent snapshot. When you remove the
-reference from the child clone to the parent snapshot, you effectively "flatten"
-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. ::
+reference to the parent snapshot from the clone, you effectively "flatten" the
+clone by copying the data stored in 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 first flatten the child images (or delete them):
+
+.. prompt:: bash $
+
+   rbd flatten {pool-name}/{image-name}
 
-	rbd flatten {pool-name}/{image-name}
+For example:
 
-For example:: 
+.. prompt:: bash $
 
-	rbd flatten rbd/new-image
+   rbd flatten rbd/bar
 
-.. note:: Since a flattened image contains all the information from the snapshot, 
-   a flattened image will take up more storage space than a layered clone.
+.. note:: Since a flattened image contains all the data stored in the snapshot,
+   a flattened image takes up more storage space than a layered clone does.
 
 
 .. _cephx: ../../rados/configuration/auth-config-ref/