How upgrades work

An upgrade is applied to a snapshot and takes effect on the next start. The running system is never immutable, and a failed upgrade undoes itself.

Deployments

The root file system is a btrfs subvolume, joe/deploy/ID, called a deployment. /home and /var are separate subvolumes, shared by every deployment. /etc belongs to the deployment, so configuration rolls back with the system.

dave’s database is inside the deployment, in /usr/lib/dave/db, so every snapshot carries the database that describes exactly its own contents. That is also why nothing under /var may be packaged, and why system users have fixed ids: /var is shared by deployments that may disagree about everything else.

Installing and removing

dave install and dave remove take effect at once. Before they change anything, the system as it is becomes a deployment you can start, so there is always a way back.

Upgrades lose nothing

dave upgrade only records a plan, after proving it applies. At shutdown, dave-finalize.service snapshots the root as it is at that moment and applies the plan to the snapshot. Anything changed between dave upgrade and the restart is therefore in the new system; there is no merge step.

The boot entry for the new deployment is written last. A power cut at any earlier point starts the old system, with the upgrade still pending.

A newer systemd-boot in the upgraded system replaces the one on the EFI system partition at the same moment, and only ever a newer one, because every deployment is started by the same loader.

The boot loader keeps the health record

Each deployment has one systemd-boot entry, loader/entries/joe-ID.conf. dave keeps no record of its own that could drift from it: priority and health are both in the entry.

Priority. Entries are ordered by a priority that is raised whenever a deployment is chosen. Activating an upgrade and rolling back are the same operation, and a rollback lasts.

Health. A new deployment is written as joe-ID+3.conf: three tries. systemd-boot counts the suffix down on each attempt, and dave-boot-check.service runs before systemd marks the boot good. If the check fails, the machine restarts.

Entry Means
joe-42+3.conf new, three tries left
joe-42+2-1.conf one boot failed, two tries left
joe-42+1-2.conf two failed, one left
joe-42+0-3.conf out of tries: systemd-boot starts what was chosen before
joe-42.conf passed its check; the suffix is removed by systemd-bless-boot

A root that cannot be mounted at all takes the same path, through the kernel’s panic timeout.

Not immutable

Nothing here makes the running system read-only. You change it as you would any other distribution, by editing /etc or adding files anywhere; the snapshot at shutdown takes the system as it is then. Packaged files are sealed, which means they can be replaced or deleted but not modified in place.

What this design assumes about systemd-boot is pinned by a test in a virtual machine, and so are upgrades, rollbacks, power loss and recovery (Building from source lists the tests).