|
Some checks are pending
ci / test (push) Waiting to run
- Excised standalone dwl packages: gui-wm/dwl, waybar, wofi, mako, swaybg, swayidle, swaylock - Removed standalone dwl session and helper assets: PHOEBUS_SESSION_SCRIPT, PHOEBUS_MENU_SCRIPT, PHOEBUS_LOCK_SCRIPT, PHOEBUS_IDLE_SCRIPT, WAYBAR_CONFIG, WAYBAR_STYLE, phoebus-dwl.desktop - Consolidated DesktopProfile enum to Mango (default) and None (headless), rejecting legacy dwl configurations - PHOEBUS_MANGO_SESSION_SCRIPT (/usr/local/bin/phoebus-session-mango) fails visibly/diagnostically on error without silent fallback - Provided /usr/local/bin/phoebus-session as a direct wrapper to phoebus-session-mango - Live ISO emitted assets reduced from 24 to 17 and verified clean |
||
|---|---|---|
| .. | ||
| 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 | ||
| 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).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.
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