Compare commits

..

No commits in common. "3b1b54ffb914093ff7a2a92ced9c0098aba36ba6" and "6e5c7d999f5ed98c09eac0126c45ab912ebb5e96" have entirely different histories.

25 changed files with 496 additions and 2175 deletions

View file

@ -3,57 +3,6 @@
All notable changes are recorded here. The authoritative history is `git log`; All notable changes are recorded here. The authoritative history is `git log`;
this file is the curated, human-readable summary. this file is the curated, human-readable summary.
## 2026-09-23 — NVIDIA reliability, verification and harness repair
- **Deterministic live GPU decision (`phoebus-core`, `phoebus-installer`):**
`--live-gpu-plan` classifies the PCI display controllers (class `0x03`,
vendor `0x10de`) against the generated device table and the bundled branch's
capabilities, returning `load-nvidia`, `nouveau-fallback`, `no-device` or
`disabled`. The live `phoebus-nvidia-load` script consumes it: a supported GPU
loads the accelerated stack, an unsupported GPU (or a failed load) explicitly
`modprobe`s `nouveau`, and a machine without an NVIDIA display device is left
alone. `build.sh` now creates `etc/modprobe.d/phoebus-nvidia.conf` (the file
the old build required but never produced) and replaces Debian's
unconditional nouveau configuration. The fail-safe entry sets
`nomodeset phoebus.nvidia=off`, which the script and the unit both honour.
- **Legacy branch boundary corrected (`phoebus-core`):** Maxwell/Pascal/Volta
are capped at NVIDIA's last supporting series (580) with
`>=x11-drivers/nvidia-drivers-581` masked; a Blackwell plus proprietary-only
GPU set is now reported as an explicit incompatibility instead of installing a
single driver that cannot serve both.
- **Payload verifier hardened (`phoebus-executor`):** `--verify-live-nvidia`
now rejects placeholder modules/libraries, requires every module to be
registered in the live kernel's `modules.dep`, normalises the dpkg revision
and matches userspace/firmware versions to the bundled driver, infers and
checks the module flavor, and requires the exact `phoebus-nvidia.conf`. All
reads stay rooted inside the build root.
- **Installed lifecycle fixed (`phoebus-executor`, `phoebus-installer`):** the
NVIDIA dracut `force_drivers` fragment is written only in the NVIDIA stage,
after the driver exists, and the final initramfs is regenerated then. The
installer proves the modules were built for a kernel (or fails) and records
the real resolved version, kernel and module names. The update path verifies
the rebuilt modules before reporting success.
- **GUI acceptance harness repaired (`installer/tests/vm/gui-driver.py`):**
state-based step navigation replaces the step-0 keystroke count; the real
account fields and the default single-password encryption are driven; the
direct "Install now" action replaces ERASE typing and the (never-assigned)
confirmation toggle; duplicate submission is exercised; install timeouts
report stage, elapsed time and last state; the detached boot unlocks with the
single-password passphrase and falls back to the separate one.
- **Rollback acceptance automated (`installer/tests/vm/`):** a new
`serial-driver.py rollback` mode with `rollback-guest.sh` /
`rollback-verify.sh` records the package-database fingerprint and a `/home`
marker, creates a recovery point with `sys snapshot`, performs a controlled
reversible package install, runs `sys undo`, reboots detached and compares
package state and `/home`. The destructive VM gate is written but unrun.
- **Live privilege scoped (`phoebus-core`, `installer/live`):** the live
`NOPASSWD: ALL` rule is replaced by an emitted, `visudo`-validated policy that
grants unattended escalation only to the typed brokers
(`phoebus-installer`, `sys`) and `systemctl` power actions. The recovery
console is preserved via the password-authenticated live credential.
- Docs: ADR 0012 updated; the stale "`gui_bridge` tests hang" handoff claim
withdrawn (the workspace suite passes).
## 2026-09-23 — Comprehensive installer UX overhaul: 6-step flow, friendly pickers, and resilient UI ## 2026-09-23 — Comprehensive installer UX overhaul: 6-step flow, friendly pickers, and resilient UI
- **Streamlined 6-Step Flow (`phoebus-install`, QML):** - **Streamlined 6-Step Flow (`phoebus-install`, QML):**

View file

@ -3,127 +3,144 @@
Rolling note between work sessions. **Update this file before you finish**, then Rolling note between work sessions. **Update this file before you finish**, then
commit it. It should be short and current; use `git log` for detail. commit it. It should be short and current; use `git log` for detail.
- **Last updated:** this session (2026-09-23), NVIDIA reliability and - **Last updated:** this session (2026-09-23), Comprehensive installer UX overhaul: 6-step flow, friendly pickers, and resilient UI.
verification pass: live driver decision, verifier hardening, installed
lifecycle, rollback harness, GUI harness repair, scoped live privilege.
- **Current focus:** - **Current focus:**
1. **Deterministic live NVIDIA decision.** `phoebus-installer 1. Streamlined 6-Step Flow: eliminated Step 0 duplicate welcome screen in installer, starting directly at "Step 1 of 6 · Language and keyboard", hiding "Back" on Step 1, and rendering 6 accurate progress dots.
--live-gpu-plan` classifies the actual PCI display controllers against the 2. Friendly Keyboard & Locale Pickers: parsed full names from `evdev.lst`, sorted top 30 world layouts first, dynamic keymap switching on select via `localectl set-x11-keymap`, auto-detected timezone, and auto-closing sibling combos on dropdown open.
bundled branch and returns `load-nvidia` / `nouveau-fallback` / 3. Cleaned Welcome Screen: removed redundant "Keyboard test" button and modal from live welcome app.
`no-device` / `disabled`; the old `0x10de`-vendor grep is gone. An 4. Simplified Credentials: single password toggle ("Use same password to encrypt disk") default enabled, single username field (no fullname prompt), and removed 8-char minimum limit.
unsupported GPU (or a failed load) explicitly `modprobe`s `nouveau`, and 5. Direct Review & Confirmation: replaced typing "ERASE" in all caps and checkboxes with a direct "Install now" button on the review screen.
the fail-safe entry sets `nomodeset phoebus.nvidia=off` which the script 6. Subsystem & Desktop Invariants: enforced Mango + DMS desktop, Btrfs filesystem, and Flatpak/Nix in both AI prompt and validator.
and unit both honour. 7. Local AI Auto-Detection & Guidance: auto-probes ports 4096 (OpenCode) and 11434 (Ollama), replaces technical jargon with friendly instructions.
2. **Live payload gate is a compatibility gate.** It rejects placeholder 8. Humanized Error Handling: calm, user-friendly failure explanations with [Retry] and [View technical details] buttons; working live details box with auto-scroll.
modules/libraries, requires registration in the live kernel's
`modules.dep`, matches userspace/firmware versions to the bundled driver,
infers and checks the module flavor, and requires the exact
`etc/modprobe.d/phoebus-nvidia.conf` (now produced by `build.sh`).
3. **Branch boundary corrected.** Maxwell/Pascal/Volta are capped at the last
supporting series (580) instead of `<595`; a Blackwell plus
proprietary-only GPU is reported as an explicit incompatibility.
4. **Installed lifecycle.** The NVIDIA `force_drivers` fragment is written
only after the driver exists; the installer proves the modules built for a
kernel and records the real version/kernel/module names.
5. **GUI harness repaired** for the six-step installer (no step 0, no ERASE,
no confirmation toggle, single-password account); state-based step
navigation; boot uses the single-password disk passphrase.
6. **Rollback acceptance automated** as `serial-driver.py rollback`.
7. **Live privilege scoped:** `NOPASSWD` only for the two typed brokers and
`systemctl` power actions; the recovery console uses the live password.
- **Last verified (this session):** - **Last verified (this session):**
- `cargo fmt --all -- --check`, `cargo clippy --workspace --all-targets` - All workspace tests pass: `cargo fmt`, `cargo clippy`, and `cargo test --workspace` pass 100% (47 phoebus-installer tests, 36 phoebus-ai tests, etc.).
(0 errors) and `cargo test --workspace` all pass. The `gui_bridge` dry-run - Static release binary built and deployed to live VM.
tests **do not hang** on this checkout: the earlier "block" note was stale - Interactive live VM tested and verified with screenshots:
and is withdrawn. - Welcome app shows clean action buttons with "Keyboard test" completely removed.
- `installer/tests/vm/test_vmsafety.py` (18 tests) passes, including `bash -n` - Installer launches in full screen without 50/50 window tiling splits.
over every guest script. - Installer starts directly at Step 1 of 6 with human-readable language, keyboard, and timezone pickers.
- Py-compile clean for `gui-driver.py`, `serial-driver.py`, `live-driver.py`. - Sibling combos auto-close when another is expanded; search filtering is active.
- The emitted live sudoers policy is validated with host `visudo` in a unit - OpenCode local loopback auto-detected on port 4096.
test and at build time. - Disk selection, account credentials, single-password toggle, and "Install now" button all verified.
- New coverage: `live_nvidia_plan` decisions, sysfs device scan + CLI - Failure screen displays humanized explanation and expands technical details on request.
fixtures, mixed-hardware incompatibility, verifier negatives (placeholders, - `cargo fmt --all -- --check` clean; `cargo clippy --workspace --all-targets`
stale `modules.dep`, version/flavor mismatch, missing final config), finished with 0 errors (pre-existing warnings only).
installed module proof + version record, and the ordering fix. - All tests pass for `phoebus-core` (142), `phoebus-ai` (35),
- **Not yet verified this session (unchanged blockers):** the **full desktop `phoebus-executor` (129), `phoebus-tui`, and every `phoebus-installer`
live ISO** is still not assembled (host has ~12 GiB free; `make doctor` wants integration test (`plan_golden`, `cli_coverage` incl. the new
>=20 GiB), so the `gui`/`opencode`/`gui-install` journeys were **not re-run** `--verify-live-nvidia` gate, `live_iso`, `ai_guidance`, `sys_cli`); the
against the repaired harness, and the NVIDIA live/installed boot gates are non-`gui_bridge` installer library tests pass. The `gui_bridge` dry-run
unrun (no NVIDIA GPU). The rollback harness is written and unit-checked but tests block in this environment (pre-existing; unrelated to this change).
its destructive VM gate is **unrun**. `sys` is not installed into the target - New tests: PCI classification (representative IDs), branch/flavor policy,
(see below). Kepler/unknown fallback, hybrid, package/`modprobe`/dracut config, plan
exposure and stage ordering, live-payload verification (complete, missing
module, missing userspace/firmware, missing kernel, Debian `nvidia-current*`
naming), the AI refusal, and the `@module-rebuild`/`kernel-install` update
coordination.
- **Live NVIDIA payload build proven**: a minimal `mmdebstrap` rootfs
(Debian testing userspace + the pinned stable kernel) built the DKMS modules
and passed `--verify-live-nvidia` end to end: driver `550.163.01`, kernel
`6.12.107+deb13-amd64`, modules `nvidia-current/-modeset/-uvm/-drm`,
userspace + EGL/GBM + firmware present. The live kernel is now pinned to
Debian stable because testing's 7.2 kernel removed `strncpy` and breaks the
550 driver.
- **Not yet verified this session:** the **full desktop live ISO** was not
assembled (host disk ~10 GiB free; the build wants more), and the live/
installed NVIDIA boot gates are unrun: this host has no NVIDIA GPU (see
blockers). Actual NVIDIA acceleration is **not** verified. Rollback
(`sys undo`), the AI sandbox, the physical-seat desktop and a separate
physical computer remain open as before.
- **Public repo:** <https://git.phoebus.club/phoebus/phoebus_os> - **Public repo:** <https://git.phoebus.club/phoebus/phoebus_os>
(remote `origin`, SSH port 2222). (remote `origin`, SSH port 2222).
## Next actions (in order) ## Next actions (in order)
1. **Run the repaired GUI harness** once disk allows: `gui`, `opencode`, then 1. **NVIDIA hardware acceptance (BLOCKED)**: on a machine with an NVIDIA GPU
`gui-install` + detached `boot`. It now expects the six-step flow and the (or an explicitly authorized passthrough VM) boot the built live ISO and the
direct "Install now" action. Serve `live.pw` (0600) alongside `test.conf`, installed system and confirm: `phoebus-nvidia.service` loaded the driver,
`luks.pw` and `user.pw` for the `gui-install` preseed. `nvidia-smi` works, `cat /sys/module/nvidia_drm/parameters/modeset` is `Y`,
2. **NVIDIA hardware acceptance (BLOCKED)**: on a machine with an NVIDIA GPU Mango/DMS logs in accelerated, XWayland/Flatpak render, monitors and
boot the live ISO and the installed system and confirm the accelerated stack, suspend/resume work, and a kernel update rebuilds the modules and initramfs.
`nvidia_drm` modeset, Mango/DMS acceleration, XWayland/Flatpak, and a kernel Needs an NVIDIA GPU; none is available here and passthrough must not be
update that rebuilds the modules and initramfs. Needs an NVIDIA GPU. reconfigured unilaterally.
3. **Rollback VM acceptance (BLOCKED on disk + a clone)**: create an installed 2. **Live ISO build + verify (BLOCKED on disk)**: `installer/live/build.sh`
disposable clone, then `serial-driver.py rollback`. The gate and the exact now bundles and verifies the NVIDIA payload. It needs more free space than
evidence markers are implemented; it has not executed. the ~12 GiB this host has; free space (do not delete unrelated files) and run
4. **Install `sys` into the target**: the installed system still lacks the the `gui` harness to confirm ordinary virtual-GPU boot is unchanged.
deterministic CLI, so the no-model fallback contract is only partially 3. **Installed Mango desktop**: install the default profile (Mango + DMS) in a
shipped. This blocks a pure product-path rollback test. graphical VM and verify the panel/launcher/terminal/audio/network/lock/idle,
5. **Live ISO build + verify (BLOCKED on disk)**: `installer/live/build.sh` the dwl fallback, and the welcome/installer absence on the installed system.
now also emits and `visudo`-validates the scoped sudo policy and produces the 4. **Rollback VM acceptance (BLOCKED)**: deliberately break an update, run
live NVIDIA config. Free space and run the `gui` harness. `sys undo`, reboot detached, verify `/var/db/pkg` matches `/`, then boot the
6. **Installed Mango desktop**: install the default profile in a graphical VM recovery entry with no network or model (ADR 0007). Needed: (a) free the
and verify panel/launcher/terminal/audio/network/lock/idle and the dwl >=20 GiB `make doctor` wants for the harness; (b) an automated driver for the
fallback; a no-desktop run is a separate baseline. break-update/undo/recovery sequence — the harness has no such mode.
5. **Narrow the live broker privilege**: replace the live-only `NOPASSWD: ALL`
rule for the GUI bridge with the smallest practical command-scoped rule once
a safe sudoers form is verified (ADR 0011 context).
6. **Physical-seat desktop**: run `phoebus-session` on a real VT/seat and check
`phoebus-menu`, `phoebus-lock`, `phoebus-idle`, kitty, XWayland, the polkit
agent, logout/reap and reboot (`docs/DEVELOPMENT.md`).
7. **Release gates on a CI runner**: `phoebus-release gates --execute` and 7. **Release gates on a CI runner**: `phoebus-release gates --execute` and
`publish` once a runner exists; no gate has executed. `publish` once a runner exists; no gate has executed.
## Known blockers / risks ## Known blockers / risks
- **Disk is the harness constraint.** `make doctor` reports ~12 GiB free versus - **NVIDIA hardware verification is BLOCKED**: this host has no NVIDIA GPU and
the >=20 GiB the VM harness wants. This blocks assembling the full desktop QEMU's virtual GPU cannot establish NVIDIA acceleration; no passthrough setup
ISO and the rollback acceptance run. Do not delete unrelated files. is available or authorized. Unit/integration tests and the live-payload
- **No NVIDIA GPU** (and no authorised passthrough): actual acceleration cannot verifier pass, and a minimal live rootfs with the driver was built and
be verified here. The live decision and verifier are device-based and verified, but no NVIDIA-accelerated boot has been observed. The **full desktop
unit/fixture-tested only. ISO** also cannot be assembled here: `df` shows ~10 GiB free. Unblock by
- **`sys` is absent from the installed target.** The live medium and the providing an NVIDIA GPU (or an authorized passthrough VM) and freeing disk
`phoebus-assistant` launcher use `sys`, and the rollback harness fetches it space, then running `installer/live/build.sh` and the `gui`/`install`/`boot`
from the host, but the installed system has no `/usr/local/bin/sys`. Fixing it harness modes. Note: the live kernel is pinned to Debian stable because
(embedding the static `sys` binary in the install) is future work. testing's 7.2 kernel breaks Debian's 550 driver; revisit when Debian ships a
- **The `gui-install` completion is still host-time bound**: the base package matching driver.
stage took ~116 min and the AI-selected kernel was still compiling at the 4 h - **The complete graphical install and detached boot are BLOCKED on host build
timeout. The deterministic noninteractive install + detached boot remains the time.** The `gui-install` journey passes every assertion and starts a real
proven path. install, but on this host the base packages take ~116 min and the
- **Installed** Mango (GURU + compiled Quickshell/DMS) and the dwl fallback are (AI-selected) optimized kernel was still compiling after 100 min, so the 4h
still not VM-verified. harness timeout fired. Two completed fresh-disk GUI installs + detached boot
- **Recovery-entry offline boot** is not automated: the rollback harness records therefore remain unrun here. The deterministic noninteractive install +
the snapshot recovery entry but does not select it in the bootloader. detached boot is the proven path.
- The live appliance guest scripts (`appliance-guest.sh`, - **Installed** Mango (GURU + compiled Quickshell/DMS) is not VM-verified; nor
`appliance-guest-gui.sh`) still use `sudo -n`/`poweroff` and a is the dwl fallback session. The `gui-install` journey intentionally preseeded
`/run/live/medium/phoebus/bin/phoebus` launcher path; they predate the scoped a no-desktop, safe-kernel configuration to bound the harness run, so it proves
policy and would need the live password if re-run against the narrowed image. the wizard and the install pipeline, not the desktop build.
- **Rollback (`sys undo`) is implemented and unit-tested but NOT VM-verified
(BLOCKED).** Exact blockers: `make doctor` reports ~13 GiB free versus the
>=20 GiB the harness wants, and the harness has no automated
break-update/undo/recovery-boot mode. The AI sandbox is likewise
implemented/unit-tested but not VM-verified. NVIDIA is not verified.
- A **separate physical computer** for the OpenCode transport test is not
available (BLOCKED); a forwarded-hop + unauthenticated-LAN-refusal host-local
test was done instead.
- The GUI bridge reaches Quickshell via `Process` + `/usr/bin/sudo -n`; it
relies on the live user's passwordless sudo. The live sudoers rule is still
`NOPASSWD: ALL` (live-only); narrowing the broker permission is future work.
- Harness artifacts live under `/var/tmp/phoebus-vm/` (outside git): - Harness artifacts live under `/var/tmp/phoebus-vm/` (outside git):
`results.json`, `screenshot-manifest.json`, `report.html`, screenshots. `results.json`, `screenshot-manifest.json`, `report.html`, screenshots.
## Environment notes ## Environment notes
- Dev host: Ubuntu 26.04. QEMU/OVMF/xorriso/rustfmt/clippy/ImageMagick/visudo - Dev host: Ubuntu 26.04. QEMU/OVMF/xorriso/rustfmt/clippy/ImageMagick present.
present. ~12 GiB free on the root filesystem.
- Debian-Live base ISO is cached at `/home/dominic/debian-live-standard.iso` - Debian-Live base ISO is cached at `/home/dominic/debian-live-standard.iso`
(matches `installer/live/base.sha256`). (matches `installer/live/base.sha256`); the appliance ISO builds without root.
- VM harnesses: `installer/tests/vm/gui-driver.py` (`gui`/`opencode`/ - Local QML iteration: `/tmp/opencode/run-qml.sh <config-dir>` runs a config on
`gui-install`/`install`/`boot`), `serial-driver.py` a nested Mango over the host X11 using the built rootfs libraries, and
(`install`/`boot`/`rollback`), `appliance-driver.py`, `live-driver.py`. `grim` captures it. The sanctioned verification is the disposable VM.
`DISK` must be a disposable qcow2; never point it at `/dev/*`. - VM harnesses: `installer/tests/vm/gui-driver.py` (graphical live ISO:
- Serve fixtures from `/home/dominic/vmlab/serve` with `gui`/`opencode`/`gui-install`/`install`/`boot`), `appliance-driver.py`,
`python3 -m http.server 8000 --bind 127.0.0.1` (reachable as `10.0.2.2:8000`), `serial-driver.py`. `DISK` must be a disposable qcow2; never point it at
including `live.pw` for the `gui-install` preseed and `rollback-guest.sh`, `/dev/*`. A `gui-install` run leaves its installed disk for a following
`rollback-verify.sh` and `sys` for the rollback mode. `boot` run.
- Serve the install fixtures from `/home/dominic/vmlab/serve` with
`python3 -m http.server 8000 --bind 127.0.0.1` (reachable as `10.0.2.2:8000`).
## Definition of a good stopping point ## Definition of a good stopping point
- `make test` passes; `docs/STATUS.md` and `docs/CHANGELOG.md` updated; - `make test` passes; `docs/STATUS.md` and `docs/CHANGELOG.md` updated;
`docs/HANDOFF.md` updated; committed (via `scripts/agent-commit.sh`) and `docs/HANDOFF.md` updated; committed and pushed
pushed (`scripts/publish.sh`). (`scripts/agent-commit.sh` + `scripts/publish.sh`).

View file

@ -118,10 +118,6 @@ still not VM-verified.
| NVIDIA installed Gentoo integration (Portage/modprobe/dracut/initramfs) | yes | yes | no | no | | NVIDIA installed Gentoo integration (Portage/modprobe/dracut/initramfs) | yes | yes | no | no |
| NVIDIA live ISO payload (bundled modules/firmware/userspace) | yes | yes (verifier + guards) | no | no | | NVIDIA live ISO payload (bundled modules/firmware/userspace) | yes | yes (verifier + guards) | no | no |
| NVIDIA kernel/module/initramfs update coordination (`@module-rebuild`) | yes | yes | no | no | | NVIDIA kernel/module/initramfs update coordination (`@module-rebuild`) | yes | yes | no | no |
| NVIDIA live GPU decision + real nouveau fallback | yes | yes (fixtures + CLI) | no | no |
| NVIDIA installed lifecycle (driver before final initramfs, module proof) | yes | yes | no | no |
| Live GUI broker scoped sudoers (no `NOPASSWD: ALL`) | yes | yes (`visudo`) | no | n/a |
| Rollback acceptance harness mode | yes | yes (bash -n/unit) | destructive gate unrun | no |
| UKI | no (deferred) | no | no | no | | UKI | no (deferred) | no | no | no |
## Known limitations ## Known limitations
@ -135,49 +131,33 @@ still not VM-verified.
- **NVIDIA** is implemented (hardware-driven branch/flavor policy, scoped - **NVIDIA** is implemented (hardware-driven branch/flavor policy, scoped
Portage configuration, a live payload that is build-time verified, and Portage configuration, a live payload that is build-time verified, and
kernel/module/initramfs update coordination) and covered by Rust tests and the kernel/module/initramfs update coordination) and covered by Rust tests and the
live-payload verifier. The policy now caps Maxwell/Pascal/Volta at the last live-payload verifier. A minimal live rootfs with the stable kernel and NVIDIA
supporting series (580) and reports a Blackwell plus proprietary-only GPU driver was **built and verified** this session (driver 550.163.01, kernel
combination as an explicit incompatibility rather than installing one driver 6.12.107+deb13-amd64, modules `nvidia-current*`). It is **not verified on
that cannot serve both. The live driver choice is a deterministic, hardware**: this host has no NVIDIA GPU and QEMU's virtual GPU cannot
device-class-based decision (`--live-gpu-plan`) with a real `nouveau` establish NVIDIA acceleration; no passthrough setup is available or
fallback, and the verifier rejects placeholders, cross-kernel module trees and authorized. The full desktop ISO was not assembled here (the host has ~10 GiB
version/flavor mismatches. The installed sequence now installs the driver and free; the build wants more) and the live/installed NVIDIA boot gates are
proves its modules exist **before** forcing them into the final initramfs. unrun. See `docs/VM-BOOT-VERIFICATION.md` for the exact unblock commands. The
A minimal live rootfs with the stable kernel and NVIDIA driver was **built and live kernel is pinned to Debian stable (trixie 6.12 LTS) because testing's
verified** previously (driver 550.163.01, kernel 6.12.107+deb13-amd64, modules kernel (7.2) breaks Debian's 550 driver; the bundled branch covers Maxwell
`nvidia-current*`). It is **not verified on hardware or in the VM**: this host through Ada/Hopper, and Blackwell falls back to nouveau on the live medium.
has no NVIDIA GPU and QEMU's virtual GPU cannot establish NVIDIA The installed Gentoo system uses the current branch with NVIDIA's open kernel
acceleration; no passthrough setup is available or authorized. The full modules on Turing and newer.
desktop ISO was not assembled here (the host has ~12 GiB free; the build wants
more) and the live/installed NVIDIA boot gates are unrun. See
`docs/VM-BOOT-VERIFICATION.md` for the exact unblock commands. The live kernel
is pinned to Debian stable (trixie 6.12 LTS) because testing's kernel (7.2)
breaks Debian's 550 driver; the bundled branch covers Maxwell through Hopper,
and Blackwell (or a failed accelerated load) falls back to nouveau on the live
medium. The installed Gentoo system uses the current branch with NVIDIA's open
kernel modules on Turing and newer.
- **The installed target does not install the `sys` binary.** The deterministic
CLI is present on the live medium and on the installed desktop's
`phoebus-assistant` launcher (which calls `sudo sys ask`), but the installed
system has no `/usr/local/bin/sys`: the harness fetches it from the host to
exercise rollback. This is a real gap against the "operate and repair by hand"
contract and is recorded as future work; it also blocks the rollback harness
from being a pure product-path test.
- **UKI** is deferred; the dracut UKI generator did not embed the kernel - **UKI** is deferred; the dracut UKI generator did not embed the kernel
command line, so BLS is used (and verified). command line, so BLS is used (and verified).
- **Rollback (`sys undo`) is NOT VM-verified.** It is implemented and - **Rollback is NOT VM-verified.** It is implemented and unit-tested end to end
unit-tested end to end at the command/text layer (snapshot sets, root/var at the command/text layer (snapshot sets, root/var generation, fstab and BLS
generation, fstab and BLS rewriting, kernel selection, interruption resume, rewriting, kernel selection, interruption resume, retention, free-space
retention, free-space gate). The harness now **automates the acceptance gate), but the destructive acceptance test (deliberately broken update ->
sequence** (`serial-driver.py rollback` + `rollback-guest.sh` / `sys undo` -> detached reboot -> package-state check -> recovery with no
`rollback-verify.sh`): a known-good package-database fingerprint and `/home` network/model) was **not run in this session**. Blockers: (1) `make doctor`
marker, `sys snapshot`, a controlled reversible package install, `sys undo`, reports only ~13 GiB free versus the >=20 GiB the VM harness wants, and the
detached reboot, then package-state/home comparison, kernel-module check and root filesystem has ~12 GiB free; (2) the committed appliance/serial harness
recovery-entry/status evidence. The destructive gate itself is **unrun**: only implements `install` and `boot` modes — there is no automated driver for
`make doctor` reports ~12 GiB free versus the >=20 GiB the harness wants, and the break-update / `sys undo` / recovery-boot sequence, which is documented as
there is no already-installed disposable clone available. Booting the recovery an interactive procedure. `sys undo` is present; treat VM verification as the
entry offline is still a manual step. `sys undo` is present; treat the VM gate gate before relying on it.
as unpassed before relying on it.
- **Mango + DankMaterialShell** is the default desktop - **Mango + DankMaterialShell** is the default desktop
(`desktop.profile = "mango"`, Flatpak on). It is implemented with Mango (`desktop.profile = "mango"`, Flatpak on). It is implemented with Mango
0.17.2, DMS (pinned release), Quickshell 0.3.1 and scenefx 0.5 from the GURU 0.17.2, DMS (pinned release), Quickshell 0.3.1 and scenefx 0.5 from the GURU

View file

@ -399,23 +399,13 @@ Not yet verified for this baseline: `sys undo`, a deliberately broken update, a
detached rollback reboot, and recovery with no network/model (the rollback detached rollback reboot, and recovery with no network/model (the rollback
acceptance gate). acceptance gate).
**2026-09-23 update — rollback acceptance automated, still NOT run.** The **2026-09-22 update — rollback acceptance still NOT run.** A session of `sys`
missing driver now exists: `serial-driver.py rollback` (with administration hardening did not run the destructive acceptance test. The
`rollback-guest.sh` and `rollback-verify.sh`) performs the full sequence, blockers are unchanged and exact: `make doctor` reports ~13 GiB free versus the
including a `/var/db/pkg` fingerprint comparison and a `/home` survival check, >=20 GiB the VM harness requires (the root filesystem has ~12 GiB free), and the
and `bash -n` guards run in `test_vmsafety.py`. The **destructive VM gate committed harness (`appliance-driver.py`, `serial-driver.py`) implements only
itself is unrun**: `make doctor` reports ~12 GiB free versus the >=20 GiB the VM `install` and `boot`, with no automated break-update / `sys undo` /
harness requires, and no already-installed disposable clone is available. recovery-boot mode. `sys undo` therefore remains **unverified**, not passing.
Booting the recovery entry offline is still a manual step. `sys undo` therefore
remains **unverified**, not passing.
**2026-09-23 update — NVIDIA gates still NOT run.** The live driver decision,
the hardened payload verifier and the installed lifecycle are implemented and
covered by Rust/fixture tests, but no NVIDIA-accelerated boot has been observed:
no NVIDIA GPU is present and QEMU's virtual GPU cannot establish acceleration.
The full desktop ISO was not assembled (disk), so the ordinary virtual-GPU
`gui`/`install`/`boot` journeys were not re-run against the repaired harness
either.
## Mango + DankMaterialShell verification (IN PROGRESS) ## Mango + DankMaterialShell verification (IN PROGRESS)

View file

@ -14,14 +14,11 @@ Phoebus must run NVIDIA's official accelerated driver stack on both targets:
NVIDIA's Linux driver has three relevant regimes (verified 2026-09 against NVIDIA's Linux driver has three relevant regimes (verified 2026-09 against
NVIDIA/Gentoo and the PCI ID database): NVIDIA/Gentoo and the PCI ID database):
- **Turing (GTX 16xx / RTX 20xx) through Hopper** can use NVIDIA's **open - **Turing (GTX 16xx / RTX 20xx) and newer** can use NVIDIA's **open kernel
kernel modules** (`kernel-open`). The open modules are *recommended* from 560 modules** (`kernel-open`). The open modules are *recommended* from 560 and
and *mandatory* from 595. *mandatory* from 595; Blackwell (RTX 50xx) requires them.
- **Blackwell (RTX 50xx)** *requires* the open kernel modules; the proprietary
kernel modules cannot drive it.
- **Maxwell, Pascal and Volta** cannot use the open modules and need the - **Maxwell, Pascal and Volta** cannot use the open modules and need the
proprietary modules. NVIDIA's **580 series is the last** to support them; the proprietary modules from a branch that still supports them.
next series drops those architectures.
- **Fermi, Kepler and older** have no security-supported proprietary branch; - **Fermi, Kepler and older** have no security-supported proprietary branch;
the in-tree `nouveau` driver is the honest choice. the in-tree `nouveau` driver is the honest choice.
@ -43,24 +40,15 @@ never claimed as supported.
### 2. Deterministic branch/flavor selection ### 2. Deterministic branch/flavor selection
One driver install covers every adapter, so the branch is computed **across the One driver install covers every adapter, so the branch must serve the **oldest**
whole device set** rather than assuming the oldest card's branch serves the supported GPU present:
newer ones:
| Generation | Branch | Module flavor | Portage | | Generation | Branch | Module flavor | Portage |
| --- | --- | --- | --- | | --- | --- | --- | --- |
| Turing / Ampere / Ada / Hopper | current | open (`kernel-open`) | `x11-drivers/nvidia-drivers ~amd64` | | Turing / Ampere / Ada / Hopper / Blackwell | current | open (`kernel-open`) | `x11-drivers/nvidia-drivers ~amd64` |
| Blackwell | current | open required (`kernel-open`) | `x11-drivers/nvidia-drivers ~amd64` | | Maxwell / Pascal / Volta | proprietary | proprietary (`-kernel-open`) | mask `>=x11-drivers/nvidia-drivers-595` |
| Maxwell / Pascal / Volta | proprietary (580 is the last series) | proprietary (`-kernel-open`) | mask `>=x11-drivers/nvidia-drivers-581` |
| Fermi / Kepler and older | none (nouveau) | — | no NVIDIA package | | Fermi / Kepler and older | none (nouveau) | — | no NVIDIA package |
A Blackwell GPU (open-only) together with a Maxwell/Pascal/Volta GPU
(proprietary-only) has **no single compatible branch**. The plan reports that
incompatibility explicitly and leaves the adapters on `nouveau` instead of
installing one driver that cannot accelerate one of the cards. Pascal plus a
Turing-class GPU stays proprietary and supported, because the newer generation
accepts either flavor.
Hybrid Intel/AMD GPUs keep their `VIDEO_CARDS` entries; the NVIDIA decision Hybrid Intel/AMD GPUs keep their `VIDEO_CARDS` entries; the NVIDIA decision
only adds `nvidia`, or `nouveau` when the card is unserved. only adds `nvidia`, or `nouveau` when the card is unserved.
@ -92,21 +80,8 @@ override it.
- The signed Debian `contrib`/`non-free`/`non-free-firmware` components supply - The signed Debian `contrib`/`non-free`/`non-free-firmware` components supply
the driver. Debian 13/testing ships branch **550.163.01**, whose proprietary the driver. Debian 13/testing ships branch **550.163.01**, whose proprietary
modules cover Maxwell through Hopper. **Blackwell is unsupported by that modules cover Maxwell through Ada/Hopper. **Blackwell is unsupported by that
branch**; on live it falls back to nouveau, reported, never silently claimed. branch**; on live it falls back to nouveau, reported, never silently claimed.
- The live driver choice is **deterministic and device-based**:
`phoebus-installer --live-gpu-plan` enumerates the PCI display controllers
(class `0x03`, vendor `0x10de`), classifies them against the generated
device table, and decides `load-nvidia`, `nouveau-fallback`, `no-device` or
`disabled`. It never matches on a vendor name alone.
- `nouveau` is blacklisted so it cannot *auto-bind* a supported GPU, but an
unsupported GPU (or a failed accelerated load) explicitly `modprobe`s
`nouveau`, so the documented fallback is real. The fail-safe GRUB entry sets
`nomodeset phoebus.nvidia=off`; the load script and the unit both stand down
on that command line, so recovery intent is authoritative.
- The live policy file `etc/modprobe.d/phoebus-nvidia.conf` is created by
`build.sh` (not only on the installed Gentoo target) and replaces Debian's
unconditional nouveau configuration.
- The **live kernel is pinned to Debian stable (trixie, 6.12 LTS)**. Testing's - The **live kernel is pinned to Debian stable (trixie, 6.12 LTS)**. Testing's
current kernel (7.2) removed the `strncpy` declaration the 550 driver still current kernel (7.2) removed the `strncpy` declaration the 550 driver still
uses, so `nvidia-kernel-dkms` cannot build against it; the rolling kernel uses, so `nvidia-kernel-dkms` cannot build against it; the rolling kernel
@ -116,15 +91,11 @@ override it.
any module is missing. Debian renames them `nvidia-current*`; the hook and the any module is missing. Debian renames them `nvidia-current*`; the hook and the
verifier accept either that or the upstream names. verifier accept either that or the upstream names.
- `build.sh` runs `--verify-live-nvidia` on **every** build (including - `build.sh` runs `--verify-live-nvidia` on **every** build (including
`PHOEBUS_REUSE_ROOTFS=1`). It is a compatibility gate, not a presence list: `PHOEBUS_REUSE_ROOTFS=1`): it checks modules, userspace libraries,
it rejects placeholder modules/libraries, requires every module to be `nvidia-smi`, EGL external-platform manifests, firmware, the gated load script
registered in the live kernel's `modules.dep`, normalises the dpkg revision and the nouveau blacklist, and records the bundled driver version, module
and requires the userspace `libnvidia-glcore` and firmware-directory versions flavor and kernel in `/etc/phoebus/nvidia`. A missing or mismatched component
to match the bundled driver, infers and checks the module flavor, requires a fails the build.
non-empty GSP firmware and the exact `etc/modprobe.d/phoebus-nvidia.conf`,
and keeps every read rooted inside the build root. It records the bundled
driver version, module flavor and kernel in `/etc/phoebus/nvidia`. Any
missing or mismatched component fails the build.
- Nouveau blacklisting and module options come from Debian's own - Nouveau blacklisting and module options come from Debian's own
`nvidia-kernel-common`. Its unconditional modules-load entry is removed in `nvidia-kernel-common`. Its unconditional modules-load entry is removed in
favour of a gated service that loads the driver before greetd/Mango **only favour of a gated service that loads the driver before greetd/Mango **only

View file

@ -13,27 +13,18 @@
//! //!
//! Branch policy (NVIDIA/Gentoo, verified 2026-09): //! Branch policy (NVIDIA/Gentoo, verified 2026-09):
//! //!
//! * **Turing / Ampere / Ada / Hopper** use the current //! * **Turing / Ampere / Ada / Hopper / Blackwell** use the current
//! `x11-drivers/nvidia-drivers` branch. NVIDIA's *open* kernel modules //! `x11-drivers/nvidia-drivers` branch with NVIDIA's *open* kernel modules
//! (`USE=kernel-open`) support Turing (GTX 16xx / RTX 20xx) and newer and are //! (`USE=kernel-open`). The open modules support Turing (GTX 16xx / RTX 20xx)
//! recommended there; they become mandatory from driver 595. //! and newer. They are mandatory from driver 595 and are required for
//! * **Blackwell (RTX 50xx)** requires the open kernel modules; the proprietary //! Blackwell (RTX 50xx).
//! kernel modules cannot drive it. //! * **Maxwell / Pascal / Volta** cannot use the open modules. They are pinned
//! * **Maxwell / Pascal / Volta** cannot use the open modules and are served //! to the newest proprietary branch below the open-mandatory cut (595) with
//! only by the proprietary branch. NVIDIA's 580 series is the **last** branch //! `USE=-kernel-open`, and `>=x11-drivers/nvidia-drivers-595` is masked.
//! to support those architectures, so the install is capped below the next
//! series with `USE=-kernel-open` and
//! `>=x11-drivers/nvidia-drivers-581` masked.
//! * **Fermi / Kepler and older** are not served by a security-supported //! * **Fermi / Kepler and older** are not served by a security-supported
//! proprietary branch; they fall back to the in-tree `nouveau` driver. This //! proprietary branch; they fall back to the in-tree `nouveau` driver. This
//! is reported, never silently substituted as NVIDIA success. //! is reported, never silently substituted as NVIDIA success.
//! //!
//! One driver install covers every adapter, so the branch is computed across
//! the whole device set. A Blackwell GPU (open-only) together with a
//! Maxwell/Pascal/Volta GPU (proprietary-only) has **no** single compatible
//! branch; the plan says so explicitly instead of installing a driver that
//! cannot accelerate one of the cards.
//!
//! The Debian live medium ships a single signed branch (550.163.01 in Debian //! The Debian live medium ships a single signed branch (550.163.01 in Debian
//! 13/testing). That branch's proprietary kernel modules cover Maxwell through //! 13/testing). That branch's proprietary kernel modules cover Maxwell through
//! Ada/Hopper; it does not support Blackwell, so Blackwell live boots fall back //! Ada/Hopper; it does not support Blackwell, so Blackwell live boots fall back
@ -48,18 +39,10 @@ use crate::nvidia_devices;
pub const GENTOO_ATOM: &str = "x11-drivers/nvidia-drivers"; pub const GENTOO_ATOM: &str = "x11-drivers/nvidia-drivers";
/// The first NVIDIA driver series that makes the open kernel modules mandatory /// The first NVIDIA driver series that makes the open kernel modules mandatory
/// (`USE=kernel-open` can no longer be disabled). Informational: the /// (`USE=kernel-open` can no longer be disabled). Maxwell/Pascal/Volta are
/// Maxwell/Pascal/Volta cap is the earlier legacy cut below, not this one. /// pinned below this cut.
pub const OPEN_MANDATORY_SERIES: u32 = 595; pub const OPEN_MANDATORY_SERIES: u32 = 595;
/// The last NVIDIA driver series that supports Maxwell, Pascal and Volta.
///
/// NVIDIA confirmed the 580 series is the final branch with full feature
/// support for those architectures
/// (<https://nvidia.custhelp.com/app/answers/detail/a_id/5676>). The next
/// series is masked so Portage cannot install a branch that drops the GPU.
pub const LEGACY_PROPRIETARY_LAST_SERIES: u32 = 580;
/// The NVIDIA branch bundled on the Debian live medium. It is a property of /// The NVIDIA branch bundled on the Debian live medium. It is a property of
/// the signed Debian archive, not of the detected GPU. /// the signed Debian archive, not of the detected GPU.
pub const LIVE_DEBIAN_BRANCH: &str = "550.163.01"; pub const LIVE_DEBIAN_BRANCH: &str = "550.163.01";
@ -71,13 +54,6 @@ pub const LIVE_PROPRIETARY_KMOD: &str = "nvidia-kernel-dkms";
/// The Debian package that builds the open kernel module (Turing+ only). /// The Debian package that builds the open kernel module (Turing+ only).
pub const LIVE_OPEN_KMOD: &str = "nvidia-open-kernel-dkms"; pub const LIVE_OPEN_KMOD: &str = "nvidia-open-kernel-dkms";
/// The newest NVIDIA generation the bundled live branch can drive.
///
/// Debian's live branch is `550.163.01`, which predates Blackwell (RTX 50xx);
/// it covers Maxwell through Hopper. The live driver decision is therefore
/// bounded by the branch, not by the installed-system policy.
pub const LIVE_BRANCH_MAX_GENERATION: NvidiaGeneration = NvidiaGeneration::Hopper;
/// NVIDIA GPU architecture generation, derived from the PCI device ID. /// NVIDIA GPU architecture generation, derived from the PCI device ID.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)] #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")] #[serde(rename_all = "snake_case")]
@ -146,26 +122,6 @@ impl NvidiaGeneration {
_ => NvidiaSupport::Open, _ => NvidiaSupport::Open,
} }
} }
/// Whether NVIDIA's open kernel modules are the only choice for this
/// generation. Blackwell cannot be driven by the proprietary kernel
/// modules; Gentoo states `kernel-open` is *required* for 50xx and newer.
pub fn requires_open_modules(self) -> bool {
matches!(self, NvidiaGeneration::Blackwell)
}
/// Whether this generation can only be served by the proprietary modules.
pub fn requires_proprietary_modules(self) -> bool {
self.support() == NvidiaSupport::Proprietary
}
/// Whether the bundled live branch (Debian 550) can drive this generation.
///
/// This is deliberately branch-scoped: a generation the live branch cannot
/// drive must fall back to `nouveau`, never be claimed as accelerated.
pub fn supported_by_live_branch(self) -> bool {
self.support() != NvidiaSupport::Unsupported && self <= LIVE_BRANCH_MAX_GENERATION
}
} }
/// How an NVIDIA generation is served. /// How an NVIDIA generation is served.
@ -210,11 +166,6 @@ pub struct NvidiaDevice {
} }
impl NvidiaDevice { impl NvidiaDevice {
/// Classify a probed display device into an NVIDIA device.
pub fn from_gpu(gpu: &GpuInfo) -> NvidiaDevice {
nvidia_device(gpu)
}
/// Whether the device is claimed by the selected proprietary/open driver. /// Whether the device is claimed by the selected proprietary/open driver.
pub fn is_supported(&self) -> bool { pub fn is_supported(&self) -> bool {
self.generation self.generation
@ -291,70 +242,13 @@ impl NvidiaPlan {
}; };
} }
// One driver install covers every adapter, so compute compatibility // The branch must serve the oldest supported adapter present, because
// across the whole set rather than assuming the oldest card's branch // one driver install covers every card. Maxwell/Pascal/Volta force the
// serves the newer ones. // proprietary branch; otherwise the open modules are used.
let requires_open = supported.iter().any(|d| { let needs_proprietary = supported
d.generation
.map(|g| g.requires_open_modules())
.unwrap_or(false)
});
let requires_proprietary = supported.iter().any(|d| {
d.generation
.map(|g| g.requires_proprietary_modules())
.unwrap_or(false)
});
if requires_open && requires_proprietary {
// A Blackwell-class GPU needs the open kernel modules; a
// Maxwell/Pascal/Volta GPU needs the proprietary modules. No
// single branch serves both, so do not install a driver that can
// only accelerate one of them.
let open_only: Vec<String> = supported
.iter() .iter()
.filter(|d| { .any(|d| d.support() == NvidiaSupport::Proprietary);
d.generation let flavor = if needs_proprietary {
.map(|g| g.requires_open_modules())
.unwrap_or(false)
})
.map(|d| {
format!(
"{} ({})",
d.pci_id,
d.generation.map(|g| g.as_str()).unwrap_or("unknown")
)
})
.collect();
let prop_only: Vec<String> = supported
.iter()
.filter(|d| {
d.generation
.map(|g| g.requires_proprietary_modules())
.unwrap_or(false)
})
.map(|d| {
format!(
"{} ({})",
d.pci_id,
d.generation.map(|g| g.as_str()).unwrap_or("unknown")
)
})
.collect();
return Self {
devices,
supported: false,
generation: None,
flavor: None,
branch: "nouveau".into(),
reason: format!(
"no single NVIDIA branch serves both {} (open kernel modules only) and \
{} (proprietary only); leaving all NVIDIA adapters on the in-tree nouveau \
fallback instead of shipping a driver that cannot accelerate one of them",
open_only.join(", "),
prop_only.join(", ")
),
};
}
let flavor = if requires_proprietary {
NvidiaModuleFlavor::Proprietary NvidiaModuleFlavor::Proprietary
} else { } else {
NvidiaModuleFlavor::Open NvidiaModuleFlavor::Open
@ -400,12 +294,10 @@ impl NvidiaPlan {
flavor: Some(flavor), flavor: Some(flavor),
branch: match flavor { branch: match flavor {
NvidiaModuleFlavor::Open => { NvidiaModuleFlavor::Open => {
format!("current open kernel modules (mandatory from {OPEN_MANDATORY_SERIES})") format!("current open kernel modules (>= {OPEN_MANDATORY_SERIES})")
} }
NvidiaModuleFlavor::Proprietary => { NvidiaModuleFlavor::Proprietary => {
format!( format!("proprietary (for Maxwell/Pascal/Volta; capped below {OPEN_MANDATORY_SERIES})")
"proprietary (Maxwell/Pascal/Volta; capped at the last supporting series {LEGACY_PROPRIETARY_LAST_SERIES})"
)
} }
}, },
reason, reason,
@ -435,16 +327,12 @@ impl NvidiaPlan {
} }
} }
/// `package.mask` lines. Maxwell/Pascal/Volta are capped at the last /// `package.mask` lines. Maxwell/Pascal/Volta must stay below the branch
/// NVIDIA series that supports them; the next series (which drops those /// that made the open modules mandatory.
/// architectures) is masked so Portage cannot install it.
pub fn gentoo_package_mask(&self) -> Vec<String> { pub fn gentoo_package_mask(&self) -> Vec<String> {
match self.flavor { match self.flavor {
Some(NvidiaModuleFlavor::Proprietary) => { Some(NvidiaModuleFlavor::Proprietary) => {
vec![format!( vec![format!(">={GENTOO_ATOM}-{OPEN_MANDATORY_SERIES}")]
">={GENTOO_ATOM}-{}",
LEGACY_PROPRIETARY_LAST_SERIES + 1
)]
} }
_ => Vec::new(), _ => Vec::new(),
} }
@ -583,155 +471,6 @@ fn nvidia_device(gpu: &GpuInfo) -> NvidiaDevice {
} }
} }
/// The action the live medium takes before the graphical session starts.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum LiveNvidiaAction {
/// No NVIDIA display device: leave the in-tree drivers to auto-detect.
NoDevice,
/// Fail-safe graphics requested: do not load NVIDIA at all.
Disabled,
/// Every NVIDIA display device is served by the bundled branch.
LoadNvidia,
/// At least one NVIDIA display device is not served: bind `nouveau`.
NouveauFallback,
}
impl LiveNvidiaAction {
pub fn as_str(self) -> &'static str {
match self {
LiveNvidiaAction::NoDevice => "no-device",
LiveNvidiaAction::Disabled => "disabled",
LiveNvidiaAction::LoadNvidia => "load-nvidia",
LiveNvidiaAction::NouveauFallback => "nouveau-fallback",
}
}
}
/// The live medium's display-driver decision, computed from the actual PCI
/// display devices and the capabilities of the bundled branch.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct LiveNvidiaPlan {
pub action: LiveNvidiaAction,
/// The module flavor to load, when the accelerated stack is selected.
pub flavor: Option<NvidiaModuleFlavor>,
/// Kernel modules the load script must modprobe, in dependency order.
pub modules: Vec<&'static str>,
/// Every probed NVIDIA display device.
pub devices: Vec<NvidiaDevice>,
/// Devices the bundled branch cannot serve (the `nouveau` set).
pub unclaimed: Vec<NvidiaDevice>,
pub reason: String,
}
impl LiveNvidiaPlan {
/// A stable `key=value` rendering consumed by `phoebus-nvidia-load`.
pub fn render(&self) -> String {
let mut o = String::new();
o.push_str(&format!("action={}\n", self.action.as_str()));
if let Some(flavor) = self.flavor {
o.push_str(&format!("flavor={}\n", flavor.as_str()));
}
if !self.modules.is_empty() {
o.push_str(&format!("modules={}\n", self.modules.join(" ")));
}
for device in &self.devices {
o.push_str(&format!(
"device={} {}\n",
device.pci_id,
device.generation.map(|g| g.as_str()).unwrap_or("unknown")
));
}
for device in &self.unclaimed {
o.push_str(&format!(
"unclaimed={} {}\n",
device.pci_id,
device.generation.map(|g| g.as_str()).unwrap_or("unknown")
));
}
o.push_str(&format!("reason={}\n", self.reason));
o
}
}
/// Decide the live medium's display-driver action.
///
/// `fail_safe` is true when the kernel command line requests fail-safe graphics
/// (`nomodeset` or `phoebus.nvidia=off`); recovery intent is authoritative, so
/// no NVIDIA module is loaded in that case even though the service is armed.
pub fn live_nvidia_plan(devices: &[NvidiaDevice], fail_safe: bool) -> LiveNvidiaPlan {
if fail_safe {
return LiveNvidiaPlan {
action: LiveNvidiaAction::Disabled,
flavor: None,
modules: Vec::new(),
devices: devices.to_vec(),
unclaimed: Vec::new(),
reason: "fail-safe graphics requested (nomodeset or phoebus.nvidia=off); \
not loading the NVIDIA stack"
.into(),
};
}
if devices.is_empty() {
return LiveNvidiaPlan {
action: LiveNvidiaAction::NoDevice,
flavor: None,
modules: Vec::new(),
devices: Vec::new(),
unclaimed: Vec::new(),
reason: "no NVIDIA display device detected".into(),
};
}
let unclaimed: Vec<NvidiaDevice> = devices
.iter()
.filter(|d| {
!d.generation
.map(|g| g.supported_by_live_branch())
.unwrap_or(false)
})
.cloned()
.collect();
if unclaimed.is_empty() {
LiveNvidiaPlan {
action: LiveNvidiaAction::LoadNvidia,
// The live branch is the proprietary Debian build; the open
// modules have not been shown to build against the pinned live
// kernel, so the accelerated stack loaded at boot is the bundled
// proprietary one.
flavor: Some(NvidiaModuleFlavor::Proprietary),
modules: vec!["nvidia", "nvidia_modeset", "nvidia_uvm", "nvidia_drm"],
devices: devices.to_vec(),
unclaimed: Vec::new(),
reason: format!(
"all {} NVIDIA display device(s) are supported by the bundled live branch",
devices.len()
),
}
} else {
let names: Vec<String> = unclaimed
.iter()
.map(|d| {
format!(
"{} ({})",
d.pci_id,
d.generation.map(|g| g.as_str()).unwrap_or("unknown")
)
})
.collect();
LiveNvidiaPlan {
action: LiveNvidiaAction::NouveauFallback,
flavor: None,
modules: Vec::new(),
devices: devices.to_vec(),
unclaimed,
reason: format!(
"the bundled live branch cannot drive {}; using the in-tree nouveau driver",
names.join(", ")
),
}
}
}
/// Parse `vendor:device` (hex) into `(vendor, device)`. /// Parse `vendor:device` (hex) into `(vendor, device)`.
pub fn parse_pci_pair(value: &str) -> Option<(u16, u16)> { pub fn parse_pci_pair(value: &str) -> Option<(u16, u16)> {
let (vendor, device) = value.split_once(':')?; let (vendor, device) = value.split_once(':')?;
@ -774,17 +513,14 @@ mod tests {
} }
#[test] #[test]
fn pascal_uses_the_proprietary_branch_capped_after_580() { fn pascal_uses_the_proprietary_branch_and_is_masked_below_595() {
let hw = hardware(vec![nvidia("10de:1b81", "GP104 [GeForce GTX 1070]")]); let hw = hardware(vec![nvidia("10de:1b81", "GP104 [GeForce GTX 1070]")]);
let plan = NvidiaPlan::for_hardware(&hw); let plan = NvidiaPlan::for_hardware(&hw);
assert_eq!(plan.flavor, Some(NvidiaModuleFlavor::Proprietary)); assert_eq!(plan.flavor, Some(NvidiaModuleFlavor::Proprietary));
// 580 is the last branch that supports Maxwell/Pascal/Volta; the next
// series is masked so Portage cannot install a branch without the GPU.
assert_eq!( assert_eq!(
plan.gentoo_package_mask(), plan.gentoo_package_mask(),
vec![">=x11-drivers/nvidia-drivers-581".to_string()] vec![">=x11-drivers/nvidia-drivers-595".to_string()]
); );
assert!(plan.branch.contains("580"));
assert!(plan.gentoo_package_use()[0].contains("-kernel-open")); assert!(plan.gentoo_package_use()[0].contains("-kernel-open"));
} }
@ -833,9 +569,7 @@ mod tests {
} }
#[test] #[test]
fn mixed_pascal_and_ampere_stays_proprietary_and_supported() { fn mixed_old_and_new_picks_the_proprietary_branch_for_the_oldest() {
// Ampere can use either flavor, so the proprietary-only Pascal still
// leaves a single compatible branch.
let hw = hardware(vec![ let hw = hardware(vec![
nvidia("10de:1b81", "GP104 [GeForce GTX 1070]"), nvidia("10de:1b81", "GP104 [GeForce GTX 1070]"),
nvidia("10de:2482", "GA104 [GeForce RTX 3070]"), nvidia("10de:2482", "GA104 [GeForce RTX 3070]"),
@ -845,27 +579,6 @@ mod tests {
assert_eq!(plan.flavor, Some(NvidiaModuleFlavor::Proprietary)); assert_eq!(plan.flavor, Some(NvidiaModuleFlavor::Proprietary));
} }
#[test]
fn blackwell_plus_pascal_has_no_single_compatible_branch() {
// Blackwell needs NVIDIA's open kernel modules; Pascal can only use the
// proprietary modules. No one branch serves both, so the plan must not
// claim support.
let hw = hardware(vec![
nvidia("10de:1b81", "GP104 [GeForce GTX 1070]"),
nvidia("10de:2b85", "GB202 [GeForce RTX 5090]"),
]);
let plan = NvidiaPlan::for_hardware(&hw);
assert!(!plan.supported);
assert_eq!(plan.branch, "nouveau");
assert_eq!(plan.flavor, None);
assert!(
plan.reason.contains("no single NVIDIA branch"),
"{}",
plan.reason
);
assert!(plan.gentoo_atom().is_none());
}
#[test] #[test]
fn no_nvidia_gpu_has_no_plan() { fn no_nvidia_gpu_has_no_plan() {
let hw = hardware(vec![GpuInfo { let hw = hardware(vec![GpuInfo {
@ -913,57 +626,4 @@ mod tests {
assert_eq!(parse_pci_pair("10de:2482"), Some((0x10de, 0x2482))); assert_eq!(parse_pci_pair("10de:2482"), Some((0x10de, 0x2482)));
assert_eq!(parse_pci_pair("zzzz"), None); assert_eq!(parse_pci_pair("zzzz"), None);
} }
#[test]
fn live_branch_support_is_bounded_before_blackwell() {
assert!(NvidiaGeneration::Maxwell.supported_by_live_branch());
assert!(NvidiaGeneration::Hopper.supported_by_live_branch());
assert!(!NvidiaGeneration::Blackwell.supported_by_live_branch());
assert!(!NvidiaGeneration::Kepler.supported_by_live_branch());
assert!(NvidiaGeneration::Blackwell.requires_open_modules());
assert!(!NvidiaGeneration::Ada.requires_open_modules());
assert!(NvidiaGeneration::Pascal.requires_proprietary_modules());
}
#[test]
fn live_plan_loads_the_stack_only_for_supported_devices() {
let supported = NvidiaDevice::from_gpu(&nvidia("10de:2482", "GA104 [GeForce RTX 3070]"));
let plan = live_nvidia_plan(&[supported], false);
assert_eq!(plan.action, LiveNvidiaAction::LoadNvidia);
assert!(plan.modules.contains(&"nvidia_drm"));
assert!(plan.render().contains("action=load-nvidia"));
let blackwell = NvidiaDevice::from_gpu(&nvidia("10de:2b85", "GB202 [GeForce RTX 5090]"));
let plan = live_nvidia_plan(&[blackwell], false);
assert_eq!(plan.action, LiveNvidiaAction::NouveauFallback);
assert_eq!(plan.unclaimed.len(), 1);
assert!(plan.render().contains("action=nouveau-fallback"));
}
#[test]
fn live_plan_falls_back_when_one_of_several_devices_is_unsupported() {
let devices = vec![
NvidiaDevice::from_gpu(&nvidia("10de:2482", "GA104 [GeForce RTX 3070]")),
NvidiaDevice::from_gpu(&nvidia("10de:2b85", "GB202 [GeForce RTX 5090]")),
];
let plan = live_nvidia_plan(&devices, false);
assert_eq!(plan.action, LiveNvidiaAction::NouveauFallback);
assert_eq!(plan.unclaimed.len(), 1);
}
#[test]
fn live_plan_is_disabled_on_the_fail_safe_entry() {
let device = NvidiaDevice::from_gpu(&nvidia("10de:2482", "GA104 [GeForce RTX 3070]"));
let plan = live_nvidia_plan(&[device], true);
assert_eq!(plan.action, LiveNvidiaAction::Disabled);
assert!(plan.modules.is_empty());
assert!(plan.reason.contains("fail-safe"));
}
#[test]
fn live_plan_with_no_nvidia_device_does_nothing() {
let plan = live_nvidia_plan(&[], false);
assert_eq!(plan.action, LiveNvidiaAction::NoDevice);
assert_eq!(plan.render().lines().next(), Some("action=no-device"));
}
} }

View file

@ -414,8 +414,8 @@ pub fn package_use(config: &InstallConfig, hardware: &HardwareReport) -> String
o o
} }
/// Scoped `package.mask` lines. Maxwell/Pascal/Volta must stay on the last /// Scoped `package.mask` lines. Maxwell/Pascal/Volta must stay below the
/// NVIDIA series that supports them (580); the next series is masked. /// branch that made NVIDIA's open kernel modules mandatory.
pub fn package_mask(config: &InstallConfig, hardware: &HardwareReport) -> String { pub fn package_mask(config: &InstallConfig, hardware: &HardwareReport) -> String {
let _ = config; let _ = config;
let nvidia = crate::nvidia::NvidiaPlan::for_hardware(hardware); let nvidia = crate::nvidia::NvidiaPlan::for_hardware(hardware);
@ -461,13 +461,7 @@ pub fn install_conf() -> String {
o o
} }
/// The generic dracut configuration. pub fn dracut_conf(config: &InstallConfig, hardware: &HardwareReport) -> String {
///
/// It deliberately does **not** force the NVIDIA modules: `force_drivers`
/// naming a module that does not exist yet makes the first kernel build fail.
/// The NVIDIA fragment is written by the NVIDIA install stage, after the
/// driver's modules exist, and the initramfs is regenerated there.
pub fn dracut_conf(config: &InstallConfig) -> String {
let mut o = String::new(); let mut o = String::new();
o.push_str(&format!( o.push_str(&format!(
"# {} dracut configuration\n", "# {} dracut configuration\n",
@ -477,16 +471,14 @@ pub fn dracut_conf(config: &InstallConfig) -> String {
o.push_str("hostonly=\"no\"\n"); o.push_str("hostonly=\"no\"\n");
o.push_str("compress=\"zstd\"\n"); o.push_str("compress=\"zstd\"\n");
o.push_str("add_dracutmodules+=\" crypt btrfs \"\n"); o.push_str("add_dracutmodules+=\" crypt btrfs \"\n");
// NVIDIA: force the DRM/modeset modules (and their firmware) into the
// initramfs so the compositor never starts against a modeset-less GPU.
if let Some(nvidia) = crate::nvidia::NvidiaPlan::for_hardware(hardware).dracut_conf() {
o.push_str(&nvidia);
}
o o
} }
/// The NVIDIA dracut fragment that forces the DRM/modeset modules (and their
/// firmware) into the initramfs, so the compositor never starts against a
/// modeset-less GPU. Only meaningful once the modules are installed.
pub fn nvidia_dracut_conf(hardware: &HardwareReport) -> Option<String> {
crate::nvidia::NvidiaPlan::for_hardware(hardware).dracut_conf()
}
pub fn kernel_profile_config(config: &InstallConfig) -> String { pub fn kernel_profile_config(config: &InstallConfig) -> String {
let profile = config.kernel.profile.as_str(); let profile = config.kernel.profile.as_str();
let mut o = String::new(); let mut o = String::new();
@ -1197,77 +1189,29 @@ pub fn default_session_command(profile: DesktopProfile) -> &'static str {
/// The live ISO's unprivileged user. /// The live ISO's unprivileged user.
pub const LIVE_USER: &str = "phoebus"; pub const LIVE_USER: &str = "phoebus";
/// The live medium's passwordless privilege policy.
///
/// The recovery console keeps full root through the **password-authenticated**
/// `sudo` group (the live-only `phoebus`/`phoebus` credential, printed in
/// `installer/live/README.md`), so a serial or VT operator can still repair a
/// broken live session. Unattended escalation is limited to the two typed
/// brokers — the installer and `sys` — which validate actions before doing
/// anything. `systemctl` power actions are included because the welcome and
/// installer UIs offer them. There is no `ALL` command, no `sh -c`, and no
/// wildcard: a permitted program cannot become a general shell.
pub const LIVE_SUDOERS: &str = "\
# Phoebus live-medium privilege policy (generated).
# The recovery console authenticates with the live-only password; only the
# typed brokers below can escalate without a prompt. Do not add ALL or
# wildcards here.
phoebus ALL=(root) NOPASSWD: /usr/local/bin/phoebus-installer
phoebus ALL=(root) NOPASSWD: /usr/local/bin/sys
phoebus ALL=(root) NOPASSWD: /usr/bin/systemctl poweroff
phoebus ALL=(root) NOPASSWD: /usr/bin/systemctl reboot
";
/// `phoebus-nvidia-load`: live-only. It runs before the graphical session and /// `phoebus-nvidia-load`: live-only. It runs before the graphical session and
/// asks the installer for a deterministic decision based on the actual PCI /// loads NVIDIA's accelerated stack only when an NVIDIA display device is
/// display devices and the bundled branch's capabilities. Systems without an /// present, so systems without one keep the in-tree driver and never record a
/// NVIDIA GPU keep the in-tree driver; an unsupported GPU explicitly binds /// failed unit.
/// `nouveau`; fail-safe graphics loads nothing. A failed accelerated load is a
/// fallback, never a failed unit.
pub const PHOEBUS_NVIDIA_LOAD_SCRIPT: &str = r#"#!/bin/bash pub const PHOEBUS_NVIDIA_LOAD_SCRIPT: &str = r#"#!/bin/bash
# Select the live medium's display driver before greetd/Mango starts. # Load the NVIDIA accelerated driver on the live medium, but only when an
# # NVIDIA display controller is actually present. nouveau is blacklisted by
# `phoebus-installer --live-gpu-plan` classifies every PCI display controller # nvidia-kernel-common, so nothing else claims the GPU first. Debian's
# and compares it with the bundled branch, then prints: # nvidia-kernel-dkms names the modules nvidia-current*, and its modprobe
# action=load-nvidia -> load the bundled accelerated stack # `install` directives map the upstream names used below.
# action=nouveau-fallback-> explicitly bind the in-tree nouveau driver
# action=no-device -> no NVIDIA GPU; leave auto-detection alone
# action=disabled -> fail-safe boot; load no NVIDIA module
#
# `blacklist nouveau` in /etc/modprobe.d stops nouveau *auto-binding* a
# supported GPU; it does not block an explicit `modprobe nouveau`, which is
# exactly what the fallback path uses. Debian's nvidia-kernel-dkms maps the
# upstream module names used here onto nvidia-current*.
set -u set -u
BIN=/usr/local/bin/phoebus-installer if ! grep -lq 0x10de /sys/bus/pci/devices/*/vendor 2>/dev/null; then
echo "phoebus-nvidia: no NVIDIA display device; leaving the in-tree driver in charge"
log() { logger -t phoebus-nvidia -- "$*" 2>/dev/null || true; }
plan="$("$BIN" --live-gpu-plan 2>/dev/null || true)"
action="$(printf '%s\n' "$plan" | sed -n 's/^action=//p' | head -n1)"
case "$action" in
load-nvidia)
if modprobe nvidia-drm; then
modprobe nvidia-uvm || log "nvidia-uvm did not load (not fatal)"
log "loaded the NVIDIA accelerated driver: $(printf '%s' "$plan" | tr '\n' ';')"
exit 0 exit 0
fi fi
log "NVIDIA initialisation failed; falling back to nouveau" if ! modprobe nvidia-drm; then
modprobe nouveau || log "nouveau did not load either; run phoebus-gpu-report" echo "phoebus-nvidia: could not load nvidia-drm; run phoebus-gpu-report" >&2
;; exit 1
nouveau-fallback) fi
log "NVIDIA GPU is not supported by the bundled branch; using nouveau: $(printf '%s' "$plan" | tr '\n' ';')" # Unified memory is a soft dependency; a failure here is not fatal for the
modprobe nouveau || log "nouveau did not load; run phoebus-gpu-report" # desktop but is reported.
;; modprobe nvidia-uvm || echo "phoebus-nvidia: nvidia-uvm did not load" >&2
disabled) echo "phoebus-nvidia: NVIDIA modules loaded"
log "fail-safe graphics requested; not loading the NVIDIA stack"
;;
*)
log "no NVIDIA display device; leaving driver auto-detection in charge"
;;
esac
exit 0
"#; "#;
/// `phoebus-nvidia.service`: load the driver before greetd/Mango. /// `phoebus-nvidia.service`: load the driver before greetd/Mango.
@ -1276,9 +1220,6 @@ Description=Load the NVIDIA accelerated driver (Phoebus live)
Documentation=man:nvidia(4) Documentation=man:nvidia(4)
After=systemd-modules-load.service After=systemd-modules-load.service
Before=display-manager.service greetd.service Before=display-manager.service greetd.service
# Recovery intent is authoritative: the fail-safe entry sets
# phoebus.nvidia=off, so the unit does not even run there.
ConditionKernelCommandLine=!phoebus.nvidia=off
[Service] [Service]
Type=oneshot Type=oneshot
@ -1333,8 +1274,6 @@ pub fn desktop_asset(name: &str) -> Option<String> {
"install-desktop" => PHOEBUS_INSTALL_DESKTOP_ENTRY.to_string(), "install-desktop" => PHOEBUS_INSTALL_DESKTOP_ENTRY.to_string(),
"greetd-installed" => greetd_config(default_cmd), "greetd-installed" => greetd_config(default_cmd),
"greetd-live" => greetd_config_live(LIVE_USER, live_cmd), "greetd-live" => greetd_config_live(LIVE_USER, live_cmd),
// Live-only privilege policy (scoped, never NOPASSWD: ALL).
"live-sudoers" => LIVE_SUDOERS.to_string(),
// Live-only NVIDIA driver loading and diagnostics. // Live-only NVIDIA driver loading and diagnostics.
"nvidia-load" => PHOEBUS_NVIDIA_LOAD_SCRIPT.to_string(), "nvidia-load" => PHOEBUS_NVIDIA_LOAD_SCRIPT.to_string(),
"nvidia-service" => PHOEBUS_NVIDIA_SERVICE.to_string(), "nvidia-service" => PHOEBUS_NVIDIA_SERVICE.to_string(),
@ -1969,54 +1908,13 @@ mod tests {
assert!(desktop_asset("does-not-exist").is_none()); assert!(desktop_asset("does-not-exist").is_none());
} }
#[test]
fn live_sudoers_is_scoped_and_valid() {
let sudoers = desktop_asset("live-sudoers").unwrap();
assert!(sudoers.contains("/usr/local/bin/phoebus-installer"));
assert!(sudoers.contains("/usr/local/bin/sys"));
assert!(sudoers.contains("systemctl poweroff"));
// The unattended rule must never be a general root escape.
assert!(!sudoers.contains("NOPASSWD: ALL"), "{sudoers}");
assert!(!sudoers.contains("(ALL)"), "{sudoers}");
assert!(!sudoers.contains('*'), "{sudoers}");
assert!(sudoers.ends_with('\n'));
// `visudo` is the authority on syntax; validate when the host has it.
let Ok(mut child) = std::process::Command::new("visudo")
.args(["-cf", "/dev/stdin"])
.stdin(std::process::Stdio::piped())
.stdout(std::process::Stdio::null())
.stderr(std::process::Stdio::piped())
.spawn()
else {
return;
};
{
use std::io::Write;
if let Some(stdin) = child.stdin.as_mut() {
let _ = stdin.write_all(sudoers.as_bytes());
}
}
if let Ok(out) = child.wait_with_output() {
assert!(
out.status.success(),
"visudo rejected the live policy: {}",
String::from_utf8_lossy(&out.stderr)
);
}
}
#[test] #[test]
fn live_nvidia_assets_are_bounded_and_ordered_before_greetd() { fn live_nvidia_assets_are_bounded_and_ordered_before_greetd() {
let load = desktop_asset("nvidia-load").unwrap(); let load = desktop_asset("nvidia-load").unwrap();
// The decision comes from the installer, not a vendor-name grep. assert!(load.contains("0x10de"));
assert!(load.contains("--live-gpu-plan")); assert!(load.contains("modprobe nvidia"));
assert!(load.contains("nouveau-fallback"));
assert!(load.contains("modprobe nvidia-drm"));
// A failed accelerated load must not fail the boot unit.
assert!(!load.contains("exit 1"));
let service = desktop_asset("nvidia-service").unwrap(); let service = desktop_asset("nvidia-service").unwrap();
assert!(service.contains("Before=display-manager.service greetd.service")); assert!(service.contains("Before=display-manager.service greetd.service"));
assert!(service.contains("ConditionKernelCommandLine=!phoebus.nvidia=off"));
assert!(service.contains("ExecStart=/usr/local/bin/phoebus-nvidia-load")); assert!(service.contains("ExecStart=/usr/local/bin/phoebus-nvidia-load"));
let report = desktop_asset("gpu-report").unwrap(); let report = desktop_asset("gpu-report").unwrap();
assert!(report.contains("nvidia-smi")); assert!(report.contains("nvidia-smi"));
@ -2043,16 +1941,13 @@ mod tests {
assert!(use_text.contains("x11-drivers/nvidia-drivers dist-kernel kernel-open")); assert!(use_text.contains("x11-drivers/nvidia-drivers dist-kernel kernel-open"));
assert!(package_mask(&cfg, &hw).trim().is_empty()); assert!(package_mask(&cfg, &hw).trim().is_empty());
assert!(accept_keywords_policy(&hw).contains("x11-drivers/nvidia-drivers ~amd64")); assert!(accept_keywords_policy(&hw).contains("x11-drivers/nvidia-drivers ~amd64"));
// The generic initramfs must not force modules that do not exist yet; let dracut = dracut_conf(&cfg, &hw);
// the NVIDIA fragment is written once the driver is installed. assert!(dracut.contains("force_drivers+="));
assert!(!dracut_conf(&cfg).contains("force_drivers")); assert!(dracut.contains("nvidia_drm"));
let nvidia = nvidia_dracut_conf(&hw).expect("nvidia dracut fragment");
assert!(nvidia.contains("force_drivers+="));
assert!(nvidia.contains("nvidia_drm"));
} }
#[test] #[test]
fn nvidia_pascal_uses_proprietary_and_is_capped_after_580() { fn nvidia_pascal_uses_proprietary_and_masks_the_open_mandatory_branch() {
let cfg = InstallConfig::default(); let cfg = InstallConfig::default();
let hw = nvidia_hw("10de:1b81"); let hw = nvidia_hw("10de:1b81");
let use_text = package_use(&cfg, &hw); let use_text = package_use(&cfg, &hw);
@ -2060,7 +1955,7 @@ mod tests {
assert_eq!( assert_eq!(
package_mask(&cfg, &hw), package_mask(&cfg, &hw),
"# NVIDIA: proprietary branch required for Maxwell/Pascal/Volta.\n\ "# NVIDIA: proprietary branch required for Maxwell/Pascal/Volta.\n\
>=x11-drivers/nvidia-drivers-581\n" >=x11-drivers/nvidia-drivers-595\n"
); );
} }
@ -2072,8 +1967,7 @@ mod tests {
assert!(!package_use(&cfg, &hw).contains("nvidia-drivers")); assert!(!package_use(&cfg, &hw).contains("nvidia-drivers"));
assert!(package_mask(&cfg, &hw).is_empty()); assert!(package_mask(&cfg, &hw).is_empty());
assert!(!accept_keywords_policy(&hw).contains("nvidia-drivers")); assert!(!accept_keywords_policy(&hw).contains("nvidia-drivers"));
assert!(nvidia_dracut_conf(&hw).is_none()); assert!(!dracut_conf(&cfg, &hw).contains("nvidia"));
assert!(!dracut_conf(&cfg).contains("nvidia"));
} }
#[test] #[test]

View file

@ -512,13 +512,6 @@ pub fn execute(
"kernel-install", "kernel-install",
&["add-all".into()], &["add-all".into()],
)?; )?;
// Do not report success unless the rebuilt modules exist for a
// kernel; an update that installed a kernel but no matching
// NVIDIA modules must fail loudly, not silently boot degraded.
crate::boot::verify_nvidia_modules(root)?;
// The previous kernels and their module trees are left in
// place, so a failed update still has a bootable, coherent
// generation to fall back to.
} }
"system update complete".to_string() "system update complete".to_string()
} }
@ -693,13 +686,6 @@ Total: 1 package (1 new), Size of downloads: 512 KiB
std::fs::create_dir_all(exec.root.join("etc/phoebus")).unwrap(); std::fs::create_dir_all(exec.root.join("etc/phoebus")).unwrap();
std::fs::write(exec.root.join("etc/phoebus/nvidia"), "branch=current\n").unwrap(); std::fs::write(exec.root.join("etc/phoebus/nvidia"), "branch=current\n").unwrap();
std::fs::create_dir_all(exec.root.join(snapshot::SNAPSHOT_DIR)).unwrap(); std::fs::create_dir_all(exec.root.join(snapshot::SNAPSHOT_DIR)).unwrap();
// The rebuilt modules exist for the activated kernel.
let modules = exec.root.join("lib/modules/6.18.48");
std::fs::create_dir_all(&modules).unwrap();
std::fs::write(modules.join("modules.dep"), b"").unwrap();
for m in ["nvidia", "nvidia_modeset", "nvidia_uvm", "nvidia_drm"] {
std::fs::write(modules.join(format!("{m}.ko")), b"x").unwrap();
}
let auth = auth(); let auth = auth();
execute( execute(
&exec, &exec,
@ -723,25 +709,6 @@ Total: 1 package (1 new), Size of downloads: 512 KiB
); );
} }
#[test]
fn an_nvidia_update_that_produced_no_modules_fails() {
let runner = RecordingRunner::new();
let exec = make_exec(runner.clone());
std::fs::create_dir_all(exec.root.join("etc/phoebus")).unwrap();
std::fs::write(exec.root.join("etc/phoebus/nvidia"), "branch=current\n").unwrap();
std::fs::create_dir_all(exec.root.join(snapshot::SNAPSHOT_DIR)).unwrap();
let auth = auth();
let err = execute(
&exec,
&SystemAction::UpdateSystem,
Some(&auth),
Path::new(&exec.root),
)
.unwrap_err()
.to_string();
assert!(err.contains("NVIDIA"), "{err}");
}
#[test] #[test]
fn protective_snapshot_id_is_preserved_in_the_outcome() { fn protective_snapshot_id_is_preserved_in_the_outcome() {
let runner = RecordingRunner::new(); let runner = RecordingRunner::new();

View file

@ -29,14 +29,11 @@ pub fn write_dracut_conf(
) -> Result<()> { ) -> Result<()> {
exec.target().write( exec.target().write(
"etc/dracut.conf.d/10-phoebus.conf", "etc/dracut.conf.d/10-phoebus.conf",
sysgen::dracut_conf(config), sysgen::dracut_conf(config, hardware),
)?; )?;
exec.logger.info("wrote /etc/dracut.conf.d/10-phoebus.conf"); exec.logger.info("wrote /etc/dracut.conf.d/10-phoebus.conf");
// NVIDIA modprobe policy (nouveau blacklist, modeset, uvm softdep) must be // NVIDIA modprobe policy (nouveau blacklist, modeset, uvm softdep) must be
// in place before the kernel is built and its initramfs generated. The // in place before the kernel is built and its initramfs generated.
// NVIDIA *dracut* fragment is intentionally not written here: the modules
// do not exist until the NVIDIA stage installs them, and `force_drivers`
// referencing a missing module makes the first kernel build fail.
if let Some(conf) = phoebus_core::nvidia::NvidiaPlan::for_hardware(hardware).modprobe_conf() { if let Some(conf) = phoebus_core::nvidia::NvidiaPlan::for_hardware(hardware).modprobe_conf() {
exec.target() exec.target()
.write("etc/modprobe.d/phoebus-nvidia.conf", conf)?; .write("etc/modprobe.d/phoebus-nvidia.conf", conf)?;
@ -46,146 +43,6 @@ pub fn write_dracut_conf(
Ok(()) Ok(())
} }
/// Write the NVIDIA `force_drivers` fragment. Called by the NVIDIA install
/// stage **after** the driver's kernel modules exist, so the final initramfs
/// (generated immediately afterwards) embeds them without naming a missing
/// module.
pub fn write_nvidia_dracut_conf(exec: &Exec, hardware: &HardwareReport) -> Result<()> {
if let Some(conf) = sysgen::nvidia_dracut_conf(hardware) {
exec.target()
.write("etc/dracut.conf.d/20-phoebus-nvidia.conf", conf)?;
exec.logger
.info("wrote /etc/dracut.conf.d/20-phoebus-nvidia.conf (force_drivers)");
}
Ok(())
}
/// The installed NVIDIA modules found for one kernel.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct InstalledNvidia {
/// The resolved driver package version from `var/db/pkg`, when present.
pub version: String,
/// The kernel the modules were built for.
pub kernel: String,
/// The on-disk module file names.
pub modules: Vec<String>,
}
/// The module stems that may satisfy a logical NVIDIA module. Debian's
/// `nvidia-kernel-dkms` renames them `nvidia-current*`; Gentoo and upstream use
/// the plain names.
fn nvidia_module_stems(module: &str) -> &'static [&'static str] {
match module {
"nvidia" => &["nvidia", "nvidia-current"],
"nvidia_modeset" => &["nvidia_modeset", "nvidia-current-modeset"],
"nvidia_uvm" => &["nvidia_uvm", "nvidia-current-uvm"],
"nvidia_drm" => &["nvidia_drm", "nvidia-current-drm"],
_ => &[],
}
}
/// Find a module file anywhere under `dir`, without following symlinks.
fn find_module_file(dir: &Path, module: &str) -> Option<String> {
let stems = nvidia_module_stems(module);
for entry in std::fs::read_dir(dir).ok()?.flatten() {
let path = entry.path();
if entry.file_type().map(|t| t.is_dir()).unwrap_or(false) {
if let Some(found) = find_module_file(&path, module) {
return Some(found);
}
} else if let Some(name) = path.file_name().and_then(|n| n.to_str()) {
if stems.iter().any(|stem| {
name == format!("{stem}.ko") || name.starts_with(&format!("{stem}.ko."))
}) {
return Some(name.to_string());
}
}
}
None
}
/// The resolved `x11-drivers/nvidia-drivers` version from the target package
/// database, or an empty string when it cannot be determined.
fn installed_driver_version(root: &Path) -> String {
let dir = root.join("var/db/pkg/x11-drivers");
let Ok(entries) = std::fs::read_dir(&dir) else {
return String::new();
};
let mut best: Option<String> = None;
for entry in entries.flatten() {
let name = entry.file_name().to_string_lossy().to_string();
if let Some(version) = name.strip_prefix("nvidia-drivers-") {
let version = version.to_string();
if best.as_ref().map(|b| version > *b).unwrap_or(true) {
best = Some(version);
}
}
}
best.unwrap_or_default()
}
/// Verify that the NVIDIA driver actually built modules for a kernel in the
/// target.
///
/// A driver package that emerged but produced no loadable modules for any
/// kernel must make the install fail; it must never be recorded as successful
/// NVIDIA support. Returns the newest coherent kernel found.
pub fn verify_nvidia_modules(root: &Path) -> Result<InstalledNvidia> {
let required = ["nvidia", "nvidia_modeset", "nvidia_uvm", "nvidia_drm"];
let mut checked: Vec<String> = Vec::new();
let mut newest: Option<InstalledNvidia> = None;
for modules_root in ["lib/modules", "usr/lib/modules"] {
let dir = root.join(modules_root);
let Ok(entries) = std::fs::read_dir(&dir) else {
continue;
};
let mut kernels: Vec<String> = entries
.flatten()
.filter(|e| e.path().join("modules.dep").is_file())
.map(|e| e.file_name().to_string_lossy().to_string())
.collect();
kernels.sort_by(|a, b| {
phoebus_core::boot::version_key(a).cmp(&phoebus_core::boot::version_key(b))
});
for kernel in kernels {
checked.push(kernel.clone());
let kernel_dir = dir.join(&kernel);
let mut modules = Vec::new();
let mut complete = true;
for module in required {
match find_module_file(&kernel_dir, module) {
Some(name) => modules.push(name),
None => {
complete = false;
break;
}
}
}
if complete {
newest = Some(InstalledNvidia {
version: installed_driver_version(root),
kernel,
modules,
});
}
}
}
newest.ok_or_else(|| {
ExecError::operation(
"nvidia_drivers",
"verify installed modules",
format!(
"the NVIDIA driver produced no complete module set for any kernel{}",
if checked.is_empty() {
String::new()
} else {
format!(" (checked {})", checked.join(", "))
}
),
)
})
}
pub fn esp_path(exec: &Exec, config: &InstallConfig) -> std::path::PathBuf { pub fn esp_path(exec: &Exec, config: &InstallConfig) -> std::path::PathBuf {
exec.root exec.root
.join(config.storage.efi_mount.trim_start_matches('/')) .join(config.storage.efi_mount.trim_start_matches('/'))
@ -479,7 +336,7 @@ mod tests {
} }
#[test] #[test]
fn nvidia_modprobe_policy_precedes_the_kernel_but_force_drivers_follow_the_driver() { fn nvidia_hardware_writes_modprobe_and_dracut_before_the_kernel_build() {
use phoebus_core::hardware::{GpuInfo, GpuVendor}; use phoebus_core::hardware::{GpuInfo, GpuVendor};
let runner = RecordingRunner::new(); let runner = RecordingRunner::new();
let exec = make_exec(runner); let exec = make_exec(runner);
@ -491,48 +348,16 @@ mod tests {
pci_id: Some("10de:2482".into()), pci_id: Some("10de:2482".into()),
pci_address: Some("0000:01:00.0".into()), pci_address: Some("0000:01:00.0".into()),
}); });
// First kernel build: the modprobe policy is present, but the initramfs
// is not told to force modules that do not exist yet.
write_dracut_conf(&exec, &cfg, &hw).unwrap(); write_dracut_conf(&exec, &cfg, &hw).unwrap();
let dracut = let dracut =
std::fs::read_to_string(exec.root.join("etc/dracut.conf.d/10-phoebus.conf")).unwrap(); std::fs::read_to_string(exec.root.join("etc/dracut.conf.d/10-phoebus.conf")).unwrap();
assert!(!dracut.contains("force_drivers")); assert!(dracut.contains("force_drivers+="));
assert!(dracut.contains("nvidia_drm"));
let modprobe = let modprobe =
std::fs::read_to_string(exec.root.join("etc/modprobe.d/phoebus-nvidia.conf")).unwrap(); std::fs::read_to_string(exec.root.join("etc/modprobe.d/phoebus-nvidia.conf")).unwrap();
assert!(modprobe.contains("blacklist nouveau")); assert!(modprobe.contains("blacklist nouveau"));
assert!(modprobe.contains("options nvidia_drm modeset=1")); assert!(modprobe.contains("options nvidia_drm modeset=1"));
// NVIDIA stage: the fragment is written only now, before the final
// initramfs is regenerated.
write_nvidia_dracut_conf(&exec, &hw).unwrap();
let fragment =
std::fs::read_to_string(exec.root.join("etc/dracut.conf.d/20-phoebus-nvidia.conf"))
.unwrap();
assert!(fragment.contains("force_drivers+="));
assert!(fragment.contains("nvidia_drm"));
}
#[test]
fn nvidia_module_verification_requires_a_complete_kernel_set() {
use std::fs;
let dir = tempfile::tempdir().unwrap();
let root = dir.path();
let modules = root.join("lib/modules/6.18.48");
fs::create_dir_all(&modules).unwrap();
fs::write(modules.join("modules.dep"), b"").unwrap();
// One module is not a driver.
fs::write(modules.join("nvidia.ko"), b"x").unwrap();
assert!(verify_nvidia_modules(root).is_err());
for m in ["nvidia_modeset", "nvidia_uvm", "nvidia_drm"] {
fs::write(modules.join(format!("{m}.ko")), b"x").unwrap();
}
let pkg = root.join("var/db/pkg/x11-drivers/nvidia-drivers-580.65.06");
fs::create_dir_all(&pkg).unwrap();
let installed = verify_nvidia_modules(root).unwrap();
assert_eq!(installed.kernel, "6.18.48");
assert_eq!(installed.version, "580.65.06");
assert_eq!(installed.modules.len(), 4);
} }
#[test] #[test]

View file

@ -106,20 +106,17 @@ fn kernel_version(rootfs: &Path) -> Result<String> {
} }
} }
/// Walk `root` without following symlinks, collecting `(file name, path)`. fn walk(root: &Path, out: &mut Vec<String>) {
///
/// `DirEntry::file_type` does not follow symlinks, so a symlink inside the
/// rootfs can never make us walk the host, and every returned path is inside
/// `root` by construction.
fn walk_files(root: &Path, out: &mut Vec<(String, PathBuf)>) {
if let Ok(entries) = std::fs::read_dir(root) { if let Ok(entries) = std::fs::read_dir(root) {
for entry in entries.flatten() { for entry in entries.flatten() {
let path = entry.path(); let path = entry.path();
// `DirEntry::file_type` does not follow symlinks, so an absolute
// symlink inside the rootfs can never make us walk the host.
match entry.file_type() { match entry.file_type() {
Ok(ft) if ft.is_dir() => walk_files(&path, out), Ok(ft) if ft.is_dir() => walk(&path, out),
Ok(_) => { Ok(_) => {
if let Some(name) = path.file_name().and_then(|n| n.to_str()) { if let Some(name) = path.file_name().and_then(|n| n.to_str()) {
out.push((name.to_string(), path)); out.push(name.to_string());
} }
} }
Err(_) => {} Err(_) => {}
@ -128,26 +125,6 @@ fn walk_files(root: &Path, out: &mut Vec<(String, PathBuf)>) {
} }
} }
/// All files under `root`, as `(name, path)` pairs rooted inside it.
fn files_under(root: &Path) -> Vec<(String, PathBuf)> {
let mut out = Vec::new();
walk_files(root, &mut out);
out
}
/// Directory names directly under `root`.
fn dirs_under(root: &Path) -> Vec<String> {
let mut out = Vec::new();
if let Ok(entries) = std::fs::read_dir(root) {
for entry in entries.flatten() {
if entry.file_type().map(|t| t.is_dir()).unwrap_or(false) {
out.push(entry.file_name().to_string_lossy().to_string());
}
}
}
out
}
/// Read a rootfs-relative file, resolving symlinks **within** the rootfs. /// Read a rootfs-relative file, resolving symlinks **within** the rootfs.
fn read_in_rootfs(rootfs: &Path, rel: &str) -> Option<String> { fn read_in_rootfs(rootfs: &Path, rel: &str) -> Option<String> {
let mut current = rootfs.join(rel.trim_start_matches('/')); let mut current = rootfs.join(rel.trim_start_matches('/'));
@ -168,48 +145,35 @@ fn read_in_rootfs(rootfs: &Path, rel: &str) -> Option<String> {
None None
} }
/// Size of a file, or 0 when it is missing or unreadable (a broken symlink /// Whether `rel` (relative to the rootfs) resolves to a file, following
/// included, because `metadata` follows symlinks). /// symlinks **within** the rootfs. Absolute symlinks are meaningless outside it,
fn size_of(path: &Path) -> u64 { /// so they are resolved against the rootfs, never the host.
std::fs::metadata(path).map(|m| m.len()).unwrap_or(0) fn exists_in_rootfs(rootfs: &Path, rel: &str) -> bool {
} let mut current = rootfs.join(rel.trim_start_matches('/'));
for _ in 0..16 {
/// The upstream part of a driver version: Debian's `550.163.01-1~deb13u1` match std::fs::symlink_metadata(&current) {
/// becomes `550.163.01`. Err(_) => return false,
fn upstream_version(version: &str) -> &str { Ok(meta) if meta.file_type().is_symlink() => {
version let Ok(target) = std::fs::read_link(&current) else {
.split(['-', '~', '+']) return false;
.next() };
.filter(|s| !s.is_empty()) if target.is_absolute() {
.unwrap_or(version) current = rootfs.join(target.strip_prefix("/").unwrap_or(&target));
}
/// A dotted numeric version embedded in a shared-library name, e.g.
/// `libnvidia-glcore.so.550.163.01` -> `550.163.01`. `libGLX_nvidia.so.0`
/// yields `None` because a bare SONAME is not the driver version.
fn embedded_version(name: &str, prefix: &str) -> Option<String> {
let rest = name.strip_prefix(prefix)?;
let rest = rest.strip_prefix('.')?;
let version = rest.trim_end_matches(|c: char| c.is_ascii_alphabetic());
if version.is_empty()
|| !version.chars().next()?.is_ascii_digit()
|| !version.contains('.')
|| !version.chars().all(|c| c.is_ascii_digit() || c == '.')
{
return None;
}
Some(version.trim_end_matches('.').to_string())
}
/// The flavor a module name implies, when the name is Debian's renamed form.
fn flavor_from_module_name(name: &str) -> Option<&'static str> {
if name.contains("-open") || name.contains("nvidia-open") {
Some("open")
} else if name.starts_with("nvidia-current") {
Some("proprietary")
} else { } else {
None current = current.parent().unwrap_or(rootfs).join(target);
} }
}
Ok(meta) => return meta.is_file(),
}
}
false
}
/// All file names under `root`, for a bounded, rootfs-relative search.
fn names_under(root: &Path) -> Vec<String> {
let mut out = Vec::new();
walk(root, &mut out);
out
} }
/// The logical NVIDIA module and the on-disk names that may provide it. Debian's /// The logical NVIDIA module and the on-disk names that may provide it. Debian's
@ -230,54 +194,20 @@ fn name_matches(file: &str, module: &str) -> bool {
file == format!("{module}.ko") || file.starts_with(&format!("{module}.ko.")) file == format!("{module}.ko") || file.starts_with(&format!("{module}.ko."))
} }
/// A real kernel module or shared library is far larger than this. A tiny file /// The mounted-module name actually found on disk.
/// is a placeholder that must never satisfy the build gate. fn find_module(names: &[String], module: &str) -> Option<String> {
const MIN_BINARY_BYTES: u64 = 4096;
/// Resolve a rootfs-relative path *within* the rootfs. Absolute symlinks are
/// clamped to the rootfs, never resolved against the host.
fn resolve_in_rootfs(rootfs: &Path, rel: &str) -> Option<PathBuf> {
let mut current = rootfs.join(rel.trim_start_matches('/'));
for _ in 0..16 {
match std::fs::symlink_metadata(&current) {
Err(_) => return None,
Ok(meta) if meta.file_type().is_symlink() => {
let target = std::fs::read_link(&current).ok()?;
current = if target.is_absolute() {
rootfs.join(target.strip_prefix("/").unwrap_or(&target))
} else {
current.parent().unwrap_or(rootfs).join(target)
};
}
Ok(_) => return Some(current),
}
}
None
}
/// The on-disk module file for a logical module: `(recorded label, file name,
/// path)`. The label is the canonical `<candidate>.ko`; the file name keeps the
/// compression/renaming suffix for the `modules.dep` check.
fn find_module_file(
files: &[(String, PathBuf)],
module: &str,
) -> Option<(String, String, PathBuf)> {
for candidate in module_candidates(module) { for candidate in module_candidates(module) {
if let Some((name, path)) = files.iter().find(|(n, _)| name_matches(n, candidate)) { if names.iter().any(|n| name_matches(n, candidate)) {
return Some((format!("{candidate}.ko"), name.clone(), path.clone())); return Some(format!("{candidate}.ko"));
} }
} }
None None
} }
/// Verify that `rootfs` bundles a complete and *self-consistent* NVIDIA payload /// Verify that `rootfs` bundles a complete NVIDIA payload for its live kernel.
/// for the one kernel it boots.
/// ///
/// This is a compatibility gate, not a presence checklist: it rejects an /// Any missing or mismatched component is a hard error: the build fails rather
/// incomplete payload, placeholder files, a module tree built for another /// than shipping an image that cannot accelerate the GPU it advertises.
/// kernel, a userspace/firmware version that does not match the bundled driver,
/// a flavor that contradicts the module naming, and a final boot configuration
/// that would not activate the driver. Any mismatch fails the build.
pub fn verify_live_nvidia( pub fn verify_live_nvidia(
rootfs: &Path, rootfs: &Path,
driver_version: &str, driver_version: &str,
@ -290,43 +220,26 @@ pub fn verify_live_nvidia(
))); )));
} }
let kernel = kernel_version(rootfs)?; let kernel = kernel_version(rootfs)?;
let upstream = upstream_version(driver_version).to_string();
// Kernel modules built for exactly this kernel. Both module roots are // Kernel modules built for exactly this kernel.
// scanned for a merged-usr image and deduplicated by name: `/lib` and let mut module_names = Vec::new();
// `/usr/lib` describe the same tree, not two kernels.
let mut module_files: Vec<(String, PathBuf)> = Vec::new();
for modules_root in ["lib/modules", "usr/lib/modules"] { for modules_root in ["lib/modules", "usr/lib/modules"] {
let dir = rootfs.join(modules_root).join(&kernel); let dir = rootfs.join(modules_root).join(&kernel);
if dir.is_dir() { if dir.is_dir() {
for (name, path) in files_under(&dir) { module_names.extend(names_under(&dir));
if !module_files.iter().any(|(n, _)| n == &name) {
module_files.push((name, path));
} }
} }
} if module_names.is_empty() {
}
if module_files.is_empty() {
return Err(fail(format!( return Err(fail(format!(
"no modules found for kernel {kernel}; the driver was not built for the live kernel" "no modules found for kernel {kernel}; the driver was not built for the live kernel"
))); )));
} }
let required = ["nvidia", "nvidia_modeset", "nvidia_uvm", "nvidia_drm"]; let required = ["nvidia", "nvidia_modeset", "nvidia_uvm", "nvidia_drm"];
let mut modules = Vec::new(); let mut modules = Vec::new();
let mut found: Vec<(String, PathBuf)> = Vec::new();
let mut missing = Vec::new(); let mut missing = Vec::new();
for module in required { for module in required {
match find_module_file(&module_files, module) { match find_module(&module_names, module) {
Some((label, file, path)) => { Some(name) => modules.push(name),
let size = size_of(&path);
if size < MIN_BINARY_BYTES {
return Err(fail(format!(
"kernel module {file} is a placeholder ({size} bytes); the driver was not built"
)));
}
modules.push(label);
found.push((file, path));
}
None => missing.push(module), None => missing.push(module),
} }
} }
@ -337,64 +250,30 @@ pub fn verify_live_nvidia(
))); )));
} }
// Kernel compatibility: modules the kernel cannot resolve are useless. Every
// required module must be registered in this kernel's `modules.dep`.
let dep = read_in_rootfs(rootfs, &format!("lib/modules/{kernel}/modules.dep"))
.or_else(|| read_in_rootfs(rootfs, &format!("usr/lib/modules/{kernel}/modules.dep")))
.ok_or_else(|| {
fail(format!(
"kernel {kernel} has no readable modules.dep; the module tree is incomplete"
))
})?;
for (file, _) in &found {
if !dep.contains(file.as_str()) {
return Err(fail(format!(
"kernel {kernel} modules.dep does not register {file}; the driver was not built for this kernel"
)));
}
}
// Establish the actual flavor from the on-disk naming and reject a payload
// whose naming contradicts the flavor the build claims.
if let Some(observed) = found
.iter()
.find_map(|(file, _)| flavor_from_module_name(file))
{
if observed != flavor.as_str() {
return Err(fail(format!(
"the modules are a {observed} build but a {} payload was expected",
flavor.as_str()
)));
}
}
// Userspace: GLVND/GLX libraries, the management tool, and the Wayland/GBM // Userspace: GLVND/GLX libraries, the management tool, and the Wayland/GBM
// EGL external-platform integration. // EGL external-platform integration.
let lib_files = files_under(&rootfs.join("usr/lib")); let lib_names = names_under(&rootfs.join("usr/lib"));
let mut userspace = Vec::new(); let mut userspace = Vec::new();
let mut missing_lib = Vec::new(); let mut missing_lib = Vec::new();
let mut glcore_version: Option<String> = None; if let Some(name) = find_prefix(&lib_names, "libnvidia-glcore.so") {
for prefix in [ userspace.push(name);
"libnvidia-glcore.so", } else {
"libGLX_nvidia.so", missing_lib.push("libnvidia-glcore.so");
"libnvidia-egl-gbm.so",
"libnvidia-egl-wayland.so",
] {
match lib_files.iter().find(|(n, _)| n.starts_with(prefix)) {
Some((name, path)) => {
let size = size_of(path);
if size < MIN_BINARY_BYTES {
return Err(fail(format!(
"userspace library {name} is a placeholder ({size} bytes)"
)));
} }
if prefix == "libnvidia-glcore.so" { if let Some(name) = find_prefix(&lib_names, "libGLX_nvidia.so") {
glcore_version = embedded_version(name, prefix); userspace.push(name);
} else {
missing_lib.push("libGLX_nvidia.so");
} }
userspace.push(prefix.to_string()); if let Some(name) = find_prefix(&lib_names, "libnvidia-egl-gbm.so") {
} userspace.push(name);
None => missing_lib.push(prefix), } else {
missing_lib.push("libnvidia-egl-gbm.so");
} }
if let Some(name) = find_prefix(&lib_names, "libnvidia-egl-wayland.so") {
userspace.push(name);
} else {
missing_lib.push("libnvidia-egl-wayland.so");
} }
if !missing_lib.is_empty() { if !missing_lib.is_empty() {
return Err(fail(format!( return Err(fail(format!(
@ -402,97 +281,61 @@ pub fn verify_live_nvidia(
missing_lib.join(", ") missing_lib.join(", ")
))); )));
} }
// The userspace driver version must match the module/firmware version, or if !exists_in_rootfs(rootfs, "usr/bin/nvidia-smi") {
// the accelerated stack fails with an API mismatch. return Err(fail(
if let Some(found_version) = &glcore_version { "usr/bin/nvidia-smi is missing (nvidia-smi package not installed)".into(),
if found_version != &upstream { ));
}
userspace.push("nvidia-smi".into());
// EGL external-platform manifests drive Wayland/GBM interop.
let egl_dir = rootfs.join("usr/share/egl/egl_external_platform.d");
let egl = names_under(&egl_dir);
for required_json in ["15_nvidia_gbm.json", "10_nvidia_wayland.json"] {
if !egl.iter().any(|n| n == required_json) {
return Err(fail(format!( return Err(fail(format!(
"userspace library version {found_version} does not match the bundled driver {upstream}" "EGL external-platform manifest {required_json} is missing under usr/share/egl/egl_external_platform.d"
))); )));
} }
} }
match resolve_in_rootfs(rootfs, "usr/bin/nvidia-smi") { userspace.push("15_nvidia_gbm.json".into());
Some(path) if size_of(&path) > 0 => userspace.push("nvidia-smi".into()), userspace.push("10_nvidia_wayland.json".into());
Some(_) => return Err(fail("usr/bin/nvidia-smi is empty".into())),
None => {
return Err(fail(
"usr/bin/nvidia-smi is missing (nvidia-smi package not installed)".into(),
))
}
}
// EGL external-platform manifests drive Wayland/GBM interop. // Firmware (GSP) is mandatory for the module to initialise.
let egl = files_under(&rootfs.join("usr/share/egl/egl_external_platform.d")); let firmware_names = names_under(&rootfs.join("usr/lib/firmware/nvidia"));
for required_json in ["15_nvidia_gbm.json", "10_nvidia_wayland.json"] { if firmware_names.is_empty() {
match egl.iter().find(|(n, _)| n == required_json) {
Some((_, path)) if size_of(path) > 0 => userspace.push(required_json.to_string()),
_ => {
return Err(fail(format!(
"EGL external-platform manifest {required_json} is missing or empty under usr/share/egl/egl_external_platform.d"
)))
}
}
}
// Firmware (GSP) is mandatory for the module to initialise, and its version
// directory names the driver it was built for.
let fw_root = rootfs.join("usr/lib/firmware/nvidia");
if files_under(&fw_root).is_empty() {
return Err(fail( return Err(fail(
"no NVIDIA firmware found under usr/lib/firmware/nvidia (firmware-nvidia-gsp/graphics not installed)" "no NVIDIA firmware found under usr/lib/firmware/nvidia (firmware-nvidia-gsp/graphics not installed)"
.into(), .into(),
)); ));
} }
let versions = dirs_under(&fw_root); let firmware: Vec<String> = firmware_names.into_iter().take(16).collect();
if !versions.is_empty() && !versions.iter().any(|v| v == &upstream) {
return Err(fail(format!( // The live-only load script and its unit must be present and gated so a
"firmware directory {} does not match the bundled driver {upstream}", // machine without an NVIDIA GPU never records a failed unit. Nouveau must be
versions.join(", ") // blacklisted by the distro's own nvidia-kernel-common configuration.
))); if !exists_in_rootfs(rootfs, "usr/local/bin/phoebus-nvidia-load") {
}
let gsp: Vec<(String, PathBuf)> = files_under(&fw_root)
.into_iter()
.filter(|(n, _)| n.starts_with("gsp"))
.collect();
if gsp.is_empty() || gsp.iter().all(|(_, p)| size_of(p) == 0) {
return Err(fail( return Err(fail(
"no non-empty GSP firmware (gsp_*.bin) found under usr/lib/firmware/nvidia".into(), "usr/local/bin/phoebus-nvidia-load is missing (gated driver load)".into(),
)); ));
} }
let firmware: Vec<String> = files_under(&fw_root) let mut has_nouveau_blacklist = false;
.into_iter() if let Ok(entries) = std::fs::read_dir(rootfs.join("etc/modprobe.d")) {
.filter(|(_, p)| size_of(p) > 0) for entry in entries.flatten() {
.map(|(n, _)| n) let rel = format!("etc/modprobe.d/{}", entry.file_name().to_string_lossy());
.take(16) if let Some(text) = read_in_rootfs(rootfs, &rel) {
.collect(); if text.contains("blacklist nouveau") {
has_nouveau_blacklist = true;
// The live-only load script must be present; a machine without an NVIDIA
// GPU must never record a failed unit.
let load =
resolve_in_rootfs(rootfs, "usr/local/bin/phoebus-nvidia-load").filter(|p| size_of(p) > 0);
if load.is_none() {
return Err(fail(
"usr/local/bin/phoebus-nvidia-load is missing or empty (gated driver load)".into(),
));
} }
}
// The final boot configuration must carry the intended policy, not merely }
// any nouveau blacklist somewhere: the load script and the fallback both }
// depend on this exact file. if !has_nouveau_blacklist {
let conf = read_in_rootfs(rootfs, "etc/modprobe.d/phoebus-nvidia.conf").ok_or_else(|| {
fail("etc/modprobe.d/phoebus-nvidia.conf is missing; the live driver policy was not installed".into())
})?;
if !conf.contains("blacklist nouveau") {
return Err(fail( return Err(fail(
"etc/modprobe.d/phoebus-nvidia.conf does not blacklist nouveau; the driver could be preempted" "no nouveau blacklist found under etc/modprobe.d; the selected branch could be preempted"
.into(), .into(),
)); ));
} }
if !conf.contains("modeset=1") {
return Err(fail(
"etc/modprobe.d/phoebus-nvidia.conf does not enable nvidia_drm modeset".into(),
));
}
Ok(LiveNvidiaPayload { Ok(LiveNvidiaPayload {
kernel_version: kernel, kernel_version: kernel,
@ -504,67 +347,48 @@ pub fn verify_live_nvidia(
}) })
} }
/// Find the first name starting with `prefix`, returning a bounded label.
fn find_prefix(names: &[String], prefix: &str) -> Option<String> {
names
.iter()
.find(|n| n.starts_with(prefix))
.map(|_| prefix.to_string())
}
#[cfg(test)] #[cfg(test)]
mod tests { mod tests {
use super::*; use super::*;
const KVER: &str = "6.16.7-amd64";
const DRIVER: &str = "550.163.01";
fn write_bytes(path: &Path, len: usize) {
std::fs::create_dir_all(path.parent().unwrap()).unwrap();
std::fs::write(path, vec![0u8; len]).unwrap();
}
fn touch(path: &Path) { fn touch(path: &Path) {
write_bytes(path, 8192); std::fs::create_dir_all(path.parent().unwrap()).unwrap();
} std::fs::write(path, b"x").unwrap();
/// Register every module file under `updates/dkms` in `modules.dep`, so a
/// fixture models a kernel whose module tree is coherent.
fn write_dep(kernel_dir: &Path) {
let dkms = kernel_dir.join("updates/dkms");
let mut lines = Vec::new();
if let Ok(entries) = std::fs::read_dir(&dkms) {
for entry in entries.flatten() {
lines.push(format!(
"updates/dkms/{}:",
entry.file_name().to_string_lossy()
));
}
}
lines.sort();
std::fs::write(kernel_dir.join("modules.dep"), lines.join("\n")).unwrap();
}
fn install_modules(root: &Path) {
let kernel = root.join(format!("lib/modules/{KVER}"));
std::fs::create_dir_all(&kernel).unwrap();
for m in ["nvidia", "nvidia_modeset", "nvidia_uvm", "nvidia_drm"] {
touch(&kernel.join(format!("updates/dkms/{m}.ko")));
}
write_dep(&kernel);
} }
fn complete_rootfs(root: &Path) { fn complete_rootfs(root: &Path) {
touch(&root.join(format!("boot/vmlinuz-{KVER}"))); let kver = "6.16.7-amd64";
install_modules(root); touch(&root.join(format!("boot/vmlinuz-{kver}")));
let modules = root.join(format!("lib/modules/{kver}"));
std::fs::create_dir_all(&modules).unwrap();
std::fs::write(modules.join("modules.dep"), b"").unwrap();
for m in ["nvidia", "nvidia_modeset", "nvidia_uvm", "nvidia_drm"] {
touch(&modules.join(format!("updates/dkms/{m}.ko")));
}
for lib in [ for lib in [
format!("libnvidia-glcore.so.{DRIVER}"), "libnvidia-glcore.so.550.163.01",
"libGLX_nvidia.so.0".to_string(), "libGLX_nvidia.so.0",
"libnvidia-egl-gbm.so.1.1.2".to_string(), "libnvidia-egl-gbm.so.1.1.2",
"libnvidia-egl-wayland.so.1.1.21".to_string(), "libnvidia-egl-wayland.so.1.1.21",
] { ] {
touch(&root.join("usr/lib/x86_64-linux-gnu").join(lib)); touch(&root.join("usr/lib/x86_64-linux-gnu").join(lib));
} }
touch(&root.join("usr/bin/nvidia-smi")); touch(&root.join("usr/bin/nvidia-smi"));
touch(&root.join("usr/share/egl/egl_external_platform.d/15_nvidia_gbm.json")); touch(&root.join("usr/share/egl/egl_external_platform.d/15_nvidia_gbm.json"));
touch(&root.join("usr/share/egl/egl_external_platform.d/10_nvidia_wayland.json")); touch(&root.join("usr/share/egl/egl_external_platform.d/10_nvidia_wayland.json"));
touch(&root.join(format!("usr/lib/firmware/nvidia/{DRIVER}/gsp_ga10x.bin"))); touch(&root.join("usr/lib/firmware/nvidia/550.163.01/gsp_ga10x.bin"));
touch(&root.join("usr/local/bin/phoebus-nvidia-load")); touch(&root.join("usr/local/bin/phoebus-nvidia-load"));
let conf = root.join("etc/modprobe.d/phoebus-nvidia.conf"); let blacklist = root.join("etc/modprobe.d/nvidia-blacklists-nouveau.conf");
std::fs::create_dir_all(conf.parent().unwrap()).unwrap(); std::fs::create_dir_all(blacklist.parent().unwrap()).unwrap();
std::fs::write(&conf, b"blacklist nouveau\noptions nvidia_drm modeset=1\n").unwrap(); std::fs::write(&blacklist, b"blacklist nouveau\n").unwrap();
} }
#[test] #[test]
@ -572,38 +396,24 @@ mod tests {
let dir = tempfile::tempdir().unwrap(); let dir = tempfile::tempdir().unwrap();
complete_rootfs(dir.path()); complete_rootfs(dir.path());
let payload = let payload =
verify_live_nvidia(dir.path(), DRIVER, NvidiaModuleFlavor::Proprietary).unwrap(); verify_live_nvidia(dir.path(), "550.163.01", NvidiaModuleFlavor::Proprietary).unwrap();
assert_eq!(payload.kernel_version, KVER); assert_eq!(payload.kernel_version, "6.16.7-amd64");
assert_eq!(payload.modules.len(), 4); assert_eq!(payload.modules.len(), 4);
let record = payload.record(); let record = payload.record();
assert!(record.contains("driver_version=550.163.01")); assert!(record.contains("driver_version=550.163.01"));
assert!(record.contains("flavor=proprietary")); assert!(record.contains("flavor=proprietary"));
} }
#[test]
fn a_debian_revision_in_the_version_is_normalised() {
let dir = tempfile::tempdir().unwrap();
complete_rootfs(dir.path());
// The dpkg version carries a Debian revision; the libs and firmware do
// not.
verify_live_nvidia(
dir.path(),
"550.163.01-1~deb13u1",
NvidiaModuleFlavor::Proprietary,
)
.unwrap();
}
#[test] #[test]
fn missing_kernel_module_fails_the_build() { fn missing_kernel_module_fails_the_build() {
let dir = tempfile::tempdir().unwrap(); let dir = tempfile::tempdir().unwrap();
complete_rootfs(dir.path()); complete_rootfs(dir.path());
std::fs::remove_file( std::fs::remove_file(
dir.path() dir.path()
.join(format!("lib/modules/{KVER}/updates/dkms/nvidia_drm.ko")), .join("lib/modules/6.16.7-amd64/updates/dkms/nvidia_drm.ko"),
) )
.unwrap(); .unwrap();
let err = verify_live_nvidia(dir.path(), DRIVER, NvidiaModuleFlavor::Proprietary) let err = verify_live_nvidia(dir.path(), "550.163.01", NvidiaModuleFlavor::Proprietary)
.unwrap_err() .unwrap_err()
.to_string(); .to_string();
assert!(err.contains("nvidia_drm"), "{err}"); assert!(err.contains("nvidia_drm"), "{err}");
@ -614,14 +424,14 @@ mod tests {
let dir = tempfile::tempdir().unwrap(); let dir = tempfile::tempdir().unwrap();
complete_rootfs(dir.path()); complete_rootfs(dir.path());
std::fs::remove_file(dir.path().join("usr/bin/nvidia-smi")).unwrap(); std::fs::remove_file(dir.path().join("usr/bin/nvidia-smi")).unwrap();
assert!(verify_live_nvidia(dir.path(), DRIVER, NvidiaModuleFlavor::Proprietary).is_err()); assert!(verify_live_nvidia(dir.path(), "550", NvidiaModuleFlavor::Proprietary).is_err());
let dir2 = tempfile::tempdir().unwrap(); let dir2 = tempfile::tempdir().unwrap();
std::fs::create_dir_all(dir2.path().join("usr/lib/firmware")).unwrap(); std::fs::create_dir_all(dir2.path().join("usr/lib/firmware")).unwrap();
complete_rootfs(dir2.path()); complete_rootfs(dir2.path());
// Remove the firmware tree. // Remove the firmware tree.
std::fs::remove_dir_all(dir2.path().join("usr/lib/firmware/nvidia")).unwrap(); std::fs::remove_dir_all(dir2.path().join("usr/lib/firmware/nvidia")).unwrap();
let err = verify_live_nvidia(dir2.path(), DRIVER, NvidiaModuleFlavor::Proprietary) let err = verify_live_nvidia(dir2.path(), "550", NvidiaModuleFlavor::Proprietary)
.unwrap_err() .unwrap_err()
.to_string(); .to_string();
assert!(err.contains("firmware"), "{err}"); assert!(err.contains("firmware"), "{err}");
@ -634,23 +444,25 @@ mod tests {
// Debian is merged-usr: the same kernel tree is visible under both // Debian is merged-usr: the same kernel tree is visible under both
// /lib/modules and /usr/lib/modules. That must not look like two // /lib/modules and /usr/lib/modules. That must not look like two
// kernels. // kernels.
let dst = dir.path().join(format!("usr/lib/modules/{KVER}")); let kver = "6.16.7-amd64";
let dst = dir.path().join(format!("usr/lib/modules/{kver}"));
std::fs::create_dir_all(dst.parent().unwrap()).unwrap();
std::fs::create_dir_all(&dst).unwrap(); std::fs::create_dir_all(&dst).unwrap();
std::fs::write(dst.join("modules.dep"), b"").unwrap(); std::fs::write(dst.join("modules.dep"), b"").unwrap();
for m in ["nvidia", "nvidia_modeset", "nvidia_uvm", "nvidia_drm"] { for m in ["nvidia", "nvidia_modeset", "nvidia_uvm", "nvidia_drm"] {
touch(&dst.join(format!("updates/dkms/{m}.ko"))); touch(&dst.join(format!("updates/dkms/{m}.ko")));
} }
let payload = let payload =
verify_live_nvidia(dir.path(), DRIVER, NvidiaModuleFlavor::Proprietary).unwrap(); verify_live_nvidia(dir.path(), "550.163.01", NvidiaModuleFlavor::Proprietary).unwrap();
assert_eq!(payload.kernel_version, KVER); assert_eq!(payload.kernel_version, kver);
} }
#[test] #[test]
fn debian_renamed_modules_are_accepted_and_recorded() { fn debian_renamed_modules_are_accepted_and_recorded() {
let dir = tempfile::tempdir().unwrap(); let dir = tempfile::tempdir().unwrap();
complete_rootfs(dir.path()); complete_rootfs(dir.path());
let kernel = dir.path().join(format!("lib/modules/{KVER}")); let kver = "6.16.7-amd64";
let dkms = kernel.join("updates/dkms"); let dkms = dir.path().join(format!("lib/modules/{kver}/updates/dkms"));
// Replace the upstream names with Debian's DKMS-renamed output. // Replace the upstream names with Debian's DKMS-renamed output.
for m in ["nvidia", "nvidia_modeset", "nvidia_uvm", "nvidia_drm"] { for m in ["nvidia", "nvidia_modeset", "nvidia_uvm", "nvidia_drm"] {
std::fs::remove_file(dkms.join(format!("{m}.ko"))).unwrap(); std::fs::remove_file(dkms.join(format!("{m}.ko"))).unwrap();
@ -663,9 +475,8 @@ mod tests {
] { ] {
touch(&dkms.join(format!("{m}.ko.xz"))); touch(&dkms.join(format!("{m}.ko.xz")));
} }
write_dep(&kernel);
let payload = let payload =
verify_live_nvidia(dir.path(), DRIVER, NvidiaModuleFlavor::Proprietary).unwrap(); verify_live_nvidia(dir.path(), "550.163.01", NvidiaModuleFlavor::Proprietary).unwrap();
assert!(payload assert!(payload
.modules .modules
.contains(&"nvidia-current-drm.ko".to_string())); .contains(&"nvidia-current-drm.ko".to_string()));
@ -675,131 +486,11 @@ mod tests {
#[test] #[test]
fn missing_kernel_is_reported() { fn missing_kernel_is_reported() {
let dir = tempfile::tempdir().unwrap(); let dir = tempfile::tempdir().unwrap();
std::fs::create_dir_all(dir.path().join(format!("lib/modules/{KVER}"))).unwrap(); std::fs::create_dir_all(dir.path().join("lib/modules/6.16.7-amd64")).unwrap();
std::fs::write( std::fs::write(dir.path().join("lib/modules/6.16.7-amd64/modules.dep"), b"").unwrap();
dir.path().join(format!("lib/modules/{KVER}/modules.dep")),
b"",
)
.unwrap();
let err = verify_live_nvidia(dir.path(), "550", NvidiaModuleFlavor::Proprietary) let err = verify_live_nvidia(dir.path(), "550", NvidiaModuleFlavor::Proprietary)
.unwrap_err() .unwrap_err()
.to_string(); .to_string();
assert!(err.contains("vmlinuz"), "{err}"); assert!(err.contains("vmlinuz"), "{err}");
} }
#[test]
fn a_one_byte_module_placeholder_is_rejected() {
let dir = tempfile::tempdir().unwrap();
complete_rootfs(dir.path());
write_bytes(
&dir.path()
.join(format!("lib/modules/{KVER}/updates/dkms/nvidia.ko")),
1,
);
let err = verify_live_nvidia(dir.path(), DRIVER, NvidiaModuleFlavor::Proprietary)
.unwrap_err()
.to_string();
assert!(err.contains("placeholder"), "{err}");
}
#[test]
fn a_one_byte_userspace_placeholder_is_rejected() {
let dir = tempfile::tempdir().unwrap();
complete_rootfs(dir.path());
write_bytes(
&dir.path().join(format!(
"usr/lib/x86_64-linux-gnu/libnvidia-glcore.so.{DRIVER}"
)),
1,
);
let err = verify_live_nvidia(dir.path(), DRIVER, NvidiaModuleFlavor::Proprietary)
.unwrap_err()
.to_string();
assert!(err.contains("placeholder"), "{err}");
}
#[test]
fn a_userspace_version_mismatch_is_rejected() {
let dir = tempfile::tempdir().unwrap();
complete_rootfs(dir.path());
std::fs::rename(
dir.path().join(format!(
"usr/lib/x86_64-linux-gnu/libnvidia-glcore.so.{DRIVER}"
)),
dir.path()
.join("usr/lib/x86_64-linux-gnu/libnvidia-glcore.so.999.0.0"),
)
.unwrap();
let err = verify_live_nvidia(dir.path(), DRIVER, NvidiaModuleFlavor::Proprietary)
.unwrap_err()
.to_string();
assert!(err.contains("does not match"), "{err}");
}
#[test]
fn a_firmware_version_mismatch_is_rejected() {
let dir = tempfile::tempdir().unwrap();
complete_rootfs(dir.path());
std::fs::rename(
dir.path().join(format!("usr/lib/firmware/nvidia/{DRIVER}")),
dir.path().join("usr/lib/firmware/nvidia/999.0"),
)
.unwrap();
let err = verify_live_nvidia(dir.path(), DRIVER, NvidiaModuleFlavor::Proprietary)
.unwrap_err()
.to_string();
assert!(err.contains("does not match"), "{err}");
}
#[test]
fn a_stale_modules_dep_is_rejected() {
let dir = tempfile::tempdir().unwrap();
complete_rootfs(dir.path());
std::fs::write(
dir.path().join(format!("lib/modules/{KVER}/modules.dep")),
b"kernel/other.ko:\n",
)
.unwrap();
let err = verify_live_nvidia(dir.path(), DRIVER, NvidiaModuleFlavor::Proprietary)
.unwrap_err()
.to_string();
assert!(err.contains("modules.dep"), "{err}");
}
#[test]
fn a_contradictory_flavor_is_rejected() {
let dir = tempfile::tempdir().unwrap();
complete_rootfs(dir.path());
let kernel = dir.path().join(format!("lib/modules/{KVER}"));
let dkms = kernel.join("updates/dkms");
// Make the payload unmistakably Debian's proprietary build, then claim
// it is the open one.
for m in ["nvidia", "nvidia_modeset", "nvidia_uvm", "nvidia_drm"] {
std::fs::remove_file(dkms.join(format!("{m}.ko"))).unwrap();
}
for m in [
"nvidia-current",
"nvidia-current-modeset",
"nvidia-current-uvm",
"nvidia-current-drm",
] {
touch(&dkms.join(format!("{m}.ko.xz")));
}
write_dep(&kernel);
let err = verify_live_nvidia(dir.path(), DRIVER, NvidiaModuleFlavor::Open)
.unwrap_err()
.to_string();
assert!(err.contains("proprietary build"), "{err}");
}
#[test]
fn a_missing_final_modprobe_config_is_rejected() {
let dir = tempfile::tempdir().unwrap();
complete_rootfs(dir.path());
std::fs::remove_file(dir.path().join("etc/modprobe.d/phoebus-nvidia.conf")).unwrap();
let err = verify_live_nvidia(dir.path(), DRIVER, NvidiaModuleFlavor::Proprietary)
.unwrap_err()
.to_string();
assert!(err.contains("phoebus-nvidia.conf"), "{err}");
}
} }

View file

@ -5,7 +5,6 @@
//! independent of `run_cmd`). //! independent of `run_cmd`).
use std::collections::HashMap; use std::collections::HashMap;
use std::path::Path;
use phoebus_core::disk::{Disk, DiskKind}; use phoebus_core::disk::{Disk, DiskKind};
use phoebus_core::hardware::{ use phoebus_core::hardware::{
@ -237,50 +236,6 @@ pub fn probe_hardware(runner: &dyn ProcessRunner) -> HardwareReport {
} }
} }
/// Enumerate NVIDIA display controllers from sysfs.
///
/// `sysfs` is normally `/sys`; it is a parameter so the live driver decision
/// can be exercised against a fixture without root or the real machine's
/// hardware. Only display-class functions (`class >> 16 == 0x03`: VGA, 3D and
/// Display controllers) from vendor `0x10de` are returned.
pub fn probe_nvidia_display_devices(sysfs: &Path) -> Vec<GpuInfo> {
let mut out = Vec::new();
let dir = sysfs.join("bus/pci/devices");
let Ok(entries) = std::fs::read_dir(&dir) else {
return out;
};
for entry in entries.flatten() {
let base = entry.path();
let read = |name: &str| -> Option<String> {
std::fs::read_to_string(base.join(name))
.ok()
.map(|s| s.trim().to_string())
};
let (Some(class), Some(vendor), Some(device)) =
(read("class"), read("vendor"), read("device"))
else {
continue;
};
let parse = |s: &str| u32::from_str_radix(s.trim_start_matches("0x"), 16).ok();
let (Some(class), Some(vendor), Some(device)) =
(parse(&class), parse(&vendor), parse(&device))
else {
continue;
};
if (class >> 16) != 0x03 || vendor != 0x10de {
continue;
}
out.push(GpuInfo {
vendor: GpuVendor::Nvidia,
description: format!("NVIDIA display controller {vendor:04x}:{device:04x}"),
pci_id: Some(format!("{vendor:04x}:{device:04x}")),
pci_address: Some(entry.file_name().to_string_lossy().to_string()),
});
}
out.sort_by(|a, b| a.pci_id.cmp(&b.pci_id));
out
}
// --------------------------------------------------------------------------- // ---------------------------------------------------------------------------
// Disks // Disks
// --------------------------------------------------------------------------- // ---------------------------------------------------------------------------
@ -602,26 +557,4 @@ mod tests {
(None, Some("00:00.0".into())) (None, Some("00:00.0".into()))
); );
} }
#[test]
fn sysfs_scan_finds_only_nvidia_display_controllers() {
let dir = tempfile::tempdir().unwrap();
let devices = dir.path().join("bus/pci/devices");
let write = |addr: &str, class: &str, vendor: &str, device: &str| {
let d = devices.join(addr);
std::fs::create_dir_all(&d).unwrap();
std::fs::write(d.join("class"), class).unwrap();
std::fs::write(d.join("vendor"), vendor).unwrap();
std::fs::write(d.join("device"), device).unwrap();
};
write("0000:01:00.0", "0x030000", "0x10de", "0x2482");
// NVIDIA's HDA audio function on the same card is not a display device.
write("0000:01:00.1", "0x040300", "0x10de", "0x228b");
// An Intel display controller is left to the in-tree driver.
write("0000:00:02.0", "0x030000", "0x8086", "0x9a60");
let found = probe_nvidia_display_devices(dir.path());
assert_eq!(found.len(), 1);
assert_eq!(found[0].pci_id.as_deref(), Some("10de:2482"));
assert_eq!(found[0].pci_address.as_deref(), Some("0000:01:00.0"));
}
} }

View file

@ -134,21 +134,6 @@ struct Cli {
#[arg(long, value_name = "FLAVOR", hide = true)] #[arg(long, value_name = "FLAVOR", hide = true)]
nvidia_flavor: Option<String>, nvidia_flavor: Option<String>,
/// Print the live medium's display-driver decision as stable `key=value`
/// lines and exit. Consumed by the live-only `phoebus-nvidia-load`
/// service; the decision comes from the actual PCI display devices and the
/// bundled branch's capabilities, never from a vendor-name match.
#[arg(long, hide = true)]
live_gpu_plan: bool,
/// Override the sysfs root used by `--live-gpu-plan` (fixtures/testing).
#[arg(long, value_name = "PATH", hide = true)]
sysfs_root: Option<PathBuf>,
/// Override the kernel command line used by `--live-gpu-plan`.
#[arg(long, value_name = "CMDLINE", hide = true)]
kernel_cmdline: Option<String>,
/// Speak the typed JSON protocol used by the graphical installer frontend /// Speak the typed JSON protocol used by the graphical installer frontend
/// (stdin/stdout). Not intended for direct interactive use. /// (stdin/stdout). Not intended for direct interactive use.
#[arg(long, hide = true)] #[arg(long, hide = true)]
@ -227,35 +212,6 @@ fn verify_live_nvidia_command(cli: &Cli, rootfs: &std::path::Path) -> ExitCode {
} }
} }
/// Print the live medium's display-driver decision as stable `key=value` lines.
///
/// This is the single authority the live-only `phoebus-nvidia-load` service
/// consults. It is deterministic, read-only and outside the AI boundary: the
/// action follows the actual PCI display devices and the bundled branch, and
/// fail-safe graphics (`nomodeset` / `phoebus.nvidia=off`) always wins.
fn live_gpu_plan_command(cli: &Cli) -> ExitCode {
let sysfs = cli
.sysfs_root
.clone()
.unwrap_or_else(|| PathBuf::from("/sys"));
let cmdline = cli
.kernel_cmdline
.clone()
.or_else(|| std::fs::read_to_string("/proc/cmdline").ok())
.unwrap_or_default();
let fail_safe = cmdline
.split_whitespace()
.any(|tok| tok == "nomodeset" || tok == "phoebus.nvidia=off");
let gpus = phoebus_executor::probe::probe_nvidia_display_devices(&sysfs);
let devices: Vec<phoebus_core::nvidia::NvidiaDevice> = gpus
.iter()
.map(phoebus_core::nvidia::NvidiaDevice::from_gpu)
.collect();
let plan = phoebus_core::nvidia::live_nvidia_plan(&devices, fail_safe);
print!("{}", plan.render());
ExitCode::SUCCESS
}
struct TerminalConfirm; struct TerminalConfirm;
impl Confirmation for TerminalConfirm { impl Confirmation for TerminalConfirm {
@ -589,10 +545,6 @@ fn run() -> std::result::Result<ExitCode, Box<dyn std::error::Error>> {
}; };
} }
if cli.live_gpu_plan {
return Ok(live_gpu_plan_command(&cli));
}
if let Some(rootfs) = &cli.verify_live_nvidia { if let Some(rootfs) = &cli.verify_live_nvidia {
return Ok(verify_live_nvidia_command(&cli, rootfs)); return Ok(verify_live_nvidia_command(&cli, rootfs));
} }

View file

@ -524,13 +524,8 @@ impl Installer {
&self.engine, &self.engine,
&self.policy_ctx, &self.policy_ctx,
)?; )?;
// The modules exist now: force them into the initramfs, prove they
// were actually built for the selected kernel, then regenerate the
// boot image. A driver that produced no modules fails the install.
boot::write_nvidia_dracut_conf(&self.exec, &self.hardware)?;
let installed = boot::verify_nvidia_modules(&self.exec.root)?;
boot::generate_entries(&self.exec)?; boot::generate_entries(&self.exec)?;
self.record_nvidia(&plan, &installed)?; self.record_nvidia(&plan)?;
Ok(()) Ok(())
})(); })();
self.exec.umount_chroot()?; self.exec.umount_chroot()?;
@ -540,25 +535,11 @@ impl Installer {
result result
} }
/// Persist the resolved driver decision and the *actual* installed version /// Persist the resolved driver decision in the target so post-install
/// in the target, so post-install inspection and recovery know exactly what /// inspection and recovery know exactly what was selected.
/// was selected rather than only a "current" label. fn record_nvidia(&self, plan: &phoebus_core::nvidia::NvidiaPlan) -> Result<()> {
fn record_nvidia(
&self,
plan: &phoebus_core::nvidia::NvidiaPlan,
installed: &boot::InstalledNvidia,
) -> Result<()> {
let mut text = String::new(); let mut text = String::new();
text.push_str("# Resolved NVIDIA accelerated driver (generated by the installer).\n"); text.push_str("# Resolved NVIDIA accelerated driver (generated by the installer).\n");
text.push_str(&format!(
"version={}\n",
if installed.version.is_empty() {
"unknown"
} else {
&installed.version
}
));
text.push_str(&format!("kernel={}\n", installed.kernel));
text.push_str(&format!("branch={}\n", plan.branch)); text.push_str(&format!("branch={}\n", plan.branch));
text.push_str(&format!( text.push_str(&format!(
"flavor={}\n", "flavor={}\n",
@ -569,9 +550,6 @@ impl Installer {
plan.generation.map(|g| g.as_str()).unwrap_or("none") plan.generation.map(|g| g.as_str()).unwrap_or("none")
)); ));
text.push_str("package=x11-drivers/nvidia-drivers\n"); text.push_str("package=x11-drivers/nvidia-drivers\n");
for module in &installed.modules {
text.push_str(&format!("module={module}\n"));
}
for device in &plan.devices { for device in &plan.devices {
text.push_str(&format!( text.push_str(&format!(
"device={} {}\n", "device={} {}\n",
@ -581,12 +559,9 @@ impl Installer {
} }
text.push_str(&format!("reason={}\n", plan.reason)); text.push_str(&format!("reason={}\n", plan.reason));
self.exec.target().write("etc/phoebus/nvidia", text)?; self.exec.target().write("etc/phoebus/nvidia", text)?;
self.exec.logger.info(format!( self.exec
"recorded the NVIDIA driver selection in /etc/phoebus/nvidia (version {}, kernel {}, modules: {})", .logger
if installed.version.is_empty() { "unknown" } else { &installed.version }, .info("recorded the NVIDIA driver selection in /etc/phoebus/nvidia");
installed.kernel,
installed.modules.join(", ")
));
Ok(()) Ok(())
} }

View file

@ -66,21 +66,19 @@ fn every_bash_cli_mode_has_a_rust_flag() {
fn verify_live_nvidia_accepts_a_complete_payload_and_rejects_an_incomplete_one() { fn verify_live_nvidia_accepts_a_complete_payload_and_rejects_an_incomplete_one() {
fn touch(path: &std::path::Path) { fn touch(path: &std::path::Path) {
std::fs::create_dir_all(path.parent().unwrap()).unwrap(); std::fs::create_dir_all(path.parent().unwrap()).unwrap();
std::fs::write(path, vec![0u8; 8192]).unwrap(); std::fs::write(path, b"x").unwrap();
} }
fn complete(root: &std::path::Path) { fn complete(root: &std::path::Path) {
let kver = "6.16.7-amd64"; let kver = "6.16.7-amd64";
touch(&root.join(format!("boot/vmlinuz-{kver}"))); touch(&root.join(format!("boot/vmlinuz-{kver}")));
let modules = root.join(format!("lib/modules/{kver}")); let modules = root.join(format!("lib/modules/{kver}"));
std::fs::create_dir_all(&modules).unwrap(); std::fs::create_dir_all(&modules).unwrap();
let mut dep = Vec::new(); std::fs::write(modules.join("modules.dep"), b"").unwrap();
for m in ["nvidia", "nvidia_modeset", "nvidia_uvm", "nvidia_drm"] { for m in ["nvidia", "nvidia_modeset", "nvidia_uvm", "nvidia_drm"] {
touch(&modules.join(format!("updates/dkms/{m}.ko"))); touch(&modules.join(format!("updates/dkms/{m}.ko")));
dep.push(format!("updates/dkms/{m}.ko:"));
} }
std::fs::write(modules.join("modules.dep"), dep.join("\n")).unwrap();
for lib in [ for lib in [
"libnvidia-glcore.so.550.163.01", "libnvidia-glcore.so.550",
"libGLX_nvidia.so.0", "libGLX_nvidia.so.0",
"libnvidia-egl-gbm.so.1", "libnvidia-egl-gbm.so.1",
"libnvidia-egl-wayland.so.1", "libnvidia-egl-wayland.so.1",
@ -92,9 +90,9 @@ fn verify_live_nvidia_accepts_a_complete_payload_and_rejects_an_incomplete_one()
touch(&root.join("usr/share/egl/egl_external_platform.d/10_nvidia_wayland.json")); touch(&root.join("usr/share/egl/egl_external_platform.d/10_nvidia_wayland.json"));
touch(&root.join("usr/lib/firmware/nvidia/550.163.01/gsp.bin")); touch(&root.join("usr/lib/firmware/nvidia/550.163.01/gsp.bin"));
touch(&root.join("usr/local/bin/phoebus-nvidia-load")); touch(&root.join("usr/local/bin/phoebus-nvidia-load"));
let conf = root.join("etc/modprobe.d/phoebus-nvidia.conf"); let blacklist = root.join("etc/modprobe.d/nvidia-blacklists-nouveau.conf");
std::fs::create_dir_all(conf.parent().unwrap()).unwrap(); std::fs::create_dir_all(blacklist.parent().unwrap()).unwrap();
std::fs::write(&conf, b"blacklist nouveau\noptions nvidia_drm modeset=1\n").unwrap(); std::fs::write(&blacklist, b"blacklist nouveau\n").unwrap();
} }
let run = |root: &std::path::Path| { let run = |root: &std::path::Path| {
@ -134,66 +132,6 @@ fn verify_live_nvidia_accepts_a_complete_payload_and_rejects_an_incomplete_one()
assert_eq!(out.status.code(), Some(1)); assert_eq!(out.status.code(), Some(1));
} }
#[test]
fn live_gpu_plan_reflects_the_fixture_and_the_fail_safe_cmdline() {
fn write_device(root: &std::path::Path, addr: &str, class: &str, vendor: &str, device: &str) {
let d = root.join("bus/pci/devices").join(addr);
std::fs::create_dir_all(&d).unwrap();
std::fs::write(d.join("class"), class).unwrap();
std::fs::write(d.join("vendor"), vendor).unwrap();
std::fs::write(d.join("device"), device).unwrap();
}
let run = |sysfs: &std::path::Path, cmdline: &str| -> String {
let out = Command::new(env!("CARGO_BIN_EXE_phoebus-installer"))
.arg("--live-gpu-plan")
.arg("--sysfs-root")
.arg(sysfs)
.arg("--kernel-cmdline")
.arg(cmdline)
.output()
.expect("run --live-gpu-plan");
assert!(out.status.success());
String::from_utf8_lossy(&out.stdout).into_owned()
};
let supported = tempfile::tempdir().unwrap();
write_device(
supported.path(),
"0000:01:00.0",
"0x030000",
"0x10de",
"0x2482",
);
let plan = run(supported.path(), "quiet splash");
assert!(plan.contains("action=load-nvidia"), "{plan}");
assert!(plan.contains("device=10de:2482 Ampere"), "{plan}");
// Blackwell cannot be driven by the bundled 550 branch.
let blackwell = tempfile::tempdir().unwrap();
write_device(
blackwell.path(),
"0000:01:00.0",
"0x030000",
"0x10de",
"0x2b85",
);
let plan = run(blackwell.path(), "");
assert!(plan.contains("action=nouveau-fallback"), "{plan}");
assert!(plan.contains("unclaimed=10de:2b85 Blackwell"), "{plan}");
// Fail-safe graphics wins even with a supported GPU present.
let plan = run(supported.path(), "quiet nomodeset");
assert!(plan.contains("action=disabled"), "{plan}");
let plan = run(supported.path(), "quiet phoebus.nvidia=off");
assert!(plan.contains("action=disabled"), "{plan}");
// No NVIDIA display device -> leave auto-detection alone.
let none = tempfile::tempdir().unwrap();
write_device(none.path(), "0000:00:02.0", "0x030000", "0x8086", "0x9a60");
let plan = run(none.path(), "");
assert!(plan.contains("action=no-device"), "{plan}");
}
#[test] #[test]
fn relocated_opencode_manifest_is_pinned_and_complete() { fn relocated_opencode_manifest_is_pinned_and_complete() {
let path = manifest_path(); let path = manifest_path();

View file

@ -57,21 +57,12 @@ fn live_build_bundles_and_verifies_the_nvidia_payload() {
assert!(build.contains("trixie")); assert!(build.contains("trixie"));
assert!(build.contains("linux-kbuild-")); assert!(build.contains("linux-kbuild-"));
assert!(build.contains("--setup-hook")); assert!(build.contains("--setup-hook"));
// The live driver policy file the verifier requires is actually produced, // Nouveau blacklisting/module options come from nvidia-kernel-common; the
// and Debian's unconditional nouveau configuration is replaced so the // unconditional modules-load entry is removed in favour of the gated unit.
// explicit nouveau fallback can bind an unsupported GPU.
assert!(build.contains("etc/modprobe.d/phoebus-nvidia.conf"));
assert!(build.contains("nvidia-blacklists-nouveau.conf"));
assert!(build.contains("blacklist nouveau"));
// Nouveau blacklisting/module options no longer come solely from
// nvidia-kernel-common; its unconditional modules-load entry is removed in
// favour of the gated unit.
assert!(build.contains("nvidia-kernel-common")); assert!(build.contains("nvidia-kernel-common"));
assert!(build.contains("modules-load.d/nvidia.conf")); assert!(build.contains("modules-load.d/nvidia.conf"));
// A documented fail-safe entry disables NVIDIA for that boot, and marks the // A documented fail-safe entry disables NVIDIA for that boot.
// command line so the load script and unit both stand down.
assert!(build.contains("nomodeset")); assert!(build.contains("nomodeset"));
assert!(build.contains("phoebus.nvidia=off"));
assert!(build.contains("modprobe.blacklist=nvidia")); assert!(build.contains("modprobe.blacklist=nvidia"));
} }

View file

@ -83,14 +83,8 @@ launcher is missing; it never silently emits a text-only ISO.
completion. A second launch never opens a duplicate session. If Quickshell or completion. A second launch never opens a duplicate session. If Quickshell or
Wayland is unavailable the launcher falls back to the TUI/CLI. Wayland is unavailable the launcher falls back to the TUI/CLI.
- A text recovery console is available on the serial line and on another VT - A text recovery console is available on the serial line and on another VT
(`Ctrl+Alt+F2`): log in as `phoebus` / `phoebus` (live-only credential) and (`Ctrl+Alt+F2`): log in as `phoebus` / `phoebus` (live-only credential),
use `sudo` with that password. Unattended (`NOPASSWD`) escalation is scoped passwordless `sudo`.
to the two typed brokers — `/usr/local/bin/phoebus-installer` and
`/usr/local/bin/sys` — plus `systemctl poweroff`/`reboot`. There is no
`NOPASSWD: ALL`, no `sh -c` and no wildcard; the policy is emitted as
`live-sudoers`, installed to `/etc/sudoers.d/90-phoebus-live` and validated
with `visudo` at build time. The password-authenticated recovery console is
deliberate and preserved.
- The `phoebus-dwl` session remains selectable as a fallback. - The `phoebus-dwl` session remains selectable as a fallback.
## NVIDIA accelerated graphics ## NVIDIA accelerated graphics
@ -116,30 +110,24 @@ anything at boot.
`nvidia-kernel-dkms` renames them `nvidia-current`, `nvidia-current-modeset`, `nvidia-kernel-dkms` renames them `nvidia-current`, `nvidia-current-modeset`,
`nvidia-current-drm` and `nvidia-current-uvm`; the verifier and the hook `nvidia-current-drm` and `nvidia-current-uvm`; the verifier and the hook
accept either that naming or the upstream names. accept either that naming or the upstream names.
- `build.sh` then runs `phoebus-installer --verify-live-nvidia`. It is a - `build.sh` then runs `phoebus-installer --verify-live-nvidia`, which checks
compatibility gate, not a presence list: it rejects placeholder the kernel modules, the GLVND/EGL/GBM userspace libraries, `nvidia-smi`, the
modules/libraries, requires every module to be registered in the live kernel's EGL external-platform manifests, the GSP firmware, the gated load script and
`modules.dep`, checks the userspace `libnvidia-glcore` and firmware-directory the nouveau blacklist. It runs on **every** build, including
versions against the bundled driver, infers and checks the module flavor, `PHOEBUS_REUSE_ROOTFS=1`, so a cached rootfs can never silently ship without
requires non-empty GSP firmware and the exact the payload. The bundled driver version, module flavor and kernel are recorded
`etc/modprobe.d/phoebus-nvidia.conf`. It runs on **every** build, including in `/etc/phoebus/nvidia` on the medium.
`PHOEBUS_REUSE_ROOTFS=1`, so a cached rootfs can never silently ship a - Nouveau blacklisting and module options come from Debian's own
mismatched payload. The bundled driver version, module flavor and kernel are `nvidia-kernel-common`. Its unconditional modules-load entry is removed in
recorded in `/etc/phoebus/nvidia` on the medium. favour of the live-only `phoebus-nvidia.service`, which runs the gated
- The live load script makes a **deterministic, device-based decision** via `phoebus-nvidia-load` before greetd/Mango **only when an NVIDIA display device
`phoebus-installer --live-gpu-plan`, not a `0x10de` vendor grep. A supported is present**, so systems without one keep nouveau/virtio and record no failed
GPU loads the bundled accelerated stack; an unsupported GPU (or a failed unit.
accelerated load) explicitly `modprobe`s `nouveau`; a machine with no NVIDIA - The GRUB **fail-safe graphics** entry disables modesetting
display device leaves auto-detection alone. `build.sh` writes (`nomodeset`) and blacklists the NVIDIA modules for that boot; it is the
`etc/modprobe.d/phoebus-nvidia.conf` (replacing Debian's unconditional documented recovery path when driver initialisation misbehaves. Use
nouveau configuration), so the fallback is real. Debian's unconditional `phoebus-gpu-report` for read-only diagnostics (PCI devices, loaded modules,
modules-load entry is removed in favour of `phoebus-nvidia.service`, which `nvidia_drm` modeset, `nvidia-smi`, recent kernel messages).
runs the script before greetd/Mango.
- The GRUB **fail-safe graphics** entry sets `nomodeset phoebus.nvidia=off` and
blacklists the NVIDIA modules for that boot; the load script and the unit both
stand down, so recovery intent is authoritative. Use `phoebus-gpu-report` for
read-only diagnostics (PCI devices, loaded modules, `nvidia_drm` modeset,
`nvidia-smi`, recent kernel messages).
- The installed Gentoo target is unaffected: it uses Portage - The installed Gentoo target is unaffected: it uses Portage
(`x11-drivers/nvidia-drivers`) with the branch/flavor selected from the PCI (`x11-drivers/nvidia-drivers`) with the branch/flavor selected from the PCI
device IDs — open kernel modules for Turing and newer, the proprietary branch device IDs — open kernel modules for Turing and newer, the proprietary branch

View file

@ -102,7 +102,7 @@ assets=(
session-mango session-dwl assistant install welcome menu lock idle session-mango session-dwl assistant install welcome menu lock idle
mango-config mango-session-target install-desktop mango-config mango-session-target install-desktop
wayland-session-mango wayland-session-dwl wayland-session-mango wayland-session-dwl
waybar-config waybar-style greetd-live live-sudoers waybar-config waybar-style greetd-live
brand-emblem brand-wordmark brand-wallpaper brand-tokens brand-emblem brand-wordmark brand-wallpaper brand-tokens
nvidia-load nvidia-service gpu-report nvidia-load nvidia-service gpu-report
) )
@ -256,18 +256,6 @@ install_asset waybar-style /etc/xdg/waybar/style.css
# Live-only automatic login (never copied to an installed system). # Live-only automatic login (never copied to an installed system).
install_asset greetd-live /etc/greetd/config.toml install_asset greetd-live /etc/greetd/config.toml
# Live-only privilege policy. The recovery console keeps root through the
# password-authenticated sudo group; unattended escalation is scoped to the
# typed brokers. Reject a broad or malformed policy rather than ship it.
install -d -m 0755 "$rootfs/etc/sudoers.d"
install -D -m 0440 "$work/assets/live-sudoers" "$rootfs/etc/sudoers.d/90-phoebus-live"
if command -v visudo >/dev/null 2>&1; then
visudo -cf "$rootfs/etc/sudoers.d/90-phoebus-live" >/dev/null || {
echo "the emitted live sudoers policy is invalid" >&2; exit 1; }
fi
grep -qE 'NOPASSWD:[[:space:]]*ALL|ALL=\(ALL\)' "$rootfs/etc/sudoers.d/90-phoebus-live" && {
echo "refusing to ship an unscoped live sudoers policy" >&2; exit 1; } || true
# NVIDIA accelerated driver: load it before greetd/Mango, and provide # NVIDIA accelerated driver: load it before greetd/Mango, and provide
# diagnostics. The driver modules themselves are built into the rootfs by # diagnostics. The driver modules themselves are built into the rootfs by
# livefs-hook.sh; nouveau blacklisting and module options come from Debian's # livefs-hook.sh; nouveau blacklisting and module options come from Debian's
@ -282,21 +270,6 @@ ln -sf /usr/lib/systemd/system/phoebus-nvidia.service \
# with no NVIDIA GPU that can leave a failed unit, so remove it and rely on the # with no NVIDIA GPU that can leave a failed unit, so remove it and rely on the
# gated service above (which is a no-op without an NVIDIA display device). # gated service above (which is a no-op without an NVIDIA display device).
rm -f "$rootfs/etc/modules-load.d/nvidia.conf" rm -f "$rootfs/etc/modules-load.d/nvidia.conf"
# The live module policy. nouveau is blacklisted so it cannot *auto-bind* a GPU
# the accelerated stack is meant to drive; the load script explicitly modprobes
# nouveau for an unsupported GPU (a blacklist only suppresses alias-based
# auto-loading). Debian's own nvidia-kernel-common file is replaced so its
# unconditional nouveau options cannot defeat that fallback, and the file the
# payload verifier checks is produced here rather than only on the installed
# Gentoo target.
rm -f "$rootfs/etc/modprobe.d/nvidia-blacklists-nouveau.conf"
install -d -m 0755 "$rootfs/etc/modprobe.d"
cat > "$rootfs/etc/modprobe.d/phoebus-nvidia.conf" <<'NVIDIA'
# NVIDIA accelerated graphics on the Phoebus live medium (generated at build).
blacklist nouveau
options nvidia_drm modeset=1
softdep nvidia post: nvidia-uvm
NVIDIA
# Build-time gate: the assembled rootfs (cached or fresh) MUST carry a complete # Build-time gate: the assembled rootfs (cached or fresh) MUST carry a complete
# NVIDIA payload for its exact kernel, or the build fails. This also writes # NVIDIA payload for its exact kernel, or the build fails. This also writes
@ -464,7 +437,7 @@ t = t.replace('menuentry "Live system (amd64 fail-safe mode)"',
# entry is unaffected. This is a recovery path, not the default. # entry is unaffected. This is a recovery path, not the default.
t = t.replace( t = t.replace(
'nosplash vga=788', 'nosplash vga=788',
'nosplash vga=788 nomodeset phoebus.nvidia=off ' 'nosplash vga=788 nomodeset '
'modprobe.blacklist=nvidia,nvidia_modeset,nvidia_uvm,nvidia_drm') 'modprobe.blacklist=nvidia,nvidia_modeset,nvidia_uvm,nvidia_drm')
open(p, "w").write(t) open(p, "w").write(t)
PY PY

View file

@ -33,9 +33,8 @@ if ! in_root id "$LIVE_USER" >/dev/null 2>&1; then
--groups sudo,video,render,input,audio "$LIVE_USER" --groups sudo,video,render,input,audio "$LIVE_USER"
fi fi
install -d -m 0755 "$root/etc/sudoers.d" install -d -m 0755 "$root/etc/sudoers.d"
# The live privilege policy is the scoped, visudo-validated asset installed by printf '%s ALL=(ALL) NOPASSWD: ALL\n' "$LIVE_USER" > "$root/etc/sudoers.d/90-phoebus-live"
# build.sh (only the typed brokers escalate without a prompt). The recovery chmod 440 "$root/etc/sudoers.d/90-phoebus-live"
# console keeps root through the password-authenticated sudo group below.
# A well-known live password so the serial/recovery console is usable; the # A well-known live password so the serial/recovery console is usable; the
# graphical session still logs in automatically via greetd. This is live-only # graphical session still logs in automatically via greetd. This is live-only
# and is never written to an installed system. # and is never written to an installed system.

View file

@ -7,10 +7,7 @@ touching a physical disk. The target is always a qcow2 file.
- `run-vm.sh` interactive QEMU launcher (manual testing). - `run-vm.sh` interactive QEMU launcher (manual testing).
- `install.sh` guest-side, non-interactive installation (run in the VM). - `install.sh` guest-side, non-interactive installation (run in the VM).
- `serial-driver.py` host-side pexpect driver (`install`, `boot` and - `serial-driver.py` host-side pexpect driver (`install` and `boot` modes).
`rollback` modes).
- `rollback-guest.sh`, `rollback-verify.sh` guest-side rollback acceptance
(fetch `sys`, snapshot, break, undo, verify).
- `test.conf.example` installer configuration used by the driver. - `test.conf.example` installer configuration used by the driver.
## Host prerequisites ## Host prerequisites
@ -65,33 +62,6 @@ To patch a console into an existing entry for observation, the BLS entry in
`/efi/loader/entries/*.conf` takes an `options` line; the installer can also `/efi/loader/entries/*.conf` takes an `options` line; the installer can also
embed a console via `KERNEL_CONSOLE` (`GENTOO_KERNEL_CONSOLE` equivalent). embed a console via `KERNEL_CONSOLE` (`GENTOO_KERNEL_CONSOLE` equivalent).
## Rollback acceptance (`serial-driver.py rollback`)
`rollback` drives the real rollback path end to end on an
**already-installed** disposable disk:
1. boot the installed disk, unlock LUKS and log in;
2. fetch `sys` and `rollback-guest.sh` from the host (the target does not yet
install `sys`; see `docs/HANDOFF.md`), record the `/var/db/pkg` fingerprint
and a `/home` marker, create a recovery point with `sys snapshot`, install a
small package (a controlled, reversible update) and run `sys undo`;
3. power off, boot the disk detached, and run `rollback-verify.sh`, comparing
the package fingerprint and the `/home` marker, checking kernel modules, and
reading the snapshot recovery entry and `sys rollback status`.
Serve the fixtures as well as the installer:
```sh
cp installer/tests/vm/rollback-guest.sh installer/tests/vm/rollback-verify.sh /path/to/serve/
cp installer-rs/target/x86_64-unknown-linux-gnu/release/sys /path/to/serve/
DISK=/tmp/phoebus/installed-clone.qcow2 OVMF_CODE=... OVMF_VARS=... \
python3 installer/tests/vm/serial-driver.py rollback
```
Point `DISK` at a **disposable clone** of the evidence image so the original is
preserved. Booting the recovery entry itself with the network removed remains a
manual gate; the harness records the entry but does not select it.
## Safety (enforced, not just documented) ## Safety (enforced, not just documented)
`vmsafety.py` validates every writable drive before QEMU starts: `vmsafety.py` validates every writable drive before QEMU starts:

View file

@ -14,8 +14,7 @@ Modes:
opencode: drive the OpenCode AI step through the real graphical UI and opencode: drive the OpenCode AI step through the real graphical UI and
validate a model response and proposal. validate a model response and proposal.
gui-install: complete a full installation through the visible wizard (AI gui-install: complete a full installation through the visible wizard (AI
connection, disk, account, direct "Install now", install) on a connection, disk, account, ERASE, install) on a disposable disk.
disposable disk.
install : boot, log in on serial, fetch a non-interactive config and 0600 install : boot, log in on serial, fetch a non-interactive config and 0600
secrets over QEMU user networking, run the deterministic install secrets over QEMU user networking, run the deterministic install
with the static binary, scan the log for a secret leak, power off. with the static binary, scan the log for a secret leak, power off.
@ -58,12 +57,11 @@ LIVE_PW = os.environ.get("LIVE_PASSWORD", "phoebus")
USER = os.environ.get("USERNAME", "phoebus") USER = os.environ.get("USERNAME", "phoebus")
USER_PW = os.environ.get("USER_PASSWORD", "phoebus-user-test") USER_PW = os.environ.get("USER_PASSWORD", "phoebus-user-test")
LUKS_PW = os.environ.get("LUKS_PASSPHRASE", "phoebus-luks-test") LUKS_PW = os.environ.get("LUKS_PASSPHRASE", "phoebus-luks-test")
USER_NAME = os.environ.get("USER_USERNAME", USER)
HOST_NAME = os.environ.get("HOST_NAME", "phoebus-vm")
MEM = os.environ.get("VM_MEM", "8192") MEM = os.environ.get("VM_MEM", "8192")
SMP = os.environ.get("VM_SMP", "8") SMP = os.environ.get("VM_SMP", "8")
BOOT_TIMEOUT = int(os.environ.get("BOOT_TIMEOUT", "900")) BOOT_TIMEOUT = int(os.environ.get("BOOT_TIMEOUT", "900"))
INSTALL_TIMEOUT = int(os.environ.get("INSTALL_TIMEOUT", "10800")) INSTALL_TIMEOUT = int(os.environ.get("INSTALL_TIMEOUT", "10800"))
SESSION_SETTLE = int(os.environ.get("SESSION_SETTLE", "20"))
BACKEND_SETTLE = int(os.environ.get("BACKEND_SETTLE", "30")) BACKEND_SETTLE = int(os.environ.get("BACKEND_SETTLE", "30"))
# OpenCode GUI-driving knobs (test-only). The wizard focuses the first AI # OpenCode GUI-driving knobs (test-only). The wizard focuses the first AI
# provider chip when the AI step opens, so three Tabs reach the OpenCode chip. # provider chip when the AI step opens, so three Tabs reach the OpenCode chip.
@ -501,16 +499,12 @@ class Driver:
f"n1={n1} n2={n2}", f"n1={n1} n2={n2}",
) )
# The installer opens directly on step 1 (language and keyboard): the # Keyboard-walk the wizard, capturing each step. The welcome step's
# duplicate step-0 welcome was removed. Capture it and walk with # primary action is focused, so Return starts the journey; Ctrl+Right
# Ctrl+Right from the frontend's own state, not a keystroke count. # then advances through the deterministic steps.
at_language = self._goto_step(1) self.sendkey("ret")
self.results.assert_true( time.sleep(2)
"language-step-reached", self.shot("03-language", "language and keyboard", "Return on Get started",
at_language is not None and at_language["step"] == 1,
f"the wizard did not open on the language step: {at_language}",
)
self.shot("03-language", "language and keyboard", "installer opened",
"the language and keyboard step is shown") "the language and keyboard step is shown")
# Regression: the suggestion list supports arrow-key navigation and # Regression: the suggestion list supports arrow-key navigation and
# Enter selection, with the value stored being the identifier. # Enter selection, with the value stored being the identifier.
@ -532,16 +526,13 @@ class Driver:
) )
self.shot("03b-locale-selected", "locale selected", "Down then Enter", self.shot("03b-locale-selected", "locale selected", "Down then Enter",
"the highlighted locale is selected") "the highlighted locale is selected")
for slug, label, target in [ for slug, state in [
("04-network", "network and prerequisites", 2), ("04-network", "network and prerequisites"),
("05-ai-model", "AI model connection", 3), ("05-ai-model", "AI model connection"),
]: ]:
reached = self._goto_step(target) self.sendkey("ctrl-right")
self.results.assert_true( time.sleep(2)
f"{slug}-reached", reached is not None and reached["step"] == target, self.shot(slug, state, "Ctrl+Right", "next wizard step")
f"did not reach {label}: {reached}",
)
self.shot(slug, label, "Ctrl+Right", "next wizard step")
if not self._installer_alive(): if not self._installer_alive():
self.results.fail("installer-survived-navigation", f"crashed at {slug}") self.results.fail("installer-survived-navigation", f"crashed at {slug}")
return return
@ -664,36 +655,6 @@ class Driver:
time.sleep(2) time.sleep(2)
return None return None
def _goto_step(self, target: int, *, timeout: int = 90) -> dict | None:
"""Advance to a wizard step using the frontend's own state.
The installer now starts directly on step 1 (the duplicate step-0
welcome was removed), so counting keystrokes is brittle. Poll the
secret-free state line and advance with Ctrl+Right until the step is
reached: a state-based wait, not a fixed number of keypresses.
"""
state = self._frontend_state()
if state is not None and state["step"] >= target:
return state
deadline = time.monotonic() + timeout
while time.monotonic() < deadline:
self.sendkey("ctrl-right")
time.sleep(1.5)
state = self._frontend_state()
if state is not None and state["step"] >= target:
return state
return state
def _install_progress(self) -> str:
"""A short, secret-free description of the current install state."""
state = self._frontend_state()
if state is None:
return "no frontend state line available"
return (
f"step={state['step']} phase={state['phase']} "
f"aiConnected={state['aiConnected']}"
)
def do_opencode(self) -> None: def do_opencode(self) -> None:
"""Drive the OpenCode AI step through the real graphical UI. """Drive the OpenCode AI step through the real graphical UI.
@ -745,13 +706,19 @@ class Driver:
"CLOSED", timeout=30, label="close-welcome", "CLOSED", timeout=30, label="close-welcome",
) )
# Navigate to the AI step from step 1 (language -> network -> AI). # Navigate to the AI step (welcome -> language -> network -> AI).
state = self._goto_step(3) self.sendkey("ret")
time.sleep(2)
self.sendkey("ctrl-right")
time.sleep(2)
self.sendkey("ctrl-right")
time.sleep(2)
state = self._frontend_state()
self.results.assert_true( self.results.assert_true(
"ai-step-reached", state is not None and state["step"] == 3, "ai-step-reached", state is not None and state["step"] == 3,
f"frontend state: {state}", f"frontend state: {state}",
) )
self.shot("oc-01-ai", "AI step", "Ctrl+Right to step 3", "the AI model step is shown") self.shot("oc-01-ai", "AI step", "Return + Ctrl+Right twice", "the AI model step is shown")
# Select the "OpenCode agent" chip with the keyboard. The AI step opens # Select the "OpenCode agent" chip with the keyboard. The AI step opens
# with the first provider chip focused. # with the first provider chip focused.
@ -923,9 +890,8 @@ class Driver:
`appliance-guest-gui.sh` installs non-interactively, which does not `appliance-guest-gui.sh` installs non-interactively, which does not
prove the graphical journey. This mode presses the real controls: it prove the graphical journey. This mode presses the real controls: it
connects OpenCode through the UI, accepts the reviewed AI changes, connects OpenCode through the UI, accepts the reviewed AI changes,
selects a disk, sets the account, triggers the direct "Install now" selects a disk, sets the account, types ERASE, installs, and checks the
action, and checks the frontend reports completion. The disk must be a frontend reports completion. The disk must be a disposable qcow2.
disposable qcow2.
""" """
if not self.disks: if not self.disks:
self.results.blocked("gui-install-disk", "no writable disk configured") self.results.blocked("gui-install-disk", "no writable disk configured")
@ -942,17 +908,12 @@ class Driver:
self.set_wayland() self.set_wayland()
# Preseed the wizard defaults so the run is bounded (safe kernel, no # Preseed the wizard defaults so the run is bounded (safe kernel, no
# desktop) while the wizard, validation, AI gate and the direct # desktop) while the wizard, validation, AI gate and ERASE confirmation
# "Install now" authorization remain the real graphical path. # remain the real graphical path.
# The live privilege policy no longer grants bare `install`, so stage
# the config and authenticate the one privileged write with the
# live-only credential, fetched to a 0600 file (never on the command
# line and never in the serial transcript).
self.shell( self.shell(
f"curl -fsSL {SERVE_URL}/test.conf -o /tmp/gui-install.conf && " f"curl -fsSL {SERVE_URL}/test.conf -o /tmp/gui-install.conf && "
f"curl -fsSL {SERVE_URL}/live.pw -o /tmp/live.pw && chmod 600 /tmp/live.pw && " "sudo -n install -D -m 0644 /tmp/gui-install.conf /etc/phoebus/install.conf && "
"sudo -S -p '' install -D -m 0644 /tmp/gui-install.conf /etc/phoebus/install.conf " "echo PRESEED-$(printf DONE)",
"< /tmp/live.pw && echo PRESEED-$(printf DONE)",
"PRESEED-DONE", timeout=60, label="preseed-config", "PRESEED-DONE", timeout=60, label="preseed-config",
) )
# Start the loopback relay to the host OpenCode server. # Start the loopback relay to the host OpenCode server.
@ -988,11 +949,17 @@ class Driver:
"CLOSED", timeout=30, label="close-welcome", "CLOSED", timeout=30, label="close-welcome",
) )
# The installer opens on step 1; advance to the AI step. # Welcome -> language -> network -> AI.
state = self._goto_step(3) self.sendkey("ret")
time.sleep(2)
self.sendkey("ctrl-right")
time.sleep(2)
self.sendkey("ctrl-right")
time.sleep(3)
state = self._frontend_state()
self.results.assert_true("gui-install-ai-step", state is not None and state["step"] == 3, self.results.assert_true("gui-install-ai-step", state is not None and state["step"] == 3,
f"AI step not reached: {state}") f"AI step not reached: {state}")
self.shot("gi-01-ai", "AI step", "Ctrl+Right to step 3", "AI connection step") self.shot("gi-01-ai", "AI step", "Return, Ctrl+Right twice", "AI connection step")
# Select OpenCode and connect through the UI. # Select OpenCode and connect through the UI.
for _ in range(OC_TAB_TO_CHIP): for _ in range(OC_TAB_TO_CHIP):
@ -1027,7 +994,8 @@ class Driver:
self.shot("gi-02-ai-reviewed", "AI reviewed", "Accept changes", "review accepted") self.shot("gi-02-ai-reviewed", "AI reviewed", "Accept changes", "review accepted")
# Destination disk: pick the first selectable disk. # Destination disk: pick the first selectable disk.
self._goto_step(4) self.sendkey("ctrl-right")
time.sleep(3)
self.sendkey("tab") self.sendkey("tab")
time.sleep(0.5) time.sleep(0.5)
self.sendkey("ret") self.sendkey("ret")
@ -1073,66 +1041,59 @@ class Driver:
f"the disk selection did not survive backtracking: {state}", f"the disk selection did not survive backtracking: {state}",
) )
# Account and encryption. The current product has a single Username # Account and encryption.
# field, a Computer name, Password and Confirm password; the self.sendkey("ctrl-right")
# "Use same password to encrypt disk" toggle is on by default, so the time.sleep(2)
# separate LUKS passphrase fields are hidden and must not be driven. state = self._frontend_state()
state = self._goto_step(5)
self.results.assert_true("gui-install-account-step", state is not None and state["step"] == 5, self.results.assert_true("gui-install-account-step", state is not None and state["step"] == 5,
f"account step not reached: {state}") f"account step not reached: {state}")
# Focus opens on Username. self._tabs(3) # full name -> username -> computer name -> password
self._gui_type(USER_NAME)
self._tabs(1) # -> Computer name
self._gui_type(HOST_NAME)
self._tabs(1) # -> Password
self._gui_type(USER_PW) self._gui_type(USER_PW)
self._tabs(1) # -> Confirm password self._tabs(2) # reveal -> confirm password
self._gui_type(USER_PW) self._gui_type(USER_PW)
self._tabs(2) # reveal -> passphrase
self._gui_type(LUKS_PW)
self._tabs(2) # reveal -> confirm passphrase
self._gui_type(LUKS_PW)
self.shot("gi-04-account", "account and encryption", "typed credentials", self.shot("gi-04-account", "account and encryption", "typed credentials",
"username, computer name and matching password entered") "password and passphrase entered")
# Review. The product now uses a direct "Install now" action: typing # Review and ERASE. The review step focuses the ERASE field.
# ERASE and the confirmation checkbox were intentionally removed, and self.sendkey("ctrl-right")
# Ctrl+Right on the review step runs exactly that action. The backend time.sleep(4)
# still enforces approval binding and disk revalidation. state = self._frontend_state()
state = self._goto_step(6)
self.results.assert_true("gui-install-review-step", state is not None and state["step"] == 6, self.results.assert_true("gui-install-review-step", state is not None and state["step"] == 6,
f"review step not reached: {state}") f"review step not reached: {state}")
self.shot("gi-05-review", "review and confirmation", "review shown", self.shot("gi-05-review", "review and confirmation", "review shown",
"backend facts and the installation plan") "backend facts, plan and ERASE confirmation")
self.sendkey("ctrl-right") # Install now self._gui_type("ERASE")
started = time.monotonic() self.sendkey("tab") # the confirmation toggle
time.sleep(0.4)
confirmed = self._frontend_state()
# The toggle responds to Return and Space; QEMU names Space `spc`.
for key in ("ret", "spc"):
if confirmed is not None and confirmed["confirm"]:
break
self.sendkey(key)
time.sleep(0.5)
confirmed = self._frontend_state()
if confirmed is None or not confirmed["confirm"]:
self.results.fail(
"gui-install-erase-confirmed",
f"the confirmation toggle was not ticked: {confirmed}",
)
return
self.results.pass_("gui-install-erase-confirmed")
self.sendkey("ctrl-right") # authorize and install
self.shot("gi-06-installing", "installing", "Ctrl+Right on review", self.shot("gi-06-installing", "installing", "Ctrl+Right on review",
"the installation has started") "the installation has started")
# Approval replay: once the install is underway, submitting the review
# again must not crash the installer or regress it to a failure. The
# backend binds the authorization to the reviewed plan; the frontend
# must survive a repeated action.
underway = self.wait_state(
lambda s: s["phase"] in ("installing", "done", "failed"), timeout=180
)
if underway is not None:
self.sendkey("ctrl-right")
time.sleep(3)
replay = self._frontend_state()
self.results.assert_true(
"gui-install-replay-safe",
replay is not None and replay["phase"] != "failed" and self._installer_alive(),
f"re-submitting the review was not handled safely: {replay}",
)
done = self.wait_state( done = self.wait_state(
lambda s: s["phase"] in ("done", "failed"), lambda s: s["phase"] in ("done", "failed"),
timeout=INSTALL_TIMEOUT, timeout=INSTALL_TIMEOUT,
) )
if done is None: if done is None:
elapsed = int(time.monotonic() - started) self.results.fail("gui-install-completes", "the wizard did not report completion")
self.results.fail(
"gui-install-completes",
f"the wizard did not report completion after {elapsed}s "
f"({self._install_progress()})",
)
return return
self.results.assert_true( self.results.assert_true(
"gui-install-completes", done["phase"] == "done", "gui-install-completes", done["phase"] == "done",
@ -1250,20 +1211,7 @@ class Driver:
assert self.child is not None assert self.child is not None
idx = self.expect([r"[Pp]assphrase", r"login:"], timeout=BOOT_TIMEOUT, label="boot-prompt") idx = self.expect([r"[Pp]assphrase", r"login:"], timeout=BOOT_TIMEOUT, label="boot-prompt")
if idx == 0: if idx == 0:
# `gui-install` uses the default single-password encryption, so the self.child.sendline(LUKS_PW)
# disk passphrase is the user password; the non-interactive
# `install` journey sets a separate one. Try both, in that order,
# and let cryptsetup's immediate re-prompt disambiguate without
# consuming the login prompt on success.
override = os.environ.get("BOOT_PASSPHRASE")
candidates = [override] if override else [USER_PW, LUKS_PW]
self.child.sendline(candidates[0])
for candidate in candidates[1:]:
try:
self.child.expect(r"[Pp]assphrase", timeout=15)
self.child.sendline(candidate)
except (pexpect.TIMEOUT, pexpect.EOF):
break # accepted; the system is booting
logged_in = False logged_in = False
for _ in range(5): for _ in range(5):
try: try:

View file

@ -110,7 +110,7 @@ def main():
"pgrep -a qs || pgrep -a quickshell || echo NO-QUICKSHELL; " "pgrep -a qs || pgrep -a quickshell || echo NO-QUICKSHELL; "
"pgrep -af 'waybar|mako|swayidle|swaylock' || echo NO-DWL-HELPERS; " "pgrep -af 'waybar|mako|swayidle|swaylock' || echo NO-DWL-HELPERS; "
"ls -l /dev/dri 2>&1; " "ls -l /dev/dri 2>&1; "
"systemctl is-enabled greetd; " "sudo -n systemctl is-enabled greetd; "
"echo ===CHECKS-$(printf END)===", "echo ===CHECKS-$(printf END)===",
) )
child.sendline(checks) child.sendline(checks)

View file

@ -1,56 +0,0 @@
#!/bin/bash
# Guest-side rollback acceptance for the disposable VM.
#
# Fetched and run by `serial-driver.py rollback` inside an already-installed
# Phoebus system. It establishes a known-good package/root state, creates a
# recovery point through the supported `sys` interface, introduces a
# controlled, reversible mutation, runs the real `sys undo` path and powers
# off. The host then boots the disk detached and verifies the restored state.
#
# `sys` is fetched from the host (it is not installed into the target yet; see
# docs/HANDOFF.md), so this exercises the real command path, not a mock.
set -uo pipefail
SERVE="${SERVE_URL:-http://10.0.2.2:8000}"
SYS="${SYS_BIN:-/tmp/sys}"
USER_NAME="${USERNAME:-phoebus}"
WORK=/tmp/phoebus-rollback
mkdir -p "$WORK"
pkg_fingerprint() {
# The package database, not a marker file: a rollback must restore it.
find /var/db/pkg -mindepth 2 -maxdepth 2 -type d 2>/dev/null \
| sort | sha256sum | awk '{print $1}'
}
# 1. Establish and record a known-good root/package state. The /home marker
# proves user data survives (it is not part of the snapshotted subvolumes).
KERNEL="$(uname -r)"
HOME_MARKER="rollback-marker-$$-$KERNEL"
printf '%s\n' "$HOME_MARKER" > "/home/$USER_NAME/rollback-marker.txt"
PKGS_BEFORE="$(pkg_fingerprint)"
echo "===ROLLBACK-KNOWN-GOOD pkgs=$PKGS_BEFORE kernel=$KERNEL home=$HOME_MARKER==="
# 2. Create the recovery point through the supported interface.
"$SYS" -y snapshot "rollback acceptance" > "$WORK/snapshot.out" 2>&1
SNAP_ID="$(sed -n 's/^protective snapshot: //p' "$WORK/snapshot.out" | tail -1)"
echo "===ROLLBACK-SNAPSHOT id=$SNAP_ID==="
# 3. Controlled, reversible update failure. A small package install is a real
# update: it changes both the root subvolume and /var/db/pkg, and a snapshot
# can restore it. A root marker proves the root generation too.
printf 'broken by rollback acceptance\n' > /etc/phoebus/rollback-broken.txt 2>/dev/null || true
"$SYS" -y install app-editors/nano > "$WORK/break.out" 2>&1
echo "===ROLLBACK-BROKEN pkgs=$(pkg_fingerprint)==="
# 4. Invoke the real sys undo path.
"$SYS" -y undo > "$WORK/undo.out" 2>&1
RC=$?
echo "===ROLLBACK-UNDO rc=$RC==="
"$SYS" rollback status > "$WORK/status.out" 2>&1 || true
sed -n '1,40p' "$WORK/status.out"
echo "===ROLLBACK-DONE==="
sync
sudo -n poweroff -f || poweroff -f
echo "===POWEROFF==="

View file

@ -1,53 +0,0 @@
#!/bin/bash
# Guest-side post-rollback verification for the disposable VM.
#
# Fetched and run by `serial-driver.py rollback` after the detached reboot. It
# records the restored root/var generation, the package-database fingerprint,
# kernel modules, the /home marker, the recovery BLS entry and `sys rollback
# status`. The host compares these against the pre-rollback markers; a marker
# alone would not prove package-state consistency.
set -uo pipefail
SYS="${SYS_BIN:-/tmp/sys}"
USER_NAME="${USERNAME:-phoebus}"
pkg_fingerprint() {
find /var/db/pkg -mindepth 2 -maxdepth 2 -type d 2>/dev/null \
| sort | sha256sum | awk '{print $1}'
}
HOME_MARKER="$(cat "/home/$USER_NAME/rollback-marker.txt" 2>/dev/null || echo missing)"
echo "===AFTER-KNOWN-GOOD pkgs=$(pkg_fingerprint) kernel=$(uname -r) home=$HOME_MARKER==="
if [ -e /etc/phoebus/rollback-broken.txt ]; then
echo "===AFTER-BROKEN-MARKER present==="
else
echo "===AFTER-BROKEN-MARKER absent==="
fi
echo "===AFTER-ROOT==="
btrfs subvolume show / 2>&1 | sed -n '1,10p'
echo "===AFTER-VAR==="
btrfs subvolume show /var 2>&1 | sed -n '1,10p'
if [ -d "/lib/modules/$(uname -r)" ]; then
echo "===AFTER-MODULES ok==="
else
echo "===AFTER-MODULES missing==="
fi
echo "===AFTER-ENTRIES==="
for d in /efi/loader/entries /boot/efi/loader/entries; do
if [ -d "$d" ]; then
ls "$d"
break
fi
done
echo "===AFTER-RECOVERY==="
cat /efi/loader/entries/phoebus-recovery.conf \
/boot/efi/loader/entries/phoebus-recovery.conf 2>/dev/null || true
echo "===AFTER-STATUS==="
"$SYS" rollback status 2>&1 || true
echo "===AFTER-DONE==="

View file

@ -1,17 +1,12 @@
#!/usr/bin/env python3 #!/usr/bin/env python3
"""Headless serial driver for the disposable UEFI VM. """Headless serial driver for the disposable UEFI VM.
Modes: Two modes:
install : boot the live ISO kernel/initrd, run a guest script that installs install : boot the live ISO kernel/initrd, run a guest script that installs
Phoebus non-interactively, then power off. Phoebus non-interactively, then power off.
boot : boot the installed disk alone (no ISO, no -kernel), unlock LUKS, boot : boot the installed disk alone (no ISO, no -kernel), unlock LUKS,
log in and run verification commands. log in and run verification commands.
rollback: boot an installed disk, record a known-good state, create a
recovery point through `sys snapshot`, introduce a reversible
update, run the real `sys undo`, power off and boot detached to
verify the restored root/var and package state. Destructive: point
DISK at a disposable clone, never a physical device.
Everything is parameterised through environment variables so the script is not Everything is parameterised through environment variables so the script is not
tied to one host. See tests/vm/README.md for the variables. tied to one host. See tests/vm/README.md for the variables.
@ -49,13 +44,6 @@ BLS_APPEND = (
"rd.live.squashimg=image.squashfs cdroot console=ttyS0,115200" "rd.live.squashimg=image.squashfs cdroot console=ttyS0,115200"
) )
# Rollback acceptance fixtures, served from the host over QEMU user networking.
ROLLBACK_URL = os.environ.get("ROLLBACK_URL", "http://10.0.2.2:8000/rollback-guest.sh")
ROLLBACK_VERIFY_URL = os.environ.get(
"ROLLBACK_VERIFY_URL", "http://10.0.2.2:8000/rollback-verify.sh"
)
SYS_URL = os.environ.get("SYS_URL", "http://10.0.2.2:8000/sys")
def disposable_dir(): def disposable_dir():
import pathlib import pathlib
@ -124,147 +112,6 @@ def do_install(results, paths, disks):
log.close() log.close()
def _installed_args(paths, disks):
env, args = base_args(str(paths.ovmf_vars))
for disk in disks:
args += ["-drive", f"file={disk},if=virtio,format=qcow2"]
args += ["-boot", "order=c"]
return env, args
def _unlock_and_login(child, results, tag):
child.expect([r"[Pp]assphrase", r"login:"], timeout=300)
if "assphrase" in (child.after or ""):
override = os.environ.get("BOOT_PASSPHRASE")
candidates = [override] if override else [USER_PW, LUKS_PW]
child.sendline(candidates[0])
for candidate in candidates[1:]:
try:
child.expect(r"[Pp]assphrase", timeout=15)
child.sendline(candidate)
except (pexpect.TIMEOUT, pexpect.EOF):
break
logged_in = False
for _ in range(5):
child.expect(r"phoebus login:", timeout=180)
child.sendline(USER)
idx = child.expect([r"[Pp]assword:", r"phoebus login:", r"Login incorrect"],
timeout=30)
if idx == 0:
child.sendline(USER_PW)
if child.expect([r"[$#] $", r"Login incorrect", r"phoebus login:"],
timeout=60) == 0:
logged_in = True
break
results.assert_true(f"{tag}-login", logged_in, f"{tag}: could not log in")
def _fetch_sys(child):
child.sendline(
f"curl -fsSL {SYS_URL} -o /tmp/sys && chmod 755 /tmp/sys "
"&& test -x /tmp/sys && echo SYS-OK-$(printf READY)"
)
child.expect("SYS-OK-READY", timeout=120)
def _parse_marker(text, key):
import re
match = re.search(r"===" + re.escape(key) + r"(.+?)===", text)
if not match:
return None
out = {}
for token in match.group(1).split():
if "=" in token:
name, value = token.split("=", 1)
out[name] = value
return out
def do_rollback(results, paths, disks):
"""Snapshot -> reversible update -> sys undo -> detached verify."""
# Phase 1: known-good -> snapshot -> break -> undo, then power off.
env, args = _installed_args(paths, disks)
log = open(paths.serial_log, "w")
child = spawn(args, env, log)
phase1 = ""
try:
_unlock_and_login(child, results, "rollback-before")
_fetch_sys(child)
child.sendline(f"curl -fsSL {ROLLBACK_URL} -o /tmp/rb.sh && bash /tmp/rb.sh")
child.expect(
["===ROLLBACK-DONE===", "curl:", pexpect.TIMEOUT, pexpect.EOF],
timeout=int(os.environ.get("ROLLBACK_TIMEOUT", "7200")),
)
if "ROLLBACK-DONE" not in (child.after or ""):
results.fail("rollback-sequence", f"the guest rollback did not finish: {child.after!r}")
else:
results.pass_("rollback-sequence")
child.expect(["===POWEROFF===", pexpect.EOF, pexpect.TIMEOUT], timeout=600)
phase1 = paths.serial_log.read_text(errors="replace")
except pexpect.TIMEOUT as exc:
results.fail("rollback-before", f"timeout: {exc}")
except pexpect.EOF:
results.fail("rollback-before", "unexpected EOF")
finally:
child.close(force=True)
log.close()
before = _parse_marker(phase1, "ROLLBACK-KNOWN-GOOD")
undo = _parse_marker(phase1, "ROLLBACK-UNDO")
if before is None:
results.fail("rollback-known-good", "the guest did not record the known-good state")
if undo is None or undo.get("rc") != "0":
results.fail("rollback-undo", f"sys undo did not succeed: {undo}")
# Phase 2: boot the disk detached and verify the restored generation.
env, args = _installed_args(paths, disks)
log = open(paths.serial_log, "w")
child = spawn(args, env, log)
phase2 = ""
try:
_unlock_and_login(child, results, "rollback-after")
_fetch_sys(child)
child.sendline(f"curl -fsSL {ROLLBACK_VERIFY_URL} -o /tmp/rbv.sh && bash /tmp/rbv.sh")
child.expect("===AFTER-DONE===",
timeout=int(os.environ.get("ROLLBACK_VERIFY_TIMEOUT", "900")))
phase2 = paths.serial_log.read_text(errors="replace")
results.assert_true("rollback-systemd-running", "running" in phase2,
"systemd did not report running after rollback")
after = _parse_marker(phase2, "AFTER-KNOWN-GOOD")
if before is None or after is None:
results.fail("rollback-state", "could not read the before/after state")
else:
results.assert_true(
"rollback-package-state-restored",
before.get("pkgs") == after.get("pkgs"),
f"package db changed across rollback: before={before.get('pkgs')} after={after.get('pkgs')}",
)
results.assert_true(
"rollback-home-survives",
before.get("home") == after.get("home"),
f"/home did not survive: before={before.get('home')} after={after.get('home')}",
)
results.assert_true("rollback-modules-present", "===AFTER-MODULES ok===" in phase2,
"no kernel modules for the running kernel")
results.assert_true(
"rollback-recovery-entry",
"systemd.unit=rescue.target" in phase2 and "@snapshots/" in phase2,
"the snapshot recovery entry is missing or not snapshot-based",
)
status = phase2.split("===AFTER-STATUS===", 1)
status_text = status[1].split("===AFTER-DONE===", 1)[0].strip() if len(status) > 1 else ""
results.assert_true("rollback-status-recorded", bool(status_text),
"sys rollback status produced no evidence")
except pexpect.TIMEOUT as exc:
results.fail("rollback-after", f"timeout: {exc}")
except pexpect.EOF:
results.fail("rollback-after", "unexpected EOF")
finally:
child.close(force=True)
log.close()
def do_boot(results, paths, disks): def do_boot(results, paths, disks):
env, args = base_args(str(paths.ovmf_vars)) env, args = base_args(str(paths.ovmf_vars))
for disk in disks: for disk in disks:
@ -315,7 +162,7 @@ def do_boot(results, paths, disks):
def main() -> int: def main() -> int:
mode = sys.argv[1] if len(sys.argv) > 1 else "" mode = sys.argv[1] if len(sys.argv) > 1 else ""
if mode not in ("install", "boot", "rollback"): if mode not in ("install", "boot"):
print(__doc__) print(__doc__)
return 2 return 2
results = Results(f"serial-{mode}") results = Results(f"serial-{mode}")
@ -334,8 +181,6 @@ def main() -> int:
try: try:
if mode == "install": if mode == "install":
do_install(results, paths, disks) do_install(results, paths, disks)
elif mode == "rollback":
do_rollback(results, paths, disks)
else: else:
do_boot(results, paths, disks) do_boot(results, paths, disks)
finally: finally:

View file

@ -223,31 +223,5 @@ class QmpClientTests(unittest.TestCase):
self.assertTrue(any(cmd.startswith("screendump") for cmd in server.commands)) self.assertTrue(any(cmd.startswith("screendump") for cmd in server.commands))
class HarnessScriptsTest(unittest.TestCase):
"""Guest scripts must be valid shell before any VM is allowed to run them."""
VM_DIR = Path(__file__).resolve().parent
def test_guest_scripts_are_syntactically_valid(self):
scripts = sorted(self.VM_DIR.glob("*.sh"))
self.assertTrue(scripts, "no guest scripts found")
for script in scripts:
proc = subprocess.run(
["bash", "-n", str(script)], capture_output=True, text=True
)
self.assertEqual(
proc.returncode,
0,
f"bash -n failed for {script.name}: {proc.stderr}",
)
def test_rollback_fixtures_and_mode_are_present(self):
for name in ("rollback-guest.sh", "rollback-verify.sh"):
self.assertTrue((self.VM_DIR / name).is_file(), f"missing {name}")
driver = (self.VM_DIR / "serial-driver.py").read_text()
self.assertIn('"rollback"', driver)
self.assertIn("do_rollback", driver)
if __name__ == "__main__": if __name__ == "__main__":
unittest.main(verbosity=2) unittest.main(verbosity=2)