Custom Docker Images

Overview

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

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

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

2. Install any required packages for your use case.

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

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

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

6. Start one of the provided Docker entrypoints.

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

Configuring Guacamole using guacamole.properties.docker

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

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

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

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

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

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

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

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

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

• kcm-guacamole

• kcm-guacd

• tomcat

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

• kcm-guacamole-auth-duo

• kcm-guacamole-auth-json

• kcm-guacamole-auth-ldap

• kcm-guacamole-auth-mysql

• kcm-guacamole-auth-postgresql

• kcm-guacamole-auth-sqlserver

• kcm-guacamole-auth-totp

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

• kcm-libguac-client-rdp

• kcm-libguac-client-ssh

• kcm-libguac-client-telnet

• kcm-libguac-client-vnc

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

• epel-release

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

• gettext

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

# Build off CentOS 7
FROM centos:centos7

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

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

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

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

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

# Tomcat will be accessed via port 8080
EXPOSE 8080

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

Creating a separate Guacamole image (without guacd)

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

• kcm-guacamole

• tomcat

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

• kcm-guacamole-auth-saml

• kcm-guacamole-auth-openid

• kcm-guacamole-auth-duo

• kcm-guacamole-auth-json

• kcm-guacamole-auth-ldap

• kcm-guacamole-auth-mysql

• kcm-guacamole-auth-postgresql

• kcm-guacamole-auth-sqlserver

• kcm-guacamole-auth-totp

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

• gettext

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

# Build off CentOS 7
FROM centos:centos7

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

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

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

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

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

# Tomcat will be accessed via port 8080
EXPOSE 8080

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

Creating a separate guacd image (without Guacamole)

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

• kcm-guacd

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

• kcm-libguac-client-rdp

• kcm-libguac-client-ssh

• kcm-libguac-client-telnet

• kcm-libguac-client-vnc

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

• epel-release

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

# Build off CentOS 7
FROM centos:centos7

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

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

# guacd will be accessed via port 4822
EXPOSE 4822

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