Fix Guacamole graphics login cache and session repair

This commit is contained in:
cabbage committed 2026-10-08 07:11:21 +00:00
1 parent 98a474696b
commit 4f1ed41f9f
4 files changed
+43 -15

No files matched your search

+9 -3
View File
@@ -904,9 +904,15 @@ watchdog/tunnel is bound
only to the helper's private Docker gateway. Stop the helper before the normal 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 `test-host reset`. It is a recovery interface, not a product component or a
replacement for Guest Control/native test automation. replacement for Guest Control/native test automation.
The helper's `repair` action may restart only guacd when a dropped browser The helper's `repair` action restarts guacd and the Guacamole web application
leaves a stale worker holding the fixture's single VRDE slot; it must not when a dropped browser leaves a stale worker holding the fixture's single VRDE
restart or mutate the Windows VM automatically. 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 Because Windows can power off the virtual monitor while the VM remains
running, `test-host prepare` must also reapply the disposable display/sleep running, `test-host prepare` must also reapply the disposable display/sleep
keepalive and record `prepare-display-keepalive`. A zero-bpp VRDE framebuffer keepalive and record `prepare-display-keepalive`. A zero-bpp VRDE framebuffer
+4 -1
View File
@@ -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 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) the Windows baseline. See the [gateway quality settings](../test/rdp-access/README.md#network-and-graphics-quality)
for all levels and server-negotiation caveats. for all levels and server-negotiation caveats.
+15 -5
View File
@@ -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` The choice is saved per gateway profile and reused when omitted. `status`
prints the saved `graphics` mode. A change rewrites the connection mapping prints the saved `graphics` mode. A change rewrites the connection mapping
while retaining the gateway and tunnels; disconnect/reconnect the desktop to while retaining the gateway and tunnels; **log out of Guacamole and sign in
apply it. Existing sessions continue with their original display settings. 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 If an old browser connection holds the single VRDE slot, close it or use the
documented `repair` action before reconnecting. documented `repair` action before reconnecting.
@@ -286,8 +292,12 @@ disabled, run:
test/rdp-access/rdp-access repair test/rdp-access/rdp-access repair
``` ```
`repair` restarts only guacd, retains the VM, SSH tunnel, gateway, and IPv6 `repair` restarts guacd **and the Guacamole web application**, clearing stale
forward, and does not alter the Windows guest. Close old browser tabs and sign 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. in again after it completes.
For quick recovery, use this decision table: 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 | | 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 | | 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 | | 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 | | 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 | | Stop temporary access | `test/rdp-access/rdp-access down` | Stops gateway, IPv6 forward, SSH watchdog/tunnel; retains verifier/cert |
+15 -6
View File
@@ -30,7 +30,7 @@ usage: test/rdp-access/rdp-access ACTION [OPTIONS]
Actions: Actions:
up start a private VRDE SSH tunnel and self-signed HTTPS Guacamole up start a private VRDE SSH tunnel and self-signed HTTPS Guacamole
status show gateway, tunnel, and fixture status without changing anything 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 url print the current browser URL
logs follow or print Compose logs (pass Docker Compose log options) logs follow or print Compose logs (pass Docker Compose log options)
down stop containers and the private SSH watchdog/tunnel; retain generated state 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 IPv6-to-IPv4 listener for dual-stack hostnames. Set
RDP_ACCESS_GUACD_LOG_LEVEL=debug for temporary protocol diagnostics. RDP_ACCESS_GUACD_LOG_LEVEL=debug for temporary protocol diagnostics.
RDP_ACCESS_GRAPHICS is equivalent to --graphics; omitted values reuse the RDP_ACCESS_GRAPHICS is equivalent to --graphics; omitted values reuse the
saved profile setting (normal for a first start). Reconnect the desktop after saved profile setting (normal for a first start). Log OUT of Guacamole and sign
changing graphics; existing connections retain their original settings. in again after changing graphics; reconnecting a desktop alone retains the
login's cached settings. repair clears both cached logins and stale workers.
EOF 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" 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 if [ "$saved_graphics" != "$RDP_ACCESS_GRAPHICS" ]; then
render_mapping 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 fi
if tunnel_active; then if tunnel_active; then
printf 'Guacamole stack and private VRDE tunnel are already active.\n' printf 'Guacamole stack and private VRDE tunnel are already active.\n'
@@ -600,9 +601,17 @@ case $action in
docker compose version >/dev/null docker compose version >/dev/null
assert_fixture_running assert_fixture_running
[ -n "$(compose ps -q guacd 2>/dev/null || true)" ] || fail "Guacamole stack is not running; run up first" [ -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 compose restart guacd >/dev/null
wait_for_gateway || fail "Guacamole gateway did not become ready after guacd repair" compose restart guacamole >/dev/null
printf 'guacd restarted; stale VRDE workers released. Close any old browser tab and sign in again.\n' 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) url)
[ "$#" -eq 0 ] || { usage >&2; fail "url accepts no options"; } [ "$#" -eq 0 ] || { usage >&2; fail "url accepts no options"; }