docs: record provisioned Windows test VM
This commit is contained in:
@@ -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).
|
||||
Reference in New Issue
Block a user