Under the hood

Disk layout

The installer partitions the machine differently depending on its boot mode.

The root partition is labelled calaos-os and mounted with the options noatime,compress=zstd.

On UEFI, GRUB is installed in removable mode — into /EFI/BOOT/BOOTX64.EFI — to stay compatible with firmwares that handle custom boot entries poorly.

Btrfs subvolumes

The installer creates the following layout:

@                              main volume
@/.snapshots                   restore points
@/.snapshots/1/snapshot        the actually booted root (default subvolume)
@/boot/grub
@/opt
@/root
@/srv
@/tmp
@/usr/local
@/var/cache
@/var/log
@/var/spool
@/var/tmp

Copy-on-write is disabled on the @/var/* subvolumes, whose contents change constantly.

The system boots not from @ but from @/.snapshots/1/snapshot, set as the default subvolume. This indirection is what lets snapper point the root at another restore point without moving anything.

What a restore point covers

A restore point photographs the root subvolume. Separately mounted subvolumes are not part of it.

Conversely, since /var/log sits on a separate subvolume, the logs survive a rollback: this is what allows an incident to be analysed after working around it.

How restore points are created

Two mechanisms feed them:

• dpkg hooks — a restore point is created before every package operation, so on every calaos-os upgrade as well as every apt;
• snapper-timeline.timer — periodic points, independent of updates.

Point number 1 is created during installation, with the description First Root Filesystem Created at Installation.

Automatic retention

snapper-cleanup.timer does the housekeeping according to the configuration set at installation:

To read or change these values:

snapper -c root get-config
snapper -c root set-config "NUMBER_LIMIT=10"

Inspecting restore points

snapper list                 # list with dates and descriptions
snapper delete NUMBER        # delete one specific point
btrfs filesystem usage /     # real disk usage

Boot menu

grub-btrfsd watches the restore points and automatically regenerates the submenu offered at boot. The GRUB timeout is deliberately kept at 5 seconds to leave time to choose.

When you boot on a restore point, the root is mounted read-only, and an overlay layer receives temporary writes. Nothing is therefore modified until you confirm.

How rollback works

The calaos_rollback script:

1. checks that the machine really booted on a read-only restore point — otherwise it stops with the message Not booted from a readonly btrfs snapshot;
2. reads the restore point number from /proc/cmdline, in the form subvol=@/.snapshots/<number>/snapshot;
3. temporarily mounts the main volume and the restore points subvolume;
4. calls snapper rollback <number>, which makes that point the new root;
5. unmounts everything.

All that remains is to reboot onto the restored root.

The script is started either by the Calaos Home interface, which automatically displays a window in this context, or by hand from a terminal.

Maintenance tasks

Sources

This information comes from the scripts in the calaos-container repository, in particular scripts/calaos_install and scripts/calaos_rollback.