# Boot and install safety

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

Source: https://wolos.pages.dev/manual/boot

## 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](/manual/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](/manual/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](/manual/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`.