All pages
Powered by GitBook
1 of 20

Installation

Keeper Connection Manager installation instructions in the cloud or on-prem environments.

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.

The container running Keeper Connection Manager needs network access to the target desktops/systems that will be managed.

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.

If you plan to use Let's Encrypt as your CA, you should open port 80 and 443. LetsEncrypt uses port 80 to perform automated SSL certificate generation.

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.

License Key

Activating your Keeper Connection Manager license key

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.

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

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 your KCM on-prem license key. It can then be accessed directly from the Keeper Admin Console:

On-Prem License Key
License Key Download

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.

How to add your KCM license key to your docker-compose.yml

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

System Requirements

Detailed list of system and operating system requirements for Keeper Connection Manger

Supported Operating Systems:

The recommended method to install Keeper Connection Manager is via the automated docker install. 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:

The generalized formula for sizing Keeper Connection Manager is 1 CPU core and 2 GB of memory for every 25 concurrent users anticipated. We recommend a minimum of 8GB RAM and 2 cores for any small deployment.

Minimum host recommendations:

# Concurrent connections
CPU
Min. RAM

0-25

2

8gb

26-50

3

12gb

51-100

4

16gb

101-200

8

32gb

200+

Contact us

Contact us

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.

There are far too many variables in play to accurately predict disk space needs for recordings. The best practices are to monitor the recordings folder and offload them to another location as needed.

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.

Preparing for Installation

Get your environment, network, and system ready and prepared.

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.

On RHEL, the haveged package is not available from the Red Hat repositories and must instead be installed from the EPEL repository. EPEL provides instructions for configuring their repository here: https://docs.fedoraproject.org/en-US/epel/. After EPEL is installed, run the following commands:

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

Auto Docker Install

Automated Linux Docker installer for users without Docker experience

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.

If you want to use Let's Encrypt (option 1) to quickly and easily generate and install an SSL certificate, you must have public DNS in place pointing to your static public IP. Also, Let's Encrypt requires HTTP port 80 and HTTPS port 443 to be open during the install process.

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.

LogoAuthenticating Users with SAMLKeeper Connection Manager

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!

Store the provided username, password, and URL in your Keeper Vault

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.

Initial login screen

🎉 Installation Complete!

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.

How to Use KCM

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

Service Management

Auto Docker Install service management

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.

Command
Description

backup

Backup all database data to a file.

check

Perform an automated self-check of all services.

install

Install Keeper Connection Manager (DEFAULT).

logs

Display the log files from all installed services.

reconfigure

Modify the configuration of an existing KCM installation.

restart

Restart all installed services, starting any that are stopped.

restore

Restore database data from a prior backup.

start

Start all installed services that are not started.

status

Display the status of installed services.

stop

Stop all installed services that are not stopped.

uninstall

Completely remove the existing installation. This will delete all stored data in the database.

upgrade

Upgrade the existing installation by pulling the latest docker images. Your data stored in the service is retained.

apply

Strictly apply changes made externally to docker-compose.yml and do not pull new images.

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.

Upgrading

Upgrading Keeper Connection Manager with the Docker Automated Install method

Before making any changes to your environment, we recommend backing up in accordance with the instructions on the Backup and Recovery page.

Update Instructions

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

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

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

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

Select "Y" when prompted.

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

If you run into any issues during the upgrade, see Troubleshooting

Adding Packages

Activating additional packages on the Auto Docker Install method

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

Docker Compose Install

Deployment of Keeper Connection Manager using Docker Compose

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

Install Docker Desktop following Docker's official instructions.

Amazon Linux 2

Install Docker on your instance. A nice step by step guide is published here.

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.

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

Ubuntu

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

sudo apt-get install haveged

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.

version: "3"
services:

    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"
        volumes:
            - "common-storage:/var/lib/guacamole:rw"

    db:
        image: keeper/guacamole-db-mysql:2
        restart: unless-stopped
        environment:
            ACCEPT_EULA: "Y"
            MYSQL_RANDOM_ROOT_PASSWORD: "yes"
            GUACAMOLE_DATABASE: guacamole_db
            GUACAMOLE_USERNAME: guacamole_user
            GUACAMOLE_PASSWORD: some_strong_password
            GUACAMOLE_ADMIN_PASSWORD: some_strong_password

    guacamole:
        image: keeper/guacamole:2
        restart: unless-stopped
        environment:
            ACCEPT_EULA: "Y"
            GUACD_HOSTNAME: guacd
            MYSQL_HOSTNAME: db
            MYSQL_DATABASE: guacamole_db
            MYSQL_USERNAME: guacamole_user
            MYSQL_PASSWORD: some_password
            KCM_LICENSE: "XXXXXXXXXXXXXXXXXXXXXXXXXX"
        volumes:
            - "common-storage:/var/lib/guacamole:rw"

    ssl:
        image: keeper/guacamole-ssl-nginx:2
        restart: unless-stopped
        ports:
            - "80:80"
            - "443:443"
        environment:
            ACCEPT_EULA: "Y"
            GUACAMOLE_HOSTNAME: guacamole
            SSL_HOSTNAME: keeper.mycompany.com
            LETSENCRYPT_ACCEPT_TOS: "Y"
            LETSENCRYPT_EMAIL: you@company.com

volumes:
    common-storage:

Copy this file to your target KCM instance. Please note that you'll need to modify a few of the fields immediately:

  • shm_size should be roughly half of available physical memory on the instance.

  • security_opt refers to the path of the seccomp security profile and must be included for remote browser isolation.

  • GUACAMOLE_PASSWORD and MYSQL_PASSWORD need to match, and should be a randomly generated strong password. We recommend using your Keeper vault for generating a password. Avoid using special characters like backslashes, dollar signs and forward slashes.

  • GUACAMOLE_ADMIN_PASSWORD is the password for the default "guacadmin" user login. This should be a strong and randomly generated password. We recommend using your Keeper vault for generating a password. Avoid using special characters like backslashes, dollar signs and forward slashes.

  • SSL_HOSTNAME needs to be the FQDN you set up to point to this server. Make sure that the DNS is routable to the IP from the outside world, and ports 80/443 are open so that Let's Encrypt can register the certificate.

version: "3"
services:

    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"
        volumes:
            - "common-storage:/var/lib/guacamole:rw"

    db:
        image: keeper/guacamole-db-postgres:2
        restart: unless-stopped
        environment:
            ACCEPT_EULA: "Y"
            POSTGRES_PASSWORD: some_strong_password
            GUACAMOLE_DATABASE: guacamole_db
            GUACAMOLE_USERNAME: guacamole_user
            GUACAMOLE_PASSWORD: some_strong_password
            GUACAMOLE_ADMIN_PASSWORD: some_strong_password

    guacamole:
        image: keeper/guacamole:2
        restart: unless-stopped
        environment:
            ACCEPT_EULA: "Y"
            GUACD_HOSTNAME: "guacd"
            POSTGRES_HOSTNAME: "db"
            POSTGRES_DATABASE: "guacamole_db"
            POSTGRES_USERNAME: "guacamole_user"
            POSTGRES_PASSWORD: "xxxxxxx"
        volumes:
            - "common-storage:/var/lib/guacamole:rw"

    ssl:
        image: keeper/guacamole-ssl-nginx:2
        restart: unless-stopped
        ports:
            - "80:80"
            - "443:443"
        environment:
            ACCEPT_EULA: "Y"
            GUACAMOLE_HOSTNAME: guacamole
            SSL_HOSTNAME: keeper.mycompany.com
            LETSENCRYPT_ACCEPT_TOS: "Y"
            LETSENCRYPT_EMAIL: you@company.com

volumes:
    common-storage:

Copy this file to your target KCM instance. Please note that you'll need to modify a few of the fields immediately:

  • shm_size should be roughly half of available physical memory on the instance.

  • security_opt refers to the path of the seccomp security profile and must be included for remote browser isolation.

  • GUACAMOLE_PASSWORD and POSTGRES_PASSWORD need to match, and should be a randomly generated strong password. We recommend using your Keeper vault for generating a password. Avoid using special characters like backslashes, dollar signs and forward slashes.

  • GUACAMOLE_ADMIN_PASSWORD is the password for the default "guacadmin" user login. This should be a strong and randomly generated password. We recommend using your Keeper vault for generating a password. Avoid using special characters like backslashes, dollar signs and forward slashes.

  • SSL_HOSTNAME needs to be the FQDN you set up to point to this server. Make sure that the DNS is routable to the IP from the outside world, and ports 80/443 are open so that Let's Encrypt can register the certificate.

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:

    ssl:
        image: keeper/guacamole-ssl-nginx:2
        restart: unless-stopped
        ports:
            - "80:80"
            - "443:443"
        environment:
            SELF_SIGNED: "N"
            ACCEPT_EULA: "Y"
            GUACAMOLE_HOSTNAME: "guacamole"
            SSL_HOSTNAME: "keeper.mycompany.com"
            CERTIFICATE_FILE: "/var/lib/guacamole/your_certificate.pem"
            PRIVATE_KEY_FILE: "/var/lib/guacamole/your_private_key.key"
        volumes:
            - "C:\Users\Path\To\Cert:/var/lib/guacamole:ro"

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:

docker compose up -d

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.

Keeper Connection Manager Login Screen

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:

docker run --rm --entrypoint=/bin/cat keeper/guacd:2 /opt/keeper/share/guacd/docker-seccomp.json

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.

Image name
Base image
Description

keeper/guacamole

centos:7

The Apache Guacamole web application, deployed under Apache Tomcat.

keeper/guacd

centos:7

The Apache Guacamole proxy daemon, guacd, with support for native protocols such as RDP and SSH.

keeper/guacamole-db-mysql

mysql:5

An instance of MySQL, automatically initialized with the Apache Guacamole database schema.

keeper/guacamole-db-postgres

postgres:11

An instance of PostgreSQL, automatically initialized with the Apache Guacamole database schema.

keeper/guacamole-ssl-nginx

nginx:stable

An instance of NGINX which automatically provides SSL termination for Keeper Connection Manager.

🎉 Installation Complete!

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.

How to Use KCM

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.

keeper/guacamole

Docker deployment of Apache Guacamole with Keeper Connection Manager

Image: keeper/guacamole

To activate advanced features of Keeper Connection Manager, you simply add an environmental variable to the docker file that controls the feature, or you add one of the EXTENSIONS flags as documented below.

Arbitrary third-party extensions may be used through volume mounts and setting ADDITIONAL_GUACAMOLE_PROPERTIES variables as needed.

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

Variable name
Description

API_MAX_REQUEST_SIZE

The maximum number of bytes to accept within the entity body of any particular HTTP request to the REST API, including authentication requests. This limit does not apply to files transferred within a remote desktop session. Specifying 0 disables request size limitations. By default, requests are limited to 2097152 bytes (2 MB).

API_SESSION_TIMEOUT

The amount of time, in minutes, a Guacamole session may remain valid despite being inactive. By default, Guacamole sessions are limited to one hour.

This setting affects Guacamole sessions only, not remote desktop sessions. To enforce limits on the duration of remote desktop sessions, you must change the relevant setting within your remote desktop server, such as the session time limit GPOs provided by the Windows RDP server. Guacamole considers a connected remote desktop session to be user activity, and does not attempt to define what constitutes an idle but connected remote desktop session.

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:

Variable name
Description

AWS_DISCOVERY_ACCESS_KEY_ID

The access key ID for the AWS account that should be used to authenticate with AWS.

AWS_DISCOVERY_SECRET_KEY

The secret key associated with the access key

AWS_DISCOVERY_REGIONS

Comma-separated list of regions to query for EC2 instances, such as us-west-1,us-east-1.

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

Variable name
Description

AWS_DISCOVERY_INSTANCE_BASE_PATH

The name of the organizational connection group that should be used to house the EC2 instances for convenience. By default, this will be "Amazon EC2".

AWS_DISCOVERY_ADMIN_GROUP

The name of the User Group in Keeper Connection Manager to require for any user to see the discovered EC2 instances. By default, this will be a group called "AWS EC2 Administrators".

AWS_DISCOVERY_RECORD_CONNECTIONS_BY_DEFAULT

If set to "true", screen recording will be enabled by default on all connections. Connection session recording can also be set at an individual machine level using the "kcm:record" EC2 instance tag, which overrides the value set here, if any.

AWS_DISCOVERY_KSM_CONFIG

The base64-encoded Keeper Secrets Manager configuration to use to retrieve the private keys for EC2 instances from the Keeper vault.

AWS_DISCOVERY_KSM_API_CALL_INTERVAL

The minimum number of milliseconds that must elapse between API calls to Keeper Secrets Manager. By default, KCM will wait 10 seconds between each call, using cached data from the last retrieval until another retrieval attempt is allowed.

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.

Variable name

BAN_ADDRESS_DURATION

The amount of time an IP address is temporarily blocked after repeatedly failing to authenticate, in seconds. By default, addresses are blocked for 5 minutes.

BAN_MAX_ADDRESSES

The maximum number of IP addresses that KCM will track to check for invalid attempts. By default, up to 10485760 addresses will be tracked.

BAN_MAX_INVALID_ATTEMPTS

The number of invalid attempts that may occur before the source IP address is temporarily blocked from further attempts. By default, 5 failed authentication attempts will result in a temporary block.

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:

Environment Variable
Description

DUO_API_HOSTNAME

REQUIRED. The hostname of the Duo API endpoint that will be used to verify user identities, assigned by Duo when Guacamole was added as a "Web SDK" application. This value can be found within the application details in Duo's "Admin" panel.

DUO_AUTH_TIMEOUT

The timeout, in minutes, for in-progress Duo authentication attempts. Authentication attempts exceeding this duration will be invalidated. By default, Duo authentication attempts will time out after 5 minutes.

DUO_CLIENT_ID

REQUIRED. The client ID provided for you by Duo when KCM was added as a "Web SDK" application. This value can be found within the application details in Duo's "Admin" panel.

DUO_CLIENT_SECRET

REQUIRED. The client secret provided for you by Duo when KCM was added as a "Web SDK" application. This value can be found within the application details in Duo's "Admin" panel.

DUO_REDIRECT_URI

REQUIRED. The user-facing URI that the Duo service can use to redirect an authenticated user's browser back to KCM. This is the URI that you use for the KCM deployment, e.g. https://kcm.company.com

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

Extension name
Declared capability
Corresponding package

duo

guacamole(duo)

kcm-guacamole-auth-duo

json

guacamole(json)

kcm-guacamole-auth-json

ldap

guacamole(ldap)

kcm-guacamole-auth-ldap

mysql

guacamole(mysql)

kcm-guacamole-auth-jdbc-mysql

openid

guacamole(openid)

kcm-guacamole-auth-sso-openid

postgresql

guacamole(postgresql)

kcm-guacamole-auth-jdbc-postgresql

saml

guacamole(saml)

kcm-guacamole-auth-sso-saml

sqlserver

guacamole(sqlserver)

kcm-guacamole-auth-jdbc-sqlserver

ssl

guacamole(ssl)

kcm-guacamole-auth-sso-ssl

totp

guacamole(totp)

kcm-guacamole-auth-totp

uds

guacamole(uds)

kcm-guacamole-auth-uds

This variable is mainly of use for extensions which can be used without setting any configuration options, like TOTP two-factor authentication, or to force sanity checks on the presence of required environment variables even if all associated variables might be accidentally omitted. Extensions not listed within this environment variable will still be included if any of their corresponding environment variables are set.

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:

Description
Value of EXTENSION_PRIORITY

Force SAML to take priority over all other extensions.

saml

Force all other extensions to take priority over SAML.

*, saml

Prefer LDAP over any other authentication method, and force all other extensions to take priority over SAML and OpenID.

ldap, *, saml, openid

GUACD_*

TCP connection information for guacd.

Variable name
Description

GUACD_HOSTNAME

The hostname of the machine hosting the guacd service.

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

Variable name
Description

GUACD_PORT

The port used by the guacd service.

GUACD_SSL

Whether the guacd service has been configured for SSL/TLS.

JSON_*

All environment variables which start with JSON_ correspond to configuration properties for encrypted JSON authentication which would normally be specified within guacamole.properties.

The following environment variables are required if using encrypted JSON authentication:

Variable name
Description

JSON_SECRET_KEY

The shared secret key that will be used by systems generating JSON data to encrypt and sign that data. This key must be 128 bits, specified with 32 hexadecimal digits.

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

Variable name
Description

JSON_TRUSTED_NETWORKS

A comma-separated list of trusted IP addresses and/or CIDR subnets which should be allowed to send encrypted JSON. If omitted, any address will be allowed to send JSON.

KSM_*

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

Variable name
Description

KSM_ALLOW_USER_CONFIG

If set to "true", users will be allowed to provide their own KSM configuration or one-time token. Vault records of users that provide this will be additionally considered for any connection that (1) an administrator enables for use with user vaults and (2) contains a token that cannot be satisfied with a record from the system-wide vault configured with KSM_CONFIG. By default, users are not allowed to provide their own KSM configuration.

KSM_API_CALL_INTERVAL

The minimum number of milliseconds that must elapse between API calls to Keeper Secrets Manager. By default, KCM will wait 10 seconds between each call, using cached data from the last retrieval until another retrieval attempt is allowed.

KSM_CONFIG

The Keeper Secrets Manager b64 configuration, generated by Keeper Commander.

KSM_MATCH_DOMAINS_FOR_USERS

If set to "true", Active Directory domains within KSM records and KCM connections will be considered when determining whether a record matches a username. By default, only the username itself is considered.

KSM_STRIP_WINDOWS_DOMAINS

If set to "true", Active Directory domains within KSM records will be alternatively determined by splitting the record username into username and domain components. Splitting is performed based on the User Principal Name and Down-Level Logon Name formats. By default, usernames are not split, and Windows domains will be read only from a separate "Domain" field on the record.

KSM_TOKEN_MAPPING

Static tokens used to identify specific Keeper vault records and fields.

*_KSM_SECRET

Used for protection and storage of configuration values in the Keeper vault.

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

Variable name
Description

LDAP_HOSTNAME

The hostname or IP address of the LDAP server that Guacamole should use for authentication.

LDAP_USER_BASE_DN

The common base DN shared by all Guacamole users within the LDAP directory.

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

Variable name
Description

LDAP_SERVERS

A list of LDAP servers in the proper yml format. Follow this guide.

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

Variable name
Description

LDAP_PORT

The TCP port that the LDAP server is listening on. If omitted, the standard LDAP or LDAPS port will be used, depending on the encryption method. Unencrypted LDAP uses the standard port of 389, while LDAPS uses port 636.

LDAP_ENCRYPTION_METHOD

The encryption mechanism to use when communicating with your LDAP server, if any. Legal values are "none" for unencrypted LDAP, "ssl" for LDAP over SSL/TLS (commonly known as LDAPS), or "starttls" for STARTTLS. If omitted, encryption will not be used.

LDAP_NETWORK_TIMEOUT

The maximum amount of time to allow for any LDAP network operation, in milliseconds, including attempts to connect to the LDAP server. By default, LDAP network operations will time out after 30 seconds (30000 milliseconds). Note that this value is intentionally more granular than LDAP_OPERATION_TIMEOUT, as failover to alternative LDAP servers may need to occur quickly if multiple LDAP servers are configured.

LDAP_OPERATION_TIMEOUT

The maximum amount of time to allow for any LDAP query, in seconds. By default, LDAP queries will time out after 30 seconds.

LDAP_USERNAME_ATTRIBUTE

The attribute which contains the username within all relevant user objects in the LDAP directory. If multiple attributes may contain the username, multiple attributes may be specified separated by commas, and a search DN is required.

LDAP_SEARCH_BIND_DN

The DN that the web application should bind as when determining the DN of the user attempting to authenticate. Specifying a search DN is required if usernames may be within any one of several attributes, or if the user's username is not part of their DN.

LDAP_SEARCH_BIND_PASSWORD

The password to use when authenticating with the search DN.

LDAP_CONFIG_BASE_DN

The common base DN shared by all guacConfigGroup objects, if the LDAP directory is being used to store connection data.

LDAP_GROUP_BASE_DN

The common base DN shared by all user groups which may dictate guacConfigGroup access within the LDAP directory via the seeAlso attribute.

LDAP_MAX_SEARCH_RESULTS

The maximum number of results to attempt to retrieve from the LDAP directory for any particular search. Searches which exceed this limit will fail. By default, searches are limited to 1000 entries.

LDAP_USER_SEARCH_FILTER

The LDAP search filter to use when querying user accounts. If omitted, (objectClass=*) will be used by default.

LDAP_GROUP_SEARCH_FILTER

The LDAP search filter to use when retrieving groups. If omitted, (objectClass=*) will be used by default.

LDAP_DEREFERENCE_ALIASES

Whether aliases should be automatically dereferenced. Legal values are "never", "searching" (dereference only after the base DN is located), "finding" (dereference only when locating the base DN), and "always". By default, aliases are not derefenced.

LDAP_FOLLOW_REFERRALS

If "true", automatically follow referrals received from the LDAP directory. By default, LDAP referrals are not followed.

LDAP_MAX_REFERRAL_HOPS

The maximum number of referrals that may be followed when resolving any particular LDAP referral. By default, if LDAP automatic following of referrals is enabled, up to 5 hops are allowed for any one referral.

CA_CERTIFICATES

The contents of one or more certificates used by your internal certificate authority (CA), in PEM form. When specified, SSL/TLS connections to other servers will be verified against these certificates, including connections to LDAP servers that use SSL/TLS.

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:

Variable name
Description

MYSQL_HOSTNAME

The hostname or IP address of the MySQL or MariaDB server hosting the Guacamole database.

MYSQL_DATABASE

The name of the database that has been created for Guacamole on the MySQL or MariaDB server.

MYSQL_USERNAME

The username that Guacamole should use when authenticating with the MySQL or MariaDB server.

MYSQL_PASSWORD

The password that Guacamole should provide when authenticating with the MySQL or MariaDB server.

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

Variable name
Description

MYSQL_PORT

The TCP port that the MySQL or MariaDB server is listening on. If omitted, the standard MySQL port of 3306 will be used.

MYSQL_USER_PASSWORD_MIN_LENGTH

The minimum length to require for user passwords. By default, password complexity is not enforced.

MYSQL_USER_PASSWORD_REQUIRE_MULTIPLE_CASE

If set to "true", require that user passwords use both uppercase and lowercase characters.

MYSQL_USER_PASSWORD_REQUIRE_SYMBOL

If set to "true", require that user passwords contain at least one symbol. By default, password complexity is not enforced.

MYSQL_USER_PASSWORD_REQUIRE_DIGIT

If set to "true", require that user passwords contain at least one digit. By default, password complexity is not enforced.

MYSQL_USER_PASSWORD_PROHIBIT_USERNAME

If set to "true", disallow user passwords that contain the user's username. By default, password complexity is not enforced.

MYSQL_USER_PASSWORD_MIN_AGE

The minimum number of days that must elapse following a password change before the user may change their password again. By default, users are not required to wait before changing their password.

MYSQL_USER_PASSWORD_MAX_AGE

The maximum number of days that may elapse since the last password change before the user is required to change their password. By default, users are not required to regularly change their password.

MYSQL_USER_PASSWORD_HISTORY_SIZE

Remember this number of previous passwords and prohibit reuse of those passwords when the user's password is changed. By default, users are allowed to reuse previous passwords.

MYSQL_DEFAULT_MAX_CONNECTIONS

The maximum number of concurrent connections to allow to any particular connection, regardless of user, where a value of "0" indicates unlimited. By default, concurrent usage of connections is not limited.

MYSQL_DEFAULT_MAX_GROUP_CONNECTIONS

The maximum number of concurrent connections to allow to any particular connection group, regardless of user, where a value of "0" indicates unlimited. By default, concurrent usage of connection groups is not limited.

MYSQL_DEFAULT_MAX_CONNECTIONS_PER_USER

The maximum number of concurrent connections to allow each user to hold to any particular connection, where a value of "0" indicates unlimited. By default, user-specific concurrent usage of connections is not limited.

MYSQL_DEFAULT_MAX_GROUP_CONNECTIONS_PER_USER

The maximum number of concurrent connections to allow each user to hold to any particular connection group, where a value of "0" indicates unlimited. By default, user-specific concurrent usage of connection groups is limited to one.

MYSQL_ABSOLUTE_MAX_CONNECTIONS

The maximum number of concurrent connections to allow to overall, regardless of user, connection or connection group, where a value of "0" indicates unlimited. By default, overall concurrent usage is not limited.

MYSQL_USER_REQUIRED

If set to "true", require that each user have a corresponding account defined within the database, even if the user authenticated through some other mechanism (such as LDAP). By default, users that successfully authenticate through another mechanism are not required to also have an account within the database.

MYSQL_TRACK_EXTERNAL_CONNECTION_HISTORY

Whether connections that do not exist within the database should have connection history tracked in the database. If set to "true", connection history records will be created for any connection established. If set to "false", connection history records will be created only for connections defined in the database. By default, external connections will be tracked.

MYSQL_ENFORCE_ACCESS_WINDOWS_FOR_ACTIVE_SESSIONS

Whether access time restrictions imposed by the administrator on user accounts should be enforced while a user is logged in. If set to "true", users will be automatically logged out within roughly one minute of reaching their access time limits. If set to "false", access time restrictions will only be enforced at the moment a user attempts to log in. By default, access time restrictions are enforced while users are logged in.

MYSQL_AUTO_CREATE_ACCOUNTS

Whether user account entries should automatically be created within the database for users that successfully authenticate through other means, such as an SSO provider or LDAP. This may be necessary if using an extension that requires account-specific storage, like TOTP or per-account approvals. If set to "true", user account entries will automatically be created. By default, administrators must manually create such entries if needed.

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.

Variable Name
Description

OPENID_AUTHORIZATION_ENDPOINT

The authorization endpoint (URI) of the OpenID service. This value should be provided to you by the identity provider. For identity providers that implement OpenID Connect Discovery, this value can be retrieved from the "authorization_endpoint" property of your provider's ".well-known/openid-configuration" JSON file.

OPENID_CLIENT_ID

The OpenID client ID which should be submitted to the OpenID service when necessary. This value is typically provided to you by the OpenID service when OpenID credentials are generated for your application.

OPENID_ISSUER

The issuer to expect for all received ID tokens. This value should be provided to you by the identity provider. For identity providers that implement OpenID Connect Discovery, this value can be retrieved from the "issuer" property of your provider's

".well-known/openid-configuration" JSON file.

OPENID_JWKS_ENDPOINT

The endpoint (URI) of the JWKS service which defines how received ID tokens (JSON Web Tokens or JWTs) shall be validated. This value should be provided to you by the identity provider. For identity providers that

implement OpenID Connect Discovery, this value can be retrieved from the "jwks_uri" property of your provider's ".well-known/openid-configuration" JSON file.

OPENID_REDIRECT_URI

The URI that should be submitted to the OpenID service such that they can redirect the authenticated user back to Keeper Connection Manager after the authentication process is complete. This must be the full URL that a user would enter into their browser to access Keeper Connection Manager. The URI that should be submitted to the OpenID service such that they can redirect the authenticated user back to Keeper Connection Manager after the authentication process is complete. This must be the full URL that a user would enter into their browser to access Keeper Connection Manager.

Optional variables:

Variable Name
Description

OPENID_ALLOWED_CLOCK_SKEW

The amount of clock skew tolerated for timestamp comparisons between the Guacamole server and OpenID service clocks, in seconds. By default, clock skew of up to 30 seconds is tolerated.

OPENID_GROUPS_CLAIM_TYPE

The claim type within any valid JWT that contains the list of groups of which the authenticated user is a member. By default, the “groups” claim type is used.

OPENID_MAX_NONCE_VALIDITY

The maximum amount of time that a nonce generated by the Guacamole server should remain valid, in minutes. As each OpenID request has a unique nonce value, this imposes an upper limit on the amount of time any particular OpenID request can result in successful authentication within Guacamole. By default, each generated nonce expires after 10 minutes.

OPENID_MAX_TOKEN_VALIDITY

The maximum amount of time that an OpenID token should remain valid, in minutes. By default, each OpenID token remains valid for 300 minutes (5 hours).

OPENID_SCOPE

The space-separated list of OpenID scopes to request. OpenID scopes determine the information returned within the OpenID token, and thus affect what values can be used as an authenticated user’s username. To be compliant with OpenID, at least “openid profile” must be requested. By default, “openid email profile” is used.

OPENID_USERNAME_CLAIM_TYPE

The claim type within any valid JWT that contains the list of groups of which the authenticated user is a member. By default, the “groups” claim type is used.

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:

Variable name
Description

POSTGRES_HOSTNAME

The hostname or IP address of the PostgreSQL server hosting the Guacamole database.

POSTGRES_DATABASE

The name of the database that has been created for Guacamole on the PostgreSQL server.

POSTGRES_USERNAME

The username that Guacamole should use when authenticating with the PostgreSQL server.

POSTGRES_PASSWORD

The password that Guacamole should provide when authenticating with the PostgreSQL server.

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

Variable name
Description

POSTGRES_PORT

The TCP port that the PostgreSQL server is listening on. If omitted, the standard PostgreSQL port of 5432 will be used.

POSTGRES_USER_PASSWORD_MIN_LENGTH

The minimum length to require for user passwords. By default, password complexity is not enforced.

POSTGRES_USER_PASSWORD_REQUIRE_MULTIPLE_CASE

If set to "true", require that user passwords use both uppercase and lowercase characters.

POSTGRES_USER_PASSWORD_REQUIRE_SYMBOL

If set to "true", require that user passwords contain at least one symbol. By default, password complexity is not enforced.

POSTGRES_USER_PASSWORD_REQUIRE_DIGIT

If set to "true", require that user passwords contain at least one digit. By default, password complexity is not enforced.

POSTGRES_USER_PASSWORD_PROHIBIT_USERNAME

If set to "true", disallow user passwords that contain the user's username. By default, password complexity is not enforced.

POSTGRES_USER_PASSWORD_MIN_AGE

The minimum number of days that must elapse following a password change before the user may change their password again. By default, users are not required to wait before changing their password.

POSTGRES_USER_PASSWORD_MAX_AGE

The maximum number of days that may elapse since the last password change before the user is required to change their password. By default, users are not required to regularly change their password.

POSTGRES_USER_PASSWORD_HISTORY_SIZE

Remember this number of previous passwords and prohibit reuse of those passwords when the user's password is changed. By default, users are allowed to reuse previous passwords.

POSTGRES_DEFAULT_MAX_CONNECTIONS

The maximum number of concurrent connections to allow to any particular connection, regardless of user, where a value of "0" indicates unlimited. By default, concurrent usage of connections is not limited.

POSTGRES_DEFAULT_MAX_GROUP_CONNECTIONS

The maximum number of concurrent connections to allow to any particular connection group, regardless of user, where a value of "0" indicates unlimited. By default, concurrent usage of connection groups is not limited.

POSTGRES_DEFAULT_MAX_CONNECTIONS_PER_USER

The maximum number of concurrent connections to allow each user to hold to any particular connection, where a value of "0" indicates unlimited. By default, user-specific concurrent usage of connections is not limited.

POSTGRES_DEFAULT_MAX_GROUP_CONNECTIONS_PER_USER

The maximum number of concurrent connections to allow each user to hold to any particular connection group, where a value of "0" indicates unlimited. By default, user-specific concurrent usage of connection groups is limited to one.

POSTGRES_ABSOLUTE_MAX_CONNECTIONS

The maximum number of concurrent connections to allow to overall, regardless of user, connection or connection group, where a value of "0" indicates unlimited. By default, overall concurrent usage is not limited.

POSTGRES_USER_REQUIRED

If set to "true", require that each user have a corresponding account defined within the database, even if the user authenticated through some other mechanism (such as LDAP). By default, users that successfully authenticate through another mechanism are not required to also have an account within the database.

POSTGRESQL_TRACK_EXTERNAL_CONNECTION_HISTORY

Whether connections that do not exist within the database should have connection history tracked in the database. If set to "true", connection history records will be created for any connection established. If set to "false", connection history records will be created only for connections defined in the database. By default, external connections will be tracked.

POSTGRESQL_ENFORCE_ACCESS_WINDOWS_FOR_ACTIVE_SESSIONS

Whether access time restrictions imposed by the administrator on user accounts should be enforced while a user is logged in. If set to "true", users will be automatically logged out within roughly one minute of reaching their access time limits. If set to "false", access time restrictions will only be enforced at the moment a user attempts to log in. By default, access time restrictions are enforced while users are logged in.

POSTGRESQL_AUTO_CREATE_ACCOUNTS

Whether user account entries should automatically be created within the database for users that successfully authenticate through other means, such as an SSO provider or LDAP. This may be necessary if using an extension that requires account-specific storage, like TOTP or per-account approvals. If set to "true", user account entries will automatically be created. By default, administrators must manually create such entries if needed.

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:

Description
Value of REQUIRE_ACCOUNT_APPROVAL

Require approval for logins from SAML.

saml

Require approval for logins from SAML and LDAP.

saml, ldap

Account approval status can only be stored and enforced on users with identities in the KCM database. Depending on which database you are using, you can request that KCM automatically create this storage for accounts that do not yet exist within the database by setting one of the following environment variables to "true":

  • MYSQL_AUTO_CREATE_ACCOUNTS

  • POSTGRESQL_AUTO_CREATE_ACCOUNTS

  • SQLSERVER_AUTO_CREATE_ACCOUNTS

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:

Variable Name
Description

SAML_CALLBACK_URL

The URI that should be submitted to the SAML service such that they can POST the authentication result to Keeper Connection Manager and redirect the user back to the application. This must be the full URL that a user would enter into their browser to access Keeper Connection Manager.

Optional environmental variables:

Variable Name
Description

SAML_COMPRESS_REQUEST

Enable compression of the HTTP requests sent to the SAML IdP. This property is optional and will default to true (compression enabled).

SAML_COMPRESS_RESPONSE

Request that the SAML response returned by the IdP be compressed. This property is optional and will default to true (compression will be requested).

SAML_ENTITY_ID

The entity ID of the Guacamole SAML client, which is generally the URL of the Guacamole server, but is not required to be so. This property is required if either the saml-idp-metadata-url property is not specified, or if the provided metadata file does not contain the SAML SP Entity ID for Guacamole Client.

SAML_GROUP_ATTRIBUTE

The name of the attribute provided by the SAML IdP that contains group membership of the user. These groups will be parsed and used to map group membership of the user logging in, which can be used for permissions management within Guacamole Client, particularly when layered with other authentication modules. This property is optional, and defaults to “groups”.

SAML_IDP_METADATA_URL

The URI of the XML metadata file that from the SAML Identity Provider that contains all of the information the SAML extension needs in order to know how to authenticate with the IdP. This URI can either be a remote server (e.g. https://) or a local file on the filesystem (e.g. file://). Often the metadata file contains most of the required properties for SAML authentication and the other parameters are not required.

SAML_IDP_URL

The base URL of the SAML IdP. This is the URL that the SAML authentication extension will use to redirect when requesting SAML authentication. If the saml-idp-metadata-url property is provided, this parameter will be ignored. If the metadata file is not provided this property is required.

SAML_PRIVATE_KEY_PATH

The full path of the private key in PEM format that should be used to sign SAML requests submitted to the SAML IdP. This is required only if the SAML IdP requires signed requests. By default, SAML requests are not signed.

SAML_X509_CERT_PATH

The full path of the X.509 certificate in PEM format that should be used to sign SAML requests submitted to the SAML IdP. This is required only if the SAML IdP requires signed requests. By default, SAML requests are not signed.

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:

Variable name
Description

SQLSERVER_HOSTNAME

The hostname or IP address of the SQL Server instance hosting the Guacamole database.

SQLSERVER_DATABASE

The name of the database that has been created for Guacamole on the SQL Server instance.

SQLSERVER_USERNAME

The username that Guacamole should use when authenticating with the SQL Server instance.

SQLSERVER_PASSWORD

The password that Guacamole should provide when authenticating with the SQL Server instance.

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

Variable name
Description

SQLSERVER_PORT

The TCP port that the SQL Server instance is listening on. If omitted, the standard SQL Server port of 1433 will be used.

SQLSERVER_USER_PASSWORD_MIN_LENGTH

The minimum length to require for user passwords. By default, password complexity is not enforced.

SQLSERVER_USER_PASSWORD_REQUIRE_MULTIPLE_CASE

If set to "true", require that user passwords use both uppercase and lowercase characters.

SQLSERVER_USER_PASSWORD_REQUIRE_SYMBOL

If set to "true", require that user passwords contain at least one symbol. By default, password complexity is not enforced.

SQLSERVER_USER_PASSWORD_REQUIRE_DIGIT

If set to "true", require that user passwords contain at least one digit. By default, password complexity is not enforced.

SQLSERVER_USER_PASSWORD_PROHIBIT_USERNAME

If set to "true", disallow user passwords that contain the user's username. By default, password complexity is not enforced.

SQLSERVER_USER_PASSWORD_MIN_AGE

The minimum number of days that must elapse following a password change before the user may change their password again. By default, users are not required to wait before changing their password.

SQLSERVER_USER_PASSWORD_MAX_AGE

The maximum number of days that may elapse since the last password change before the user is required to change their password. By default, users are not required to regularly change their password.

SQLSERVER_USER_PASSWORD_HISTORY_SIZE

Remember this number of previous passwords and prohibit reuse of those passwords when the user's password is changed. By default, users are allowed to reuse previous passwords.

SQLSERVER_DEFAULT_MAX_CONNECTIONS

The maximum number of concurrent connections to allow to any particular connection, regardless of user, where a value of "0" indicates unlimited. By default, concurrent usage of connections is not limited.

SQLSERVER_DEFAULT_MAX_GROUP_CONNECTIONS

The maximum number of concurrent connections to allow to any particular connection group, regardless of user, where a value of "0" indicates unlimited. By default, concurrent usage of connection groups is not limited.

SQLSERVER_DEFAULT_MAX_CONNECTIONS_PER_USER

The maximum number of concurrent connections to allow each user to hold to any particular connection, where a value of "0" indicates unlimited. By default, user-specific concurrent usage of connections is not limited.

SQLSERVER_DEFAULT_MAX_GROUP_CONNECTIONS_PER_USER

The maximum number of concurrent connections to allow each user to hold to any particular connection group, where a value of "0" indicates unlimited. By default, user-specific concurrent usage of connection groups is limited to one.

SQLSERVER_ABSOLUTE_MAX_CONNECTIONS

The maximum number of concurrent connections to allow to overall, regardless of user, connection or connection group, where a value of "0" indicates unlimited. By default, overall concurrent usage is not limited.

SQLSERVER_USER_REQUIRED

If set to "true", require that each user have a corresponding account defined within the database, even if the user authenticated through some other mechanism (such as LDAP). By default, users that successfully authenticate through another mechanism are not required to also have an account within the database.

SQLSERVER_TRACK_EXTERNAL_CONNECTION_HISTORY

Whether connections that do not exist within the database should have connection history tracked in the database. If set to "true", connection history records will be created for any connection established. If set to "false", connection history records will be created only for connections defined in the database. By default, external connections will be tracked.

SQLSERVER_ENFORCE_ACCESS_WINDOWS_FOR_ACTIVE_SESSIONS

Whether access time restrictions imposed by the administrator on user accounts should be enforced while a user is logged in. If set to "true", users will be automatically logged out within roughly one minute of reaching their access time limits. If set to "false", access time restrictions will only be enforced at the moment a user attempts to log in. By default, access time restrictions are enforced while users are logged in.

SQLSERVER_AUTO_CREATE_ACCOUNTS

Whether user account entries should automatically be created within the database for users that successfully authenticate through other means, such as an SSO provider or LDAP. This may be necessary if using an extension that requires account-specific storage, like TOTP or per-account approvals. If set to "true", user account entries will automatically be created. By default, administrators must manually create such entries if needed.

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:

Variable name
Description

SSL_CLIENT_AUTH_URI

A wildcard URI that points to this Guacamole instance and requests SSL/TLS client authentication.

SSL_PRIMARY_URI

A non-wildcard URI that points to this Guacamole instance and does not request SSL/TLS client authentication.

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

Variable name
Description

SSL_CLIENT_CERTIFICATE_HEADER

The name of the header to use to retrieve the URL-encoded client certificate from an HTTP request received from an SSL termination service providing SSL/TLS client authentication. By default, X-Client-Certificate is used, matching the behavior of the keeper/guacamole-ssl-nginx image.

SSL_CLIENT_VERIFIED_HEADER

The name of the header to use to retrieve the verification status of the certificate an HTTP request received from an SSL termination service providing SSL/TLS client authentication. This value of this header must be "SUCCESS" (all uppercase) if the certificate was successfully verified. By default, X-Client-Verified is used, matching the behavior of the keeper/guacamole-ssl-nginx image.

SSL_MAX_DOMAIN_VALIDITY

The amount of time that the temporary, unique subdomain generated for SSL/TLS authentication may remain valid, in minutes. By default, temporary subdomains are valid for 5 minutes.

SSL_MAX_TOKEN_VALIDITY

The amount of time that a temporary authentication token for SSL/TLS authentication may remain valid, in minutes. By default, temporary authentication tokens are valid for 5 minutes.

SSL_SUBJECT_BASE_DN

The base DN containing all valid subject DNs. If specified, only certificates asserting subject DNs beneath this base DN will be accepted. By default, all DNs are accepted as long as the certificate is valid.

SSL_SUBJECT_USERNAME_ATTRIBUTE

The LDAP attribute or attributes that may be used to represent a username within the subject DN of a user's X.509 certificate. If the least-significant attribute of the subject DN is not one of these attributes, the certificate will be rejected. By default, any attribute is accepted and used as the username.

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.

Variable name
Description

TOTP_ISSUER

The human-readable name of the entity issuing user accounts. By default, this is "Apache Guacamole".

TOTP_DIGITS

The number of digits which should be included in each generated code. TOTP allows for 6-, 7-, or 8-digit codes. Longer or shorter codes than this are not possible as they violate the TOTP standard. By default, 6-digit codes will be used.

TOTP_PERIOD

The duration that each generated code should remain valid, in seconds. The code generation period is given in positive integer seconds and may be any value, however the value should be long enough to allow the user a reasonable amount of time to enter their code. Their authentication device will generate a new code after this period elapses. By default, generated codes are valid for 30 seconds.

TOTP_MODE

The hash algorithm that should be used to generate codes. Valid TOTP modes (hashes) are "sha1", "sha256", and "sha512". By default, "sha1" is used.

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.

Variable name
Description

UDS_BASE_URL

The base URL of the UDS Enterprise deployment that may leverage Keeper Connection Manager to provide remote access. Keeper Connection Manager will use this URL to contact UDS to authenticate and authorize connection requests.

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

keeper/guacd

Docker deployment of guacd with Keeper Connection Manager

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.

Database images

Docker deployment of Pre-Initialized Database Images with Keeper Connection Manager

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

Image name
Base image
Description

keeper/guacamole-db-mysql

mysql:5

An instance of MySQL, automatically initialized with the Apache Guacamole database schema.

keeper/guacamole-db-postgres

postgres:11

An instance of PostgreSQL, automatically initialized with 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 keeper/guacamole and keeper/guacd 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 keeper/guacamole and keeper/guacd images using docker-compose, an entire deployment of Apache Guacamole can be created and managed using a single docker-compose.yml.

keeper/guacamole-db-mysql

Docker deployment of MySQL with Keeper Connection Manager

Image: keeper/guacamole-db-mysql

keeper/guacamole-db-mysql is a Dockerized deployment of MySQL, built off Docker's official MySQL image 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 EULA. It is normally used to provide a MySQL database for a container using the keeper/guacamole image.

Environment variables

In addition to the environment variables documented below, all environment variables supported by the official Docker MySQL image 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 Keeper Connection Manager EULA. 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.

The GUACAMOLE_USERNAME and GUACAMOLE_PASSWORD are not strictly required, as the user created with MYSQL_USER and MYSQL_PASSWORD may be used instead, however they are strongly recommended to ensure the Principle of Least Privilege is followed.

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:

docker run --name some-guacamole-db \
    -e ACCEPT_EULA=Y \
    -e MYSQL_RANDOM_ROOT_PASSWORD=yes \
    -e GUACAMOLE_ADMIN_PASSWORD=some_password \
    -e GUACAMOLE_DATABASE=guacamole_db \
    -e GUACAMOLE_USERNAME_FILE=/run/secrets/mysql-username \
    -e GUACAMOLE_PASSWORD_FILE=/run/secrets/mysql-password \
    -d keeper/guacamole-db-mysql

keeper/guacamole-db-postgres

Docker deployment of Postgres with Keeper Connection Manager

Image: keeper/guacamole-db-postgres

keeper/guacamole-db-postgres is a Dockerized deployment of PostgreSQL, built off Docker's official PostgreSQL image 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 EULA. It is normally used to provide a PostgreSQL database for a container using the keeper/guacamole image.

Environment variables

In addition to the environment variables documented below, all environment variables supported by the official Docker PostgreSQL image 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 Keeper Connection Manager EULA. 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 the official PostgreSQL image in that the created user has limited privileges, being granted only what privileges are absolutely required for Guacamole to run.

The GUACAMOLE_USERNAME and GUACAMOLE_PASSWORD are not strictly required, as the user created with POSTGRES_USER and POSTGRES_PASSWORD may be used instead, however they are strongly recommended to ensure the Principle of Least Privilege is followed.

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:

docker run --name some-guacamole-db \
    -e ACCEPT_EULA=Y \
    -e GUACAMOLE_DATABASE=guacamole_db \
    -e POSTGRES_PASSWORD=some_password \
    -e GUACAMOLE_ADMIN_PASSWORD=some_password \
    -e GUACAMOLE_USERNAME_FILE=/run/secrets/postgres-username \
    -e GUACAMOLE_PASSWORD_FILE=/run/secrets/postgres-password \
    -d keeper/guacamole-db-postgres

SSL Termination

Docker deployment of NGINX with Keeper Connection Manager for SSL Termination

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

Image name
Base image
Description

keeper/guacamole-ssl-nginx

nginx:1.19

An instance of NGINX which automatically provides SSL termination for Keeper Connection Manager.

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.

keeper/guacamole-ssl-nginx

Docker deployment of NGINX for SSL termination with Keeper Connection Manager

Image: keeper/guacamole-ssl-nginx

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

  • Automatic retrieval of a certificate from Let's Encrypt.

  • Automatic generation of a self-signed certificate.

  • Usage of an existing certificate 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 EULA. It is normally used to provide SSL termination for a container using the keeper/guacamole image.

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:

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

  • GUACAMOLE_HOSTNAME - The hostname/address of the Guacamole instance.

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

If you are just testing usage of Let's Encrypt, you should use the Let's Encrypt staging/testing environment instead of the production environment:

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

    ssl:
        image: keeper/guacamole-ssl-nginx:2
        restart: unless-stopped
        ports:
            - "80:80"
            - "443:443"
        environment:
            ACCEPT_EULA: "Y"
            GUACAMOLE_HOSTNAME: guacamole
            SSL_HOSTNAME: keeper.mycompany.com
            LETSENCRYPT_ACCEPT_TOS: "Y"
            LETSENCRYPT_EMAIL: "you@company.com"

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.

    ssl:
        image: keeper/guacamole-ssl-nginx:2
        restart: unless-stopped
        ports:
            - "80:80"
            - "443:443"
        environment:
            ACCEPT_EULA: "Y"
            GUACAMOLE_HOSTNAME: guacamole
            SSL_HOSTNAME: keeper.mycompany.com
            CERTIFICATE_FILE: "/path/in/container/mycert.pem"
            PRIVATE_KEY_FILE: "/path/in/container/mykey.pem"
        volumes:
            - "/local/path/to/keys:/path/in/container/"

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

In addition to the environment variables documented below, all environment variables supported by the official Docker Nginx image are accepted, as the official NGINX 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 Keeper Connection Manager EULA. This Docker image may not be used except under the terms of the 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

If intending to use Let's Encrypt, the LETSENCRYPT_ACCEPT_TOS environment variable must be set to "Y" to indicate your acceptance of the Let's Encrypt Terms of Service. Let's Encrypt cannot be used unless you agree to the relevant Terms of Service.

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

If set to "Y", requests that the Let's Encrypt staging environment be used to retrieve an SSL certificate, rather than the production environment. This option should be used if you are just testing the Let's Encrypt functionality.

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.

It is not typically necessary set this environment variable except in cases where custom KCM/Guacamole extensions require a more lenient policy.

Be careful if overriding the default policy is necessary. An overly-strict CSP can easily prevent KCM from performing core required tasks, such as decoding graphical data or making requests to its own REST API.

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.

As HSTS is not always appropriate for all deployments of KCM, particularly if KCM will share a domain with other web applications that do not all support HTTPS, installations of KCM do not enable HSTS by default.

The STRICT_TRANSPORT_SECURITY environment variable must be set to a value to enable HSTS. A recommended default is available for convenience.

STRICT_TRANSPORT_SECURITY

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

If set to "Y", a reasonable default Strict-Transport-Security value will be set: 'max-age=31536000; includeSubDomains; preload;' always, as recommended by https://https.cio.gov/hsts/.

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:

docker run --name some-guacamole-ssl \
    -e ACCEPT_EULA=Y \
    -e LETSENCRYPT_ACCEPT_TOS=Y \
    -e LETSENCRYPT_EMAIL_FILE=/run/secrets/letsencrypt-email \
    -d keeper/guacamole-ssl-nginx

Advanced Configuration

The environment variables in this section are only needed in unusual cases, such as when serving KCM from a non-standard port or when older ciphers or versions of SSL must be enabled. Do not set these variables unless you are certain that doing so is necessary.

SSL_CIPHERS

Configures the allowable SSL ciphers for the Nginx instance. For information on the allowable values for this parameter, see the Nginx documentation. If not otherwise specified, the value will default to "HIGH:!aNULL:!MD5".

SSL_PROTOCOLS

Configures the allowable SSL protocols for the Nginx instance. For information on the allowable values for this parameter, see the Nginx documentation. If not otherwise specified, TLS 1.2 and 1.3 will be enabled.

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 a non-standard port is used for SSL, this port must additionally be mapped to the standard port, e.g. -p 8443:443. Setting this variable has no impact on the ports used by Nginx internally within the image.

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.

Using a Custom SSL Cert

How to deploy a custom SSL Certificate to Keeper Connection Manager

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

openssl genrsa -out demo3.kcmdemo.com.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.

openssl req -new -key demo3.kcmdemo.com.key -out demo3.kcmdemo.com.csr

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

Ensure that the SSL certificate created for your KCM instance is only used for this purpose. Do not use a wildcard certificate that is shared with other services.

If you don't have a provider already, a good site is: https://www.ssls.com/

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:

-----BEGIN CERTIFICATE-----
MIIGQjCCBSqgAwIBAgIQeLDY2eR6ZdAagFwb7A/YxzANBgkqhkiG9w0BAQsFADCB
jzELMAkGA1UEBhMCR0IxGzAZBgNVBAgTEkdyZWF0ZXIgTWFuY2hlc3RlcjEQMA4G
A1UEBxMHU2FsZm9yZDEYMBYGA1UEChMPU2VjdGlnbyBMaW1pdGVkMTcwNQYDVQQD
.....
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIGEzCCA/ugAwIBAgIQfVtRJrR2uhHbdBYLvFMNpzANBgkqhkiG9w0BAQwFADCB
iDELMAkGA1UEBhMCVVMxEzARBgNVBAgTCk5ldyBKZXJzZXkxFDASBgNVBAcTC0pl
yOGBQMkKW+ESPMFgKuOXwIlCypTPRpgSabuY0MLTDXJLR27lk8QyKGOHQ+SwMj4K
00u/I5sUKUErmgQfky3xxzlIPK1aEn8=
...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIFgTCCBGmgAwIBAgIQOXJEOvkit1HX02wQ3TE1lTANBgkqhkiG9w0BAQwFADB7
MQswCQYDVQQGEwJHQjEbMBkGA1UECAwSR3JlYXRlciBNYW5jaGVzdGVyMRAwDgYD
...
-----END CERTIFICATE-----

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:

-----BEGIN RSA PRIVATE KEY-----
MIIEpAIBBAKCAQDAvzLIMM7MnVa7z/CTLm+dTnxcd9Rn0QOVdIRIHbQnoBQ9irv6
lgNp8pnpIKp/WPcvoNKEZND08CX8Ylxbw51ccoERNBPtvyXbJtfIFu81nplqr+Lt
....
eABEVrVcYwO10apQQ0lkXWyYhTS0WuB1wFZlIiFq7RJg2X7s9tmVMw==
-----END RSA PRIVATE KEY-----

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

sudo mv demo3.kcmdemo.com_bundle.crt /etc/kcm-setup/
sudo mv demo3.kcmdemo.com.key /etc/kcm-setup/

sudo chmod 600 /etc/kcm-setup/demo3.kcmdemo.com_bundle.crt
sudo chmod 600 /etc/kcm-setup/demo3.kcmdemo.com.key

chown root:root /etc/kcm-setup/demo3.kcmdemo.com_bundle.crt
chown root:root /etc/kcm-setup/demo3.kcmdemo.com.key

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

sudo vi /etc/kcm-setup/docker-compose.yml
docker-compose.yml
    ssl:
        image: keeper/guacamole-ssl-nginx:2
        restart: unless-stopped
        ports:
            - "80:80"
            - "443:443"
        environment:
            CERTIFICATE_FILE: "/etc/ssl/certs/certificate.pem"
            PRIVATE_KEY_FILE: "/etc/ssl/certs/private.pem"
            ACCEPT_EULA: "Y"
            GUACAMOLE_HOSTNAME: "guacamole"
            SSL_HOSTNAME: "demo3.kcmdemo.com"
        volumes:
            - "/etc/kcm-setup:/etc/ssl/certs/:ro"

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

To restart the service with the new certificate:

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

Annual Renewal

On an annual basis, you will need to renew your cert. Most certificate providers will generate a new cert for you. After certificate renewal, you need to replace the certificate file and restart the service.

Upgrading

Upgrading Keeper Connection Manager with the Docker Manual Install method

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

sudo docker-compose pull
sudo docker-compose up -d

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

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

Select "Y" when prompted.

Podman Install

This walkthrough follows Keeper’s official “Docker Compose Install” instructions but modified for Podman.

Before you start

What you need
Minimum
Notes

Linux server

RHEL 9 / Alma 9 / Rocky 9 / Fedora 39 OR Ubuntu 24.04 / Debian 12

Any modern distro that ships Podman 5+ works.

Packages

podman & podman‑compose

Installed in Step 3.

Network

One free TCP port (8080 is used below)

If you want HTTPS later, you’ll also open 80 & 443.

Step 1. Create a working folder and save the Compose file

  • Sign in to your server and run:

sudo mkdir -p /opt/kcm && cd /opt/kcm
  • In a browser, visit the Docker Compose Install page

  • Scroll to Step 2 — Create Docker Compose File.

  • Copy the YAML block and paste the text into the file /opt/kcm/docker‑compose.yml with a text editor.


Step 2. Download the hardened seccomp profile

Keeper’s docs place this file automatically if you use their install script. With Compose we pull it ourselves:

sudo mkdir -p /etc/kcm-setup
sudo podman run --rm --entrypoint=/bin/cat \
  docker.io/keeper/guacd:2 \
  /opt/keeper/share/guacd/docker-seccomp.json \
  | sudo tee /etc/kcm-setup/guacd-docker-seccomp.json

The command starts a temporary container, reads the JSON file inside, and saves it on the host.


Step 3. Install Podman & helper tools

RHEL / Alma / Rocky / Fedora

sudo dnf install -y podman podman-compose firewalld haveged
sudo systemctl enable --now haveged   # adds extra entropy for SSL

Ubuntu / Debian

sudo apt update && sudo apt install -y podman podman-compose firewalld haveged
sudo systemctl enable --now haveged

Check: podman --version should show 5.x or newer.


Step 4. Modify the Compose file for Podman

Open /opt/kcm/docker‑compose.yml again and make these small edits:

  1. Security profile (under the guacd service):

    security_opt:
      - seccomp:/etc/kcm-setup/guacd-docker-seccomp.json
  2. SELinux hosts only (RHEL/Fedora): add :Z after each bind‑mount, for example: - "common-storage:/var/lib/guacamole:rw,Z"

  3. Optional: Replace any :latest tags with the current major tag :2 (e.g. keeper/guacamole:2).

That’s it—no other changes are required.


Step 5. Start Keeper Connection Manager

cd /opt/kcm
sudo podman-compose up -d  # add --time 30 if the DB needs extra init time

Check that three containers are Up:

podman ps --format "{{.Names}}  {{.Status}}  {{.Ports}}"

Open your browser to http://<server‑IP>:8080. You should see the Keeper login page.


Step 6. Open the firewall (RHEL/Fedora)

sudo systemctl enable --now firewalld
sudo firewall-cmd --permanent --add-port=8080/tcp
sudo firewall-cmd --reload

(Ubuntu’s UFW or Debian’s nftables users perform the equivalent rule.)


Step 7. Set up automatic startup

sudo podman generate systemd --name kcm_guacamole_1 --files --new
sudo podman generate systemd --name kcm_guacd_1      --files --new
sudo podman generate systemd --name kcm_db_1         --files --new
sudo mv *.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now container-kcm_guacamole_1.service \
                       container-kcm_guacd_1.service \
                       container-kcm_db_1.service

Now KCM will survive server reboots without any extra commands.


Step 8. First‑run checks

What to test
Command
Expected result

Local health

curl -f http://localhost:8080/

Returns HTML with <title>Guacamole</title>

Container status

podman ps

All three containers show Up

Remote access

Browser → http://<server-IP>:8080

Shows login page


Troubleshooting

Problem you see

Likely reason

Quick remedy

Browser says “Connection timed out”

Server firewall still blocking 8080 or you ran Podman rootless (port bound to 127.0.0.1)

Rootful: run the firewall‑cmd lines in Step 6. Rootless: run KCM on 8080 and put nginx/HAProxy in front on port 80/443.

404 Not Found at /guacamole

The UI sits at / by default.

Go to http://host:8080/ or set GUACAMOLE_CONTEXT_PATH=guacamole in the guacamole service.

Permission denied errors on Fedora/RHEL

Missing SELinux label

Add :Z to each volume line in docker-compose.yml, then podman-compose down && podman-compose up -d.

Service dies after a reboot

Podman‑Compose ignores restart:

Follow Step 7 to generate systemd units.

DB keeps restarting

Passwords don’t match or volume wiped

Check the POSTGRES_PASSWORD and other DB env vars are the same in both db and guacamole services.

When in doubt, run podman logs <container-name> and read the last few lines—it usually tells you what went wrong.


You’re done! Keeper Connection Manager is now running on Podman without Docker. Enjoy your lighter, daemon‑free setup.


Backup & Recovery

Backup and recovery options

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:

  1. Server backup

  2. Database snapshots

  3. Docker compose 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.