How To Install Apache Guacamole on AlmaLinux 9

In this tutorial, we will show you how to install Apache Guacamole on AlmaLinux 9. Apache Guacamole stands as one of the most powerful open-source remote desktop gateways available today. This clientless solution enables users to access remote servers through a standard web browser, eliminating the need for additional plugins or client software. For system administrators and IT professionals managing multiple servers, Guacamole offers a streamlined approach to remote access management on Linux systems. This comprehensive guide walks through the complete installation process on AlmaLinux 9, an enterprise-grade Linux distribution that provides excellent stability for hosting services like Guacamole.

Understanding Apache Guacamole

Apache Guacamole functions as a clientless remote desktop gateway, supporting multiple protocols including RDP, VNC, and SSH. Unlike traditional remote access solutions, Guacamole requires no plugins or client software on the user’s device. Everything operates through standard HTML5 and JavaScript, making it accessible from virtually any modern web browser.

The architecture consists of two main components: the guacd server (which handles protocol translation) and the web application (which provides the user interface). These components work together to create a seamless remote access experience across different operating systems and devices.

AlmaLinux 9 provides an ideal foundation for Apache Guacamole due to its stability, long-term support, and compatibility with enterprise environments. The installation process involves several components, each requiring specific configuration to ensure optimal performance and security.

Prerequisites and System Requirements

Before beginning the installation process, ensure your AlmaLinux 9 server meets these minimum requirements:

• A fresh installation of AlmaLinux 9 with root or sudo privileges
• Minimum 2GB RAM (4GB recommended for production environments)
• At least 2 CPU cores (more for multiple concurrent connections)
• Minimum 10GB free disk space
• Active internet connection for package downloads
• Basic Linux command line knowledge
• A domain name pointed to your server (optional but recommended for SSL)
• Open ports in your firewall: 80/443 (HTTP/HTTPS) and 8080 (Tomcat)

The installation will include several components working together:

1. guacd – The Guacamole proxy daemon
2. Tomcat – Java servlet container to host the web application
3. MariaDB – Database backend for authentication and connection management
4. Optional: Nginx – Web server for reverse proxy configuration
5. Optional: Let’s Encrypt – For SSL/TLS certificate management

Properly preparing your system before installation helps avoid common issues and ensures a smooth deployment process.

System Preparation

Updating Your System

Begin by updating your AlmaLinux 9 system to ensure all packages are current before installation. This step is crucial for security and compatibility with newer software.

sudo dnf update -y

This command updates all installed packages to their latest versions. The -y flag automatically confirms the update without requiring manual intervention.

Installing Required Utilities

Next, install basic utilities needed throughout the installation process:

sudo dnf install wget curl tar unzip nano vim -y

These utilities provide essential functionality:

• wget and curl: For downloading files
• tar and unzip: For extracting archived files
• nano and vim: Text editors for configuration file modifications

Configuring Firewall

AlmaLinux 9 uses firewalld for managing network access. Configure it to allow the necessary traffic:

sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --permanent --add-service=https
sudo firewall-cmd --permanent --add-port=8080/tcp
sudo firewall-cmd --reload

These commands:

1. Allow HTTP traffic (port 80)
2. Allow HTTPS traffic (port 443)
3. Open port 8080 for Tomcat
4. Apply the changes by reloading the firewall

Verify the firewall configuration with:

sudo firewall-cmd --list-all

This displays all current firewall rules, allowing you to confirm the correct ports are open.

Installing Dependencies

Development Tools and Libraries

Apache Guacamole requires several dependencies to support various remote access protocols. Install these dependencies using:

sudo dnf install -y epel-release
sudo dnf update -y
sudo dnf install -y gcc make cairo-devel libjpeg-turbo-devel libpng-devel libtool-ltdl-devel libuuid-devel openssl-devel pango-devel libssh2-devel libvncserver-devel libwebsockets-devel freerdp-devel libvorbis-devel libwebp-devel pulseaudio-libs-devel uuid-devel ffmpeg-devel

First, we install the EPEL (Extra Packages for Enterprise Linux) repository, which provides additional packages not found in the default AlmaLinux repositories. After updating the package lists, we install all necessary development libraries.

These packages serve specific purposes:

• Cairo and Pango: Vector graphics libraries for rendering
• libjpeg, libpng, libwebp: Image format support libraries
• libssh2: SSH protocol support
• libvncserver: VNC protocol support
• freerdp: RDP protocol support
• libvorbis and pulseaudio: Audio streaming support
• ffmpeg: Video encoding/decoding support

If you encounter any dependency errors, check for specific error messages that might indicate missing repositories or package conflicts.

Troubleshooting Dependency Issues

If packages are unavailable or dependency conflicts occur, try enabling additional repositories:

sudo dnf install dnf-plugins-core -y
sudo dnf config-manager --set-enabled crb
sudo dnf install epel-release -y
sudo dnf update -y

The Code Ready Builder (CRB) repository contains additional development packages that might be required. After enabling it, retry the dependency installation command.

Installing Java and Tomcat

Java Installation

Apache Guacamole requires Java to run. Install OpenJDK 11, which provides excellent compatibility with Tomcat and Guacamole:

sudo dnf install java-11-openjdk-devel -y

Verify the Java installation and check the version:

java --version

You should see output confirming Java 11 is installed. If multiple Java versions exist on your system, you can select the default using:

sudo alternatives --config java

Tomcat Installation

Install Apache Tomcat 9, which will host the Guacamole web application:

sudo dnf install tomcat -y

Configuring Tomcat Memory Settings

For better performance, especially with multiple concurrent connections, adjust Tomcat’s memory settings:

sudo nano /etc/tomcat/tomcat.conf

Add or modify the following line:

JAVA_OPTS="-Djava.awt.headless=true -Xmx512m -XX:MaxPermSize=256m"

This allocates additional memory to Tomcat. Adjust the values based on your server’s available resources.

Starting and Enabling Tomcat

Start the Tomcat service and enable it to run automatically at system boot:

sudo systemctl start tomcat
sudo systemctl enable tomcat

Verify that Tomcat is running properly:

sudo systemctl status tomcat

The output should show that Tomcat is active and running. You can test the Tomcat installation by visiting http://your_server_ip:8080 in a web browser, which should display the Apache Tomcat default page.

Troubleshooting Tomcat Issues

If Tomcat fails to start, check the logs for detailed error information:

sudo journalctl -u tomcat

Common issues include:

• Port conflicts: Another service might be using port 8080
• Memory problems: Insufficient memory allocated to the JVM
• Permission issues: Incorrect ownership of Tomcat directories

Setting Up MariaDB Database

Installing MariaDB

Guacamole uses a database to store user credentials, connection configurations, and other settings. Install MariaDB:

sudo dnf install mariadb-server -y

Starting and Securing MariaDB

Start the MariaDB service and enable it to run at system startup:

sudo systemctl start mariadb
sudo systemctl enable mariadb

Secure your MariaDB installation using the security script:

sudo mysql_secure_installation

During this process, you’ll:

1. Set a root password (if not already set)
2. Remove anonymous users
3. Disallow root login remotely
4. Remove the test database
5. Reload privilege tables

Answer “Y” to all prompts for maximum security.

Creating Guacamole Database and User

Log in to MariaDB as root:

sudo mysql -u root -p

Enter your MariaDB root password when prompted. Then create the database and user for Guacamole:

CREATE DATABASE guacamole_db;
CREATE USER 'guacamole_user'@'localhost' IDENTIFIED BY 'YourStrongPasswordHere';
GRANT ALL PRIVILEGES ON guacamole_db.* TO 'guacamole_user'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Replace ‘YourStrongPasswordHere’ with a secure password. This creates:

• A database named guacamole_db
• A user named guacamole_user with full privileges on that database
• Restricted access so the user can only connect from localhost

Make sure to save the database name, username, and password as you’ll need them later when configuring Guacamole.

Installing Guacamole Server

Downloading and Extracting Guacamole Server

Download the latest version of Guacamole server source code:

cd /tmp
wget https://dlcdn.apache.org/guacamole/1.5.5/source/guacamole-server-1.5.5.tar.gz
tar -xf guacamole-server-1.5.5.tar.gz
cd guacamole-server-1.5.5/

Configuring and Building Guacamole Server

Configure the build with systemd support:

./configure --with-systemd-dir=/etc/systemd/system/

This command checks your system for all required dependencies and prepares for compilation. Review the output to verify that all required features are enabled. You should see “yes” next to protocols like RDP, SSH, and VNC if the dependencies were installed correctly.

If any required features show “no,” install the missing dependencies and run the configure command again.

Compiling and Installing

Build and install the Guacamole server:

make
sudo make install
sudo ldconfig

These commands:

1. Compile the source code
2. Install the compiled binaries to the appropriate locations
3. Update the system’s shared library cache

The compilation process may take several minutes depending on your server’s performance. If you encounter any errors during compilation, review the output for specific missing dependencies or build issues.

Setting up Guacamole Daemon (guacd)

The Guacamole daemon (guacd) is now installed with systemd integration. Start and enable the service:

sudo systemctl start guacd
sudo systemctl enable guacd

Verify the service is running:

sudo systemctl status guacd

The output should show that guacd is active and running. This daemon is responsible for handling the connections between the web application and remote desktops.

Troubleshooting guacd Issues

If guacd fails to start, check the system logs:

sudo journalctl -u guacd

Common issues include:

• Missing libraries: If certain dependencies weren’t properly installed
• Permission problems: If guacd can’t access required directories
• Port conflicts: If another service is using port 4822

Installing Guacamole Web Application

Downloading the Guacamole Client

Download the Guacamole web application:

cd /tmp
wget https://dlcdn.apache.org/guacamole/1.5.5/binary/guacamole-1.5.5.war

Creating Guacamole Directories

Create the necessary directories for Guacamole configuration:

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

These directories will store:

• extensions: Authentication modules and other plugins
• lib: JDBC connectors and other libraries

Deploying to Tomcat

Deploy the Guacamole web application to Tomcat:

sudo cp guacamole-1.5.5.war /var/lib/tomcat/webapps/guacamole.war

Tomcat automatically detects and deploys WAR files placed in its webapps directory. The deployment process extracts the contents of the WAR file into a new directory.

Creating Symbolic Link

Create a symbolic link to ensure Guacamole finds its configuration files:

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

This ensures that the Guacamole web application can access its configuration files regardless of how Tomcat is configured.

Configuring Guacamole

Setting Up Basic Configuration

Create the main Guacamole configuration file:

sudo nano /etc/guacamole/guacamole.properties

Add the following basic configuration:

# Guacamole proxy configuration
guacd-hostname: localhost
guacd-port: 4822

# Authentication method (initially using simple file-based auth)
user-mapping: /etc/guacamole/user-mapping.xml

This configuration tells the Guacamole web application how to connect to the guacd daemon. The user-mapping property specifies a file for basic authentication.

Setting Up Environment Variables

Tell Tomcat where to find the Guacamole configuration:

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

This environment variable ensures that Tomcat can locate the Guacamole configuration directory.

Setting Up Basic User Authentication

For initial testing, create a simple user mapping file:

sudo nano /etc/guacamole/user-mapping.xml

Add a basic configuration with a user and connection:

<user-mapping>
    <authorize username="admin" password="AdminPassword123">
        <connection name="AlmaLinux Server SSH">
            <protocol>ssh</protocol>
            <param name="hostname">localhost</param>
            <param name="port">22</param>
            <param name="username">your_ssh_username</param>
        </connection>
        <connection name="Example VNC Server">
            <protocol>vnc</protocol>
            <param name="hostname">vnc-server-address</param>
            <param name="port">5900</param>
            <param name="password">vnc-password</param>
        </connection>
    </authorize>
</user-mapping>

Replace placeholders with actual values:

• AdminPassword123: A secure password for the admin user
• your_ssh_username: Your SSH username on the server
• vnc-server-address: Address of a VNC server you want to connect to
• vnc-password: Password for the VNC server

This basic configuration is useful for initial testing, but for production environments, you should use database authentication instead.

Database Authentication Setup

Downloading Database Extension

For a more robust authentication system, configure database authentication:

cd /tmp
wget https://dlcdn.apache.org/guacamole/1.5.5/binary/guacamole-auth-jdbc-1.5.5.tar.gz
tar -xf guacamole-auth-jdbc-1.5.5.tar.gz

Installing MySQL Connector

Download and install the MySQL Connector for Java:

wget https://dev.mysql.com/get/Downloads/Connector-J/mysql-connector-j-8.0.32.tar.gz
tar -xf mysql-connector-j-8.0.32.tar.gz
sudo cp mysql-connector-j-8.0.32/mysql-connector-j-8.0.32.jar /etc/guacamole/lib/

Installing JDBC Authentication Extension

Copy the MySQL authentication extension to the Guacamole extensions directory:

sudo cp guacamole-auth-jdbc-1.5.5/mysql/guacamole-auth-jdbc-mysql-1.5.5.jar /etc/guacamole/extensions/

Initializing the Database Schema

Import the database schema for Guacamole:

cd guacamole-auth-jdbc-1.5.5/mysql/schema
cat *.sql | sudo mysql -u guacamole_user -p guacamole_db

Enter the password you created for the guacamole_user when prompted. This imports several SQL scripts that create the necessary tables for Guacamole.

Updating Guacamole Configuration

Update the guacamole.properties file to use database authentication:

sudo nano /etc/guacamole/guacamole.properties

Replace the existing content with:

# Guacamole proxy configuration
guacd-hostname: localhost
guacd-port: 4822

# MySQL properties
mysql-hostname: localhost
mysql-port: 3306
mysql-database: guacamole_db
mysql-username: guacamole_user
mysql-password: YourStrongPasswordHere

Replace YourStrongPasswordHere with the actual password you created for the guacamole_user.

Restarting Tomcat

After making these changes, restart Tomcat to apply them:

sudo systemctl restart tomcat

This configuration replaces the simple XML-based authentication with a database-backed system that offers more flexibility and security.

Setting Up Nginx as Reverse Proxy

Installing Nginx

While Tomcat can serve the Guacamole web application directly, using Nginx as a reverse proxy offers better performance, security, and flexibility:

sudo dnf install nginx -y

Configuring Nginx

Create a new Nginx configuration file for Guacamole:

sudo nano /etc/nginx/conf.d/guacamole.conf

Add the following configuration:

server {
    listen 80;
    server_name your-domain.com;

    access_log /var/log/nginx/guacamole_access.log;
    error_log /var/log/nginx/guacamole_error.log;

    location / {
        proxy_pass http://localhost:8080/guacamole/;
        proxy_buffering off;
        proxy_http_version 1.1;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $http_connection;
        proxy_set_header Host $host;
        client_max_body_size 0;
    }
}

Replace your-domain.com with your actual domain name or server IP address.

This configuration:

• Listens on port 80 (HTTP)
• Routes all requests to the Guacamole web application
• Handles WebSocket connections correctly
• Configures logging for troubleshooting

Testing and Starting Nginx

Check the configuration syntax for errors:

sudo nginx -t

If the test passes, start and enable Nginx:

sudo systemctl start nginx
sudo systemctl enable nginx

Now you can access Guacamole by visiting http://your-domain.com or http://your-server-ip. The reverse proxy configuration removes the need to specify the /guacamole path.

Securing with SSL/TLS

Installing Certbot

For production environments, secure your Guacamole installation with SSL/TLS using Let’s Encrypt:

sudo dnf install certbot python3-certbot-nginx -y

Obtaining SSL Certificate

If you have a domain name pointed to your server, obtain a certificate:

sudo certbot --nginx -d your-domain.com

Follow the interactive prompts to complete the certificate issuance process. Certbot automatically modifies your Nginx configuration to use HTTPS.

Testing SSL Configuration

Verify that the SSL configuration is working:

sudo nginx -t
sudo systemctl reload nginx

Now you can access Guacamole securely via https://your-domain.com. Your browser should show a secure connection with a valid SSL certificate.

Automatic Certificate Renewal

Let’s Encrypt certificates expire after 90 days. Set up automatic renewal:

echo "0 0,12 * * * root python -c 'import random; import time; time.sleep(random.random() * 3600)' && certbot renew -q" | sudo tee -a /etc/crontab > /dev/null

This creates a cron job that attempts renewal twice daily (with a random delay to distribute load on Let’s Encrypt servers).

Additional Security Considerations

Restricting File Permissions

Secure your configuration files:

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

Setting Up Fail2Ban

Install Fail2Ban to protect against brute force attacks:

sudo dnf install fail2ban -y
sudo systemctl enable fail2ban
sudo systemctl start fail2ban

Create a Fail2Ban filter for Guacamole:

sudo nano /etc/fail2ban/filter.d/guacamole.conf

Add the following content:

[Definition]
failregex = ^.*WARNING.*Authentication attempt from .* for user "[^"]*" failed\.
ignoreregex =

Create a jail configuration:

sudo nano /etc/fail2ban/jail.d/guacamole.conf

Add:

[guacamole]
enabled = true
port = http,https
filter = guacamole
logpath = /var/log/tomcat/catalina.out
maxretry = 3
bantime = 3600

Restart Fail2Ban:

sudo systemctl restart fail2ban

This configuration blocks IP addresses that fail authentication multiple times, adding another layer of security to your installation.

Finalizing and Testing

Restarting All Services

Ensure all components are running with the latest configuration:

sudo systemctl restart guacd
sudo systemctl restart tomcat
sudo systemctl restart nginx

Accessing Guacamole

Access your Guacamole installation at:

• https://your-domain.com (if using Nginx with SSL)
• http://your-server-ip:8080/guacamole (if using direct Tomcat access)

Log in with the credentials you configured:

• For basic XML authentication: Use admin/AdminPassword123
• For database authentication: The default credentials are guacadmin/guacadmin

Initial Setup

When using database authentication, after your first login with the default credentials, immediately:

1. Create a new administrator account
2. Log out and log in with the new account
3. Delete the default guacadmin account

Testing Connections

Test your remote connections to ensure everything is working correctly. If you encounter issues, check the logs:

sudo journalctl -u guacd
sudo journalctl -u tomcat
sudo cat /var/log/nginx/guacamole_error.log

Troubleshooting Common Issues

Connection Fails to Establish

If you can’t establish remote connections:

• Verify that guacd is running: sudo systemctl status guacd
• Check that required protocols (SSH, VNC, RDP) are properly installed
• Ensure the remote host is accessible (test with direct SSH/VNC/RDP clients)
• Review firewall settings on both the Guacamole server and target systems

Login Issues

If you can’t log in to Guacamole:

• For XML authentication: Verify the user-mapping.xml file syntax
• For database authentication: Check the database connection parameters
• Ensure Tomcat can access the guacamole.properties file
• Check Tomcat logs for authentication-related errors

Performance Problems

If you experience slow performance:

• Increase Tomcat’s memory allocation in tomcat.conf
• Optimize remote desktop protocol settings (reduce color depth, disable audio)
• Consider upgrading server resources for multiple concurrent users

Congratulations! You have successfully installed Apache Guacamole. Thanks for using this tutorial for installing the Apache Guacamole remote desktop gateway on AlmaLinux 9 system. For additional help or useful information, we recommend you check the official Apache website.