docs: automate gif generation

This commit is contained in:
Willem Vanhulle committed 2026-10-16 11:42:52 +02:00
1 parent a39797cbd2
commit 04219bb58e
18 files changed
+375 -153

No files matched your search

+10 -4
View File
@@ -13,10 +13,16 @@ Work inside the dev shell (`direnv allow` once). Run `cargo clippy
- `nix run .#demo-units -- start`, then
`cargo run -- --user --target bootvine-demo.target --hold 3s`: live against
your user manager.
- `nix build .#checks.x86_64-linux.boot`: boots a VM and reads the screen with
OCR; screenshots land in `result/`. Run it by hand with
`nix run .#checks.x86_64-linux.boot.driverInteractive`, then `test_script()`.
The images in `docs/` are copies of these screenshots.
- `nix build .#checks.x86_64-linux.<name>`: each `tests/<name>.nix` boots a VM
and runs `tests/console.py` followed by `tests/<name>.py`. `boot` follows
the initrd, stage 2 and a poweroff; `luks` answers a passphrase prompt in
the initrd. They read tty12 as text from `/dev/vcsu12`, hold the boot with
the initrd backdoor and gate files under `/run` instead of sleeping. Run one
by hand with `nix run .#checks.x86_64-linux.boot.driverInteractive`, then
`test_script()`.
- `nix run .#docs`, from the repository root: renders `docs/boot.tape` and
`docs/shutdown.tape` with VHS against the scripted examples into the README
GIFs, and copies the passphrase screenshot from the `luks` check.
Prefix the VM commands with `env -u LD_LIBRARY_PATH` when the shell exports
libraries that clash with QEMU's.
+5
View File
@@ -21,6 +21,11 @@ the units that have to stop first, until systemd hands over to
<img src="docs/shutdown.gif" width="691" alt="A poweroff: units stopping under the targets waiting on them">
Passphrase prompts, such as a LUKS unlock in the initrd, are answered in place
over the tree.
<img src="docs/passphrase.png" width="640" alt="A LUKS passphrase prompt floating over the initrd tree">
## Try
```sh
-57
View File
@@ -1,57 +0,0 @@
{ bootvineModule }:
{
name = "bootvine-luks";
enableOCR = true;
nodes.machine =
{ lib, pkgs, ... }:
{
imports = [ bootvineModule ];
services.bootvine.enable = true;
boot.loader.systemd-boot.enable = true;
boot.initrd.systemd.enable = true;
environment.systemPackages = [ pkgs.cryptsetup ];
virtualisation = {
emptyDiskImages = [ 64 ];
useBootLoader = true;
useEFIBoot = true;
mountHostNixStore = true;
};
specialisation.unlock.configuration = {
boot.initrd.luks.devices = lib.mkVMOverride {
secret.device = "/dev/vdb";
};
};
};
testScript = ''
import time
passphrase = "quietly unlocked"
machine.wait_for_unit("multi-user.target")
machine.succeed(f"echo -n '{passphrase}' | cryptsetup luksFormat -q --iter-time=1 /dev/vdb -")
machine.succeed("bootctl set-default nixos-generation-1-specialisation-unlock.conf")
machine.succeed("sync")
machine.crash()
machine.start()
machine.wait_for_text("passphrase")
machine.send_chars("not the passphrase\n")
time.sleep(5)
machine.wait_for_text("passphrase")
machine.screenshot("passphrase")
machine.send_chars(f"{passphrase}\n")
machine.wait_for_unit("multi-user.target")
machine.succeed("test -e /dev/mapper/secret")
journal = machine.succeed("journalctl -b -u bootvine -o cat")
print(journal)
assert "in initrd" in journal, "never ran in the initrd"
assert journal.count("answered a password prompt") == 2, "did not answer both attempts itself"
'';
}
-66
View File
@@ -1,66 +0,0 @@
{ demoHost }:
{
name = "bootvine";
enableOCR = true;
nodes.machine =
{ lib, pkgs, ... }:
let
lingerFor = seconds: lib.mkForce "${pkgs.coreutils}/bin/sleep ${seconds}";
in
{
imports = [ demoHost ];
systemd.settings.Manager.ShowStatus = lib.mkForce true;
systemd.services.demo-db.serviceConfig.ExecStop = lingerFor "20";
virtualisation = {
memorySize = 2048;
qemu.options = [
"-vga none"
"-device virtio-vga,xres=1280,yres=800"
];
};
};
testScript = ''
machine.start()
machine.wait_for_text("Initrd")
machine.screenshot("initrd")
machine.wait_for_text("Stage 2")
machine.screenshot("stage-2")
quieted = machine.succeed("cut -f1 /proc/sys/kernel/printk").strip()
assert quieted == "1", f"stage 2 sysctl reopened the kernel console: {quieted}"
machine.wait_for_unit("greetd.service")
machine.wait_until_succeeds("systemctl show -p ActiveState --value bootvine | grep -qx inactive")
journal = machine.succeed("journalctl -b -u bootvine -o cat")
print(journal)
watched = [line for line in journal.splitlines() if line.startswith("bootvine: watching")]
assert any(" in initrd " in line for line in watched), "never ran in the initrd"
assert any(" in stage 2 " in line for line in watched), "never reconnected after the root switch"
pids = {line.split(" as pid ")[1].split()[0] for line in watched}
assert len(pids) == 1, f"the initrd process did not survive the root switch: {pids}"
assert "handing the console over" in journal, "never handed the console over"
machine.succeed("test \"$(systemctl show -p Result --value bootvine)\" = success")
console_level = machine.succeed("cut -f1 /proc/sys/kernel/printk").strip()
assert console_level != "1", f"kernel console level was not restored: {console_level}"
show_status = machine.succeed("systemctl show -p ShowStatus --value").strip()
assert show_status == "yes", f"systemd status output was not restored: {show_status}"
machine.screenshot("handed-over")
foreground = machine.succeed("cat /sys/class/tty/tty0/active").strip()
machine.succeed("systemctl restart bootvine")
machine.wait_until_succeeds("systemctl show -p ActiveState --value bootvine | grep -qx inactive", timeout=10)
assert "boot already finished" in machine.succeed("journalctl -u bootvine -o cat"), "a restart after boot did not stand down"
still_foreground = machine.succeed("cat /sys/class/tty/tty0/active").strip()
assert still_foreground == foreground, f"a restart after boot took the console: {foreground} -> {still_foreground}"
machine.succeed("systemctl poweroff --no-block")
machine.wait_for_text("demo-db")
machine.screenshot("shutdown")
machine.wait_for_shutdown()
'';
}
+21
View File
@@ -0,0 +1,21 @@
Output docs/boot.gif
Require bootvine-boot-example
Set Shell bash
Set FontSize 22
Set Width 1380
Set Height 980
Set Padding 16
Set Theme "Monokai Vivid"
Set TypingSpeed 0
Set Framerate 10
Hide
Type "clear && bootvine-boot-example"
Enter
Show
Wait+Screen@60s /0 running\s+0 waiting/
Sleep 2s
Hide
BIN
View File
Binary file not shown.

Before

Width:  |  Height:  |  Size: 5.9 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 9.7 KiB

BIN
View File
Binary file not shown.

Before

Width:  |  Height:  |  Size: 14 KiB

+21
View File
@@ -0,0 +1,21 @@
Output docs/shutdown.gif
Require bootvine-shutdown-example
Set Shell bash
Set FontSize 22
Set Width 1380
Set Height 980
Set Padding 16
Set Theme "Monokai Vivid"
Set TypingSpeed 0
Set Framerate 10
Hide
Type "clear && bootvine-shutdown-example"
Enter
Show
Wait+Screen@60s /0 running\s+0 waiting/
Sleep 2s
Hide
BIN
View File
Binary file not shown.

Before

Width:  |  Height:  |  Size: 11 KiB

+59 -18
View File
@@ -64,8 +64,8 @@
{
packages = forEachSystem (
{ pkgs, craneLib, ... }:
{
default = craneLib.buildPackage {
let
commonArgs = {
inherit (buildInputsFor pkgs) nativeBuildInputs buildInputs;
src = lib.fileset.toSource {
root = ./.;
@@ -75,20 +75,40 @@
];
};
strictDeps = true;
postInstall = ''
for unit in bootvine.service bootvine-shutdown.service; do
install -Dm644 packaging/systemd/$unit $out/lib/systemd/system/$unit
substituteInPlace $out/lib/systemd/system/$unit \
--replace-fail /usr/bin/bootvine $out/bin/bootvine
done
install -Dm755 packaging/dracut/90bootvine/module-setup.sh \
$out/lib/dracut/modules.d/90bootvine/module-setup.sh
install -Dm644 packaging/mkinitcpio/install/sd-bootvine \
$out/lib/initcpio/install/sd-bootvine
'';
meta.mainProgram = "bootvine";
meta.platforms = lib.platforms.linux;
};
in
{
examples = craneLib.buildPackage (
commonArgs
// {
pname = "bootvine-examples";
cargoExtraArgs = "--examples";
doCheck = false;
installPhaseCommand = ''
for example in boot shutdown; do
install -Dm755 target/release/examples/$example $out/bin/bootvine-$example-example
done
'';
}
);
default = craneLib.buildPackage (
commonArgs
// {
postInstall = ''
for unit in bootvine.service bootvine-shutdown.service; do
install -Dm644 packaging/systemd/$unit $out/lib/systemd/system/$unit
substituteInPlace $out/lib/systemd/system/$unit \
--replace-fail /usr/bin/bootvine $out/bin/bootvine
done
install -Dm755 packaging/dracut/90bootvine/module-setup.sh \
$out/lib/dracut/modules.d/90bootvine/module-setup.sh
install -Dm644 packaging/mkinitcpio/install/sd-bootvine \
$out/lib/initcpio/install/sd-bootvine
'';
meta.mainProgram = "bootvine";
meta.platforms = lib.platforms.linux;
}
);
demo-units = pkgs.callPackage ./demo/user-units.nix { inherit demoUnits; };
}
);
@@ -98,7 +118,7 @@
nixosConfigurations.demo = demoSystem "x86_64-linux";
apps = forEachSystem (
{ system, ... }:
{ pkgs, system, ... }:
{
vm = {
type = "app";
@@ -108,6 +128,27 @@
type = "app";
program = lib.getExe self.packages.${system}.demo-units;
};
docs = {
type = "app";
program = lib.getExe (
pkgs.writeShellApplication {
name = "bootvine-docs";
runtimeInputs = [
pkgs.vhs
self.packages.${system}.examples
];
text = ''
if [ ! -d docs ]; then
echo "no docs directory here; run from the repository root" >&2
exit 1
fi
vhs ${./docs/boot.tape}
vhs ${./docs/shutdown.tape}
install -m644 -t docs ${self.checks.${system}.luks}/passphrase.png
'';
}
);
};
}
);
@@ -115,9 +156,9 @@
{ pkgs, system, ... }:
{
package = self.packages.${system}.default;
boot = pkgs.testers.runNixOSTest (import ./demo/test.nix { inherit demoHost; });
boot = pkgs.testers.runNixOSTest (import ./tests/boot.nix { inherit demoHost; });
luks = pkgs.testers.runNixOSTest (
import ./demo/luks-test.nix { bootvineModule = self.nixosModules.default; }
import ./tests/luks.nix { bootvineModule = self.nixosModules.default; }
);
}
);
+13 -8
View File
@@ -21,6 +21,7 @@ pub struct Console {
foreground: Option<ForegroundVt>,
for_system: bool,
pub glyphs: Glyphs,
pub bold_is_brightness: bool,
}
impl Console {
@@ -38,6 +39,7 @@ impl Console {
},
for_system,
glyphs: font_glyphs(),
bold_is_brightness: own_vt().is_some(),
}
}
@@ -163,16 +165,19 @@ fn active_vt() -> Option<u16> {
Some(state.active)
}
fn own_vt() -> Option<u16> {
let name = ttyname(stdin(), Vec::new()).ok()?;
name.to_str()
.ok()?
.strip_prefix(VIRTUAL_TERMINAL_PREFIX)?
.parse()
.ok()
.filter(|number| *number > 0)
}
impl ForegroundVt {
fn take() -> Option<Self> {
let name = ttyname(stdin(), Vec::new()).ok()?;
let own: u16 = name
.to_str()
.ok()?
.strip_prefix(VIRTUAL_TERMINAL_PREFIX)?
.parse()
.ok()
.filter(|number| *number > 0)?;
let own = own_vt()?;
let previous = active_vt()?;
if previous != own {
activate(own).ok()?;
+11
View File
@@ -22,6 +22,7 @@ use ratatui::{
DefaultTerminal,
backend::Backend,
buffer::{Buffer, CellDiffOption},
style::Modifier,
};
use rustix::{
event::{PollFd, PollFlags, poll},
@@ -130,6 +131,13 @@ fn overwrite_every_cell<B: Backend>(backend: &mut B, frame: &Buffer) -> Result<(
backend.flush()
}
fn drop_bold(frame: &mut Buffer) {
frame
.content
.iter_mut()
.for_each(|cell| cell.modifier.remove(Modifier::BOLD));
}
fn watch(
state: &mut BootState,
feed: &mut Feed,
@@ -180,6 +188,9 @@ fn watch(
},
canvas.area(),
);
if console.bold_is_brightness {
drop_bold(canvas.buffer_mut());
}
})?;
if repaint_due {
let painted = completed.buffer.clone();
+31
View File
@@ -0,0 +1,31 @@
{ demoHost }:
{
name = "bootvine";
nodes.machine =
{ lib, ... }:
let
waitFor = flag: "/bin/sh -c 'until [ -e /run/${flag} ]; do sleep 0.1; done'";
in
{
imports = [ demoHost ];
testing.initrdBackdoor = true;
boot.initrd.systemd.services.demo-initrd-probe.serviceConfig.ExecStart = lib.mkForce (
waitFor "release-initrd-probe"
);
systemd = {
settings.Manager.ShowStatus = lib.mkForce true;
services.demo-db.serviceConfig.ExecStop = lib.mkForce (waitFor "release-demo-db");
services.backdoor.before = [ "demo-db.service" ];
};
virtualisation = {
memorySize = 2048;
qemu.options = [
"-vga none"
"-device virtio-vga,xres=1280,yres=800"
];
};
};
testScript = builtins.readFile ./console.py + builtins.readFile ./boot.py;
}
+54
View File
@@ -0,0 +1,54 @@
def console_level():
return machine.succeed("cut -f1 /proc/sys/kernel/printk").strip()
def unit_state(unit):
return machine.succeed(f"systemctl is-active {unit} || true").strip()
machine.start()
wait_for_screen("Initrd", "Slow hardware probe")
assert_bootvine_in_front()
assert_text_visible(font_has_512_glyphs=True)
assert console_level() == "1", f"the kernel console was not quieted: {console_level()}"
machine.succeed("touch /run/release-initrd-probe")
machine.switch_root()
retry(lambda _: unit_state("demo-db") == "activating", timeout_seconds=60)
wait_for_screen("Stage 2", "demo-db")
assert_bootvine_in_front()
assert_text_visible(font_has_512_glyphs=True)
assert console_level() == "1", f"stage 2 sysctl reopened the kernel console: {console_level()}"
machine.wait_for_unit("greetd.service")
retry(lambda _: unit_state("bootvine") == "inactive", timeout_seconds=60)
journal = bootvine_journal()
print(journal)
watched = [line for line in journal.splitlines() if line.startswith("bootvine: watching")]
assert any(" in Initrd " in line for line in watched), "never ran in the initrd"
assert any(" in Stage 2 " in line for line in watched), "never reconnected after the root switch"
pids = {line.split(" as pid ")[1].split()[0] for line in watched}
assert len(pids) == 1, f"the initrd process did not survive the root switch: {pids}"
assert "handing the console over" in journal, "never handed the console over"
machine.succeed('test "$(systemctl show -p Result --value bootvine)" = success')
assert console_level() != "1", f"kernel console level was not restored: {console_level()}"
show_status = machine.succeed("systemctl show -p ShowStatus --value").strip()
assert show_status == "yes", f"systemd status output was not restored: {show_status}"
foreground = foreground_terminal()
assert foreground != f"tty{BOOTVINE_TERMINAL}", "bootvine kept the console after handing it over"
machine.succeed("systemctl restart bootvine")
retry(lambda _: unit_state("bootvine") == "inactive", timeout_seconds=10)
assert "boot already finished" in bootvine_journal(), "a restart after boot did not stand down"
assert foreground_terminal() == foreground, "a restart after boot took the console"
machine.succeed("systemctl poweroff --no-block")
retry(lambda _: unit_state("demo-db") == "deactivating", timeout_seconds=60)
wait_for_screen("Shutdown", "demo-db")
assert_bootvine_in_front()
assert_text_visible(font_has_512_glyphs=True)
machine.succeed("touch /run/release-demo-db")
machine.wait_for_shutdown()
+69
View File
@@ -0,0 +1,69 @@
import base64
BOOTVINE_TERMINAL = 12
def read_terminal():
attributed, characters = machine.succeed(
f"base64 -w0 /dev/vcsa{BOOTVINE_TERMINAL}; echo; "
f"base64 -w0 /dev/vcsu{BOOTVINE_TERMINAL}"
).split()
attributed = base64.b64decode(attributed)
columns = attributed[1]
attributes = attributed[5::2]
text = base64.b64decode(characters).decode("utf-32-le")
return columns, text, attributes
def as_rows(text, columns):
return "\n".join(text[start : start + columns] for start in range(0, len(text), columns))
def screen():
columns, text, _ = read_terminal()
return as_rows(text, columns)
def colours(attribute, font_has_512_glyphs):
if font_has_512_glyphs:
return (attribute >> 1) & 0x0F, (attribute >> 5) & 0x07
return attribute & 0x0F, (attribute >> 4) & 0x07
def assert_text_visible(font_has_512_glyphs=False):
columns, text, attributes = read_terminal()
def is_hidden(character, attribute):
foreground, background = colours(attribute, font_has_512_glyphs)
return character != " " and foreground == background
hidden = "".join(
"#" if is_hidden(character, attribute) else " "
for character, attribute in zip(text, attributes)
)
assert "#" not in hidden, (
f"text drawn in its background colour, marked #:\n{as_rows(hidden, columns)}\n{as_rows(text, columns)}"
)
def wait_for_screen(*fragments):
def shows_all(last_try):
text = screen()
if last_try:
print(text)
return all(fragment in text for fragment in fragments)
retry(shows_all, timeout_seconds=60)
def foreground_terminal():
return machine.succeed("cat /sys/class/tty/tty0/active").strip()
def assert_bootvine_in_front():
active = foreground_terminal()
assert active == f"tty{BOOTVINE_TERMINAL}", f"bootvine is not in front: {active}"
def bootvine_journal():
return machine.succeed("journalctl -b -u bootvine -o cat")
+50
View File
@@ -0,0 +1,50 @@
{ bootvineModule }:
let
passphrase = "quietly unlocked";
in
{
name = "bootvine-luks";
nodes.machine =
{ lib, pkgs, ... }:
let
secretUuid = "9d1f2a8e-0b7c-4c55-9a8e-6b2f8f3c1d00";
secretDisk = pkgs.runCommand "bootvine-luks-disk" { nativeBuildInputs = [ pkgs.cryptsetup ]; } ''
truncate -s 32M disk.img
echo -n '${passphrase}' | cryptsetup luksFormat -q --disable-locks --type luks2 \
--pbkdf pbkdf2 --pbkdf-force-iterations 1000 --uuid ${secretUuid} disk.img -
mv disk.img $out
'';
in
{
imports = [ bootvineModule ];
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}";
};
virtualisation.qemu.options = [
"-vga none"
"-device virtio-vga,xres=1280,yres=800"
];
virtualisation.qemu.drives = [
{
name = "secret";
file = "${secretDisk}";
driveExtraOpts = {
format = "raw";
snapshot = "on";
};
}
];
};
testScript = ''
PASSPHRASE = "${passphrase}"
''
+ builtins.readFile ./console.py
+ builtins.readFile ./luks.py;
}
+31
View File
@@ -0,0 +1,31 @@
def answered_prompts():
return bootvine_journal().count("answered a password prompt")
def pending_prompt():
listing = machine.succeed("ls /run/systemd/ask-password").split()
return next((name for name in listing if name.startswith("ask.")), "")
machine.start()
retry(lambda _: pending_prompt() != "", timeout_seconds=60)
wait_for_screen("passphrase")
assert_text_visible()
first_prompt = pending_prompt()
machine.send_chars("not the passphrase\n")
retry(lambda _: answered_prompts() == 1, timeout_seconds=30)
retry(lambda _: pending_prompt() not in ("", first_prompt), timeout_seconds=30)
wait_for_screen("passphrase")
assert_text_visible()
machine.screenshot("passphrase")
machine.send_chars(f"{PASSPHRASE}\n")
machine.wait_for_unit("systemd-cryptsetup@secret.service")
machine.switch_root()
machine.wait_for_unit("multi-user.target")
machine.succeed("test -e /dev/mapper/secret")
journal = bootvine_journal()
print(journal)
assert " in Initrd " in journal, "never ran in the initrd"
assert journal.count("answered a password prompt") == 2, "did not answer both attempts itself"