fix: deal with scripted initrd changes in nixos unstable

This commit is contained in:
Willem Vanhulle committed 2026-10-25 12:03:39 +01:00
1 parent 631315ffe1
commit 4dad85473b
9 files changed
+339 -191

No files matched your search

+94
View File
@@ -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.
+93
View File
@@ -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 <path>` | Read the settings from another file than `/etc/bootvine.toml`. |
| `--hold <duration>` | Override `timing.keep-final-frame-for`, e.g. `3s`. |
| `--target <unit>` | 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.
+78
View File
@@ -0,0 +1,78 @@
# Development
## Setup
Work inside the dev shell (`direnv allow` once). Version control is jj, not
the `git` CLI.
## Before committing
```sh
cargo clippy --workspace --all-targets
cargo fmt --all
```
Clippy runs with the pedantic lints and forbids absolute paths; formatting
needs the nightly toolchain the dev shell provides.
Commit messages follow [Conventional Commits](https://www.conventionalcommits.org).
jj does not run git hooks, so check the commits you are about to push with:
```sh
nix run .#check-conventional-commits -- origin/main..HEAD
```
Git users can install the same commit-message check and a formatting check as
hooks with `prek install` (from the dev shell) or `pre-commit install`.
## Continuous integration
`.woodpecker/rust-and-flake-checks.yaml` runs on Codeberg for every push and
pull request: the bootvine build with its tests, the xtask build, clippy,
rustfmt, an evaluation of every flake output, and the commit-message check on
pull requests. Builds on `main` are pushed to the `wvhulle` Cachix cache, which
`nixConfig` in `flake.nix` offers as a substituter. The two VM checks need KVM,
which Codeberg's runners lack, so they only run locally.
## Testing
| What | Command |
| --- | --- |
| Model and render tests | `cargo test --workspace` |
| Scripted demos | `cargo run --example boot` (also `shutdown`, `luks`) |
| Sample machine in a window | `nix run .#sample-machine-vm` |
| Boot and shutdown in a VM | `nix build .#checks.x86_64-linux.vm-boot-and-shutdown` |
| Passphrase prompt in a VM | `nix build .#checks.x86_64-linux.vm-luks-passphrase` |
To watch your own user manager start the sample units:
```sh
units=$(nix build --no-link --print-out-paths .#sample-unit-files)
systemctl --user link --runtime $units/*
systemctl --user start --no-block bootvine-demo.target
cargo run -- --user --target bootvine-demo.target --hold 3s
systemctl --user stop $(ls $units)
systemctl --user disable --runtime $(ls $units)
```
The VM checks read the console as text, hold the boot at fixed points and wait
on marker files instead of sleeping. To step through one by hand, run
`nix run .#checks.x86_64-linux.vm-boot-and-shutdown.driverInteractive` and
call `test_script()`.
Prefix VM and recording commands with `env -u LD_LIBRARY_PATH` when your shell
exports libraries that clash with QEMU or Chromium.
## Repository tasks
- `nix run .#record-screencasts` re-records the README animations from the
scripted demos and copies the passphrase screenshot from the VM check.
- `cargo xtask install --destdir <dir> --initrd dracut` stages an install
without touching the system; `cargo xtask uninstall --destdir <dir>` removes
it again.
## Code style and design
- [Code style](style.md).
- [Architecture](architecture.md): the event loop, the console
takeover and the workarounds for systemd's private socket.
+114
View File
@@ -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 <dir>` stages the files under `<dir>` 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.
+10
View File
@@ -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.