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

+22 -161
View File
@@ -7,17 +7,8 @@ ones that ran.
<img src="https://codeberg.org/wvhulle/bootvine/raw/branch/main/recordings/boot.gif" width="691" alt="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.
<img src="https://codeberg.org/wvhulle/bootvine/raw/branch/main/recordings/shutdown.gif" width="691" alt="A poweroff: units stopping under the targets waiting on them">
@@ -26,13 +17,15 @@ over the tree.
<img src="https://codeberg.org/wvhulle/bootvine/raw/branch/main/recordings/passphrase.png" width="640" alt="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 <dir>` stages the files under `<dir>` 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).
+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.
+5 -27
View File
@@ -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 <dir>` 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.
+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.
+1 -1
View File
@@ -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" ];
-1
View File
@@ -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" ];
-1
View File
@@ -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}";
};