Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
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.
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.
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.
The amount of time, in minutes, a Guacamole session may remain valid despite being inactive. By default, Guacamole sessions remain valid for 60 minutes.
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.
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.
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 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.
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:
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.
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.
OpenID Connect Configuration Properties
TOTP Configuration Properties
UDS Enterprise Configuration Properties
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, .
Advanced configuration properties for Duo 2FA
The properties listed here are only applicable if Duo two-factor authentication is being used. Support for Duo two-factor authentication is installed using the kcm-guacamole-auth-duo
package or enabled with the Docker installation. If using the keeper/guacamole Docker image, support for Duo two-factor authentication is configured using environment variables.
The API hostname, integration key, and secret key are provided for you by Duo when you registered Guacamole within Duo's "Admin" panel. Each of these values is required and is generated by Duo.
duo-api-hostname
The hostname of the Duo API endpoint to be used to verify user identities, generated by Duo when you registered Guacamole within Duo's "Admin" panel. This value can be found within the application details in the "API hostname" field.
duo-integration-key
The integration key provided for Guacamole by Duo when you registered Guacamole within Duo's "Admin" panel. This value can be found within the application details in the "Integration key" field.
duo-secret-key
The secret key provided for Guacamole by Duo when you registered Guacamole within Duo's "Admin" panel. This value can be found within the application details in the "Secret key" field.
An arbitrary and random key must be provided for communicating with the Duo service. This key MUST be manually generated and MUST BE AT LEAST 40 CHARACTERS.
duo-application-key
The arbitrary, random key to use when communicating with the Duo service.
Any random value containing at least 40 characters will suffice. To quickly grab 40 random characters from /dev/random
:
Advanced configuration properties for MySQL
The properties listed here are only applicable if MySQL authentication is being used. Support for MySQL authentication is installed using thekcm-guacamole-auth-jdbc-mysql
package. If using the keeper/guacamole Docker image, support for MySQL authentication is instead configured using environment variables.
Minimum password length and complexity
Minimum/maximum password age
Password reuse prevention
Database concurrent connection limits
General connection concurrency limits
Per-user concurrency limits
Absolute concurrency limits
The TCP connection details for the MySQL / MariaDB database.
mysql-hostname
localhost
The hostname of the database server.
mysql-port
3306
The port of the MySQL or MariaDB service running on the database server.
The name of the database to use, as well as the credentials to use when connecting to the database. These properties are required if one of the database authentication extensions will be used.
mysql-database
The name of the database that Guacamole should issue queries against.
mysql-username
The username of the user that Guacamole should use to connect to the database.
mysql-password
The password Guacamole should provide when authenticating with the database.
Restrictions that should be applied to all database users with respect to password complexity, length, change frequency, and reuse.
These properties do not affect users defined outside the database.
mysql-user-password-min-length
0
The minimum length of each password, in characters. If specified, users will not be able to change their passwords to values that are not at least this length. By default, no minimum length is enforced. Empty passwords are never allowed.
mysql-user-password-require-multiple-case
false
If set to "true", require that all passwords contain at least one uppercase character and one lowercase character. By default, passwords are not required to contain mixed case.
mysql-user-password-require-symbol
false
If set to "true", require that all passwords contain at least one symbol, where a "symbol" is any non-alphanumeric character. By default, passwords are not required to contain symbols.
mysql-user-password-require-digit
false
If set to "true", require that all passwords contain at least one digit, where a "digit" is any numeric character. By default, passwords are not required to contain digits.
mysql-user-password-prohibit-username
false
If set to "true", prohibit passwords from containing the user's own username, regardless of case. By default, use of the user's own username within their password is not prevented.
mysql-user-password-min-age
The minimum number of days that must elapse between password changes (preventing users from changing passwords too frequency and defeating password reuse protections). By default, frequency of password changes is not restricted.
mysql-user-password-max-age
The maximum number of days that may elapse before users are required to change their passwords. By default, users passwords do not automatically expire.
mysql-user-password-history-size
The number of past passwords that should be remembered for each user. If specified, users will be prevented from reusing any of these passwords. By default, reuse of past passwords is not prevented.
Concurrent usage restrictions that should be enforced by default across all connections. With the exception the absolute concurrency limit, each of these restrictions may be overridden by the administrator on a per-connection basis by editing the connection.
mysql-default-max-connections
0
The maximum number of concurrent connections to allow to any particular connection, where "0" represents unlimited. By default, no overall concurrency limits are enforced on connections.
mysql-default-max-group-connections
0
The maximum number of concurrent connections to allow to any particular balancing connection group, where "0" represents unlimited. By default, no overall concurrency limits are enforced on connection groups.
mysql-default-max-connections-per-user
0
The maximum number of concurrent connections to allow to any individual user to establish to a connection, where "0" represents unlimited. By default, no per-user concurrency limits are enforced on connections.
mysql-default-max-group-connections-per-user
1
The maximum number of concurrent connections to allow to any individual user to establish to a balancing connection group, where "0" represents unlimited. By default, no each user is limited to a single connection for each balancing connection group, to avoid allowing any one user to exhaust the available connections within that group..
mysql-absolute-max-connections
0
The absolute maximum number of concurrent connections to allow to the Guacamole server as a whole, regardless of which users are establishing those connections and which connections or groups are being accessed, where "0" represents unlimited. By default, no absolute concurrent restrictions are enforced.
Whether authentication via other extensions is allowed for users that do not exist within the MySQL / MariaDB database. If set to "true", authentication attempts will be denied unless the authenticated user has been defined within the database.
mysql-user-required
false
If set to "true", require that all successful authentication attempts be associated with a user defined within MySQL. If a user authentications successfully via another mechanism (such as LDAP), that attempt will still be denied if no corresponding MySQL user exists. By default, successful authentication attempts will be considered successful regardless of whether an account for that user exists within MySQL.
Advanced configuration properties for PostgreSQL
The properties listed here are only applicable if PostgreSQL authentication is being used. Support for PostgreSQL authentication is installed using thekcm-guacamole-auth-jdbc-postgresql
package. If using the keeper/guacamole Docker image, support for PostgreSQL authentication is instead configured using environment variables.
Minimum password length and complexity
Minimum/maximum password age
Password reuse prevention
Database concurrent connection limits
General connection concurrency limits
Per-user concurrency limits
Absolute concurrency limits
The TCP connection details for the PostgreSQL database.
postgresql-hostname
localhost
The hostname of the database server.
postgresql-port
5432
The port of the PostgreSQL service running on the database server.
The name of the database to use, as well as the credentials to use when connecting to the database. These properties are required if one of the database authentication extensions will be used.
postgresql-database
The name of the database that Guacamole should issue queries against.
postgresql-username
The username of the user that Guacamole should use to connect to the database.
postgresql-password
The password Guacamole should provide when authenticating with the database.
Restrictions that should be applied to all database users with respect to password complexity, length, change frequency, and reuse.
These properties do not affect users defined outside the database.
postgresql-user-password-min-length
0
The minimum length of each password, in characters. If specified, users will not be able to change their passwords to values that are not at least this length. By default, no minimum length is enforced. Empty passwords are never allowed.
postgresql-user-password-require-multiple-case
false
If set to "true", require that all passwords contain at least one uppercase character and one lowercase character. By default, passwords are not required to contain mixed case.
postgresql-user-password-require-symbol
false
If set to "true", require that all passwords contain at least one symbol, where a "symbol" is any non-alphanumeric character. By default, passwords are not required to contain symbols.
postgresql-user-password-require-digit
false
If set to "true", require that all passwords contain at least one digit, where a "digit" is any numeric character. By default, passwords are not required to contain digits.
postgresql-user-password-prohibit-username
false
If set to "true", prohibit passwords from containing the user's own username, regardless of case. By default, use of the user's own username within their password is not prevented.
postgresql-user-password-min-age
The minimum number of days that must elapse between password changes (preventing users from changing passwords too frequency and defeating password reuse protections). By default, frequency of password changes is not restricted.
postgresql-user-password-max-age
The maximum number of days that may elapse before users are required to change their passwords. By default, users passwords do not automatically expire.
postgresql-user-password-history-size
The number of past passwords that should be remembered for each user. If specified, users will be prevented from reusing any of these passwords. By default, reuse of past passwords is not prevented.
Concurrent usage restrictions that should be enforced by default across all connections. With the exception the absolute concurrency limit, each of these restrictions may be overridden by the administrator on a per-connection basis by editing the connection.
postgresql-default-max-connections
0
The maximum number of concurrent connections to allow to any particular connection, where "0" represents unlimited. By default, no overall concurrency limits are enforced on connections.
postgresql-default-max-group-connections
0
The maximum number of concurrent connections to allow to any particular balancing connection group, where "0" represents unlimited. By default, no overall concurrency limits are enforced on connection groups.
postgresql-default-max-connections-per-user
0
The maximum number of concurrent connections to allow to any individual user to establish to a connection, where "0" represents unlimited. By default, no per-user concurrency limits are enforced on connections.
postgresql-default-max-group-connections-per-user
1
The maximum number of concurrent connections to allow to any individual user to establish to a balancing connection group, where "0" represents unlimited. By default, no each user is limited to a single connection for each balancing connection group, to avoid allowing any one user to exhaust the available connections within that group..
postgresql-absolute-max-connections
0
The absolute maximum number of concurrent connections to allow to the Guacamole server as a whole, regardless of which users are establishing those connections and which connections or groups are being accessed, where "0" represents unlimited. By default, no absolute concurrent restrictions are enforced.
Whether authentication via other extensions is allowed for users that do not exist within the PostgreSQL database. If set to "true", authentication attempts will be denied unless the authenticated user has been defined within the database.
postgresql-user-required
false
If set to "true", require that all successful authentication attempts be associated with a user defined within PostgreSQL. If a user authentications successfully via another mechanism (such as LDAP), that attempt will still be denied if no corresponding PostgreSQL user exists. By default, successful authentication attempts will be considered successful regardless of whether an account for that user exists within PostgreSQL.
Advanced configuration properties for SAML 2.0 SSO
The properties listed here are only applicable if SAML 2.0 authentication is being used. Support for SAML 2.0 authentication is installed using package or enabled with the Docker installation. If using the Docker image, support for SAML 2.0 authentication is configured using environment variables.
Keeper Connection Manager loads authentication extensions in order of priority, and evaluates authentication attempts in this same order. This has implications for how the login process behaves when an SSO extension is present:
If the SSO extension has priority:
Users that are not yet authenticated will be immediately redirected to the configured identity provider. They will not see a Keeper Connection Manager login screen.
If a non-SSO extension has priority:
Users that are not yet authenticated will be presented with a Keeper Connection Manager login screen. Additionally, links to the configured identity provider(s) will be available for users that wish to log in using SSO.
The default priority of extensions is dictated by their filenames, with extensions that sort earlier alphabetically having higher priority than others. This can be overridden by setting the extension-priority
property within guacamole.properties
.
Automatically redirecting all unauthenticated users
To ensure users are redirected to the SAML identity provider immediately (without a Keeper Connection Manager login screen), ensure the SAML extension has priority over all others:
Presenting unauthenticated users with a login screen
To ensure users are given a normal Keeper Connection Manager login screen and have the option to log in with traditional credentials or with SAML, ensure the SAML extension does not have priority:
saml-idp-metadata-url
The URI of the XML metadata file that from the SAML Identity Provider that contains all of the information the SAML extension needs in order to know how to authenticate with the IdP. This URI can either be a remote server (e.g. https://
) or a local file on the filesystem (e.g. file://
). Often the metadata file contains most of the required properties for SAML authentication and the other parameters are not required.
saml-idp-url
The base URL of the SAML IdP. This is the URL that the SAML authentication extension will use to redirect when requesting SAML authentication. If the saml-idp-metadata-url
property is provided, this parameter will be ignored. If the metadata file is not provided this property is required.
saml-entity-id
The entity ID of the Keeper Connection Manager SAML client, which is generally the URL of the Keeper Connection Manager server, but is not required to be so. This property is required if either the saml-idp-metadata-url
property is not specified, or if the provided metadata file does not contain the SAML SP Entity ID for the Keeper Connection Manager Client.
saml-callback-url
The URL that the IdP will use once authentication has succeeded to return to the Keeper Connection Manager web application and provide the authentication details to the SAML extension. The SAML extension currently only supports callback as a POST operation to this callback URL. This property is required.
saml-strict
Require strict security checks during SAML logins. This will insure that valid certificates are present for all interactions with SAML servers and fail SAML authentication if security restrictions are violated. This property is optional, and will default to true, requiring strict security checks. This property should only be set to false in non-production environments during testing of SAML authentication.
saml-debug
Enable additional logging within the supporting SAML library that can assist in tracking down issues during SAML logins. This property is optional, and will default to false (no debugging).
saml-compress-request
Enable compression of the HTTP requests sent to the SAML IdP. This property is optional and will default to true (compression enabled).
saml-compress-response
Request that the SAML response returned by the IdP be compressed. This property is optional and will default to "true" (compression will be requested).
saml-group-attribute
The name of the attribute provided by the SAML IdP that contains group membership of the user. These groups will be parsed and used to map group membership of the user logging in, which can be used for permissions management within the Keeper Connection Manager Client, particularly when layered with other authentication modules. This property is optional, and defaults to “groups”.
saml-private-key-path
Path to a private key for use with connecting to an ID Provider which is configured to expect signed requests
saml-x509-cert-path
Path to a certificate used to authenticate to an ID Provider which is configured to expect signed requests
Advanced configuration properties for Encrypted JSON Auth
The properties listed here are only applicable if encrypted JSON authentication is being used. Support for encrypted JSON authentication is installed using the kcm-guacamole-auth-json
package. If using the keeper/guacamole Docker image, support for encrypted JSON authentication is instead configured using environment variables.
A shared secret key is used by systems generating JSON data to encrypt and sign the JSON, and by the Guacamole server to verify and decrypt received data. This key must be 128 bits, specified with 32 hexadecimal digits.
json-secret-key
The 128-bit secret key that will be used to encrypt and sign JSON sent to Guacamole for authentication, formatted as 32 hexadecimal digits. Received JSON will not be accepted unless it has been encrypted and signed using this key.
This key can be essentially anything as long as it is unpredictable. An easy way of generating such a key is to echo a passphrase through the "md5sum" utility. This is the technique OpenSSL itself uses to generate 128-bit keys from passphrases. For example:
By default, received encrypted JSON will be accepted as long as it is valid and properly signed with the secret key. This can be further restricted to accept encrypted JSON only from machines which match a comma-separated list of trusted IP addresses and/or CIDR subnets.
json-trusted-networks
A comma-separated list of IP addresses and/or CIDR subnets which should be allowed to authenticate using encrypted JSON. By default, encrypted JSON is accepted without restriction from any address or subnet.