Apache Guacamole Client

You can avoid using plaintext environment variables for sensitive database credentials by using Docker Secrets.

Append _FILE to the standard environment variable names (e.g., MYSQL_PASSWORD becomes MYSQL_PASSWORD_FILE) and provide the path to the secret file within the container (typically /run/secrets/<secret_name>).

Precedence Rules:

• You can mix standard environment variables and _FILE variables.
• If both a standard variable (e.g., MYSQL_PASSWORD) and its _FILE counterpart (e.g., MYSQL_PASSWORD_FILE) are provided, the _FILE version takes precedence.

To initialize a SQLServer database for Guacamole:

1. Generate the SQL script: docker run --rm guacamole/guacamole /opt/guacamole/bin/initdb.sh --sqlserver > initdb.sql
2. Create the database (e.g., guacamole_db) in SQLServer.
3. Create a user (e.g., guacamole_user) with access to the database.
4. Run the generated script on the new database.

To authenticate a user, you must POST the base64-encoded, encrypted, and signed JSON to the /api/tokens endpoint. The payload must be sent as an HTTP parameter named data.

Important: You must URL-encode the base64 string before sending it, as base64 contains characters like + and = which have special meanings in URLs.

Authentication via POST

# Example using curl
curl --data-urlencode "data=BASE64_RESULT" http://localhost:8080/guacamole/api/tokens

Alternatively, you can include the data parameter as a query string in the URL of any Guacamole page.

$ curl --data-urlencode "data=BASE64_RESULT" http://localhost:8080/guacamole/api/tokens

To use the guacamole-auth-json extension, you must define a 128-bit secret key in your guacamole.properties file. This key is used by both the Guacamole server and your external system to sign and encrypt the authentication JSON.

To generate a 128-bit key from a passphrase, you can use the md5sum utility. The resulting 32-digit hex value must be assigned to the json-secret-key property.

# Generate a 128-bit key from a passphrase
$ echo -n "ThisIsATest" | md5sum
4c0b569e4c96df157eee1b65dd0e4d41  -

# Add to guacamole.properties
json-secret-key: 4c0b569e4c96df157eee1b65dd0e4d41

Guacamole does not automatically create its database tables. You must initialize the schema manually.

1. Generate the SQL script using the initdb.sh tool included in the image: docker run --rm guacamole/guacamole /opt/guacamole/bin/initdb.sh --postgresql > initdb.sql
2. Create the database (e.g., guacamole_db) in your PostgreSQL instance.
3. Run the generated script against the new database.
4. Create a user (e.g., guacamole_user) with appropriate access to the tables and sequences.

To initialize a MySQL database for Guacamole:

1. Generate the SQL script: docker run --rm guacamole/guacamole /opt/guacamole/bin/initdb.sh --mysql > initdb.sql
2. Create the database (e.g., guacamole_db) in MySQL.
3. Create a user (e.g., guacamole_user) with access to the database.
4. Run the generated script on the new database.

To run Apache Guacamole in Docker, you need three components:

1. The guacamole/guacamole image.
2. A running guacd container.
3. A database container (PostgreSQL, MySQL, or SQLServer).

Configuration is handled via environment variables. Once running, Guacamole is accessible at http://[address of container]:8080/guacamole/.

guacamole-client is a Maven-based superproject that contains the various subprojects required to build Apache Guacamole. Apache Guacamole is an HTML5 web application that provides remote desktop access using remote desktop protocols.

While the subprojects are independent and can be built separately, using guacamole-client with Maven ensures that all dependencies are built in the correct order.

To link Guacamole to SQLServer, you can use either standard environment variables or Docker secrets.

Standard Variables:

• SQLSERVER_DATABASE
• SQLSERVER_USER
• SQLSERVER_PASSWORD

Docker Secrets (replaces standard variables):

• SQLSERVER_DATABASE_FILE
• SQLSERVER_USER_FILE
• SQLSERVER_PASSWORD_FILE

Failure to provide these will cause the container to stop.

# Example using Docker Secrets
docker run --name some-guacamole --link some-guacd:guacd \
    --link some-sqlserver:sqlserver      \
    -e SQLSERVER_DATABASE_FILE=/run/secrets/<secret_name> \
    -e SQLSERVER_USER_FILE=/run/secrets/<secret_name> \
    -e SQLSERVER_PASSWORD_FILE=/run/secrets/<secret_name> \
    -d -p 8080:8080 guacamole/guacamole

To link Guacamole to a PostgreSQL database, you must provide the following environment variables:

• POSTGRESQL_DATABASE: The name of the database.
• POSTGRESQL_USER: The database user.
• POSTGRESQL_PASSWORD: The password for the user.

To use Docker secrets instead, use:

• POSTGRESQL_DATABASE_FILE
• POSTGRESQL_USER_FILE
• POSTGRESQL_PASSWORD_FILE

Failure to provide these will cause the container to stop.

docker run --name some-guacamole --link some-guacd:guacd \
    --link some-postgres:postgres        \
    -e POSTGRESQL_DATABASE=guacamole_db  \
    -e POSTGRESQL_USER=guacamole_user    \
    -e POSTGRESQL_PASSWORD=some_password \
    -e POSTGRESQL_DATABASE_FILE=/run/secrets/<secret_name> \
    -e POSTGRESQL_USER_FILE=/run/secrets/<secret_name> \
    -e POSTGRESQL_PASSWORD_FILE=/run/secrets/<secret_name> \
    -d -p 8080:8080 guacamole/guacamole

To link Guacamole to a MySQL database, you must provide the following environment variables:

• MYSQL_DATABASE: The name of the database.
• MYSQL_USER: The database user.
• MYSQL_PASSWORD: The password for the user.

To use Docker secrets instead, use:

• MYSQL_DATABASE_FILE
• MYSQL_USER_FILE
• MYSQL_PASSWORD_FILE

Failure to provide these will cause the container to stop.

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 \
    -e MYSQL_DATABASE_FILE=/run/secrets/<secret_name> \
    -e MYSQL_USER_FILE=/run/secrets/<secret_name> \
    -e MYSQL_PASSWORD_FILE=/run/secrets/<secret_name> \
    -d -p 8080:8080 guacamole/guacamole

You can apply custom branding (colors, fonts, logos) and HTML extensions to the Guacamole Client web application by creating a JAR file containing a guac-manifest.json file. This manifest specifies the resources provided by the extension.

To install a branding extension:

1. Zip the branding directory into a JAR file.
2. Place the JAR file in the GUACAMOLE_HOME/extensions folder.
3. Reload the web application (e.g., by touching the .war file in Tomcat).

Note: Adjust paths based on your specific GUACAMOLE_HOME and web application deployment directory.