Guacamole 1.5.4 has been released. The master branch will now be used for Guacamole 1.5.4, and the branch 1.4.0 will still be maintained for Guacamole 1.4.0 for a few months, but will gradually be retired.
If you decide to try the new images, make sure to delete the previous extensions. Go to the config/guacamole/extensions
directory, and delete the files that contain 1.4.0 in their names (rm *1.4.0*.jar
). Having multiple versions of the same extension will create issues. You can similarly clean the extensions-available
.
This is a fork of oznu/docker-guacamole, updated to tomcat 9.0.89 (guacamole is not compatible with tomcat10), postgresql 13/14/15 (see below), guacamole 1.5.4, and s6_overlay 3.1.
If you are looking to upgrade from Oznu's image, or from an image that uses a version of PostgreSQL lower than 13, please have a look at the upgrade instructions. It is written for my images, but can be adapted for any image.
Every month, inactive images on Docker Hub will be removed. If you use one of those, you'll need to update to a newer image. If you need to keep a specific image, please raise an Issue, so I can track it.
Base OS | PostgreSQL 13 | PostgreSQL 14 | PostgreSQL 15 | PostgreSQL 16 |
---|---|---|---|---|
Bullseye | guacamole:1.5.4-bullseye | N/A | N/A | N/A |
Ubuntu | guacamole:1.5.5 guacamole:latest |
guacamole:1.5.5-pg14 guacamole:latest-pg14 |
guacamole:1.5.5-pg15 guacamole:latest-pg15 |
guacamole:1.5.5-pg16 guacamole:latest-pg16 |
Alpine | N/A | guacamole:1.5.5-alpine | guacamole:1.5.5-alpine-pg15 | guacamole:1.5.5-alpine-pg16 |
2024-09-04 - Fixed an issue with PostgreSQL 16 images (Issue #40)
2024-08-26 - Updated to PostgreSQL JDBC 42.7.4
2024-08-21 - Updated to Tomcat 9.0.93, and added images for Postgresql 16 (suffixed with pg16)
2024-07-12 - Updated with fix from WindoC (Issue #38)
2024-07-09 - Updated to Tomcat 9.0.91
2024-05-15 - Updated to Tomcat 9.0.89
2024-04-22 - Updated to Tomcat 9.0.88
2024-04-09 - Updated to Guacamole 1.5.5
2024-03-20 - Updated to Tomcat 9.0.87 and PostgreSQL JDBC 42.7.3
2024-02-22 - Updated to Tomcat 9.0.86 and PostgreSQL JDBC 42.7.2
2024-02-02 - Added sso-ssl extension for the Github images (see below)
2024-02-01 - Updated Guacamole to 1.5.5 for the Github images
2024-01-10 - Updated to Tomcat 9.0.85
1.5.4
latest
, version 1.5.4, uses PostgreSQL 13, based on latest Tomcat (Ubuntu base), PostgresJDBC driver and S6 Overlay available at time of build.
1.5.4-pg14
latest-pg14
, version 1.5.4, uses PostgreSQL 14, based on latest Tomcat (Ubuntu base), PostgresJDBC driver and S6 Overlay available at time of build.
1.5.4-pg15
latest-pg15
, version 1.5.4, uses PostgreSQL 15, based on latest Tomcat (Ubuntu base), PostgresJDBC driver and S6 Overlay available at time of build.
1.5.4-bullseye
, version 1.5.4, uses PostgreSQL 14, based on latest Tomcat (latest available Debian Bullseye base image), PostgresJDBC driver and S6 Overlay available at time of build.
1.5.4-alpine
, version 1.5.4, build from scratch from Alpine Edge, using latest Tomcat, PostgresJDBC driver and S6 overlay available at time of build.
1.5.4-alpine-pg15
, version 1.5.4, build from scratch from Alpine Edge, using latest Tomcat, PostgresJDBC driver and S6 overlay available at time of build.
1.4.0
, version 1.4.0, uses PostgreSQL 13, based on latest Tomcat (Ubuntu base), PostgresJDBC driver and S6 Overlay available at time of build.
1.4.0-pg14
, version 1.4.0, uses PostgreSQL 14, based on latest Tomcat (Ubuntu base), PostgresJDBC driver and S6 Overlay available at time of build.
1.4.0-bullseye
, version 1.4.0, uses PostgreSQL 14, based on latest Tomcat (latest available Debian Bullseye base image), PostgresJDBC driver and S6 Overlay available at time of build.
1.4.0-alpine
, version 1.4.0, build from scratch from Alpine Edge, using latest Tomcat, PostgresJDBC driver and S6 overlay available at time of build.
github
, github-pg13
, version 1.5.5, client and server built from the Apache GitHub repositories, uses PostgreSQL 13, based on latest Tomcat (Ubuntu base), PostgresJDBC driver and S6 Overlay available at time of build.
github-pg14
, version 1.5.5, client and server built from the Apache GitHub repositories, uses PostgreSQL 14, based on latest Tomcat (Ubuntu base), PostgresJDBC driver and S6 Overlay available at time of build.
github-pg15
, version 1.5.5, client and server built from the Apache GitHub repositories, uses PostgreSQL 15, based on latest Tomcat (Ubuntu base), PostgresJDBC driver and S6 Overlay available at time of build.
test
compiled from available source code on GitHub for guacamole-client and guacamole-server.
1.3.0
version 1.3.0, based on latest Tomcat, PostgresJDBC driver available at time of build, and S6 Overlay 2.2.0.3.
1.4.0-s6_v3
updated to s6 overlay 3.0.0.0 and tomcat:9.0.58-jre11 (note: This image is built on a custom build of s6 overlay. It will be renamed as latest when s6 overlay is fixed and I can use the release tarballs.)
If Guacamole is useful to you, do not hesitate to support the great work of the Apache Foundation.
On a side note, running the server I use to build these images, researching update info, maintaining the images, takes quite some time and a little money. I'll gladly accept a coffee!
A Docker Container for Apache Guacamole, a client-less remote desktop gateway. It supports standard protocols like VNC, RDP, and SSH over HTML5.
This container runs the guacamole web client, the guacd server and a postgres database.
docker run \
-p 8080:8080 \
-v </path/to/config>:/config \
abesnier/guacamole
The parameters are split into two halves, separated by a colon, the left hand side representing the host and the right the container side.
-p 8080:8080
- Binds the service to port 8080 on the Docker host, required
-v /config
- The config and database location, required
-e EXTENSIONS
- See below for details.
Extensions can be enabled using the -e EXTENSIONS
variable. Multiple extensions can be enabled using a comma separated list without spaces.
For example:
docker run \
-p 8080:8080 \
-v </path/to/config>:/config \
-e "EXTENSIONS=auth-ldap,auth-duo"
abesnier/guacamole
Currently the available extensions are:
[1.3.0] [1.4.0] [1.5.4] auth-ldap - LDAP Authentication
[1.3.0] [1.4.0] [1.5.4] auth-duo - Duo two-factor authentication
[1.3.0] [1.4.0] [1.5.4] auth-header - HTTP header authentication
[1.3.0] [1.4.0] [1.5.4] auth-sso-cas - CAS Authentication
[1.3.0] [1.4.0] [1.5.4] auth-sso-openid - OpenID Connect authentication
[1.3.0] [1.4.0] [1.5.4] auth-totp - TOTP two-factor authentication
[1.3.0] [1.4.0] [1.5.4] auth-quickconnect - Ad-hoc connections extension
[1.3.0] [1.4.0] [1.5.4] auth-sso-saml - SAML Authentication
[1.5.5] auth-sso-ssl - SSL/Smart cards authenticatition
[1.4.0] [1.5.4] auth-sso - SSO Authentication metapackage, contains classes for CAS, OpenID and SAML authentication (see links above)
[1.4.0] [1.5.4] auth-json - Encrypted JSON Authentication
[1.5.5] history-recording-storage - In-application playback of recordings
[1.5.4] vault - Support for retrieving secrets from key vaults
[1.5.5] auth-ban - Extension for automatically blocking brute-force auth attempts
[1.5.5] display-statistics - Display graphics statistics at the bottom of the cielnt screen for remote desktop sessions (remote desktop fps, server fps, cleint fps, dropped frames)
Extensions marked as available for version 1.5.5 are only available with the github
tags (github
, github-pg14
and github-pg15
).
You should only enable the extensions you require, if an extensions is not configured correctly in the guacamole.properties
file it may prevent the system from loading. See the official documentation for more details.
The default username is guacadmin
with password guacadmin
.
Mapped volumes behave differently when running Docker for Windows and you may encounter some issues with PostgreSQL file system permissions. To avoid these issues, and still retain your config between container upgrades and recreation, you can use the local volume driver, as shown in the docker-compose.yml
example below. When using this setup be careful to gracefully stop the container or data may be lost.
version: "3"
services:
guacamole:
image: abesnier/guacamole
container_name: guacamole
volumes:
- /local_path_config_directory:/config
ports:
- 8080:8080
See docker-compose.yml for more details
There are multiple ways to show the real IP of the users, and it depends on your network configuration, and/or docker configuration.
I have implemented Guacamole's REMOTE_IP_VALVE_ENABLED environment variable. See the documentation
For example, Issue #22 shows you a solution to show the clients IP behind a Cloudflare tunnel.
It is possible that after some upgrades, either in the Guacamole version, or to a newer PostgreSQL version (13 to 14 or 15, after you carefully follow the instructions here for example), you are faced with an error message after entering your TOTP token. Guacamole will display the message "Verification failed. Please try again.".
There are multiple causes to this issues I believe.
The first one was a slight oversight from my part during start-up of the container, and you are left with multiple versions of some extensions. Go to your /config/guacamole/extensions, and delete all extensions that do not contain the correct Guacamole version (1.5.2 at the time of writing this). This issue is now fixed, and extensions should be properly cleaned when the container starts again. So restart the container, and that should be it.
If cleaning does not solve the issue, then you will have to reset the TOTP secret for at least one admin user. This can be done in a one-liner:
docker exec -it guacamole bash -c "psql -U guacamole guacamole_db -c \"UPDATE guacamole_user_attribute SET attribute_value='false' WHERE attribute_name = 'guac-totp-key-confirmed' and user_id = (SELECT user_id FROM guacamole_user INNER JOIN guacamole_entity ON guacamole_entity.entity_id = guacamole_user.entity_id WHERE guacamole_entity.name = 'your username');\""
Once executed, try to login with the user name you specified, and you will be prompted to register your MFA again:
When your admin user has recovered access, he can go tio the admin panel and reset TOTP secret for other users. This will force users to re-enroll. See documentation here.
One of the shiny new extensions shipped with version 1.5.1 is the History Recording viewer inside Guacamole itself.
But there are some steps required to make it work properly.
First, create a folder that will store the recordings and that must be accessible to Docker. The easiest is to use a sub-folder from the config directory you need to use to start the container. config/guacamole/recordings
looks like a good option.
Then, you will need to amend the guacamole.properties
file to override Guacamole's default behaviour. Add the following line: recording-search-path: /config/guacamole/recordings
Amend your docker-compose.yml, or your docker run command, to add the history-recording-storage extension (EXTENSIONS=auth-ldap,auth-duo, history-recording-storage
for example).
Restart the container to load the changes. make sure the extension has been copied in the /config/guacamole/extensions
directory. If not, I messed something up in the image, and I'll let you report an issue!
Now, you can setup the session recording as per the Guacamole manual, and when a connection that has recording enabled is closed, you should be able to see in the recordings directory, and see the "View >" link in the History tab:
Recordings can be found in your Guacamole server:
Note that guacamole needs to be allowed to read and write into the directory storing the recordings. Please see this discussion for a good summary of the requirements.
There is a known bug, where, in certain conditions, the underscore character is not displayed properly. This issue appeared since Guacamole 1.3, and still exists in 1.4.
Based on some investigations, it seems the issue is with the libpango library (text rendering library), that is used by Guacamole. The issue has been known for quite a few years now by the library team, but unfortunately, it does not look like a solution will ever be found, as it really appears to be quite random and difficult to reproduce.
Please have a look at this JIRA issue for details.
Now, that being said, here's what happens: by default, a new ssh connection will use the default remote machine font (most likely the default monospace font, and in most Linux distros these days, it is DejaVu or Nimbus), with a size 12.
This exact configuration, in some cases will result in the underscore not being displayed.
There are two solutions that worked for me:
Change the base image for my Docker image (downgrading from Debian Bullseye to Debian Buster)
Change the font size in the connection settings
The first solution is not good for me, as the idea of this image is to be kept up-to-date with the latest available packages.
The second solution is easy to implement, but it must be done by the admin. Go to Guacamole > Settings > Connections > Parameters > change the font size to 14 for example > save your changes.
If the docker seems to not start properly, check the logs with docker logs <container_name>
. It may be useful to start the container with a higher debug verbosity, by using the GUACD_LOG_LEVEL environment variable. The variable can be set either by adding -e GUACD_LOG_LEVEL=debug
to your docker run command, or in the environment section of your docker-compose.yml
file. The log will be more verbose, and will help you pinpoint the errors.
If you see lines like this one: postgres: could not access the server configuration file "/config/postgres/postgresql.conf": No such file or directory
, this means that the configuration volume could not be mounted properly.
If that is the case, make sure to start the container as root. This will force the creation of the config folder.
docker run \
-p 8080:8080 \
-u root \
-v </path/to/config>:/config \
abesnier/guacamole
or in docker-compose.yml:
version: "3"
services:
guacamole:
image: abesnier/guacamole
container_name: guacamole
user: root
volumes:
- </path/to/config>:/config
ports:
- 8080:8080
Yeah, I know. As Docker still sees a guacamole-brading-1.5.1.jar in the config/guacamole/extensions
directory, it will not overwrite it with the file in the image.
The solution is simply to remove the jar file in the config directory, and restart the container.
This issue was raised on Github, and here are the solutions:
1 - Delete the content of the config directory, and the full setup of Guacamole will be reset. You will lose all your connections, history, etc... but the default user will be re-generated.
2 - Download the database schema for the default user from https://raw.githubusercontent.com/apache/guacamole-client/main/extensions/guacamole-auth-jdbc/modules/guacamole-auth-jdbc-postgresql/schema/002-create-admin-user.sql and put it in your config directory.
Enter the docker container (docker exec -it guacamole bash
)
Execute the SQL file with command psql -U guacamole guacamole_db -a -f 002-create-admin-user.sql
.
You can now logon with guacadmin/guacadmin.
Well, I must admit, I managed to break a few things here and there nevertheless...
The easiest way to correct issues is to stop the container, delete the config folder, and restart the container.
But this has the side effect of deleting your stored users and connections as well.
You can backup and restore the database with the following command (assuming your container is named guacamole
):
Backup: docker exec -it guacamole bash -c "pg_dump -U guacamole -F t guacamole_db > guacamole_db_backup.tar"
This creates a guacamole_db_backup.tar
in your config
directory that you need to save somewhere else.
Now stop the container, delete the config folder, and restart the container.
To restore the database, copy the backup file in your mounted config folder, and run docker exec -it guacamole bash -c "pg_restore -d guacamole_db guacamole_db_backup.tar -c -U guacamole"
. You can now login to Guacamole with your user data and should find your connections as you left them.
Have a look at the GitHub repo, and the Issues page.
If you believe the issue is with Guacamole and not the docker image, have a look at the mailing list for general support, and if you believe there is a bug, use the bug tracker to report it.
And of course, don't forget to look at the official documentation.
Copyright (C) 2021-2024 abesnier
Copyright (C) 2017-2020 oznu
Apache Guacamole is released under the Apache License version 2.0.
Extensions uses third-party modules. To consult the licensing for each module, download the extension from https://guacamole.apache.org/releases/1.5.1/, extract it, and check the content of the bundled
directory.
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.