diff --git a/docs/implementation-plan.v1.md b/docs/implementation-plan.v1.md index ca2720d..6e0779e 100644 --- a/docs/implementation-plan.v1.md +++ b/docs/implementation-plan.v1.md @@ -904,9 +904,15 @@ watchdog/tunnel is bound only to the helper's private Docker gateway. Stop the helper before the normal `test-host reset`. It is a recovery interface, not a product component or a replacement for Guest Control/native test automation. -The helper's `repair` action may restart only guacd when a dropped browser -leaves a stale worker holding the fixture's single VRDE slot; it must not -restart or mutate the Windows VM automatically. +The helper's `repair` action restarts guacd and the Guacamole web application +when a dropped browser leaves a stale worker holding the fixture's single VRDE +slot, or an authenticated login retains an old graphics configuration. It +clears cached web logins but preserves the HTTPS gateway and forwarding; it +must not restart or mutate the Windows VM automatically. Changing a graphics +preset requires logging out of Guacamole and signing in again, not merely +reconnecting the desktop: file authentication retains a connection map in the +authenticated user's context. Verify graphics through the authenticated web +tunnel, not only a direct guacd connection which bypasses that context. Because Windows can power off the virtual monitor while the VM remains running, `test-host prepare` must also reapply the disposable display/sleep keepalive and record `prepare-display-keepalive`. A zero-bpp VRDE framebuffer diff --git a/docs/testing-vm.md b/docs/testing-vm.md index 4cc8fdc..eb84cc8 100644 --- a/docs/testing-vm.md +++ b/docs/testing-vm.md @@ -216,7 +216,10 @@ test/rdp-access/rdp-access up --bind 0.0.0.0 \ ``` That requests 800×600/8-bit graphics and saves the selection per gateway -profile. Disconnect/reconnect to apply a profile change; it does not modify +profile. Log out of Guacamole and sign in again to apply a profile change: +desktop disconnect/reconnect alone retains the login's cached configuration. +`rdp-access repair` clears both cached web logins and stale RDP workers without +rebooting Windows. A profile change does not modify the Windows baseline. See the [gateway quality settings](../test/rdp-access/README.md#network-and-graphics-quality) for all levels and server-negotiation caveats. diff --git a/test/rdp-access/README.md b/test/rdp-access/README.md index 352059f..4455842 100644 --- a/test/rdp-access/README.md +++ b/test/rdp-access/README.md @@ -43,8 +43,14 @@ test/rdp-access/rdp-access up --bind 0.0.0.0 --public-host x1.xcel.me --graphics The choice is saved per gateway profile and reused when omitted. `status` prints the saved `graphics` mode. A change rewrites the connection mapping -while retaining the gateway and tunnels; disconnect/reconnect the desktop to -apply it. Existing sessions continue with their original display settings. +while retaining the gateway and tunnels; **log out of Guacamole and sign in +again** to apply it. Disconnecting/reconnecting the desktop or refreshing the +page alone is insufficient: file-based authentication keeps a copy of the +connection settings in each authenticated user's context. Existing logins +continue with their original display settings even when they create another +desktop connection. This follows the [Guacamole 1.6 authentication implementation](https://github.com/apache/guacamole-client/blob/1.6.0/guacamole-ext/src/main/java/org/apache/guacamole/net/auth/simple/SimpleAuthenticationProvider.java). +To clear cached logins and workers without rebooting the VM or replacing the +gateway/tunnels, run `test/rdp-access/rdp-access repair`, then sign in again. If an old browser connection holds the single VRDE slot, close it or use the documented `repair` action before reconnecting. @@ -286,8 +292,12 @@ disabled, run: test/rdp-access/rdp-access repair ``` -`repair` restarts only guacd, retains the VM, SSH tunnel, gateway, and IPv6 -forward, and does not alter the Windows guest. Close old browser tabs and sign +`repair` restarts guacd **and the Guacamole web application**, clearing stale +workers and cached login connection settings. It retains the VM, SSH tunnel, +HTTPS gateway, and IPv6 +forward, and does not alter the Windows guest. It restarts those services +sequentially and reloads nginx's upstream DNS address so Docker service IP +reassignment cannot leave a `502 Bad Gateway` behind. Close old browser tabs and sign in again after it completes. For quick recovery, use this decision table: @@ -296,7 +306,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 | +| Browser says “Waiting for response”, or resolution remains from an old preset | `test/rdp-access/rdp-access status`; `test/rdp-access/rdp-access logs --tail=100`; `test/rdp-access/rdp-access repair`, then sign in again | Diagnoses tunnel/dual-stack issues; clears cached web logins and stale guacd workers without restarting the VM | | 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 | diff --git a/test/rdp-access/rdp-access b/test/rdp-access/rdp-access index a918dd5..24c59aa 100755 --- a/test/rdp-access/rdp-access +++ b/test/rdp-access/rdp-access @@ -30,7 +30,7 @@ usage: test/rdp-access/rdp-access ACTION [OPTIONS] Actions: up start a private VRDE SSH tunnel and self-signed HTTPS Guacamole status show gateway, tunnel, and fixture status without changing anything - repair restart only guacd to release a stale single-VRDE-slot worker + repair restart guacd and Guacamole; release stale workers and cached logins url print the current browser URL logs follow or print Compose logs (pass Docker Compose log options) down stop containers and the private SSH watchdog/tunnel; retain generated state @@ -60,8 +60,9 @@ RDP_ACCESS_IPV6_FORWARD (auto, always, or never) control the reversible IPv6-to-IPv4 listener for dual-stack hostnames. Set RDP_ACCESS_GUACD_LOG_LEVEL=debug for temporary protocol diagnostics. RDP_ACCESS_GRAPHICS is equivalent to --graphics; omitted values reuse the -saved profile setting (normal for a first start). Reconnect the desktop after -changing graphics; existing connections retain their original settings. +saved profile setting (normal for a first start). Log OUT of Guacamole and sign +in again after changing graphics; reconnecting a desktop alone retains the +login's cached settings. repair clears both cached logins and stale workers. EOF } @@ -533,7 +534,7 @@ case $action in session_matches_current || fail "gateway already exists with a different configuration; run down first, then run up with the desired options" if [ "$saved_graphics" != "$RDP_ACCESS_GRAPHICS" ]; then render_mapping - printf 'Graphics changed to %s. Disconnect/reconnect the desktop to apply.\n' "$RDP_ACCESS_GRAPHICS" + printf 'Graphics changed to %s. Log out of Guacamole and sign in again to apply (desktop reconnect alone is insufficient).\n' "$RDP_ACCESS_GRAPHICS" fi if tunnel_active; then printf 'Guacamole stack and private VRDE tunnel are already active.\n' @@ -600,9 +601,17 @@ case $action in docker compose version >/dev/null assert_fixture_running [ -n "$(compose ps -q guacd 2>/dev/null || true)" ] || fail "Guacamole stack is not running; run up first" + # File authentication retains connection configurations in each + # authenticated UserContext. Restart the webapp as well as guacd so + # a reconnect cannot silently reuse a login's old graphics preset. + # Restart sequentially: simultaneous restarts can swap Docker-assigned + # service IPs. Reload nginx's statically resolved upstream afterward, + # even if Docker preserves the IPs on this particular restart. compose restart guacd >/dev/null - wait_for_gateway || fail "Guacamole gateway did not become ready after guacd repair" - printf 'guacd restarted; stale VRDE workers released. Close any old browser tab and sign in again.\n' + compose restart guacamole >/dev/null + compose exec -T gateway nginx -s reload >/dev/null + wait_for_gateway || fail "Guacamole gateway did not become ready after session repair" + printf 'Guacamole and guacd restarted; cached logins and stale VRDE workers cleared. Sign in again. VM and forwarding are unchanged.\n' ;; url) [ "$#" -eq 0 ] || { usage >&2; fail "url accepts no options"; }