cabbage/rvbox
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: record provisioned Windows test VM

Browse Source
This commit is contained in:
cabbage
2026-09-09 05:50:47 +00:00
parent 541f050802
commit 2abf0bf19b
4 changed files with 187 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/README.md
+3
View File
@@ -17,6 +17,9 @@ Read the documents in this order:
package boundaries, storage/session/client details, tests, and release gates. package boundaries, storage/session/client details, tests, and release gates.
7. [Implementation testing](testing.md) — container entry points, run 7. [Implementation testing](testing.md) — container entry points, run
lifecycle, exact cleanup, and coverage inventory. 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): The wire authority is in [`../protos/rvbox/v1`](../protos/rvbox/v1):
`common.proto` contains shared data types, `agent.proto` contains the `common.proto` contains shared data types, `agent.proto` contains the
docs/implementation-plan.v1.md
+15 -6
View File
@@ -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 larger Windows release matrix above: it has one active user, no standard-user
fixture, no ambiguous multi-session fixture, and no Server Core variant. 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 | | Item | Value |
| --- | --- | | --- | --- |
| Hypervisor | VirtualBox `7.2.16r174877` on the Arch Linux `helium-remote` host | | 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 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` | | 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 | | 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) | | 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) | | Devices | Audio (`none`), playback/capture, USB (OHCI/EHCI/xHCI), clipboard/file transfer, drag-and-drop, and shared folders disabled; Intel 82540EM NIC, cable connected |
| Guest control | Guest Additions installed and verified (`GuestAdditionsRunLevel=3`) | | 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` |
| 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` | | 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 |
| Baseline | snapshot `baseline-disk-first` (UUID `9430a9a4-754a-4b22-beaa-8dfd90043f5b`), current known-good snapshot; parent `baseline-clean` is retained | | Native Windows RDP | Disabled in baseline (`TermService` stopped, `fDenyTSConnections=1`); port 3390 must not be treated as a usable control endpoint |
| Initial state | VM is normally left powered off; restore the baseline before each destructive run | | 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 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 them in the operator/CI secret store or a mode-600 password file outside the
docs/testing-vm.md
+153
View File
@@ -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).
docs/testing.md
+16 -6
View File
@@ -87,6 +87,16 @@ cleanup.
`test/coverage.toml` is the incremental requirement-to-test inventory. The `test/coverage.toml` is the incremental requirement-to-test inventory. The
`make verify` lint stage checks unique stable IDs and verifies every implemented `make verify` lint stage checks unique stable IDs and verifies every implemented
test reference against source. A resettable Windows smoke VM is now available. 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 The exact headless VirtualBox/Guest Control adapter is
`scripts/windows/test-host.ps1`; it takes the VM name, baseline snapshot, and `scripts/windows/test-host.ps1`; it takes the VM name, baseline snapshot, and
guest identity/password-file only from host environment variables, acquires an 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 `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 minimum smoke lane, so deferred native multi-session/ambiguous-session, Server
Core, and older-build entries remain explicitly blocked until their own Core, and older-build entries remain explicitly blocked until their own
fixtures exist. During the current Windows 10 fixture check, VirtualBox Guest fixtures exist. A previous Windows 10 fixture probe found that VirtualBox Guest
Control 7.2.16 rejected the GUI-subsystem `rvbox.exe` as a directly runnable 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 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 left the Guest Control wrapper waiting. This remains an adapter completion-path
off, but native runtime coverage remains blocked until the host adapter gains a limitation: native runtime coverage needs a service-driven or
GUI-process completion path (or a service-driven guest runner). Wine or a console-compatible guest runner. Wine or a protocol stub is not treated as
protocol stub is not treated as equivalent coverage. equivalent coverage.