[
https://issues.apache.org/jira/browse/GUACAMOLE-2284?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Jairo Morales updated GUACAMOLE-2284:
-------------------------------------
Description:
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:
# There is no visual indication on the home screen of whether a managed
machine is currently powered on or off.
# 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: Original WoL integration
- GUACAMOLE-1686: Host availability check before sending WoL packet
(implemented in 1.6.0)
- 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)
was:
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)
> 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
> Priority: Minor
> Labels: features
> 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:
> # There is no visual indication on the home screen of whether a managed
> machine is currently powered on or off.
> # 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: Original WoL integration
> - GUACAMOLE-1686: Host availability check before sending WoL packet
> (implemented in 1.6.0)
> - 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)
