Restoring an RBD image from an export

Advanced⏱ ~18 minrbd

What you'll learn

Import an exported image
Restore the image metadata the export omits
Reattach it to the workload
Verify the restore

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

Restoring under pressure is where the steps nobody documented become visible, and most of them are not the data transfer.

Importing

# Substitute your own value before running:
POOL=rbd-vms

rbd import /backups/pool_image01_20260818.raw "$POOL"/image01-restored

# from a remote host without landing locally
POOL=rbd-vms

ssh backup-host 'cat /backups/pool_image01_20260818.raw' | \
  rbd import - "$POOL"/image01-restored

# with the image features the workload expects
POOL=rbd-vms

rbd import --image-feature layering,exclusive-lock,object-map,fast-diff,deep-flatten \
  /backups/image01.raw "$POOL"/image01-restored

Import creates a new image. Restoring over the original requires
removing it first, which should be a deliberate decision rather than an
accident.

Metadata the export omits

Item	Recovered from
Image features	recorded separately, or set at import
Image size	implied by the file; verify it matches
Snapshots	not in the export; only the exported state
`rbd image-meta` entries	recorded separately
Striping parameters	recorded separately; set at import
The pool and image name	the restore procedure

# capture these at backup time so the restore has them
POOL=rbd-vms
IMAGE=vm-disk-01
rbd info ${POOL}/${IMAGE} > /backups/image01.info
rbd image-meta list ${POOL}/${IMAGE} > /backups/image01.meta

# and reapply at restore
POOL=rbd-vms

while read -r k v; do
  rbd image-meta set "$POOL"/image01-restored "$k" "$v"
done < <(awk 'NR>1 {print $1, $2}' /backups/image01.meta)

POOL=rbd-vms

rbd info "$POOL"/image01-restored
diff <(rbd info "$POOL"/image01-restored | grep -E 'size|features|order') \
     <(grep -E 'size|features|order' /backups/image01.info)

Reattaching

# kernel client
POOL=rbd-vms

rbd map "$POOL"/image01-restored
mount "/dev/rbd/$POOL/image01-restored" /mnt/restored

# libvirt: update the domain XML to the restored image
DOMAIN=vm-db-01
virsh domblklist ${DOMAIN}

The reattachment step is where restores overrun. The image is restored
in minutes and the VM configuration, the volume references in the
orchestrator, and the application's own expectations take longer.

Consumer	Reattachment
libvirt VM	edit the domain XML, restart the domain
Kubernetes PV	the PV references the image name; recreate or patch
OpenStack Cinder	the volume ID maps to an image name; update the database or re-create
A mapped kernel device	map and mount

Verifying

# the filesystem is intact
POOL=rbd-vms

mount "/dev/rbd/$POOL/image01-restored" /mnt/restored
df -h /mnt/restored
ls /mnt/restored
umount /mnt/restored

# the application starts
# — this is the only verification that means anything

# and the size and content match expectations
POOL=rbd-vms

rbd du "$POOL"/image01-restored

Quiz

Knowledge check · 4 questions

Q1. What usually dominates real RBD restore time?

The data transfer, since the export has to cross the network at whatever rate the backup target can serve Creating the target image, because a full-size image has to be provisioned before any of its restored objects can be written Verifying the checksum, which reads the whole restored image a second time before it can be handed back The reattachment — updating the hypervisor, orchestrator, or platform references that identify the image, which is rarely documented
Q2. Restoring to a new name and renaming afterwards is what keeps a restore from the wrong date harmless.

True False
Q3. Restore an RBD image under pressure.

A VM's disk image was corrupted by an application defect. A nightly export from two days ago exists on the backup host.
Q4. What should be captured at backup time that `rbd export` does not include?

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

Production discipline

Restore to a new image name and verify before replacing the original — rbd import refusing an existing target is a safety property worth keeping. Capture rbd info and rbd image-meta at backup time; the export file carries neither.

Cross-course references

Kubernetes: rebinding a restored volume to a PVC is the analogous slow step
Linux: restore procedures overrun on reconnection, not on data movement