fix: deal with scripted initrd changes in nixos unstable
This commit is contained in:
1 parent
631315ffe1
commit
4dad85473b
9 files changed
+339
-191
No files matched your search
@@ -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.
|
||||
Reference in new issue
Block a user