Apache Guacamole consists of two main components:
guacd proxy and all native, server-side components required for Guacamole to connect to remote desktops.Both components must be installed to set up the Guacamole web-based remote desktop client.
Ensure your system package cache is up-to-date:
apt update
Guacamole Server needs to be built from source, which requires several dependencies. Install them with the following command:
apt install -y build-essential \
libcairo2-dev \
libjpeg62-turbo-dev \
libpng-dev \
libtool-bin \
uuid-dev \
libossp-uuid-dev \
libavcodec-dev \
libavformat-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
To build Guacamole, download the latest source tarball from the Guacamole releases page. As of this writing, the latest version is 1.5.5. Set a variable for the current stable version and download the source:
VER=1.5.5
wget https://downloads.apache.org/guacamole/$VER/source/guacamole-server-$VER.tar.gz
Extract the tarball:
tar xzf guacamole-server-$VER.tar.gz
Navigate to the extracted source directory and run the configuration script:
cd guacamole-server-$VER
./configure --with-systemd-dir=/etc/systemd/system/
If you encounter issues with optional dependencies like FFmpeg (used by the guacenc utility), you can disable them:
./configure --with-systemd-dir=/etc/systemd/system/ --disable-guacenc
Build and install Guacamole Server:
make
make install
After installation, update the system’s shared library cache:
ldconfig
Reload the systemd configuration files, and enable and start the guacd service:
systemctl daemon-reload
systemctl enable --now guacd
Check the service status:
systemctl status guacd
If the guacd service listens on the IPv6 address (::1) instead of 127.0.0.1, modify the /etc/hosts file by commenting out the IPv6 localhost line:
sed -i '/^::1/s/^/#/g' /etc/hosts
Restart the service:
systemctl restart guacd
Confirm the service is now running on 127.0.0.1:
ss -altnp | grep :4822
Apache Tomcat serves Guacamole client content to users via a web browser. As Guacamole doesn't support Tomcat 10 yet (the default on Debian 12), Tomcat 9 must be installed either by building from the archive or by using the Debian 11 repositories.
Refer to this guide: How to Install Tomcat 9 on Debian 12.
echo "deb http://deb.debian.org/debian/ bullseye main" > /etc/apt/sources.list.d/bullseye.list
apt update
apt install tomcat9 tomcat9-admin tomcat9-common tomcat9-user -y
sed -i 's/^/#/' /etc/apt/sources.list.d/bullseye.list
systemctl status tomcat9.service
● tomcat9.service - Apache Tomcat 9 Web Application Server
Active: active (running)
If UFW is installed and enabled, allow traffic on port 8080:
ufw allow 8080/tcp
The Guacamole client provides an HTML5 interface to access remote desktops. This requires both guacamole-client and a working Guacamole daemon (guacd).
Create the configuration directory:
mkdir /etc/guacamole
Download the latest Guacamole client (e.g., version 1.5.5):
VER=1.5.5
wget https://downloads.apache.org/guacamole/$VER/binary/guacamole-$VER.war -O /etc/guacamole/guacamole.war
Create a symbolic link to Tomcat’s webapps directory:
ln -s /etc/guacamole/guacamole.war /var/lib/tomcat9/webapps/
If using Tomcat built from source:
ln -s /etc/guacamole/guacamole.war /opt/tomcat9/webapps/
Restart Tomcat and Guacamole server:
systemctl restart tomcat9 guacd
Guacamole requires proper configuration to connect with guacd and manage connections.
Create directories for Guacamole extensions and libraries:
mkdir /etc/guacamole/{extensions,lib}
Set the Guacamole home directory in the Tomcat environment file:
echo "GUACAMOLE_HOME=/etc/guacamole" >> /etc/default/tomcat9
If using Tomcat built from source:
echo "GUACAMOLE_HOME=/etc/guacamole" >> /etc/profile.d/tomcat9.sh
Define the Guacamole connection settings:
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
ln -s /etc/guacamole /usr/share/tomcat9/.guacamole
If using Tomcat built from source:
ln -s /etc/guacamole /opt/tomcat9/.guacamole
By default, Guacamole uses the user-mapping.xml file to store user credentials, connection details, and permissions.
Define users and their connections in /etc/guacamole/user-mapping.xml. For example:
<user-mapping>
<authorize username="user" password="password">
<connection name="Example Server">
<protocol>vnc</protocol>
<param name="hostname">192.168.1.10</param>
<param name="port">5900</param>
</connection>
</authorize>
</user-mapping>
Note: Avoid storing sensitive information like plain-text passwords in
user-mapping.xml. Implement HTTPS to secure the Guacamole web UI if it's accessible over the internet.
Guacamole supports various authentication methods beyond the default XML file:
For improved security, consider using a database or an external authentication provider.