Creating and Mounting a Block Device

This procedure creates a Ceph Block Device (RBD) image, maps it on a Linux client, and mounts a file system on it. Use it to try block storage on a new cluster. For day-to-day image management, see Ceph Block Device.

Prerequisites

A running Ceph cluster that reports HEALTH_OK.
A Linux client host that has the ceph-common package installed, and a copy of /etc/ceph/ceph.conf and of a keyring that is allowed to use the cluster. On a cephadm bootstrap host both files are in /etc/ceph; the keyring is ceph.client.admin.keyring.
A client host that is not also a host of the Ceph cluster, unless the client is a virtual machine. Mapping a block device with the kernel client on a host that runs Ceph daemons can cause a deadlock.

Procedure

On a cluster host, inside cephadm shell, create a pool for block device images. This example uses the pool name rbd1701:
```
ceph osd pool create rbd1701
```
The command prints pool 'rbd1701' created.
Initialize the pool for use by RBD:
```
rbd pool init rbd1701
```
The command prints nothing on success.
On the client host, create a 1 GB image:
```
rbd create rbd1701/image1701 --size 1G
```
The command prints nothing. rbd ls rbd1701 lists image1701.
Map the image to a block device:
```
rbd map rbd1701/image1701
```
The command prints the device name, for example /dev/rbd0. The next steps use the link /dev/rbd/rbd1701/image1701 that the ceph-common udev rule creates. If that link does not exist, use the /dev/rbdN name instead.
Create a file system on the device:
```
mkfs.ext4 /dev/rbd/rbd1701/image1701
```
The output ends with Writing superblocks and filesystem accounting information: done.
Create a mount point:
```
mkdir /mnt/ceph-block-device
```
Mount the file system:
```
mount /dev/rbd/rbd1701/image1701 /mnt/ceph-block-device
```
The command prints nothing on success.

Verification

List the mapped images:
```
rbd device list
```
The output shows image1701 in pool rbd1701 and the device that it is mapped to.
Confirm that the file system is mounted:
```
df -h /mnt/ceph-block-device
```
The output shows the /dev/rbd device mounted on /mnt/ceph-block-device with about 1 GB of space.

Troubleshooting

If rbd map reports RBD image feature set mismatch, the kernel on the client does not support every feature that is enabled on the image. Run the rbd feature disable command that the error message suggests, then map the image again.
If rbd map reports rbd: map failed: (2) No such file or directory or modprobe: FATAL: Module rbd not found, the client kernel has no rbd module. Run modprobe rbd, then map the image again.
If mkfs.ext4 or mount reports No such file or directory for /dev/rbd/rbd1701/image1701, the udev link was not created. Use the /dev/rbdN device name that rbd map printed.
If rbd commands hang or report an authentication error, check that /etc/ceph/ceph.conf and the keyring on the client are copies of the files on the cluster. Then check that the client can reach the Monitors over the network.

Next Steps

Map the image automatically at boot. See the rbdmap manpage.
Create a Ceph user for block device clients instead of using the admin user. See Basic Block Device Commands.

Additional Resources

Brought to you by the Ceph Foundation

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