Chapter 2. Block Device Commands

There are two prerequisites that you must meet before you can use the Ceph Block Devices and the rbd command:

Use the rbd help command to display help for a particular rbd command and its subcommand:

rbd help <command> <subcommand>

[root@rbd-client ~]# rbd help <command> <subcommand>

Example

To display help for the snap list command:

rbd help snap list

[root@rbd-client ~]# rbd help snap list

Before using the block device client, ensure a pool for rbd exists and is enabled and initialized. To create an rbd pool, execute the following:

ceph osd pool create {pool-name} {pg-num} {pgp-num}
ceph osd pool application enable {pool-name} rbd
rbd pool init -p {pool-name}

[root@rbd-client ~]# ceph osd pool create {pool-name} {pg-num} {pgp-num}
[root@rbd-client ~]# ceph osd pool application enable {pool-name} rbd
[root@rbd-client ~]# rbd pool init -p {pool-name}

Before adding a block device to a node, create an image for it in the Ceph storage cluster. To create a block device image, execute the following command:

rbd create <image-name> --size <megabytes> --pool <pool-name>

[root@rbd-client ~]# rbd create <image-name> --size <megabytes> --pool <pool-name>

For example, to create a 1GB image named data that stores information in a pool named stack, run:

rbd create data --size 1024 --pool stack

[root@rbd-client ~]# rbd create data --size 1024 --pool stack

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

rbd ls

[root@rbd-client ~]# rbd ls

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

rbd ls {poolname}

[root@rbd-client ~]# rbd ls {poolname}

For example:

rbd ls swimmingpool

[root@rbd-client ~]# rbd ls swimmingpool

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

[root@rbd-client ~]# rbd --image {image-name} info

For example:

rbd --image foo info

[root@rbd-client ~]# rbd --image foo info

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

[root@rbd-client ~]# rbd --image {image-name} -p {pool-name} info

For example:

rbd --image bar -p swimmingpool info

[root@rbd-client ~]# rbd --image bar -p swimmingpool info

Ceph block device images are thin provisioned. They do not actually use any physical storage until you begin saving data to them. However, they do have a maximum capacity that you set with the --size option.

To increase or decrease the maximum size of a Ceph block device image:

rbd resize --image <image-name> --size <size>

[root@rbd-client ~]# rbd resize --image <image-name> --size <size>

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

rbd rm {image-name}

[root@rbd-client ~]# rbd rm {image-name}

For example:

rbd rm foo

[root@rbd-client ~]# 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:

rbd rm {image-name} -p {pool-name}

[root@rbd-client ~]# rbd rm {image-name} -p {pool-name}

For example:

rbd rm bar -p swimmingpool

[root@rbd-client ~]# rbd rm bar -p swimmingpool

RADOS Block Device (RBD) images can be moved to the trash using the rbd trash command. This command provides more options than the rbd rm command.

Once an image is moved to the trash, it can be removed from the trash at a later time. This helps to avoid accidental deletion.

To move an image to the trash execute the following:

rbd trash move {image-spec}

[root@rbd-client ~]# rbd trash move {image-spec}

Once an image is in the trash, it is assigned a unique image ID. You will need this image ID to specify the image later if you need to use any of the trash options. Execute the rbd trash list for a list of IDs of the images in the trash. This command also returns the image’s pre-deletion name.

In addition, there is an optional --image-id argument that can be used with rbd info and rbd snap commands. Use --image-id with the rbd info command to see the properties of an image in the trash, and with rbd snap to remove an image’s snapshots from the trash.

Remove an Image from the Trash

To remove an image from the trash execute the following:

rbd trash remove [{pool-name}/] {image-id}

[root@rbd-client ~]# rbd trash remove [{pool-name}/] {image-id}

Delay Trash Removal

Use the --delay option to set an amount of time before an image can be removed from the trash. Execute the following, except replace {time} with the number of seconds to wait before the image can be removed (defaults to 0):

rbd trash move [--delay {time}] {image-spec}

[root@rbd-client ~]# rbd trash move [--delay {time}] {image-spec}

Once the --delay option is enabled, an image cannot be removed from the trash within the specified timeframe unless forced.

Restore an Image from the Trash

As long as an image has not been removed from the trash, it can be restored using the rbd trash restore command.

Execute the rbd trash restore command to restore the image:

rbd trash restore [{pool-name}/] {image-id}

[root@rbd-client ~]# rbd trash restore [{pool-name}/] {image-id}

You can enable or disable image features, such as fast-diff, exclusive-lock, object-map, or journaling, on already existing images.

To enable a feature:

rbd feature enable <pool-name>/<image-name> <feature-name>

[root@rbd-client ~]# rbd feature enable <pool-name>/<image-name> <feature-name>

To disable a feature:

rbd feature disable <pool-name>/<image-name> <feature-name>

[root@rbd-client ~]# rbd feature disable <pool-name>/<image-name> <feature-name>

Examples

rbd object-map rebuild <pool-name>/<image-name>

[root@rbd-client ~]# rbd object-map rebuild <pool-name>/<image-name>

Ceph supports adding custom image metadata as key-value pairs. The pairs do not have any strict format.

Also, by using metadata, you can set the RBD configuration parameters for particular images. See Overriding the Default Configuration for Particular Images for details.

Use the rbd image-meta commands to work with metadata.

rbd image-meta set <pool-name>/<image-name> <key> <value>

[root@rbd-client ~]# rbd image-meta set <pool-name>/<image-name> <key> <value>

Example

rbd image-meta remove <pool-name>/<image-name> <key>

[root@rbd-client ~]# rbd image-meta remove <pool-name>/<image-name> <key>

Example

rbd image-meta get <pool-name>/<image-name> <key>

[root@rbd-client ~]# rbd image-meta get <pool-name>/<image-name> <key>

Example

rbd image-meta list <pool-name>/<image-name>

[root@rbd-client ~]# rbd image-meta list <pool-name>/<image-name>

Example

rbd image-meta set <pool-name>/<image-name> conf_<parameter> <value>

[root@rbd-client ~]# rbd image-meta set <pool-name>/<image-name> conf_<parameter> <value>

Example

See Block Device Configuration Reference for a list of possible configuration options.