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 Advanced Linux Install with package installations and custom configurations, we support Red Hat Enterprise Linux 7/8 and CentOS 7.

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.

Advanced Linux Install

--> Installation Instructions for Advanced Linux Install

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

Obtaining a License Key

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

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

Installation

To install your license key, you must provide the license as the sole contents of /etc/guacamole/kcm.license, which must be readable by the guacamole group.

cat "license_key_supplied_by_keeper" > /etc/guacamole/kcm.license
chmod 640 /etc/guacamole/kcm.license
chown root:guacamole /etc/guacamole/kcm.license

After adding the license key, restarting the service may be necessary.

sudo systemctl restart guacamole guacd

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:

Table with host recommendations:

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

Disk space requirements

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

Network throughput for concurrent connections

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

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

Preparing for Installation

Since you'll be accessing Keeper Connection Manager using a browser, we need to establish where to find it.

You'll need the following:

1. A designated machine (usually a Linux VM) 2. 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 (or generate one during installation) 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 a DNS A Record (or AAAA record) to point your domain to your KCM server's IP address

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

Platform-specific Setup

Virtual Machines

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

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

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

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

sudo apt-get install haveged

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

RHEL / Rocky Linux 8 (and derivatives)

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

sudo yum remove containerd
sudo yum remove runc

Overview

This method of installation requires one of the following operating systems:

• Linux CentOS 7 or 8

• RHEL 7 or 8

The Keeper Connection Manager packages have dependencies on various Apache Tomcat and Apache Guacamole packages. Once Guacamole and Tomcat have been set up, a production deployment will also require:

• An instance of a supported database (MySQL / MariaDB, PostgreSQL, or SQL Server).

• SSL termination using a reverse proxy (Apache HTTPD or Nginx).

If you do not already have a database server and reverse proxy ready, and are not experienced with setting up those services, instructions are also provided for installing a local instance of MariaDB, installing a local instance of PostgreSQL, and for installing Nginx to provide SSL termination.

Keeper Connection Manager is made up of multiple packaged components. The packages provide binary versions of the Apache Guacamole stack that can be updated automatically. The other components will come from your OS repository (CentOS / RHEL), from other services deployed on your network, or from third-party service providers, depending on your preferences.

A typical and minimal production deployment of Keeper Connection Manager will involve the following:

• The Guacamole Web Application, served by Apache Tomcat.

• SSL termination that sits in front of Apache Tomcat.

• The "guacd" service, used internally by the Guacamole web application.

• A database, used by the Guacamole web application for authentication and storage.

Advanced capabilities of the platform can be installed as packages, providing features such as:

• SAML 2.0 / SSO Authentication

• AD/LDAP Authentication

• Keeper Secrets Manager integration

• TOTP for Two-Factor Authentication

System Diagram

Installation of Keeper Connection Manager requires the following steps:

1. Installing the Guacamole web application and its backend service, "guacd".

2. Installing a database like MariaDB or PostgreSQL, if no such database is already deployed.

3. Configuring Guacamole to use your database.

4. Installing and configuring a reverse proxy to provide SSL termination, if no such proxy is already deployed.

This guide will walk through the installation of the core components of Keeper Connection Manager- the components necessary to see the web application in a browser and test some remote desktop connections.

Once the basic Keeper Connection Manager setup has been installed, you will still need to configure a database and deploy SSL termination before moving to production.

Additional guides are available which cover configuring Keeper Connection Manager to use your database of choice and configuring your reverse proxy to provide SSL termination. If you do not yet have a database or do not yet have a reverse proxy, additional guides covering installation of those required services are available.

Configure the Linux Machine

Before getting started, make sure that your Linux environment is fully up-to-date.

sudo yum update

To ensure that the linux machine is capable of generating enough entropy for random number generation, we recommend installing the haveged package.

These packages can be installed using the commands below:

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

Set up the YUM repository

So that YUM can find the various RPM packages which make up Keeper Connection Manager, a repository file needs to be created.

To use the 'yum' utility to automatically create this .repo file, use the following command:

sudo yum install "https://keepersecurity.com/kcm/2/`rpm -E%{suffix:%dist}`/kcm-release.rpm"

Install and deploy Apache Guacamole

Keeper Connection Manager provides a "@kcm" package group for convenience which installs all of the packages typically required for an Apache Guacamole deployment, and includes support for VNC, RDP, SSH, Telnet, MySQL and Kubernetes. This package group automatically deploys Apache Guacamole beneath a version of Apache Tomcat bundled and packaged by Keeper Connection Manager.

Install the @kcm package group

Installing "@kcm" will install the core packages required for Apache Guacamole and a bundled version of Apache Tomcat. The Guacamole web application will be automatically deployed beneath the bundled version of Tomcat:

$ sudo yum install @kcm

Start Guacamole and guacd

The full Apache Guacamole stack is made up of two services: the Guacamole web application (served by Tomcat) and its remote desktop proxy service, "guacd". Thus, both the "guacamole" and "guacd" services must be started for Guacamole to function, and should be configured to start automatically on boot:

$ sudo systemctl start guacd guacamole
$ sudo systemctl enable guacd guacamole

Congratulations! At this point, Keeper Connection Manager should be working, and a login screen should be visible if you visit http://HOSTNAME:8080/ with a web browser, where “HOSTNAME” is the hostname or IP address of your server.

Note that this environment will be missing all of the connection management screens. These features will become activated as soon as you configure a database in the next step.

Quick Connection Test

With the bare bones deployment running, you can move forward with testing your deployment using /etc/guacamole/user-mapping.xml (the built-in authentication method intended for testing). This allows you to manually test a remote connection and set up a sandbox user account.

Database Setup

To activate the full functionality of the platform, a database must be configured.

MySQL / MariaDB, PostgreSQL, and SQL Server are supported. If you do not already have a database deployed, or are unfamiliar with deploying databases, instructions are provided for installing a local instance of MariaDB and for installing a local instance of PostgreSQL.

SSL Termination

In a production environment, proper SSL termination is required. Apache HTTPD and Nginx are supported for this purpose. If you do not already have a reverse proxy in place, or are unfamiliar with installing and configuring a reverse proxy, instructions are provided for installing Nginx to provide SSL termination.

Protecting your Keeper Connection Manager Instance

During the initial testing and deployment phase, we recommend locking down access to the Keeper Connection Manager service with firewall rules. Port 80 or 443 should only be opened and restricted to specific users.

When activating the Lets Encrypt SSL certificates, you may need to open up the gateway for the generation and verification of the domain.

In a production environment, we recommend using SAML/SSO authentication with your preferred identity provider. Step by step guides are provided in this documentation.

Keeper produces new minor releases of Keeper Connection Manager (1.1, 1.2, 1.3, etc.) roughly every 3 months following the first general availability release. Minor releases are updates to an existing major release which add new features and fix bugs, and will always maintain strict API compatibility. The details of upcoming and past releases can be found in the changelog.

Checking for updates

To check whether updates are available for Keeper Connection Manager packages without actually applying those updates, you can use the yum list updates command. Providing the "kcm-*" pattern to yum list updates restricts the packages checked to only those packages provided by Keeper Connection Manager:

sudo yum list updates "kcm-*"

If the above command lists one or more packages, then there are newer versions of Keeper Connection Manager packages available, and you should proceed with upgrading when a maintenance window permits.

Performing the upgrade

Stop Guacamole and guacd services

Before upgrading the Keeper Connection Manager packages, both Guacamole and guacd should be taken offline:

sudo systemctl stop guacamole guacd

$ sudo systemctl stop tomcat guacd

This is because:

• If both the Guacamole web application and one of its extensions are being updated, the package manager may update the web application first. The running Tomcat service may then redeploy and restart the web application before the extension is updated, resulting in inconsistency.

• If protocol support for guacd is being updated, older versions of that support may be cached by the system linker until the guacd service has been restarted.

• If the guacd service is being updated, those updates cannot take effect until the guacd service is restarted. The running process will continue to use the older, cached binary.

The system should remain stable if the upgrade is performed without stopping Tomcat and guacd, however it is best practice to do so. An upgrade to the web application will always result in the web application being restarted, and any updates being applied will likely not take effect until after services are restarted. With updates to the web application inherently causing a service restart, and updates in general requiring a service restart in order to take effect, it's best to plan this restart as a controlled part of the process.

Apply updates using yum

Once Tomcat and guacd are stopped, the Keeper Connection Manager packages can be upgraded using the yum utility, just like the other packages in the system. The upgrade can be restricted to only Keeper Connection Manager packages by specifying the "kcm-*" pattern:

sudo yum upgrade "kcm-*"

Start the Guacamole and guacd services

After yum upgrade completes, the system has been updated and it is safe to start Guacamole and guacd back up:

sudo systemctl start guacamole guacd

Process overview

Updating an installation of Glyptodon from the 1.x major release to the 2.x major release or to Keeper Connection Manager (releases of version 2.8 and greater) is slightly more complex than simply updating between minor releases and will involve the following steps:

1. Stop Tomcat and guacd services

2. Update your .repo file to point to the 2.x release (rather than 1.x)

3. Update your installed packages using yum upgrade

4. Force Tomcat to redeploy Guacamole (it may not automatically recognize the new guacamole.war as new)

5. If you are using a database: Update your database schema

6. If using SSL termination: Update Tomcat's server.xml to trust "X-Forwarded-For" from your proxy

7. Start Tomcat and guacd services

Stop Tomcat and guacd

Before upgrading the Glyptodon Enterprise packages, both Tomcat and guacd must be taken offline. By definition, the components of different major releases are incompatible with each other, and these components will be replaced during the upgrade process. It is not safe to perform a major release upgrade while components of Guacamole are running.

$ sudo systemctl stop tomcat guacd

Update the .repo file within /etc/yum.repos.d

Each major release of Keeper Connection Manager is located within its own, isolated repository. To upgrade to a major release after 1.X, remove the current .repo file and use the following command to automatically create an updated version:

sudo yum install "https://keepersecurity.com/kcm/2/`rpm -E%{suffix:%dist}`/kcm-release.rpm"

Alternatively the .repo file can be updated manually. To do this, use a text editor to replace the contents of your old .repo file within /etc/yum.repos.d:

$ sudo vi /etc/yum.repos.d/kcm.repo

The only difference between the 1.x and 2.x files is in the baseurl, with the relevant part of the base URL changing from "release/1/" to "kcm/2/". Once updated, your .repo file should ultimately look like:

[kcm]
name=Keeper Connection Manager 2.x
baseurl=https://keepersecurity.com/kcm/2/el/$releasever/$basearch/
enabled=1
gpgcheck=1
repo_gpgcheck=1
gpgkey=https://keepersecurity.com/kcm/RPM-GPG-KEY-kcm-release

Apply updates using yum

Once the .repo file has been updated to point to the Glyptodon Enterprise 2.x repository, the software components can be upgraded to their 2.x versions by simply running yum upgrade:

$ sudo yum upgrade "kcm-*"

As mentioned above, be sure that Tomcat and guacd are both stopped prior to running yum upgrade. If you encounter errors during the upgrade process, double-check that both Tomcat and guacd have indeed been stopped, and re-run the yum upgrade command.

Force Tomcat to redeploy Guacamole

Tomcat may not automatically recognize that the new guacamole.war is indeed new, and may continue to use its cached copy of the older version. To ensure that the new version of Guacamole is deployed, you should remove the directory created by Tomcat when it originally deployed guacamole.war, thus forcing Tomcat to redeploy the .war during startup:

$ sudo rm -r /var/lib/tomcat/webapps/guacamole/

Apply database schema changes

If using MySQL, MariaDB, or PostgreSQL for connection storage and/or authentication, the database schema of your existing database will be that of Apache Guacamole 0.9.12-incubating. It will need to be brought up-to-date with the base version of Apache Guacamole provided by Glyptodon Enterprise 2.x by running the appropriate SQL script against the database in question:

If using PostgreSQL, you will additionally need to re-run the permission grants to ensure the Guacamole database user has sufficient permissions to execute queries against new tables and sequences, as PostgreSQL does not automatically extend the permissions already granted when new tables/sequences are created.

$ mysql -u root -p guacamole_db < /opt/keeper/share/guacamole-auth-jdbc-mysql/schema/upgrade/upgrade-GLEN-1.x.sql

$ psql -d guacamole_db -f /opt/keeper/share/guacamole-auth-jdbc-postgresql/schema/upgrade/upgrade-GLEN-1.x.sql

GRANT SELECT,INSERT,UPDATE,DELETE ON ALL TABLES IN SCHEMA public TO guacamole_user;
GRANT SELECT,USAGE ON ALL SEQUENCES IN SCHEMA public TO guacamole_user;

Update server.xml to trust "X-Forwarded-For" from known proxies

From Apache Guacamole 1.0.0 onward, logging of client IP addresses now relies on Tomcat configuration to determine whether the "X-Forwarded-For" header can be trusted. This includes Glyptodon Enterprise 2.x, which is based off Apache Guacamole 1.1.0. If you are using a reverse proxy like Nginx or Apache for SSL termination, you will need to add a "RemoteIpValve" entry to /etc/tomcat/server.xml.

$ sudo cp /opt/keeper/share/guacamole/server.xml /etc/tomcat/

<Valve className="org.apache.catalina.valves.RemoteIpValve"/>

        ...

        <Valve className="org.apache.catalina.valves.RemoteIpValve"/>

      </Host>
    </Engine>
  </Service>
</Server>

<Valve className="org.apache.catalina.valves.RemoteIpValve"
       internalProxies="127\.\d{1,3}\.\d{1,3}\.\d{1,3}|0:0:0:0:0:0:0:1|::1"/>

Start Tomcat and guacd

After yum upgrade completes, and any needed changes to the database and Tomcat's server.xml have been made, the system has been updated and it is safe to start Tomcat and guacd back up:

$ sudo systemctl start tomcat guacd

Your Keeper Connection Manager installation should now be working and up-to-date with the 2.x release.

Apache Guacamole comes with a built-in, simplified, XML-driven authentication mechanism for the sake of testing. Accounts and connections can be defined within /etc/guacamole/user-mapping.xml without having to install support for a database. The default file included with Keeper Connection Manager looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<!--

  user-mapping.xml:

      Configuration file for Apache Guacamole's built-in, XML-based
      authentication scheme.

  WARNING: user-mapping.xml is meant to provide an easy means of verifying an
  Apache Guacamole install. Production deployments of Guacamole should switch
  to one of the database authentication methods or LDAP when possible.

  Keeper Connection Manager provides packages for these authentication methods,
  which are intended for production use:

      - kcm-guacamole-auth-jdbc-mysql
      - kcm-guacamole-auth-jdbc-postgresql
      - kcm-guacamole-auth-ldap

  Two-factor authentication using Duo is also supported, and can be layered on
  top of any of the above methods:

      - kcm-guacamole-auth-duo

-->
<user-mapping>
    ...
</user-mapping>

As noted at the top of the file, you can leverage this to verify that your Guacamole installation is functional, however the user-mapping.xml file should not be used for production deployments. Production deployments of Guacamole should instead use one of the authentication extensions, such as the database support or LDAP. Unlike the XML, all of these extensions are intended for production use.

Format of user-mapping.xml

The user-mapping.xml file consists of a main, root-level <user-mapping> element:

<?xml version="1.0" encoding="UTF-8"?>
<user-mapping>
    ...
</user-mapping>

Defining user accounts

This <user-mapping> element may contain any number of <authorize> blocks, each describing a user and their corresponding password:

<?xml version="1.0" encoding="UTF-8"?>
<user-mapping>

    <!-- First user -->
    <authorize username="user1" password="pass1">
    </authorize>

    <!-- Second user -->
    <authorize username="user2" password="pass2">
    </authorize>

</user-mapping>

Granting access to connections

The <authorize> blocks in turn may contain any number of <connection> blocks, each describing a connection that should be accessible to the user:

<?xml version="1.0" encoding="UTF-8"?>
<user-mapping>

    <!-- First user -->
    <authorize username="user1" password="pass1">

        <connection name="Example VNC connection">
            <protocol>vnc</protocol>
            <param name="hostname">localhost</param>
            <param name="port">5901</param>
            <param name="password">VNCPASS</param>
        </connection>

    </authorize>

    <!-- Second user -->
    <authorize username="user2" password="pass2">

        <connection name="Example VNC connection">
            <protocol>vnc</protocol>
            <param name="hostname">localhost</param>
            <param name="port">5901</param>
            <param name="password">VNCPASS</param>
        </connection>

        <connection name="Example RDP connection">
            <protocol>rdp</protocol>
            <param name="hostname">otherhost</param>
            <param name="username">RDPUSER</param>
            <param name="password">RDPPASS</param>
        </connection>

    </authorize>

</user-mapping>

This file is automatically reread when modified, so you should be able to immediately log in when you define a new user in this way, however changes to an active user’s connections will not be available to that user until they logout.

Defining connections (protocols and parameters)

Each <connection> contains exactly one <protocol> element (specifying the unique name of the protocol to use to connect to the remote desktop) and any number of <param> elements (specifying the name of a parameter and the value to use for that connection). These protocol and parameter names are standardized and case-sensitive. The names of each supported protocol are defined by Guacamole, and the names of available parameters are defined by the part of Guacamole implementing that support:

The names of many parameters are predictable and common across the supported protocols, like "hostname" and "port", but please consult the documentation for the relevant protocol for a full list of available parameters and their allowed values, as well as which parameters are absolutely required.

Moving to production

When finished testing, you should prepare to move forward with adding the remaining layers normally required by a production deployment:

1. A supported database: MySQL / MariaDB, PostgreSQL, and SQL Server are supported. If you do not already have a database deployed, or are unfamiliar with deploying databases, instructions are provided for installing a local instance of MariaDB.

2. SSL termination: Apache HTTPD and Nginx are supported for this purpose. If you do not already have a reverse proxy in place, or are unfamiliar with installing and configuring a reverse proxy, instructions are provided for installing Nginx to provide SSL termination.

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

Server Backup Instructions

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

• In most installations, a database running locally 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

• Please use the database platform's backup features, for example mysqladmin on MySQL backed installs.