Menu Close

Red Hat Training

A Red Hat training course is available for Red Hat Ceph Storage

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 Manually Installing Ceph Block Device 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.4, “Creating Block Device Images” for details.

2.2. Displaying Help

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

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

Example

To display help for the snap list command:

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

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

2.3. Creating Block Device Pools

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:

[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}
Note

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

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

[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:

[root@rbd-client ~]# rbd create data --size 1024 --pool stack
NOTE
Ensure a pool for rbd exists before creating an image. See Creating Block Device Pools for additional details.

2.5. Listing Block Device Images

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

[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:

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

For example:

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

2.6. Retrieving Image Information

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

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

For example:

[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:

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

For example:

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

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

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

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

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

For example:

[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:

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

For example:

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

2.9. Moving Block Device Images to the Trash

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:

[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:

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

Once an image is removed from the trash, it cannot be restored.

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):

[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:

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

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

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

To disable a feature:

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

Examples

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

    [root@rbd-client ~]# rbd feature enable data/image1 exclusive-lock
  • To disable the fast-diff feature on the image2 image in the data pool:

    [root@rbd-client ~]# rbd feature disable data/image2 fast-diff
Important

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

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

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

    [root@rbd-client ~]# rbd image-meta set data/dataset last_update 2016-06-06

Removing Image Metadata

To remove a metadata key-value pair:

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

    [root@rbd-client ~]# rbd image-meta remove data/dataset last_update

Getting a Value for a Key

To view a value of a key:

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

Example

  • To view the value of the last_update key:

    [root@rbd-client ~]# rbd image-meta get data/dataset last_update

Listing Image Metadata

To show all metadata on an image:

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

Example

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

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

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

    [root@rbd-client ~]# rbd image-meta set data/dataset conf_rbd_cache false

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