How restore points and recovery work

The technical side of Going back: when restore points are taken, what a rollback does to the disk, and how the recovery screen decides to appear.

Taking restore points

Restore points are BTRFS snapshots of the @ subvolume, which holds the system, managed by Snapper. They are taken:

• before and after every pacman transaction, by snap-pac, whatever started it: the Update Center, the App Store, an AUR helper or a terminal;
• by the update engine, before it starts a nightly update;
• by hand, from the Update Center's History tab.

A snapshot costs almost nothing when it is taken; it grows only as the files it covers change. Snapper keeps the 10 most recent numbered snapshots, plus up to 5 marked important, and snapper-cleanup.timer removes older ones. No snapshots are taken on a timer.

/home, the logs, the package cache and the snapshots themselves are separate subvolumes and are never part of a restore point. See Disk layout.

What a rollback does

SakuraOS boots a unified kernel image whose kernel command line is built in and always mounts subvol=@. Going back therefore changes what @ is, rather than which subvolume is booted:

1. The current @ is renamed to a name beginning @rollback-. It is kept, so that if going back was the wrong call, the system you left still exists.

2. A new, writable @ is created from the chosen snapshot.

3. The computer starts from the new @.

The newest of these kept copies stays for 30 days after the computer has started successfully; older ones are removed then. Each one holds on to the disk space of a whole system, so keeping them all would fill the disk over time.

Because the command line never changes, it stays inside the signed image, and the same mechanism works with Secure Boot on or off. A separate boot entry per snapshot would not: with Secure Boot on, systemd-stub ignores a command line passed from outside a signed image that has its own.

A rollback cannot happen while @ is mounted as the running system, so it is done in the initramfs, before the system mounts it. When you go back from the Update Center, it records the chosen snapshot number in /etc/sakura/rollback-request and restarts, and the initramfs carries it out.

The recovery screen

Recovery is a second unified kernel image, listed in the boot menu as SakuraOS Recovery. It lists snapshots and performs the rollback you choose.

The normal image also opens it by itself after failed starts. Early in every start, the initramfs increments a counter on the EFI system partition, in EFI/sakura/state. sakura-boot-success.service resets it once the login screen has started and is still running a short while later. If the counter passes 3, the next start opens the recovery screen, saying it was started because the machine has not started properly three times.

The threshold is three rather than one because a single failed start is usually a power cut or a held power button.

Kernel updates and rollback

The kernel images live on the EFI system partition, which is FAT and not part of any snapshot, while the kernel's modules live in @. After going back across a kernel update, the two can disagree: the newer kernel starts, but the restored system only has modules for the older one.

sakura-kernel-sync.service checks on every start whether the running kernel has its modules. If not, it rebuilds the boot image for the installed kernel and restarts once. A marker file stops it from restarting more than once for the same problem.

Useful commands

snapper -c root list            # every restore point
sudo btrfs subvolume list /     # subvolumes, including kept @rollback-* ones

Last checked against the SakuraOS release of 3 October 2026. If your system behaves differently from this page, the page is wrong: please report it.