Chapter 3. Installing Guacamole with Docker

Chapter 3. Installing Guacamole with Docker
Prev	Part I. User's Guide	Next

Chapter 3. Installing Guacamole with Docker

Table of Contents

Running the guacd Docker image

Running guacd for use by the Guacamole Docker image
Running guacd for use by services outside Docker

The Guacamole Docker image

Deploying Guacamole with MySQL authentication
Deploying Guacamole with PostgreSQL authentication
Deploying Guacamole with LDAP authentication

Guacamole can be deployed using Docker, removing the need to build guacamole-server from source or configure the web application manually. The Guacamole project provides officially-supported Docker images for both Guacamole and guacd which are kept up-to-date with each release.

A typical Docker deployment of Guacamole will involve three separate containers, linked together at creation time:

guacamole/guacd: Provides the guacd daemon, built from the released guacamole-server source with support for VNC, RDP, SSH, and telnet.
guacamole/guacamole: Provides the Guacamole web application running within Tomcat 8 with support for WebSocket. The configuration necessary to connect to the linked guacd container and MySQL or PostgreSQL database will be generated automatically when the image starts.

mysql or postgresql: Provides the database that Guacamole will use for authentication and storage of connection configuration data.

This separation is important, as it facilitates upgrades and maintains proper separation of concerns. With the database separate from Guacamole and guacd, those containers can be freely destroyed and recreated at will. The only container which must persist data through upgrades is the database.

Running the guacd Docker image

The guacd Docker image is built from the released guacamole-server source with support for VNC, RDP, SSH, and telnet. Common pitfalls like installing the required dependencies, installing fonts for SSH or telnet, and ensuring the FreeRDP plugins are installed to the correct location are all taken care of. It will simply just work.

Running guacd for use by the Guacamole Docker image

When running the guacd image with the intent of linking to a Guacamole container, no ports need be exposed on the network. Access to these ports will be handled automatically by Docker during linking, and the Guacamole image will properly detect and configure the connection to guacd.

$ docker run --name some-guacd -d guacamole/guacd

When run in this manner, guacd will be listening on its default port 4822, but this port will only be available to Docker containers that have been explicitly linked to some-guacd.

Running guacd for use by services outside Docker

If you are not going to use the Guacamole image, you can still leverage the guacd image for ease of installation and maintenance. By exposing the guacd port, 4822, services external to Docker will be able to access guacd.

Important

Take great care when doing this - guacd is a passive proxy and does not perform any kind of authentication.

If you do not properly isolate guacd from untrusted parts of your network, malicious users may be able to use guacd as a jumping point to other systems.

$ docker run --name some-guacd -d -p 4822:4822 guacamole/guacd

guacd will now be listening on port 4822, and Docker will expose this port on the same server hosting Docker. Other services, such as an instance of Tomcat running outside of Docker, will be able to connect to guacd directly.

The Guacamole Docker image

The Guacamole Docker image is built on top of a standard Tomcat 8 image and takes care of all configuration automatically. When properly linked to a guacd container and either a PostgreSQL or MySQL database, the necessary Guacamole configuration will be automatically generated at startup.

The name of the database and all associated credentials are specified with environment variables given when the container is created. All other configuration information is generated from the Docker links, and need only be explicitly provided if Docker is not used to host the database.

Important

You will need to initialize the database manually. Guacamole will not automatically create its own tables, but SQL scripts are provided to do this.

Once the Guacamole image is running, Guacamole will be accessible at http://HOSTNAME:8080/guacamole/, where HOSTNAME is the hostname or address of the machine hosting Docker.

Deploying Guacamole with MySQL authentication

Before deploying Guacamole with the intent of using MySQL for authentication, please ensure that you have each of the following already prepared:

A Docker container running the guacamole/guacd image. Guacamole needs guacd in order to function, and the Guacamole Docker image depends on a linked Docker container running guacd.
A Docker container running the mysql image, or network access to a working installation of MySQL.

Initializing the MySQL database

If your database is not already initialized with the Guacamole schema, you will need to do so prior to using Guacamole. A convenience script for generating the necessary SQL to do this is included in the Guacamole image.

To generate a SQL script which can be used to initialize a fresh MySQL database as documented in Chapter 6, Database authentication:

$ docker run --rm guacamole/guacamole /opt/guacamole/bin/initdb.sh --mysql > initdb.sql

Alternatively, you can use the SQL scripts included with the database authentication.

Once this script is generated, you must:

Create a database for Guacamole within MySQL, such as guacamole_db.
Create a user for Guacamole within MySQL with access to this database, such as guacamole_user.
Run the script on the newly-created database.

The process for doing this via the mysql utility included with MySQL is documented in Chapter 6, Database authentication.

Deploying Guacamole

Linking Guacamole to MySQL will requires additional configuration parameters specified via environment variables. These variables collectively describe how Guacamole will connect to MySQL:

Variable	Description
`MYSQL_DATABASE`	The name of the database to use for Guacamole authentication.
`MYSQL_USER`	The user that Guacamole will use to connect to MySQL.
`MYSQL_PASSWORD`	The password that Guacamole will provide when connecting to MySQL as `MYSQL_USER`.

Additional optional environment variables may be used to configure Guacamole's default behavior with respect to concurrent connection use by one or more users. Concurrent use of connections and connection groups can be limited to an overall maximum and/or a per-user maximum:

Variable	Description
`MYSQL_ABSOLUTE_MAX_CONNECTIONS`	The absolute maximum number of concurrent connections to allow at any time, regardless of the Guacamole connection or user involved. If set to "0", this will be unlimited. Because this limit applies across all Guacamole connections, it cannot be overridden if set. By default, the absolute total number of concurrent connections is unlimited ("0").
`MYSQL_DEFAULT_MAX_CONNECTIONS`	The maximum number of concurrent connections to allow to any one Guacamole connection. If set to "0", this will be unlimited. This can be overridden on a per-connection basis when editing a connection. By default, overall concurrent use of connections is unlimited ("0").
`MYSQL_DEFAULT_MAX_GROUP_CONNECTIONS`	The maximum number of concurrent connections to allow to any one Guacamole connection group. If set to "0", this will be unlimited. This can be overridden on a per-group basis when editing a connection group. By default, overall concurrent use of connection groups is unlimited ("0").
`MYSQL_DEFAULT_MAX_CONNECTIONS_PER_USER`	The maximum number of concurrent connections to allow a single user to maintain to any one Guacamole connection. If set to "0", this will be unlimited. This can be overridden on a per-connection basis when editing a connection. By default, per-user concurrent use of connections is unlimited ("0").
`MYSQL_DEFAULT_MAX_GROUP_CONNECTIONS_PER_USER`	The maximum number of concurrent connections to allow a single user to maintain to any one Guacamole connection group. If set to "0", this will be unlimited. This can be overridden on a per-group basis when editing a connection group. By default, per-user concurrent use of connection groups is limited to one ("1"), to prevent a balancing connection group from being completely exhausted by one user alone.

Once your guacd container is ready, and the values of the above variables are known, Guacamole can be deployed through Docker:

$ docker run --name some-guacamole --link some-guacd:guacd \
    --link some-mysql:mysql         \
    -e MYSQL_DATABASE=guacamole_db  \
    -e MYSQL_USER=guacamole_user    \
    -e MYSQL_PASSWORD=some_password \
    -d -p 8080:8080 guacamole/guacamole

The network connection information for MySQL is normally implied through the "mysql" Docker link, and thus does not need to be explicitly specified. If you are not using Docker to provide your MySQL database, you will need to provide the network connection information yourself using additional environment variables:

Variable	Description
`MYSQL_HOSTNAME`	The hostname of the database to use for Guacamole authentication. This is required if you are not using Docker to provide your MySQL database.
`MYSQL_PORT`	The user that Guacamole will use to connect to MySQL. This environment variable is optional. If not provided, the standard MySQL port of 3306 will be used.

The MYSQL_HOSTNAME and, if necessary, MYSQL_POST environment variables can thus be used in place of a Docker link if using a Docker link is impossible or undesirable:

$ docker run --name some-guacamole --link some-guacd:guacd \
    -e MYSQL_HOSTNAME=172.17.42.1   \
    -e MYSQL_DATABASE=guacamole_db  \
    -e MYSQL_USER=guacamole_user    \
    -e MYSQL_PASSWORD=some_password \
    -d -p 8080:8080 guacamole/guacamole

If any required environment variables are omitted, you will receive an error message in the logs, and the image will stop. You will then need to recreate the container with the proper variables specified.

Verifying the Guacamole install

Now that the Guacamole image is running, Guacamole should be accessible at http://HOSTNAME:8080/guacamole/, where HOSTNAME is the hostname or address of the machine hosting Docker.

If you cannot access Guacamole, check the logs using Docker to determine if something is wrong. Configuration parameters may have been given incorrectly, or the database may be improperly initialized:

$ docker logs some-guacamole

If Guacamole has been successfully installed, you will see the Guacamole login screen. The database initialization scripts will create the default administrative user as "guacadmin" with the password "guacadmin". You should change your password immediately after verifying that your login works.

Once you have verified Guacamole has been deployed successfully, you can create connections and add users through the web interface as described in Chapter 10, Administration.

Deploying Guacamole with PostgreSQL authentication

Before deploying Guacamole with the intent of using PostgreSQL for authentication, please ensure that you have each of the following already prepared:

A Docker container running the guacamole/guacd image. Guacamole needs guacd in order to function, and the Guacamole Docker image depends on a linked Docker container running guacd.
A Docker container running the postgresql image, or network access to a working installation of PostgreSQL.

Initializing the PostgreSQL database

To generate a SQL script which can be used to initialize a fresh PostgreSQL database as documented in Chapter 6, Database authentication:

$ docker run --rm guacamole/guacamole /opt/guacamole/bin/initdb.sh --postgres > initdb.sql

Alternatively, you can use the SQL scripts included with the database authentication.

Once this script is generated, you must:

Create a database for Guacamole within PostgreSQL, such as guacamole_db.
Run the script on the newly-created database.
Create a user for Guacamole within PostgreSQL with access to the tables and sequences of this database, such as guacamole_user.

The process for doing this via the psql and createdb utilities included with PostgreSQL is documented in Chapter 6, Database authentication.

Deploying Guacamole

Linking Guacamole to your PostgreSQL database will require additional configuration parameters specified via environment variables. These variables collectively describe how Guacamole will connect to PostgreSQL:

Variable	Description
`POSTGRES_DATABASE`	The name of the database to use for Guacamole authentication.
`POSTGRES_USER`	The user that Guacamole will use to connect to PostgreSQL.
`POSTGRES_PASSWORD`	The password that Guacamole will provide when connecting to PostgreSQL as `POSTGRES_USER`.

Variable	Description
`POSTGRES_ABSOLUTE_MAX_CONNECTIONS`	The absolute maximum number of concurrent connections to allow at any time, regardless of the Guacamole connection or user involved. If set to "0", this will be unlimited. Because this limit applies across all Guacamole connections, it cannot be overridden if set. By default, the absolute total number of concurrent connections is unlimited ("0").
`POSTGRES_DEFAULT_MAX_CONNECTIONS`	The maximum number of concurrent connections to allow to any one Guacamole connection. If set to "0", this will be unlimited. This can be overridden on a per-connection basis when editing a connection. By default, overall concurrent use of connections is unlimited ("0").
`POSTGRES_DEFAULT_MAX_GROUP_CONNECTIONS`	The maximum number of concurrent connections to allow to any one Guacamole connection group. If set to "0", this will be unlimited. This can be overridden on a per-group basis when editing a connection group. By default, overall concurrent use of connection groups is unlimited ("0").
`POSTGRES_DEFAULT_MAX_CONNECTIONS_PER_USER`	The maximum number of concurrent connections to allow a single user to maintain to any one Guacamole connection. If set to "0", this will be unlimited. This can be overridden on a per-connection basis when editing a connection. By default, per-user concurrent use of connections is unlimited ("0").
`POSTGRES_DEFAULT_MAX_GROUP_CONNECTIONS_PER_USER`	The maximum number of concurrent connections to allow a single user to maintain to any one Guacamole connection group. If set to "0", this will be unlimited. This can be overridden on a per-group basis when editing a connection group. By default, per-user concurrent use of connection groups is limited to one ("1"), to prevent a balancing connection group from being completely exhausted by one user alone.

Once your guacd container is ready, and the values of the above variables are known, Guacamole can be deployed through Docker:

$ docker run --name some-guacamole --link some-guacd:guacd \
    --link some-postgres:postgres      \
    -e POSTGRES_DATABASE=guacamole_db  \
    -e POSTGRES_USER=guacamole_user    \
    -e POSTGRES_PASSWORD=some_password \
    -d -p 8080:8080 guacamole/guacamole

The network connection information for PostgreSQL is normally implied through the "postgres" Docker link, and thus does not need to be explicitly specified. If you are not using Docker to provide your PostgreSQL database, you will need to provide the network connection information yourself using additional environment variables:

Variable	Description
`POSTGRES_HOSTNAME`	The hostname of the database to use for Guacamole authentication. This is required if you are not using Docker to provide your PostgreSQL database.
`POSTGRES_PORT`	The user that Guacamole will use to connect to PostgreSQL. This environment variable is optional. If not provided, the standard PostgreSQL port of 5432 will be used.

The POSTGRES_HOSTNAME and, if necessary, POSTGRES_POST environment variables can thus be used in place of a Docker link if using a Docker link is impossible or undesirable:

$ docker run --name some-guacamole --link some-guacd:guacd \
    -e POSTGRES_HOSTNAME=172.17.42.1   \
    -e POSTGRES_DATABASE=guacamole_db  \
    -e POSTGRES_USER=guacamole_user    \
    -e POSTGRES_PASSWORD=some_password \
    -d -p 8080:8080 guacamole/guacamole

Verifying the Guacamole install

Now that the Guacamole image is running, Guacamole should be accessible at http://HOSTNAME:8080/guacamole/, where HOSTNAME is the hostname or address of the machine hosting Docker.

$ docker logs some-guacamole

Once you have verified Guacamole has been deployed successfully, you can create connections and add users through the web interface as described in Chapter 10, Administration.

Deploying Guacamole with LDAP authentication

Before deploying Guacamole with the intent of using LDAP for authentication, please ensure that you have each of the following already prepared:

A Docker container running the guacamole/guacd image. Guacamole needs guacd in order to function, and the Guacamole Docker image depends on a linked Docker container running guacd.
Network access to a working LDAP server.

Deploying Guacamole

Linking Guacamole to your LDAP directory will require additional configuration parameters specified via environment variables. These variables collectively describe how Guacamole will connect to LDAP:

Variable	Description
`LDAP_HOSTNAME`	The hostname or IP address of your LDAP server.
`LDAP_USER_BASE_DN`	The base of the DN for all Guacamole users. All Guacamole users that will be authenticating against LDAP must be descendents of this base DN.

Additional optional environment variables may be used to configure the details of your LDAP directory hierarchy, encryption, or to enable more flexible searching for user accounts:

Variable	Description
`LDAP_PORT`	The port your LDAP server listens on. By default, this will be 389 for unencrypted LDAP or LDAP using STARTTLS, and 636 for LDAP over SSL (LDAPS).
`LDAP_ENCRYPTION_METHOD`	The encryption mechanism that Guacamole should use when communicating with your LDAP server. 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_GROUP_BASE_DN`	The base of the DN for all groups that may be referenced within Guacamole configurations using the standard seeAlso attribute. All groups which will be used to control access to Guacamole configurations must be descendents of this base DN. If this variable is omitted, the seeAlso attribute will have no effect on Guacamole configurations.
`LDAP_SEARCH_BIND_DN`	The DN (Distinguished Name) of the user to bind as when authenticating users that are attempting to log in. If specified, Guacamole will query the LDAP directory to determine the DN of each user that logs in. If omitted, each user's DN will be derived directly using the base DN specified with `LDAP_USER_BASE_DN`.
`LDAP_SEARCH_BIND_PASSWORD`	The password to provide to the LDAP server when binding as `LDAP_SEARCH_BIND_DN` to authenticate other users. This variable is only used if `LDAP_SEARCH_BIND_DN` is specified. If omitted, but `LDAP_SEARCH_BIND_DN` is specified, Guacamole will attempt to bind with the LDAP server without a password.
`LDAP_USERNAME_ATTRIBUTE`	The attribute or attributes which contain the username within all Guacamole user objects in the LDAP directory. Usually, and by default, this will simply be "uid". If your LDAP directory contains users whose usernames are dictated by different attributes, multiple attributes can be specified here, separated by commas, but beware: doing so requires that a search DN be provided with `LDAP_SEARCH_BIND_DN`.
`LDAP_CONFIG_BASE_DN`	The base of the DN for all Guacamole configurations. If omitted, the configurations of Guacamole connections will simply not be queried from the LDAP directory, and you will need to store them elsewhere, such as within a MySQL or PostgreSQL database.

Once your guacd container is ready, and the values of the above variables are known, Guacamole can be deployed through Docker:

$ docker run --name some-guacamole --link some-guacd:guacd \
    -e LDAP_HOSTNAME=172.17.42.1                            \
    -e LDAP_USER_BASE_DN=ou=people,dc=example,dc=com        \
    -e LDAP_CONFIG_BASE_DN=ou=connections,dc=example,dc=com \
    -d -p 8080:8080 guacamole/guacamole

As documented in Chapter 7, LDAP authentication, Guacamole does support combining LDAP with a MySQL or PostgreSQL database, and this can be configured with the Guacamole Docker image, as well. By providing the required environment variables for both systems, Guacamole will automatically be configured to use both when the Docker image starts:

$ docker run --name some-guacamole --link some-guacd:guacd \
    -e LDAP_HOSTNAME=172.17.42.1                            \
    -e LDAP_USER_BASE_DN=ou=people,dc=example,dc=com        \
    -e LDAP_CONFIG_BASE_DN=ou=connections,dc=example,dc=com \
    -e MYSQL_HOSTNAME=172.17.42.1   \
    -e MYSQL_DATABASE=guacamole_db  \
    -e MYSQL_USER=guacamole_user    \
    -e MYSQL_PASSWORD=some_password \
    -d -p 8080:8080 guacamole/guacamole

Verifying the Guacamole install

Now that the Guacamole image is running, Guacamole should be accessible at http://HOSTNAME:8080/guacamole/, where HOSTNAME is the hostname or address of the machine hosting Docker.

$ docker logs some-guacamole

If Guacamole has been successfully installed, you will see the Guacamole login screen, and should be able to login using an LDAP account beneath LDAP_USER_BASE_DN. You will be able to access any connections defined within LDAP_CONFIG_BASE_DN for which your user has access. If a MySQL or PostgreSQL database has also been configured, and your user has an account within that database, you will also be able to access your connections from that database.

Prev	Up	Next
Chapter 2. Installing Guacamole natively	Home	Chapter 4. Proxying Guacamole