From 2abf0bf19bea6adf8e05aad621a5824302760824 Mon Sep 17 00:00:00 2001 From: cabbage Date: Wed, 9 Sep 2026 05:50:47 +0000 Subject: [PATCH] docs: record provisioned Windows test VM --- docs/README.md | 3 + docs/implementation-plan.v1.md | 21 +++-- docs/testing-vm.md | 153 +++++++++++++++++++++++++++++++++ docs/testing.md | 22 +++-- 4 files changed, 187 insertions(+), 12 deletions(-) create mode 100644 docs/testing-vm.md diff --git a/docs/README.md b/docs/README.md index 23536ec..b7ea2d4 100644 --- a/docs/README.md +++ b/docs/README.md @@ -17,6 +17,9 @@ Read the documents in this order: package boundaries, storage/session/client details, tests, and release gates. 7. [Implementation testing](testing.md) — container entry points, run lifecycle, exact cleanup, and coverage inventory. +8. [Provisioned Windows test VM](testing-vm.md) — exact fixture identity, + host/guest access, endpoints, snapshots, credentials contract, reset + procedure, and known limitations. The wire authority is in [`../protos/rvbox/v1`](../protos/rvbox/v1): `common.proto` contains shared data types, `agent.proto` contains the diff --git a/docs/implementation-plan.v1.md b/docs/implementation-plan.v1.md index 33c4512..04f0df5 100644 --- a/docs/implementation-plan.v1.md +++ b/docs/implementation-plan.v1.md @@ -775,19 +775,28 @@ work. It is deliberately a minimum smoke lane, not a replacement for the larger Windows release matrix above: it has one active user, no standard-user fixture, no ambiguous multi-session fixture, and no Server Core variant. +The full fixture record, including the exact endpoint, device, snapshot, +credential-file, and reset contracts, is maintained in +[testing-vm.md](testing-vm.md). The table below is the implementation-plan +mirror; update both documents when the fixture is reprovisioned. + | Item | Value | | --- | --- | | Hypervisor | VirtualBox `7.2.16r174877` on the Arch Linux `helium-remote` host | +| Host access | SSH alias `helium-remote` (`192.168.50.162`), host user `cabbage`; lifecycle commands execute on this host | | VM name / UUID | `rvbox-win10-test` / `6cdc114f-71e5-4167-a394-e922e14e6f5c` | | VM group / config | `/RVBox/Tests`; `/home/cabbage/VirtualBox VMs/RVBox/Tests/rvbox-win10-test/rvbox-win10-test.vbox` | | Guest OS | Windows 10 Pro 22H2, build `19045.2006`, en-US, BIOS boot | -| Resources | 2 vCPU, 4096 MiB RAM, 32 MiB VRAM, 40 GiB dynamically allocated VDI | +| Guest Additions | `7.2.16r174877`; Guest Control readiness requires `GuestAdditionsRunLevel=3` | +| Resources | 2 vCPU, 4096 MiB RAM, 64 MiB VRAM, `VBoxSVGA`, 3D acceleration disabled, 40 GiB dynamically allocated VDI | | Disk / source media | `/home/cabbage/VMs/rvbox-win10-test.vdi`; source ISO `/media/Data2/Downloaded/Win10_22H2_English_x64.iso` (Windows image index 6) | -| Devices/network | NAT NIC; audio, USB, 3D, clipboard, drag-and-drop, and VRDE disabled; last observed guest IPv4 was `10.0.2.15` (DHCP observation only, never a management identity) | -| Guest control | Guest Additions installed and verified (`GuestAdditionsRunLevel=3`) | -| Test account | local `rvboxtest`; one active console session (session 1); split-token local administrator; Guest Control was verified with `whoami`, `whoami /groups`, and `query user` | -| Baseline | snapshot `baseline-disk-first` (UUID `9430a9a4-754a-4b22-beaa-8dfd90043f5b`), current known-good snapshot; parent `baseline-clean` is retained | -| Initial state | VM is normally left powered off; restore the baseline before each destructive run | +| Devices | Audio (`none`), playback/capture, USB (OHCI/EHCI/xHCI), clipboard/file transfer, drag-and-drop, and shared folders disabled; Intel 82540EM NIC, cable connected | +| Network | NAT; last observed guest IPv4 `10.0.2.15` is DHCP state only; NAT rule `rvbox-rdp` maps host `192.168.50.162:3390` to guest `:3389` | +| Diagnostic VRDE | Enabled at `192.168.50.162:3389`, external/`VBoxAuthSimple` authentication, input/display enabled, audio/USB/clipboard/RDPDR disabled; diagnostic-only because client compatibility is unreliable | +| Native Windows RDP | Disabled in baseline (`TermService` stopped, `fDenyTSConnections=1`); port 3390 must not be treated as a usable control endpoint | +| Test account | Local `rvboxtest`; split-token local administrator; console session 1 observed; Guest Control verified with `whoami`, `whoami /groups`, and `query user` | +| Baseline | `baseline-clean` (UUID `5e79176a-3e56-4c5d-bb61-a405a6dcdd59`) and child `baseline-disk-first` (UUID `9430a9a4-754a-4b22-beaa-8dfd90043f5b`); both are clean and must be retained | +| Last checked state | `poweroff`, current snapshot `baseline-disk-first`; the harness must re-check state and leave the VM powered off after cleanup | The guest password, SSH key, and any host account secret are test secrets. Keep them in the operator/CI secret store or a mode-600 password file outside the diff --git a/docs/testing-vm.md b/docs/testing-vm.md new file mode 100644 index 0000000..823aa2a --- /dev/null +++ b/docs/testing-vm.md @@ -0,0 +1,153 @@ +# Provisioned Windows test VM + +This page is the authoritative record for the resettable Windows smoke fixture. +It describes the machine that is available today; it is not the complete +Windows release matrix. Keep the values here in sync with the VM before adding +or changing native test automation. + +Last configuration check: 2026-09-09 UTC. The VM was observed powered off with +`baseline-disk-first` selected. A test run must still perform its own identity, +snapshot, readiness, and exclusive-lease checks rather than relying on that +observation. + +## Identity and access + +| Item | Value | +| --- | --- | +| Test VM | `rvbox-win10-test` | +| VM UUID | `6cdc114f-71e5-4167-a394-e922e14e6f5c` | +| VM group | `/RVBox/Tests` | +| VirtualBox host | SSH alias `helium-remote`; host address `192.168.50.162`; host user `cabbage` | +| Host platform | Arch Linux; kernel `7.2.2-arch1-1`; VirtualBox `7.2.16r174877` | +| VM configuration | `/home/cabbage/VirtualBox VMs/RVBox/Tests/rvbox-win10-test/rvbox-win10-test.vbox` | +| VM logs | `/home/cabbage/VirtualBox VMs/RVBox/Tests/rvbox-win10-test/Logs` | +| Snapshot folder | `/home/cabbage/VirtualBox VMs/RVBox/Tests/rvbox-win10-test/Snapshots` | +| Guest OS | Windows 10 Pro 22H2, build `19045.2006`, en-US, BIOS boot | +| Guest account | Local `rvboxtest`; split-token local administrator; console session 1 was observed during provisioning | +| Guest Additions | `7.2.16r174877`; Guest Control readiness requires `GuestAdditionsRunLevel=3` | +| Last observed state | `poweroff`; current snapshot `baseline-disk-first` | + +The Guest Control credential is test-only. The account name is safe to record, +but the password value is intentionally not committed to this repository. On +the Helium host, the approved password-file location is: + +```text +/home/cabbage/.local/share/rvbox-secrets/rvbox-win10-test.password +``` + +The file must be mode `0600` and must be supplied with VirtualBox +`--passwordfile`. Agents and CI must obtain the value through the operator's +test secret store or this host-only file; never put the password in a command +line, run manifest, log, artifact, or checked-in document. The SSH key and the +Helium host account credential follow the same rule. + +## Hardware and device profile + +| Item | Value | +| --- | --- | +| Memory / CPUs | 4096 MiB RAM; 2 vCPUs; 100% execution cap; host CPU profile | +| Display | `VBoxSVGA`; 64 MiB VRAM; 3D acceleration disabled | +| Firmware / boot | BIOS; disk first, DVD second; install media is detached after provisioning | +| System disk | 40 GiB dynamically allocated VDI; logical base path `/home/cabbage/VMs/rvbox-win10-test.vdi`; active snapshot differencing disks live under the snapshot folder above | +| Install media | `/media/Data2/Downloaded/Win10_22H2_English_x64.iso`, Windows image index 6 | +| Audio | Virtual audio disabled (`audio=none`, playback and capture off) | +| USB | OHCI, EHCI, and xHCI disabled; no USB filters | +| Clipboard / drag and drop | Disabled, including clipboard file transfers | +| Network adapter | One Intel 82540EM adapter, cable connected, NAT attachment; MAC `080027036E7C` | +| Shared folders | None; there is no shared-folder contract for tests | + +This is a minimum smoke profile (2 vCPU/4 GiB), not the recommended release +host profile. It is suitable for bounded tests and may be too small for long +parallel suites. + +## Network and remote-control endpoints + +The guest address is assigned by VirtualBox NAT/DHCP. `10.0.2.15` was the last +observed guest IPv4 address, but it is not a stable identity and must not be +hard-coded into a harness. + +| Endpoint | Configuration and use | +| --- | --- | +| Host management | SSH to `helium-remote`, then invoke `VBoxManage`; do not assume `VBoxManage` is installed on the Linux controller | +| Guest management | VirtualBox Guest Control over the host; use explicit executable/argument vectors and the password file above | +| VRDE (VirtualBox RDP) | Enabled for diagnostics at `192.168.50.162:3389`; external authentication, `VBoxAuthSimple` user `rvboxtest`, `Security/Method=negotiate`, single connection reuse, multiconnection off | +| VRDE TLS material | Auto-generated certificate and private key under `/home/cabbage/VirtualBox VMs/RVBox/Tests/rvbox-win10-test/`; keep both on Helium and do not copy them into the repository or test artifacts | +| VRDE channels | Input/display enabled; audio, upstream audio, USB, clipboard, and RDP device redirection disabled; no video channel | +| Native Windows RDP forward | NAT rule `rvbox-rdp`: host `192.168.50.162:3390` to guest port `3389` | +| Native Windows RDP state | Disabled in the baseline (`TermService` stopped and `fDenyTSConnections=1`); do not treat port 3390 as usable until a test explicitly enables and later restores it | + +VRDE is not the supported test-control channel. It is retained for bounded +diagnostic probes only: some RDP clients negotiate input capabilities that +VirtualBox 7.2.16 does not handle reliably, and earlier probes included +headless-server crashes. Use Guest Control for deterministic setup, execution, +and collection. Do not expose the VM's RDP endpoints beyond the test LAN. + +## Snapshots and reset contract + +Two clean snapshots exist and must be retained: + +| Snapshot | UUID | Description | +| --- | --- | --- | +| `baseline-clean` | `5e79176a-3e56-4c5d-bb61-a405a6dcdd59` | `baseline-windows10-pro-22h2-rvboxtest-guest-additions` | +| `baseline-disk-first` | `9430a9a4-754a-4b22-beaa-8dfd90043f5b` | `baseline-windows10-pro-22h2-disk-first`; current smoke baseline | + +Restore only while the VM is powered off. Every destructive or potentially +stateful run must: + +1. Acquire the run lease and verify the VM name, UUID, and snapshot UUID. +2. Restore `baseline-disk-first` if the current state is not the baseline. +3. Start headless and wait for `VMState=running` plus Guest Additions readiness. +4. Run the bounded test, collect redacted artifacts, and close every Guest + Control process that was opened by the run. +5. Request a graceful guest shutdown and wait for `VMState=poweroff`. +6. Restore `baseline-disk-first` again and leave the VM powered off. + +Use `controlvm ... poweroff` only for a hung, disposable test; it can lose +guest state. Never delete either clean snapshot, unregister the VM, or alter +the stale unregistered `win10_dev` configuration (its disk is missing). + +## Harness contract + +The checked-in PowerShell adapter is [`scripts/windows/test-host.ps1`](../scripts/windows/test-host.ps1). +Its actions are `Prepare`, `Status`, `Run`, `Collect`, `Stop`, and `Reset`. +The adapter takes identity and credentials only from the host environment: + +```powershell +$env:RVBOX_WINDOWS_VM = 'rvbox-win10-test' +$env:RVBOX_WINDOWS_BASELINE_SNAPSHOT = 'baseline-disk-first' +$env:RVBOX_WINDOWS_GUEST_USER = 'rvboxtest' +$env:RVBOX_WINDOWS_GUEST_PASSWORD_FILE = 'C:\secure\rvbox-win10-test.password' +``` + +The implementation plan also uses the equivalent `RVBOX_TEST_*` names for +controllers that run the lifecycle over SSH: + +```sh +export RVBOX_TEST_VBOX_HOST=helium-remote +export RVBOX_TEST_VBOX_VM=rvbox-win10-test +export RVBOX_TEST_VBOX_SNAPSHOT=baseline-disk-first +export RVBOX_TEST_GUEST_USER=rvboxtest +export RVBOX_TEST_GUEST_PASSWORD_FILE=/home/cabbage/.local/share/rvbox-secrets/rvbox-win10-test.password +``` + +The provisioned lane's backend is SSH plus `VBoxManage` plus Guest Control; it +does not require WinRM, OpenSSH inside Windows, or a stable guest IP. Guest +commands must pass explicit paths and argument vectors. With this VirtualBox +build, `--wait-stdout` and `--wait-stderr` are supported but `--wait-exit` is +not; use `closeprocess` when a process wait cannot complete. For `cmd.exe` +payloads, include `--unquoted-args` so Windows backslashes and the single `/c` +payload are preserved. + +## Scope and known limitations + +This fixture currently provides one active console user and no standard-user, +ambiguous multi-session, Server Core, older-build, or physical hardware +variant. Those release-matrix entries remain deferred; their selector and +fallback unit tests are still required. The GUI-subsystem Guest Control probe +also exposed a completion-path limitation for `rvbox.exe`; native runtime +coverage must use a service-driven/console-compatible runner until that adapter +path is completed. Wine and protocol stubs do not count as Windows coverage. + +For a complete command sequence and lifecycle examples, see the provisioned +lane section in [`implementation-plan.v1.md`](implementation-plan.v1.md) and the +general [testing workflow](testing.md). diff --git a/docs/testing.md b/docs/testing.md index 38d5dc2..1c801f9 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -87,6 +87,16 @@ cleanup. `test/coverage.toml` is the incremental requirement-to-test inventory. The `make verify` lint stage checks unique stable IDs and verifies every implemented test reference against source. A resettable Windows smoke VM is now available. +The authoritative fixture record is +[testing-vm.md](testing-vm.md): it lists the VM/host UUIDs, Windows build, +hardware and device profile, NAT and VRDE endpoints, snapshot UUIDs, +credential-file contract, and the required reset sequence. At the last check +the VM was powered off with `baseline-disk-first` selected. The guest address +`10.0.2.15` is DHCP state only; use SSH plus VirtualBox Guest Control rather +than treating it as a stable endpoint. VRDE is enabled at +`192.168.50.162:3389` for diagnostics, while native Windows RDP is disabled in +the baseline. + The exact headless VirtualBox/Guest Control adapter is `scripts/windows/test-host.ps1`; it takes the VM name, baseline snapshot, and guest identity/password-file only from host environment variables, acquires an @@ -97,10 +107,10 @@ inline password. Use `Prepare`, `Run`, `Collect`, `Stop`, and `Reset` in that order for a native run. The VM is the minimum smoke lane, so deferred native multi-session/ambiguous-session, Server Core, and older-build entries remain explicitly blocked until their own -fixtures exist. During the current Windows 10 fixture check, VirtualBox Guest -Control 7.2.16 rejected the GUI-subsystem `rvbox.exe` as a directly runnable +fixtures exist. A previous Windows 10 fixture probe found that VirtualBox Guest +Control 7.2.16 rejects the GUI-subsystem `rvbox.exe` as a directly runnable guest executable; wrapping it through `cmd.exe` exited the RVBox process but -left the Guest Control wrapper waiting. The VM was restored and left powered -off, but native runtime coverage remains blocked until the host adapter gains a -GUI-process completion path (or a service-driven guest runner). Wine or a -protocol stub is not treated as equivalent coverage. +left the Guest Control wrapper waiting. This remains an adapter completion-path +limitation: native runtime coverage needs a service-driven or +console-compatible guest runner. Wine or a protocol stub is not treated as +equivalent coverage.