Advanced Configuration

Advanced configuration and custom integration options

Apache Guacamole is configured using files within the /etc/guacamole directory, commonly referred to as GUACAMOLE_HOME. The two primary components of the Apache Guacamole stack, guacd and the Guacamole web application, both have their own dedicated configuration files within /etc/guacamole. Keeper Connection Manager includes default, skeleton versions of these files.

Filename	Description
/etc/guacamole/guacd.conf	The configuration file for the Apache Guacamole proxy daemon, "guacd". This file and the guacd service are provided by the kcm-guacd package.
/etc/guacamole/guacamole.properties	The configuration file for the Apache Guacamole web application. This file and the Guacamole web application are provided by the kcm package.
/etc/guacamole/ldap-servers.yml	A YAML file describing the LDAP servers available to authenticate Guacamole users. As the full details of a single LDAP server can be described using guacamole.properties, this file is primarily of use if multiple LDAP servers need to be used, particularly if the set of users available may vary by LDAP server. A skeleton version of this file is provided by the kcm-guacamole-auth-ldap package.
/etc/guacamole/user-mapping.xml	An XML mapping of users to connections which Apache Guacamole can use by default without any additional extensions, primarily intended for initial testing. A skeleton version of this file is provided by the kcm package. Production use of this file is not recommended.

Installing and configuring included extensions

Supported extensions, such as those provided by the Keeper Connection Manager packages, are installed through installing their corresponding packages. If you are using the keeper/guacamole Docker image, extensions are automatically installed using the above packages depending on the environment variables provided when the container is first started.

Extension	Package name	Docker image environment variables
Active Directory / LDAP support	kcm-guacamole-auth-ldap	LDAP_*
Duo two-factor authentication	kcm-guacamole-auth-duo	DUO_*
Encrypted JSON authentication	kcm-guacamole-auth-json	JSON_*
MySQL / MariaDB database support	kcm-guacamole-auth-jdbc-mysql	MYSQL_*
PostgreSQL database support	kcm-guacamole-auth-jdbc-postgresql	POSTGRES_*
SQL Server database support	kcm-guacamole-auth-jdbc-sqlserver	SQLSERVER_*
TOTP two-factor authentication	kcm-guacamole-auth-totp	TOTP_*
SAML 2.0 / SSO Integration	kcm-guacamole-auth-saml	SAML_*
OpenID Connect Integration	kcm-guacamole-auth-openid	OPENID_*

The Keeper Connection Manager packages for supported extensions will automatically create symbolic links to install themselves and any needed libraries/drivers. You do not need to manually create links, copy files, etc. for the extensions which are provided within the Keeper Connection Manager repository.

Installing custom / third-party extensions

Custom extensions, such as custom branding provided as part of a Keeper Connection Manager subscription, are installed by placing their corresponding .jar files within /etc/guacamole/extensions. If those extensions require additional libraries, such as JDBC drivers, the .jar files for those libraries are placed within /etc/guacamole/lib.

Filename	Description
/etc/guacamole/extensions/	The directory in which extension .jar files should be placed. Tomcat must be restarted after extension .jar files are added or removed.
/etc/guacamole/lib/	The directory in which library .jar files required by installed extensions should be placed. Libraries within this directory will be available within the classpath for all extensions.

Note that support is not provided for custom extensions with the following exceptions:

• Branding extensions which we have provided as part of a subscription

• Subscriptions which explicitly extend support to include custom / third-party extensions

Applying custom branding

Custom branding is applied through branding extensions, such as the branding extensions we provide on request as part of a Keeper Connection Manager subscription. If you have a custom branding extension and wish to apply that branding to your deployment of Keeper Connection Manager, you must:

1. Remove the symbolic link to the default Keeper Connection Manager branding, located at /etc/guacamole/extensions/_kcm-branding.jar. The kcm-guacamole package considers the existence/absence of this link to be an aspect of configuration and is designed to allow this symbolic link to be removed. If using the keeper/guacamole Docker image, this can also be accomplished by setting the USE_DEFAULT_BRANDING environment variable to "N".

2. Copy the extension's .jar file to /etc/guacamole/extensions/.

3. Restart Tomcat

You may need to clear cache within browsers that have already visited your deployment.