Jairo Morales created GUACAMOLE-2284:
----------------------------------------
Summary: Add TCP reachability check instruction to Guacamole
protocol to support WoL countdown notification and connection status indicator
Key: GUACAMOLE-2284
URL: https://issues.apache.org/jira/browse/GUACAMOLE-2284
Project: Guacamole
Issue Type: New Feature
Components: guacamole-client, guacd
Affects Versions: 1.6.0
Reporter: Jairo Morales
Attachments: Status Indication.png, WoL Waiting Screen.png
h2. Background
Wake-on-LAN (WoL) support was introduced in Guacamole 1.2.0 (GUACAMOLE-513) and
the ability to check host availability before sending the WoL packet was
implemented in 1.6.0 (GUACAMOLE-1686). However, two usability gaps remain that
motivated this proposal:
1. There is no visual indication on the home screen of whether a managed
machine is currently powered on or off.
2. When a WoL-enabled connection enters the WAITING state, there is no
user-facing feedback about how long to expect to wait — the UI simply spins
silently.
A naive client-side solution (running TCP checks from Tomcat) breaks down in
deployments where guacd sits inside a private network and the Java/Tomcat
components have no direct path to the managed systems — which is exactly the
topology Guacamole is designed to support. This is the same reason WoL packet
sending lives inside guacd and not in the Java client.
h2. Proposed Solution
Implement a TCP reachability-check instruction as part of the Guacamole
protocol, allowing guacamole-client to delegate host availability checks to
guacd, which has actual network access to the managed systems.
h3. 1. New TCP ping instruction in the Guacamole protocol (guacamole-server)
- guacamole-client sends a batch request to guacd containing one or more
(hostname, port) pairs.
- guacd performs a non-blocking TCP connection attempt to each target.
- guacd responds with a per-host status (up/down) and optionally latency.
h3. 2. TCP ping handler in guacd (guacamole-server)
- Implement the server-side handler that processes the batch ping request and
returns results.
h3. 3. Client-side handler in guacamole-client (guacamole-client)
- Tomcat sends the batch ping request on home screen load and caches results
briefly to avoid flooding guacd.
- The feature is opt-in via a guacamole.properties flag (disabled by default)
so large installations with existing monitoring systems are not impacted.
h3. 4. Connection status indicator on the home screen (guacamole-client)
- Connection tile icons reflect the up/down state returned by guacd.
h3. 5. WoL countdown notification (guacamole-client)
- When a connection enters the WAITING state and WoL is configured, display a
live countdown based on wol-wait-time, informed by the ping result from guacd
rather than a client-side probe.
- This creates a concrete link between the client-side visualization and
guacd's WoL timer, addressing the assumption gap noted in PR #1208.
h2. Related Issues
-[GUACAMOLE-513|https://issues.apache.org/jira/browse/GUACAMOLE-513]: Original
WoL integration
- [GUACAMOLE-1686|https://issues.apache.org/jira/browse/GUACAMOLE-1686]: Host
availability check before sending WoL packet (implemented in 1.6.0)
- [GUACAMOLE-2107|https://issues.apache.org/jira/browse/GUACAMOLE-2107]:
guac_tcp_connect() error handling fix (fix merged into staging/1.6.1 via PR
#609)
h2. Related Pull Request
- [guacamole-client PR
#1208|https://github.com/apache/guacamole-client/pull/1208] (initial
client-side prototype, architectural concerns addressed by this proposal)
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
