Basic Block Device Commands

The rbd command enables you to create, list, introspect 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 usingthe rbd command, see RBD – 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

  • On the admin node, use the ceph tool to create a pool.

  • On the admin node, use the rbd tool to initialize the pool for use by RBD:

  1. rbd pool init <pool-name>

Note

The rbd tool assumes a default pool name of ‘rbd’ when notprovided.

Create a Block Device User

Unless specified, the rbd command will access the Ceph cluster using the IDadmin. This ID allows full administrative access to the cluster. It isrecommended that you utilize a more restricted user wherever possible.

To create a Ceph user, with ceph specify the auth get-or-createcommand, user name, monitor caps, and OSD caps:

  1. ceph auth get-or-create client.{ID} mon 'profile rbd' osd 'profile {profile name} [pool={pool-name}][, profile ...]' mgr 'profile rbd [pool={pool-name}]'

For example, to create a user ID named qemu with read-write access to thepool vms and read-only access to the pool images, execute thefollowing:

  1. ceph auth get-or-create client.qemu mon 'profile rbd' osd 'profile rbd pool=vms, profile rbd-read-only pool=images' mgr 'profile rbd pool=images'

The output from the ceph auth get-or-create command will be the keyring forthe specified user, which can be written to /etc/ceph/ceph.client.{ID}.keyring.

Note

The user ID can be specified when using the rbd command byproviding the —id {id} optional argument.

Creating a Block Device Image

Before you can add a block device to a node, you must create an image for it inthe Ceph Storage Cluster first. To create a block device image, executethe following:

  1. rbd create --size {megabytes} {pool-name}/{image-name}

For example, to create a 1GB image named bar that stores information in apool named swimmingpool, execute the following:

  1. rbd create --size 1024 swimmingpool/bar

If you don’t specify pool when creating an image, it will be stored in thedefault pool rbd. For example, to create a 1GB image named foo stored inthe default pool rbd, execute the following:

  1. rbd create --size 1024 foo

Note

You must create a pool first before you can specify it as asource. See Storage Pools for details.

Listing Block Device Images

To list block devices in the rbd pool, execute the following(i.e., rbd is the default pool name):

  1. rbd ls

To list block devices in a particular pool, execute the following,but replace {poolname} with the name of the pool:

  1. rbd ls {poolname}

For example:

  1. rbd ls swimmingpool

To list deferred delete block devices in the rbd pool, execute thefollowing:

  1. rbd trash ls

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

  1. rbd trash ls {poolname}

For example:

  1. rbd trash ls swimmingpool

Retrieving Image Information

To retrieve information from a particular image, execute the following,but replace {image-name} with the name for the image:

  1. rbd info {image-name}

For example:

  1. 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:

  1. rbd info {pool-name}/{image-name}

For example:

  1. rbd info swimmingpool/bar

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, executethe following:

  1. rbd resize --size 2048 foo (to increase)
  2. rbd resize --size 2048 foo --allow-shrink (to decrease)

Removing a Block Device Image

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

  1. rbd rm {image-name}

For example:

  1. rbd rm foo

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:

  1. rbd rm {pool-name}/{image-name}

For example:

  1. rbd rm swimmingpool/bar

To defer delete a block device from a pool, execute the following, butreplace {image-name} with the name of the image to move and replace{pool-name} with the name of the pool:

  1. rbd trash mv {pool-name}/{image-name}

For example:

  1. rbd trash mv swimmingpool/bar

To remove a deferred block device from a pool, execute the following, butreplace {image-id} with the id of the image to remove and replace{pool-name} with the name of the pool:

  1. rbd trash rm {pool-name}/{image-id}

For example:

  1. rbd trash rm swimmingpool/2bf4474b0dc51

Note

  • You can move an image to the trash even it has snapshot(s) or activelyin-use by clones, but can not be removed from trash.

  • You can use –expires-at to set the defer time (default is now),and if its deferment time has not expired, it can not be removed unlessyou use –force.

Restoring a Block Device Image

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

  1. rbd trash restore {image-id}

For example:

  1. rbd trash restore 2bf4474b0dc51

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

  1. rbd trash restore {pool-name}/{image-id}

For example:

  1. rbd trash restore swimmingpool/2bf4474b0dc51

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

For example:

  1. rbd trash restore swimmingpool/2bf4474b0dc51 --image new-name