GUACAMOLE-2138: Add connection-timeout parameter #1117

tkuhlengel · 2025-09-16T19:14:08Z

Summary

In my company's business use case for Guacamole, for security and auditing purposes, we need to be able to ensure that any idle user is disconnected and logged off within a set period of time of idleness.

In an ideal version of such a system, we would do the following.

Check if the user has interacted with the connection in the last X minutes, or if an active SFTP transfer is happening on the connection.
If not, terminate the user connection after X minutes of inactivity.
If they remain idle, the Guacamole idle timer will log them out after the pre-configured login idle timeout.

This requires a lot of conditionals and would be more difficult to implement and maintain in an ongoing project like Guacamole.

A more practical, yet sufficient, version is:

The Administrator sets a maximum duration for any connection, specified in minutes.
Any connection that exceeds that duration, regardless of activity, is terminated while the user remains logged in. They are free to reconnect if the user is still active.
The login idle timeout starts when the connection ends.

This second option meets our business needs, and we would like to share it with others.

Features

Add parameter connection-timeout in guacamole.properties, disconnecting users after connection-timeout minutes. Defaults to 0, disabling the feature.
Implement the connection timeout using a Map that stores the creation time of the connection.
Integrate the connection timeout check into the existing idle timeout function.

* Add defaults for parameter connection-timeout in guacamole.properties to disable feature. * Implement the connection timeout using a Map based on creation time * Integrate the connection timeout check into the existing idle timeout function.

Copilot

Pull Request Overview

This PR adds a connection timeout feature to automatically terminate connections after a specified duration, regardless of activity level. This addresses security and auditing requirements for ensuring idle users are disconnected within set time limits.

Adds a new connection-timeout parameter in guacamole.properties (defaults to 0/disabled)
Implements connection timeout tracking using a Map to store tunnel creation times
Integrates connection timeout checks into the existing session eviction mechanism

Reviewed Changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
HashTokenSessionMap.java	Adds connection-timeout property configuration and integrates timeout checking into session eviction task
GuacamoleSession.java	Implements tunnel creation time tracking and expiration logic for individual connections

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

guacamole/src/main/java/org/apache/guacamole/rest/auth/HashTokenSessionMap.java

Copilot · 2025-09-16T19:14:42Z

guacamole/src/main/java/org/apache/guacamole/GuacamoleSession.java

+            UserTunnel tunnel = tunnels.get(tunnelId);
+            if (tunnel != null) {
+                try {
+                    tunnel.close();
+                    logger.debug("Closed tunnel \"{}\" due to connection timeout.", tunnelId);
+                }
+                catch (GuacamoleException e) {
+                    logger.debug("Unable to close expired tunnel \"" + tunnelId + "\".", e);
+                }
+                // Remove from both maps regardless of whether close succeeded
+                tunnels.remove(tunnelId);
+                tunnelCreationTimes.remove(tunnelId);
+                closedCount++;
+            }
+        }


The tunnel removal logic is duplicated here and in the removeTunnel method. Consider extracting this into a private helper method to avoid code duplication.

Suggested change

UserTunnel tunnel = tunnels.get(tunnelId);

if (tunnel != null) {

try {

tunnel.close();

logger.debug("Closed tunnel \"{}\" due to connection timeout.", tunnelId);

}

catch (GuacamoleException e) {

logger.debug("Unable to close expired tunnel \"" + tunnelId + "\".", e);

}

// Remove from both maps regardless of whether close succeeded

tunnels.remove(tunnelId);

tunnelCreationTimes.remove(tunnelId);

closedCount++;

}

}

if (removeTunnelById(tunnelId, "Closed tunnel \"{}\" due to connection timeout.", "Unable to close expired tunnel \"{}\".")) {

closedCount++;

}

}

/**

* Removes the tunnel with the given ID from the session, closing it and removing

* its creation time. Returns true if a tunnel was removed, false otherwise.

*

* @param tunnelId

* The ID of the tunnel to remove.

* @param successMsg

* The message to log on successful close.

* @param errorMsg

* The message to log on error.

* @return

* true if a tunnel was removed, false otherwise.

*/

private boolean removeTunnelById(String tunnelId, String successMsg, String errorMsg) {

UserTunnel tunnel = tunnels.get(tunnelId);

if (tunnel != null) {

try {

tunnel.close();

logger.debug(successMsg, tunnelId);

}

catch (GuacamoleException e) {

logger.debug(errorMsg, tunnelId, e);

}

tunnels.remove(tunnelId);

tunnelCreationTimes.remove(tunnelId);

return true;

}

return false;

}

I'm not sure I agree with CoPilot, here; however, is there any reason not to use the removeTunnel() method?

I'm not the expert in this particular case.

My understanding of removeTunnel is that it doesn't close an active tunnel, only removes it from the list of active tunnels. I think that's the equivalent of disassociating it from one user?

I could use it on line +375 in this chunk, but I'm not sure how much difference it will make to make it smaller or meaningfully better other than consistency. I still need to close the tunnel first.

guacamole/src/main/java/org/apache/guacamole/GuacamoleSession.java

- Introduce creationTime field in AbstractGuacamoleTunnel - Implement getCreationTime method in GuacamoleTunnel interface - Update DelegatingGuacamoleTunnel to return tunnel creation time - Remove tunnel creation time tracking map from GuacamoleSession - Adjust methods in GuacamoleSession to use GuacamoleTunnel.getCreationTime() and reuse the existing Map of active tunnels.

tkuhlengel · 2025-10-30T15:30:18Z

I think this is the full "whole-server" version I have for now, addressing the comments above.

I saw your comments about adding feedback to guacd. Is that something I would need to implement in a guacd pull request for this to be approved?

guacamole/src/main/java/org/apache/guacamole/GuacamoleSession.java

guacamole-common/src/main/java/org/apache/guacamole/net/GuacamoleTunnel.java

necouchman · 2025-10-30T18:48:00Z

guacamole/src/main/java/org/apache/guacamole/rest/auth/HashTokenSessionMap.java

+    /**
+     * The connection timeout for individual Guacamole connections, in minutes.
+     * If 0, connections will not be automatically terminated based on age.
+     */
+    private final IntegerGuacamoleProperty CONNECTION_TIMEOUT =
+            new IntegerGuacamoleProperty() {
+
+        @Override
+        public String getName() { return "connection-timeout"; }
+
+    };
+


I'm thinking that we may want to name this slightly differently. "timeout" carries with it the notion that the connection is waiting for something - user input, or a response from a remote system, etc. - and what you've really implemented, here, is a maximum connection duration, at which point the connection(s) will be forcibly dropped and users will have to reconnect. My thought is that maybe this code - both internally within the code and for exposed things like properties - should call this something different - maximum-session-duration or session-limit or something similar?

maximum-session-duration might work as a descriptive setting name. I don't know if that is a similar name to a user login session, which is different.

maximum-connection-duration might work. I'll put that in for now and we can iterate on it.

guacamole/src/main/java/org/apache/guacamole/rest/auth/HashTokenSessionMap.java

guacamole/src/main/java/org/apache/guacamole/GuacamoleSession.java

necouchman · 2025-10-30T18:54:46Z

guacamole/src/main/java/org/apache/guacamole/GuacamoleSession.java

+            UserTunnel tunnel = tunnels.get(tunnelId);
+            if (tunnel != null) {
+                try {
+                    tunnel.close();
+                    logger.debug("Closed tunnel \"{}\" due to connection timeout.", tunnelId);
+                }
+                catch (GuacamoleException e) {
+                    logger.debug("Unable to close expired tunnel \"" + tunnelId + "\".", e);
+                }
+                // Remove from both maps regardless of whether close succeeded
+                tunnels.remove(tunnelId);
+                tunnelCreationTimes.remove(tunnelId);
+                closedCount++;
+            }
+        }


I'm not sure I agree with CoPilot, here; however, is there any reason not to use the removeTunnel() method?

necouchman · 2025-10-30T18:57:37Z

I think this is the full "whole-server" version I have for now, addressing the comments above.

I saw your comments about adding feedback to guacd. Is that something I would need to implement in a guacd pull request for this to be approved?

Yes, any sort of feedback look for guacd would require some changes both here and in the guacd code.

* Formatting and style cleanup.

tkuhlengel · 2025-11-13T18:10:58Z

In terms of communication with guacd:

Would it be okay to use the SESSION_TIMEOUT error code or should I make my own? Or possibly just use the 'disconnect' handler on the guacd side?
If the client needs to send information back to guacd when tunnels are closed, why isn't a message isn't sent tunnel.close() implementations by default?

necouchman · 2025-12-14T12:23:13Z

In terms of communication with guacd:

Would it be okay to use the SESSION_TIMEOUT error code or should I make my own? Or possibly just use the 'disconnect' handler on the guacd side?

I'm tempted to say make another one, because of things I've mentioned above - the implementation, here, isn't so much a "timeout" as it is a limit. To me, "timeout" carries a notion of waiting for something - user interaction, a network response, etc. - and not getting that. In this case, you're actually putting a cap on the session duration regardless of whether the user is active or not, the server is responsive or not, etc.

If the client needs to send information back to guacd when tunnels are closed, why isn't a message isn't sent tunnel.close() implementations by default?

I would guess there just hasn't been a need for it in the past. It could probably be added - my only caution would be to make sure that adding it doesn't break compatibility with clients that don't send a message.

Copilot AI review requested due to automatic review settings September 16, 2025 19:14

Copilot AI reviewed Sep 16, 2025

View reviewed changes

necouchman reviewed Sep 16, 2025

View reviewed changes

guacamole/src/main/java/org/apache/guacamole/GuacamoleSession.java Outdated Show resolved Hide resolved

necouchman requested changes Oct 30, 2025

View reviewed changes

tkuhlengel and others added 2 commits November 11, 2025 22:24

Merge branch 'apache:main' into GUACAMOLE-2138

2f6f299

GUACAMOLE-2138: Renaming setting to max-connection-duration

8704eb4

* Formatting and style cleanup.

GUACAMOLE-2138: Add connection-timeout parameter #1117

Are you sure you want to change the base?

GUACAMOLE-2138: Add connection-timeout parameter #1117

Uh oh!

Conversation

tkuhlengel commented Sep 16, 2025

Summary

Features

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Copilot AI Sep 16, 2025

Choose a reason for hiding this comment

Uh oh!

necouchman Oct 30, 2025

Choose a reason for hiding this comment

Uh oh!

tkuhlengel Nov 12, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

tkuhlengel commented Oct 30, 2025

Uh oh!

Uh oh!

Uh oh!

necouchman Oct 30, 2025

Choose a reason for hiding this comment

Uh oh!

tkuhlengel Nov 12, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

necouchman Oct 30, 2025

Choose a reason for hiding this comment

Uh oh!

necouchman commented Oct 30, 2025

Uh oh!

tkuhlengel commented Nov 13, 2025

Uh oh!

necouchman commented Dec 14, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants