Compare commits

...

9 commits

Author SHA1 Message Date
3b1b54ffb9 docs: reconcile NVIDIA, verification and harness status
Some checks are pending
ci / test (push) Waiting to run
Record the reliability pass across STATUS, HANDOFF, CHANGELOG, ADR 0012,
the live README and the boot-verification log: the deterministic live GPU
decision with a real nouveau fallback, the 580 legacy cap and mixed
open/proprietary incompatibility, the compatibility verifier, the
installed lifecycle fix, the repaired GUI harness, the automated but
unrun rollback gate, and the scoped live sudoers. Withdraw the stale
handoff claim that the gui_bridge tests hang (the workspace suite
passes) and record the installed-target missing-sys gap.
2026-09-23 06:28:30 -07:00
4265aefacd fix(live): scope the live privilege policy to the typed brokers
The live user had NOPASSWD: ALL for the graphical broker. Replace it with
an emitted, visudo-validated policy that grants unattended escalation only
to /usr/local/bin/phoebus-installer, /usr/local/bin/sys and the systemctl
power actions; no ALL, no sh -c and no wildcard. The recovery console is
preserved: it logs in with the live-only password and authenticates sudo.
build.sh installs the asset, validates it with visudo and refuses any
unscoped policy. The GUI harness stages its preseed config with the
password-authenticated sudo over a 0600 file instead of bare install, and
the read-only greetd check no longer needs sudo.
2026-09-23 06:22:19 -07:00
c759477c7f test(vm): automate rollback acceptance on a disposable clone
Add a serial-driver rollback mode and guest scripts that exercise the real
rollback path: record the /var/db/pkg fingerprint and a /home marker,
create a recovery point with sys snapshot, install a small package as a
controlled reversible update, run sys undo, power off, boot detached and
compare the restored package state and /home against the pre-rollback
values. Checks kernel modules, the snapshot recovery entry and sys
rollback status. sys is fetched from the host, matching the existing
harness evidence procedure; booting the recovery entry offline remains a
documented manual gate. bash -n guards for every guest script are added
to the no-VM unit tests.
2026-09-23 06:19:17 -07:00
a510efdea2 test(gui): drive the current six-step installer instead of the removed UI
The graphical harness still assumed a step-0 welcome, an ERASE field, a
confirmation checkbox, a full-name field and separate passphrase prompts
that were all removed. Update it to the current product:

- navigate with a state-based _goto_step() instead of counting
  Return/Ctrl+Right from a step that no longer exists;
- drive the real account fields (username, computer name, password,
  confirm) with the default single-password encryption, leaving the
  hidden passphrase fields alone;
- trigger the direct "Install now" action and drop the ERASE/confirm
  assertions, while still exercising duplicate submission;
- report stage, elapsed time and the last state on an install timeout;
- boot with the single-password disk passphrase (user password) and fall
  back to the separate passphrase, instead of always using LUKS_PW;
- remove the dead SESSION_SETTLE knob.
2026-09-23 06:16:30 -07:00
12f264a0e9 fix(nvidia): install the driver before forcing it into the initramfs
The installer wrote dracut force_drivers naming nvidia modules during the
first kernel build, before the driver package existed, so the initial
kernel/initramfs build could not resolve them. Only the NVIDIA install
stage installs the driver and regenerates the initramfs.

- dracut_conf() no longer emits the NVIDIA fragment; the modprobe policy
  is still written before the kernel.
- write_nvidia_dracut_conf() writes it in the NVIDIA stage, after emerge
  and before kernel-install add-all.
- verify_nvidia_modules() proves the driver actually built modules for a
  kernel and fails the install otherwise; it returns the resolved version
  from var/db/pkg so the record carries the real version, kernel and
  module names rather than a 'current' label.
- The update path verifies the rebuilt modules before reporting success;
  previous kernels and module trees are left in place.
2026-09-23 06:13:14 -07:00
33b0b1df77 style: cargo fmt the nvidia changes 2026-09-23 06:10:21 -07:00
5103b57be9 test(nvidia): make the live payload gate prove compatibility
The verifier accepted one-byte placeholder modules, a caller-supplied
version/flavor, any NVIDIA firmware file and a nouveau blacklist that
happened to exist somewhere. It now establishes what it claims:

- reject placeholder modules and userspace libraries (size floor);
- require every module to be registered in the live kernel's modules.dep;
- normalise the dpkg revision and require the userspace libnvidia-glcore
  and firmware directory versions to match the bundled driver;
- infer the module flavor from the on-disk naming and reject a
  contradiction;
- require the exact etc/modprobe.d/phoebus-nvidia.conf with nouveau
  blacklist and nvidia_drm modeset, not any blacklist;
- keep every filesystem read rooted inside the build root.

Negative tests cover placeholders, version mismatches, a stale
modules.dep, a contradictory flavor and a missing final config.
2026-09-23 06:09:54 -07:00
b32683da99 fix(nvidia): cap the legacy branch at 580 and reject mixed open/proprietary hardware
NVIDIA's 580 series is the last to support Maxwell/Pascal/Volta, and
Blackwell requires the open kernel modules. The policy previously masked
>=595, which permits branches that already dropped those architectures,
and assumed the oldest card's branch could serve every newer card.

- Mask >=x11-drivers/nvidia-drivers-581 for the proprietary branch (the
  first series after the last supporting one).
- Compute compatibility across the whole device set: Blackwell plus a
  proprietary-only GPU has no single branch and is reported as an
  explicit incompatibility (nouveau) instead of installing a driver that
  cannot accelerate one card.
- Pascal + Ampere remains proprietary and supported (Ampere accepts
  either flavor).
2026-09-23 06:06:51 -07:00
dc5e27e60a fix(nvidia): deterministic live GPU decision, nouveau fallback and fail-safe
The live load script previously modprobed the NVIDIA stack for any PCI
vendor 0x10de and the build required etc/modprobe.d/phoebus-nvidia.conf
that nothing created. Replace the vendor-name check with a deterministic
decision computed from the actual display controllers and the bundled
branch's capabilities:

- phoebus-core gains live_nvidia_plan(): supported GPU -> load the
  bundled accelerated stack; unsupported GPU -> explicit nouveau
  fallback; no GPU -> leave auto-detection; fail-safe -> load nothing.
- phoebus-installer --live-gpu-plan scans sysfs (overridable for tests)
  and prints stable key=value lines; probe_nvidia_display_devices() only
  considers display-class NVIDIA functions.
- phoebus-nvidia-load consults it, falls back to nouveau on an
  unsupported GPU or a failed accelerated load, and never fails the
  unit; the service honours phoebus.nvidia=off.
- build.sh now creates the live modprobe policy, replaces Debian's
  unconditional nouveau blacklist, and marks the fail-safe entry.
2026-09-23 06:05:27 -07:00
25 changed files with 2178 additions and 499 deletions

View file

@ -3,6 +3,57 @@
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,144 +3,127 @@
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), Comprehensive installer UX overhaul: 6-step flow, friendly pickers, and resilient UI.
- **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.
- **Current focus:**
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.
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.
- **Last verified (this session):**
- 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.
- `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).
- **Public repo:** <https://git.phoebus.club/phoebus/phoebus_os>
(remote `origin`, SSH port 2222).
## Next actions (in order)
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`).
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.
7. **Release gates on a CI runner**: `phoebus-release gates --execute` and
`publish` once a runner exists; no gate has executed.
## Known blockers / risks
- **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.
- **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.
- 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 present.
- Dev host: Ubuntu 26.04. QEMU/OVMF/xorriso/rustfmt/clippy/ImageMagick/visudo
present. ~12 GiB free on the root filesystem.
- Debian-Live base ISO is cached at `/home/dominic/debian-live-standard.iso`
(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`).
(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.
## Definition of a good stopping point
- `make test` passes; `docs/STATUS.md` and `docs/CHANGELOG.md` updated;
`docs/HANDOFF.md` updated; committed and pushed
(`scripts/agent-commit.sh` + `scripts/publish.sh`).
`docs/HANDOFF.md` updated; committed (via `scripts/agent-commit.sh`) and
pushed (`scripts/publish.sh`).

View file

@ -118,6 +118,10 @@ 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
@ -131,33 +135,49 @@ 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. 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.
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.
- **UKI** is deferred; the dracut UKI generator did not embed the kernel
command line, so BLS is used (and verified).
- **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.
- **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.
- **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,13 +399,23 @@ 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-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.
**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.
## Mango + DankMaterialShell verification (IN PROGRESS)

View file

@ -14,11 +14,14 @@ 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) 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.
- **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.
- **Maxwell, Pascal and Volta** cannot use the open modules and need the
proprietary modules from a branch that still supports them.
proprietary modules. NVIDIA's **580 series is the last** to support them; the
next series drops those architectures.
- **Fermi, Kepler and older** have no security-supported proprietary branch;
the in-tree `nouveau` driver is the honest choice.
@ -40,15 +43,24 @@ never claimed as supported.
### 2. Deterministic branch/flavor selection
One driver install covers every adapter, so the branch must serve the **oldest**
supported GPU present:
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:
| Generation | Branch | Module flavor | Portage |
| --- | --- | --- | --- |
| 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` |
| 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` |
| 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.
@ -80,8 +92,21 @@ 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 Ada/Hopper. **Blackwell is unsupported by that
modules cover Maxwell through 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
@ -91,11 +116,15 @@ 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 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.
`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.
- 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,18 +13,27 @@
//!
//! Branch policy (NVIDIA/Gentoo, verified 2026-09):
//!
//! * **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.
//! * **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.
//! * **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
@ -39,10 +48,18 @@ 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). Maxwell/Pascal/Volta are
/// pinned below this cut.
/// (`USE=kernel-open` can no longer be disabled). Informational: the
/// Maxwell/Pascal/Volta cap is the earlier legacy cut below, not this one.
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";
@ -54,6 +71,13 @@ 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")]
@ -122,6 +146,26 @@ 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.
@ -166,6 +210,11 @@ 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
@ -242,13 +291,70 @@ impl NvidiaPlan {
};
}
// 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()
.any(|d| d.support() == NvidiaSupport::Proprietary);
let flavor = if needs_proprietary {
// 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
.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 {
NvidiaModuleFlavor::Proprietary
} else {
NvidiaModuleFlavor::Open
@ -294,10 +400,12 @@ impl NvidiaPlan {
flavor: Some(flavor),
branch: match flavor {
NvidiaModuleFlavor::Open => {
format!("current open kernel modules (>= {OPEN_MANDATORY_SERIES})")
format!("current open kernel modules (mandatory from {OPEN_MANDATORY_SERIES})")
}
NvidiaModuleFlavor::Proprietary => {
format!("proprietary (for Maxwell/Pascal/Volta; capped below {OPEN_MANDATORY_SERIES})")
format!(
"proprietary (Maxwell/Pascal/Volta; capped at the last supporting series {LEGACY_PROPRIETARY_LAST_SERIES})"
)
}
},
reason,
@ -327,12 +435,16 @@ impl NvidiaPlan {
}
}
/// `package.mask` lines. Maxwell/Pascal/Volta must stay below the branch
/// that made the open modules mandatory.
/// `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.
pub fn gentoo_package_mask(&self) -> Vec<String> {
match self.flavor {
Some(NvidiaModuleFlavor::Proprietary) => {
vec![format!(">={GENTOO_ATOM}-{OPEN_MANDATORY_SERIES}")]
vec![format!(
">={GENTOO_ATOM}-{}",
LEGACY_PROPRIETARY_LAST_SERIES + 1
)]
}
_ => Vec::new(),
}
@ -471,6 +583,155 @@ 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(':')?;
@ -513,14 +774,17 @@ mod tests {
}
#[test]
fn pascal_uses_the_proprietary_branch_and_is_masked_below_595() {
fn pascal_uses_the_proprietary_branch_capped_after_580() {
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-595".to_string()]
vec![">=x11-drivers/nvidia-drivers-581".to_string()]
);
assert!(plan.branch.contains("580"));
assert!(plan.gentoo_package_use()[0].contains("-kernel-open"));
}
@ -569,7 +833,9 @@ mod tests {
}
#[test]
fn mixed_old_and_new_picks_the_proprietary_branch_for_the_oldest() {
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.
let hw = hardware(vec![
nvidia("10de:1b81", "GP104 [GeForce GTX 1070]"),
nvidia("10de:2482", "GA104 [GeForce RTX 3070]"),
@ -579,6 +845,27 @@ 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 {
@ -626,4 +913,57 @@ 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 below the
/// branch that made NVIDIA's open kernel modules mandatory.
/// Scoped `package.mask` lines. Maxwell/Pascal/Volta must stay on the last
/// NVIDIA series that supports them (580); the next series is masked.
pub fn package_mask(config: &InstallConfig, hardware: &HardwareReport) -> String {
let _ = config;
let nvidia = crate::nvidia::NvidiaPlan::for_hardware(hardware);
@ -461,7 +461,13 @@ pub fn install_conf() -> String {
o
}
pub fn dracut_conf(config: &InstallConfig, hardware: &HardwareReport) -> String {
/// 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 {
let mut o = String::new();
o.push_str(&format!(
"# {} dracut configuration\n",
@ -471,14 +477,16 @@ pub fn dracut_conf(config: &InstallConfig, hardware: &HardwareReport) -> String
o.push_str("hostonly=\"no\"\n");
o.push_str("compress=\"zstd\"\n");
o.push_str("add_dracutmodules+=\" crypt btrfs \"\n");
// NVIDIA: force the DRM/modeset modules (and their firmware) into the
// initramfs so the compositor never starts against a modeset-less GPU.
if let Some(nvidia) = crate::nvidia::NvidiaPlan::for_hardware(hardware).dracut_conf() {
o.push_str(&nvidia);
}
o
}
/// The NVIDIA dracut fragment that forces the DRM/modeset modules (and their
/// firmware) into the initramfs, so the compositor never starts against a
/// modeset-less GPU. Only meaningful once the modules are installed.
pub fn nvidia_dracut_conf(hardware: &HardwareReport) -> Option<String> {
crate::nvidia::NvidiaPlan::for_hardware(hardware).dracut_conf()
}
pub fn kernel_profile_config(config: &InstallConfig) -> String {
let profile = config.kernel.profile.as_str();
let mut o = String::new();
@ -1189,29 +1197,77 @@ 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
/// 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.
/// 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.
pub const PHOEBUS_NVIDIA_LOAD_SCRIPT: &str = r#"#!/bin/bash
# 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.
# 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*.
set -u
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
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"
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' ';')"
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
"#;
/// `phoebus-nvidia.service`: load the driver before greetd/Mango.
@ -1220,6 +1276,9 @@ 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
@ -1274,6 +1333,8 @@ 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(),
@ -1908,13 +1969,54 @@ 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();
assert!(load.contains("0x10de"));
assert!(load.contains("modprobe nvidia"));
// 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"));
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"));
@ -1941,13 +2043,16 @@ 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"));
let dracut = dracut_conf(&cfg, &hw);
assert!(dracut.contains("force_drivers+="));
assert!(dracut.contains("nvidia_drm"));
// 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"));
}
#[test]
fn nvidia_pascal_uses_proprietary_and_masks_the_open_mandatory_branch() {
fn nvidia_pascal_uses_proprietary_and_is_capped_after_580() {
let cfg = InstallConfig::default();
let hw = nvidia_hw("10de:1b81");
let use_text = package_use(&cfg, &hw);
@ -1955,7 +2060,7 @@ mod tests {
assert_eq!(
package_mask(&cfg, &hw),
"# NVIDIA: proprietary branch required for Maxwell/Pascal/Volta.\n\
>=x11-drivers/nvidia-drivers-595\n"
>=x11-drivers/nvidia-drivers-581\n"
);
}
@ -1967,7 +2072,8 @@ 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!(!dracut_conf(&cfg, &hw).contains("nvidia"));
assert!(nvidia_dracut_conf(&hw).is_none());
assert!(!dracut_conf(&cfg).contains("nvidia"));
}
#[test]

View file

@ -512,6 +512,13 @@ 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()
}
@ -686,6 +693,13 @@ 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,
@ -709,6 +723,25 @@ 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,11 +29,14 @@ pub fn write_dracut_conf(
) -> Result<()> {
exec.target().write(
"etc/dracut.conf.d/10-phoebus.conf",
sysgen::dracut_conf(config, hardware),
sysgen::dracut_conf(config),
)?;
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.
// 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.
if let Some(conf) = phoebus_core::nvidia::NvidiaPlan::for_hardware(hardware).modprobe_conf() {
exec.target()
.write("etc/modprobe.d/phoebus-nvidia.conf", conf)?;
@ -43,6 +46,146 @@ 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('/'))
@ -336,7 +479,7 @@ mod tests {
}
#[test]
fn nvidia_hardware_writes_modprobe_and_dracut_before_the_kernel_build() {
fn nvidia_modprobe_policy_precedes_the_kernel_but_force_drivers_follow_the_driver() {
use phoebus_core::hardware::{GpuInfo, GpuVendor};
let runner = RecordingRunner::new();
let exec = make_exec(runner);
@ -348,16 +491,48 @@ 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("nvidia_drm"));
assert!(!dracut.contains("force_drivers"));
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,17 +106,20 @@ fn kernel_version(rootfs: &Path) -> Result<String> {
}
}
fn walk(root: &Path, out: &mut Vec<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)>) {
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(&path, out),
Ok(ft) if ft.is_dir() => walk_files(&path, out),
Ok(_) => {
if let Some(name) = path.file_name().and_then(|n| n.to_str()) {
out.push(name.to_string());
out.push((name.to_string(), path));
}
}
Err(_) => {}
@ -125,6 +128,26 @@ fn walk(root: &Path, out: &mut Vec<String>) {
}
}
/// 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('/'));
@ -145,35 +168,48 @@ fn read_in_rootfs(rootfs: &Path, rel: &str) -> Option<String> {
None
}
/// 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 {
current = current.parent().unwrap_or(rootfs).join(target);
}
}
Ok(meta) => return meta.is_file(),
}
}
false
/// 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)
}
/// 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 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")
} else {
None
}
}
/// The logical NVIDIA module and the on-disk names that may provide it. Debian's
@ -194,20 +230,54 @@ fn name_matches(file: &str, module: &str) -> bool {
file == format!("{module}.ko") || file.starts_with(&format!("{module}.ko."))
}
/// The mounted-module name actually found on disk.
fn find_module(names: &[String], module: &str) -> Option<String> {
for candidate in module_candidates(module) {
if names.iter().any(|n| name_matches(n, candidate)) {
return Some(format!("{candidate}.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
}
/// Verify that `rootfs` bundles a complete NVIDIA payload for its live kernel.
/// The on-disk module file for a logical module: `(recorded label, file name,
/// path)`. The label is the canonical `<candidate>.ko`; the file name keeps the
/// compression/renaming suffix for the `modules.dep` check.
fn find_module_file(
files: &[(String, PathBuf)],
module: &str,
) -> Option<(String, String, PathBuf)> {
for candidate in module_candidates(module) {
if let Some((name, path)) = files.iter().find(|(n, _)| name_matches(n, candidate)) {
return Some((format!("{candidate}.ko"), name.clone(), path.clone()));
}
}
None
}
/// Verify that `rootfs` bundles a complete and *self-consistent* NVIDIA payload
/// for the one kernel it boots.
///
/// Any missing or mismatched component is a hard error: the build fails rather
/// than shipping an image that cannot accelerate the GPU it advertises.
/// 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.
pub fn verify_live_nvidia(
rootfs: &Path,
driver_version: &str,
@ -220,26 +290,43 @@ 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.
let mut module_names = Vec::new();
// 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();
for modules_root in ["lib/modules", "usr/lib/modules"] {
let dir = rootfs.join(modules_root).join(&kernel);
if dir.is_dir() {
module_names.extend(names_under(&dir));
for (name, path) in files_under(&dir) {
if !module_files.iter().any(|(n, _)| n == &name) {
module_files.push((name, path));
}
}
}
}
if module_names.is_empty() {
if module_files.is_empty() {
return Err(fail(format!(
"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(&module_names, module) {
Some(name) => modules.push(name),
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));
}
None => missing.push(module),
}
}
@ -250,30 +337,64 @@ 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_names = names_under(&rootfs.join("usr/lib"));
let lib_files = files_under(&rootfs.join("usr/lib"));
let mut userspace = Vec::new();
let mut missing_lib = Vec::new();
if let Some(name) = find_prefix(&lib_names, "libnvidia-glcore.so") {
userspace.push(name);
} else {
missing_lib.push("libnvidia-glcore.so");
}
if let Some(name) = find_prefix(&lib_names, "libGLX_nvidia.so") {
userspace.push(name);
} else {
missing_lib.push("libGLX_nvidia.so");
}
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");
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 prefix == "libnvidia-glcore.so" {
glcore_version = embedded_version(name, prefix);
}
userspace.push(prefix.to_string());
}
None => missing_lib.push(prefix),
}
}
if !missing_lib.is_empty() {
return Err(fail(format!(
@ -281,61 +402,97 @@ pub fn verify_live_nvidia(
missing_lib.join(", ")
)));
}
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) {
// 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 {
return Err(fail(format!(
"EGL external-platform manifest {required_json} is missing under usr/share/egl/egl_external_platform.d"
"userspace library version {found_version} does not match the bundled driver {upstream}"
)));
}
}
userspace.push("15_nvidia_gbm.json".into());
userspace.push("10_nvidia_wayland.json".into());
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(),
))
}
}
// 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() {
// 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() {
return Err(fail(
"no NVIDIA firmware found under usr/lib/firmware/nvidia (firmware-nvidia-gsp/graphics not installed)"
.into(),
));
}
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") {
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) {
return Err(fail(
"usr/local/bin/phoebus-nvidia-load is missing (gated driver load)".into(),
"no non-empty GSP firmware (gsp_*.bin) found under usr/lib/firmware/nvidia".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;
}
}
}
}
if !has_nouveau_blacklist {
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(
"no nouveau blacklist found under etc/modprobe.d; the selected branch could be preempted"
"usr/local/bin/phoebus-nvidia-load is missing or empty (gated driver load)".into(),
));
}
// The final boot configuration must carry the intended policy, not merely
// any nouveau blacklist somewhere: the load script and the fallback both
// depend on this exact file.
let conf = read_in_rootfs(rootfs, "etc/modprobe.d/phoebus-nvidia.conf").ok_or_else(|| {
fail("etc/modprobe.d/phoebus-nvidia.conf is missing; the live driver policy was not installed".into())
})?;
if !conf.contains("blacklist nouveau") {
return Err(fail(
"etc/modprobe.d/phoebus-nvidia.conf does not blacklist nouveau; the driver 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,
@ -347,48 +504,67 @@ 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::*;
fn touch(path: &Path) {
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, b"x").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);
}
fn complete_rootfs(root: &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();
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")));
}
touch(&root.join(format!("boot/vmlinuz-{KVER}")));
install_modules(root);
for lib in [
"libnvidia-glcore.so.550.163.01",
"libGLX_nvidia.so.0",
"libnvidia-egl-gbm.so.1.1.2",
"libnvidia-egl-wayland.so.1.1.21",
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(),
] {
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("usr/lib/firmware/nvidia/550.163.01/gsp_ga10x.bin"));
touch(&root.join(format!("usr/lib/firmware/nvidia/{DRIVER}/gsp_ga10x.bin")));
touch(&root.join("usr/local/bin/phoebus-nvidia-load"));
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 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();
}
#[test]
@ -396,24 +572,38 @@ mod tests {
let dir = tempfile::tempdir().unwrap();
complete_rootfs(dir.path());
let payload =
verify_live_nvidia(dir.path(), "550.163.01", NvidiaModuleFlavor::Proprietary).unwrap();
assert_eq!(payload.kernel_version, "6.16.7-amd64");
verify_live_nvidia(dir.path(), DRIVER, NvidiaModuleFlavor::Proprietary).unwrap();
assert_eq!(payload.kernel_version, KVER);
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("lib/modules/6.16.7-amd64/updates/dkms/nvidia_drm.ko"),
.join(format!("lib/modules/{KVER}/updates/dkms/nvidia_drm.ko")),
)
.unwrap();
let err = verify_live_nvidia(dir.path(), "550.163.01", NvidiaModuleFlavor::Proprietary)
let err = verify_live_nvidia(dir.path(), DRIVER, NvidiaModuleFlavor::Proprietary)
.unwrap_err()
.to_string();
assert!(err.contains("nvidia_drm"), "{err}");
@ -424,14 +614,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(), "550", NvidiaModuleFlavor::Proprietary).is_err());
assert!(verify_live_nvidia(dir.path(), DRIVER, 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(), "550", NvidiaModuleFlavor::Proprietary)
let err = verify_live_nvidia(dir2.path(), DRIVER, NvidiaModuleFlavor::Proprietary)
.unwrap_err()
.to_string();
assert!(err.contains("firmware"), "{err}");
@ -444,25 +634,23 @@ 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 kver = "6.16.7-amd64";
let dst = dir.path().join(format!("usr/lib/modules/{kver}"));
std::fs::create_dir_all(dst.parent().unwrap()).unwrap();
let dst = dir.path().join(format!("usr/lib/modules/{KVER}"));
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(), "550.163.01", NvidiaModuleFlavor::Proprietary).unwrap();
assert_eq!(payload.kernel_version, kver);
verify_live_nvidia(dir.path(), DRIVER, 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 kver = "6.16.7-amd64";
let dkms = dir.path().join(format!("lib/modules/{kver}/updates/dkms"));
let kernel = dir.path().join(format!("lib/modules/{KVER}"));
let dkms = kernel.join("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();
@ -475,8 +663,9 @@ mod tests {
] {
touch(&dkms.join(format!("{m}.ko.xz")));
}
write_dep(&kernel);
let payload =
verify_live_nvidia(dir.path(), "550.163.01", NvidiaModuleFlavor::Proprietary).unwrap();
verify_live_nvidia(dir.path(), DRIVER, NvidiaModuleFlavor::Proprietary).unwrap();
assert!(payload
.modules
.contains(&"nvidia-current-drm.ko".to_string()));
@ -486,11 +675,131 @@ mod tests {
#[test]
fn missing_kernel_is_reported() {
let dir = tempfile::tempdir().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();
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();
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,6 +5,7 @@
//! independent of `run_cmd`).
use std::collections::HashMap;
use std::path::Path;
use phoebus_core::disk::{Disk, DiskKind};
use phoebus_core::hardware::{
@ -236,6 +237,50 @@ 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
// ---------------------------------------------------------------------------
@ -557,4 +602,26 @@ 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,6 +134,21 @@ 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)]
@ -212,6 +227,35 @@ 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 {
@ -545,6 +589,10 @@ 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,8 +524,13 @@ 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)?;
self.record_nvidia(&plan, &installed)?;
Ok(())
})();
self.exec.umount_chroot()?;
@ -535,11 +540,25 @@ impl Installer {
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<()> {
/// 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<()> {
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",
@ -550,6 +569,9 @@ 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",
@ -559,9 +581,12 @@ impl Installer {
}
text.push_str(&format!("reason={}\n", plan.reason));
self.exec.target().write("etc/phoebus/nvidia", text)?;
self.exec
.logger
.info("recorded the NVIDIA driver selection in /etc/phoebus/nvidia");
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(", ")
));
Ok(())
}

View file

@ -66,19 +66,21 @@ 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, b"x").unwrap();
std::fs::write(path, vec![0u8; 8192]).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();
std::fs::write(modules.join("modules.dep"), b"").unwrap();
let mut dep = Vec::new();
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",
"libnvidia-glcore.so.550.163.01",
"libGLX_nvidia.so.0",
"libnvidia-egl-gbm.so.1",
"libnvidia-egl-wayland.so.1",
@ -90,9 +92,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 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 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 run = |root: &std::path::Path| {
@ -132,6 +134,66 @@ 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,12 +57,21 @@ fn live_build_bundles_and_verifies_the_nvidia_payload() {
assert!(build.contains("trixie"));
assert!(build.contains("linux-kbuild-"));
assert!(build.contains("--setup-hook"));
// Nouveau blacklisting/module options come from nvidia-kernel-common; the
// unconditional modules-load entry is removed in favour of the gated unit.
// 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.
assert!(build.contains("nvidia-kernel-common"));
assert!(build.contains("modules-load.d/nvidia.conf"));
// A documented fail-safe entry disables NVIDIA for that boot.
// A documented fail-safe entry disables NVIDIA for that boot, and marks the
// command line so the load script and unit both stand down.
assert!(build.contains("nomodeset"));
assert!(build.contains("phoebus.nvidia=off"));
assert!(build.contains("modprobe.blacklist=nvidia"));
}

View file

@ -83,8 +83,14 @@ 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),
passwordless `sudo`.
(`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.
- The `phoebus-dwl` session remains selectable as a fallback.
## NVIDIA accelerated graphics
@ -110,24 +116,30 @@ 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`, 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).
- `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).
- 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
waybar-config waybar-style greetd-live live-sudoers
brand-emblem brand-wordmark brand-wallpaper brand-tokens
nvidia-load nvidia-service gpu-report
)
@ -256,6 +256,18 @@ 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
@ -270,6 +282,21 @@ 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
@ -437,7 +464,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 '
'nosplash vga=788 nomodeset phoebus.nvidia=off '
'modprobe.blacklist=nvidia,nvidia_modeset,nvidia_uvm,nvidia_drm')
open(p, "w").write(t)
PY

View file

@ -33,8 +33,9 @@ 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"
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"
# 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.
# 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,7 +7,10 @@ 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` and `boot` modes).
- `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).
- `test.conf.example` installer configuration used by the driver.
## Host prerequisites
@ -62,6 +65,33 @@ 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,7 +14,8 @@ 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, ERASE, install) on a disposable disk.
connection, disk, account, direct "Install now", 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.
@ -57,11 +58,12 @@ 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.
@ -499,12 +501,16 @@ class Driver:
f"n1={n1} n2={n2}",
)
# 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 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",
"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.
@ -526,13 +532,16 @@ class Driver:
)
self.shot("03b-locale-selected", "locale selected", "Down then Enter",
"the highlighted locale is selected")
for slug, state in [
("04-network", "network and prerequisites"),
("05-ai-model", "AI model connection"),
for slug, label, target in [
("04-network", "network and prerequisites", 2),
("05-ai-model", "AI model connection", 3),
]:
self.sendkey("ctrl-right")
time.sleep(2)
self.shot(slug, state, "Ctrl+Right", "next wizard step")
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")
if not self._installer_alive():
self.results.fail("installer-survived-navigation", f"crashed at {slug}")
return
@ -655,6 +664,36 @@ 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.
@ -706,19 +745,13 @@ class Driver:
"CLOSED", timeout=30, label="close-welcome",
)
# 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()
# Navigate to the AI step from step 1 (language -> network -> AI).
state = self._goto_step(3)
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", "Return + Ctrl+Right twice", "the AI model step is shown")
self.shot("oc-01-ai", "AI step", "Ctrl+Right to step 3", "the AI model step is shown")
# Select the "OpenCode agent" chip with the keyboard. The AI step opens
# with the first provider chip focused.
@ -890,8 +923,9 @@ 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, types ERASE, installs, and checks the
frontend reports completion. The disk must be a disposable qcow2.
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.
"""
if not self.disks:
self.results.blocked("gui-install-disk", "no writable disk configured")
@ -908,12 +942,17 @@ 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 ERASE confirmation
# remain the real graphical path.
# 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).
self.shell(
f"curl -fsSL {SERVE_URL}/test.conf -o /tmp/gui-install.conf && "
"sudo -n install -D -m 0644 /tmp/gui-install.conf /etc/phoebus/install.conf && "
"echo PRESEED-$(printf DONE)",
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)",
"PRESEED-DONE", timeout=60, label="preseed-config",
)
# Start the loopback relay to the host OpenCode server.
@ -949,17 +988,11 @@ class Driver:
"CLOSED", timeout=30, label="close-welcome",
)
# 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()
# The installer opens on step 1; advance to the AI step.
state = self._goto_step(3)
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", "Return, Ctrl+Right twice", "AI connection step")
self.shot("gi-01-ai", "AI step", "Ctrl+Right to step 3", "AI connection step")
# Select OpenCode and connect through the UI.
for _ in range(OC_TAB_TO_CHIP):
@ -994,8 +1027,7 @@ class Driver:
self.shot("gi-02-ai-reviewed", "AI reviewed", "Accept changes", "review accepted")
# Destination disk: pick the first selectable disk.
self.sendkey("ctrl-right")
time.sleep(3)
self._goto_step(4)
self.sendkey("tab")
time.sleep(0.5)
self.sendkey("ret")
@ -1041,59 +1073,66 @@ class Driver:
f"the disk selection did not survive backtracking: {state}",
)
# Account and encryption.
self.sendkey("ctrl-right")
time.sleep(2)
state = self._frontend_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)
self.results.assert_true("gui-install-account-step", state is not None and state["step"] == 5,
f"account step not reached: {state}")
self._tabs(3) # full name -> username -> computer name -> password
# Focus opens on Username.
self._gui_type(USER_NAME)
self._tabs(1) # -> Computer name
self._gui_type(HOST_NAME)
self._tabs(1) # -> Password
self._gui_type(USER_PW)
self._tabs(2) # reveal -> confirm password
self._tabs(1) # -> 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",
"password and passphrase entered")
"username, computer name and matching password entered")
# Review and ERASE. The review step focuses the ERASE field.
self.sendkey("ctrl-right")
time.sleep(4)
state = self._frontend_state()
# 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)
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, 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
"backend facts and the installation plan")
self.sendkey("ctrl-right") # Install now
started = time.monotonic()
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:
self.results.fail("gui-install-completes", "the wizard did not report completion")
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()})",
)
return
self.results.assert_true(
"gui-install-completes", done["phase"] == "done",
@ -1211,7 +1250,20 @@ 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:
self.child.sendline(LUKS_PW)
# `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
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; "
"sudo -n systemctl is-enabled greetd; "
"systemctl is-enabled greetd; "
"echo ===CHECKS-$(printf END)===",
)
child.sendline(checks)

View file

@ -0,0 +1,56 @@
#!/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

@ -0,0 +1,53 @@
#!/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,12 +1,17 @@
#!/usr/bin/env python3
"""Headless serial driver for the disposable UEFI VM.
Two modes:
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.
@ -44,6 +49,13 @@ 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
@ -112,6 +124,147 @@ 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:
@ -162,7 +315,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"):
if mode not in ("install", "boot", "rollback"):
print(__doc__)
return 2
results = Results(f"serial-{mode}")
@ -181,6 +334,8 @@ 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,5 +223,31 @@ 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)