Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
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.
To start a guacd instance which listens on TCP port 4822:
where some-guacd
is the name you wish to assign to your container.
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:
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.
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_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.
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 which is automatically initialized with the Apache Guacamole database schema. It is built using the packages provided by Keeper Connection Manager and made available under the same . It is normally used to provide a PostgreSQL database for a container using the image.
In addition to the environment variables documented below, all environment variables supported by are accepted, as the official PostgreSQL image forms the basis of this image.
ACCEPT_EULA
The ACCEPT_EULA
environment variable must be set to "Y" to indicate your acceptance of the . This Docker image may not be used except under the terms of the EULA.
POSTGRES_PASSWORD
The PostgreSQL administrator password.
GUACAMOLE_DATABASE
The name of the database to create and initialized for use with Apache Guacamole. This environment variable ultimately maps to the POSTGRES_DB
environment variable of the official PostgreSQL image. If omitted, the default value defined by the official PostgreSQL image will be used.
The GUACAMOLE_DATABASE
variable is provided here for consistency with the other Guacamole-specific variables and may be omitted if POSTGRES_DB
is provided.
GUACAMOLE_ADMIN_PASSWORD
This is the Administrator password for the guacadmin
user.
GUACAMOLE_USERNAME
and GUACAMOLE_PASSWORD
The username and password to use for the PostgreSQL database user specific to the Guacamole web application. This pair of variables differ from the POSTGRES_USER
and POSTGRES_PASSWORD
environment variables provided by in that the created user has limited privileges, being granted only what privileges are absolutely required for Guacamole to run.
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 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:
Each of these images:
Is based off Docker's official images for the same databases, and thus each accepts the same core environment variables.
Accepts a common set of Guacamole-specific environment variables defining the name to be used for Guacamole's database and the reduced-privilege credentials to be used by Guacamole to execute queries.
Requires the same ACCEPT_EULA
environment variable as the and images.
The images may be used as part of an entirely Dockerized deployment of Apache Guacamole, or separately as an easier method of deploying a functional, pre-initialized, and supported database. When combined with the and images using , an entire deployment of Apache Guacamole can be created and managed using a single docker-compose.yml
.
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 which is automatically initialized with the Apache Guacamole database schema. It is built using the packages provided by Keeper Connection Manager and made available under the same . It is normally used to provide a MySQL database for a container using
In addition to the environment variables documented below, all environment variables supported by are accepted, as the official MySQL image forms the basis of this image.
ACCEPT_EULA
The ACCEPT_EULA
environment variable must be set to "Y" to indicate your acceptance of the . This Docker image may not be used except under the terms of the EULA.
MYSQL_RANDOM_ROOT_PASSWORD
This is an optional variable. Set to a non-empty value, like yes
, to generate a random initial password for the root user (using pwgen
). The generated root password will be printed to stdout (GENERATED ROOT PASSWORD: .....
).
GUACAMOLE_DATABASE
The name of the database to create and initialized for use with Apache Guacamole. This environment variable is required and ultimately maps to the MYSQL_DATABASE
environment variable of the official MySQL image.
The GUACAMOLE_DATABASE
variable is provided here for consistency with the other Guacamole-specific variables, but may be omitted if MYSQL_DATABASE
is provided.
GUACAMOLE_ADMIN_PASSWORD
This is the Administrator password for the guacadmin
user.
GUACAMOLE_USERNAME
and GUACAMOLE_PASSWORD
The username and password to use for the MySQL database user specific to the Guacamole web application. This pair of variables differ from the MYSQL_USER
and MYSQL_PASSWORD
environment variables provided by the official MySQL image in that the created user has limited privileges, being granted only what privileges are absolutely required for Guacamole to run.
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:
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 is followed.
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 is followed.
An instance of MySQL, automatically initialized with the Apache Guacamole database schema.
An instance of PostgreSQL, automatically initialized with the Apache Guacamole database schema.
Deployment of Keeper Connection Manager using Docker Compose
This section describes how to install Keeper Connection Manager using Docker by building a customized docker-compose orchestration file.
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.
Ubuntu
Install the haveged
package to ensure that the environment is capable of generating enough entropy for creating secure random numbers.
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.
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.
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.
If you plan to use a custom SSL certificate instead of Let's Encrypt, replace the "ssl" section of the Docker Compose file with a section that looks like this:
In this case, CERTIFICATE_FILE
is the PEM-encoded certificate including the intermediate certificate chain. The PRIVATE_KEY_FILE
is the private key file.
Also, note that in the above snippet, there is a volume mount that assigns the local filesystem to the target container. You should only modify the C:\Users\Path\To\Cert
portion of the string. On linux environments it will be /path/to/cert
.
On Windows, open a Command Prompt. On Linux, open the terminal shell. Navigate to the location of the docker-compose.yml
file that was saved in step 2.
To start up the environment, simply type the below command:
Note: Some versions require "docker-compose" with a hyphen.
That's it. If everything is successful, you can open the Keeper Connection Manager login screen on the specified FQDN.
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
.
If you plan to use remote browser isolation, you'll need to create a seccomp
security profile for the guacd container. For a new installation of Keeper Connection Manager, the kcm-setup.run
script automatically handles this for you and places the file called guacd-docker-seccomp.json
in the folder /etc/kcm-setup/
on the instance.
If this file is not automatically created, or you are upgrading an instance to use remote browser isolation, you may need to create the file manually.
You can obtain a copy of the file directly from the guacd
Docker image once your docker containers are updated and running. For example, the following prints the contents of that file to a terminal:
Place the output of this command into /etc/kcm-setup/guacd-docker-seccomp.json
and restart the containers.
Below is a description of each of the images.
The Apache Guacamole web application, deployed under Apache Tomcat.
The Apache Guacamole proxy daemon, guacd, with support for native protocols such as RDP and SSH.
An instance of MySQL, automatically initialized with the Apache Guacamole database schema.
An instance of PostgreSQL, automatically initialized with the Apache Guacamole database schema.
An instance of NGINX which automatically provides SSL termination for Keeper Connection Manager.
Now that your Keeper Connection Manager instance is running, you can login as guacadmin and start setting up some connections. Follow the Using Keeper Connection Manager documentation for next steps.
The next several sections of this installation guide provide detailed information about each specific Docker image, if you plan to customize or modify the environment.