Overview

Auto Docker Install is Keeper's recommended installation method.

Make sure to read the Preparing for Installation section first.

The Auto Docker Install method creates a standard Keeper Connection Manager environment using a script that is easy to run. This method does not restrict any features and you can still utilize this installation with advanced control at a later time.

If you are already familiar with Docker, you may choose to use the Docker Compose Install method.

Licensing

Before installing KCM 2.19 or later versions, please ensure you have a valid license key. Without a valid license key, users and administrators will be unable to use KCM after the update is applied

For more info, visit this page.

Installation

(1) Download the Installer

From the linux command line, download the installer script using the curl command.

curl -O https://keepersecurity.com/kcm/kcm-setup.run

(2) Add the execute permission to the Installer

chmod +x kcm-setup.run

(3) Run the Installer as root

sudo ./kcm-setup.run

The next question asks if you already have SSL termination available. If unsure, select N for no.

At the next prompt, enter your FQDN, even if it is internal. This is where users will access KCM in their browser.

Then, choose an option for SSL. A self-signed certificate (option 3) is okay for testing. After testing is complete, make sure to put a proper SSL certificate in place.

Secrets Manager Integration (optional)

The next prompt will be to choose your database, and then it will prompt for "Your one-time access token or base64 configuration". This value is generated from Keeper Secrets Manager (a tab in your vault). If this doesn't apply to you, just press enter. You can always add it later, too.

Set up SSO Login (optional)

Next up is SAML. You can choose "no" to skip it (you can come back and set it up later), or you can choose "yes" to set up SSO now. Follow the SSO setup steps here.

Save the creds and URL into a record in your Vault

After installation is completed, an admin login and password is created for you. Make sure to store this in your Keeper vault, as it's not provided again later.

Installation has completed successfully! You may now access your Keeper 
Connection Manager installation at:

    https://connection.mycompany.com/

The administrator credentials are:

    Username: guacadmin
    Password: **************************

Thank you for installing Keeper Connection Manager!

Navigate to the URL in your Browser

Now that the installation is complete, simply go to the URL/hostname that you designated. You'll be able to login as the guacadmin default user with the credentials provided at the completion of the installation.

Now that your Keeper Connection Manager instance is running, you can login as guacadmin and start setting up some connections. Need to import connections in bulk? Follow the steps here.

The next section of this documentation reviews the process of managing, upgrading and adding packages to the Docker Compose environment.

Overview

The Auto Docker Method installs Docker and 4 containers (if you selected all options) which start up automatically after the installer completes:

• Database (MySQL or PostgreSQL depending on selection)

• Guacamole (Tomcat)

• Guacd

• SSL (NGINX)

The installer also creates a docker-compose.yml file that can be found in the filesystem:

/etc/kcm-setup/docker-compose.yml

This Docker Compose file is the configuration file which manages the multi-docker container system. If you need to make further changes to the environment, you can modify this file and restart the docker services using the kcm-setup.run script or by directly using Docker functionality.

Managing the Service

When using the Docker Simple Install method, the kcm-setup.run script can be used to manage the entire service and the underlying docker containers. The purpose of this script is to make management of the Keeper Connection Manager platform very simple.

Usage:

sudo ./kcm-setup.run [OPTIONS] [COMMAND] [ARG...]

Install, maintain, or uninstall Keeper Connection Manager automatically.

Shared Volume

When using the Auto Docker Install method, a shared volume is automatically added to store file transfers and session recordings. The created volumes are located at /var/lib/guacamole/ which contains the drives and recordings.

Keeper Connection Manager is installed as a gateway in your cloud, virtual or on-prem environment. There are several methods of deployment, and installation only takes a few minutes.

Install Methods

For Auto Docker Install method, we support any version of Linux.

For Docker Compose Install, Keeper Connection Manager will run on any platform that supports Docker or Docker Desktop, including all versions of Windows and Linux.

Customers who directly installed via Linux RPMs can refer to our advanced linux install docs.

Configure DNS

In a production deployment, select a domain name to access the endpoint, e.g. kcm.company.com and create a new DNS record to map it to your server's public IP. You will be prompted to enter the domain name during the installation.

Ensure that the DNS record maps to your server's public IP address, or an IP that is internally available to your end-users over HTTPS port 443.

Decide on Let's Encrypt or Existing Cert

Keeper Connection Manager requires an SSL certificate for installation. Decide before starting installation if you want to use Let'sEncrypt, or if you have your own certificate file and private key.

LetsEncrypt is a certificate authority that is free, automated, open, and is also the world's largest CA. During installation using the Auto Docker Install method, Keeper Connection Manager will provide an option to utilize LetsEncrypt (option 1), which will generate a 3-month trusted certificate for your domain.

However, if you would like to use your own certificate obtained by a different CA, you can do so by choosing (option 2) during the installation prompt.

If you would like to use your own certificate, Keeper Connection Manager installation will prompt you to enter the full path and file name first for your .crt file, and next for your .pem file. Make sure to transfer these files to your server before beginning installation.

Select an Install Method

Keeper Connection Manager can be installed using one of the following methods.

Option 1: Auto Docker Install

An automated installer script is available for Linux which performs several of the Docker setup steps, such as generating a Docker Compose file, setting up SSL certificates and other options.

Go to: Installation Instructions for Auto Docker Install

This method is recommended for users who are new to Docker and prefer Linux.

Option 2: Docker Compose Install

This advanced and customized Docker install for Keeper Connection Manager provides the Docker Compose file to deploy in any Docker environment with support for additional packages such as SSO, LDAP, TOTP and more.

Go to: Installation Instructions for Docker Compose Install

This method is required for Windows and recommended for users who are familiar with Docker.

Starting with Keeper Connection Manager version 2.19, customers are required to obtain a license key from Keeper in order to continue the use of the application.

Obtaining a License Key

To obtain a license key, please contact Keeper Support directly at: https://www.keepersecurity.com/support.html

Upon request, Keeper staff will generate and send a copy of your license key.

To install your license key, follow the steps below:

New Customers

During the installation process, you will be prompted to input the license key.

Existing Customers

If using the Auto Docker Install or Docker Compose Install method, simply update the keeper/guacamole container definition with the license as the value of the KCM_LICENSE environment variable.

Example:

    guacamole:
        image: keeper/guacamole:2
        restart: unless-stopped
        environment:
            ACCEPT_EULA: "Y"
            .
            .
            .
            KCM_LICENSE: "XXXXXXXXXXXXXXXXXXXXXXXXXX"
        volumes:
            - "common-storage:/var/lib/guacamole:rw"

• (Optional) If the license will be present within a file in your container, you may alternatively use the KCM_LICENSE_FILE environment variable to point to that file.

• (Optional) If using the RPM packages, you must provide the license as the sole contents of /etc/guacamole/kcm.license, which must be readable by the guacamole group.

After adding the license key, restarting the container is necessary. If using the Auto Docker Install method, simply run:

sudo ./kcm-setup.run apply

Preparing for Installation

Keeper Connection Manager will serve your secure "jumpbox" and you'll use your web browser to access it. First, choose a URL that you'd like to use for accessing KCM.

You'll need the following:

1. A designated machine (usually a Linux VM) with a static IP address 2. Choose a fully-qualified domain name (FQDN) 3. Your DNS record set to point your FQDN to the IP of your designated machine 4. An SSL certificate

No cert? Don't worry, you can:

1. Start by choosing "use a self-signed certificate" (for testing)

2. Choose "Let's Encrypt" to generate a 90 day auto-renewing cert (requires 80 and 443 open)

3. Bring your own cert during setup or add it in later using the reconfigure command

You can either bring your own SSL certificate, or you can generate one during the installation by choosing the option for Let's Encrypt. If planning to use Let's Encrypt, make sure that ports 80 and 443 are open to the internet during the installation.

To prepare for installation:

1. Create/Identify and establish root access to the server that will run the Keeper Connection Manager gateway

2. Decide if you want your KCM gateway to be public-facing (assign public IP), or internal-only (assign private IP)

3. Add internal/external DNS A Record (or AAAA record) to point your domain to your KCM server's IP address

4. Make sure that ports 80 and 443 are open to the public if you plan to use Let's Encrypt.

Check your firewall to make sure that traffic can flow between your server and Docker. Some domains that it will need to reach include docker.com, docker.io and others.

Platform-specific Setup

Virtual Machines

To check your that your linux system's entropy level is at least 1000, use the command:

$ cat /proc/sys/kernel/random/entropy_avail

To increase the speed of entropy generation, you can install the haveged service to ensure that the environment can efficiently create secure random numbers.

sudo yum install haveged
sudo systemctl start haveged
sudo systemctl enable haveged

sudo apt-get install haveged

sudo yum install epel-release
sudo yum install haveged
sudo systemctl start haveged
sudo systemctl enable haveged

RHEL / Rocky Linux 8 (and derivatives)

If Podman is installed, you must run the following two commands before installation:

sudo yum remove containerd
sudo yum remove runc

Supported Operating Systems:

The recommended method to install Keeper Connection Manager is via the. This removes any operating system, system pre-requisites and other requirements. If the underlying system supports a current version of Docker, the container is fully supported.

Supported KCM Versions:

• Glyptodon 1.x - Full support for 2 years after any major release

• Glyptodon 2.x - Full support for 2 years after any major release

• Keeper Connection Manager 2.x - Full support for 2 years after any major release

Minimum system specs for production deployment:

Minimum host recommendations:

For anything over 200 concurrent sessions, we have several options, and it may be best to talk through this with our sales engineering team to find the right solution based on your needs and connection types.

Disk space requirements

A single session recording can vary based on the content being shown. This is affected by the type of connection. GUIs typically have higher recording sizes versus CLI connections like SSH, which can be quite small.

Network throughput for concurrent connections

Network throughput also varies based on activity, type of session and connection settings. From actual examples, we've found that for a system running about 100 concurrent sessions, network traffic varies between 9Mbit/s and 15Mbit/s for all 100 connections. Each connection would be on average 1/100th of the 15Mbit value.

In the same above scenario with 100 connections, we would expect about 15gb total traffic per hour on the network adaptor. Comparing inbound and outbound traffic, just over 90% of the traffic is outbound from the server to the clients.

Image: keeper/guacamole-db-mysql

keeper/guacamole-db-mysql is a Dockerized deployment of MySQL, built off which is automatically initialized with the Apache Guacamole database schema. It is built using the packages provided by Keeper Connection Manager and made available under the same . It is normally used to provide a MySQL database for a container using

Environment variables

In addition to the environment variables documented below, all environment variables supported by are accepted, as the official MySQL image forms the basis of this image.

ACCEPT_EULA

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

MYSQL_RANDOM_ROOT_PASSWORD

This is an optional variable. Set to a non-empty value, like yes, to generate a random initial password for the root user (using pwgen). The generated root password will be printed to stdout (GENERATED ROOT PASSWORD: .....).

GUACAMOLE_DATABASE

The name of the database to create and initialized for use with Apache Guacamole. This environment variable is required and ultimately maps to the MYSQL_DATABASE environment variable of the official MySQL image.

The GUACAMOLE_DATABASE variable is provided here for consistency with the other Guacamole-specific variables, but may be omitted if MYSQL_DATABASE is provided.

GUACAMOLE_ADMIN_PASSWORD

This is the Administrator password for the guacadmin user.

GUACAMOLE_USERNAME and GUACAMOLE_PASSWORD

The username and password to use for the MySQL database user specific to the Guacamole web application. This pair of variables differ from the MYSQL_USER and MYSQL_PASSWORD environment variables provided by the official MySQL image in that the created user has limited privileges, being granted only what privileges are absolutely required for Guacamole to run.

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

For example, to load the username and password for the limited-privilege user specific to the Guacamole web application from Docker secrets:

Image: keeper/guacamole-db-postgres

keeper/guacamole-db-postgres is a Dockerized deployment of PostgreSQL, built off which is automatically initialized with the Apache Guacamole database schema. It is built using the packages provided by Keeper Connection Manager and made available under the same . It is normally used to provide a PostgreSQL database for a container using the image.

Environment variables

In addition to the environment variables documented below, all environment variables supported by are accepted, as the official PostgreSQL image forms the basis of this image.

ACCEPT_EULA

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

POSTGRES_PASSWORD

The PostgreSQL administrator password.

GUACAMOLE_DATABASE

The name of the database to create and initialized for use with Apache Guacamole. This environment variable ultimately maps to the POSTGRES_DB environment variable of the official PostgreSQL image. If omitted, the default value defined by the official PostgreSQL image will be used.

The GUACAMOLE_DATABASE variable is provided here for consistency with the other Guacamole-specific variables and may be omitted if POSTGRES_DB is provided.

GUACAMOLE_ADMIN_PASSWORD

This is the Administrator password for the guacadmin user.

GUACAMOLE_USERNAME and GUACAMOLE_PASSWORD

The username and password to use for the PostgreSQL database user specific to the Guacamole web application. This pair of variables differ from the POSTGRES_USER and POSTGRES_PASSWORD environment variables provided by in that the created user has limited privileges, being granted only what privileges are absolutely required for Guacamole to run.

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

For example, to load the username and password for the limited-privilege user specific to the Guacamole web application from Docker secrets:

Update Instructions

From the Linux command line, update to the latest installer script using the curl command.

To update all of the underlying software and Docker containers when using the Docker Automated Install method, run the below commands:

Select "Y" when prompted.

Once the upgrade is complete, the service is started again automatically after a minute.

Overview

This section describes how to install Keeper Connection Manager using Docker by building a customized docker-compose orchestration file.

Step 1: Platform-specific Setup

Windows

Amazon Linux 2

CentOS7, RHEL

In addition to installing Docker, please install the haveged package to ensure that the environment is capable of generating enough entropy for creating secure random numbers.

Ubuntu

Install the haveged package to ensure that the environment is capable of generating enough entropy for creating secure random numbers.

Step 2: Create Docker Compose File

Now that you have Docker running on your instance, you need to generate a docker-compose.yml file that must be transferred to a working directory on your machine.

An example docker-compose.yml file for a deployment of Keeper Connection Manager which uses Let's Encrypt for its SSL certificate and an automatically-initialized database for authentication is provided below with a MySQL and PostgreSQL option.

Using a Custom SSL Certificate

If you plan to use a custom SSL certificate instead of Let's Encrypt, replace the "ssl" section of the Docker Compose file with a section that looks like this:

In this case, CERTIFICATE_FILE is the PEM-encoded certificate including the intermediate certificate chain. The PRIVATE_KEY_FILE is the private key file.

Also, note that in the above snippet, there is a volume mount that assigns the local filesystem to the target container. You should only modify the C:\Users\Path\To\Cert portion of the string. On linux environments it will be /path/to/cert.

Step 3: Start the Docker Containers

On Windows, open a Command Prompt. On Linux, open the terminal shell. Navigate to the location of the docker-compose.yml file that was saved in step 2.

To start up the environment, simply type the below command:

Note: Some versions require "docker-compose" with a hyphen.

That's it. If everything is successful, you can open the Keeper Connection Manager login screen on the specified FQDN.

Important Notes

• If you have not set up a proper domain name routing to the server, you can temporarily host-hack the local system in order to at least access the user interface and start testing.

• If you're using your own SSL certificate, we don't recommend using a wildcard cert. A certificate that has been explicitly created for the Keeper Connection Manager endpoint is the best practice since you'll be storing the SSL private key on the device.

• If you're using Windows, you will need to modify your Windows Defender Firewall to open up ports 443 to the Docker service.

• Running docker compose down will delete all data in the container including users, connections and history. To simply stop the containers, use docker compose stop.

Remote Browser Isolation Configuration

If you plan to use remote browser isolation, you'll need to create a seccomp security profile for the guacd container. For a new installation of Keeper Connection Manager, the kcm-setup.run script automatically handles this for you and places the file called guacd-docker-seccomp.json in the folder /etc/kcm-setup/ on the instance.

If this file is not automatically created, or you are upgrading an instance to use remote browser isolation, you may need to create the file manually.

You can obtain a copy of the file directly from the guacd Docker image once your docker containers are updated and running. For example, the following prints the contents of that file to a terminal:

Place the output of this command into /etc/kcm-setup/guacd-docker-seccomp.json and restart the containers.

Images

Below is a description of each of the images.

Now that your Keeper Connection Manager instance is running, you can login as guacadmin and start setting up some connections. Follow the Using Keeper Connection Manager documentation for next steps.

The next several sections of this installation guide provide detailed information about each specific Docker image, if you plan to customize or modify the environment.

For convenience, Docker images for both MySQL and PostgreSQL are provided which automatically initialize themselves using the Apache Guacamole database schema:

Each of these images:

• Is based off Docker's official images for the same databases, and thus each accepts the same core environment variables.

• Accepts a common set of Guacamole-specific environment variables defining the name to be used for Guacamole's database and the reduced-privilege credentials to be used by Guacamole to execute queries.

• Requires the same ACCEPT_EULA environment variable as the and images.

The images may be used as part of an entirely Dockerized deployment of Apache Guacamole, or separately as an easier method of deploying a functional, pre-initialized, and supported database. When combined with the and images using , an entire deployment of Apache Guacamole can be created and managed using a single docker-compose.yml.

Image: keeper/guacd

keeper/guacd is a Dockerized deployment of guacd, the Apache Guacamole proxy daemon, with support for VNC, RDP, SSH, K8s, MySQL, PostgreSQL, SQL Server and telnet. It is normally used to provide a guacd instance for a container using the keeper/guacamole image.

Starting a guacd instance

To start a guacd instance which listens on TCP port 4822:

docker run --name some-guacd -e ACCEPT_EULA=Y -d keeper/guacd

where some-guacd is the name you wish to assign to your container.

Viewing the guacd logs

The guacd logs are useful if debugging unexpected behavior of the remote desktop or failure to connect, as it is guacd that handles protocol-specific communication. To view the guacd logs:

docker logs some-guacd

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 Keeper Connection Manager EULA. This Docker image may not be used except under the terms of the EULA.

CA_CERTIFICATES

This variable is optional and specifies 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 RDP servers and Remote Browser Isolation sessions that use SSL/TLS.

Below is an example guacd section of docker-compose.yml with 2 certificates:

    guacd:
        image: keeper/guacd:2
        restart: unless-stopped
        shm_size: 1001500k
        security_opt:
            - "seccomp:/etc/kcm-setup/guacd-docker-seccomp.json"
        environment:
            ACCEPT_EULA: "Y"
            CA_CERTIFICATES: |
              -----BEGIN CERTIFICATE-----
              MIIEczCCA1ugAwIBAgIBADANBgkqhkiG9w0BAQQFAD..AkGA1UEBhMCR0Ix
              EzARBgNVBAgTClNvbWUtU3RhdGUxFDASBgNVBAoTC0..0EgTHRkMTcwNQYD
              VQQLEy5DbGFzcyAxIFB1YmxpYyBQcmltYXJ5IENlcn..XRpb24gQXV0aG9y
              aXR5MRQwEgYDVQQDEwtCZXN0IENBIEx0ZDAeFw0wMD..TUwMTZaFw0wMTAy
              -----END CERTIFICATE-----
              -----BEGIN CERTIFICATE-----
              MIIEczCCA1ugAwIBAgIBADANBgkqhkiG9w0BAQQFAD..AkGA1UEBhMCR0Ix
              EzARBgNVBAgTClNvbWUtU3RhdGUxFDASBgNVBAoTC0..0EgTHRkMTcwNQYD
              VQQLEy5DbGFzcyAxIFB1YmxpYyBQcmltYXJ5IENlcn..XRpb24gQXV0aG9y
              aXR5MRQwEgYDVQQDEwtCZXN0IENBIEx0ZDAeFw0wMD..TUwMTZaFw0wMTAy
              -----END CERTIFICATE-----
        volumes:
            - "common-storage:/var/lib/guacamole:rw"

GUACD_UID

This variable is optional and specifies the numeric UID which should be assigned to the user that the guacd service runs as. If omitted, the guacd service will run with the UID of the reduced-privilege user created by the Keeper Connection Manager package for guacd.

This is mainly useful if guacd will need to write to a volume mount whose file permissions may not match those of the keeper/guacd Docker image.

GUACD_GID

This variable is optional and specifies the numeric GID which should be assigned to the group that the guacd service runs as. If omitted, the guacd service will run with the GID of the reduced-privilege group created by the Keeper Connection Manager package for guacd.

This is mainly useful if guacd will need to write to a volume mount whose file permissions may not match those of the keeper/guacd Docker image.

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", "warning", "info", "debug", "trace".

The default log level is "info".

AUTOFILL_RULES

This variable is optional and specifies the full contents of the /etc/guacamole/autofill-rules.yml file that can be used to configure autofill of username/password in the Remote Browser Isolation protocol.

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.

• Environment variables

  • ACCEPT_EULA

  • KCM_LICENSE

  • ADDITIONAL_GUACAMOLE_PROPERTIES

  • ALLOWED_LANGUAGES

  • API_*

  • AWS_DISCOVERY_*

  • BAN_*

  • CA_CERTIFICATES

  • CATALINA_OPTS

  • CONTEXT_PATH

  • DUO_*

  • EXTENSIONS

  • EXTENSION_PRIORITY

  • GUACD_*

  • JSON_*

  • KSM_*

  • LDAP_*

  • LOG_LEVEL

  • MYSQL_*

  • OPENID_*

  • POSTGRES_*

  • REQUIRE_ACCOUNT_APPROVAL

  • SAML_*

  • SQLSERVER_*

  • SSL_*

  • TOTP_*

  • UDS_*

  • USER_MAPPING

  • USE_DEFAULT_BRANDING

  • USE_SHM

• Docker secrets

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

Environment variables

ACCEPT_EULA

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.

KCM_LICENSE

The KCM_LICENSE environment variable contains the license key provided by Keeper support.

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.

ALLOWED_LANGUAGES

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.

API_*

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.

AWS_DISCOVERY_*

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:

Other, optional environment variables are available for the other properties related to EC2 discovery:

BAN_*

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.

CA_CERTIFICATES

This variable is optional and specifies 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.

CATALINA_OPTS

This variable is optional and specifies arbitrary command-line options that should be passed to the JVM running Tomcat. It corresponds to Tomcat's own CATALINA_OPTS environment variable and is primarily used to pass additional system properties to the JVM, as may be necessary to configure platform-level options like whether an HTTP proxy should be used.

For example, if you wish to ensure that all outbound HTTPS connections go through an HTTP proxy, including API calls to services like Keeper Secrets Manager (KSM), you would set CATALINA_OPTS to:

-Dhttps.proxyHost=my.proxy -Dhttps.proxyPort=3129

where "my.proxy" is the hostname or IP address of the desired HTTP proxy and "3129" is its TCP port number.

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

The following environment variables are required if using Duo multi-factor authentication:

EXTENSIONS

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):

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.

EXTENSION_PRIORITY

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:

GUACD_*

TCP connection information for guacd.

Other, optional environment variables are available for configuring other aspects of the connection to guacd:

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:

Other, optional environment variables are available for the other properties related to encrypted JSON authentication:

KSM_*

All environment variables which start with KSM_* correspond to configuration properties for Keeper Secrets Manager. See the Keeper Vault Integration guide.

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 LDAP authentication (for a single LDAP server):

If using multiple LDAP servers, or if you prefer to provide LDAP server configuration in YAML format, the following environment variable is required:

Other, optional environment variables are available for the other properties related to LDAP authentication:

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 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:

Other, optional environment variables are available for the other properties related to MySQL authentication:

OPENID_*

All environmental variables which start with OPENID_ correspond to configuration properties for Open ID Connect authentication which would normally be specified within guacamole.properties.

Optional variables:

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 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:

Other, optional environment variables are available for the other properties related to PostgreSQL authentication:

REQUIRE_ACCOUNT_APPROVAL

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:

SAML_*

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:

Optional environmental variables:

SQLSERVER_*

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:

Other, optional environment variables are available for the other properties related to SQL Server authentication:

SSL_*

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:

Other, optional environment variables are available for the other properties related to SSL/TLS client authentication:

TOTP_*

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

UDS_*

All environment variables which start with UDS_ correspond to configuration properties for integrating with UDS Enterprise that would normally be specified within guacamole.properties.

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

USE_DEFAULT_BRANDING

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.

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

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

When using the Auto Docker Install method, packages can be added by directly modifying the generated Docker Compose file. For example, adding SSO or LDAP support.

To modify your Keeper Connection Manager environment, you'll need to edit the docker-compose.yml file located here:

/etc/kcm-setup/docker-compose.yml

Applying Configuration Changes

The kcm-setup.run script has an apply feature which allows you to apply configuration changes without updating the containers. From the Linux command line, update to the latest installer script using the curl command.

curl -O https://keepersecurity.com/kcm/kcm-setup.run

Apply the changes

sudo ./kcm-setup.run apply

Update and Restart the Containers

To update the environment, use the kcm-setup.run upgrade command to update the containers and start with the latest configuration:

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

or.....

sudo su
cd /etc/kcm-setup/
docker-compose -p kcm up -d

For convenience, a Docker image for SSL termination using NGINX is provided which automatically configures itself with an SSL certificate:

This image:

• Is based off Docker's official image for NGINX, and thus each accepts the same core environment variables.

• Accepts a set of Keeper-specific environment variables defining the Guacamole instance that will be behind SSL termination.

• Can automatically retrieve a certificate from Let's Encrypt, generate its own self-signed certificate for testing, or use an existing certificate that you have already obtained from a certificate authority.

• Requires the same ACCEPT_EULA environment variable as the keeper/guacamole and keeper/guacd images.

See the next section to view configuration examples.

To update all of the Keeper Connection Manager docker images when using the Docker Compose Install method, run the below command (assuming docker-compose.yml is in the current folder):

If you originally installed with the Auto Docker Install method (kcm-setup.run script), run the below command:

Select "Y" when prompted.

This page provides details on how to create an SSL certificate for use with the Keeper Connection Manager service.

Generate and Prepare the SSL Certificate

The process of generating an SSL certificate varies depending on the provider, but the general flow is documented here.

(1) On your local workstation, Generate a private key

(2) Generate a CSR, making sure to use the hostname which you plan to use for KCM. In this case, we will be using demo3.kcmdemo.com. The important item here is that the Common Name matches exactly to the domain.

(3) Purchase an SSL certificate and Submit the CSR to your SSL certificate provider.

If you don't have a provider already, a good site is:

Create a certificate for a domain that is specific for this KCM instance, e.g. demo3.kcmdemo.com. The SSL certificate provider will deliver you a zip file that contains a signed certificate (.crt file) and intermediate CA cert.

(4) After the certificate has been issued, combine the certificate (.crt) and bundle (bundle.crt) into a single file that is PEM-encoded.

The file needs to be formatted like this:

Note that a newline exists after each "END CERTIFICATE" line. KCM will reject a malformed certificate.

The private key file will be PEM-encoded, formatted like this:

(5) Transfer the 2 files to the KCM server

Copy the files to a location in the server which is running Keeper Connection Manager.

If you are using the Auto Docker install method of Keeper Connection Manager, a good place to put the files is in /etc/kcm-setup. Make sure to set the permissions appropriately, e.g.:

(6) Update the docker-compose.yml file with the SSL cert

Using your preferred editor, update the Docker Compose file. If you used the Auto Docker install method of KCM, the file will be located in /etc/kcm/setup/docker-compose.yml. The section to edit is below:

Make sure to edit the SSL_HOSTNAME and volume mount paths and filenames.

To restart the service with the new certificate:

Annual Renewal

Image: keeper/guacamole-ssl-nginx

keeper/guacamole-ssl-nginx is a Dockerized deployment of NGINX, built off which is pre-configured to provide SSL termination for Guacamole. It supports:

• that you have already obtained from a certificate authority.

This image is produced as part of Keeper Connection Manager and made available under the same . It is normally used to provide SSL termination for a container using the .

Supported Types of SSL certificates

The keeper/guacamole-ssl-nginx supports several mechanisms for generating, retrieving, or using existing SSL certificates. The mechanism used depends on which environment variables are specified when the Docker container is created.

In addition to these mechanism-specific environment variables, there is a set of environment variables that must always be specified:

• - Whether you accept the Keeper Connection Manager EULA (acceptance of the EULA is required to use the image).

• - The hostname/address of the Guacamole instance.

• - The public domain name that will be used to access Guacamole.

Let's Encrypt

Let's Encrypt is used by default if no existing certificate is supplied and generation of a self-signed certificate is not requested. The keeper/guacamole-ssl-nginx image will reach out to the Let's Encrypt service using the "certbot" tool to retrieve an SSL certificate.

Only one environment variable specific to Let's Encrypt is strictly required if using Let's Encrypt certificates:

• LETSENCRYPT_ACCEPT_TOS - Whether you accept the Let's Encrypt Terms of Service (acceptance of Let's Encrypt's Terms of Service is required to use that service).

In addition to accepting their Terms of Service, beware that Let's Encrypt strongly recommends providing an email address so that you can get important alerts regarding your certificate. You should additionally provide an email address unless you have a reason not to do so:

• LETSENCRYPT_EMAIL - The email address to submit to Let's Encrypt when requesting the certificate.

• LETSENCRYPT_STAGING - Set to "Y" to use Let's Encrypt's staging environment instead of production.

The retrieved certificate be automatically renewed by the image when necessary. If retrieval fails, the container will stop, details describing the failure will be logged, and the process will be retried the next time the container starts.

The keeper/guacamole-ssl-nginx image leverages Docker volumes to enable Let's Encrypt certificates and state to persist across container recreation.

For example, below will generate a Let's Encrypt certificate in your docker-compose.yml file:

Existing certificate from an arbitrary CA

If you already have a certificate that you obtained from a certificate authority, you can use that certificate by pointing to the relevant files with the CERTIFICATE_FILE and PRIVATE_KEY_FILE environment variables. The relevant files will need to be exposed to the image using Docker volume mounts.

• CERTIFICATE_FILE - The full path to the certificate PEM file.

• PRIVATE_KEY_FILE - The full path to the private key PEM file.

When your certificate comes up for renewal with your CA, you will need to replace the certificate and private key and reload NGINX. Stop and start the Docker Compose after the certificate has been updated.

For Docker Compose configuration, the example below will load a custom certificate from a shared volume that will hold the keys.

Self-signed Certificates

If deploying for testing, the image can automatically generate and maintain its own self-signed certificate:

• SELF_SIGNED - Set to "Y" to automatically generate a self-signed certificate for testing.

The keeper/guacamole-ssl-nginx image will regenerate the self-signed certificate on startup. As the certificate expires 30 days after generation, the image will also automatically regenerate the certificate every 21 days to ensure it does not expire.

The certificate expiration date and fingerprints will be logged each time the certificate is regenerated, allowing rudimentary server identity verification.

Environment Variables

ACCEPT_EULA

SSL_HOSTNAME

The public-facing hostname of the server hosting Docker. This environment variable is required and should be the full public domain name that will be used to access Guacamole over the internet, already associated with the IP address that reaches the server running Docker and this image.

GUACAMOLE_HOSTNAME

The internal hostname or IP address of the Guacamole server. This environment variable is required, and should be the hostname/address that NGINX will connect to internally when servicing connections.

Note that the Guacamole service whose hostname/address is provided here should be reachable only on the internal network. Only the SSL terminating service (this image) should be public-facing.

GUACAMOLE_PORT

The TCP port number that the Guacamole server is listening on. This environment variable is optional. If omitted, the typical port 8080 will be used by default.

GUACAMOLE_CONTEXT_PATH

The path that Guacamole is being served beneath. This environment variable is optional. By default, this will be blank, representing that Guacamole is being served from the root path. As with the GUACAMOLE_CONTEXT_PATH environment variable of the keeper/guacamole image, this parameter may not contain slashes.

For example, if Guacamole is running internally at http://some-host/guacamole/, you would set GUACAMOLE_CONTEXT_PATH to guacamole.

SELF_SIGNED

If set to "Y", requests that a self-signed certificate be automatically generated for SSL_HOSTNAME rather than using an existing certificate or retrieving a new certificate from Let's Encrypt.

Self-signed certificates are inherently insecure. This option should be used only for testing.

CERTIFICATE_FILE and PRIVATE_KEY_FILE

The paths of the PEM files for the SSL certificate and associated private key, respectively. These paths are relative to the filesystem of the Docker container. Externally-provided SSL certificate PEM files will need to be exposed within the container using Docker volume mounts.

These environment variables are only required if providing your own certificate. They will be ignored if using a self-signed certificate for testing with SELF_SIGNED.

LETSENCRYPT_ACCEPT_TOS

This environment variable is only required if using Let's Encrypt. It is ignored if providing your own certificate using CERTIFICATE_FILE and PRIVATE_KEY_FILE, or if using a self-signed certificate for testing with SELF_SIGNED.

LETSENCRYPT_EMAIL

The email address that should be provided to Let's Encrypt when requesting a certificate. This environment variable is optional and is ignored if providing your own certificate using CERTIFICATE_FILE and PRIVATE_KEY_FILE, or if using a self-signed certificate for testing with SELF_SIGNED.

While this environment variable is optional, beware that Let's Encrypt strongly recommends providing an email address when obtaining a certificate using their service. From the help content for the certbot tool:

... This is strongly discouraged, because in the event of key loss or account compromise you will irrevocably lose access to your account. You will also be unable to receive notice about impending expiration or revocation of your certificates. Updates to the Subscriber Agreement will still affect you, and will be effective 14 days after posting an update to the web site.

LETSENCRYPT_STAGING

Content Security Policy (CSP)

Content Security Policy (CSP) is a browser feature that allows web applications like KCM to declare to the browser what types of operations should be allowed in the context of that web application. In particular, CSP allows web applications to request that the browser block attempts to load resources or run scripts that the web application considers unsafe or unexpected. This is done by adding a Content-Security-Policy header to HTTP responses.

A default Content-Security-Policy header with known-good default value is set automatically by the keeper/guacamole-ssl-nginx image unless configured otherwise using the CONTENT_SECURITY_POLICY environment variable.

CONTENT_SECURITY_POLICY

Configures the value of the Content-Security-Policy header that will be sent in responses from Nginx.

If set to "Y", a reasonable default Content-Security-Policy value will be set that's known to work with most KCM installations: script-src 'self' 'unsafe-eval'; default-src 'self' data:; style-src 'self' 'unsafe-inline';. This configuration allows loading of assets from the same domain as KCM, along with allowing eval() for translations, and allowing JavaScript to dynamically load CSS.

If set to "N", the header will not be added to responses.

If this variable is set to any other value, the literal value of the variable will be sent with the response.

HTTP Strict Transport Security (HSTS)

HTTP Strict Transport Security (HSTS) is a browser feature that allows the owners of a domain to advise browsers that connections should only use HTTPS, and that any HTTP connections should be upgraded to HTTPS before being sent.

STRICT_TRANSPORT_SECURITY

Configures the value of the Strict-Transport-Security header that will be sent in responses from Nginx.

If set to "N", the header will not be added to responses.

If this variable is set to any other value, the literal value of the variable will be sent with the response.

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

For example, to load the Let's Encrypt account email from Docker secrets:

Advanced Configuration

SSL_CIPHERS

SSL_PROTOCOLS

SSL_EXTERNAL_PORT

Configures value of the X-Forwarded-Port header that will be sent to the KCM web application in requests from Nginx. This header advises the KCM server know that SSL requests are being received at a non-standard port.

If not specified, KCM will expect that inbound requests are coming from the standard HTTPS port (443).

ADDITIONAL_CONFIG

Arbitrary configuration for the server block that points at the KCM web application in the Nginx configuration files generated by this image.

This variable functions as a catch-all for applying Nginx configuration options that do not have corresponding environment variables in the keeper/guacamole-ssl-nginx image.

Any value provided via the ADDITIONAL_CONFIG environment variable will be included in the main server block pointing at the KCM web application. Only configuration options that Nginx will accept within a server block may be included here.

Keeper Connection Manager is packaged and installed in your environment. As such, backups should be taken in order to recover the environment if required.

It is highly recommended to perform backups of the following components:

3. and other critical files

Server Backup Instructions

• We recommend performing daily snapshots of your Keeper Connection Manager instances.

• In most installations, a database running locally or within the Docker containers includes the connection and user data. When backing up the instance, ensure that the database is included.

• When using the Advanced Linux Install method, ensure that the /etc/guacamole/ folder is included in the snapshot.

Database Snapshots

• For Docker and Auto Docker install methods, the kcm-setup.run backup command will run a backup locally.

• For other installation methods, please use the database platform's backup features, for example mysqladmin on MySQL-backed installs.

Docker compose

• Back up and protect the files located in /etc/kcm-setup/ which include docker-compose.yml and any other files which are being utilized by your container.