Chapter 2. Block Device Commands

The rbd command enables you to create, list, introspect, and remove block device images. You can also use it to clone images, create snapshots, rollback an image to a snapshot, view a snapshot, and so on.

2.1. Prerequisites

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

Important

The Client Installation chapter also provides information on mounting and using Ceph Block Devices on client nodes. Execute these steps on client nodes only after creating an image for the Block Device in the Ceph Storage Cluster. See Section 2.2, “Creating Block Device Images” for details.

2.2. Creating Block Device Images

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>

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
Note

You must create a pool first before you can specify it as a source. See the Pools chapter in the Storage Strategies for Red Hat Ceph Storage 2 guide for details.

2.3. Listing Block Device Images

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

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}

For example:

rbd ls swimmingpool

2.4. Retrieving Image Information

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

For example:

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

For example:

rbd --image bar -p swimmingpool info

2.5. Resizing Block Device Images

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>

2.6. Removing Block Device Images

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}

For example:

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}

For example:

rbd rm bar -p swimmingpool

2.7. Enabling and Disabling Image Features

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>

To disable a feature:

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

Examples

  • To enable the exclusive-lock feature on the image1 image in the data pool:

    $ rbd feature enable data/image1 exclusive-lock
  • To disable the fast-diff feature on the image2 image in the data pool:

    $ rbd feature disable data/image2 fast-diff
Important

After enabling the fast-diff and object-map features, rebuild the object map:

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

The deep flatten feature can be only disabled on already existing images but not enabled. To use deep flatten, enable it when creating images.

2.8. Working with Image Metadata

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.

Setting Image Metadata

To set a new metadata key-value pair:

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

Example

  • To set the last_update key to the 2016-06-06 value on the dataset image in the data pool:

    $ rbd image-meta set data/dataset last_update 2016-06-06

Removing Image Metadata

To remove a metadata key-value pair:

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

Example

  • To remove the last_update key-value pair from the dataset image in the data pool:

    $ rbd image-meta remove data/dataset last_update

Getting a Value for a Key

To view a value of a key:

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

Example

  • To view the value of the last_update key:

    $ rbd image-meta get data/dataset last_update

Listing Image Metadata

To show all metadata on an image:

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

Example

  • To list metadata set on the dataset image in the data pool:

    $ rbd data/dataset image-meta list

Overriding the Default Configuration for Particular Images

To override the RBD image configuration settings set in the Ceph configuration file for a particular image, set the configuration parameters with the conf_ prefix as image metadata:

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

Example

  • To disable the RBD cache for the dataset image in the data pool:

    $ rbd image-meta set data/dataset conf_rbd_cache false

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

2.9. Displaying Help

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

rbd help <command> <subcommand>

Example

To display help for the snap list command:

$ rbd help snap list
Note

The -h option still displays help for all available commands.