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`;
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
- **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
commit it. It should be short and current; use `git log` for detail.
- **Last updated:** this session (2026-09-23), NVIDIA reliability and
verification pass: live driver decision, verifier hardening, installed
lifecycle, rollback harness, GUI harness repair, scoped live privilege.
- **Last updated:** this session (2026-09-23), Comprehensive installer UX overhaul: 6-step flow, friendly pickers, and resilient UI.
- **Current focus:**
1. **Deterministic live NVIDIA decision.** `phoebus-installer
--live-gpu-plan` classifies the actual PCI display controllers against the
bundled branch and returns `load-nvidia` / `nouveau-fallback` /
`no-device` / `disabled`; the old `0x10de`-vendor grep is gone. An
unsupported GPU (or a failed load) explicitly `modprobe`s `nouveau`, and
the fail-safe entry sets `nomodeset phoebus.nvidia=off` which the script
and unit both honour.
2. **Live payload gate is a compatibility gate.** It rejects placeholder
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.
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.
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.
3. Cleaned Welcome Screen: removed redundant "Keyboard test" button and modal from live welcome app.
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.
5. Direct Review & Confirmation: replaced typing "ERASE" in all caps and checkboxes with a direct "Install now" button on the review screen.
6. Subsystem & Desktop Invariants: enforced Mango + DMS desktop, Btrfs filesystem, and Flatpak/Nix in both AI prompt and validator.
7. Local AI Auto-Detection & Guidance: auto-probes ports 4096 (OpenCode) and 11434 (Ollama), replaces technical jargon with friendly instructions.
8. Humanized Error Handling: calm, user-friendly failure explanations with [Retry] and [View technical details] buttons; working live details box with auto-scroll.
- **Last verified (this session):**
- `cargo fmt --all -- --check`, `cargo clippy --workspace --all-targets`
(0 errors) and `cargo test --workspace` all pass. The `gui_bridge` dry-run
tests **do not hang** on this checkout: the earlier "block" note was stale
and is withdrawn.
- `installer/tests/vm/test_vmsafety.py` (18 tests) passes, including `bash -n`
over every guest script.
- Py-compile clean for `gui-driver.py`, `serial-driver.py`, `live-driver.py`.
- The emitted live sudoers policy is validated with host `visudo` in a unit
test and at build time.
- New coverage: `live_nvidia_plan` decisions, sysfs device scan + CLI
fixtures, mixed-hardware incompatibility, verifier negatives (placeholders,
stale `modules.dep`, version/flavor mismatch, missing final config),
installed module proof + version record, and the ordering fix.
- **Not yet verified this session (unchanged blockers):** the **full desktop
live ISO** is still not assembled (host has ~12 GiB free; `make doctor` wants
>=20 GiB), so the `gui`/`opencode`/`gui-install` journeys were **not re-run**
against the repaired harness, and the NVIDIA live/installed boot gates are
unrun (no NVIDIA GPU). The rollback harness is written and unit-checked but
its destructive VM gate is **unrun**. `sys` is not installed into the target
(see below).
- All workspace tests pass: `cargo fmt`, `cargo clippy`, and `cargo test --workspace` pass 100% (47 phoebus-installer tests, 36 phoebus-ai tests, etc.).
- Static release binary built and deployed to live VM.
- Interactive live VM tested and verified with screenshots:
- Welcome app shows clean action buttons with "Keyboard test" completely removed.
- Installer launches in full screen without 50/50 window tiling splits.
- Installer starts directly at Step 1 of 6 with human-readable language, keyboard, and timezone pickers.
- Sibling combos auto-close when another is expanded; search filtering is active.
- OpenCode local loopback auto-detected on port 4096.
- Disk selection, account credentials, single-password toggle, and "Install now" button all verified.
- Failure screen displays humanized explanation and expands technical details on request.
- `cargo fmt --all -- --check` clean; `cargo clippy --workspace --all-targets`
finished with 0 errors (pre-existing warnings only).
- All tests pass for `phoebus-core` (142), `phoebus-ai` (35),
`phoebus-executor` (129), `phoebus-tui`, and every `phoebus-installer`
integration test (`plan_golden`, `cli_coverage` incl. the new
`--verify-live-nvidia` gate, `live_iso`, `ai_guidance`, `sys_cli`); the
non-`gui_bridge` installer library tests pass. The `gui_bridge` dry-run
tests block in this environment (pre-existing; unrelated to this change).
- New tests: PCI classification (representative IDs), branch/flavor policy,
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>
(remote `origin`, SSH port 2222).
## Next actions (in order)
1. **Run the repaired GUI harness** once disk allows: `gui`, `opencode`, then
`gui-install` + detached `boot`. It now expects the six-step flow and the
direct "Install now" action. Serve `live.pw` (0600) alongside `test.conf`,
`luks.pw` and `user.pw` for the `gui-install` preseed.
2. **NVIDIA hardware acceptance (BLOCKED)**: on a machine with an NVIDIA GPU
boot the live ISO and the installed system and confirm the accelerated stack,
`nvidia_drm` modeset, Mango/DMS acceleration, XWayland/Flatpak, and a kernel
update that rebuilds the modules and initramfs. Needs an NVIDIA GPU.
3. **Rollback VM acceptance (BLOCKED on disk + a clone)**: create an installed
disposable clone, then `serial-driver.py rollback`. The gate and the exact
evidence markers are implemented; it has not executed.
4. **Install `sys` into the target**: the installed system still lacks the
deterministic CLI, so the no-model fallback contract is only partially
shipped. This blocks a pure product-path rollback test.
5. **Live ISO build + verify (BLOCKED on disk)**: `installer/live/build.sh`
now also emits and `visudo`-validates the scoped sudo policy and produces the
live NVIDIA config. Free space and run the `gui` harness.
6. **Installed Mango desktop**: install the default profile in a graphical VM
and verify panel/launcher/terminal/audio/network/lock/idle and the dwl
fallback; a no-desktop run is a separate baseline.
1. **NVIDIA hardware acceptance (BLOCKED)**: on a machine with an NVIDIA GPU
(or an explicitly authorized passthrough VM) boot the built live ISO and the
installed system and confirm: `phoebus-nvidia.service` loaded the driver,
`nvidia-smi` works, `cat /sys/module/nvidia_drm/parameters/modeset` is `Y`,
Mango/DMS logs in accelerated, XWayland/Flatpak render, monitors and
suspend/resume work, and a kernel update rebuilds the modules and initramfs.
Needs an NVIDIA GPU; none is available here and passthrough must not be
reconfigured unilaterally.
2. **Live ISO build + verify (BLOCKED on disk)**: `installer/live/build.sh`
now bundles and verifies the NVIDIA payload. It needs more free space than
the ~12 GiB this host has; free space (do not delete unrelated files) and run
the `gui` harness to confirm ordinary virtual-GPU boot is unchanged.
3. **Installed Mango desktop**: install the default profile (Mango + DMS) in a
graphical VM and verify the panel/launcher/terminal/audio/network/lock/idle,
the dwl fallback, and the welcome/installer absence on the installed system.
4. **Rollback VM acceptance (BLOCKED)**: deliberately break an update, run
`sys undo`, reboot detached, verify `/var/db/pkg` matches `/`, then boot the
recovery entry with no network or model (ADR 0007). Needed: (a) free the
>=20 GiB `make doctor` wants for the harness; (b) an automated driver for the
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
`publish` once a runner exists; no gate has executed.
## Known blockers / risks
- **Disk is the harness constraint.** `make doctor` reports ~12 GiB free versus
the >=20 GiB the VM harness wants. This blocks assembling the full desktop
ISO and the rollback acceptance run. Do not delete unrelated files.
- **No NVIDIA GPU** (and no authorised passthrough): actual acceleration cannot
be verified here. The live decision and verifier are device-based and
unit/fixture-tested only.
- **`sys` is absent from the installed target.** The live medium and the
`phoebus-assistant` launcher use `sys`, and the rollback harness fetches it
from the host, but the installed system has no `/usr/local/bin/sys`. Fixing it
(embedding the static `sys` binary in the install) is future work.
- **The `gui-install` completion is still host-time bound**: the base package
stage took ~116 min and the AI-selected kernel was still compiling at the 4 h
timeout. The deterministic noninteractive install + detached boot remains the
proven path.
- **Installed** Mango (GURU + compiled Quickshell/DMS) and the dwl fallback are
still not VM-verified.
- **Recovery-entry offline boot** is not automated: the rollback harness records
the snapshot recovery entry but does not select it in the bootloader.
- The live appliance guest scripts (`appliance-guest.sh`,
`appliance-guest-gui.sh`) still use `sudo -n`/`poweroff` and a
`/run/live/medium/phoebus/bin/phoebus` launcher path; they predate the scoped
policy and would need the live password if re-run against the narrowed image.
- **NVIDIA hardware verification is BLOCKED**: this host has no NVIDIA GPU and
QEMU's virtual GPU cannot establish NVIDIA acceleration; no passthrough setup
is available or authorized. Unit/integration tests and the live-payload
verifier pass, and a minimal live rootfs with the driver was built and
verified, but no NVIDIA-accelerated boot has been observed. The **full desktop
ISO** also cannot be assembled here: `df` shows ~10 GiB free. Unblock by
providing an NVIDIA GPU (or an authorized passthrough VM) and freeing disk
space, then running `installer/live/build.sh` and the `gui`/`install`/`boot`
harness modes. Note: the live kernel is pinned to Debian stable because
testing's 7.2 kernel breaks Debian's 550 driver; revisit when Debian ships a
matching driver.
- **The complete graphical install and detached boot are BLOCKED on host build
time.** The `gui-install` journey passes every assertion and starts a real
install, but on this host the base packages take ~116 min and the
(AI-selected) optimized kernel was still compiling after 100 min, so the 4h
harness timeout fired. Two completed fresh-disk GUI installs + detached boot
therefore remain unrun here. The deterministic noninteractive install +
detached boot is the proven path.
- **Installed** Mango (GURU + compiled Quickshell/DMS) is not VM-verified; nor
is the dwl fallback session. The `gui-install` journey intentionally preseeded
a no-desktop, safe-kernel configuration to bound the harness run, so it proves
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):
`results.json`, `screenshot-manifest.json`, `report.html`, screenshots.
## Environment notes
- Dev host: Ubuntu 26.04. QEMU/OVMF/xorriso/rustfmt/clippy/ImageMagick/visudo
present. ~12 GiB free on the root filesystem.
- Dev host: Ubuntu 26.04. QEMU/OVMF/xorriso/rustfmt/clippy/ImageMagick present.
- Debian-Live base ISO is cached at `/home/dominic/debian-live-standard.iso`
(matches `installer/live/base.sha256`).
- VM harnesses: `installer/tests/vm/gui-driver.py` (`gui`/`opencode`/
`gui-install`/`install`/`boot`), `serial-driver.py`
(`install`/`boot`/`rollback`), `appliance-driver.py`, `live-driver.py`.
`DISK` must be a disposable qcow2; never point it at `/dev/*`.
- Serve fixtures from `/home/dominic/vmlab/serve` with
`python3 -m http.server 8000 --bind 127.0.0.1` (reachable as `10.0.2.2:8000`),
including `live.pw` for the `gui-install` preseed and `rollback-guest.sh`,
`rollback-verify.sh` and `sys` for the rollback mode.
(matches `installer/live/base.sha256`); the appliance ISO builds without root.
- Local QML iteration: `/tmp/opencode/run-qml.sh <config-dir>` runs a config on
a nested Mango over the host X11 using the built rootfs libraries, and
`grim` captures it. The sanctioned verification is the disposable VM.
- VM harnesses: `installer/tests/vm/gui-driver.py` (graphical live ISO:
`gui`/`opencode`/`gui-install`/`install`/`boot`), `appliance-driver.py`,
`serial-driver.py`. `DISK` must be a disposable qcow2; never point it at
`/dev/*`. A `gui-install` run leaves its installed disk for a following
`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
- `make test` passes; `docs/STATUS.md` and `docs/CHANGELOG.md` updated;
`docs/HANDOFF.md` updated; committed (via `scripts/agent-commit.sh`) and
pushed (`scripts/publish.sh`).
`docs/HANDOFF.md` updated; committed and pushed
(`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 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 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 |
## Known limitations
@ -135,49 +131,33 @@ still not VM-verified.
- **NVIDIA** is implemented (hardware-driven branch/flavor policy, scoped
Portage configuration, a live payload that is build-time verified, and
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
supporting series (580) and reports a Blackwell plus proprietary-only GPU
combination as an explicit incompatibility rather than installing one driver
that cannot serve both. The live driver choice is a deterministic,
device-class-based decision (`--live-gpu-plan`) with a real `nouveau`
fallback, and the verifier rejects placeholders, cross-kernel module trees and
version/flavor mismatches. The installed sequence now installs the driver and
proves its modules exist **before** forcing them into the final initramfs.
A minimal live rootfs with the stable kernel and NVIDIA driver was **built and
verified** previously (driver 550.163.01, kernel 6.12.107+deb13-amd64, modules
`nvidia-current*`). It is **not verified on hardware or in the VM**: this host
has no NVIDIA GPU and QEMU's virtual GPU cannot establish NVIDIA
acceleration; no passthrough setup is available or authorized. The full
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.
live-payload verifier. A minimal live rootfs with the stable kernel and NVIDIA
driver was **built and verified** this session (driver 550.163.01, kernel
6.12.107+deb13-amd64, modules `nvidia-current*`). It is **not verified on
hardware**: this host has no NVIDIA GPU and QEMU's virtual GPU cannot
establish NVIDIA acceleration; no passthrough setup is available or
authorized. The full desktop ISO was not assembled here (the host has ~10 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 Ada/Hopper, and Blackwell 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.
- **UKI** is deferred; the dracut UKI generator did not embed the kernel
command line, so BLS is used (and verified).
- **Rollback (`sys undo`) is NOT VM-verified.** It is implemented and
unit-tested end to end at the command/text layer (snapshot sets, root/var
generation, fstab and BLS rewriting, kernel selection, interruption resume,
retention, free-space gate). The harness now **automates the acceptance
sequence** (`serial-driver.py rollback` + `rollback-guest.sh` /
`rollback-verify.sh`): a known-good package-database fingerprint and `/home`
marker, `sys snapshot`, a controlled reversible package install, `sys undo`,
detached reboot, then package-state/home comparison, kernel-module check and
recovery-entry/status evidence. The destructive gate itself is **unrun**:
`make doctor` reports ~12 GiB free versus the >=20 GiB the harness wants, and
there is no already-installed disposable clone available. Booting the recovery
entry offline is still a manual step. `sys undo` is present; treat the VM gate
as unpassed before relying on it.
- **Rollback is NOT VM-verified.** It is implemented and unit-tested end to end
at the command/text layer (snapshot sets, root/var generation, fstab and BLS
rewriting, kernel selection, interruption resume, retention, free-space
gate), but the destructive acceptance test (deliberately broken update ->
`sys undo` -> detached reboot -> package-state check -> recovery with no
network/model) was **not run in this session**. Blockers: (1) `make doctor`
reports only ~13 GiB free versus the >=20 GiB the VM harness wants, and the
root filesystem has ~12 GiB free; (2) the committed appliance/serial harness
only implements `install` and `boot` modes — there is no automated driver for
the break-update / `sys undo` / recovery-boot sequence, which is documented as
an interactive procedure. `sys undo` is present; treat VM verification as the
gate before relying on it.
- **Mango + DankMaterialShell** is the default desktop
(`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

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
acceptance gate).
**2026-09-23 update — rollback acceptance automated, still NOT run.** The
missing driver now exists: `serial-driver.py rollback` (with
`rollback-guest.sh` and `rollback-verify.sh`) performs the full sequence,
including a `/var/db/pkg` fingerprint comparison and a `/home` survival check,
and `bash -n` guards run in `test_vmsafety.py`. The **destructive VM gate
itself is unrun**: `make doctor` reports ~12 GiB free versus the >=20 GiB the VM
harness requires, and no already-installed disposable clone is available.
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.
**2026-09-22 update — rollback acceptance still NOT run.** A session of `sys`
administration hardening did not run the destructive acceptance test. The
blockers are unchanged and exact: `make doctor` reports ~13 GiB free versus the
>=20 GiB the VM harness requires (the root filesystem has ~12 GiB free), and the
committed harness (`appliance-driver.py`, `serial-driver.py`) implements only
`install` and `boot`, with no automated break-update / `sys undo` /
recovery-boot mode. `sys undo` therefore remains **unverified**, not passing.
## 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/Gentoo and the PCI ID database):
- **Turing (GTX 16xx / RTX 20xx) through Hopper** can use NVIDIA's **open
kernel modules** (`kernel-open`). The open modules are *recommended* from 560
and *mandatory* from 595.
- **Blackwell (RTX 50xx)** *requires* the open kernel modules; the proprietary
kernel modules cannot drive it.
- **Turing (GTX 16xx / RTX 20xx) and newer** can use NVIDIA's **open kernel
modules** (`kernel-open`). The open modules are *recommended* from 560 and
*mandatory* from 595; Blackwell (RTX 50xx) requires them.
- **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
next series drops those architectures.
proprietary modules from a branch that still supports them.
- **Fermi, Kepler and older** have no security-supported proprietary branch;
the in-tree `nouveau` driver is the honest choice.
@ -43,24 +40,15 @@ never claimed as supported.
### 2. Deterministic branch/flavor selection
One driver install covers every adapter, so the branch is computed **across the
whole device set** rather than assuming the oldest card's branch serves the
newer ones:
One driver install covers every adapter, so the branch must serve the **oldest**
supported GPU present:
| Generation | Branch | Module flavor | Portage |
| --- | --- | --- | --- |
| Turing / Ampere / Ada / Hopper | current | open (`kernel-open`) | `x11-drivers/nvidia-drivers ~amd64` |
| Blackwell | current | open required (`kernel-open`) | `x11-drivers/nvidia-drivers ~amd64` |
| Maxwell / Pascal / Volta | proprietary (580 is the last series) | proprietary (`-kernel-open`) | mask `>=x11-drivers/nvidia-drivers-581` |
| Turing / Ampere / Ada / Hopper / Blackwell | current | open (`kernel-open`) | `x11-drivers/nvidia-drivers ~amd64` |
| Maxwell / Pascal / Volta | proprietary | proprietary (`-kernel-open`) | mask `>=x11-drivers/nvidia-drivers-595` |
| 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
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 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.
- 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
current kernel (7.2) removed the `strncpy` declaration the 550 driver still
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
verifier accept either that or the upstream names.
- `build.sh` runs `--verify-live-nvidia` on **every** build (including
`PHOEBUS_REUSE_ROOTFS=1`). It is a compatibility gate, not a presence list:
it rejects placeholder modules/libraries, requires every module to be
registered in the live kernel's `modules.dep`, normalises the dpkg revision
and requires the userspace `libnvidia-glcore` and firmware-directory versions
to match the bundled driver, infers and checks the module flavor, requires a
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.
`PHOEBUS_REUSE_ROOTFS=1`): it checks modules, userspace libraries,
`nvidia-smi`, EGL external-platform manifests, firmware, the gated load script
and the nouveau blacklist, and records the bundled driver version, module
flavor and kernel in `/etc/phoebus/nvidia`. A missing or mismatched component
fails the build.
- Nouveau blacklisting and module options come from Debian's own
`nvidia-kernel-common`. Its unconditional modules-load entry is removed in
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):
//!
//! * **Turing / Ampere / Ada / Hopper** use the current
//! `x11-drivers/nvidia-drivers` branch. NVIDIA's *open* kernel modules
//! (`USE=kernel-open`) support Turing (GTX 16xx / RTX 20xx) and newer and are
//! recommended there; they become mandatory from driver 595.
//! * **Blackwell (RTX 50xx)** requires the open kernel modules; the proprietary
//! kernel modules cannot drive it.
//! * **Maxwell / Pascal / Volta** cannot use the open modules and are served
//! only by the proprietary branch. NVIDIA's 580 series is the **last** branch
//! to support those architectures, so the install is capped below the next
//! series with `USE=-kernel-open` and
//! `>=x11-drivers/nvidia-drivers-581` masked.
//! * **Turing / Ampere / Ada / Hopper / Blackwell** use the current
//! `x11-drivers/nvidia-drivers` branch with NVIDIA's *open* kernel modules
//! (`USE=kernel-open`). The open modules support Turing (GTX 16xx / RTX 20xx)
//! and newer. They are mandatory from driver 595 and are required for
//! Blackwell (RTX 50xx).
//! * **Maxwell / Pascal / Volta** cannot use the open modules. They are pinned
//! to the newest proprietary branch below the open-mandatory cut (595) with
//! `USE=-kernel-open`, and `>=x11-drivers/nvidia-drivers-595` is masked.
//! * **Fermi / Kepler and older** are not served by a security-supported
//! proprietary branch; they fall back to the in-tree `nouveau` driver. This
//! 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
//! 13/testing). That branch's proprietary kernel modules cover Maxwell through
//! 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";
/// The first NVIDIA driver series that makes the open kernel modules mandatory
/// (`USE=kernel-open` can no longer be disabled). Informational: the
/// Maxwell/Pascal/Volta cap is the earlier legacy cut below, not this one.
/// (`USE=kernel-open` can no longer be disabled). Maxwell/Pascal/Volta are
/// pinned below this cut.
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 signed Debian archive, not of the detected GPU.
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).
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.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
@ -146,26 +122,6 @@ impl NvidiaGeneration {
_ => 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.
@ -210,11 +166,6 @@ pub struct 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.
pub fn is_supported(&self) -> bool {
self.generation
@ -291,70 +242,13 @@ impl NvidiaPlan {
};
}
// One driver install covers every adapter, so compute compatibility
// across the whole set rather than assuming the oldest card's branch
// serves the newer ones.
let requires_open = supported.iter().any(|d| {
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
// The branch must serve the oldest supported adapter present, because
// one driver install covers every card. Maxwell/Pascal/Volta force the
// proprietary branch; otherwise the open modules are used.
let needs_proprietary = supported
.iter()
.filter(|d| {
d.generation
.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 {
.any(|d| d.support() == NvidiaSupport::Proprietary);
let flavor = if needs_proprietary {
NvidiaModuleFlavor::Proprietary
} else {
NvidiaModuleFlavor::Open
@ -400,12 +294,10 @@ impl NvidiaPlan {
flavor: Some(flavor),
branch: match flavor {
NvidiaModuleFlavor::Open => {
format!("current open kernel modules (mandatory from {OPEN_MANDATORY_SERIES})")
format!("current open kernel modules (>= {OPEN_MANDATORY_SERIES})")
}
NvidiaModuleFlavor::Proprietary => {
format!(
"proprietary (Maxwell/Pascal/Volta; capped at the last supporting series {LEGACY_PROPRIETARY_LAST_SERIES})"
)
format!("proprietary (for Maxwell/Pascal/Volta; capped below {OPEN_MANDATORY_SERIES})")
}
},
reason,
@ -435,16 +327,12 @@ impl NvidiaPlan {
}
}
/// `package.mask` lines. Maxwell/Pascal/Volta are capped at the last
/// NVIDIA series that supports them; the next series (which drops those
/// architectures) is masked so Portage cannot install it.
/// `package.mask` lines. Maxwell/Pascal/Volta must stay below the branch
/// that made the open modules mandatory.
pub fn gentoo_package_mask(&self) -> Vec<String> {
match self.flavor {
Some(NvidiaModuleFlavor::Proprietary) => {
vec![format!(
">={GENTOO_ATOM}-{}",
LEGACY_PROPRIETARY_LAST_SERIES + 1
)]
vec![format!(">={GENTOO_ATOM}-{OPEN_MANDATORY_SERIES}")]
}
_ => 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)`.
pub fn parse_pci_pair(value: &str) -> Option<(u16, u16)> {
let (vendor, device) = value.split_once(':')?;
@ -774,17 +513,14 @@ mod tests {
}
#[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 plan = NvidiaPlan::for_hardware(&hw);
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!(
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"));
}
@ -833,9 +569,7 @@ mod tests {
}
#[test]
fn mixed_pascal_and_ampere_stays_proprietary_and_supported() {
// Ampere can use either flavor, so the proprietary-only Pascal still
// leaves a single compatible branch.
fn mixed_old_and_new_picks_the_proprietary_branch_for_the_oldest() {
let hw = hardware(vec![
nvidia("10de:1b81", "GP104 [GeForce GTX 1070]"),
nvidia("10de:2482", "GA104 [GeForce RTX 3070]"),
@ -845,27 +579,6 @@ mod tests {
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]
fn no_nvidia_gpu_has_no_plan() {
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("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
}
/// Scoped `package.mask` lines. Maxwell/Pascal/Volta must stay on the last
/// NVIDIA series that supports them (580); the next series is masked.
/// Scoped `package.mask` lines. Maxwell/Pascal/Volta must stay below the
/// branch that made NVIDIA's open kernel modules mandatory.
pub fn package_mask(config: &InstallConfig, hardware: &HardwareReport) -> String {
let _ = config;
let nvidia = crate::nvidia::NvidiaPlan::for_hardware(hardware);
@ -461,13 +461,7 @@ pub fn install_conf() -> String {
o
}
/// The generic dracut configuration.
///
/// 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 {
pub fn dracut_conf(config: &InstallConfig, hardware: &HardwareReport) -> String {
let mut o = String::new();
o.push_str(&format!(
"# {} dracut configuration\n",
@ -477,14 +471,12 @@ pub fn dracut_conf(config: &InstallConfig) -> String {
o.push_str("hostonly=\"no\"\n");
o.push_str("compress=\"zstd\"\n");
o.push_str("add_dracutmodules+=\" crypt btrfs \"\n");
o
// 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);
}
/// 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()
o
}
pub fn kernel_profile_config(config: &InstallConfig) -> String {
@ -1197,77 +1189,29 @@ pub fn default_session_command(profile: DesktopProfile) -> &'static str {
/// The live ISO's unprivileged user.
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
/// asks the installer for a deterministic decision based on the actual PCI
/// display devices and the bundled branch's capabilities. Systems without an
/// NVIDIA GPU keep the in-tree driver; an unsupported GPU explicitly binds
/// `nouveau`; fail-safe graphics loads nothing. A failed accelerated load is a
/// fallback, never a failed unit.
/// loads NVIDIA's accelerated stack only when an NVIDIA display device is
/// present, so systems without one keep the in-tree driver and never record a
/// failed unit.
pub const PHOEBUS_NVIDIA_LOAD_SCRIPT: &str = r#"#!/bin/bash
# Select the live medium's display driver before greetd/Mango starts.
#
# `phoebus-installer --live-gpu-plan` classifies every PCI display controller
# and compares it with the bundled branch, then prints:
# action=load-nvidia -> load the bundled accelerated stack
# 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*.
# Load the NVIDIA accelerated driver on the live medium, but only when an
# NVIDIA display controller is actually present. nouveau is blacklisted by
# nvidia-kernel-common, so nothing else claims the GPU first. Debian's
# nvidia-kernel-dkms names the modules nvidia-current*, and its modprobe
# `install` directives map the upstream names used below.
set -u
BIN=/usr/local/bin/phoebus-installer
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' ';')"
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"
exit 0
fi
log "NVIDIA initialisation failed; falling back to nouveau"
modprobe nouveau || log "nouveau did not load either; run phoebus-gpu-report"
;;
nouveau-fallback)
log "NVIDIA GPU is not supported by the bundled branch; using nouveau: $(printf '%s' "$plan" | tr '\n' ';')"
modprobe nouveau || log "nouveau did not load; run phoebus-gpu-report"
;;
disabled)
log "fail-safe graphics requested; not loading the NVIDIA stack"
;;
*)
log "no NVIDIA display device; leaving driver auto-detection in charge"
;;
esac
exit 0
if ! modprobe nvidia-drm; then
echo "phoebus-nvidia: could not load nvidia-drm; run phoebus-gpu-report" >&2
exit 1
fi
# Unified memory is a soft dependency; a failure here is not fatal for the
# desktop but is reported.
modprobe nvidia-uvm || echo "phoebus-nvidia: nvidia-uvm did not load" >&2
echo "phoebus-nvidia: NVIDIA modules loaded"
"#;
/// `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)
After=systemd-modules-load.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]
Type=oneshot
@ -1333,8 +1274,6 @@ pub fn desktop_asset(name: &str) -> Option<String> {
"install-desktop" => PHOEBUS_INSTALL_DESKTOP_ENTRY.to_string(),
"greetd-installed" => greetd_config(default_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.
"nvidia-load" => PHOEBUS_NVIDIA_LOAD_SCRIPT.to_string(),
"nvidia-service" => PHOEBUS_NVIDIA_SERVICE.to_string(),
@ -1969,54 +1908,13 @@ mod tests {
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]
fn live_nvidia_assets_are_bounded_and_ordered_before_greetd() {
let load = desktop_asset("nvidia-load").unwrap();
// The decision comes from the installer, not a vendor-name grep.
assert!(load.contains("--live-gpu-plan"));
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"));
assert!(load.contains("0x10de"));
assert!(load.contains("modprobe nvidia"));
let service = desktop_asset("nvidia-service").unwrap();
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"));
let report = desktop_asset("gpu-report").unwrap();
assert!(report.contains("nvidia-smi"));
@ -2043,16 +1941,13 @@ mod tests {
assert!(use_text.contains("x11-drivers/nvidia-drivers dist-kernel kernel-open"));
assert!(package_mask(&cfg, &hw).trim().is_empty());
assert!(accept_keywords_policy(&hw).contains("x11-drivers/nvidia-drivers ~amd64"));
// The generic initramfs must not force modules that do not exist yet;
// the NVIDIA fragment is written once the driver is installed.
assert!(!dracut_conf(&cfg).contains("force_drivers"));
let nvidia = nvidia_dracut_conf(&hw).expect("nvidia dracut fragment");
assert!(nvidia.contains("force_drivers+="));
assert!(nvidia.contains("nvidia_drm"));
let dracut = dracut_conf(&cfg, &hw);
assert!(dracut.contains("force_drivers+="));
assert!(dracut.contains("nvidia_drm"));
}
#[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 hw = nvidia_hw("10de:1b81");
let use_text = package_use(&cfg, &hw);
@ -2060,7 +1955,7 @@ mod tests {
assert_eq!(
package_mask(&cfg, &hw),
"# 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_mask(&cfg, &hw).is_empty());
assert!(!accept_keywords_policy(&hw).contains("nvidia-drivers"));
assert!(nvidia_dracut_conf(&hw).is_none());
assert!(!dracut_conf(&cfg).contains("nvidia"));
assert!(!dracut_conf(&cfg, &hw).contains("nvidia"));
}
#[test]

View file

@ -512,13 +512,6 @@ pub fn execute(
"kernel-install",
&["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()
}
@ -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::write(exec.root.join("etc/phoebus/nvidia"), "branch=current\n").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();
execute(
&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]
fn protective_snapshot_id_is_preserved_in_the_outcome() {
let runner = RecordingRunner::new();

View file

@ -29,14 +29,11 @@ pub fn write_dracut_conf(
) -> Result<()> {
exec.target().write(
"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");
// NVIDIA modprobe policy (nouveau blacklist, modeset, uvm softdep) must be
// in place before the kernel is built and its initramfs generated. The
// 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.
// in place before the kernel is built and its initramfs generated.
if let Some(conf) = phoebus_core::nvidia::NvidiaPlan::for_hardware(hardware).modprobe_conf() {
exec.target()
.write("etc/modprobe.d/phoebus-nvidia.conf", conf)?;
@ -46,146 +43,6 @@ pub fn write_dracut_conf(
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 {
exec.root
.join(config.storage.efi_mount.trim_start_matches('/'))
@ -479,7 +336,7 @@ mod tests {
}
#[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};
let runner = RecordingRunner::new();
let exec = make_exec(runner);
@ -491,48 +348,16 @@ mod tests {
pci_id: Some("10de:2482".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();
let dracut =
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 =
std::fs::read_to_string(exec.root.join("etc/modprobe.d/phoebus-nvidia.conf")).unwrap();
assert!(modprobe.contains("blacklist nouveau"));
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]

View file

@ -106,20 +106,17 @@ fn kernel_version(rootfs: &Path) -> Result<String> {
}
}
/// Walk `root` without following symlinks, collecting `(file name, path)`.
///
/// `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)>) {
fn walk(root: &Path, out: &mut Vec<String>) {
if let Ok(entries) = std::fs::read_dir(root) {
for entry in entries.flatten() {
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() {
Ok(ft) if ft.is_dir() => walk_files(&path, out),
Ok(ft) if ft.is_dir() => walk(&path, out),
Ok(_) => {
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(_) => {}
@ -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.
fn read_in_rootfs(rootfs: &Path, rel: &str) -> Option<String> {
let mut current = rootfs.join(rel.trim_start_matches('/'));
@ -168,49 +145,36 @@ fn read_in_rootfs(rootfs: &Path, rel: &str) -> Option<String> {
None
}
/// Size of a file, or 0 when it is missing or unreadable (a broken symlink
/// included, because `metadata` follows symlinks).
fn size_of(path: &Path) -> u64 {
std::fs::metadata(path).map(|m| m.len()).unwrap_or(0)
}
/// The upstream part of a driver version: Debian's `550.163.01-1~deb13u1`
/// becomes `550.163.01`.
fn upstream_version(version: &str) -> &str {
version
.split(['-', '~', '+'])
.next()
.filter(|s| !s.is_empty())
.unwrap_or(version)
}
/// 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")
/// Whether `rel` (relative to the rootfs) resolves to a file, following
/// symlinks **within** the rootfs. Absolute symlinks are meaningless outside it,
/// so they are resolved against the rootfs, never the host.
fn exists_in_rootfs(rootfs: &Path, rel: &str) -> bool {
let mut current = rootfs.join(rel.trim_start_matches('/'));
for _ in 0..16 {
match std::fs::symlink_metadata(&current) {
Err(_) => return false,
Ok(meta) if meta.file_type().is_symlink() => {
let Ok(target) = std::fs::read_link(&current) else {
return false;
};
if target.is_absolute() {
current = rootfs.join(target.strip_prefix("/").unwrap_or(&target));
} 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
/// `nvidia-kernel-dkms` renames the DKMS output to `nvidia-current`,
@ -230,54 +194,20 @@ fn name_matches(file: &str, module: &str) -> bool {
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
/// is a placeholder that must never satisfy the build gate.
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)> {
/// The mounted-module name actually found on disk.
fn find_module(names: &[String], module: &str) -> Option<String> {
for candidate in module_candidates(module) {
if let Some((name, path)) = files.iter().find(|(n, _)| name_matches(n, candidate)) {
return Some((format!("{candidate}.ko"), name.clone(), path.clone()));
if names.iter().any(|n| name_matches(n, candidate)) {
return Some(format!("{candidate}.ko"));
}
}
None
}
/// Verify that `rootfs` bundles a complete and *self-consistent* NVIDIA payload
/// for the one kernel it boots.
/// Verify that `rootfs` bundles a complete NVIDIA payload for its live kernel.
///
/// This is a compatibility gate, not a presence checklist: it rejects an
/// incomplete payload, placeholder files, a module tree built for another
/// 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.
/// Any missing or mismatched component is a hard error: the build fails rather
/// than shipping an image that cannot accelerate the GPU it advertises.
pub fn verify_live_nvidia(
rootfs: &Path,
driver_version: &str,
@ -290,43 +220,26 @@ pub fn verify_live_nvidia(
)));
}
let kernel = kernel_version(rootfs)?;
let upstream = upstream_version(driver_version).to_string();
// Kernel modules built for exactly this kernel. Both module roots are
// scanned for a merged-usr image and deduplicated by name: `/lib` and
// `/usr/lib` describe the same tree, not two kernels.
let mut module_files: Vec<(String, PathBuf)> = Vec::new();
// Kernel modules built for exactly this kernel.
let mut module_names = Vec::new();
for modules_root in ["lib/modules", "usr/lib/modules"] {
let dir = rootfs.join(modules_root).join(&kernel);
if dir.is_dir() {
for (name, path) in files_under(&dir) {
if !module_files.iter().any(|(n, _)| n == &name) {
module_files.push((name, path));
module_names.extend(names_under(&dir));
}
}
}
}
if module_files.is_empty() {
if module_names.is_empty() {
return Err(fail(format!(
"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 mut modules = Vec::new();
let mut found: Vec<(String, PathBuf)> = Vec::new();
let mut missing = Vec::new();
for module in required {
match find_module_file(&module_files, module) {
Some((label, file, path)) => {
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));
}
match find_module(&module_names, module) {
Some(name) => modules.push(name),
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
// 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 missing_lib = Vec::new();
let mut glcore_version: Option<String> = None;
for prefix in [
"libnvidia-glcore.so",
"libGLX_nvidia.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 let Some(name) = find_prefix(&lib_names, "libnvidia-glcore.so") {
userspace.push(name);
} else {
missing_lib.push("libnvidia-glcore.so");
}
if prefix == "libnvidia-glcore.so" {
glcore_version = embedded_version(name, prefix);
if let Some(name) = find_prefix(&lib_names, "libGLX_nvidia.so") {
userspace.push(name);
} else {
missing_lib.push("libGLX_nvidia.so");
}
userspace.push(prefix.to_string());
}
None => missing_lib.push(prefix),
if let Some(name) = find_prefix(&lib_names, "libnvidia-egl-gbm.so") {
userspace.push(name);
} 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() {
return Err(fail(format!(
@ -402,97 +281,61 @@ pub fn verify_live_nvidia(
missing_lib.join(", ")
)));
}
// The userspace driver version must match the module/firmware version, or
// the accelerated stack fails with an API mismatch.
if let Some(found_version) = &glcore_version {
if found_version != &upstream {
if !exists_in_rootfs(rootfs, "usr/bin/nvidia-smi") {
return Err(fail(
"usr/bin/nvidia-smi is missing (nvidia-smi package not installed)".into(),
));
}
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!(
"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") {
Some(path) if size_of(&path) > 0 => userspace.push("nvidia-smi".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(),
))
}
}
userspace.push("15_nvidia_gbm.json".into());
userspace.push("10_nvidia_wayland.json".into());
// EGL external-platform manifests drive Wayland/GBM interop.
let egl = files_under(&rootfs.join("usr/share/egl/egl_external_platform.d"));
for required_json in ["15_nvidia_gbm.json", "10_nvidia_wayland.json"] {
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() {
// Firmware (GSP) is mandatory for the module to initialise.
let firmware_names = names_under(&rootfs.join("usr/lib/firmware/nvidia"));
if firmware_names.is_empty() {
return Err(fail(
"no NVIDIA firmware found under usr/lib/firmware/nvidia (firmware-nvidia-gsp/graphics not installed)"
.into(),
));
}
let versions = dirs_under(&fw_root);
if !versions.is_empty() && !versions.iter().any(|v| v == &upstream) {
return Err(fail(format!(
"firmware directory {} does not match the bundled driver {upstream}",
versions.join(", ")
)));
}
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) {
let firmware: Vec<String> = firmware_names.into_iter().take(16).collect();
// The live-only load script and its unit must be present and gated so a
// machine without an NVIDIA GPU never records a failed unit. Nouveau must be
// blacklisted by the distro's own nvidia-kernel-common configuration.
if !exists_in_rootfs(rootfs, "usr/local/bin/phoebus-nvidia-load") {
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)
.into_iter()
.filter(|(_, p)| size_of(p) > 0)
.map(|(n, _)| n)
.take(16)
.collect();
// 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(),
));
let mut has_nouveau_blacklist = false;
if let Ok(entries) = std::fs::read_dir(rootfs.join("etc/modprobe.d")) {
for entry in entries.flatten() {
let rel = format!("etc/modprobe.d/{}", entry.file_name().to_string_lossy());
if let Some(text) = read_in_rootfs(rootfs, &rel) {
if text.contains("blacklist nouveau") {
has_nouveau_blacklist = true;
}
// 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.
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") {
}
}
}
if !has_nouveau_blacklist {
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(),
));
}
if !conf.contains("modeset=1") {
return Err(fail(
"etc/modprobe.d/phoebus-nvidia.conf does not enable nvidia_drm modeset".into(),
));
}
Ok(LiveNvidiaPayload {
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)]
mod tests {
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) {
write_bytes(path, 8192);
}
/// 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);
std::fs::create_dir_all(path.parent().unwrap()).unwrap();
std::fs::write(path, b"x").unwrap();
}
fn complete_rootfs(root: &Path) {
touch(&root.join(format!("boot/vmlinuz-{KVER}")));
install_modules(root);
let kver = "6.16.7-amd64";
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 [
format!("libnvidia-glcore.so.{DRIVER}"),
"libGLX_nvidia.so.0".to_string(),
"libnvidia-egl-gbm.so.1.1.2".to_string(),
"libnvidia-egl-wayland.so.1.1.21".to_string(),
"libnvidia-glcore.so.550.163.01",
"libGLX_nvidia.so.0",
"libnvidia-egl-gbm.so.1.1.2",
"libnvidia-egl-wayland.so.1.1.21",
] {
touch(&root.join("usr/lib/x86_64-linux-gnu").join(lib));
}
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/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"));
let conf = root.join("etc/modprobe.d/phoebus-nvidia.conf");
std::fs::create_dir_all(conf.parent().unwrap()).unwrap();
std::fs::write(&conf, b"blacklist nouveau\noptions nvidia_drm modeset=1\n").unwrap();
let blacklist = root.join("etc/modprobe.d/nvidia-blacklists-nouveau.conf");
std::fs::create_dir_all(blacklist.parent().unwrap()).unwrap();
std::fs::write(&blacklist, b"blacklist nouveau\n").unwrap();
}
#[test]
@ -572,38 +396,24 @@ mod tests {
let dir = tempfile::tempdir().unwrap();
complete_rootfs(dir.path());
let payload =
verify_live_nvidia(dir.path(), DRIVER, NvidiaModuleFlavor::Proprietary).unwrap();
assert_eq!(payload.kernel_version, KVER);
verify_live_nvidia(dir.path(), "550.163.01", NvidiaModuleFlavor::Proprietary).unwrap();
assert_eq!(payload.kernel_version, "6.16.7-amd64");
assert_eq!(payload.modules.len(), 4);
let record = payload.record();
assert!(record.contains("driver_version=550.163.01"));
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]
fn missing_kernel_module_fails_the_build() {
let dir = tempfile::tempdir().unwrap();
complete_rootfs(dir.path());
std::fs::remove_file(
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();
let err = verify_live_nvidia(dir.path(), DRIVER, NvidiaModuleFlavor::Proprietary)
let err = verify_live_nvidia(dir.path(), "550.163.01", NvidiaModuleFlavor::Proprietary)
.unwrap_err()
.to_string();
assert!(err.contains("nvidia_drm"), "{err}");
@ -614,14 +424,14 @@ mod tests {
let dir = tempfile::tempdir().unwrap();
complete_rootfs(dir.path());
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();
std::fs::create_dir_all(dir2.path().join("usr/lib/firmware")).unwrap();
complete_rootfs(dir2.path());
// Remove the firmware tree.
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()
.to_string();
assert!(err.contains("firmware"), "{err}");
@ -634,23 +444,25 @@ mod tests {
// Debian is merged-usr: the same kernel tree is visible under both
// /lib/modules and /usr/lib/modules. That must not look like two
// 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::write(dst.join("modules.dep"), b"").unwrap();
for m in ["nvidia", "nvidia_modeset", "nvidia_uvm", "nvidia_drm"] {
touch(&dst.join(format!("updates/dkms/{m}.ko")));
}
let payload =
verify_live_nvidia(dir.path(), DRIVER, NvidiaModuleFlavor::Proprietary).unwrap();
assert_eq!(payload.kernel_version, KVER);
verify_live_nvidia(dir.path(), "550.163.01", NvidiaModuleFlavor::Proprietary).unwrap();
assert_eq!(payload.kernel_version, kver);
}
#[test]
fn debian_renamed_modules_are_accepted_and_recorded() {
let dir = tempfile::tempdir().unwrap();
complete_rootfs(dir.path());
let kernel = dir.path().join(format!("lib/modules/{KVER}"));
let dkms = kernel.join("updates/dkms");
let kver = "6.16.7-amd64";
let dkms = dir.path().join(format!("lib/modules/{kver}/updates/dkms"));
// Replace the upstream names with Debian's DKMS-renamed output.
for m in ["nvidia", "nvidia_modeset", "nvidia_uvm", "nvidia_drm"] {
std::fs::remove_file(dkms.join(format!("{m}.ko"))).unwrap();
@ -663,9 +475,8 @@ mod tests {
] {
touch(&dkms.join(format!("{m}.ko.xz")));
}
write_dep(&kernel);
let payload =
verify_live_nvidia(dir.path(), DRIVER, NvidiaModuleFlavor::Proprietary).unwrap();
verify_live_nvidia(dir.path(), "550.163.01", NvidiaModuleFlavor::Proprietary).unwrap();
assert!(payload
.modules
.contains(&"nvidia-current-drm.ko".to_string()));
@ -675,131 +486,11 @@ mod tests {
#[test]
fn missing_kernel_is_reported() {
let dir = tempfile::tempdir().unwrap();
std::fs::create_dir_all(dir.path().join(format!("lib/modules/{KVER}"))).unwrap();
std::fs::write(
dir.path().join(format!("lib/modules/{KVER}/modules.dep")),
b"",
)
.unwrap();
std::fs::create_dir_all(dir.path().join("lib/modules/6.16.7-amd64")).unwrap();
std::fs::write(dir.path().join("lib/modules/6.16.7-amd64/modules.dep"), b"").unwrap();
let err = verify_live_nvidia(dir.path(), "550", NvidiaModuleFlavor::Proprietary)
.unwrap_err()
.to_string();
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`).
use std::collections::HashMap;
use std::path::Path;
use phoebus_core::disk::{Disk, DiskKind};
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
// ---------------------------------------------------------------------------
@ -602,26 +557,4 @@ mod tests {
(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)]
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
/// (stdin/stdout). Not intended for direct interactive use.
#[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;
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 {
return Ok(verify_live_nvidia_command(&cli, rootfs));
}

View file

@ -524,13 +524,8 @@ impl Installer {
&self.engine,
&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)?;
self.record_nvidia(&plan, &installed)?;
self.record_nvidia(&plan)?;
Ok(())
})();
self.exec.umount_chroot()?;
@ -540,25 +535,11 @@ impl Installer {
result
}
/// Persist the resolved driver decision and the *actual* installed version
/// in the target, so post-install inspection and recovery know exactly what
/// was selected rather than only a "current" label.
fn record_nvidia(
&self,
plan: &phoebus_core::nvidia::NvidiaPlan,
installed: &boot::InstalledNvidia,
) -> Result<()> {
/// Persist the resolved driver decision in the target so post-install
/// inspection and recovery know exactly what was selected.
fn record_nvidia(&self, plan: &phoebus_core::nvidia::NvidiaPlan) -> Result<()> {
let mut text = String::new();
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!(
"flavor={}\n",
@ -569,9 +550,6 @@ impl Installer {
plan.generation.map(|g| g.as_str()).unwrap_or("none")
));
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 {
text.push_str(&format!(
"device={} {}\n",
@ -581,12 +559,9 @@ impl Installer {
}
text.push_str(&format!("reason={}\n", plan.reason));
self.exec.target().write("etc/phoebus/nvidia", text)?;
self.exec.logger.info(format!(
"recorded the NVIDIA driver selection in /etc/phoebus/nvidia (version {}, kernel {}, modules: {})",
if installed.version.is_empty() { "unknown" } else { &installed.version },
installed.kernel,
installed.modules.join(", ")
));
self.exec
.logger
.info("recorded the NVIDIA driver selection in /etc/phoebus/nvidia");
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 touch(path: &std::path::Path) {
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) {
let kver = "6.16.7-amd64";
touch(&root.join(format!("boot/vmlinuz-{kver}")));
let modules = root.join(format!("lib/modules/{kver}"));
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"] {
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 [
"libnvidia-glcore.so.550.163.01",
"libnvidia-glcore.so.550",
"libGLX_nvidia.so.0",
"libnvidia-egl-gbm.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/lib/firmware/nvidia/550.163.01/gsp.bin"));
touch(&root.join("usr/local/bin/phoebus-nvidia-load"));
let conf = root.join("etc/modprobe.d/phoebus-nvidia.conf");
std::fs::create_dir_all(conf.parent().unwrap()).unwrap();
std::fs::write(&conf, b"blacklist nouveau\noptions nvidia_drm modeset=1\n").unwrap();
let blacklist = root.join("etc/modprobe.d/nvidia-blacklists-nouveau.conf");
std::fs::create_dir_all(blacklist.parent().unwrap()).unwrap();
std::fs::write(&blacklist, b"blacklist nouveau\n").unwrap();
}
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));
}
#[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]
fn relocated_opencode_manifest_is_pinned_and_complete() {
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("linux-kbuild-"));
assert!(build.contains("--setup-hook"));
// The live driver policy file the verifier requires is actually produced,
// and Debian's unconditional nouveau configuration is replaced so the
// 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.
// Nouveau blacklisting/module options come from nvidia-kernel-common; the
// unconditional modules-load entry is removed in favour of the gated unit.
assert!(build.contains("nvidia-kernel-common"));
assert!(build.contains("modules-load.d/nvidia.conf"));
// A documented fail-safe entry disables NVIDIA for that boot, and marks the
// command line so the load script and unit both stand down.
// A documented fail-safe entry disables NVIDIA for that boot.
assert!(build.contains("nomodeset"));
assert!(build.contains("phoebus.nvidia=off"));
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
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
(`Ctrl+Alt+F2`): log in as `phoebus` / `phoebus` (live-only credential) and
use `sudo` with that password. Unattended (`NOPASSWD`) escalation is scoped
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.
(`Ctrl+Alt+F2`): log in as `phoebus` / `phoebus` (live-only credential),
passwordless `sudo`.
- The `phoebus-dwl` session remains selectable as a fallback.
## NVIDIA accelerated graphics
@ -116,30 +110,24 @@ anything at boot.
`nvidia-kernel-dkms` renames them `nvidia-current`, `nvidia-current-modeset`,
`nvidia-current-drm` and `nvidia-current-uvm`; the verifier and the hook
accept either that naming or the upstream names.
- `build.sh` then runs `phoebus-installer --verify-live-nvidia`. It is a
compatibility gate, not a presence list: it rejects placeholder
modules/libraries, requires every module to be registered in the live kernel's
`modules.dep`, checks the userspace `libnvidia-glcore` and firmware-directory
versions against the bundled driver, infers and checks the module flavor,
requires non-empty GSP firmware and the exact
`etc/modprobe.d/phoebus-nvidia.conf`. It runs on **every** build, including
`PHOEBUS_REUSE_ROOTFS=1`, so a cached rootfs can never silently ship a
mismatched payload. The bundled driver version, module flavor and kernel are
recorded in `/etc/phoebus/nvidia` on the medium.
- The live load script makes a **deterministic, device-based decision** via
`phoebus-installer --live-gpu-plan`, not a `0x10de` vendor grep. A supported
GPU loads the bundled accelerated stack; an unsupported GPU (or a failed
accelerated load) explicitly `modprobe`s `nouveau`; a machine with no NVIDIA
display device leaves auto-detection alone. `build.sh` writes
`etc/modprobe.d/phoebus-nvidia.conf` (replacing Debian's unconditional
nouveau configuration), so the fallback is real. Debian's unconditional
modules-load entry is removed in favour of `phoebus-nvidia.service`, which
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).
- `build.sh` then runs `phoebus-installer --verify-live-nvidia`, which checks
the kernel modules, the GLVND/EGL/GBM userspace libraries, `nvidia-smi`, the
EGL external-platform manifests, the GSP firmware, the gated load script and
the nouveau blacklist. It runs on **every** build, including
`PHOEBUS_REUSE_ROOTFS=1`, so a cached rootfs can never silently ship without
the payload. The bundled driver version, module flavor and kernel are recorded
in `/etc/phoebus/nvidia` on the medium.
- Nouveau blacklisting and module options come from Debian's own
`nvidia-kernel-common`. Its unconditional modules-load entry is removed in
favour of the live-only `phoebus-nvidia.service`, which runs the gated
`phoebus-nvidia-load` before greetd/Mango **only when an NVIDIA display device
is present**, so systems without one keep nouveau/virtio and record no failed
unit.
- The GRUB **fail-safe graphics** entry disables modesetting
(`nomodeset`) and blacklists the NVIDIA modules for that boot; it is the
documented recovery path when driver initialisation misbehaves. 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
(`x11-drivers/nvidia-drivers`) with the branch/flavor selected from the PCI
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
mango-config mango-session-target install-desktop
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
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).
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
# diagnostics. The driver modules themselves are built into the rootfs by
# 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
# gated service above (which is a no-op without an NVIDIA display device).
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
# 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.
t = t.replace(
'nosplash vga=788',
'nosplash vga=788 nomodeset phoebus.nvidia=off '
'nosplash vga=788 nomodeset '
'modprobe.blacklist=nvidia,nvidia_modeset,nvidia_uvm,nvidia_drm')
open(p, "w").write(t)
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"
fi
install -d -m 0755 "$root/etc/sudoers.d"
# The live privilege policy is the scoped, visudo-validated asset installed by
# build.sh (only the typed brokers escalate without a prompt). The recovery
# console keeps root through the password-authenticated sudo group below.
printf '%s ALL=(ALL) NOPASSWD: ALL\n' "$LIVE_USER" > "$root/etc/sudoers.d/90-phoebus-live"
chmod 440 "$root/etc/sudoers.d/90-phoebus-live"
# 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
# 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).
- `install.sh` guest-side, non-interactive installation (run in the VM).
- `serial-driver.py` host-side pexpect driver (`install`, `boot` and
`rollback` modes).
- `rollback-guest.sh`, `rollback-verify.sh` guest-side rollback acceptance
(fetch `sys`, snapshot, break, undo, verify).
- `serial-driver.py` host-side pexpect driver (`install` and `boot` modes).
- `test.conf.example` installer configuration used by the driver.
## 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
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)
`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
validate a model response and proposal.
gui-install: complete a full installation through the visible wizard (AI
connection, disk, account, direct "Install now", install) on a
disposable disk.
connection, disk, account, ERASE, install) on a disposable disk.
install : boot, log in on serial, fetch a non-interactive config and 0600
secrets over QEMU user networking, run the deterministic install
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_PW = os.environ.get("USER_PASSWORD", "phoebus-user-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")
SMP = os.environ.get("VM_SMP", "8")
BOOT_TIMEOUT = int(os.environ.get("BOOT_TIMEOUT", "900"))
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"))
# 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.
@ -501,16 +499,12 @@ class Driver:
f"n1={n1} n2={n2}",
)
# The installer opens directly on step 1 (language and keyboard): the
# duplicate step-0 welcome was removed. Capture it and walk with
# Ctrl+Right from the frontend's own state, not a keystroke count.
at_language = self._goto_step(1)
self.results.assert_true(
"language-step-reached",
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",
# Keyboard-walk the wizard, capturing each step. The welcome step's
# primary action is focused, so Return starts the journey; Ctrl+Right
# then advances through the deterministic steps.
self.sendkey("ret")
time.sleep(2)
self.shot("03-language", "language and keyboard", "Return on Get started",
"the language and keyboard step is shown")
# Regression: the suggestion list supports arrow-key navigation and
# 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",
"the highlighted locale is selected")
for slug, label, target in [
("04-network", "network and prerequisites", 2),
("05-ai-model", "AI model connection", 3),
for slug, state in [
("04-network", "network and prerequisites"),
("05-ai-model", "AI model connection"),
]:
reached = self._goto_step(target)
self.results.assert_true(
f"{slug}-reached", reached is not None and reached["step"] == target,
f"did not reach {label}: {reached}",
)
self.shot(slug, label, "Ctrl+Right", "next wizard step")
self.sendkey("ctrl-right")
time.sleep(2)
self.shot(slug, state, "Ctrl+Right", "next wizard step")
if not self._installer_alive():
self.results.fail("installer-survived-navigation", f"crashed at {slug}")
return
@ -664,36 +655,6 @@ class Driver:
time.sleep(2)
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:
"""Drive the OpenCode AI step through the real graphical UI.
@ -745,13 +706,19 @@ class Driver:
"CLOSED", timeout=30, label="close-welcome",
)
# Navigate to the AI step from step 1 (language -> network -> AI).
state = self._goto_step(3)
# Navigate to the AI step (welcome -> language -> network -> AI).
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(
"ai-step-reached", state is not None and state["step"] == 3,
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
# with the first provider chip focused.
@ -923,9 +890,8 @@ class Driver:
`appliance-guest-gui.sh` installs non-interactively, which does not
prove the graphical journey. This mode presses the real controls: it
connects OpenCode through the UI, accepts the reviewed AI changes,
selects a disk, sets the account, triggers the direct "Install now"
action, and checks the frontend reports completion. The disk must be a
disposable qcow2.
selects a disk, sets the account, types ERASE, installs, and checks the
frontend reports completion. The disk must be a disposable qcow2.
"""
if not self.disks:
self.results.blocked("gui-install-disk", "no writable disk configured")
@ -942,17 +908,12 @@ class Driver:
self.set_wayland()
# Preseed the wizard defaults so the run is bounded (safe kernel, no
# desktop) while the wizard, validation, AI gate and the direct
# "Install now" authorization 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).
# desktop) while the wizard, validation, AI gate and ERASE confirmation
# remain the real graphical path.
self.shell(
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 -S -p '' install -D -m 0644 /tmp/gui-install.conf /etc/phoebus/install.conf "
"< /tmp/live.pw && echo PRESEED-$(printf DONE)",
"sudo -n install -D -m 0644 /tmp/gui-install.conf /etc/phoebus/install.conf && "
"echo PRESEED-$(printf DONE)",
"PRESEED-DONE", timeout=60, label="preseed-config",
)
# Start the loopback relay to the host OpenCode server.
@ -988,11 +949,17 @@ class Driver:
"CLOSED", timeout=30, label="close-welcome",
)
# The installer opens on step 1; advance to the AI step.
state = self._goto_step(3)
# Welcome -> language -> network -> AI.
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,
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.
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")
# Destination disk: pick the first selectable disk.
self._goto_step(4)
self.sendkey("ctrl-right")
time.sleep(3)
self.sendkey("tab")
time.sleep(0.5)
self.sendkey("ret")
@ -1073,66 +1041,59 @@ class Driver:
f"the disk selection did not survive backtracking: {state}",
)
# Account and encryption. The current product has a single Username
# field, a Computer name, Password and Confirm password; the
# "Use same password to encrypt disk" toggle is on by default, so the
# separate LUKS passphrase fields are hidden and must not be driven.
state = self._goto_step(5)
# Account and encryption.
self.sendkey("ctrl-right")
time.sleep(2)
state = self._frontend_state()
self.results.assert_true("gui-install-account-step", state is not None and state["step"] == 5,
f"account step not reached: {state}")
# Focus opens on Username.
self._gui_type(USER_NAME)
self._tabs(1) # -> Computer name
self._gui_type(HOST_NAME)
self._tabs(1) # -> Password
self._tabs(3) # full name -> username -> computer name -> password
self._gui_type(USER_PW)
self._tabs(1) # -> Confirm password
self._tabs(2) # reveal -> confirm password
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",
"username, computer name and matching password entered")
"password and passphrase entered")
# Review. The product now uses a direct "Install now" action: typing
# ERASE and the confirmation checkbox were intentionally removed, and
# Ctrl+Right on the review step runs exactly that action. The backend
# still enforces approval binding and disk revalidation.
state = self._goto_step(6)
# Review and ERASE. The review step focuses the ERASE field.
self.sendkey("ctrl-right")
time.sleep(4)
state = self._frontend_state()
self.results.assert_true("gui-install-review-step", state is not None and state["step"] == 6,
f"review step not reached: {state}")
self.shot("gi-05-review", "review and confirmation", "review shown",
"backend facts and the installation plan")
self.sendkey("ctrl-right") # Install now
started = time.monotonic()
"backend facts, plan and ERASE confirmation")
self._gui_type("ERASE")
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",
"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(
lambda s: s["phase"] in ("done", "failed"),
timeout=INSTALL_TIMEOUT,
)
if done is None:
elapsed = int(time.monotonic() - started)
self.results.fail(
"gui-install-completes",
f"the wizard did not report completion after {elapsed}s "
f"({self._install_progress()})",
)
self.results.fail("gui-install-completes", "the wizard did not report completion")
return
self.results.assert_true(
"gui-install-completes", done["phase"] == "done",
@ -1250,20 +1211,7 @@ class Driver:
assert self.child is not None
idx = self.expect([r"[Pp]assphrase", r"login:"], timeout=BOOT_TIMEOUT, label="boot-prompt")
if idx == 0:
# `gui-install` uses the default single-password encryption, so the
# 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
self.child.sendline(LUKS_PW)
logged_in = False
for _ in range(5):
try:

View file

@ -110,7 +110,7 @@ def main():
"pgrep -a qs || pgrep -a quickshell || echo NO-QUICKSHELL; "
"pgrep -af 'waybar|mako|swayidle|swaylock' || echo NO-DWL-HELPERS; "
"ls -l /dev/dri 2>&1; "
"systemctl is-enabled greetd; "
"sudo -n systemctl is-enabled greetd; "
"echo ===CHECKS-$(printf END)===",
)
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
"""Headless serial driver for the disposable UEFI VM.
Modes:
Two modes:
install : boot the live ISO kernel/initrd, run a guest script that installs
Phoebus non-interactively, then power off.
boot : boot the installed disk alone (no ISO, no -kernel), unlock LUKS,
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
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"
)
# 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():
import pathlib
@ -124,147 +112,6 @@ def do_install(results, paths, disks):
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):
env, args = base_args(str(paths.ovmf_vars))
for disk in disks:
@ -315,7 +162,7 @@ def do_boot(results, paths, disks):
def main() -> int:
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__)
return 2
results = Results(f"serial-{mode}")
@ -334,8 +181,6 @@ def main() -> int:
try:
if mode == "install":
do_install(results, paths, disks)
elif mode == "rollback":
do_rollback(results, paths, disks)
else:
do_boot(results, paths, disks)
finally:

View file

@ -223,31 +223,5 @@ class QmpClientTests(unittest.TestCase):
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__":
unittest.main(verbosity=2)