Boot and install safety · WolOS Manual

Two system slots, signed boot images, quiet boot, and an installer that only touches what it planned.

What it is

WolOS keeps two copies of the system (slots) on one btrfs partition and boots the newest good one. Each slot starts from one signed image that holds the kernel, initramfs and command line.

Why

If an update fails to start three times, the other slot starts on its own. Signing the whole image means the command line and the system seal are covered by the signature too.

How

Nothing to do day to day. wol boot status shows the Secure Boot tier; wol boot enroll repeats the one-time key screen if you missed it. Other boot managers (rEFInd, another system's GRUB) can start WolOS.

Reference

Disk layout

GPT: partition 1 = ESP (1 GiB, FAT32, label WOLOS, mounted at /efi), partition 2 = btrfs (label WolOS). Subvolumes: @wolos-a (installed system), @home, @var; the first update creates @wolos-b. / is the slot the boot entry names (rootflags=subvol=@wolos-a); fstab mounts only /home, /var, /efi. The pacman database lives in the slot (DBPath = /usr/lib/pacman/), so each slot knows its own packages.

Boot entries

systemd-boot, timeout 0 (3 with another system on the disk), no default: entries share a sort key and sort by generation, so the newest good slot boots (ADR 0025). /usr/lib/wolos/esp-sync (pacman hook 95-wolos-esp, boot-setup, updates with --new) builds one image per kernel in EFI/wolos/ and writes:

Entry	Image	Notes
`wolos-<slot>+3.conf`	`wolos-<slot>.efi`	three tries; `version <generation>-<release>`
`wolos-<slot>-<pkgbase>.conf`	`wolos-<slot>-<pkgbase>.efi`	any other kernel installed with pacman

Words come from /etc/kernel/cmdline, the slot from /etc/wolos/slot; wolos.epoch=, the tier's words and wolos.seal= are added inside the image. A boot is good when wolos-boot-ok.service sees wold (login window) up, before boot-complete.target; systemd-bless-boot then drops the counter and wol boot bless moves the epoch floor. Three failed boots: the entry sorts last and the other slot boots.

Quiet boot

Kernel quiet splash loglevel=3 audit=0 rd.udev.log_level=3 systemd.show_status=auto vt.global_cursor_default=0; plymouth theme wolos (the mark on black) in a systemd initramfs.

Secure Boot

ADR 0025. install-boot runs boot-setup ROOT ESP after the seal; it prints the tier and writes plain words to /run/wolos/boot-note (the Install app shows that file).

Tier	When	First stage
`own-keys`	Setup Mode	our loader, signed with this computer's key, enrolled next to Microsoft's
`mok`	third-party CA in `db`	`wolos-shim`, then our signed loader as `grubx64.efi`; one key screen, word `boot`
`off`	neither, or `WOLOS_SECURE=no`	unsigned
`firmware`	Secure Boot on, nothing above fits	a firmware setting must change

Keys: /var/lib/wolos/secureboot (boot-keys create|open|close). boot-setup / /efi --enroll turns protection on later. wol boot status prints the JSON Settings reads. The firmware menu entry and tamper proofs are in wolos-iso/tests/test/.

Other boot managers

rEFInd finds EFI/systemd/systemd-bootx64.efi and EFI/wolos/*.efi on its own. Pick the first: it keeps try counting and rollback. GRUB of another system: copy /usr/share/wolos/boot/41_wolos to its /etc/grub.d/ and run its config update.

Install safety

Step	Script	Guarantee
list	`install-disks`	never the live medium, CDs, loop, zram or read-only disks
check	`install-check <disk>`	read-only; `refuse not-listed/too-small/in-use`; `os Windows/Linux/macOS/FreeBSD` from GPT types and filesystems; `secureboot on`
write	`install-run <disk>`	all checks before `systemd-repart --empty=force`; only the picked disk and its partitions are named; sleep and lid held off
plan	`install-run --plan FILE` (ADR 0023)	the disk must still match the plan's fingerprint; Alongside and Manual go through `wol install layout`, which names only the partitions in the plan and reads the table back after every step
verify	`install-run`	entry, kernel and initramfs on the ESP and fstab before `done`

Unattended: wolos.autoinstall=<disk> on the live command line (wolos-autoinstall.service), then power off. Tests: crates/controller/tests/image_install.rs (fake tools). VM: wolos-iso/tests/test-install.sh (bystander disk, BOOT PASS|FAIL). wolos-iso/tests/test-installer.sh: Windows-like and Linux-like disks, real partitioning on loop devices (layouts) and whole installs in a VM (run).

Key enrollment

wol boot enroll queues this computer's key with mokutil --import and sets the key screen to wait. boot-setup runs it during install and wolos-mok-enroll.service repeats it at each start until the key is enrolled. The password comes from wol boot password. The image carries the first stage in wolos-shim: a system without it never reports mok.