This guide will take you through the steps you can use to install Guacamole on Debian 12. Apache Guacamole is a client-less HTML5 web based remote desktop gateway which provides remote access to servers and desktops through a web browser. It supports standard protocols like VNC, RDP, and SSH.
Table of Contents
Install Guacamole on Debian 12
Guacamole is made up of two parts;
guacamole-server, which provides the guacd proxy and all the native, server-side components required by Guacamole to connect to remote desktops.
guacamole-clientwhich provides the client to be served by the servlet container which is usually
You need to install both of these components to setup Apache Guacamole web-based remote desktop client.
Install Guacamole Server on Debian 12
Run system Update
Ensure your system package cache is up-to-date;
Install Required Build Tools
To install guacamole-server, you need to build it from the source. This, therefore, requires that you need install the required build tools before you can start to build guacamole-server component;
apt install -y build-essential \ libcairo2-dev \ libjpeg62-turbo-dev \ libpng-dev \ libtool-bin \ libossp-uuid-dev \ libavutil-dev \ libswscale-dev \ freerdp2-dev \ libpango1.0-dev \ libssh2-1-dev \ libvncserver-dev \ libtelnet-dev \ libwebsockets-dev \ libssl-dev \ libvorbis-dev \ libwebp-dev \ libpulse-dev \ sudo \ vim
A comprehensive description of these dependency tools is available on required dependencies section.
Download Guacamole Source Code Tarball
To install Guacamole on Debian 12, we will build it from the source code. Hence download the latest source archive tarball from Guacamole releases page.
Apache Guacamole 1.5.3 is the latest release version as of this writing.
You can simply run the command below to download Apache Guacamole 1.5.3.
To make this easy, just set a variable for the current stable release version on the terminal.
Once the download is done, extract the source tarball.
tar xzf guacamole-server-$VER.tar.gz
Install Apache Guacamole on Debian 12
Navigate to guacamole server source code directory;
configure script to check if any required dependency is missing and to adapt Guacamole server to your system.
For more configure options, run,
... ------------------------------------------------ guacamole-server version 1.5.3 ------------------------------------------------ Library status: freerdp2 ............ yes pango ............... yes libavcodec .......... no libavformat.......... no libavutil ........... yes libssh2 ............. yes libssl .............. yes libswscale .......... yes libtelnet ........... yes libVNCServer ........ yes libvorbis ........... yes libpulse ............ yes libwebsockets ....... yes libwebp ............. yes wsock32 ............. no Protocol support: Kubernetes .... yes RDP ........... yes SSH ........... yes Telnet ........ yes VNC ........... yes Services / tools: guacd ...... yes guacenc .... no guaclog .... yes FreeRDP plugins: /usr/lib/x86_64-linux-gnu/freerdp2 Init scripts: no Systemd units: /etc/systemd/system/ Type "make" to compile guacamole-server.
Pay attention to out of the
configure script. If there is any unmet required dependency, fix before you can proceed.
Compile and install Guacamole Server on Debian 12;
Next, run the
ldconfig command to create the necessary links and cache to the most recent shared libraries found in the guacamole server directory.
Running Guacamole-Server on Debian 12
Reload systemd configuration files and start and enable guacd (Guacamole Daemon) to run on boot after the installation.
systemctl enable --now guacd
To check the status;
systemctl status guacd
● guacd.service - Guacamole Server Loaded: loaded (/etc/systemd/system/guacd.service; enabled; preset: enabled) Active: active (running) since Tue 2023-08-15 14:28:10 EDT; 11s ago Docs: man:guacd(8) Main PID: 18903 (guacd) Tasks: 1 (limit: 2307) Memory: 10.3M CPU: 14ms CGroup: /system.slice/guacd.service └─18903 /usr/local/sbin/guacd -f Aug 15 14:28:10 debian systemd: Started guacd.service - Guacamole Server. Aug 15 14:28:10 debian guacd: Guacamole proxy daemon (guacd) version 1.5.3 started Aug 15 14:28:10 debian guacd: guacd: INFO: Guacamole proxy daemon (guacd) version 1.5.3 started Aug 15 14:28:10 debian guacd: Listening on host ::1, port 4822 Aug 15 14:28:10 debian guacd: guacd: INFO: Listening on host ::1, port 4822
If you noticed, guacd is listening on IPv6 localhost address (Listening on host ::1, port 4822). This is probably because your hosts file is like;
127.0.0.1 localhost 127.0.1.1 debian # The following lines are desirable for IPv6 capable hosts ::1 localhost ip6-localhost ip6-loopback ff02::1 ip6-allnodes ff02::2 ip6-allrouters
See the line above! If you proceed with this in place, you will end up not being able to connect to your remote end points with such an error;
tomcat9: 15:47:52.938 [http-nio-8080-exec-5] ERROR o.a.g.s.GuacamoleHTTPTunnelServlet - HTTP tunnel request failed: java.net.ConnectException: Connection refused
Thus, comment out the IPv6 line on hosts file;
sed -i '/^::1/s/^/#/g' /etc/hosts
Restart Guacamole server;
systemctl restart guacd
systemctl status guacd
● guacd.service - Guacamole Server Loaded: loaded (/etc/systemd/system/guacd.service; enabled; preset: enabled) Active: active (running) since Tue 2023-08-15 15:54:42 EDT; 4s ago Docs: man:guacd(8) Main PID: 28272 (guacd) Tasks: 1 (limit: 2307) Memory: 10.0M CPU: 15ms CGroup: /system.slice/guacd.service └─28272 /usr/local/sbin/guacd -f Aug 15 15:54:42 debian systemd: Started guacd.service - Guacamole Server. Aug 15 15:54:42 debian guacd: Guacamole proxy daemon (guacd) version 1.5.3 started Aug 15 15:54:42 debian guacd: guacd: INFO: Guacamole proxy daemon (guacd) version 1.5.3 started Aug 15 15:54:42 debian guacd: Listening on host 127.0.0.1, port 4822 Aug 15 15:54:42 debian guacd: guacd: INFO: Listening on host 127.0.0.1, port 4822
ss -altnp | grep :4822
LISTEN 0 5 127.0.0.1:4822 0.0.0.0:* users:(("guacd",pid=28272,fd=4))
Install Tomcat Servlet
Apache Tomcat is used to serve guacamole client content to users that connects to guacamole server via the web browser. To install Tomcat 9 on Debian 12, you can build it from archive or install from the Debian 11 repos. This is because, Debian 12 ships with Tomcat 10 by default. Guacamole doesn’t support Tomcat 10 yet.
Install Tomcat 9 on Debian 12 by Building from Archive
Follow the link below to learn how to install Tomcat 9 on Debian 12 by building from Tomcat archive.
Install Tomcat 9 on Debian 12 from Debian 11 repos
Install the Debian 11 repos temporarily as follows;
echo "deb http://deb.debian.org/debian/ bullseye main" > cat /etc/apt/sources.list.d/bullseye.list
Then install Tomcat9;
apt install tomcat9 tomcat9-admin tomcat9-common tomcat9-user -y
Remove the Debian 11 repos;
sed -i 's/^/#/' /etc/apt/sources.list.d/bullseye.list
Tomcat9 is started and enabled to run on system boot upon installation. Check the status by running the command below;
systemctl status tomcat9.service
● tomcat9.service - Apache Tomcat 9 Web Application Server Loaded: loaded (/lib/systemd/system/tomcat9.service; enabled; preset: enabled) Active: active (running) since Tue 2023-08-15 15:31:14 EDT; 3min 16s ago Docs: https://tomcat.apache.org/tomcat-9.0-doc/index.html Process: 27898 ExecStartPre=/usr/libexec/tomcat9/tomcat-update-policy.sh (code=exited, status=0/SUCCESS) Main PID: 27902 (java) Tasks: 30 (limit: 2307) Memory: 85.5M CPU: 6.003s CGroup: /system.slice/tomcat9.service └─27902 /usr/lib/jvm/default-java/bin/java -Djava.util.logging.config.file=/var/lib/tomcat9/conf/logging.properties -Djava.util.logging.manager=org.apache.jul> Aug 15 15:31:18 debian tomcat9: Deployment of deployment descriptor [/etc/tomcat9/Catalina/localhost/manager.xml] has finished in [1,882] ms Aug 15 15:31:18 debian tomcat9: Deploying deployment descriptor [/etc/tomcat9/Catalina/localhost/host-manager.xml] Aug 15 15:31:18 debian tomcat9: The path attribute with value [/host-manager] in deployment descriptor [/etc/tomcat9/Catalina/localhost/host-manager.xml] has been i> Aug 15 15:31:19 debian tomcat9: At least one JAR was scanned for TLDs yet contained no TLDs. Enable debug logging for this logger for a complete list of JARs that w> Aug 15 15:31:19 debian tomcat9: Deployment of deployment descriptor [/etc/tomcat9/Catalina/localhost/host-manager.xml] has finished in  ms Aug 15 15:31:19 debian tomcat9: Deploying web application directory [/var/lib/tomcat9/webapps/ROOT] Aug 15 15:31:20 debian tomcat9: At least one JAR was scanned for TLDs yet contained no TLDs. Enable debug logging for this logger for a complete list of JARs that w> Aug 15 15:31:20 debian tomcat9: Deployment of web application directory [/var/lib/tomcat9/webapps/ROOT] has finished in  ms Aug 15 15:31:20 debian tomcat9: Starting ProtocolHandler ["http-nio-8080"] Aug 15 15:31:20 debian tomcat9: Server startup in  milliseconds
Apache Tomcat listens on port 8080/tcp by default;
ss -altnp | grep :8080
LISTEN 0 100 *:8080 *:* users:(("java",pid=22439,fd=37))
To allow external access to the serverlet, open the serverlet port 8080/tcp on UFW, if at all UFW is installed and enabled.
ufw allow 8080/tcp
Install Guacamole Client on Debian 12
guacamole-client contains provides web application that will serve the HTML5 Guacamole client to users that connect to your server. The web application will then connect to guacd on behalf of connected users in order to serve them any remote desktop they are authorized to access.
Download and Install Guacamole-client Binary
Create Guacamole configuration directory;
Guacamole client can be installed from source code or from ready binary. Binary installation is used in this demo.
Download Guacamole-client from Guacamole releases page for the respective latest version (v1.5.3 as of this writing) and store it in the configuration directory created above.
To download the current release version, v1.5.3 as of this writing, simply run the command below;
Similarly, we use the same client version variable;
wget \ https://downloads.apache.org/guacamole/$VER/binary/guacamole-$VER.war \ -O /etc/guacamole/guacamole.war
Create a symbolic link of the guacamole client to Tomcat webapps directory as shown below;
ln -s /etc/guacamole/guacamole.war /var/lib/tomcat9/webapps/
If you build Tomcat from Tomcat archive, then;
ln -s /etc/guacamole/guacamole.war /opt/tomcat9/webapps/
Restart Tomcat and Guacamole server to deploy the new web application;
systemctl restart tomcat9 guacd
Configure Apache Guacamole on Debian 12
Guacamole has two major configuration files;
/etc/guacamolewhich is referenced by the
/etc/guacamole/guacamole.propertieswhich is the main configuration file used by Guacamole and its extensions.
There are also guacamole extensions and libraries configurations. You need to create the directories for these configs;
Set the guacamole home directory environment variable and add it to
/etc/default/tomcat9 configuration file.
echo "GUACAMOLE_HOME=/etc/guacamole" >> /etc/default/tomcat9
If you build Tomcat from Tomcat archive, then;
echo "GUACAMOLE_HOME=/etc/guacamole" >> /etc/profile.d/tomcat9.sh
Configure Guacamole Server Connections
To define how Guacamole connects to
guacd, create the
guacamole.properties file under
/etc/guacamole directory with the following content.
cat > /etc/guacamole/guacamole.properties << EOL guacd-hostname: 127.0.0.1 guacd-port: 4822 user-mapping: /etc/guacamole/user-mapping.xml auth-provider: net.sourceforge.guacamole.net.basic.BasicFileAuthenticationProvider EOL
The configuration above is explained below;
guacd-hostname: localhost: This line sets the hostname of the Guacamole daemon (guacd) to “localhost.” The Guacamole daemon is responsible for handling remote desktop connections.
guacd-port: 4822: This line specifies the port number (4822) on which the Guacamole daemon (
guacd) is listening for connections.
user-mapping: /etc/guacamole/user-mapping.xml: This line specifies the path to the user mapping configuration file (
user-mapping.xml). This file defines how users are authenticated and which remote desktop connections they can access.
auth-provider: net.sourceforge.guacamole.net.basic.BasicFileAuthenticationProvider: This line sets the authentication provider to be used for user authentication. In this case, the BasicFileAuthenticationProvider is used, which means authentication will be based on user credentials defined in the
Next, link the Guacamole configurations directory to Tomcat servlet directory as shown below.
ln -s /etc/guacamole /usr/share/tomcat9/.guacamole
Similarly, if you build Tomcat from Tomcat archive, then;
ln -s /etc/guacamole /opt/tomcat9/.guacamole
Configure Guacamole Authentication Method
There are different authentication methods supported by Guacamole;
- Reading credentials from XML file (default).
- Database authentication
- LDAP authentication
- Retrieving secrets from a vault
- Duo two-factor authentication
- TOTP two-factor authentication
- HTTP header authentication
- Encrypted JSON authentication
- CAS Authentication
- OpenID Connect Authentication
- SAML Authentication
- RADIUS Authentication
Guacamole’s default authentication method reads all users and connections from a single file called
user-mapping.xml. We enabled basic authentication in the configuration above.
In this file,you need to define the users allowed to access Guacamole web UI, the servers to connect to and the method of connection.
You can choose to use other authentication methods below;
- Configure TOTP Two-Factor Authentication on Apache Guacamole
- Configure Guacamole MySQL Database Authentication
- Setup Apache Guacamole OpenLDAP Authentication
For the purposes of local testing, we will be using this method, however!
To begin with, generate the MD5 hash of passwords for the user to be used for logging into Guacamole web user interface.
Replace your password,
echo -n <password> | openssl md5
For example, where password is my password.
echo -n password | openssl md5
printf '%s' password | md5sum
Be sure to replace password with your strong password.
Next, create the default user authentication file,
user-mapping.xml with the following contents.
<user-mapping> <!-- Per-user authentication and config information --> <!-- A user using md5 to hash the password guacadmin user and its md5 hashed password below is used to login to Guacamole Web UI--> <authorize username="guacadmin" password="5f4dcc3b5aa765d61d8327deb882cf99" encoding="md5"> <!-- First authorized Remote connection --> <connection name="Ubuntu 22"> <protocol>ssh</protocol> <param name="hostname">192.168.58.37</param> <param name="port">22</param> </connection> <!-- Second authorized remote connection --> <connection name="Windows 10"> <protocol>rdp</protocol> <param name="hostname">192.168.56.121</param> <param name="port">3389</param> <param name="username">kifarunix</param> <param name="ignore-cert">true</param> </connection> </authorize> </user-mapping>
If you don’t specify the username and password in the file, you will be prompted to provide them while attempting to login, which I consider it a bit secure.
If you need to explicitly define usernames and passwords in the configuration file, add the parameters;
<param name="username">USERNAME</param> <param name="password">PASSWORD</param>
Save and exit the configuration file.
Restart both Tomcat and guacd to effect the changes.
systemctl restart tomcat9 guacd
Be sure to check the syslog,
/var/log/tomcat9/ log files for any issues.
Accessing Apache Guacamole from Browser
Use the credentials for the user whom you generated an MD5 hash for its password above.
Click on a connection to name to initiate remote login.
For example, to ssh into Ubuntu 22 server, just click on the connection name. This will get you a login prompt;
To login to Windows 10 via RDP, just click on Windows 10, enter the login credentials and proceed to the desktop.
Setup Apache Guacamole with HTTPS
Follow the guide below to learn how to configure Apache Guacamole with HTTPS;
If you encounter CONNECTION ERROR, and upon checking the logs;
journalctl -f -u guacd
Aug 15 16:31:53 debian guacd: Loading keymap "en-us-qwerty" Aug 15 16:31:53 debian guacd: guacd: INFO: Loading keymap "en-us-qwerty" Aug 15 16:31:53 debian guacd: RDP server closed/refused connection: Security negotiation failed (wrong security type?) Aug 15 16:31:53 debian guacd: guacd: INFO: RDP server closed/refused connection: Security negotiation failed (wrong security type?) Aug 15 16:31:53 debian guacd: guacd: INFO: User "@7de1f381-34cf-4e08-8df0-66a5048c6f65" disconnected (0 users remain) Aug 15 16:31:53 debian guacd: guacd: INFO: Last user of connection "$c9f11e3a-cc25-40c9-b6d2-c015773f7262" disconnected Aug 15 16:31:53 debian guacd: User "@7de1f381-34cf-4e08-8df0-66a5048c6f65" disconnected (0 users remain) Aug 15 16:31:53 debian guacd: Last user of connection "$c9f11e3a-cc25-40c9-b6d2-c015773f7262" disconnected Aug 15 16:31:53 debian guacd: Connection "$c9f11e3a-cc25-40c9-b6d2-c015773f7262" removed. Aug 15 16:31:53 debian guacd: guacd: INFO: Connection "$c9f11e3a-cc25-40c9-b6d2-c015773f7262" removed.
Aug 15 16:31:53 debian guacd: RDP server closed/refused connection: Security negotiation failed (wrong security type?)
Then fix it as follows;
Guacamole server (guacd) service runs as user
daemon by default.
ps aux | grep -v grep| grep guacd
daemon 28360 0.0 0.7 247892 15548 ? Ss 16:29 0:00 /usr/local/sbin/guacd -f
Create a guacd system user account which can be used to run guacd instead of running as daemon user.
useradd -M -d /var/lib/guacd/ -r -s /sbin/nologin -c "Guacd User" guacd
chown -R guacd: /var/lib/guacd
Next, update the Guacd service user;
sed -i 's/daemon/guacd/' /etc/systemd/system/guacd.service
Reload systemd daemon;
Restart Guacd Service;
systemctl restart guacd
At this point, RDP should work without any issues.
You can now add more connections to your Guacamole. Check Guacamole connections page on how to configure. That marks the end of our guide on how to install Guacamole on Debian 12.