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.

1. 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.

   Related: How to check Ceph cluster health

2. 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.

3. 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.

4. 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.

5. Unmap the RBD device from the Linux client.

   $ sudo rbd device unmap /dev/rbd0

   Related: How to map a Ceph RBD image on Linux

6. 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.

7. 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.

8. Map the restored image on the Linux client.

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

9. Mount the restored file system.

   $ sudo mount /dev/rbd0 /mnt/rbd-data

10. 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.