The installed boot path is plain unsigned BLS. kernel.uki=true and kernel.secureboot=true are now rejected by validate_config (which the CLI, TUI and GUI bridge all share) with errors naming the limitation. The plan preview reports the real BLS path unconditionally and never renders the requested flags as active. Golden plan updated; parsing, validation and rendering regressions added. |
||
|---|---|---|
| .. | ||
| appliance-driver.py | ||
| appliance-guest-gui.sh | ||
| appliance-guest.sh | ||
| appliance-test.conf.example | ||
| gui-driver.py | ||
| install.sh | ||
| launch-interactive.py | ||
| live-driver.py | ||
| live-sys-install-check.sh | ||
| oc-forward.py | ||
| README.md | ||
| report.py | ||
| rollback-guest.sh | ||
| rollback-verify.sh | ||
| run-vm.sh | ||
| serial-driver.py | ||
| snap-guest.sh | ||
| sys-acceptance.sh | ||
| test.conf.example | ||
| test_vmsafety.py | ||
| vmsafety.py | ||
Disposable UEFI VM harness
Proves that the installer produces a bootable encrypted system without ever touching a physical disk. The target is always a qcow2 file.
Files
run-vm.shinteractive QEMU launcher (manual testing).install.shguest-side, non-interactive installation (run in the VM).serial-driver.pyhost-side pexpect driver (install,bootandrollbackmodes).rollback-guest.sh,rollback-verify.shguest-side rollback acceptance (fetchsys, snapshot, break, undo, verify).snap-guest.shguest-side Snap setup/install/refresh/remove acceptance.test.conf.exampleinstaller configuration used by the driver.
Host prerequisites
qemu-system-x86_64,qemu-img, OVMF firmware, Pythonpexpect.- The reference Gentoo ISO.
- The static Rust installer (the guest never runs the Bash tree):
cd installer-rs
RUSTFLAGS="-C target-feature=+crt-static" \
cargo build --release -p phoebus-installer --target x86_64-unknown-linux-gnu
Procedure
Serve the static installer, the stage3 and the config to the guest:
cd /path/to/serve
cp /path/to/phoebus_os/installer-rs/target/x86_64-unknown-linux-gnu/release/phoebus-installer .
cp /path/to/phoebus_os/installer/tests/vm/install.sh .
cp /path/to/phoebus_os/installer/tests/vm/test.conf.example test.conf # edit TARGET_DISK etc.
sha256sum stage3.tar.xz # set STAGE3_SHA256
python3 -m http.server 8000 --bind 127.0.0.1
Run the installation (driver boots the ISO kernel/initrd directly and drives the serial console):
QEMU_BIN=/path/to/qemu-system-x86_64 \
QEMU_LIBDIR=/path/to/qemu/libs \
QEMU_DATADIR=/path/to/qemu/share \
OVMF_CODE=/path/to/OVMF_CODE_4M.fd \
OVMF_VARS=/path/to/OVMF_VARS.fd \
DISK=/tmp/phoebus/target.qcow2 \
ISO=/path/to/livegui-amd64.iso \
KERNEL=/tmp/live/boot/gentoo INITRD=/tmp/live/boot/gentoo.igz \
INSTALL_URL=http://10.0.2.2:8000/install.sh \
python3 installer/tests/vm/serial-driver.py install
Then boot the disk alone (ISO detached) and verify:
DISK=/tmp/phoebus/target.qcow2 OVMF_CODE=... OVMF_VARS=... \
python3 installer/tests/vm/serial-driver.py boot
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:
- boot the installed disk, unlock LUKS and log in;
- fetch
sysandrollback-guest.shfrom the host (the target does not yet installsys; seedocs/HANDOFF.md), record the/var/db/pkgfingerprint and a/homemarker, create a recovery point withsys snapshot, install a small package (a controlled, reversible update) and runsys undo; - power off, boot the disk detached, and run
rollback-verify.sh, comparing the package fingerprint and the/homemarker, checking kernel modules, and reading the snapshot recovery entry andsys rollback status.
Serve the fixtures as well as the installer:
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.
Snap acceptance on an installed disposable image
Serve the current static sys binary and snap-guest.sh from a small local
directory. Boot an installed qcow2 overlay with serial-driver.py boot,
setting BOOT_AUTHENTICATE=1, BOOT_POWEROFF=1, CHECKS_TIMEOUT=7200,
and the following checks. BOOT_POWEROFF cleanly shuts down the guest after
mutating checks so a later boot observes committed state:
BOOT_REQUIRE_CASES=snap-sys,snap-portage,snap-socket,snap-confinement,snap-install,snap-refresh,snap-remove
BOOT_CHECKS='echo ===CHECKS-$(printf START)===; echo SYSTEMD_STATUS:$(systemctl is-system-running); curl -fsSL http://10.0.2.2:8000/snap-guest.sh -o /tmp/snap-guest.sh; sudo bash /tmp/snap-guest.sh; echo ===CHECKS-$(printf END)==='
The guest script adds only the scoped sys-fs/squashfs-tools lzma lzo USE
setting to the disposable image, then uses sys for the reviewed Portage
install, socket activation and Snap actions. The boot driver logs only guest
output, not the test passwords it sends for LUKS, login and sudo.
Safety (enforced, not just documented)
vmsafety.py validates every writable drive before QEMU starts:
DISK/DISKSmust name qcow2 files inside the disposable directoryPHOEBUS_VM_DISKS(default$PHOEBUS_VM_STATE/disks)./dev/*paths, block and character devices, non-regular files, raw images, symlinks that resolve outside the directory, and disks whose backing chain reaches outside it are refused with a nonzero exit.- Each run gets a private state directory (mode 0700), its own writable OVMF variable file and a unique QMP monitor socket.
- Screenshots use structured QMP and argument arrays; there is no shell
interpolation (
os.system) in the harness. - Secrets are passed through 0600 files and checked for leakage in the installer log by the guest script.
Results
Every driver writes results.json (and a screenshot-manifest.json for the
GUI driver) under its run directory and exits nonzero on any FAIL (and, with
PHOEBUS_VM_STRICT=1, on BLOCKED/NOT RUN). Statuses are PASS, FAIL,
BLOCKED, SKIPPED and NOT RUN; a timeout is always a FAIL, never a pass.
make test-vm # unit-test the safety and result logic (no VM needed)
PHOEBUS_VM_DISKS=/var/tmp/phoebus-vm/disks \
OVMF_CODE=/usr/share/OVMF/OVMF_CODE_4M.fd \
OVMF_VARS=/usr/share/OVMF/OVMF_VARS_4M.fd \
DISK=/var/tmp/phoebus-vm/disks/target.qcow2 \
ISO=installer/live/phoebus-installer-amd64.iso \
python3 installer/tests/vm/gui-driver.py gui