test: add temporary Guacamole fixture access helper

2026-09-09 09:00:06 +00:00
parent 7e82f2c26f
commit 8985457d37
10 changed files with 506 additions and 0 deletions
@@ -0,0 +1,118 @@
+# Interactive Windows VM access
+
+This directory is an explicitly temporary, manual-recovery path to the Helium
+Windows fixture desktop. It is for the small class of actions that require an
+interactive UAC consent dialog. Normal setup, testing, collection, and reset
+remain `scripts/windows/test-host` plus VirtualBox Guest Control.
+
+The helper builds this private path:
+
+```text
+browser -- HTTPS/self-signed --> nginx + Guacamole containers
+                                      |
+                                 private Docker gateway
+                                      |
+controller SSH tunnel --> Helium 127.0.0.1:3389 --> VirtualBox VRDE --> VM console
+```
+
+Only the HTTPS listener can be made public, and that requires an explicit
+`--bind 0.0.0.0`. The VirtualBox VRDE endpoint stays on Helium loopback and the
+SSH tunnel binds only to the Docker network gateway; neither is publicly
+exposed. Guacamole requires the fixture login before it forwards the entered
+password to the VM. Clipboard, drives, printing, audio, microphone input, GFX,
+and display-resize extensions are disabled because the fixture's VirtualBox
+RDP4 server does not handle them reliably.
+
+## Lifecycle
+
+Run commands from the repository root. First prepare the disposable VM using a
+dedicated run ID. This restores the snapshot, starts the VM headlessly, and
+holds the exclusive fixture lease while the manual action is in progress:
+
+```sh
+scripts/windows/test-host prepare --run-id interactive-rdp
+```
+
+For browser access from another machine, deliberately expose the temporary
+HTTPS listener and name the host or IP users will enter in the browser:
+
+```sh
+test/rdp-access/rdp-access up \
+  --bind 0.0.0.0 \
+  --public-host x1.example.net
+```
+
+The command prompts without echo for the fixture password. It stores only its
+MD5 verifier in `test/rdp-access/.runtime/config/user-mapping.xml`, mode 600;
+the plaintext password is not placed in a command line, environment variable,
+log, or repository file. Browse to the printed `https://.../guacamole/` URL,
+accept the short-lived self-signed certificate warning, and sign in as
+`rvboxtest` with the fixture password.
+
+For localhost-only use, omit `--bind` and `--public-host`. The default listener
+is `127.0.0.1:5002`; use a local SSH forward or a browser on the controller.
+Choose alternate ports with `--http-port` and `--tunnel-port` if either is in
+use. The VM must already be running. `up` checks the documented VM/snapshot
+identity but intentionally does not restore, start, stop, or reset the VM.
+
+All fixture-specific values have embedded, working defaults: the
+`helium-remote` SSH alias, Helium's loopback VRDE endpoint (`127.0.0.1:3389`),
+`rvboxtest`, the browser listener (`127.0.0.1:5002`), and the private tunnel
+port (`54001`). They can be overridden without editing tracked files through
+`RVBOX_TEST_VBOX_HOST`, `RDP_ACCESS_VRDE_HOST`, `RDP_ACCESS_VRDE_PORT`,
+`RDP_ACCESS_WEB_USER`, `RDP_ACCESS_RDP_USER`, `RDP_ACCESS_BIND`,
+`RDP_ACCESS_HTTP_PORT`, `RDP_ACCESS_TUNNEL_PORT`, and
+`RDP_ACCESS_PUBLIC_HOST`. The helper deliberately limits the VRDE host to
+Helium loopback (`127.0.0.1` or `localhost`) so an override cannot accidentally
+turn the diagnostic server into a remote target.
+
+After the interactive action, close the browser connection and remove the
+temporary access path before releasing the fixture lease:
+
+```sh
+test/rdp-access/rdp-access down
+scripts/windows/test-host reset --run-id interactive-rdp
+```
+
+`down` stops containers and the SSH master/tunnel but retains the one-day
+certificate and password verifier for a quick restart. To remove all generated
+state, including the certificate and verifier:
+
+```sh
+test/rdp-access/rdp-access clean
+```
+
+To also reclaim the exact Guacamole and nginx images when they have no
+container dependency, use:
+
+```sh
+test/rdp-access/rdp-access clean --images
+```
+
+`clean --images` deliberately leaves `alpine:3.20` alone because it may be
+shared by unrelated containers. Docker will refuse removal if any other
+container still depends on an image.
+
+## Operational checks and recovery
+
+```sh
+test/rdp-access/rdp-access status
+test/rdp-access/rdp-access logs --tail=100
+test/rdp-access/rdp-access url
+```
+
+If the browser reaches Guacamole but stays on “Waiting for response”, verify
+that the VM is running and the private tunnel is active with `status`. This
+helper already uses `security=rdp` and disables Guacamole's GFX extension,
+which are required by the fixture's legacy VRDE server. Do not switch the
+helper to native Windows RDP: `TermService` is intentionally disabled in the
+baseline. If VRDE remains unusable, stop this helper and use Guest Control for
+the deterministic portion of the work; record the blocked interactive step in
+the native test report.
+
+The helper requires Docker/Docker Compose, SSH access through the existing
+`helium-remote` alias, and the fixture password file documented in
+[`docs/testing-vm.md`](../../docs/testing-vm.md). It does not install host
+packages, write credentials into Git, or alter VM settings. The tracked files
+are Docker-only configuration and the controller script; all generated content
+is ignored beneath `.runtime/`.