diff --git a/README.md b/README.md
index dad3de1..6c7272b 100644
--- a/README.md
+++ b/README.md
@@ -7,17 +7,8 @@ ones that ran.
-It needs systemd ≥ 246 as PID 1, libdbus and a virtual terminal (it draws on
-tty12). With a systemd initrd it starts about a second after the kernel and
-follows the boot through the switch to the real root; without one it starts in
-stage 2. While it runs it quiets the kernel console and systemd's status
-output, and restores both when it hands the console back. Kernel messages from
-before it starts still reach the screen; boot with `quiet`, or set
-`boot.consoleLogLevel = 3` on NixOS, to keep those to errors.
-
-It also follows shutdowns and reboots: the units being stopped, nested under
-the units that have to stop first, until systemd hands over to
-`systemd-shutdown`.
+It follows shutdowns and reboots too: the units being stopped, nested under the
+units that have to stop first.
@@ -26,13 +17,15 @@ over the tree.
+It needs systemd ≥ 246 as PID 1, libdbus and a virtual terminal. With a
+systemd initrd it shows the boot from about a second after the kernel starts.
+
## Try it without installing
Neither of these touches your system's boot.
-### Scripted boots in your terminal
-
-From a clone, with Rust installed (see step 1 of the Ubuntu install below):
+Play a scripted boot, poweroff and encrypted-root boot in your terminal, with
+Rust installed:
```sh
git clone https://codeberg.org/wvhulle/bootvine.git
@@ -42,161 +35,29 @@ cargo run --example shutdown
cargo run --example luks
```
-These play a scripted boot, a poweroff and a boot from an encrypted root, with
-no systemd involved. `q` quits. The encrypted root unlocks with the passphrase
-`demo`; `Esc` quits while it asks.
+`q` quits. The encrypted root unlocks with the passphrase `demo`; `Esc` quits
+while it asks.
-### A sample machine in a VM
-
-With Nix, and no clone needed:
+Or, with Nix, boot a sample NixOS machine with slow and failing units in a
+QEMU window:
```sh
nix run git+https://codeberg.org/wvhulle/bootvine#sample-machine-vm
```
-This boots a NixOS machine with bootvine and a set of slow and failing sample
-units in a QEMU window, from the initrd through stage 2. It logs in as root;
-`poweroff` shows the shutdown. Its disk image is kept in
-`~/.cache/bootvine-sample-machine.qcow2`.
+It logs in as root; `poweroff` shows the shutdown.
-## Install
+## Documentation
-### NixOS
-
-1. Add the flake to your system flake's inputs and pass its module in:
-
- ```nix
- {
- inputs.bootvine = {
- url = "git+https://codeberg.org/wvhulle/bootvine";
- inputs.nixpkgs.follows = "nixpkgs";
- };
-
- outputs = { nixpkgs, bootvine, ... }: {
- nixosConfigurations.my-host = nixpkgs.lib.nixosSystem {
- modules = [
- bootvine.nixosModules.default
- ./configuration.nix
- ];
- };
- };
- }
- ```
-
-2. Enable it in `configuration.nix`:
-
- ```nix
- {
- services.bootvine.enable = true;
- }
- ```
-
-3. Optionally, follow the boot from the initrd and keep early kernel messages
- to errors:
-
- ```nix
- {
- boot.initrd.systemd.enable = true;
- boot.consoleLogLevel = 3;
- }
- ```
-
-4. Rebuild and reboot:
-
- ```sh
- sudo nixos-rebuild switch --flake .#my-host
- ```
-
-### Ubuntu
-
-1. Install the build dependencies and Rust. The repository pins a nightly
- toolchain in `rust-toolchain.toml`, which rustup fetches on the first
- build:
-
- ```sh
- sudo apt install build-essential pkg-config libdbus-1-dev git curl
- curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
- ```
-
-2. Clone, build and install the binary and the systemd units, and enable
- them. `cargo xtask install` builds as you and asks `sudo` only for the
- copying and `systemctl enable`:
-
- ```sh
- git clone https://codeberg.org/wvhulle/bootvine.git
- cd bootvine
- cargo xtask install
- ```
-
- This is enough for bootvine to show stage 2 and shutdown. It installs
- `/usr/bin/bootvine` and `bootvine.service` and `bootvine-shutdown.service`
- in `/usr/lib/systemd/system`.
-
-3. Optionally, follow the boot from the initrd. This needs a dracut initramfs
- with systemd in it; initramfs-tools has no systemd, so on releases that use
- it bootvine starts in stage 2 only.
-
- ```sh
- cargo xtask install --initrd dracut
- sudo dracut --force
- ```
-
- This adds the dracut module in `/usr/lib/dracut/modules.d/90bootvine` and
- enables it in `/etc/dracut.conf.d/bootvine.conf`.
-
-4. Reboot.
-
-`cargo xtask uninstall` removes all of it again.
-
-### Other distributions
-
-Install as in the Ubuntu steps. For the initrd, use the dracut module as above,
-or on mkinitcpio run `cargo xtask install --initrd mkinitcpio`, which installs
-`/usr/lib/initcpio/install/sd-bootvine`, then add `sd-bootvine` after `systemd`
-in `HOOKS` in `/etc/mkinitcpio.conf` and run `sudo mkinitcpio -P`.
-`--destdir
` stages the files under `` instead, for packaging.
-
-## Configure
-
-`/etc/bootvine.toml`. Every key is optional; `bootvine defaults` prints them
-all with their defaults, and `bootvine defaults --format nix` prints the same as
-a Nix attribute set. A file that changes two of them:
-
-```toml
-[colors.tree]
-running-marker = "light-yellow"
-
-[timing]
-keep-final-frame-for = "500ms"
-```
-
-Each `[colors.*]` table covers one part of the screen: `header`, the finished
-`stages`, the unit `tree`, the `timeline`, the `footer` tallies and the
-`password` popup. Values are the 16 console colour names. To change how those look, set the console palette: `console.colors` on
-NixOS, or the `vt.default_red`, `_grn` and `_blu` kernel parameters elsewhere.
-
-`keep-finished-units-for` is how long a finished unit stays in the tree, faded,
-before it leaves. Runs shorter than `hide-runs-shorter-than` get no timer and no
-timeline bar. `keep-final-frame-for` is how long the last frame stays before the
-console is handed back; `--hold` overrides it. When a display manager is
-starting, bootvine instead waits for it to switch to its own terminal, up to
-`wait-for-display-manager`, so the console's status lines never show in
-between.
-
-`bootvine check /etc/bootvine.toml` reports unknown keys and bad values; at
-boot, bootvine ignores an invalid file and uses the defaults. The initrd hooks
-copy the file into the initramfs, so rebuild it after editing.
-
-On NixOS, set the same tables under `services.bootvine.settings`; the rebuild
-fails if `bootvine check` rejects them:
-
-```nix
-services.bootvine.settings = {
- colors.tree.running-marker = "light-yellow";
- timing.keep-final-frame-for = "500ms";
-};
-```
+- [Install](https://codeberg.org/wvhulle/bootvine/src/branch/main/docs/install.md)
+ on NixOS, Ubuntu and other distributions.
+- [Configuration](https://codeberg.org/wvhulle/bootvine/src/branch/main/docs/configuration.md)
+ of colours, timing and the console.
+- [Architecture](https://codeberg.org/wvhulle/bootvine/src/branch/main/docs/architecture.md):
+ how bootvine follows the boot and takes the console.
+- [Development](https://codeberg.org/wvhulle/bootvine/src/branch/main/docs/development.md)
+ and the [code style](https://codeberg.org/wvhulle/bootvine/src/branch/main/docs/style.md).
## License
-See [LICENSE](LICENSE).
+[GPL-3.0-or-later](https://codeberg.org/wvhulle/bootvine/src/branch/main/LICENSE).
diff --git a/docs/architecture.md b/docs/architecture.md
new file mode 100644
index 0000000..8e04f50
--- /dev/null
+++ b/docs/architecture.md
@@ -0,0 +1,94 @@
+# Architecture
+
+How bootvine follows a boot and a shutdown, and what it changes on the console
+while it does. None of this is needed to install or configure it.
+
+## Requirements
+
+- **systemd ≥ 246 as PID 1.** bootvine reads the jobs and units from the
+ service manager over D-Bus.
+- **libdbus.** It talks to PID 1 over systemd's private socket, which zbus
+ cannot use; see [systemd's private socket](#systemds-private-socket).
+- **A virtual terminal.** It draws on `tty12` and switches the console to it.
+
+## Lifecycle
+
+### Boot
+
+1. **Start.** `bootvine.service` is wanted by `sysinit.target` and has no
+ default dependencies, so it starts early. With a systemd initrd it starts
+ there, about a second after the kernel; without one it starts in stage 2.
+2. **Switch to the real root.** In the initrd, bootvine survives the switch
+ and keeps drawing; the tree moves the initrd into the finished stages.
+3. **Stage 2.** The tree shows the jobs still pending under the default
+ target, nested under the units waiting on them.
+4. **Handover.** bootvine hands the console back once the default target is
+ reached and the final frame has stayed for `keep-final-frame-for`. When a
+ display manager is starting, it waits instead for the display manager to
+ switch to its own terminal, up to `wait-for-display-manager`.
+
+### Shutdown
+
+`shutdown.target` conflicts with `bootvine.service` and wants
+`bootvine-shutdown.service`, which runs `bootvine --shutdown`. It shows the
+units being stopped, nested under the units that have to stop first, until
+systemd hands over to `systemd-shutdown`.
+
+## The console
+
+While it runs, bootvine:
+
+- **brings `tty12` to the foreground**, and takes it back if something else
+ switches away during the boot;
+- **quiets the kernel console** by setting the console log level in
+ `/proc/sys/kernel/printk` to 1, so only emergency messages reach the
+ screen, and sets it again if something raises it;
+- **silences systemd's status output** with the manager's `SetShowStatus`
+ call.
+
+It restores the log level and the status output when it hands the console
+back. Kernel messages from before it starts are already on screen; see
+[early kernel messages](configuration.md#early-kernel-messages).
+
+### Passphrase prompts
+
+bootvine acts as a systemd password agent: it watches
+`/run/systemd/ask-password` and answers requests, such as a LUKS unlock, in a
+popup over the tree. If another agent's prompt is already showing when it
+starts, it stays behind it and comes forward once the prompt is answered.
+
+## The units
+
+| Unit | Wanted by | Notable settings |
+| --- | --- | --- |
+| `bootvine.service` | `sysinit.target` | `IgnoreOnIsolate=yes`, `Before=display-manager.service`, process name `@bootvine` |
+| `bootvine-shutdown.service` | `shutdown.target` | `After=bootvine.service display-manager.service` |
+
+Both draw on `/dev/tty12` with `TTYReset=yes` and log to the journal.
+
+## One event loop
+
+Everything runs on one thread. The service manager, the keyboard, the frame
+timer, password prompts and termination each produce a stream of inputs; the
+streams are merged, applied in batches to a single screen state, and the screen
+is drawn once per batch. The live boot and the scripted demos share this loop
+and differ only in where their inputs come from.
+
+## systemd's private socket
+
+- zbus rejects it, because PID 1 sends under its well-known name rather than a
+ unique one. libdbus works.
+- libdbus sends its authentication handshake together with the first message,
+ which systemd leaves unread, so a no-reply ping goes out right after
+ connecting.
+
+## Surviving the switch to the real root
+
+Three things keep bootvine alive from the initrd into stage 2:
+
+- a process name starting with `@`, which systemd's switch-root spares from
+ being killed;
+- a unit that is not stopped on isolate (`IgnoreOnIsolate=yes`), since the
+ initrd isolates `initrd-switch-root.target`;
+- a chroot through a file descriptor to the new root, taken as soon as the
+ switch is queued.
diff --git a/docs/configuration.md b/docs/configuration.md
new file mode 100644
index 0000000..8b9962d
--- /dev/null
+++ b/docs/configuration.md
@@ -0,0 +1,93 @@
+# Configuration
+
+Every setting has a default, so bootvine needs no configuration. To change
+some, write only those keys:
+
+- **On NixOS**, under `services.bootvine.settings`. The module writes them to
+ `/etc/bootvine.toml` in the real root and the initrd, and the rebuild fails
+ if `bootvine check` rejects them.
+
+ ```nix
+ services.bootvine.settings = {
+ colors.tree.running-marker = "light-yellow";
+ timing.keep-final-frame-for = "500ms";
+ };
+ ```
+
+- **On other distributions**, in `/etc/bootvine.toml`:
+
+ ```toml
+ [colors.tree]
+ running-marker = "light-yellow"
+
+ [timing]
+ keep-final-frame-for = "500ms"
+ ```
+
+ Then check the file and, if bootvine runs in your initrd, rebuild the
+ initramfs, since the dracut and mkinitcpio hooks copy the file into it:
+
+ ```sh
+ bootvine check /etc/bootvine.toml
+ sudo dracut --force # or: sudo mkinitcpio -P
+ ```
+
+ At boot, bootvine ignores an invalid file and uses the defaults.
+
+## Defaults
+
+`bootvine defaults` prints every key with its default as TOML, and
+`bootvine defaults --format nix` prints the same as a Nix attribute set to
+paste into `services.bootvine.settings`.
+
+## Colours
+
+Each `[colors.*]` table covers one part of the screen:
+
+| Table | Part |
+| --- | --- |
+| `header` | the top line with the origin and total time |
+| `stages` | the finished stages, such as the initrd |
+| `tree` | the unit tree |
+| `timeline` | the timeline of the slowest units |
+| `footer` | the tallies of done, running, waiting and failed units |
+| `password` | the passphrase popup |
+
+Values are the 16 console colour names, such as `yellow`, `light-yellow`,
+`gray` and `dark-gray`. To change how those 16 colours look, set the console
+palette instead: `console.colors` on NixOS, or the `vt.default_red`,
+`vt.default_grn` and `vt.default_blu` kernel parameters elsewhere.
+
+## Timing
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `keep-finished-units-for` | `2s` | How long a finished unit stays in the tree, faded, before it leaves. |
+| `hide-runs-shorter-than` | `1s` | Runs shorter than this get no timer and no timeline bar. |
+| `keep-final-frame-for` | `1s` | How long the last frame stays before the console is handed back. |
+| `wait-for-display-manager` | `10s` | When a display manager is starting, how long to wait for it to switch to its own terminal instead, so the console's status lines never show in between. |
+
+## Early kernel messages
+
+bootvine silences the kernel console while it runs, but kernel messages from
+before it starts still reach the screen. To keep those to errors, boot with the
+`quiet` kernel parameter, or on NixOS set:
+
+```nix
+boot.consoleLogLevel = 3;
+```
+
+## Running it by hand
+
+The units run bootvine with its defaults. Run by hand, it takes these options:
+
+| Option | Meaning |
+| --- | --- |
+| `--config ` | Read the settings from another file than `/etc/bootvine.toml`. |
+| `--hold ` | Override `timing.keep-final-frame-for`, e.g. `3s`. |
+| `--target ` | Root the tree at this unit instead of the default target. |
+| `--user` | Watch your user service manager instead of PID 1. |
+| `--shutdown` | Follow a shutdown instead of a boot. |
+
+[Development](development.md#testing) shows how to watch your user manager
+start a set of sample units this way.
diff --git a/CONTRIBUTING.md b/docs/development.md
similarity index 69%
rename from CONTRIBUTING.md
rename to docs/development.md
index 093a1a5..9c1f1fb 100644
--- a/CONTRIBUTING.md
+++ b/docs/development.md
@@ -1,4 +1,4 @@
-# Contributing
+# Development
## Setup
@@ -71,30 +71,8 @@ exports libraries that clash with QEMU or Chromium.
without touching the system; `cargo xtask uninstall --destdir ` removes
it again.
-## Code style
+## Code style and design
-- No comments; names and call flow carry the intent.
-- Public fields over getters, durations over raw integers, existing crates over
- hand-written formatting.
-- Iterator and stream combinators over loops.
-
-## Design notes
-
-### One event loop
-
-Everything runs on one thread. The service manager, the keyboard, the frame
-timer, password prompts and termination each produce a stream of inputs; the
-streams are merged, applied in batches to a single screen state, and the screen
-is drawn once per batch. The live boot and the scripted demos share this loop
-and differ only in where their inputs come from.
-
-### systemd's private socket
-
-- zbus rejects it, because PID 1 sends under its well-known name rather than a
- unique one. libdbus works.
-- libdbus sends its authentication handshake together with the first message,
- which systemd leaves unread, so a no-reply ping goes out right after
- connecting.
-- Surviving the switch to the real root needs a process name starting with `@`,
- a unit that is not stopped on isolate, and a chroot through a file descriptor
- to the new root taken as soon as the switch is queued.
+- [Code style](style.md).
+- [Architecture](architecture.md): the event loop, the console
+ takeover and the workarounds for systemd's private socket.
diff --git a/docs/install.md b/docs/install.md
new file mode 100644
index 0000000..d0258e4
--- /dev/null
+++ b/docs/install.md
@@ -0,0 +1,114 @@
+# Install
+
+bootvine always shows stage 2 and shutdown. To show the boot from the initrd
+as well, the initrd has to run systemd.
+
+## NixOS
+
+1. Add the flake to your system flake's inputs and pass its module in:
+
+ ```nix
+ {
+ inputs.bootvine = {
+ url = "git+https://codeberg.org/wvhulle/bootvine";
+ inputs.nixpkgs.follows = "nixpkgs";
+ };
+
+ outputs = { nixpkgs, bootvine, ... }: {
+ nixosConfigurations.my-host = nixpkgs.lib.nixosSystem {
+ modules = [
+ bootvine.nixosModules.default
+ ./configuration.nix
+ ];
+ };
+ };
+ }
+ ```
+
+2. Enable it in `configuration.nix`:
+
+ ```nix
+ {
+ services.bootvine.enable = true;
+ }
+ ```
+
+ The initrd is a systemd initrd by default since NixOS 26.05, and the only
+ kind after it. On NixOS 25.11 and earlier, also set
+ `boot.initrd.systemd.enable = true` to show the boot from the initrd.
+
+3. Rebuild and reboot:
+
+ ```sh
+ sudo nixos-rebuild switch --flake .#my-host
+ ```
+
+## Ubuntu
+
+1. Install the build dependencies and Rust. The repository pins a nightly
+ toolchain in `rust-toolchain.toml`, which rustup fetches on the first
+ build:
+
+ ```sh
+ sudo apt install build-essential pkg-config libdbus-1-dev git curl
+ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+ ```
+
+2. Clone, build and install the binary and the systemd units, and enable
+ them. `cargo xtask install` builds as you and asks `sudo` only for the
+ copying and `systemctl enable`:
+
+ ```sh
+ git clone https://codeberg.org/wvhulle/bootvine.git
+ cd bootvine
+ cargo xtask install
+ ```
+
+ This installs `/usr/bin/bootvine`, and `bootvine.service` and
+ `bootvine-shutdown.service` in `/usr/lib/systemd/system`, which is enough
+ for stage 2 and shutdown.
+
+3. Optionally, show the boot from the initrd. This needs a dracut initramfs
+ with systemd in it; initramfs-tools has no systemd, so on releases that use
+ it bootvine starts in stage 2 only.
+
+ ```sh
+ cargo xtask install --initrd dracut
+ sudo dracut --force
+ ```
+
+ This adds the dracut module in `/usr/lib/dracut/modules.d/90bootvine` and
+ enables it in `/etc/dracut.conf.d/bootvine.conf`.
+
+4. Reboot.
+
+## Other distributions
+
+Install as in the Ubuntu steps, with your distribution's packages for a C
+toolchain, `pkg-config` and the libdbus headers.
+
+For the initrd, use the dracut module as above, or on mkinitcpio:
+
+1. Install the hook in `/usr/lib/initcpio/install/sd-bootvine`:
+
+ ```sh
+ cargo xtask install --initrd mkinitcpio
+ ```
+
+2. Add `sd-bootvine` after `systemd` in `HOOKS` in `/etc/mkinitcpio.conf`.
+
+3. Rebuild the initramfs:
+
+ ```sh
+ sudo mkinitcpio -P
+ ```
+
+## Packaging
+
+`cargo xtask install --destdir ` stages the files under `` instead of
+the root, and combines with `--initrd`.
+
+## Uninstall
+
+`cargo xtask uninstall` removes everything `cargo xtask install` put in place.
+On NixOS, remove `services.bootvine.enable` and rebuild.
diff --git a/docs/style.md b/docs/style.md
new file mode 100644
index 0000000..2d13592
--- /dev/null
+++ b/docs/style.md
@@ -0,0 +1,10 @@
+# Code style
+
+- No comments; names and call flow carry the intent.
+- Public fields over getters, durations over raw integers, existing crates over
+ hand-written formatting.
+- Iterator and stream combinators over loops.
+
+Clippy runs with the pedantic lints and forbids absolute paths; formatting
+needs the nightly toolchain the dev shell provides. See
+[Development](development.md#before-committing) for the commands.
diff --git a/nixos-module.nix b/nixos-module.nix
index 805c919..e3916e8 100644
--- a/nixos-module.nix
+++ b/nixos-module.nix
@@ -61,7 +61,7 @@ in
services.bootvine-shutdown.wantedBy = [ "shutdown.target" ];
};
- boot.initrd.systemd = lib.mkIf config.boot.initrd.systemd.enable {
+ boot.initrd.systemd = {
packages = [ cfg.package ];
storePaths = [ (lib.getExe cfg.package) ];
services.bootvine.wantedBy = [ "sysinit.target" ];
diff --git a/tests/sample-machine/machine.nix b/tests/sample-machine/machine.nix
index edf7b2b..5f6eed2 100644
--- a/tests/sample-machine/machine.nix
+++ b/tests/sample-machine/machine.nix
@@ -29,7 +29,6 @@ in
boot.consoleLogLevel = lib.mkForce 3;
boot.initrd.systemd = {
- enable = true;
services.demo-initrd-probe = {
description = "Slow hardware probe";
wantedBy = [ "initrd.target" ];
diff --git a/tests/vm-checks/luks.nix b/tests/vm-checks/luks.nix
index 1b29e82..897428c 100644
--- a/tests/vm-checks/luks.nix
+++ b/tests/vm-checks/luks.nix
@@ -21,7 +21,6 @@ in
services.bootvine.enable = true;
testing.initrdBackdoor = true;
- boot.initrd.systemd.enable = true;
boot.initrd.luks.devices = lib.mkVMOverride {
secret.device = "/dev/disk/by-uuid/${secretUuid}";
};