From e3aadd8dd6f3fb47d568df79bec0d011558a3f22 Mon Sep 17 00:00:00 2001 From: cabbage Date: Mon, 14 Sep 2026 07:07:23 +0000 Subject: [PATCH] docs: make RDP fixture management self-service --- scripts/windows/test-host | 4 +- test/rdp-access/README.md | 90 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 92 insertions(+), 2 deletions(-) diff --git a/scripts/windows/test-host b/scripts/windows/test-host index 48ed497..97bba33 100755 --- a/scripts/windows/test-host +++ b/scripts/windows/test-host @@ -20,7 +20,7 @@ Actions: stage copy a bundle containing rvbox.exe and client.toml into the guest test root install install and start RVBox from the staged bundle through a fixture-only full-admin principal run start the already-installed RVBox SCM service from the staged bundle - logoff log off the sole active fixture user; use only after service installation + logoff log off the sole active fixture user; use only after service installation collect copy bounded guest artifacts to the local test-run directory inspect read-only RVBox SCM state and bounded client log from a prepared run logs read-only service-startup and client logs from a prepared run @@ -82,7 +82,7 @@ while [ "$#" -gt 0 ]; do --run-id) [ "$#" -ge 2 ] || fail "--run-id needs a value"; run_id=$2; shift 2 ;; --bundle) [ "$#" -ge 2 ] || fail "--bundle needs a value"; bundle=$2; shift 2 ;; --endpoint) [ "$#" -ge 2 ] || fail "--endpoint needs a value"; endpoint=$2; shift 2 ;; - --fail-contexts) [ "$#" -ge 2 ] || fail "--fail-contexts needs a value"; fail_contexts=$2; shift 2 ;; + --fail-contexts) [ "$#" -ge 2 ] || fail "--fail-contexts needs a value"; fail_contexts=$2; shift 2 ;; --help|-h) usage; exit 0 ;; *) fail "unknown argument $1" ;; esac diff --git a/test/rdp-access/README.md b/test/rdp-access/README.md index ec46c88..c53dcb0 100644 --- a/test/rdp-access/README.md +++ b/test/rdp-access/README.md @@ -24,6 +24,63 @@ 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. +## Current fixture quick start + +The following is the copy/paste path for the documented `rvbox-win10-test` +fixture. Run it from the repository root. The first command acquires the +exclusive VM lease, restores the clean administrator-enabled snapshot, starts +the VM, and applies the VRDE display keepalive. The second command starts the +Docker-only gateway at the currently published endpoint: + +```sh +scripts/windows/test-host prepare --run-id interactive-rdp +test/rdp-access/rdp-access up \ + --bind 0.0.0.0 \ + --public-host x1.xcel.me +``` + +`up` prompts for the fixture password. If the password is not already in the +operator's secure notes, the test-only value is available only in the Helium +host's mode-600 file documented in [`docs/testing-vm.md`](../../docs/testing-vm.md). +For an unattended first start, pass that file through the existing SSH alias +without putting the value in an argument, environment variable, or log: + +```sh +ssh helium-remote 'cat /home/cabbage/.local/share/rvbox-secrets/rvbox-win10-test.password' | + test/rdp-access/rdp-access up \ + --bind 0.0.0.0 \ + --public-host x1.xcel.me \ + --web-password-stdin +``` + +The browser URL is `https://x1.xcel.me:5002/guacamole/`; accept the temporary +self-signed certificate warning and sign in as `rvboxtest`. The same command +is safe to rerun after a tunnel interruption. If the stack is already running, +`up` reuses it and repairs only missing forwarding; it does not consume stdin. +Use `--reset-auth` only after `down` when intentionally replacing the saved +verifier, for example: + +```sh +test/rdp-access/rdp-access down +ssh helium-remote 'cat /home/cabbage/.local/share/rvbox-secrets/rvbox-win10-test.password' | + test/rdp-access/rdp-access up \ + --bind 0.0.0.0 \ + --public-host x1.xcel.me \ + --reset-auth \ + --web-password-stdin +``` + +Do not run `clean` or `test-host reset` while another agent owns the fixture +lease or has a live browser session. The generated verifier, certificate, +tunnel state, and logs are disposable and live only under the ignored +`test/rdp-access/.runtime/` directory. + +Before a first `prepare`, run `scripts/windows/test-host status`. If it reports +`state=running`, another run may already own the fixture lease; do not restore +or reset it. Reuse that run's access path or coordinate with its owner. If it +reports `state=poweroff`, the quick-start sequence above is safe. The helper +does not guess at ownership or silently take over a running VM. + ## Lifecycle Run commands from the repository root. First prepare the disposable VM using a @@ -160,6 +217,39 @@ test/rdp-access/rdp-access repair forward, and does not alter the Windows guest. Close old browser tabs and sign in again after it completes. +For quick recovery, use this decision table: + +| Need | Command | Effect | +| --- | --- | --- | +| Inspect everything | `test/rdp-access/rdp-access status` | Read-only VM, Compose, tunnel, and IPv6-forward state | +| Start or reconnect access | `test/rdp-access/rdp-access up --bind 0.0.0.0 --public-host x1.xcel.me` | Reuses healthy services; recreates only missing tunnel/forward | +| Browser says “Waiting for response” | `test/rdp-access/rdp-access status`; `test/rdp-access/rdp-access logs --tail=100`; if guacd is stale, `test/rdp-access/rdp-access repair` | Diagnoses tunnel/dual-stack issues; restarts only guacd | +| Print the current URL | `test/rdp-access/rdp-access url` | Read-only URL from the saved session | +| Stop temporary access | `test/rdp-access/rdp-access down` | Stops gateway, IPv6 forward, SSH watchdog/tunnel; retains verifier/cert | +| Reclaim generated state | `test/rdp-access/rdp-access clean` | Stops access and removes only `.runtime/` | +| Reclaim exact unused images too | `test/rdp-access/rdp-access clean --images` | Also removes owned Guacamole/nginx images; leaves shared Alpine intact | +| Return VM to clean baseline | `scripts/windows/test-host reset --run-id interactive-rdp` | Stops/ restores the exact leased VM snapshot and leaves it powered off | + +The two scripts have a deliberate ownership boundary. `rdp-access` manages only +the temporary browser gateway, Guacamole/guacd containers, IPv6 forward, and +Helium SSH tunnel. `scripts/windows/test-host` manages the leased VM and its +service lifecycle. For a prepared run, the remaining VM-side management actions +are: + +```sh +scripts/windows/test-host inspect --run-id interactive-rdp # SCM/read-only client state +scripts/windows/test-host logs --run-id interactive-rdp # bounded startup/client logs +scripts/windows/test-host collect --run-id interactive-rdp # bounded artifacts +scripts/windows/test-host stop --run-id interactive-rdp # stop service and request guest shutdown +scripts/windows/test-host recover --run-id interactive-rdp # inspect an interrupted stopped run +``` + +`stage`, `install`, `run`, and `logoff` are also available in the +`test-host --help` command reference for a complete native-service run; they +are not required merely to use the RDP gateway. `native-test recover` and +`native-test clean` are the corresponding whole-lane recovery/cleanup actions +when the Linux server stack is part of the run. + The helper requires Docker/Docker Compose, `socat` for the optional public dual-stack forward, SSH access through the existing `helium-remote` alias, and the fixture password file documented in