guacamole.properties

Advanced configuration properties within guacamole.properties

The guacamole.properties file, located within /etc/guacamole, is Guacamole’s main configuration file. Keeper Connection Manager provides a thoroughly-commented version of this configuration file, including example properties organized into logical sections with accompanying documentation.

TCP connection information for guacd

The hostname and port of the machine hosting the guacd service, as well as whether that guacd service has been configured for SSL/TLS. By default, Guacamole will connect to guacd at port 4822 on localhost, and will not use SSL/TLS to do so.

Property name
Default value
Description

guacd-hostname

localhost

The hostname of the machine hosting the guacd service.

guacd-port

4822

The port used by the guacd service.

guacd-ssl

false

Whether the guacd service has been configured for SSL/TLS.

Guacamole user session timeout

The amount of time, in minutes, a Guacamole session may remain valid despite being inactive. By default, Guacamole sessions remain valid for 60 minutes.

Property name
Default value
Description

api-session-timeout

60

The amount of time, in minutes, a Guacamole session may remain valid despite being inactive.

This setting affects Guacamole sessions only, not remote desktop sessions. To enforce limits on the duration of remote desktop sessions, you must change the relevant setting within your remote desktop server, such as the session time limit GPOs provided by the Windows RDP server. Guacamole considers a connected remote desktop session to be user activity, and does not attempt to define what constitutes an idle but connected remote desktop session.

HTTP request size limits

It is unusual to need to change this setting:

  • File transfers within a remote desktop session are not affected by this limit.

  • Requests unrelated to file transfer should normally be well beneath the default limit (2 MB).

If you find yourself considering changing this property value, first investigate whether there may be any external factors causing the problem you're seeing, such as a reverse proxy, firewall, or browser extension. It is more common that the settings of the reverse proxy providing SSL termination need to be adjusted, and that no change needs to be made to Guacamole's request size limits whatsoever.

The maximum number of bytes to accept within the entity body of any particular HTTP request to Guacamole's internal REST API, including authentication requests. By default, HTTP requests made against the Guacamole web application are limited to 2 MB, excluding requests related to file transfer for a remote desktop session.

Property name
Default value
Description

api-max-request-size

2097152

The maximum number of bytes to accept within the entity body of any particular HTTP request to the REST API, including authentication requests. This limit does not apply to files transferred within a remote desktop session. Specifying 0 disables request size limitations.

If setting this property intending to remove or lessen limitations on request sizes, be sure to check the settings of any reverse proxy providing SSL termination. Your reverse proxy may impose its own default limitations that will need to be overridden. For example, Nginx imposes a default limit of 1 MB per request.

Restricting available languages

If you have developed your own branding extension that overrides Guacamole's translation strings only for a subset of Guacamole's supported languages, you can force Guacamole to reduce the set of supported languages to only those languages you have modified. This is only necessary if you have developed your own branding. Branding extensions provided by Keeper Connection Manager as part of a Keeper Connection Manager subscription will update all supported languages.

Property name
Description

allowed-languages

A comma-separated list of language keys for Guacamole's display language. If specified, only the listed languages will be made available to the user, and only the listed languages will be selected from automatically based on the user's browser's preferred language. By default, all defined languages will be available.

For example, to restrict Guacamole to only English and German, specify:

allowed-languages: en, de

As English is the fallback language, used whenever a translation key is missing from the chosen language, English should only be omitted from this list if you are absolutely positive that no strings are missing from your custom translations.

Extension-specific properties

In addition to the standard properties accepted by the web application, extensions may read additional properties which are specific to their own configuration needs. The guacamole.properties file included with Keeper Connection Manager contains comments which cleanly group configuration into distinct sections for each supported extension, along with example properties and documentation.

Last updated