glyptodon/guacamole

glyptodon/guacamole is a Dockerized deployment of the Apache Guacamole web application, built using the packages provided by Glyptodon Enterprise and made available under the same EULA. Sensitive files like guacamole.properties are stored only in memory by default and all authentication methods supported by the Glyptodon Enterprise packages are supported.

All properties documented within the default guacamole.properties file provided with Glyptodon Enterprise can be configured with environment variables. All supported environment variables may alternatively be read from files, including Docker secrets. Arbitrary third-party extensions, such as custom branding or authentication, may be used through volume mounts and setting ADDITIONAL_GUACAMOLE_PROPERTIES and USE_DEFAULT_BRANDING variables as needed.

• Starting a Guacamole instance

• Viewing the Guacamole logs

• Environment variables

  • ACCEPT_EULA

  • ADDITIONAL_GUACAMOLE_PROPERTIES

  • CONTEXT_PATH

  • DUO_*

  • JSON_*

  • LDAP_*

  • LOG_LEVEL

  • MYSQL_*

  • POSTGRES_*

  • USER_MAPPING

  • USE_DEFAULT_BRANDING

  • USE_SHM

• Docker secrets

Starting a Guacamole instance

To start a Guacamole instance, running under Apache Tomcat, which listens on TCP port 8080:

docker run --name some-guacamole \
    -e ACCEPT_EULA=Y \
    -e GUACD_HOSTNAME=some-guacd \
    -p 8080:8080 -d glyptodon/guacamole

where some-guacamole is the name you wish to assign to your container and some-guacd is the hostname or IP address of your guacd instance or glyptodon/guacd container.

If intending to use a database for authentication, you may wish to leverage the glyptodon/guacamole-db-mysql or glyptodon/guacamole-db-postgres images, which provide MySQL and PostgreSQL databases which are automatically initialized for Guacamole.

Viewing the Guacamole logs

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:

docker logs some-guacamole

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.

Environment variables

ACCEPT_EULA

The ACCEPT_EULA environment variable must be set to "Y" to indicate your acceptance of the Glyptodon Enterprise EULA. This Docker image may not be used except under the terms of the EULA.

ADDITIONAL_GUACAMOLE_PROPERTIES

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.

CONTEXT_PATH

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.

DUO_*

All environment variables which start with DUO_ correspond to configuration properties for Duo multi-factor authentication which would normally be specified within guacamole.properties.

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.

JSON_*

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.

LDAP_*

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 encrypted LDAP authentication:

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.

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_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_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.

LOG_LEVEL

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".

MYSQL_*

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 glyptodon/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, regarldless 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.

POSTGRES_*

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 glyptodon/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, regarldless 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.

USER_MAPPING

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 Glyptodon Enterprise quickstart guide.

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.

USE_DEFAULT_BRANDING

Glyptodon Enterprise 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 Glyptodon branding and avoid conflicts with your branding extension.

USE_SHM

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 glyptodon/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.

Docker secrets

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 glyptodon/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 glyptodon/guacamole