Files
bootvine/docs/configuration.md
Willem Vanhulle 7e95cbd8e9 feat: show why units failed, with their last journal lines
Failed jobs keep their kind: units that broke or timed out get a failure
panel entry with the reason systemd reports (exit status, signal, timeout,
start limit, status text) and their last journal lines read through
libsystemd. Units that failed only through a dependency are dimmed and left
out of the panel, and units that crash after starting count as failed.

Restructure the repository around this:
- move the library and binary into bootvine/ and the scripted demos into
  their own unpublished scripted-demos crate, with their VHS tapes
- move the crane builds and NixOS module into nix/
- group each sample VM with its check under vm-tests/, adding text-console,
  scripted-initrd, encrypted-volume and failures machines and a vm-failures
  check
- add docs/guide.md walking through the screen with every recording, keep
  one recording in the README, and re-render all recordings
2026-10-30 14:59:10 +01:00

4.6 KiB

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.

    services.bootvine.settings = {
      colors.tree.running-marker = "light-yellow";
      timing.keep-final-frame-for = "500ms";
    };
    
  • On other distributions, in /etc/bootvine.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:

    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:

[colors.header]
origin = "white"
separators = "dark-gray"
total-time = "white"

[colors.stages]
branches = "dark-gray"
finished-label = "gray"
finished-time = "green"
unit-count = "gray"
failed-count = "light-red"
current = "white"

[colors.tree]
branches = "dark-gray"
columns = "dark-gray"
target = "cyan"
current-stage = "yellow"
reached-stage = "green"
running-unit = "white"
running-marker = "yellow"
waiting-unit = "gray"
finished-unit = "dark-gray"
finished-marker = "green"
failed-unit = "light-red"
overflow = "gray"

[colors.timeline]
rule = "dark-gray"
title = "gray"
axis = "dark-gray"
milestone = "green"
finished = "green"
finished-label = "gray"
failed = "light-red"
queued-bar = "gray"
running = "yellow"
running-label = "white"

[colors.failures]
rule = "dark-gray"
title = "light-red"
unit = "light-red"
reason = "white"
log = "gray"
overflow = "dark-gray"

[colors.footer]
rule = "dark-gray"
done = "green"
running = "yellow"
waiting = "gray"
failed = "light-red"
no-failures = "gray"

[colors.password]
frame = "yellow"
message = "white"
hint = "dark-gray"
checking = "gray"
rejected = "light-red"
backdrop = "dark-gray"

[timing]
keep-finished-units-for = "2s"
hide-runs-shorter-than = "1s"
keep-final-frame-for = "1s"
wait-for-display-manager = "10s"

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
failures the failed units with their reason and last journal lines
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 Meaning
keep-finished-units-for How long a finished unit stays in the tree, faded, before it leaves.
hide-runs-shorter-than Runs shorter than this get no timer and no timeline bar.
keep-final-frame-for How long the last frame stays before the console is handed back.
wait-for-display-manager 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:

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 shows how to watch your user manager start a set of sample units this way.