Skip to the content
nullroute
Browse the docs

What the device does at boot

You type nothing and configure nothing.

  1. The Pi firmware reads config.txt and starts your board's kernel, kernel8.img on a Pi 4 or kernel8-rpi.img on a Pi 5.
  2. The initramfs mounts the system partition read only through dm-verity, against system.roothash. On a mismatch it stops and says so.
  3. nullroute-state.service mounts the fourth partition at /var/lib, making its filesystem the first time only.
  4. nullrouted.service checks its verification report and prints the manifest root. It refuses to start if the report is missing or not for this build.
  5. nullroute-bridge.service serves the frontend on 127.0.0.1:5180.
  6. nullroute-kiosk.service starts Chromium against it, full screen.

The lock screen should appear, showing the manifest root before you type a passphrase. Compare it with what make image printed.

Steps 2 to 5 are proven under QEMU, on the Pi 4's kernel. Step 1 and step 6 are not: QEMU loads the kernel itself, so the firmware and config.txt are never read, and it has no virtual terminal for the screen. The Pi 5's kernel has not booted anywhere yet. getty@tty1 and getty.target are masked, so no getty competes for the console. If the panel stays dark and the rest worked, ask these in order:

$ systemctl status nullroute-kiosk.service
$ journalctl -u nullroute-kiosk.service -b
$ ls -l /dev/dri/            # a card per GPU and display; on a Pi 5 the panel is the last
$ ls -l /dev/tty1            # and a virtual terminal
  • 208/STDIN: no /dev/tty1.
  • 216/GROUP: an account or group is missing.
  • A cage error about a seat: logind gave it none, which PAMName=login in the unit is for.

If it does not boot at all, attach a serial console. Every failure path in the initramfs prints what it was looking for.

Rendered from docs/INSTALL.md, the same bytes that ship with the code. SHA-256 2c8eeb5da574c931efdb3a904d2ca1c92cd033bd6d70e07ac5c33c811c14972f