How to Install Apache Guacamole on Debian 10: A Complete Guide
Managing remote access to multiple servers can be a complex task, often requiring different client applications for protocols like RDP, VNC, and SSH. Apache Guacamole simplifies this entire process by providing a clientless remote desktop gateway. Built on HTML5, it allows you to access all your remote connections from a single, centralized web interface—using nothing more than a standard web browser.
This guide provides a comprehensive walkthrough for installing and configuring Apache Guacamole on a Debian 10 (Buster) server. By following these steps, you can set up a powerful and secure portal for all your remote access needs.
What You’ll Need Before You Start
Before diving in, ensure you have the following prerequisites in place:
- A server running a clean installation of Debian 10 (Buster).
- Root or sudo access to the server.
- A basic understanding of the Linux command line.
Step 1: Update Your System and Install Dependencies
First, it’s crucial to update your system’s package list and install all the necessary dependencies for building Guacamole and enabling its various protocol supports.
Open your terminal and run the following commands:
sudo apt update
sudo apt upgrade -y
Next, install the build tools and libraries required by guacd—the core Guacamole proxy. These dependencies enable support for RDP, VNC, SSH, and Telnet.
sudo apt install -y build-essential libcairo2-dev libjpeg62-turbo-dev \
libpng-dev libtool-bin libossp-uuid-dev libavcodec-dev libavutil-dev \
libswscale-dev freerdp2-dev libpango1.0-dev libssh2-1-dev libvncserver-dev \
libtelnet-dev libssl-dev libvorbis-dev libwebp-dev
Step 2: Install Apache Tomcat
Guacamole’s web application runs in a Java servlet container. Apache Tomcat is a popular and robust choice for this purpose. We will install Tomcat 9, which is the standard version available in the Debian 10 repositories.
sudo apt install -y tomcat9 tomcat9-admin tomcat9-user
Once the installation is complete, start and enable the Tomcat service to ensure it launches automatically on boot.
sudo systemctl start tomcat9
sudo systemctl enable tomcat9
Step 3: Download and Build the Guacamole Server (guacd)
Now it’s time to build the heart of the system: guacd. This is the native proxy that translates protocols like RDP and SSH into the Guacamole protocol for the web client.
First, find the latest stable release of Guacamole from the official Apache Guacamole website. Download the source code archive using wget. As of this writing, 1.5.3 is the latest version.
wget https://apache.org/dyn/closer.lua/guacamole/1.5.3/source/guacamole-server-1.5.3.tar.gz
Extract the downloaded archive and navigate into the new directory:
tar -xf guacamole-server-1.5.3.tar.gz
cd guacamole-server-1.5.3/
Next, run the configure script. This script checks for all the necessary dependencies and prepares the build environment. Pay close attention to the output to verify that all the protocols you need are enabled.
./configure --with-systemd-dir=/etc/systemd/system
After running configure, you will see a summary of the installation. A successful configuration will look something like this:
------------------------------------------------
guacamole-server version 1.5.3
------------------------------------------------
Library status:
freerdp2 ............ yes
pango ............... yes
libssh2 ............. yes
libssl .............. yes
libtelnet ........... yes
libVNCServer ........ yes
libvorbis ........... yes
libwebp ............. yes
Protocol support:
RDP ....... yes
SSH ....... yes
Telnet .... yes
VNC ....... yes
...
This confirms that RDP, SSH, Telnet, and VNC support are all successfully enabled.
Now, compile and install the software:
sudo make
sudo make install
Finally, update the system’s cache of shared library links and reload the systemd daemon to recognize the new guacd service.
sudo ldconfig
sudo systemctl daemon-reload
Step 4: Deploy the Guacamole Web Application
With the server-side proxy installed, you can now deploy the web application (.war file) that provides the user interface.
First, create the Guacamole configuration directory:
sudo mkdir /etc/guacamole
Download the web application archive, ensuring it matches the version of guacamole-server you just built.
wget https://apache.org/dyn/closer.lua/guacamole/1.5.3/binary/guacamole-1.5.3.war
Move the .war file to Tomcat’s webapps directory. This will automatically deploy the application.
sudo mv guacamole-1.5.3.war /var/lib/tomcat9/webapps/guacamole.war
Step 5: Configure Guacamole Connections
Guacamole needs configuration files to connect the web application to the guacd proxy and to define users and their available connections.
Create the main properties file:
sudo nano /etc/guacamole/guacamole.properties
Add the following lines. This tells the web app where to find guacd and where to look for authentication details.
# Guacamole server location
guacd-hostname: localhost
guacd-port: 4822
# Authentication provider
auth-provider: net.sourceforge.guacamole.net.auth.xml.XMLAuthenticationProvider
xml-auth-config: /etc/guacamole/user-mapping.xml
Next, create the user-mapping.xml file. This file defines your users, passwords, and the remote desktop connections they are authorized to access.
sudo nano /etc/guacamole/user-mapping.xml
Add the following example configuration. Be sure to replace the placeholder values with your actual usernames, strong passwords, and server details.
<user-mapping>
<!-- A user for an RDP connection -->
<authorize username="rdp-user" password="YourStrongPasswordHere">
<connection name="Windows Server 2022">
<protocol>rdp</protocol>
<param name="hostname">192.168.1.100</param>
<param name="port">3389</param>
<param name="username">windows-username</param>
<param name="password">windows-password</param>
<param name="ignore-cert">true</param>
</connection>
</authorize>
<!-- A user for an SSH connection -->
<authorize username="ssh-user" password="AnotherStrongPassword">
<connection name="Debian SSH Server">
<protocol>ssh</protocol>
<param name="hostname">192.168.1.101</param>
<param name="port">22</param>
<param name="username">linux-user</param>
</connection>
</authorize>
<!-- A user for a VNC connection -->
<authorize username="vnc-user" password="YetAnotherStrongPassword">
<connection name="VNC Desktop">
<protocol>vnc</protocol>
<param name="hostname">192.168.1.102</param>
<param name="port">5901</param>
<param name="password">vnc-server-password</param>
</connection>
</authorize>
</user-mapping>
Step 6: Start the Services and Log In
With all configurations in place, it’s time to start the Guacamole service and restart Tomcat to apply all the changes.
sudo systemctl start guacd
sudo systemctl enable guacd
sudo systemctl restart tomcat9
You can now access your Guacamole instance by opening a web browser and navigating to:
http://your-server-ip:8080/guacamole/
Log in using one of the usernames and passwords you defined in the user-mapping.xml file.
Important Security Recommendations
The setup described above is fully functional but should be hardened for production use.
Set Up SSL/TLS Encryption: The default installation uses unencrypted HTTP. To protect your login credentials and remote session data, you must configure a reverse proxy like Nginx or Apache with a free SSL certificate from Let’s Encrypt. This allows you to access Guacamole securely over HTTPS on the standard port 443.
Use Strong Authentication: The
user-mapping.xmlfile is suitable for small-scale or personal use. For larger environments, it is highly recommended to configure Guacamole to use a database (MySQL, PostgreSQL) or directory service (LDAP, Active Directory) for authentication. This provides more robust user management and scalability.Maintain Your System: Regularly update your Debian server, Tomcat, and Guacamole to protect against security vulnerabilities.
By following this guide, you have successfully deployed a powerful, centralized remote access solution that streamlines connectivity and enhances productivity for you and your team.
Source: https://kifarunix.com/install-apache-guacamole-on-debian-10/
