Tumbleweed rollback with Snapper & Btrfs

On openSUSE Tumbleweed, a risky zypper dup can be turned into a safe, recoverable operation thanks to the default Btrfs layout and Snapper’s pre/post snapshots. This guide walks through the steps, a concrete example, and the trade‑offs you should keep in mind.

Problem and Thesis

On a rolling‑release system like openSUSE Tumbleweed, zypper dup is the single command that pulls in the newest kernel, libraries, and userland updates. It is powerful but risky: a single mis‑packaged module can break the boot process, lock the system into a broken state, or corrupt critical configuration files. The default installation of Tumbleweed uses a Btrfs root filesystem with a set of subvolumes. Snapper, bundled with the snapper‑zypp plugin, automatically creates a pre‑update and a post‑update snapshot around every zypper dup. Treating these snapshots as a rollback plan, rather than an after‑thought backup, turns a potentially destructive operation into a recoverable one.

1. The Default Btrfs Layout

When you install Tumbleweed with the standard YaST or Agama installer, the root filesystem is a single Btrfs volume mounted at /. Inside this volume, the installer creates a handful of subvolumes:

/ – the root subvolume (named root in Btrfs terms)
/home, /var, /srv, etc. – optional separate subvolumes to keep user data and variable data isolated

Only the / subvolume is snapshot‑able by Snapper. This is why it is crucial to confirm the layout before you rely on snapshots. Run the following as root or with sudo to see the active subvolumes:

sudo btrfs subvolume list /

or, to confirm that / is indeed a Btrfs mount:

findmnt -t btrfs /

Both commands should show that the root path is a Btrfs subvolume named root and that /home (if present) is a separate subvolume. If you see a different layout, adjust the subsequent steps accordingly.

2. Snapper Pre/Post Snapshots with zypper dup

Snapper ships with a default configuration file at /etc/snapper/configs/root. The snapper‑zypp plugin hooks into zypper and, by default, creates a snapshot pair named pre‑dup and post‑dup around every transaction. The pair is identified by consecutive snapshot IDs. Example output from snapper list after a successful update might look like:

ID  Description          Event  Type
---  -----------------     -----  ----
 12  pre‑dup              dup    pre
 13  post‑dup             dup    post

When the system is bootable after the update, you can safely keep the pair or let Snapper’s cleanup policy delete it. If the update fails, the pair gives you a clear rollback path.

3. Booting into a Snapshot

GRUB is configured by the grub-btrfs package to add a menu entry for each snapshot. After an update that breaks the boot, you can select the snapshot that corresponds to the pre‑dup snapshot ID. The entry will look something like openSUSE Tumbleweed (Snapshot 12). Booting into that snapshot mounts the root subvolume in read‑write mode, allowing you to run snapper rollback from within the running system.

Verify that snapshot entries exist before relying on them:

grep -i snapshot /boot/grub2/grub.cfg

If you do not see any snapshot lines, reinstall grub-btrfs or re‑run the installer with the grub-btrfs option.

4. Worked Example

Below is a step‑by‑step example that demonstrates a typical failure scenario and how to recover. All commands are run as root or with sudo and assume the default Btrfs layout.

Take a manual snapshot before the update. This is optional because Snapper will create one automatically, but it gives you an extra safety net.
```
sudo snapper create -d 'Before dup'
```
Run the update. If you want to see what would change before actually applying it, use -D for a dry‑run.
```
sudo zypper dup
```
If the update fails and the system does not boot, reboot and choose the snapshot entry that matches the pre‑dup snapshot ID from the GRUB menu.
Once booted, list the snapshot pairs to identify the IDs involved.
```
sudo snapper list
```
Choose the pair. Suppose 12 is pre‑dup and 13 is post‑dup. You have two rollback options:
- Undo the file changes between the snapshots:
```
sudo snapper undochange 12..13
```
- Make the pre‑dup snapshot the new boot state:
```
sudo snapper rollback 12
```
The rollback command sets the default subvolume to the chosen snapshot and updates the GRUB configuration automatically.
Reboot. The system should now start from the snapshot, effectively restoring the state before the bad update.
Optional: delete the pair to free space.
```
sudo snapper delete 12 13
```

After the rollback, run sudo zypper patch to apply any critical patches that may have been missed during the failed update.

5. Trade‑Offs and Limitations

Snapshot Storage: Snapshots share the same Btrfs pool as the system. If you enable aggressive cleanup policies (e.g., timeline or number with high thresholds), the root filesystem can fill up. Monitor usage with btrfs filesystem df / and adjust the policy in /etc/snapper/configs/root.
Non‑Root Subvolumes: Snapper only snapshots the root subvolume. Data in /home or other subvolumes is not protected by these snapshots. If you need a full system backup, combine Snapper with external backup tools.
Version Sensitivity: The exact subvolume layout and GRUB snapshot support differ between the classic YaST installer and the newer Agama installer. Verify your layout with the commands in section 1 before proceeding.
Unsupported Repository Mixing: Do not mix Tumbleweed repositories with Leap or other distributions. Snapper’s rollback logic assumes a single distribution’s package set.
Rollback Risks: snapper rollback changes the default subvolume. If you run it on a snapshot that is not fully consistent (e.g., due to a partially applied update), you may end up with a broken system. Always verify the snapshot’s integrity by booting into it first.

6. Actionable Closing

Confirm your root is a Btrfs subvolume and that /home (if used) is separate.
Ensure grub-btrfs is installed and that snapshot entries appear in GRUB.
Verify that the snapper‑zypp plugin is active: snapper get-config root | grep plugin should list zypp.
Before a major zypper dup, run zypper dup -D to preview changes.
After a failed update, boot into the pre‑dup snapshot, run snapper rollback, and reboot.
Periodically prune old snapshots: sudo snapper cleanup or adjust the cleanup policy.

By treating Snapper snapshots as your first line of defense, you convert the inherent risk of a rolling‑release update into a manageable, recoverable operation. The combination of Btrfs’s efficient copy‑on‑write, Snapper’s automated snapshot pairs, and GRUB’s snapshot boot entries gives you a safety net that is both lightweight and effective.

Recovering from a Bad zypper dup on openSUSE Tumbleweed with Snapper & Btrfs