Notice

This document is for a development version of Ceph.

Basic Block Device Commands

Therbd command enables you to create, list, inspect and remove blockdevice images. You can also use it to clone images, create snapshots,rollback an image to a snapshot, view a snapshot, etc. For details on usingtherbd command, seeRBD – Manage RADOS Block Device (RBD) Images fordetails.

Important

To use Ceph Block Device commands, you must have access toa running Ceph cluster.

Create a Block Device Pool

  1. Use theceph tool tocreate a pool.

  2. Use therbd tool to initialize the pool for use by RBD:

    rbdpoolinit<pool-name>

    Note

    Therbd tool assumes a default pool name of ‘rbd’ if no poolname is specified in the command.

Create a Block Device User

Unless otherwise specified, therbd command uses the Ceph user IDadminto access the Ceph cluster. Theadmin Ceph user ID allows fulladministrative access to the cluster. We recommend that you acess the Cephcluster with a Ceph user ID that has fewer permissions than theadmin Cephuser ID does. We call this non-admin Ceph user ID a “block device user” or“Ceph user”.

Tocreate a Ceph user, use thecephauthget-or-create command tospecify the Ceph user ID name, monitor caps (capabilities), and OSD caps(capabilities):

cephauthget-or-createclient.{ID}mon'profile rbd'osd'profile {profile name} [pool={pool-name}][, profile ...]'mgr'profile rbd [pool={pool-name}]'

For example: to create a Ceph user ID namedqemu that has read-write accessto the poolvms and read-only access to the poolimages, run thefollowing command:

cephauthget-or-createclient.qemumon'profile rbd'osd'profile rbd pool=vms, profile rbd-read-only pool=images'mgr'profile rbd pool=images'

The output from thecephauthget-or-create command is the keyring for thespecified Ceph user ID, which can be written to/etc/ceph/ceph.client.{ID}.keyring.

Note

Specify the Ceph user ID by providing the--id{id}argumentwhenusingthe``rbd command. This argument is optional.

Creating a Block Device Image

Before you can add a block device to a node, you must create an image for it intheCeph Storage Cluster. To create a block device image, run a command of this form:

rbdcreate--size{megabytes}{pool-name}/{image-name}

For example, to create a 1GB image namedbar that stores information in apool namedswimmingpool, run this command:

rbdcreate--size1024swimmingpool/bar

If you don’t specify a pool when you create an image, then the image will bestored in the default poolrbd. For example, if you ran this command, youwould create a 1GB image namedfoo that is stored in the default poolrbd:

rbdcreate--size1024foo

Note

You must create a pool before you can specify it as a source. SeeStorage Pools for details.

Listing Block Device Images

To list block devices in therbd pool, run the following command:

rbdls

Note

rbd is the default pool name, andrbdls lists the commandsin the default pool.

To list block devices in a particular pool, run the following command, butreplace{poolname} with the name of the pool:

rbdls{poolname}

For example:

rbdlsswimmingpool

To list “deferred delete” block devices in therbd pool, run thefollowing command:

rbdtrashls

To list “deferred delete” block devices in a particular pool, run thefollowing command, but replace{poolname} with the name of the pool:

rbdtrashls{poolname}

For example:

rbdtrashlsswimmingpool

Retrieving Image Information

To retrieve information from a particular image, run the following command, butreplace{image-name} with the name of the image:

rbdinfo{image-name}

For example:

rbdinfofoo

To retrieve information from an image within a pool, run the following command,but replace{image-name} with the name of the image and replace{pool-name} with the name of the pool:

rbdinfo{pool-name}/{image-name}

For example:

rbdinfoswimmingpool/bar

Note

Other naming conventions are possible, and might conflict with thenaming convention described here. For example,userid/<uuid> is apossible name for an RBD image, and such a name might (at the least) beconfusing.

Resizing a Block Device Image

Ceph Block Device images are thin provisioned. They don’t actually useany physical storage until you begin saving data to them. However, they do havea maximum capacity that you set with the--size option. If you want toincrease (or decrease) the maximum size of a Ceph Block Device image, run oneof the following commands:

Increasing the Size of a Block Device Image

rbdresize--size2048foo

Decreasing the Size of a Block Device Image

rbdresize--size2048foo--allow-shrink

Removing a Block Device Image

To remove a block device, run the following command, but replace{image-name} with the name of the image you want to remove:

rbdrm{image-name}

For example:

rbdrmfoo

Removing a Block Device from a Pool

To remove a block device from a pool, run the following command but replace{image-name} with the name of the image to be removed, and replace{pool-name} with the name of the pool from which the image is to beremoved:

rbdrm{pool-name}/{image-name}

For example:

rbdrmswimmingpool/bar

“Defer Deleting” a Block Device from a Pool

To defer delete a block device from a pool (which entails moving it to the“trash” and deleting it later), run the following command but replace{image-name} with the name of the image to be moved to the trash andreplace{pool-name} with the name of the pool:

rbdtrashmv{pool-name}/{image-name}

For example:

rbdtrashmvswimmingpool/bar

Removing a Deferred Block Device from a Pool

To remove a deferred block device from a pool, run the following command butreplace{image-id} with the ID of the image to be removed, and replace{pool-name} with the name of the pool from which the image is to beremoved:

rbdtrashrm{pool-name}/{image-id}

For example:

rbdtrashrmswimmingpool/2bf4474b0dc51

Note

  • You can move an image to the trash even if it has snapshot(s) or isactively in use by clones. However, you cannot remove it from the trashunder those conditions.

  • You can use--expires-at to set the deferment time (default isnow). If the deferment time has not yet arrived, you cannot remove theimage unless you use--force.

Restoring a Block Device Image

To restore a deferred delete block device in the rbd pool, run thefollowing command but replace{image-id} with the ID of the image:

rbdtrashrestore{image-id}

For example:

rbdtrashrestore2bf4474b0dc51

Restoring a Block Device Image in a Specific Pool

To restore a deferred delete block device in a particular pool, run thefollowing command but replace{image-id} with the ID of the image andreplace{pool-name} with the name of the pool:

rbdtrashrestore{pool-name}/{image-id}

For example:

rbdtrashrestoreswimmingpool/2bf4474b0dc51

Renaming an Image While Restoring It

You can also use--image to rename the image while restoring it.

For example:

rbdtrashrestoreswimmingpool/2bf4474b0dc51--imagenew-name

Brought to you by the Ceph Foundation

The Ceph Documentation is a community resource funded and hosted by the non-profitCeph Foundation. If you would like to support this and our other efforts, please considerjoining now.