RBD image features and what each costs

Advanced⏱ ~17 minrbd

What you'll learn

Enumerate the RBD image features and their purpose
Check and modify features on an image
Match features to client capability
Diagnose a feature-related mount failure

Prerequisites

None — start here.

Verified against Ceph Tentacle 20.2.x · Ceph Squid 19.2.x (supported previous) · cephadm matches the verified Ceph release · podman 4.x · csi-rbd and csi-cephfs current · RBD / CephFS / RGW current (matches Ceph release) · Linux kernel 5.15+ (5.10 minimum) · Ubuntu 24.04 LTS (Ceph host baseline) · Debian 12 (Bookworm) (Ceph host baseline) · Rocky Linux / RHEL / AlmaLinux 9.x (Ceph host baseline) · Proxmox VE 9.x (cross-course integration) · Kubernetes 1.31+ (cross-course integration) · 2026-08-18

Why this matters in production

Feature mismatches between an image and a client produce a specific and initially baffling failure: the image exists, the credentials work, and the map fails anyway. Knowing the feature set and which clients support what turns that into a thirty-second diagnosis.

The features

rbd info rbd-vms/vm-disk-01
# features: layering, exclusive-lock, object-map, fast-diff, deep-flatten

Feature	Provides	Cost
`layering`	clones from snapshots	none
`exclusive-lock`	one writer at a time	lock coordination
`object-map`	tracks which objects exist	small memory, needs exclusive-lock
`fast-diff`	fast `rbd du` and diff	needs object-map
`deep-flatten`	flatten with snapshots present	none
`journaling`	RBD mirroring	substantial write overhead

The first five are the modern default set and are cheap. journaling is not enabled by default and should not be enabled unless you are using journal-based mirroring — it doubles writes.

What object-map actually buys

Without it, rbd du, rbd export, and rbd diff must probe every possible object to discover which exist. On a 10 TiB image that is 2.6 million probes.

With it, the image maintains a bitmap of existing objects:

rbd du rbd-vms/vm-disk-01     # instant with object-map, slow without

The same applies to clone flattening and to backup tooling that computes incremental differences. On large images the difference is minutes versus hours.

Managing features

rbd feature disable rbd-vms/vm-disk-01 object-map fast-diff
rbd feature enable  rbd-vms/vm-disk-01 exclusive-lock object-map fast-diff

# create with a specific set
rbd create --size 100G --image-feature layering,exclusive-lock rbd-vms/compat-image

# cluster-wide default for new images
ceph config set global rbd_default_features 61

Features have dependencies: object-map requires exclusive-lock, and fast-diff requires object-map. Disabling a dependency disables what depends on it.

Kernel client support

The kernel RBD client supports fewer features than librbd, and support depends on the kernel version:

rbd: image uses unsupported features: 0x38

That message means the image has features this kernel cannot handle. Either upgrade the kernel or create the image with a reduced feature set:

rbd create --size 100G --image-feature layering rbd-vms/kernel-safe
rbd map rbd-vms/kernel-safe

librbd — used by QEMU/KVM — supports everything, which is why this only bites kernel mounts.

Quiz

Knowledge check · 4 questions

Q1. `rbd map` fails with "image uses unsupported features". What is the cause?

The image header is corrupted, so the client cannot parse the feature bitmask it carries The credentials lack the capability that the image's enabled features require The kernel RBD client does not support one or more of the image's enabled features The pool is below min_size, so the image header cannot be read at all
Q2. Enabling the journaling feature on an image that is not being mirrored roughly halves its write throughput and buys nothing.

True False
Q3. Resolve a mapping failure on a bare-metal host.

A bare-metal host running an older enterprise kernel cannot map images from a pool where all images were created with default features. QEMU hosts using the same pool work fine. Upgrading the kernel requires a change window that is weeks away.
Q4. Why does the object-map feature require exclusive-lock?

Passing score: 75%. Answers are checked in this browser.

Production discipline

Standardise the feature set at image creation according to which client will use the image, and record the reason where a reduced set is used so it is restored after the constraint is lifted. Keep journaling off unless journal-based mirroring is in use — it is the one feature whose cost is large enough to matter.

Cross-course references

Kubernetes: CSI driver capabilities constrain volume features the same way kernel version does here
Linux: filesystem feature flags versus kernel support is the identical compatibility problem