5 .. index:: Ceph Block Device; snapshots
7 A snapshot is a read-only copy of the state of an image at a particular point in
8 time. One of the advanced features of Ceph block devices is that you can create
9 snapshots of the images to retain a history of an image's state. Ceph also
10 supports snapshot layering, which allows you to clone images (e.g., a VM image)
11 quickly and easily. Ceph supports block device snapshots using the ``rbd``
12 command and many higher level interfaces, including `QEMU`_, `libvirt`_,
13 `OpenStack`_ and `CloudStack`_.
15 .. important:: To use use RBD snapshots, you must have a running Ceph cluster.
17 .. note:: If a snapshot is taken while `I/O` is still in progress in a image, the
18 snapshot might not get the exact or latest data of the image and the snapshot
19 may have to be cloned to a new image to be mountable. So, we recommend to stop
20 `I/O` before taking a snapshot of an image. If the image contains a filesystem,
21 the filesystem must be in a consistent state before taking a snapshot. To stop
22 `I/O` you can use `fsfreeze` command. See `fsfreeze(8)` man page for more details.
23 For virtual machines, `qemu-guest-agent` can be used to automatically freeze
24 filesystems when creating a snapshot.
26 .. ditaa:: +------------+ +-------------+
28 | Active |<-------*| Snapshot |
29 | Image | | of Image |
30 | (stop i/o) | | (read only) |
31 +------------+ +-------------+
37 When `cephx`_ is enabled (it is by default), you must specify a user name or ID
38 and a path to the keyring containing the corresponding key for the user. See
39 `User Management`_ for details. You may also add the ``CEPH_ARGS`` environment
40 variable to avoid re-entry of the following parameters. ::
42 rbd --id {user-ID} --keyring=/path/to/secret [commands]
43 rbd --name {username} --keyring=/path/to/secret [commands]
47 rbd --id admin --keyring=/etc/ceph/ceph.keyring [commands]
48 rbd --name client.admin --keyring=/etc/ceph/ceph.keyring [commands]
50 .. tip:: Add the user and secret to the ``CEPH_ARGS`` environment
51 variable so that you don't need to enter them each time.
57 The following procedures demonstrate how to create, list, and remove
58 snapshots using the ``rbd`` command on the command line.
63 To create a snapshot with ``rbd``, specify the ``snap create`` option, the pool
64 name and the image name. ::
66 rbd snap create {pool-name}/{image-name}@{snap-name}
70 rbd snap create rbd/foo@snapname
76 To list snapshots of an image, specify the pool name and the image name. ::
78 rbd snap ls {pool-name}/{image-name}
88 To rollback to a snapshot with ``rbd``, specify the ``snap rollback`` option, the
89 pool name, the image name and the snap name. ::
91 rbd snap rollback {pool-name}/{image-name}@{snap-name}
95 rbd snap rollback rbd/foo@snapname
98 .. note:: Rolling back an image to a snapshot means overwriting
99 the current version of the image with data from a snapshot. The
100 time it takes to execute a rollback increases with the size of the
101 image. It is **faster to clone** from a snapshot **than to rollback**
102 an image to a snapshot, and it is the preferred method of returning
103 to a pre-existing state.
109 To delete a snapshot with ``rbd``, specify the ``snap rm`` option, the pool
110 name, the image name and the snap name. ::
112 rbd snap rm {pool-name}/{image-name}@{snap-name}
116 rbd snap rm rbd/foo@snapname
119 .. note:: Ceph OSDs delete data asynchronously, so deleting a snapshot
120 doesn't free up the disk space immediately.
125 To delete all snapshots for an image with ``rbd``, specify the ``snap purge``
126 option and the image name. ::
128 rbd snap purge {pool-name}/{image-name}
132 rbd snap purge rbd/foo
135 .. index:: Ceph Block Device; snapshot layering
140 Ceph supports the ability to create many copy-on-write (COW) clones of a block
141 device shapshot. Snapshot layering enables Ceph block device clients to create
142 images very quickly. For example, you might create a block device image with a
143 Linux VM written to it; then, snapshot the image, protect the snapshot, and
144 create as many copy-on-write clones as you like. A snapshot is read-only,
145 so cloning a snapshot simplifies semantics--making it possible to create
149 .. ditaa:: +-------------+ +-------------+
151 | Snapshot | Child refers | COW Clone |
152 | of Image |<------------*| of Snapshot |
154 | (read only) | | (writable) |
155 +-------------+ +-------------+
159 .. note:: The terms "parent" and "child" mean a Ceph block device snapshot (parent),
160 and the corresponding image cloned from the snapshot (child). These terms are
161 important for the command line usage below.
163 Each cloned image (child) stores a reference to its parent image, which enables
164 the cloned image to open the parent snapshot and read it.
166 A COW clone of a snapshot behaves exactly like any other Ceph block device
167 image. You can read to, write from, clone, and resize cloned images. There are
168 no special restrictions with cloned images. However, the copy-on-write clone of
169 a snapshot refers to the snapshot, so you **MUST** protect the snapshot before
170 you clone it. The following diagram depicts the process.
172 .. note:: Ceph only supports cloning for format 2 images (i.e., created with
173 ``rbd create --image-format 2``). The kernel client supports cloned images
176 Getting Started with Layering
177 -----------------------------
179 Ceph block device layering is a simple process. You must have an image. You must
180 create a snapshot of the image. You must protect the snapshot. Once you have
181 performed these steps, you can begin cloning the snapshot.
183 .. ditaa:: +----------------------------+ +-----------------------------+
185 | Create Block Device Image |------->| Create a Snapshot |
187 +----------------------------+ +-----------------------------+
189 +--------------------------------------+
192 +----------------------------+ +-----------------------------+
194 | Protect the Snapshot |------->| Clone the Snapshot |
196 +----------------------------+ +-----------------------------+
199 The cloned image has a reference to the parent snapshot, and includes the pool
200 ID, image ID and snapshot ID. The inclusion of the pool ID means that you may
201 clone snapshots from one pool to images in another pool.
204 #. **Image Template:** A common use case for block device layering is to create a
205 a master image and a snapshot that serves as a template for clones. For example,
206 a user may create an image for a Linux distribution (e.g., Ubuntu 12.04), and
207 create a snapshot for it. Periodically, the user may update the image and create
208 a new snapshot (e.g., ``sudo apt-get update``, ``sudo apt-get upgrade``,
209 ``sudo apt-get dist-upgrade`` followed by ``rbd snap create``). As the image
210 matures, the user can clone any one of the snapshots.
212 #. **Extended Template:** A more advanced use case includes extending a template
213 image that provides more information than a base image. For example, a user may
214 clone an image (e.g., a VM template) and install other software (e.g., a database,
215 a content management system, an analytics system, etc.) and then snapshot the
216 extended image, which itself may be updated just like the base image.
218 #. **Template Pool:** One way to use block device layering is to create a
219 pool that contains master images that act as templates, and snapshots of those
220 templates. You may then extend read-only privileges to users so that they
221 may clone the snapshots without the ability to write or execute within the pool.
223 #. **Image Migration/Recovery:** One way to use block device layering is to migrate
224 or recover data from one pool into another pool.
226 Protecting a Snapshot
227 ---------------------
229 Clones access the parent snapshots. All clones would break if a user inadvertently
230 deleted the parent snapshot. To prevent data loss, you **MUST** protect the
231 snapshot before you can clone it. ::
233 rbd snap protect {pool-name}/{image-name}@{snapshot-name}
237 rbd snap protect rbd/my-image@my-snapshot
239 .. note:: You cannot delete a protected snapshot.
244 To clone a snapshot, specify you need to specify the parent pool, image and
245 snapshot; and, the child pool and image name. You must protect the snapshot
246 before you can clone it. ::
248 rbd clone {pool-name}/{parent-image}@{snap-name} {pool-name}/{child-image-name}
252 rbd clone rbd/my-image@my-snapshot rbd/new-image
254 .. note:: You may clone a snapshot from one pool to an image in another pool. For example,
255 you may maintain read-only images and snapshots as templates in one pool, and writeable
256 clones in another pool.
258 Unprotecting a Snapshot
259 -----------------------
261 Before you can delete a snapshot, you must unprotect it first. Additionally,
262 you may *NOT* delete snapshots that have references from clones. You must
263 flatten each clone of a snapshot, before you can delete the snapshot. ::
265 rbd snap unprotect {pool-name}/{image-name}@{snapshot-name}
269 rbd snap unprotect rbd/my-image@my-snapshot
272 Listing Children of a Snapshot
273 ------------------------------
275 To list the children of a snapshot, execute the following::
277 rbd children {pool-name}/{image-name}@{snapshot-name}
281 rbd children rbd/my-image@my-snapshot
284 Flattening a Cloned Image
285 -------------------------
287 Cloned images retain a reference to the parent snapshot. When you remove the
288 reference from the child clone to the parent snapshot, you effectively "flatten"
289 the image by copying the information from the snapshot to the clone. The time
290 it takes to flatten a clone increases with the size of the snapshot. To delete
291 a snapshot, you must flatten the child images first. ::
293 rbd flatten {pool-name}/{image-name}
297 rbd flatten rbd/my-image
299 .. note:: Since a flattened image contains all the information from the snapshot,
300 a flattened image will take up more storage space than a layered clone.
303 .. _cephx: ../../rados/configuration/auth-config-ref/
304 .. _User Management: ../../operations/user-management
305 .. _QEMU: ../qemu-rbd/
306 .. _OpenStack: ../rbd-openstack/
307 .. _CloudStack: ../rbd-cloudstack/
308 .. _libvirt: ../libvirt/