How To Install Apache Guacamole on Debian 12

In this tutorial, we will show you how to install Apache Guacamole on Debian 12. Apache Guacamole is a powerful clientless remote desktop gateway that enables users to access their machines through a standard web browser without requiring any plugins or client software. This HTML5-based solution supports multiple protocols including RDP, VNC, SSH, and Telnet, making it an ideal choice for system administrators who need to manage various systems remotely.

In this comprehensive guide, we’ll walk through the complete installation and configuration process of Apache Guacamole on Debian 12, from system preparation to testing your setup.

Prerequisites

Before beginning the installation process, ensure your system meets these requirements:

Hardware Requirements:

A Debian 12 system (physical or virtual)
Minimum 2GB RAM recommended for smooth operation
At least 10GB of available disk space

Software Requirements:

Debian 12 with root or sudo access
Basic Linux command line knowledge
Active internet connection for downloading packages

Setting up Apache Guacamole requires several components working together, including the Guacamole server (guacd), Tomcat servlet container, and the Guacamole client web application. Let’s start by preparing our system.

System Preparation

The first step is updating your system and installing the necessary dependencies and build tools required for compiling Guacamole from source.

Update System Packages

Start by refreshing your package lists and upgrading existing packages:

sudo apt update
sudo apt upgrade -y

Install Required Build Tools and Dependencies

Guacamole server requires several development libraries to support various protocols:

sudo 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

These packages provide support for various protocols and functionalities:

freerdp2-dev: Enables RDP protocol support
libssh2-1-dev: Provides SSH protocol functionality
libvncserver-dev: Enables VNC connections
libtelnet-dev: Supports Telnet protocol

With all dependencies installed, we can now proceed to install the Guacamole server component.

Installing Guacamole Server

The Guacamole server (guacd) is the core component that handles connections to remote desktops. We’ll need to build it from source.

Download Guacamole Source Code

First, let’s download the latest stable release of Guacamole (1.5.4 as of this writing):

VER=1.5.4
wget https://downloads.apache.org/guacamole/$VER/source/guacamole-server-$VER.tar.gz

Extract the downloaded archive:

tar xzf guacamole-server-$VER.tar.gz

Compile and Install Guacamole Server

Navigate to the extracted directory and run the configuration script:

cd guacamole-server-$VER
./configure --with-systemd-dir=/etc/systemd/system/

The configuration script checks if your system has all required dependencies and prepares for the build process. You should see output showing which protocols are supported (RDP, SSH, VNC, etc.).

Next, compile and install the server:

make
sudo make install

Update the shared library cache:

sudo ldconfig

Set Up Guacamole Daemon Service

Create a dedicated system user for running the guacd service:

sudo useradd -M -d /var/lib/guacd/ -r -s /sbin/nologin -c "Guacd User" guacd
sudo mkdir -p /var/lib/guacd
sudo chown -R guacd: /var/lib/guacd

Modify the systemd service file to use the guacd user instead of the default daemon user:

sudo sed -i 's/daemon/guacd/' /etc/systemd/system/guacd.service

Reload systemd, then start and enable the guacd service:

sudo systemctl daemon-reload
sudo systemctl start guacd
sudo systemctl enable guacd

Verify the service is running correctly:

sudo systemctl status guacd

Installing Tomcat Servlet

Guacamole’s web application requires a servlet container to run. Tomcat 9 is recommended for Debian 12, as Tomcat 10 may have compatibility issues with Guacamole.

Install Tomcat 9

Install Tomcat 9 and its related packages:

sudo apt install -y tomcat9 tomcat9-admin tomcat9-common tomcat9-user

Configure Tomcat

Create directories for Guacamole configuration files:

sudo mkdir -p /etc/guacamole/{extensions,lib}

Set the GUACAMOLE_HOME environment variable:

echo "GUACAMOLE_HOME=/etc/guacamole" | sudo tee -a /etc/default/tomcat9

Start and enable the Tomcat service:

sudo systemctl start tomcat9
sudo systemctl enable tomcat9

Installing Guacamole Client

The Guacamole client is the web application that provides the user interface.

Download Guacamole Client WAR File

Download the client web application:

sudo wget https://downloads.apache.org/guacamole/$VER/binary/guacamole-$VER.war -O /etc/guacamole/guacamole.war

Deploy Guacamole Client to Tomcat

Create a symbolic link to deploy the Guacamole web application:

sudo ln -s /etc/guacamole/guacamole.war /var/lib/tomcat9/webapps/

Link the Guacamole configuration directory:

sudo ln -s /etc/guacamole /usr/share/tomcat9/.guacamole

Configuring Guacamole

Now let’s configure Guacamole to connect to the guacd daemon and set up authentication.

Create Main Configuration Files

Create the guacamole.properties configuration file:

sudo tee /etc/guacamole/guacamole.properties > /dev/null << 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

This configuration specifies:

The guacd daemon runs on localhost (127.0.0.1) port 4822
User authentication is stored in user-mapping.xml
Basic file authentication is used

Set Up User Authentication

Generate a password hash for your admin user:

ADMIN_PASSWORD=$(echo -n "YourSecurePassword" | openssl md5 | awk '{print $2}')

Create the user-mapping.xml file with connection configurations:

sudo tee /etc/guacamole/user-mapping.xml > /dev/null << EOL
<user-mapping>
    <authorize
        username="admin"
        password="$ADMIN_PASSWORD"
        encoding="md5">
        
        <!-- Example RDP connection -->
        <connection name="Windows Server">
            <protocol>rdp</protocol>
            <param name="hostname">windows-server.example.com</param>
            <param name="port">3389</param>
            <param name="username">administrator</param>
            <param name="password">WindowsPassword</param>
            <param name="security">nla</param>
            <param name="ignore-cert">true</param>
        </connection>
        
        <!-- Example SSH connection -->
        <connection name="Linux Server">
            <protocol>ssh</protocol>
            <param name="hostname">linux-server.example.com</param>
            <param name="port">22</param>
            <param name="username">admin</param>
            <param name="password">LinuxPassword</param>
        </connection>
    </authorize>
</user-mapping>
EOL

Set proper permissions for security:

sudo chmod 600 /etc/guacamole/user-mapping.xml
sudo chmod 600 /etc/guacamole/guacamole.properties

Restart both services to apply changes:

sudo systemctl restart tomcat9 guacd

Database Authentication (Optional)

For production environments, database authentication provides better security and flexibility than file-based authentication. Here’s how to set up PostgreSQL authentication.

Install PostgreSQL

Install PostgreSQL and required packages:

sudo apt install -y postgresql postgresql-contrib

Create Guacamole Database and User

Create a database and user for Guacamole:

sudo -u postgres psql -c "CREATE USER guacamole_user WITH PASSWORD 'YourSecurePassword';"
sudo -u postgres psql -c "CREATE DATABASE guacamole_db;"
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE guacamole_db TO guacamole_user;"

Download and Install Database Extension

Download the database extension and PostgreSQL driver:

sudo wget https://downloads.apache.org/guacamole/$VER/binary/guacamole-auth-jdbc-$VER.tar.gz
sudo wget https://jdbc.postgresql.org/download/postgresql-42.5.1.jar -O /etc/guacamole/lib/postgresql-42.5.1.jar

Extract and install the extension:

sudo tar -xzf guacamole-auth-jdbc-$VER.tar.gz
sudo cp guacamole-auth-jdbc-$VER/postgresql/guacamole-auth-jdbc-postgresql-$VER.jar /etc/guacamole/extensions/

Initialize Database Schema

Run the SQL scripts to set up the schema:

sudo -u postgres psql -d guacamole_db -f guacamole-auth-jdbc-$VER/postgresql/schema/*.sql

Update Guacamole Configuration

Modify guacamole.properties for database authentication:

sudo tee /etc/guacamole/guacamole.properties > /dev/null << EOL
guacd-hostname: 127.0.0.1
guacd-port: 4822

# PostgreSQL configuration
postgresql-hostname: localhost
postgresql-port: 5432
postgresql-database: guacamole_db
postgresql-username: guacamole_user
postgresql-password: YourSecurePassword

# Authentication providers
auth-provider: net.sourceforge.guacamole.net.auth.postgresql.PostgreSQLAuthenticationProvider
EOL

Restart services:

sudo systemctl restart tomcat9 guacd

Securing Guacamole

Enhance security with HTTPS and a reverse proxy.

Set Up HTTPS with Let’s Encrypt

Install Certbot and obtain an SSL certificate:

sudo apt install -y certbot python3-certbot-apache
sudo certbot --apache -d guacamole.example.com

Configure Apache as Reverse Proxy

Install and configure Apache:

sudo apt install -y apache2
sudo a2enmod proxy proxy_http proxy_wstunnel ssl headers

Create a virtual host for Guacamole:

sudo tee /etc/apache2/sites-available/guacamole.conf > /dev/null << EOL
<VirtualHost *:443>
    ServerName guacamole.example.com
    
    SSLEngine on
    SSLCertificateFile /etc/letsencrypt/live/guacamole.example.com/fullchain.pem
    SSLCertificateKeyFile /etc/letsencrypt/live/guacamole.example.com/privkey.pem
    
    ProxyPreserveHost On
    ProxyRequests Off
    
    # WebSocket support
    RewriteEngine On
    RewriteCond %{HTTP:Upgrade} websocket [NC]
    RewriteCond %{HTTP:Connection} upgrade [NC]
    RewriteRule ^/?(.*) ws://localhost:8080/$1 [P,L]
    
    # Standard proxy
    ProxyPass / http://localhost:8080/
    ProxyPassReverse / http://localhost:8080/
    
    # Security headers
    Header always set X-Frame-Options "SAMEORIGIN"
    Header always set X-Content-Type-Options "nosniff"
    Header always set X-XSS-Protection "1; mode=block"
    Header always set Strict-Transport-Security "max-age=31536000; includeSubDomains"
</VirtualHost>
EOL

Enable the configuration:

sudo a2ensite guacamole
sudo a2dissite 000-default
sudo systemctl restart apache2

Testing and Validation

Access your Guacamole instance through a web browser:

If using a reverse proxy: https://guacamole.example.com/
If accessing directly: http://your-server-ip:8080/guacamole/

Install Apache Guacamole on Debian 12

Troubleshooting Common Issues

If you encounter problems:

Connection Refused:

Verify the remote system is accessible
Check firewall settings on both server and client

RDP Connection Issues:

Ensure freerdp2-dev is properly installed
Check RDP security settings on the Windows server

Black Screen:

Verify guacd is running: sudo systemctl status guacd
Check logs: sudo journalctl -u guacd

Congratulations! You have successfully installed Apache Guacamole. Thanks for using this tutorial to install the latest version of the Apache Guacamole remote desktop gateway on Debian 12 “Bookworm”. For additional help or useful information, we recommend you check the official Apache website.

VPS Manage Service Offer

If you don’t have time to do all of this stuff, or if this is not your area of expertise, we offer a service to do “VPS Manage Service Offer”, starting from $10 (Paypal payment). Please contact us to get the best deal!