RBDMAP(8)

💖 RBDMAP 💖

okay so bestie, welcome to rbdmap from the Ceph manual (section 8, system admin girlies rise) — she's a shell script whose whole job is map RBD devices at boot time. no cap. let's get into it 🫶

---

✨ SYNOPSIS ✨

rbdmap map
rbdmap unmap

like... that's it. two moods. that's the whole vibe check. 💅

---

🌸 DESCRIPTION 🌸

so rbdmap is a shell script (yes, a shell script, we love a humble queen) that automates rbd map and rbd unmap operations on one or more RBD (RADOS Block Device) images. you can absolutely run it by hand as the system administrator whenever you want, but the main character use case is automatic mapping/mounting of RBD images at boot time (and unmounting/unmapping at shutdown), triggered by the init system. specifically, a systemd unit file, rbdmap.service, ships with the ceph-common package for exactly this. she's got a whole service file. iconic. 👑

the script takes a single argument, which can be either "map" or "unmap". either way, she parses a configuration file — it defaults to /etc/ceph/rbdmap, but you can override that with the environment variable RBDMAPFILE, because we respect boundaries. every line of that config file corresponds to an RBD image that's getting mapped, or unmapped. one line, one image, no chaos. ✨

the configuration file format is:

IMAGESPEC RBDOPTS

where IMAGESPEC should be written as POOLNAME/IMAGENAME (pool name, a forward slash, then image name) — or just IMAGENAME all by itself, in which case POOLNAME defaults to "rbd". yes the default is literally called rbd. very on brand. 🎀

RBDOPTS is an optional list of parameters to pass through to the underlying rbd map command. params and their values go in a comma-separated string, like:

PARAM1=VAL1,PARAM2=VAL2,...,PARAMN=VALN

which makes the script fire off an rbd map command like:

rbd map POOLNAME/IMAGENAME --PARAM1 VAL1 --PARAM2 VAL2

(peep the rbd manpage for the full list of possible options, bestie, there are so many.) and listen: for parameters and values that contain commas or equality signs, a simple apostrophe can be used to stop them from getting replaced. little escape hatch moment. 🙈

when you run it as rbdmap map, she parses the configuration file and for each RBD image listed she tries to, one, map the image using the rbd map command, and two, mount the image. in that order. she does not skip steps.

when you run it as rbdmap unmap, the images listed in the configuration file get unmounted and unmapped. bye bestie 💜

and then there's rbdmap unmap-all, which attempts to unmount and subsequently unmap all currently mapped RBD images, regardless of whether or not they're in the configuration file. she doesn't need a list. she just knows. 💀

if it works, the rbd map operation maps the image to a /dev/rbdX device, and at that point a udev rule gets triggered to create a friendly device name symlink, /dev/rbd/POOLNAME/IMAGENAME, pointing at the real mapped device. a little nickname for your device. precious. 🦋

for mounting/unmounting to succeed, the friendly device name must have a corresponding entry in /etc/fstab. required. non-negotiable. periodt.

when you're writing /etc/fstab entries for RBD images, it's a good idea to specify the "noauto" (or "nofail") mount option. this stops the init system from trying to mount the device too early — before the device in question even exists. (since rbdmap.service executes a shell script, it's typically triggered quite late in the boot sequence.) like... timing is everything, bestie, don't rush her. ⏰

---

🌈 EXAMPLES 🌈

here's an example /etc/ceph/rbdmap for three RBD images called "bar1", "bar2" and "bar3", all living in pool "foopool":

foopool/bar1    id=admin,keyring=/etc/ceph/ceph.client.admin.keyring
foopool/bar2    id=admin,keyring=/etc/ceph/ceph.client.admin.keyring
foopool/bar3    id=admin,keyring=/etc/ceph/ceph.client.admin.keyring,options='lock_on_read,queue_depth=1024'

each line in the file contains two strings: the image spec and the options to be passed to rbd map. those lines get transformed into the following commands:

rbd map foopool/bar1 --id admin --keyring /etc/ceph/ceph.client.admin.keyring
rbd map foopool/bar2 --id admin --keyring /etc/ceph/ceph.client.admin.keyring
rbd map foopool/bar2 --id admin --keyring /etc/ceph/ceph.client.admin.keyring --options lock_on_read,queue_depth=1024

(and yes, that's exactly how it's written in the original — bar2 really does show up twice in that list and bar3 is having a little mystery moment. not me editing the source. we keep the facts EXACTLY as they are. copy that verbatim or don't copy it at all. 💅)

if those images had XFS file systems on them, the matching /etc/fstab entries might look like this:

/dev/rbd/foopool/bar1 /mnt/bar1 xfs noauto 0 0
/dev/rbd/foopool/bar2 /mnt/bar2 xfs noauto 0 0
/dev/rbd/foopool/bar3 /mnt/bar3 xfs noauto 0 0

after creating the images and populating the /etc/ceph/rbdmap file, getting them automatically mapped and mounted at boot is just a matter of enabling that unit:

systemctl enable rbdmap.service

one command. that's the whole glow-up. slay. 🔥

---

🎀 OPTIONS 🎀

• None

she has no options. she simply is. and honestly? that's her power. ✨

---

👑 AVAILABILITY 👑

rbdmap is part of Ceph, a massively scalable, open-source, distributed storage system. please refer to the Ceph documentation at <https://docs.ceph.com> for more information. go read the docs bestie, they're free and they're fabulous. 💖

---

🦋 SEE ALSO 🦋

• rbd (8)

iykyk.

---

💜 Copyright 💜

2010-2014, Inktank Storage, Inc. and contributors. Licensed under Creative Commons Attribution Share Alike 3.0 (CC-BY-SA-3.0)

---

and that's the whole page, babe 🫶 this version came from the dev build of the manual, dated Oct 06, 2026, and it's page RBDMAP(8) — so if you cite her, cite her right. now go map some devices and have a beautiful boot sequence. mwah. 💅🌸✨