wireguard-admin/docs/VM_ACCEPTANCE.md

Disposable systemd VM acceptance contract

Status: Milestone 9 is paused at the user's request. The exact disposable VM was powered off after a guarded first start and an installer progress screen; read-only list runningvms was empty afterward. Debian installation completion, guest provisioning, reset, cleanup, and systemd acceptance are unverified.

This contract supplements Testing and Acceptance and the M9 criteria in PLANS.md. Product behavior is governed by SPEC.md, Runtime observation and verification, and ADRs 0001–0003.

Selected target

The selected target is exactly one new VirtualBox VM:

Field	Required value
Provider	Oracle VirtualBox, local VBoxManage 7.2.8_Gentoo
VM name	wga-m9-debian137-20261025
Guest base	Official Debian 13.7.0 (Trixie) amd64 netinst ISO
ISO path	/media/data/wm/Virtualbox/wga-m9-lab/debian-13.7.0-amd64-netinst.iso
ISO SHA-256	a7ef94ac2fb9a7fec454552abd629b7cc9d5155c886165a45649f5ce6167e355
VirtualBox OS type	Debian13_64
Lab root	/media/data/wm/Virtualbox/wga-m9-lab (owner sasa, mode 0700)
Networking	One NAT NIC only, no forwarding; all other NICs disabled
VM UUID	b14c850b-a21e-4a56-acca-785590f0c4ac, pinned in the mode-0600 identity manifest
Guest marker	/etc/wga-m9-lab-marker, exact content wga-m9-debian137-20261025 after provisioning

The ISO is present, has the stated SHA-256, and was obtained from Debian's official amd64 netinst directory. VBoxManage command forms were checked against the local 7.2.8 help and Oracle's VirtualBox 7.2 VBoxManage manual. Read-only VBoxManage unattended detect --iso=... --machine-readable reported OSTypeId=Debian13_64, OSVersion=13.7.0 Trixie, and IsInstallSupported=on, but then exited 1 with NS_ERROR_NOT_IMPLEMENTED. The later bounded unattended install --dry-run --start-vm=none succeeded for this exact VM with private synthetic password files, a fully qualified .invalid hostname, and the local Guest Additions ISO. The dry run made no VM changes; actual unattended preparation and guest boot remain unverified. VirtualBox's dry-run output contains plaintext password fields, so the wrapper suppressed them and displayed only redacted output. Any actual unattended step needs a reviewed exact-target procedure and post-prepare media inspection before start.

The approved read-only inventory outside the sandbox found /dev/vboxdrv available and VBoxManage 7.2.8 working. It initially listed Windows 7 and Windows 11 VMs; neither is a test target or was modified. The create-only run registered only the new Debian target and stopped before configuration. The default sandbox does not expose the host driver/device, so host inventory and later VBoxManage operations must use the approved outside-sandbox path. The guard matches the exact new name/UUID and does not inspect existing VMs' per-VM files.

Guarded host operations

tests/vm/guard.py is a narrow standard-library Python guard, not a general VirtualBox wrapper. Its default check, start, and authorize-guest actions are outside Cargo's default test targets. The guard:

• Requires the exact lab root to be a real directory owned by the current user with mode 0700, and target-identity.json to be a regular current-user file with mode 0600.
• Requires the manifest to pin the exact VM name, current owner UID, one valid UUID, and host marker <VM name>:<UUID>.
• Uses VBoxManage list vms to require that exact name occur once with the pinned UUID, then showvminfo <UUID> --machinereadable to compare UUID/name/marker.
• Requires the VM configuration and its one VDI to reside below the lab root, the VDI to be named exactly wga-m9-debian137-20261025.vdi, and any mounted installer ISO to be the pinned Debian ISO in that root.
• Requires a complete inventory of all eight NIC slots, with only NIC 1 in NAT mode. NAT forwarding and all VirtualBox shared folders are refused.
• Performs every identity, path, and isolation check before startvm. A missing, duplicate, malformed, or mismatched identity fails closed. The only start target is the pinned UUID, in the GUI frontend for console installation.
• Before guest authorization, repeats all host checks, requires a current-user password file with mode 0600, and reads only the guest marker via VBoxManage guestcontrol ... run /usr/bin/cat with --wait-stdout and a 15-second guest process timeout. Host stdout/stderr capture is also capped at 1 MiB while the process runs. The password is supplied using --passwordfile; it is never placed in argv. Marker output is compared exactly and is not echoed. This read is unprivileged inside the guest.

The host marker is a pre-install bootstrap identity: it binds the created VirtualBox object and protected manifest before the first start. It is not proof of guest identity. The guest marker is installed only after Debian setup and is checked separately after boot. Do not perform root provisioning, run application acceptance, or access the guest system bus until authorize-guest succeeds for the exact UUID. The guest marker check is deliberately read-only; it does not grant the caller a general guest command runner.

The exact current focused checks are:

python3 -m unittest discover -s tests/vm -p 'test_*.py' -v
python3 -m py_compile tests/vm/guard.py tests/vm/test_guard.py
git diff --check

They use a temporary synthetic VM inventory and fake VBoxManage responses. They do not call VBoxManage, start a guest, contact a host service, or read any registered VM configuration. The behavioral cases cover normal exact identity, missing/duplicate/wrong UUID, wrong name, manifest/root permissions, storage escape, NIC mode and incomplete inventory, NAT forwarding, shared folders, host/guest marker mismatch, no startvm on refusal, and exact UUID start scope.

The guard supports these later commands once the selected VM has been created, its manifest and marker have been recorded, and the coordinator has reviewed the mutation step:

python3 tests/vm/guard.py check
python3 tests/vm/guard.py start
python3 tests/vm/guard.py authorize-guest --password-file /path/to/private/guest-password

The placeholder password path above must name a private file owned by the current user with mode 0600. Do not put a password value in the command line, environment, terminal history, or output. The start command is an implemented guarded operation but has not been run. Running it requires the approved outside-sandbox path because the default sandbox does not expose the host VirtualBox device.

Create-only procedure (ran once; do not rerun)

tests/vm/create.py exposes only the fixed create operation; it accepts no target, path, or action override. After confirming the lab root owner/mode, exact ISO digest, absence of both the identity manifest and the exact target VM path (using lstat, so dangling symlinks also count as occupied), and a well-formed VirtualBox inventory without the selected name, it issues bounded VBoxManage calls to:

1. Register wga-m9-debian137-20261025 as Debian13_64 below the lab root.
2. Configure 1024 MiB RAM, one CPU, NIC 1 in NAT mode, NICs 2–8 disabled, audio disabled, USB disabled, and DVD then disk boot order.
3. Create one dynamically allocated standard 8192 MiB VDI, attach it on SATA port 0, and attach the pinned Debian ISO on SATA port 1.
4. Write the actual VM UUID and <name>:<UUID> host marker in target-identity.json with mode 0600, set the same marker as the VirtualBox description, then run the existing read-only host guard.

Run this exact command only after coordinator review of the current host state and the scoped mutations:

python3 tests/vm/create.py

The command must run through the approved outside-sandbox path because the default sandbox cannot access the VirtualBox host driver. Its effects are VM registration, storage/network/device/boot configuration, ISO attachment, and the protected host identity manifest. It does not start the VM, install Debian, use guest control, create snapshots, or delete/clean up resources. VBoxManage calls have 30-second timeouts and 1 MiB per-stream output limits. Errors omit VBoxManage output; after registration they report the exact target name and known UUID. A failed procedure retains any partial target and its identity for inspection; it performs no automatic rollback or broad cleanup. The final guard must pass before the script reports success. The first run registered the UUID above, then stopped when strict parsing rejected VirtualBox's indented rec_screen0 recording marker. The parser was narrowly repaired and independently re-reviewed. The target path is now occupied, so create.py must not be rerun; use the reviewed resume procedure below.

Resume the registered partial target (ran once; do not rerun)

The earlier create attempt registered the selected target before stopping at the initial machine-readable parse. The exact retained target is wga-m9-debian137-20261025 with UUID b14c850b-a21e-4a56-acca-785590f0c4ac; it is powered off and has only its .vbox configuration file. Its observed NIC inventory was NIC 1 in NAT with NICs 2–8 disabled. It had no identity manifest or VDI. That prior state was the sole input accepted by tests/vm/resume.py.

The resume-only procedure is fixed to that UUID and lab root. Before its first mutation it checks the private root, exact pinned ISO path and SHA-256, absent manifest and target VDI, unique registered name/UUID identity, exact .vbox path, powered-off state, empty host description, default memory/CPU settings, the observed NIC inventory (NIC 1 in NAT and NICs 2–8 disabled), no attached media or storage controller, no shared folders, and no NAT forwarding. It refuses an unexpected adapter or preexisting state. After preflight it configures memory/CPU, NAT-only networking, disabled audio and USB, boot order, one standard 8192 MiB VDI, and the pinned ISO; then it writes the protected host manifest, sets the host marker, and runs the existing read-only guard. It does not create, start, unregister, delete, or clean up a VM. A failure after mutation retains the exact target and reports its pinned UUID for inspection; no rollback is attempted.

The focused command is:

python3 -m unittest discover -s tests/vm -p 'test_resume.py' -v

It uses only a temporary synthetic lab and fake VBoxManage responses. It does not call VBoxManage or establish host/VM evidence. The implementation command was python3 tests/vm/resume.py; it ran once via the approved outside-sandbox path. It configured the exact target and wrote the host marker/manifest. Its final guard call initially refused observed VirtualBox storage metadata; focused repairs and independent re-review closed those parser and guard findings. A subsequent read-only python3 tests/vm/guard.py check passed against the actual powered-off target. Do not rerun the resume command on this occupied state.

Do not infer unregistervm --delete, snapshot restore, guest-control, or broad cleanup commands from the CLI help. No provisioning command is documented because Debian installation, Guest Additions/management channel, the unprivileged wga account, and guest marker placement have not been validated. No reset or deletion command is documented because a baseline snapshot and exact owned resource IDs do not yet exist. Existing registered VMs must remain untouched.

Unattended preparation (ran once; do not rerun)

tests/vm/install_prepare.py is pinned to the VM UUID above and accepts no target, path, credential, or action overrides. It first checks the current user's /tmp/wga-m9-private directory is a real mode 0700 directory and its nonempty wga-password and root-password files are current-user-owned regular mode-0600 files. These are synthetic install credentials only; password contents never enter argv or output. It verifies the pinned Debian ISO and /usr/share/virtualbox/VBoxGuestAdditions.iso SHA-256 digests, then calls the existing exact-target read-only guard and additionally requires the VM to be powered off, with the expected VDI at SATA-0-0, the pinned installer ISO at SATA-1-0, and every other reported SATA attachment slot set to none or emptydrive. This accepts VirtualBox 7.2.8's real showvminfo inventory (SATA-2-0 through SATA-29-0 are none) while rejecting any additional attached media. It refuses before mutation if any check fails.

The script runs a bounded VBoxManage unattended install <pinned UUID> dry run first with --iso=<pinned Debian ISO> and --admin-password-file=/tmp/wga-m9-private/root-password, using the synthetic wga account and password file, .invalid FQDN, en_US, UTC, US country, minimal package adjustment, and the pinned Guest Additions ISO. The root credential option is --admin-password-file; --root-password-file is not a valid option for the local VBoxManage 7.2.8. Only a successful dry run permits the same bounded command without --dry-run. Both commands request --start-vm=none; the script has no start, cleanup, or retry operation. VBoxManage output is captured privately because its dry-run output contains plaintext password fields; errors and status output omit captured text. The command has a 120-second deadline and 1 MiB per-stream capture limit.

After independent review, the command ran once through the approved outside-sandbox VBoxManage path:

python3 tests/vm/install_prepare.py

The command exited 0 and left the VM powered off. Read-only showvminfo inspection found the exact VDI at SATA 0 and a VirtualBox-generated auxiliary .viso at SATA 1, both in the private target folder. The generated installer files are mode 0600; the target folder is mode 0700. The normal host guard refuses the .viso, as designed, so the first start requires a separate guard for this exact installer state and independent review. Do not rerun preparation on the occupied state. Guest boot, Guest Additions setup, and guest provisioning are not established by this result or the synthetic tests.

The focused behavioral tests use only temporary synthetic files and a fake VBoxManage runner:

python3 -m unittest discover -s tests/vm -p 'test_install_prepare.py' -v

First start of the prepared installer (ran once; VM stopped)

tests/vm/install_boot.py adds a separate, fixed-target check/start command for the one powered-off installer state. The ordinary guard.py deliberately continues to reject the generated .viso; this installer guard does not loosen that normal guard. It reuses the strict machine-readable parser and checks the exact current-user-owned mode-0600 identity manifest, pinned UUID and matching host description, exact target name/configuration path, and current-user-owned mode-0700 target folder. It requires the VDI at SATA 0 and exactly Unattended-b14c850b-a21e-4a56-acca-785590f0c4ac-aux-iso.viso at SATA 1; SATA ports 2–29 must all be none. The .viso and any generated isolinux/preseed/postinstall files are checked as current-user-owned mode-0600 regular files with exactly one hard link. The VM configuration and VDI are also required to be regular current-user-owned files with exactly one hard link. The guard never opens or prints installer-file contents. The VM must remain powered off during preflight, have only NIC 1 in NAT mode, and have no forwarding rules or shared folders. Symlinked paths, extra media, unknown attachment metadata, and incomplete or mismatched identity refuse before start.

The exact commands are:

python3 tests/vm/install_boot.py check
python3 tests/vm/install_boot.py start

check only reads the protected manifest, filesystem metadata, and bounded VirtualBox inventory; it does not change VM state. start repeats all checks, then issues only VBoxManage startvm b14c850b-a21e-4a56-acca-785590f0c4ac --type=headless. It accepts no UUID, root, media, credential, or action override. Each VBoxManage call uses the existing guard's 15-second deadline and 1 MiB per-stream output cap. Output is not copied into errors. If the start call fails or times out, the result explicitly says the VM may have started and requires a separate read-only inspection; there is no retry, cleanup, or rollback. A successful command means only that VirtualBox accepted the start request. It does not prove guest boot, Debian installation, or Guest Additions.

Focused fake-runner coverage is:

python3 -m unittest discover -s tests/vm -p 'test_install_boot.py' -v

These tests create synthetic private files and never call VBoxManage. Both commands ran once against the actual VM after independent review. check passed; start returned success; VirtualBox listed only the pinned target as running. A private console screenshot showed Debian's base-system installer at 6%. The user then stopped Milestone 9, so the exact target was powered off and read-only list runningvms returned no running VMs. Do not restart it without a new explicit request. Installation completion and guest boot remain unverified.

After installation, provision only synthetic lab packages, fixed reviewed service units, synthetic WireGuard keys/configuration, and the guest-local marker. Keep all server/client data, outputs, and working backups under a guest-only root-owned 0700 directory; secret files are 0600. The guest-local marker must be readable by the unprivileged wga account for the read-only marker gate. This work belongs to the next task after target creation and guard review; it is not claimed as implemented here.

Isolation and acceptance boundary

• Use synthetic server/client keys, configuration, settings, and vault contents generated inside the guest. Preserve imported originals. Do not copy or read production keys, configuration, backups, or credentials.
• The VM may have only one NAT management adapter, with no forwarding rules; do not use bridged, host-only, internal, NAT-network, USB network, or physical adapters. NAT-only VM egress still traverses the host's ordinary network; do not claim host-independent network isolation. No host D-Bus, /etc, /run, /var, WireGuard interface, service control, or general shared folder may be mounted or forwarded into the guest.
• A guest system D-Bus and PID 1 must be guest-local. Keep console management independent of the VPN under test. Tunnel probes target only synthetic addresses reachable through the test tunnel, never the NAT management path.
• Provision only fixed, reviewed lab units/drop-ins and fixture hooks. Imported configuration text remains data. Preserve administrator settings and prove preflight refusal using synthetic fixtures rather than silently rewriting SaveConfig.
• Exercise the public Application::restart flow with the real zbus service adapter and Rustix observer. A test seam may inject persistence failures only where already established; it may not replace service submission or runtime observation as evidence of systemd behavior. Alpine fixture apply remains separate evidence.
• Run the actual release executable separately from any cfg(test) driver. Capture source/dirty identity, compiler/locked dependencies, target, artifact SHA-256, and dynamic-library requirements for both artifacts. Prove each executable starts in the guest.
• Keep secrets out of argv, environment variables, image metadata, logs, transcripts, and evidence. Use bounded typed control, private files/channels, monotonic timeouts, and bounded output. A timeout after service submission means it may still complete; it is not cancellation.
• Before every scenario, reset to a recorded clean guest state and verify both the pinned host identity and guest marker. Afterward, stop only resources created by that run and verify their exact IDs. If cleanup is uncertain, preserve IDs and report them; never use broad host cleanup. Preserve the original failure if cleanup also fails.

Required scenario evidence

For every run, record UTC start/end, guest and base identities, kernel/systemd/ D-Bus/WireGuard versions, both marker results, source/artifact identities, exact commands, exit status and bounded redacted outcomes, backup/archive identities, reset/cleanup result, and the acceptance criteria supported. Keep raw console output private; evidence must contain no secrets or complete client config. Record each scenario independently so failures cannot be masked by unrelated fixture behavior.

Scenario	Required observable evidence
Successful apply and fast job	Existing synthetic client has positive tunnel-only IPv4 traffic. Through one Application, create and Commit a client; show saved/runtime divergence and that Commit did not submit a service job. Cancel preview with no backup/job/mutation. Confirm restart: pre-restart backup completes first, real zbus job for the resolved primary unit reaches done, Rustix observes the expected interface and complete matching peer/routes, and durable verification is written. Verify new tunnel traffic, reopen and show verification is historical. Repeat with fast completion and a configured alias resolving to the primary unit; retain the completion signal. Include application outcomes, not journal inference alone.
Deletion and reservations	Establish positive traffic before deleting/Committing. Show the client remains in runtime and its address remains reserved until successful real restart and complete verification. Then show it absent, tunnel-only traffic fails within a bounded probe, durable reservation releases, and old backups remain.
Failure and deadline	Using fixed guest-only units/drop-ins, show terminal job failure and submitted-job deadline expiry with bounded results, accurate submitted/may-still-complete status, no automatic retry/rollback, no false Verified state, and retained reservations. Also show unresolved unit fails before submission and backup failure prevents restart. After late completion, explicitly observe and reset the guest; timeout is not cancellation.
Job succeeds, verification fails	A dedicated fixed fixture service completes while leaving the interface absent or peers mismatched. Show the real adapter reports verification failure and reservations remain. Separately inject saved-state write failure only through the established persistence seam after real restart/observation; show runtime changed without durable Verified state and RecoveryRequired blocks unsafe mutations.
Restore and manual recovery	Preview and confirm a known-good archive without vault password. Show precautionary backup, full saved settings/config/vault replacement, and unchanged runtime before explicit restart. Then run real restart/verification and expected tunnel check. Demonstrate documented manual recovery; no hidden rollback. Confirm permissions and reopen behavior.
Release executable smoke	In guest console/PTY, prove identified release binary starts from its private directory and settings resolve beside it. Exercise current-client/statistics view and one controlled Commit/restart through the real worker path; confirm exit/cancel restores terminal. Help/version work as non-root without settings; non-root management is rejected. Record output/backup permissions.

The final M9 evidence must map these observations to M9-A1–A9 and the specification-to-evidence matrix. State the tested scope, including IPv4 tunnel coverage, synthetic dual-stack tests, unverified real IPv6 behavior, and QR/device interoperability limits. A mocked bus, Alpine fixture apply, missing prerequisite, skipped test, or guest boot alone does not satisfy real systemd acceptance.

Next action

None while Milestone 9 is paused by the user. The disposable VM is powered off; do not resume installation, provision it, or run acceptance without a new explicit request. No M9-A1–A9 check is complete.