Files
bootvine/README.md
T

125 lines
4.6 KiB
Markdown

# boot-tree
A live dependency tree of systemd jobs on the boot console, in the spirit of
nix-output-monitor. It replaces the scrolling kernel and systemd lines with a
tree of pending units and a timeline bar per row.
## Requirements
- Linux with **systemd ≥ 246 as PID 1** (private socket `/run/systemd/private`,
`Manager.SetShowStatus`).
- Runs as **root**, from the shipped `boot-tree.service`.
- **libdbus-1** at runtime.
- A **virtual terminal** (`CONFIG_VT`); the unit draws on `/dev/tty12`.
- Optional: a **systemd-based initrd** (NixOS `boot.initrd.systemd`, dracut, or
mkinitcpio's `systemd` hook). Without one the tree starts in stage 2, once the
real root is mounted.
- Optional: a large console font on HiDPI screens, e.g. Terminus `ter-v32n`
through the distro's console font setting.
No kernel parameters are needed: while it runs, boot-tree lowers the kernel
console log level and turns systemd's status output off, and restores both when
it hands the console over.
## How it works
- Starts as an initrd unit when the initrd runs systemd, about a second after
the kernel.
- Talks to PID 1 over the private socket `/run/systemd/private` with libdbus:
`Subscribe`, `ListJobs`, unit properties, and the `JobNew`/`JobRemoved`/
`PropertiesChanged` signals.
- Survives the switch to the real root: its `argv[0]` starts with `@`, the unit
ignores isolate, and it chroots into `/sysroot` before PID 1 re-executes, then
reconnects. Plymouth does the same with `plymouth update-root-fs`.
- Draws on its own virtual terminal (tty12 by default) and switches back to the
previous one when the display manager starts or the default target is
reached, so gettys and greeters on tty1 cannot draw over it.
## Installing
The package ships everything a system needs under `lib/`:
| File | Purpose |
| --- | --- |
| `lib/systemd/system/boot-tree.service` | the unit, used in both the initrd and stage 2 |
| `lib/dracut/modules.d/90boot-tree/` | dracut module |
| `lib/initcpio/install/sd-boot-tree` | mkinitcpio hook |
### NixOS
```nix
inputs.boot-tree.url = "git+file:/home/wvhulle/Code/boot-tree?ref=refs/heads/main";
# in the host's modules:
boot-tree.nixosModules.default
{ services.boot-tree.enable = true; }
```
With `boot.initrd.systemd.enable` the unit is added to the initrd as well.
### Other distributions
1. Install `boot-tree` to `/usr/bin` and the files above under `/usr/lib`.
2. `systemctl enable boot-tree.service`.
3. To start it in the initrd:
- dracut: `add_dracutmodules+=" boot-tree "` in `/etc/dracut.conf.d/boot-tree.conf`,
then `dracut --force`;
- mkinitcpio: add `sd-boot-tree` after `systemd` in `HOOKS`, then
`mkinitcpio -P`.
To draw on another terminal, override `TTYPath=` with
`systemctl edit boot-tree.service`.
## Configuration
Colours come from `/etc/boot-tree.toml` (another path with `--config`). Every
key is optional; these are the defaults:
```toml
[palette]
text = "white" # running units, headings
muted = "dark-gray" # rules, tree lines, axis
waiting = "gray" # queued units, finished-unit labels
running = "yellow"
done = "green"
failed = "light-red"
target = "cyan"
```
Values are the 16 console colour names (`red`, `light-red`, `dark-gray`, …).
The Linux console cannot show other colours, so to change what the names look
like, set the console palette itself. That recolours every virtual terminal from
the start of boot:
- NixOS: `console.colors = [ "1d2021" "fb4934" … ];` (16 hex values);
- elsewhere: the kernel parameters `vt.default_red=`, `vt.default_grn=` and
`vt.default_blu=`.
On NixOS set the roles as options; unset ones keep their defaults:
```nix
services.boot-tree.palette = {
running = "light-yellow";
done = "light-green";
};
```
On dracut and mkinitcpio systems the hooks copy `/etc/boot-tree.toml` into the
initramfs, so rebuild it after editing.
## Testing
Commands assume the dev shell is active (`direnv allow` once; `.envrc` runs
`use flake`).
| What | Command |
| --- | --- |
| Unit and render snapshot tests | `cargo test` |
| Scripted boot animation, no systemd needed | `cargo run --example demo` (`q` quits) |
| Live against your user manager | `nix run .#demo-units -- start`, then `nix run . -- --user --target boot-tree-demo.target --hold 3s` |
| Boot a demo VM in a window | `env -u LD_LIBRARY_PATH nix run .#vm` |
| Automated boot test with OCR | `nix build .#checks.x86_64-linux.boot` (screenshots in `result/`) |
| Same test, interactively | `nix run .#checks.x86_64-linux.boot.driverInteractive`, then `test_script()` |
`env -u LD_LIBRARY_PATH` is only needed when the shell exports libraries that
clash with QEMU's.