From 9a2b0fd3c1da3fe906addb5d76848df3cda90b93 Mon Sep 17 00:00:00 2001 From: cabbage Date: Mon, 14 Sep 2026 07:08:41 +0000 Subject: [PATCH] docs: clarify RDP recovery and prerequisites --- test/rdp-access/README.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/test/rdp-access/README.md b/test/rdp-access/README.md index c53dcb0..d1d2b76 100644 --- a/test/rdp-access/README.md +++ b/test/rdp-access/README.md @@ -153,6 +153,12 @@ SSH supervisor as `private_tunnel=active_external`. A missing listener is reported as `private_tunnel=inactive`; inspect `.runtime/tunnel.log` and run `up` again to trigger a bounded reconnect attempt. +If `up` reports that an existing gateway has a different configuration, or a +previous start left only part of the Compose stack, run `down` once and then +repeat `up`. Changing the bind address, browser host, or either port likewise +requires `down` first; refusing to mutate a live stack prevents an old browser +session from silently reaching a different endpoint. + The XML mapping intentionally uses Guacamole's `${GUAC_PASSWORD}` connection parameter token. Guacamole resolves this to the password entered at web login; it is not a host environment variable and must remain in the template. @@ -224,6 +230,7 @@ For quick recovery, use this decision table: | 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 | +| Partial stack or changed endpoint | `test/rdp-access/rdp-access down`, then `test/rdp-access/rdp-access up --bind 0.0.0.0 --public-host x1.xcel.me` | Recreates the exact project with the new settings | | 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/` | @@ -250,9 +257,10 @@ 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 +The helper requires Docker/Docker Compose with Docker socket access for the +invoking account (`docker version` must succeed), `socat` for the optional +public dual-stack forward, 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 identity/settings. The authoritative `test-host prepare` step applies only the disposable