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

docs: make RDP fixture management self-service

Browse Source
This commit is contained in:
cabbage
2026-09-14 07:07:23 +00:00
parent a68729def0
commit e3aadd8dd6
2 changed files with 92 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
scripts/windows/test-host
+2 -2
View File
@@ -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
test/rdp-access/README.md
+90
View File
@@ -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