keeper/guacamole
Docker deployment of Apache Guacamole with Keeper Connection Manager
Image:
keeper/guacamole
To activate advanced features of Keeper Connection Manager, you simply add an environmental variable to the docker file that controls the feature, or you add one of the EXTENSIONS flags as documented below.
Arbitrary third-party extensions may be used through volume mounts and setting
ADDITIONAL_GUACAMOLE_PROPERTIES
variables as needed.The Guacamole logs are useful if debugging unexpected behavior of the aspects of the web application which are not directly related to remote desktop, including authentication. To view the Tomcat/Guacamole logs follow the troubleshooting documentation.
By default, these logs will show messages only at the "info" level or above. This can be overridden when the container is created using the
LOG_LEVEL
environment variable.The
ACCEPT_EULA
environment variable must be set to "Y" to indicate your acceptance of the Keeper Connection Manager EULA. This Docker image may not be used except under the terms of the EULA.This variable is optional and specifies any additional content that should be appended to
/etc/guacamole/guacamole.properties
during startup. This content is added via guacamole.properties.docker
, thus environment variable substitution will be automatically performed on the content of this variable.This variable is optional and restricts the display languages within Guacamole to the comma-separated list of language keys. 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. 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.By default, all defined languages will be available.
All environment variables which start with
API_
correspond to configuration properties for configuring the Guacamole web application as a whole. These variables control how Guacamole handles user sessions and any HTTP requests that it receives. Note that these variables control only aspects of the Guacamole web application. They do not control the behavior of remote desktop sessions.Variable name | Description |
---|---|
API_MAX_REQUEST_SIZE | 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. By default, requests are limited to 2097152 bytes (2 MB). |
API_SESSION_TIMEOUT | The amount of time, in minutes, a Guacamole session may remain valid despite being inactive. By default, Guacamole sessions are limited to one hour. 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. |
All environment variables which start with
AWS_DISCOVERY_
correspond to configuration properties for AWS EC2 discovery which would normally be specified within guacamole.properties
.The following environment variables are required if using EC2 discovery:
Variable name | Description |
---|---|
AWS_DISCOVERY_ACCESS_KEY_ID | The access key ID for the AWS account that should be used to authenticate with AWS. |
AWS_DISCOVERY_SECRET_KEY | The secret key associated with the access key |
AWS_DISCOVERY_REGIONS | Comma-separated list of regions to query for EC2 instances, such as us-west-1,us-east-1 . |
Other, optional environment variables are available for the other properties related to EC2 discovery:
Variable name | Description |
---|---|
AWS_DISCOVERY_INSTANCE_BASE_PATH | The name of the organizational connection group that should be used to house the EC2 instances for convenience. By default, this will be "Amazon EC2". |
AWS_DISCOVERY_ADMIN_GROUP | The name of the User Group in Keeper Connection Manager to require for any user to see the discovered EC2 instances. By default, this will be a group called "AWS EC2 Administrators". |
AWS_DISCOVERY_RECORD_CONNECTIONS_BY_DEFAULT | If set to "true", screen recording will be enabled by default on all connections. Connection session recording can also be set at an individual machine level using the " kcm:record " EC2 instance tag, which overrides the value set here, if any. |
AWS_DISCOVERY_KSM_CONFIG | The base64-encoded Keeper Secrets Manager configuration to use to retrieve the private keys for EC2 instances from the Keeper vault. |
AWS_DISCOVERY_KSM_API_CALL_INTERVAL | The minimum number of milliseconds that must elapse between API calls to Keeper Secrets Manager. By default, KCM will wait 10 seconds between each call, using cached data from the last retrieval until another retrieval attempt is allowed. |
All environment variables which start with
BAN_
correspond to configuration properties for configuring how apparent brute-force authentication attempts against the web application are automatically blocked. Each of these variables is optional.Variable name | Text |
---|---|
BAN_ADDRESS_DURATION | The amount of time an IP address is temporarily blocked after repeatedly failing to authenticate, in seconds. By default, addresses are blocked for 5 minutes. |
BAN_MAX_ADDRESSES | The maximum number of IP addresses that KCM will track to check for invalid attempts. By default, up to 10485760 addresses will be tracked. |
BAN_MAX_INVALID_ATTEMPTS | The number of invalid attempts that may occur before the source IP address is temporarily blocked from further attempts. By default, 5 failed authentication attempts will result in a temporary block. |
This variable is optional and specifies the path that the Guacamole web application should be served under. By default, the web application will be served at the root directory (
http://your-container:8080/
), but this can be overridden by setting CONTEXT_PATH
to the name of a different location.Note that the location specified with
CONTEXT_PATH
may not contain slashes. If you need to serve the web application beneath a more complex nested path, you will need to use a reverse proxy like Nginx or Apache HTTPD.The following environment variables are required if using Duo multi-factor authentication:
Variable name | Description |
---|---|
DUO_API_HOSTNAME | The hostname of the Duo API endpoint that will be used to verify user identities, assigned by Duo when Guacamole was added as a "Web SDK" application. This value can be found within the application details in Duo's "Admin" panel. |
DUO_INTEGRATION_KEY | The integration key provided for you by Duo when Guacamole was added as a "Web SDK" application. This value can be found within the application details in Duo's "Admin" panel. |
DUO_SECRET_KEY | The secret key provided for you by Duo when Guacamole was added as a "Web SDK" application. This value can be found within the application details in Duo's "Admin" panel. |
DUO_APPLICATION_KEY | An arbitrary, random key consisting of at least 40 characters. This value must be manually generated specifically for this deployment of Guacamole. |
This variable is optional and specifies a comma- or newline-separated list of the names of all extensions that should be activated in the image, regardless of which other environment variables may be specified. Empty names, whitespace, and trailing commas are ignored.
Extension names are dictated by the
guacamole(*)
package capability of the corresponding Keeper Connection Manager package (part of the RPM package's metadata):Extension name | Declared capability | Corresponding package |
---|---|---|
duo | guacamole(duo) | |
json | guacamole(json) | |
ldap | guacamole(ldap) | |
mysql | guacamole(mysql) | |
openid | guacamole(openid) | |
postgresql | guacamole(postgresql) | |
saml | guacamole(saml) | |
sqlserver | guacamole(sqlserver) | |
ssl | guacamole(ssl) | |
totp | guacamole(totp) | |
uds | guacamole(uds) |
This variable is mainly of use for extensions which can be used without setting any configuration options, like TOTP two-factor authentication, or to force sanity checks on the presence of required environment variables even if all associated variables might be accidentally omitted. Extensions not listed within this environment variable will still be included if any of their corresponding environment variables are set.
This variable is optional and specifies the order that extensions should be loaded relative to each other. By default, extensions are loaded in alphabetical order based on their filenames.
To override the load order of extensions, list the names of each extension that should be loaded first, separated by commas. The special name
*
may be used as a placeholder for all other extensions. For example:Description | Value of EXTENSION_PRIORITY |
---|---|
Force SAML to take priority over all other extensions. | saml |
Force all other extensions to take priority over SAML. | *, saml |
Prefer LDAP over any other authentication method, and force all other extensions to take priority over SAML and OpenID. | ldap, *, saml, openid |
TCP connection information for guacd.
Variable name | Description |
---|---|
GUACD_HOSTNAME | The hostname of the machine hosting the guacd service. |
Other, optional environment variables are available for configuring other aspects of the connection to guacd:
Variable name | Description |
---|---|
GUACD_PORT | The port used by the guacd service. |
GUACD_SSL | Whether the guacd service has been configured for SSL/TLS. |
All environment variables which start with
JSON_
correspond to configuration properties for encrypted JSON authentication which would normally be specified within guacamole.properties
.The following environment variables are required if using encrypted JSON authentication:
Variable name | Description |
---|---|
JSON_SECRET_KEY | The shared secret key that will be used by systems generating JSON data to encrypt and sign that data. This key must be 128 bits, specified with 32 hexadecimal digits. |
Other, optional environment variables are available for the other properties related to encrypted JSON authentication:
Variable name | Description |
---|---|
JSON_TRUSTED_NETWORKS | A comma-separated list of trusted IP addresses and/or CIDR subnets which should be allowed to send encrypted JSON. If omitted, any address will be allowed to send JSON. |
All environment variables which start with
KSM_*
correspond to configuration properties for Keeper Secrets Manager. See the Keeper Vault Integration guide.Variable name | Description |
---|---|
KSM_ALLOW_USER_CONFIG | If set to "true", users will be allowed to provide their own KSM configuration or one-time token. Vault records of users that provide this will be additionally considered for any connection that (1) an administrator enables for use with user vaults and (2) contains a token that cannot be satisfied with a record from the system-wide vault configured with KSM_CONFIG . By default, users are not allowed to provide their own KSM configuration. |
KSM_API_CALL_INTERVAL | The minimum number of milliseconds that must elapse between API calls to Keeper Secrets Manager. By default, KCM will wait 10 seconds between each call, using cached data from the last retrieval until another retrieval attempt is allowed. |
KSM_CONFIG | The Keeper Secrets Manager b64 configuration, generated by Keeper Commander. |
KSM_MATCH_DOMAINS_FOR_USERS | If set to "true", Active Directory domains within KSM records and KCM connections will be considered when determining whether a record matches a username. By default, only the username itself is considered. |
KSM_STRIP_WINDOWS_DOMAINS | If set to "true", Active Directory domains within KSM records will be alternatively determined by splitting the record username into username and domain components. Splitting is performed based on the User Principal Name and Down-Level Logon Name formats. By default, usernames are not split, and Windows domains will be read only from a separate "Domain" field on the record. |
KSM_TOKEN_MAPPING | Static tokens used to identify specific Keeper vault records and fields. |
*_KSM_SECRET | Used for protection and storage of configuration values in the Keeper vault. |
All environment variables which start with
LDAP_
correspond to configuration properties for LDAP authentication which would normally be specified within guacamole.properties
.The following environment variables are required if using LDAP authentication (for a single LDAP server):
Variable name | Description |
---|---|
LDAP_HOSTNAME | The hostname or IP address of the LDAP server that Guacamole should use for authentication. |
LDAP_USER_BASE_DN | The common base DN shared by all Guacamole users within the LDAP directory. |
If using multiple LDAP servers, or if you prefer to provide LDAP server configuration in YAML format, the following environment variable is required:
Variable name | Description |
---|---|
LDAP_SERVERS | The full contents of the ldap-servers.yml file describing the LDAP servers that Guacamole should use for authentication. |
Other, optional environment variables are available for the other properties related to LDAP authentication:
Variable name | Description |
---|---|
LDAP_PORT | The TCP port that the LDAP server is listening on. If omitted, the standard LDAP or LDAPS port will be used, depending on the encryption method. Unencrypted LDAP uses the standard port of 389, while LDAPS uses port 636. |
LDAP_ENCRYPTION_METHOD | The encryption mechanism to use when communicating with your LDAP server, if any. Legal values are "none" for unencrypted LDAP, "ssl" for LDAP over SSL/TLS (commonly known as LDAPS), or "starttls" for STARTTLS. If omitted, encryption will not be used. |
LDAP_NETWORK_TIMEOUT | The maximum amount of time to allow for any LDAP network operation, in milliseconds, including attempts to connect to the LDAP server. By default, LDAP network operations will time out after 30 seconds (30000 milliseconds). Note that this value is intentionally more granular than LDAP_OPERATION_TIMEOUT , as failover to alternative LDAP servers may need to occur quickly if multiple LDAP servers are configured. |
LDAP_OPERATION_TIMEOUT | The maximum amount of time to allow for any LDAP query, in seconds. By default, LDAP queries will time out after 30 seconds. |
LDAP_USERNAME_ATTRIBUTE | The attribute which contains the username within all relevant user objects in the LDAP directory. If multiple attributes may contain the username, multiple attributes may be specified separated by commas, and a search DN is required. |
LDAP_SEARCH_BIND_DN | The DN that the web application should bind as when determining the DN of the user attempting to authenticate. Specifying a search DN is required if usernames may be within any one of several attributes, or if the user's username is not part of their DN. |
LDAP_SEARCH_BIND_PASSWORD | The password to use when authenticating with the search DN. |
LDAP_CONFIG_BASE_DN | The common base DN shared by all guacConfigGroup objects, if the LDAP directory is being used to store connection data. |
LDAP_GROUP_BASE_DN | The common base DN shared by all user groups which may dictate guacConfigGroup access within the LDAP directory via the seeAlso attribute. |
LDAP_MAX_SEARCH_RESULTS | The maximum number of results to attempt to retrieve from the LDAP directory for any particular search. Searches which exceed this limit will fail. By default, searches are limited to 1000 entries. |
LDAP_USER_SEARCH_FILTER | The LDAP search filter to use when querying user accounts. If omitted, (objectClass=*) will be used by default. |
LDAP_GROUP_SEARCH_FILTER | The LDAP search filter to use when retrieving groups. If omitted, (objectClass=*) will be used by default. |
LDAP_DEREFERENCE_ALIASES | Whether aliases should be automatically dereferenced. Legal values are "never", "searching" (dereference only after the base DN is located), "finding" (dereference only when locating the base DN), and "always". By default, aliases are not derefenced. |
LDAP_FOLLOW_REFERRALS | If "true", automatically follow referrals received from the LDAP directory. By default, LDAP referrals are not followed. |
LDAP_MAX_REFERRAL_HOPS | The maximum number of referrals that may be followed when resolving any particular LDAP referral. By default, if LDAP automatic following of referrals is enabled, up to 5 hops are allowed for any one referral. |
CA_CERTIFICATES | The contents of one or more certificates used by your internal certificate authority (CA), in PEM form. When specified, SSL/TLS connections to other servers will be verified against these certificates, including connections to LDAP servers that use SSL/TLS. |
This variable is optional and specifies the lowest level of log message that should be displayed. In order of increasing verbosity, valid values are: "error", "warn", "info", "debug", "trace".
The default log level is "info".
All environment variables which start with
MYSQL_
correspond to configuration properties for MySQL authentication which would normally be specified within guacamole.properties
.If intending to use MySQL, you may wish to use the
keeper/guacamole-db-mysql
image which provides a MySQL database that is automatically initialized for use by Guacamole.The following environment variables are required if using MySQL authentication:
Variable name | Description |
---|---|
MYSQL_HOSTNAME | The hostname or IP address of the MySQL or MariaDB server hosting the Guacamole database. |
MYSQL_DATABASE | The name of the database that has been created for Guacamole on the MySQL or MariaDB server. |
MYSQL_USERNAME | The username that Guacamole should use when authenticating with the MySQL or MariaDB server. |
MYSQL_PASSWORD | The password that Guacamole should provide when authenticating with the MySQL or MariaDB server. |
Other, optional environment variables are available for the other properties related to MySQL authentication:
Variable name | Description |
---|---|
MYSQL_PORT | The TCP port that the MySQL or MariaDB server is listening on. If omitted, the standard MySQL port of 3306 will be used. |
MYSQL_USER_PASSWORD_MIN_LENGTH | The minimum length to require for user passwords. By default, password complexity is not enforced. |
MYSQL_USER_PASSWORD_REQUIRE_MULTIPLE_CASE | If set to "true", require that user passwords use both uppercase and lowercase characters. |
MYSQL_USER_PASSWORD_REQUIRE_SYMBOL | If set to "true", require that user passwords contain at least one symbol. By default, password complexity is not enforced. |
MYSQL_USER_PASSWORD_REQUIRE_DIGIT | If set to "true", require that user passwords contain at least one digit. By default, password complexity is not enforced. |
MYSQL_USER_PASSWORD_PROHIBIT_USERNAME | If set to "true", disallow user passwords that contain the user's username. By default, password complexity is not enforced. |
MYSQL_USER_PASSWORD_MIN_AGE | The minimum number of days that must elapse following a password change before the user may change their password again. By default, users are not required to wait before changing their password. |
MYSQL_USER_PASSWORD_MAX_AGE | The maximum number of days that may elapse since the last password change before the user is required to change their password. By default, users are not required to regularly change their password. |
MYSQL_USER_PASSWORD_HISTORY_SIZE | Remember this number of previous passwords and prohibit reuse of those passwords when the user's password is changed. By default, users are allowed to reuse previous passwords. |
MYSQL_DEFAULT_MAX_CONNECTIONS | The maximum number of concurrent connections to allow to any particular connection, regardless of user, where a value of "0" indicates unlimited. By default, concurrent usage of connections is not limited. |
MYSQL_DEFAULT_MAX_GROUP_CONNECTIONS | The maximum number of concurrent connections to allow to any particular connection group, regardless of user, where a value of "0" indicates unlimited. By default, concurrent usage of connection groups is not limited. |
MYSQL_DEFAULT_MAX_CONNECTIONS_PER_USER | The maximum number of concurrent connections to allow each user to hold to any particular connection, where a value of "0" indicates unlimited. By default, user-specific concurrent usage of connections is not limited. |
MYSQL_DEFAULT_MAX_GROUP_CONNECTIONS_PER_USER | The maximum number of concurrent connections to allow each user to hold to any particular connection group, where a value of "0" indicates unlimited. By default, user-specific concurrent usage of connection groups is limited to one. |
MYSQL_ABSOLUTE_MAX_CONNECTIONS | The maximum number of concurrent connections to allow to overall, regardless of user, connection or connection group, where a value of "0" indicates unlimited. By default, overall concurrent usage is not limited. |
MYSQL_USER_REQUIRED | If set to "true", require that each user have a corresponding account defined within the database, even if the user authenticated through some other mechanism (such as LDAP). By default, users that successfully authenticate through another mechanism are not required to also have an account within the database. |
MYSQL_TRACK_EXTERNAL_CONNECTION_HISTORY | Whether connections that do not exist within the database should have connection history tracked in the database. If set to "true", connection history records will be created for any connection established. If set to "false", connection history records will be created only for connections defined in the database. By default, external connections will be tracked. |
MYSQL_ENFORCE_ACCESS_WINDOWS_FOR_ACTIVE_SESSIONS | Whether access time restrictions imposed by the administrator on user accounts should be enforced while a user is logged in. If set to "true", users will be automatically logged out within roughly one minute of reaching their access time limits. If set to "false", access time restrictions will only be enforced at the moment a user attempts to log in. By default, access time restrictions are enforced while users are logged in. |
MYSQL_AUTO_CREATE_ACCOUNTS | Whether user account entries should automatically be created within the database for users that successfully authenticate through other means, such as an SSO provider or LDAP. This may be necessary if using an extension that requires account-specific storage, like TOTP or per-account approvals. If set to "true", user account entries will automatically be created. By default, administrators must manually create such entries if needed. |
All environmental variables which start with OPENID_ correspond to configuration properties for Open ID Connect authentication which would normally be specified within guacamole.properties.
Variable Name | Description |
---|---|
OPENID_AUTHORIZATION_ENDPOINT | The authorization endpoint (URI) of the OpenID service. This value should be provided to you by the identity provider. For identity providers that implement OpenID Connect Discovery, this value can be retrieved from the "authorization_endpoint" property of your provider's ".well-known/openid-configuration" JSON file. |
OPENID_CLIENT_ID | The OpenID client ID which should be submitted to the OpenID service when necessary. This value is typically provided to you by the OpenID service when OpenID credentials are generated for your application. |
OPENID_ISSUER | The issuer to expect for all received ID tokens. This value should be provided to you by the identity provider. For identity providers that implement OpenID Connect Discovery, this value can be retrieved from the "issuer" property of your provider's ".well-known/openid-configuration" JSON file. |
OPENID_JWKS_ENDPOINT | The endpoint (URI) of the JWKS service which defines how received ID tokens (JSON Web Tokens or JWTs) shall be validated. This value should be provided to you by the identity provider. For identity providers that implement OpenID Connect Discovery, this value can be retrieved from the "jwks_uri" property of your provider's ".well-known/openid-configuration" JSON file. |
OPENID_REDIRECT_URI | The URI that should be submitted to the OpenID service such that they can redirect the authenticated user back to Keeper Connection Manager after the authentication process is complete. This must be the full URL that a user would enter into their browser to access Keeper Connection Manager. The URI that should be submitted to the OpenID service such that they can redirect the authenticated user back to Keeper Connection Manager after the authentication process is complete. This must be the full URL that a user would enter into their browser to access Keeper Connection Manager. |
Optional variables:
Variable Name | Description |
---|---|
OPENID_ALLOWED_CLOCK_SKEW | The amount of clock skew tolerated for timestamp comparisons between the Guacamole server and OpenID service clocks, in seconds. By default, clock skew of up to 30 seconds is tolerated. |
OPENID_GROUPS_CLAIM_TYPE | The claim type within any valid JWT that contains the list of groups of which the authenticated user is a member. By default, the “groups” claim type is used. |
OPENID_MAX_NONCE_VALIDITY | The maximum amount of time that a nonce generated by the Guacamole server should remain valid, in minutes. As each OpenID request has a unique nonce value, this imposes an upper limit on the amount of time any particular OpenID request can result in successful authentication within Guacamole. By default, each generated nonce expires after 10 minutes. |
OPENID_MAX_TOKEN_VALIDITY | The maximum amount of time that an OpenID token should remain valid, in minutes. By default, each OpenID token remains valid for 300 minutes (5 hours). |
OPENID_SCOPE | The space-separated list of OpenID scopes to request. OpenID scopes determine the information returned within the OpenID token, and thus affect what values can be used as an authenticated user’s username. To be compliant with OpenID, at least “openid profile” must be requested. By default, “openid email profile” is used. |
OPENID_USERNAME_CLAIM_TYPE | The claim type within any valid JWT that contains the list of groups of which the authenticated user is a member. By default, the “groups” claim type is used. |
All environment variables which start with
POSTGRES_
correspond to configuration properties for PostgreSQL authentication which would normally be specified within guacamole.properties
.If intending to use PostgreSQL, you may wish to use the
keeper/guacamole-db-postgres
image which provides a PostgreSQL database that is automatically initialized for use by Guacamole.The following environment variables are required if using PostgreSQL authentication:
Variable name | Description |
---|---|
POSTGRES_HOSTNAME | The hostname or IP address of the PostgreSQL server hosting the Guacamole database. |
POSTGRES_DATABASE | The name of the database that has been created for Guacamole on the PostgreSQL server. |
POSTGRES_USERNAME | The username that Guacamole should use when authenticating with the PostgreSQL server. |
POSTGRES_PASSWORD | The password that Guacamole should provide when authenticating with the PostgreSQL server. |
Other, optional environment variables are available for the other properties related to PostgreSQL authentication:
Variable name | Description |
---|---|
POSTGRES_PORT | The TCP port that the PostgreSQL server is listening on. If omitted, the standard PostgreSQL port of 5432 will be used. |
POSTGRES_USER_PASSWORD_MIN_LENGTH | The minimum length to require for user passwords. By default, password complexity is not enforced. |
POSTGRES_USER_PASSWORD_REQUIRE_MULTIPLE_CASE | If set to "true", require that user passwords use both uppercase and lowercase characters. |
POSTGRES_USER_PASSWORD_REQUIRE_SYMBOL | If set to "true", require that user passwords contain at least one symbol. By default, password complexity is not enforced. |
POSTGRES_USER_PASSWORD_REQUIRE_DIGIT | If set to "true", require that user passwords contain at least one digit. By default, password complexity is not enforced. |
POSTGRES_USER_PASSWORD_PROHIBIT_USERNAME | If set to "true", disallow user passwords that contain the user's username. By default, password complexity is not enforced. |
POSTGRES_USER_PASSWORD_MIN_AGE | The minimum number of days that must elapse following a password change before the user may change their password again. By default, users are not required to wait before changing their password. |
POSTGRES_USER_PASSWORD_MAX_AGE | The maximum number of days that may elapse since the last password change before the user is required to change their password. By default, users are not required to regularly change their password. |
POSTGRES_USER_PASSWORD_HISTORY_SIZE | Remember this number of previous passwords and prohibit reuse of those passwords when the user's password is changed. By default, users are allowed to reuse previous passwords. |
POSTGRES_DEFAULT_MAX_CONNECTIONS | The maximum number of concurrent connections to allow to any particular connection, regardless of user, where a value of "0" indicates unlimited. By default, concurrent usage of connections is not limited. |
POSTGRES_DEFAULT_MAX_GROUP_CONNECTIONS | The maximum number of concurrent connections to allow to any particular connection group, regardless of user, where a value of "0" indicates unlimited. By default, concurrent usage of connection groups is not limited. |
POSTGRES_DEFAULT_MAX_CONNECTIONS_PER_USER | The maximum number of concurrent connections to allow each user to hold to any particular connection, where a value of "0" indicates unlimited. By default, user-specific concurrent usage of connections is not limited. |
POSTGRES_DEFAULT_MAX_GROUP_CONNECTIONS_PER_USER | The maximum number of concurrent connections to allow each user to hold to any particular connection group, where a value of "0" indicates unlimited. By default, user-specific concurrent usage of connection groups is limited to one. |
POSTGRES_ABSOLUTE_MAX_CONNECTIONS | The maximum number of concurrent connections to allow to overall, regardless of user, connection or connection group, where a value of "0" indicates unlimited. By default, overall concurrent usage is not limited. |
POSTGRES_USER_REQUIRED | If set to "true", require that each user have a corresponding account defined within the database, even if the user authenticated through some other mechanism (such as LDAP). By default, users that successfully authenticate through another mechanism are not required to also have an account within the database. |
POSTGRESQL_TRACK_EXTERNAL_CONNECTION_HISTORY | Whether connections that do not exist within the database should have connection history tracked in the database. If set to "true", connection history records will be created for any connection established. If set to "false", connection history records will be created only for connections defined in the database. By default, external connections will be tracked. |
POSTGRESQL_ENFORCE_ACCESS_WINDOWS_FOR_ACTIVE_SESSIONS | Whether access time restrictions imposed by the administrator on user accounts should be enforced while a user is logged in. If set to "true", users will be automatically logged out within roughly one minute of reaching their access time limits. If set to "false", access time restrictions will only be enforced at the moment a user attempts to log in. By default, access time restrictions are enforced while users are logged in. |
POSTGRESQL_AUTO_CREATE_ACCOUNTS | Whether user account entries should automatically be created within the database for users that successfully authenticate through other means, such as an SSO provider or LDAP. This may be necessary if using an extension that requires account-specific storage, like TOTP or per-account approvals. If set to "true", user account entries will automatically be created. By default, administrators must manually create such entries if needed. |
This variable is optional and specifies the extensions that should require explicit approval from an administrator on a per-account basis before they can be used to authenticate a user. By default, any installed authentication method may be used.
To require approval for particular authentication methods, list the names of each extension that should require approval, separated by commas. For example:
Description | Value of REQUIRE_ACCOUNT_APPROVAL |
---|---|
Require approval for logins from SAML. | saml |
Require approval for logins from SAML and LDAP. | saml, ldap |
Account approval status can only be stored and enforced on users with identities in the KCM database. Depending on which database you are using, you can request that KCM automatically create this storage for accounts that do not yet exist within the database by setting one of the following environment variables to "true":
All environment variables which start with
SAML_
correspond to configuration properties for SAML Authentication which would normally be specified within guacamole.properties
.The following environment variables are required if using SAML authentication:
Variable Name | Description |
---|---|
SAML_CALLBACK_URL | The URI that should be submitted to the SAML service such that they can POST the authentication result to Keeper Connection Manager and redirect the user back to the application. This must be the full URL that a user would enter into their browser to access Keeper Connection Manager. |
Optional environmental variables:
Variable Name | Description |
---|---|
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_ENTITY_ID | The entity ID of the Guacamole SAML client, which is generally the URL of the Guacamole 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 Guacamole Client. |
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 Guacamole Client, particularly when layered with other authentication modules. This property is optional, and defaults to “groups”. |
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_PRIVATE_KEY_PATH | The full path of the private key in PEM format that should be used to sign SAML requests submitted to the SAML IdP. This is required only if the SAML IdP requires signed requests. By default, SAML requests are not signed. |
SAML_X509_CERT_PATH | The full path of the X.509 certificate in PEM format that should be used to sign SAML requests submitted to the SAML IdP. This is required only if the SAML IdP requires signed requests. By default, SAML requests are not signed. |
All environment variables which start with
SQLSERVER_
correspond to configuration properties for SQL Server authentication which would normally be specified within guacamole.properties
.The following environment variables are required if using SQL Server authentication:
Variable name | Description |
---|---|
SQLSERVER_HOSTNAME | The hostname or IP address of the SQL Server instance hosting the Guacamole database. |
SQLSERVER_DATABASE | The name of the database that has been created for Guacamole on the SQL Server instance. |
SQLSERVER_USERNAME | The username that Guacamole should use when authenticating with the SQL Server instance. |
SQLSERVER_PASSWORD | The password that Guacamole should provide when authenticating with the SQL Server instance. |
Other, optional environment variables are available for the other properties related to SQL Server authentication:
Variable name | Description |
---|---|
SQLSERVER_PORT | The TCP port that the SQL Server instance is listening on. If omitted, the standard SQL Server port of 1433 will be used. |
SQLSERVER_USER_PASSWORD_MIN_LENGTH | The minimum length to require for user passwords. By default, password complexity is not enforced. |
SQLSERVER_USER_PASSWORD_REQUIRE_MULTIPLE_CASE | If set to "true", require that user passwords use both uppercase and lowercase characters. |
SQLSERVER_USER_PASSWORD_REQUIRE_SYMBOL | If set to "true", require that user passwords contain at least one symbol. By default, password complexity is not enforced. |
SQLSERVER_USER_PASSWORD_REQUIRE_DIGIT | If set to "true", require that user passwords contain at least one digit. By default, password complexity is not enforced. |
SQLSERVER_USER_PASSWORD_PROHIBIT_USERNAME | If set to "true", disallow user passwords that contain the user's username. By default, password complexity is not enforced. |
SQLSERVER_USER_PASSWORD_MIN_AGE | The minimum number of days that must elapse following a password change before the user may change their password again. By default, users are not required to wait before changing their password. |
SQLSERVER_USER_PASSWORD_MAX_AGE | The maximum number of days that may elapse since the last password change before the user is required to change their password. By default, users are not required to regularly change their password. |
SQLSERVER_USER_PASSWORD_HISTORY_SIZE | Remember this number of previous passwords and prohibit reuse of those passwords when the user's password is changed. By default, users are allowed to reuse previous passwords. |
SQLSERVER_DEFAULT_MAX_CONNECTIONS | The maximum number of concurrent connections to allow to any particular connection, regardless of user, where a value of "0" indicates unlimited. By default, concurrent usage of connections is not limited. |
SQLSERVER_DEFAULT_MAX_GROUP_CONNECTIONS | The maximum number of concurrent connections to allow to any particular connection group, regardless of user, where a value of "0" indicates unlimited. By default, concurrent usage of connection groups is not limited. |
SQLSERVER_DEFAULT_MAX_CONNECTIONS_PER_USER | The maximum number of concurrent connections to allow each user to hold to any particular connection, where a value of "0" indicates unlimited. By default, user-specific concurrent usage of connections is not limited. |
SQLSERVER_DEFAULT_MAX_GROUP_CONNECTIONS_PER_USER | The maximum number of concurrent connections to allow each user to hold to any particular connection group, where a value of "0" indicates unlimited. By default, user-specific concurrent usage of connection groups is limited to one. |
SQLSERVER_ABSOLUTE_MAX_CONNECTIONS | The maximum number of concurrent connections to allow to overall, regardless of user, connection or connection group, where a value of "0" indicates unlimited. By default, overall concurrent usage is not limited. |
SQLSERVER_USER_REQUIRED | If set to "true", require that each user have a corresponding account defined within the database, even if the user authenticated through some other mechanism (such as LDAP). By default, users that successfully authenticate through another mechanism are not required to also have an account within the database. |
SQLSERVER_TRACK_EXTERNAL_CONNECTION_HISTORY | Whether connections that do not exist within the database should have connection history tracked in the database. If set to "true", connection history records will be created for any connection established. If set to "false", connection history records will be created only for connections defined in the database. By default, external connections will be tracked. |
SQLSERVER_ENFORCE_ACCESS_WINDOWS_FOR_ACTIVE_SESSIONS | Whether access time restrictions imposed by the administrator on user accounts should be enforced while a user is logged in. If set to "true", users will be automatically logged out within roughly one minute of reaching their access time limits. If set to "false", access time restrictions will only be enforced at the moment a user attempts to log in. By default, access time restrictions are enforced while users are logged in. |
SQLSERVER_AUTO_CREATE_ACCOUNTS | Whether user account entries should automatically be created within the database for users that successfully authenticate through other means, such as an SSO provider or LDAP. This may be necessary if using an extension that requires account-specific storage, like TOTP or per-account approvals. If set to "true", user account entries will automatically be created. By default, administrators must manually create such entries if needed. |
All environment variables which start with
SSL_
correspond to configuration properties for SSL/TLS client authentication (smart card authentication) which would normally be specified within guacamole.properties
.The following environment variables are required if using SSL/TLS client authentication:
Variable name | Description |
---|---|
SSL_CLIENT_AUTH_URI | A wildcard URI that points to this Guacamole instance and requests SSL/TLS client authentication. |
SSL_PRIMARY_URI | A non-wildcard URI that points to this Guacamole instance and does not request SSL/TLS client authentication. |
SSL_EXTERNAL_PORT | Custom user-facing TCP port.
Specified if not using the standard HTTPS port 443 |
Other, optional environment variables are available for the other properties related to SSL/TLS client authentication:
Variable name | Description |
---|---|
SSL_CLIENT_CERTIFICATE_HEADER | The name of the header to use to retrieve the URL-encoded client certificate from an HTTP request received from an SSL termination service providing SSL/TLS client authentication. By default, X-Client-Certificate is used, matching the behavior of the keeper/guacamole-ssl-nginx image. |
| |
SSL_CLIENT_VERIFIED_HEADER | The name of the header to use to retrieve the verification status of the certificate an HTTP request received from an SSL termination service providing SSL/TLS client authentication. This value of this header must be "SUCCESS" (all uppercase) if the certificate was successfully verified. By default, X-Client-Verified is used, matching the behavior of the keeper/guacamole-ssl-nginx image. |
SSL_MAX_DOMAIN_VALIDITY | The amount of time that the temporary, unique subdomain generated for SSL/TLS authentication may remain valid, in minutes. By default, temporary subdomains are valid for 5 minutes. |
SSL_MAX_TOKEN_VALIDITY | The amount of time that a temporary authentication token for SSL/TLS authentication may remain valid, in minutes. By default, temporary authentication tokens are valid for 5 minutes. |
SSL_SUBJECT_BASE_DN | The base DN containing all valid subject DNs. If specified, only certificates asserting subject DNs beneath this base DN will be accepted. By default, all DNs are accepted as long as the certificate is valid. |
SSL_SUBJECT_USERNAME_ATTRIBUTE | The LDAP attribute or attributes that may be used to represent a username within the subject DN of a user's X.509 certificate. If the least-significant attribute of the subject DN is not one of these attributes, the certificate will be rejected. By default, any attribute is accepted and used as the username. |
All environment variables which start with
TOTP_
correspond to configuration properties for TOTP multi-factor authentication which would normally be specified within guacamole.properties
.Variable name | Description |
---|---|
TOTP_ISSUER | The human-readable name of the entity issuing user accounts. By default, this is "Apache Guacamole". |
TOTP_DIGITS | The number of digits which should be included in each generated code. TOTP allows for 6-, 7-, or 8-digit codes. Longer or shorter codes than this are not possible as they violate the TOTP standard. By default, 6-digit codes will be used. |
TOTP_PERIOD | The duration that each generated code should remain valid, in seconds. The code generation period is given in positive integer seconds and may be any value, however the value should be long enough to allow the user a reasonable amount of time to enter their code. Their authentication device will generate a new code after this period elapses. By default, generated codes are valid for 30 seconds. |
TOTP_MODE | The hash algorithm that should be used to generate codes. Valid TOTP modes (hashes) are "sha1", "sha256", and "sha512". By default, "sha1" is used. |
All environment variables which start with
UDS_
correspond to configuration properties for integrating with UDS Enterprise that would normally be specified within guacamole.properties
.Variable name | Description |
---|---|
UDS_BASE_URL | The base URL of the UDS Enterprise deployment that may leverage Keeper Connection Manager to provide remote access. Keeper Connection Manager will use this URL to contact UDS to authenticate and authorize connection requests. |
This variable is optional and specifies the full contents of the
/etc/guacamole/user-mapping.xml
file that can be used to test a Guacamole deployment without configuring a more complex authentication method like MySQL, PostgreSQL, or LDAP. This is the authentication mechanism described within the Keeper Connection Manager installation instructions.As the contents of this file are inherently sensitive, the file will be stored purely in memory (within
/dev/shm
) unless the USE_SHM
environment variable is set to "N" as documented below.Keeper Connection Manager ships with its own default branding. If you will be using your own custom branding, the optional
USE_DEFAULT_BRANDING
environment variable should be set to "N" to disable the Keeper branding and avoid conflicts with your branding extension.This variable is optional and may be used to force storage of known sensitive files on disk rather than in memory. To force storage to disk, set
USE_SHM
to "N".By default, the
keeper/guacamole
image stores the contents of files that are known to be sensitive within /dev/shm
, thus storing those files only in memory and without potentially persisting sensitive data to disk. As such files are generated by the Docker image from environment variables during startup, this is particularly useful if Docker secrets are being used.Rather than pass data directly in environment variables, a
_FILE
suffix may be added to any environment variable supported by this image to force that variable to be read from the named file within the container. For example, to read /etc/guacamole/user-mapping.xml
from a file:docker run --name some-guacamole \
-e ACCEPT_EULA=Y \
-e GUACD_HOSTNAME=some-guacd \
-e USER_MAPPING_FILE=/some/volume/mount/user-mapping.xml \
-d keeper/guacamole
As Docker secrets store sensitive data within files beneath
/run/secrets/
within the container, this can be used to load sensitive data from Docker secrets:docker run --name some-guacamole \
-e ACCEPT_EULA=Y \
-e GUACD_HOSTNAME=some-guacd \
-e MYSQL_HOSTNAME=some-mysql \
-e MYSQL_DATABASE=guacamole_db \
-e MYSQL_USERNAME_FILE=/run/secrets/mysql-username \
-e MYSQL_PASSWORD_FILE=/run/secrets/mysql-password \
-d keeper/guacamole
Last modified 1mo ago