How to roll back a Ceph RBD image to a snapshot

Restoring a Ceph RBD image from a snapshot is a storage recovery step, not an ordinary file undo. It is used when a virtual machine disk, mounted block device, or test image must return to the exact block state captured before a failed change.

rbd snap rollback rewrites the image content back to the selected pool/image@snapshot checkpoint. The operation works at the block-image layer, so clients that still have the image open can keep stale caches or write new data over the recovered state.

Take the workload offline, confirm the snapshot name, and make the image unused before running the rollback. Large images take longer because Ceph scans the image's block address space, and cloning the snapshot can be the better recovery path when a fast alternate disk is acceptable.

Steps to roll back a Ceph RBD image to a snapshot:

Check cluster health before changing the image.

$ ceph -s
  cluster:
    id:     11111111-2222-3333-4444-555555555555
    health: HEALTH_OK

  services:
    mon: 3 daemons, quorum ceph-node1,ceph-node2,ceph-node3
    mgr: ceph-node1(active), standbys: ceph-node2
    osd: 9 osds: 9 up, 9 in

  data:
    pools:   4 pools, 96 pgs
    objects: 262.15k objects, 1.1 TiB
    usage:   3.4 TiB used, 56 TiB / 60 TiB avail
    pgs:     96 active+clean

Delay the rollback when the cluster reports degraded, backfilling, remapped, full, or stuck PGs. Rollback rewrites image data and should not add recovery pressure to an unhealthy cluster.

List snapshots on the target image.

$ rbd snap ls rbd/vm-100-disk-0
SNAPID  NAME            SIZE    PROTECTED  TIMESTAMP
12      before-upgrade  64 GiB             Mon Jun 29 07:12:44 2026
13      after-test      64 GiB             Mon Jun 29 08:05:31 2026

The rollback target is the full snapshot spec rbd/vm-100-disk-0@before-upgrade. Pick the checkpoint that was created before the bad write or failed change.

Check which clients still have the image open.
```
$ rbd status rbd/vm-100-disk-0
Watchers:
    watcher=192.0.2.21:0/4213 client.314159 cookie=18446462598732840961
```
A watcher usually means a librbd, kernel RBD, hypervisor, or backup client still has the image open.
Unmount the file system from the Linux client.
```
$ sudo umount /mnt/rbd-data
```
For a virtual machine disk, shut down the VM or detach the disk from the hypervisor instead of unmounting a Linux path inside this shell.
Unmap the RBD device from the Linux client.
```
$ sudo rbd device unmap /dev/rbd0
```
Related: How to map a Ceph RBD image on Linux
Confirm that the image has no active watchers.
```
$ rbd status rbd/vm-100-disk-0
Watchers: none
```
Do not continue while a writer still has the image open. The rollback replaces image blocks newer than the snapshot, and any active client can overwrite the restored state after the command finishes.
Roll back the image to the selected snapshot.
```
$ rbd snap rollback rbd/vm-100-disk-0@before-upgrade
Rolling back to snapshot: 100% complete...done.
```
The command iterates through the image's block address space. For a very large image, consider cloning the snapshot and attaching the clone when a faster recovery handoff fits the workload.

Map the restored image on the Linux client.

$ sudo rbd device map rbd/vm-100-disk-0
/dev/rbd0

Mount the restored file system.
```
$ sudo mount /dev/rbd0 /mnt/rbd-data
```
Verify that the client sees the restored data.
```
$ cat /mnt/rbd-data/release.txt
version=before-upgrade
```
Start the application or virtual machine only after the restored file system or guest disk passes its normal consistency and application checks.