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. A boot through the initrd into stage 2, with one failed unit -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. A poweroff: units stopping under the targets waiting on them @@ -26,13 +17,15 @@ over the tree. A LUKS passphrase prompt floating over the initrd 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}"; };