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.

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.

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.

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.

Keeper Connection Manager supports customization of the front-end user interface CSS and injection of custom Javascript. In this guide, we will demonstrate how to modify the web application to display customized branding and execute custom Javascript code.

Overview

Keeper Connection Manager provides the ability to develop "Extensions" which can add custom enhancements to the overall platform. This page covers a basic example which can be easily modified for branding and UI changes.

Extensions to Keeper Connection Manager can:

1. Provide alternative authentication methods and sources of connection/user data.

2. Provide event listeners that will be notified as Guacamole performs tasks such as authentication and tunnel connection.

3. Theme or brand the user interface through additional CSS files and static resources.

4. Extend KCM's JavaScript code by providing JavaScript that will be loaded automatically.

5. Add additional display languages, or alter the translation strings of existing languages.

Extension format

KCM extensions are standard Java .jar files (this is essentially a .zip file) which contain all classes and resources required by the extension, as well as the KCM extension manifest. There is no set structure to an extension except that the manifest must be in the root of the archive. Java classes and packages, if any, will be read from the .jar relative to the root, as well.

Example Branding Extension

Modifying your existing KCM installation with custom branding is easy, please follow the below steps as an example.

(1) On the instance running Keeper Connection Manager or your workstation, retrieve the example repository or download as a zip file. Example:

git clone https://github.com/Keeper-Security/kcm-branding.git
cd kcm-branding

(2) Zip up the contents of the branding folder into a file called kcm-branding.jar. The name of the file is arbitrary, as long as it is a unique name. KCM will load any extension that is placed into the target folder.

zip -r kcm-branding.jar guac-manifest.json css/ html/ js/ resources/ translations/

(3) Copy the file into the /etc/kcm-setup folder or any path on the server.

sudo cp kcm-branding.jar /etc/kcm-setup/

(4) In your docker-compose.yml file (e.g. /etc/kcm-setup/docker-compose.yml) there are 2 changes needed:

• In the "guacamole" section add a reference to the Jar file which volume mounts the file directly from the host into the guacamole instance. The name of the file does not matter, as KCM will pull all jar files and process them.

• Add the environment variable USE_DEFAULT_BRANDING with a value of "N".

Here's an example section:

    guacamole:
        image: keeper/guacamole:2
        restart: unless-stopped
        environment:
            ...
            USE_DEFAULT_BRANDING: "N"
        volumes:
            ...
            - "/etc/kcm-setup/kcm-branding.jar:/etc/guacamole/extensions/kcm-branding.jar:ro"

(5) Restart the container

sudo ./kcm-setup.run stop
sudo ./kcm-setup.run upgrade

That's it. After the service starts up, the branding on your KCM page will be all new, and there will be a popup alert when you load the page.

For iterating on more changes, simply edit the resources, zip up the file, copy the zip file to the target folder and restart your KCM container.

Technical Details

CSS

The CSS files referenced in guac-manifest.json are appended to the application CSS when loaded, therefore they will override the CSS properties.

Javascript

The Javascript files referenced in guac-manifest.json are appended to the application Javascript when loaded.

HTML modification

The existing HTML structure of KCM's interface can be modified through special "patch" HTML files declared by the html property in guac-manifest.json. These files are HTML fragments and are identical to any other HTML file except that they contain KCM-specific meta tags that instruct KCM to modify its own HTML in a particular way. Each meta tag takes the following form:

<meta name="NAME" content="SELECTOR">

where SELECTOR is a CSS selector that matches the elements within the KCM interface that serve as a basis for the modification, and NAME is any one of the following defined modifications:

before

Inserts the specified HTML immediately before any element matching the CSS selector.

after

Inserts the specified HTML immediately after any element matching the CSS selector.

replace

Replaces any element matching the CSS selector with the specified HTML.

before-children

Inserts the specified HTML immediately before the first child (if any) of any element matching the CSS selector. If a matching element has no children, the HTML simply becomes the entire contents of the matching element.

after-children

Inserts the specified HTML immediately after the last child (if any) of any element matching the CSS selector. If a matching element has no children, the HTML simply becomes the entire contents of the matching element.

replace-children

Replaces the entire contents of any element matching the CSS selector with the specified HTML.

For example, to add a welcome message and link to some corporate privacy policy (a fairly common need), you would add an HTML file like the following:

<meta name="after" content=".login-ui .login-dialog">

<div class="welcome">
    <h2>Welcome to our Keeper Connection Manager Demo</h2>
    <p>
        Please be sure to read our <a href="#">privacy
        policy</a> before continuing.
    </p>
</div>

After the extension is installed and KCM is restarted, the "welcome" div and its contents will automatically be inserted directly below the login dialog (the only element that would match .login-ui .login-dialog) as if they were part of KCM's HTML in the first place.

Troubleshooting

If the page loads blank after applying the extension, check the logs. For example:

sudo ./kcm-setup.run logs -f guacamole

If you see a null pointer exception, it's probably because one of the resources referenced in guac-manifest.json cannot be found in the .jar archive. Ensure that all files and folders are zipped up properly.

/etc/guacamole/guacd.conf is the configuration file for Apache Guacamole's proxy daemon, guacd. Editing this file is not normally required unless the circumstances of your deployment require internal communications to be encrypted (not just public-facing communication), the guacd service needs to listen on an external interface or non-standard port, or you need to increase logging verbosity to assist with debugging unexpected behavior.

The guacd.conf file is read only during service startup, and changes to guacd.conf will take effect only after restarting the guacd service.

Organization and general syntax

The guacd.conf file is organized within three distinct sections, each section having special meaning to guacd and containing only parameters specific to that section:

• "server" - Parameters for configuring the hostname/address and port used by guacd.

• "daemon" - Parameters for configuring the behavior of the guacd daemon, in particular logging level.

• "ssl" - Parameters for configuring SSL/TLS encryption of the internal communication between the web application and guacd.

The beginning of each section is denoted with a section name in brackets, and each section ends implicitly with the beginning of a new section, or at the end of the file.

Parameters names and values

Parameters within sections are written as a parameter name, followed by an equals sign, followed by the parameter value, all on one line.

name = value

If special characters need to be placed within a parameter value, such as whitespace, #, ", or \, the entire value must be enclosed in double quotes, and each occurrence of " or \ within the value must be escaped with backslashes:

name = "quoted # value \\ with \" special characters"

Comments

Comments may be placed anywhere, including at the end of a parameter, and consist of arbitrary text following a # symbol until end-of-line:

# Arbitrary comment
name = value # Another arbitrary comment

Server parameters

The parameters within the "server" section define the hostname/address and port that the guacd service should listen on. By default, the guacd service will listen at port 4822 on localhost, and thus will accept connections from a local instance of Guacamole only. If these values are changed, the Guacamole web application will need to be reconfigured to match by editing /etc/guacamole/guacamole.properties.

Daemon parameters

The parameters within the "daemon" section control how guacd operates as a daemon, in particular the level at which messages should be logged. Greater logging verbosity may be desired if unexpected behavior is encountered.

SSL/TLS parameters

guacd can be configured to communicate with the web application using SSL/TLS. If a certificate and key are specified, guacd will require SSL/TLS for all connections from the web application, and the web application will need to be reconfigured to match by editing /etc/guacamole/guacamole.properties. If the certificate cannot be verified by Java against well-known CA certificates, the certificate will also need to be added to Java's truststore.

By default, internal communication between guacd and the web application is not encrypted.

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

TCP connection information for guacd

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

Guacamole user session timeout

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

HTTP request size limits

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.

Restricting available languages

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

allowed-languages: en, de

Extension-specific properties

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

• Duo Two-Factor Authentication Configuration Properties

• SAML 2.0 Authentication Configuration Properties

• OpenID Connect Configuration Properties

• Encrypted JSON Configuration Properties

• LDAP Configuration Properties

• MySQL / MariaDB Configuration Properties

• PostgreSQL Configuration Properties

• SQL Server Configuration Properties

• TOTP Configuration Properties

• UDS Enterprise Configuration Properties

SAML 2.0 Configuration Properties

Controlling Login Behavior

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:

extension-priority: saml

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:

extension-priority: *, saml

OpenID Connect Configuration Properties

Additional optional properties are available to control how claims within received ID tokens are used to derive the user’s Keeper Connection Manager username, any associated groups, the OpenID scopes requested when user identities are confirmed, and to control the maximum amount of time allowed for various aspects of the conversation with the identity provider:

Controlling Login Behavior

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 OpenID identity provider immediately (without a Keeper Connection Manager login screen), ensure the OpenID extension has priority over all others:

extension-priority: openid

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 OpenID, ensure the OpenID extension does not have priority:

extension-priority: *, openid

Duo application integration details

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 application key

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.

Any random value containing at least 40 characters will suffice. To quickly grab 40 random characters from /dev/random:

$ tr -dc 'a-zA-Z0-9' < /dev/random | head -c40; echo
xqZKJODwg7ouwxdqU9hvuaWhE6lQFspijY0ofg8I
$

Shared JSON secret key

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.

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:

$ echo -n "ThisIsATest" | md5sum
4c0b569e4c96df157eee1b65dd0e4d41 -
$

Source network restrictions

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.

• TCP connection information

• LDAP user / user DN description

• LDAP user search DN

• LDAP group / group DN description

• Base DN for Guacamole connections (guacConfigGroup)

• LDAP search result limits

• LDAP user attributes

• Custom LDAP search filters

• LDAP aliases and referrals

TCP connection information

The TCP connection details of the LDAP server, as well as whether encryption should be used.

LDAP user / user DN description

The base DN of all Guacamole users within the LDAP directory, and the attribute which contains each user's username. If the username attribute is not part of the DN, a search DN will need to be provided, as well.

LDAP user search DN

The DN and password of the user to bind as when searching for the DN of each user attempting to log in. If omitted, the DN of each user will be derived directly using the user base DN and username attribute.

LDAP group / group DN description

The base DN of all Guacamole user groups within the LDAP directory, and the attribute which contains each group's name. If storing connection information within LDAP, the provided base DN must also contain any groups that may be referenced within "guacConfigGroup" objects using the "seeAlso" attribute.

Base DN for Guacamole connections (guacConfigGroup)

The base DN for all Guacamole connections defined directly within the LDAP directory using "guacConfigGroup" objects. The LDAP schema files for "guacConfigGroup" objects can be found within /usr/share/guacamole-auth-ldap/schema in both LDIF and .schema format. Note that storing connections directly within the LDAP directory is optional. If connections will not be stored within the directory, this base DN should not be provided.

LDAP search result limits

The maximum number of LDAP search results which can be returned by a single query. LDAP searches which exceed this limit will fail.

LDAP user attributes

Arbitrary LDAP user attributes may be used to dynamically affect the behavior of connections based on the user accessing them. When a user authenticates with LDAP and subsequently accesses a particular Guacamole connection, the values of these attributes will be made available as parameter tokens and applied to the parameters of the connection. If the attribute has no value for the current user, then the corresponding token is not applied. If the attribute has multiple values, then the first value of the attribute is used.

These attributes must be configured for use as parameter tokens ahead of time by being explicitly listed within /etc/guacamole/guacamole.properties. By default, no LDAP user attributes are made available as parameter tokens.

When converting an LDAP attribute name into a parameter token name, the name of the attribute is transformed into uppercase with each word separated by underscores, a naming convention referred to as "uppercase with underscores" or "screaming snake case". For example:

Custom LDAP search filters

The search filter which should be used to retrieve lists of users or groups from the LDAP directory. By default, a filter which matches all objects is used, and the only restriction is given through the relevant base DN. If you need to narrow the lists of users or groups further, the default filter can be overridden.

If overriding a search filter, be sure that the filter is a valid LDAP filter. In particular, an LDAP filter must be enclosed in a matching pair of parenthesis. If unsure whether your filter is valid, or if seeing unexpected results, it can be helpful to verify your filter against your LDAP server using a command-line utility like "ldapsearch".

LDAP aliases and referrals

Whether (and how) Guacamole should follow LDAP aliases or referrals when encountered during an LDAP query. By default, Guacamole will not dereference aliases and will not follow referrals.

• TCP connection information

• Database name and credentials

• Database password policies

  • 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

• Database user account requirements

TCP connection information

The TCP connection details for the MySQL / MariaDB database.

Database name and credentials

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.

Database password policies

Restrictions that should be applied to all database users with respect to password complexity, length, change frequency, and reuse.

Minimum password length and complexity

Minimum/maximum password age

Password reuse prevention

Database concurrent connection limits

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.

General connection concurrency limits

Per-user concurrency limits

Absolute concurrency limits

Database user account requirements

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.

• TCP connection information

• Database name and credentials

• Database password policies

  • 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

• Database user account requirements

TCP connection information

The TCP connection details for the PostgreSQL database.

Database name and credentials

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.

Database password policies

Restrictions that should be applied to all database users with respect to password complexity, length, change frequency, and reuse.

Minimum password length and complexity

Minimum/maximum password age

Password reuse prevention

Database concurrent connection limits

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.

General connection concurrency limits

Per-user concurrency limits

Absolute concurrency limits

Database user account requirements

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.

• TCP connection information

• Database name and credentials

• Database password policies

  • 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

• Database user account requirements

TCP connection information

The TCP connection details for the SQL Server database.

Database name and credentials

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.

Database password policies

Restrictions that should be applied to all database users with respect to password complexity, length, change frequency, and reuse.

Minimum password length and complexity

Minimum/maximum password age

Password reuse prevention

Database concurrent connection limits

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.

General connection concurrency limits

Per-user concurrency limits

Absolute concurrency limits

Database user account requirements

Whether authentication via other extensions is allowed for users that do not exist within the SQL Server database. If set to "true", authentication attempts will be denied unless the authenticated user has been defined within the database.

TOTP issuer details

A human readable name must be associated with generated keys such that the user enrolling their authentication device will be able to easily distinguish the code they should use for this application vs. the other applications that same authentication device may be used for. This value does not affect the key generated nor handling of received codes; it only serves as a reference for the user.

TOTP code generation

Most authentication devices supporting TOTP use 6-digit codes, a code period of 30 seconds, and the SHA-1 hash algorithm. These values are used as the defaults for code generation. If your requirements differ, these default values may be overridden.

UDS Enterprise deployment details

When leveraging Keeper Connection Manager to fulfill a request to remotely access a virtual machine, UDS Enterprise will generate and send a temporary access token to Keeper Connection Manager. This temporary access token defines the connection details of the machine being accessed and needs to be validated against UDS Enterprise for that access to be granted. In order to reach out to UDS Enterprise to perform this validation, Keeper Connection Manager needs to know the base URL of the UDS Enterprise deployment.

The URL provided need only be a URL that your Keeper Connection Manager server can use to reach your UDS Enterprise server. If UDS Enterprise is installed on the same private network or on the same server as Keeper Connection Manager, this can be an internal URL that uses a private IP address or domain name, and does not necessarily need to be the public URL that would be used to access UDS Enterprise over the internet.

As of KCM version 2.9.6, KCM can be configured to limit a user's ability to login after multiple consecutive failed login attempts. This blocks brute-force login attacks on KCM instances.

Use the following properties to change the login attempt settings

Extension API Overview

Keeper Connection Manager is designed to be integrated with third-party systems and applications using the Extension API, which allows arbitrary systems to serve as methods of authentication and as data sources.

The Extension API was used to implement the authentication mechanisms supported by Keeper Connection Manager and Apache Guacamole out-of-the-box. For Keeper Connection Manager 2.x, regardless of any updates, the extension API is compatible with upstream Apache Guacamole 1.0.0 through 1.3.0.

Documentation

• General upstream documentation on Guacamole extensions and their format

• JavaDoc for the Apache Guacamole 1.3.0 Extension API

• JavaDoc for the Apache Guacamole 1.3.0 core API (referenced by parts of the extension API)

If you are not sure where to begin with integrating Keeper Connection Manager, or are having difficulties with your existing integration, consulting on integration is included with premium subscriptions.

Overview

The main Keeper Connection Manager packages include default Docker entry points, allowing deployments of Keeper Connection Manager to be automated with Docker, even if your deployment is customized with your own branding, third-party authentication extensions, or organization-specific settings.

A simple Dockerfile can be created which accomplishes the following tasks:

1. Copy a .repo file into /etc/yum.repos.d/ so the Docker image build has access to the Keeper Connection Manager packages.

2. Install any required packages for your use case.

3. Remove the .repo file so your image doesn't contain your repository credentials.

4. Apply any desired configuration (such as through a guacamole.properties.docker file).

5. Configure the environment as required for installing the Keeper Connection Manager packages used by the image (such as adding the tomcat user to any necessary groups or deploying guacamole.war).

6. Start one of the provided Docker entrypoints.

The Keeper Connection Manager packages currently include three Docker entrypoints ready for use within custom images. Which entrypoint(s) you use will depend on whether you are creating separate images for Apache Guacamole and guacd vs. an all-in-one image which contains both:

Configuring Guacamole using guacamole.properties.docker

The entrypoint-combined.sh and entrypoint-guacamole.sh entrypoints will both check for the existence of an optional /etc/guacamole/guacamole.properties.docker file. If this file exists, it will be automatically filtered such that environment variables are substituted within the contents of the file. The filtered contents of this file will be written to /etc/guacamole/guacamole.properties, overwriting the original file, but omitting any properties which remain unset after filtering.

For example, if an /etc/guacamole/guacamole.properties file exists within a Guacamole-only or combined image containing the following:

mysql-hostname: $DATABASE_HOSTNAME
mysql-database: guacamole_db
mysql-username: $DATABASE_USERNAME
mysql-password: $DATABASE_PASSWORD

ldap-hostname: $LDAP_HOSTNAME
ldap-port: $LDAP_PORT

The main guacamole.properties will be generated using this as a template, substituting the values of the DATABASE_HOSTNAME, DATABASE_USERNAME, DATABASE_PASSWORD, LDAP_HOSTNAME, and LDAP_PORT environment variables. If only the DATABASE variables are set, then properties which depend on other values will automatically be omitted:

mysql-hostname: localhost
mysql-database: guacamole_db
mysql-username: guacamole_user
mysql-password: some_password

guacamole.properties.docker can thus be used to provide a completely custom set of configuration options. Your image need only support the options you specifically need.

Creating an all-in-one image using the combined entrypoint

An all-in-one Docker image for Guacamole contains both the Guacamole web application and guacd. An image which contains both Guacamole and guacd will require at least the following packages:

• kcm-guacamole

• kcm-guacd

• tomcat

If using LDAP and/or one of the supported databases for authentication, the relevant packages for those authentication methods will also be installed:

• kcm-guacamole-auth-duo

• kcm-guacamole-auth-json

• kcm-guacamole-auth-ldap

• kcm-guacamole-auth-mysql

• kcm-guacamole-auth-postgresql

• kcm-guacamole-auth-sqlserver

• kcm-guacamole-auth-totp

You must also install at least one package providing protocol support. The packages required depend only on the protocols you intend to support, which may well be all protocols supported by Guacamole:

• kcm-libguac-client-rdp

• kcm-libguac-client-ssh

• kcm-libguac-client-telnet

• kcm-libguac-client-vnc

If providing support for telnet, you will also need to configure your image to use the EPEL repository by installing the epel-release package. This package will need to be installed before the kcm-libguac-client-telnet package, as its dependencies will not be able to be satisfied without EPEL:

• epel-release

If you will be using guacamole.properties.docker to provide configuration options that leverage environment variables, the gettext package is required

• gettext

A combined Dockerfile which provides support for absolutely all protocols, uses MySQL for authentication, and leverages guacamole.properties.docker would look like the following:

# Build off CentOS 7
FROM centos:centos7

# Add the Keeper Connection Manager Enterprise repository
COPY kcm.repo /etc/yum.repos.d/

# Install Guacamole, Tomcat, and guacd
RUN    yum install -y epel-release               \
    && yum install -y                            \
        gettext                                  \
        kcm                      \
        kcm-guacamole-auth-jdbc-mysql      \
        kcm-guacd                          \
        kcm-libguac-client-rdp             \
        kcm-libguac-client-ssh             \
        kcm-libguac-client-telnet          \
        kcm-libguac-client-vnc             \
        tomcat                                   \
    && yum clean all                             \
    && rm /etc/yum.repos.d/kcm.repo

# Add Tomcat service user to the "guacamole" group
RUN usermod -aG guacamole tomcat

# Deploy the Guacamole web application under Tomcat
RUN ln -s /opt/keeper/share/guacamole/guacamole.war /var/lib/tomcat/webapps/ROOT.war

# Add template guacamole.properties which will be populated with environment
# variables during startup by the entrypoint script
COPY guacamole.properties.docker /etc/guacamole/

# Tomcat will be accessed via port 8080
EXPOSE 8080

# Use combined Tomcat+guacd entrypoint
ENTRYPOINT [ "/opt/keeper/share/guacamole/entrypoint-combined.sh" ]

Creating a separate Guacamole image (without guacd)

A Docker image contains only the Guacamole web application will require at least the following packages:

• kcm-guacamole

• tomcat

If using LDAP and/or one of the supported databases for authentication, the relevant packages for those authentication methods will also be installed:

• kcm-guacamole-auth-saml

• kcm-guacamole-auth-openid

• kcm-guacamole-auth-duo

• kcm-guacamole-auth-json

• kcm-guacamole-auth-ldap

• kcm-guacamole-auth-mysql

• kcm-guacamole-auth-postgresql

• kcm-guacamole-auth-sqlserver

• kcm-guacamole-auth-totp

If you will be using guacamole.properties.docker to provide configuration options that leverage environment variables, the gettext package is required

• gettext

A Dockerfile which contains only the web application, uses MySQL for authentication, and which leverages guacamole.properties.docker would look like the following:

# Build off CentOS 7
FROM centos:centos7

# Add the Keeper Connection Manager repository
COPY kcm.repo /etc/yum.repos.d/

# Install Guacamole and Tomcat
RUN    yum install -y                            \
        gettext                                  \
        kcm                                      \
        kcm-guacamole-auth-jdbc-mysql            \
        tomcat                                   \
    && yum clean all                             \
    && rm /etc/yum.repos.d/kcm.repo

# Add Tomcat service user to the "guacamole" group
RUN usermod -aG guacamole tomcat

# Deploy the Guacamole web application under Tomcat
RUN ln -s /opt/keeper/share/guacamole/guacamole.war /var/lib/tomcat/webapps/ROOT.war

# Add template guacamole.properties which will be populated with environment
# variables during startup by the entrypoint script
COPY guacamole.properties.docker /etc/guacamole/

# Tomcat will be accessed via port 8080
EXPOSE 8080

# Use Guacamole entrypoint
ENTRYPOINT [ "/opt/keeper/share/guacamole/entrypoint-guacamole.sh" ]

Creating a separate guacd image (without Guacamole)

A Docker image which contains only guacd will require at least the kcm-guacd package:

• kcm-guacd

You must also install at least one package providing protocol support. The packages required depend only on the protocols you intend to support, which may well be all protocols supported by Guacamole:

• kcm-libguac-client-rdp

• kcm-libguac-client-ssh

• kcm-libguac-client-telnet

• kcm-libguac-client-vnc

If providing support for telnet, you will also need to configure your image to use the EPEL repository by installing the epel-release package. This package will need to be installed before the kcm-libguac-client-telnet package, as its dependencies will not be able to be satisfied without EPEL:

• epel-release

A Dockerfile which contains only guacd and provides support for absolutely all protocols would look like the following:

# Build off CentOS 7
FROM centos:centos7

# Add the Keeper Connection Manager repository
COPY kcm.repo /etc/yum.repos.d/

# Install guacd and protocol support
RUN    yum install -y epel-release               \
    && yum install -y                            \
        kcm-guacd                          \
        kcm-libguac-client-rdp             \
        kcm-libguac-client-ssh             \
        kcm-libguac-client-telnet          \
        kcm-libguac-client-vnc             \
    && yum clean all                             \
    && rm /etc/yum.repos.d/kcm.repo

# guacd will be accessed via port 4822
EXPOSE 4822

# Use guacd entrypoint
ENTRYPOINT [ "/opt/keeper/share/guacd/entrypoint-guacd.sh" ]