Home » Blog » Install Guacamole on Ubuntu 22.04

Information

Install Guacamole on Ubuntu 22.04

Benhcmark Administrator

11/11/2025

2 Views 0

SaveSavedRemoved 0

The Ultimate Guide to Installing Apache Guacamole on Ubuntu 22.04

In today’s interconnected world, seamless and secure remote access to your desktops is no longer a luxury—it’s a necessity. Apache Guacamole is a powerful, open-source solution that transforms this need into a simple reality. It’s a clientless remote desktop gateway, meaning you can access your machines from any modern web browser, with no special software or plugins required.

This comprehensive guide will walk you through every step of installing and configuring Apache Guacamole on an Ubuntu 22.04 server. By the end, you will have a fully functional, secure, and self-hosted remote access portal.

What is Apache Guacamole?

Guacamole provides centralized access to your remote desktops using standard protocols like VNC, RDP, and SSH. It acts as a middleman: it connects to your target machines on your behalf and presents the display as a real-time video stream within your web browser. This architecture offers significant security and convenience benefits, allowing you to manage access from a single, secure point.

Prerequisites

Before we begin, ensure you have the following:

• An Ubuntu 22.04 LTS server.
• Root or sudo privileges.
• A basic understanding of the Linux command line.
• (Optional but highly recommended) A registered domain name to secure your Guacamole instance with SSL/TLS.

Step 1: Update Your System and Install Dependencies

First, let’s prepare the server by updating the package lists and installing all the build tools and libraries required to compile Guacamole Server (guacd) from source.

Open your terminal and run the following commands:

sudo apt update && sudo apt upgrade -y
sudo apt install -y build-essential libcairo2-dev libjpeg-turbo8-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 libwebsockets-dev libpulse-dev

These packages provide the necessary components for supporting various remote desktop protocols and for building the Guacamole daemon.

Step 2: Install and Configure Tomcat

Guacamole’s web application is a Java .war file, which requires a servlet container to run. Apache Tomcat is a popular and robust choice. We will install Tomcat 9.

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

Once installed, you can verify that the Tomcat service is running:

sudo systemctl status tomcat9

You should see an active (running) status. If not, start and enable it:

sudo systemctl start tomcat9
sudo systemctl enable tomcat9

Step 3: Set Up a MariaDB Database

While Guacamole can store user data in a simple XML file, using a dedicated database like MariaDB (a fork of MySQL) is far more scalable and secure. We’ll create a database and a dedicated user for Guacamole.

1. Install MariaDB:

   sudo apt install -y mariadb-server
   

2. Run the secure installation script. This script will help you set a root password, remove anonymous users, and enhance security.

   sudo mysql_secure_installation
   

   Follow the on-screen prompts. It is highly recommended to set a strong root password and answer “Y” (yes) to all subsequent questions.

3. Create the Guacamole database and user: Log in to the MariaDB shell as the root user.

   sudo mysql -u root -p
   

   Now, execute the following SQL commands. Be sure to replace 'your-strong-password' with a secure password of your own.

   CREATE DATABASE guacamole_db;
   CREATE USER 'guacamole_user'@'localhost' IDENTIFIED BY 'your-strong-password';
   GRANT SELECT,INSERT,UPDATE,DELETE ON guacamole_db.* TO 'guacamole_user'@'localhost';
   FLUSH PRIVILEGES;
   EXIT;
   

   This creates a database named guacamole_db, a user guacamole_user, and grants it the necessary permissions only on that database.

Step 4: Download and Compile Guacamole Server (guacd)

The Guacamole Server is the backend daemon (guacd) that connects to your remote machines. We need to compile it from source.

1. Download the latest stable source code from the Apache Guacamole website. You can find the latest version number on their releases page.

   wget https://apache.org/dyn/closer.lua/guacamole/1.5.4/source/guacamole-server-1.5.4.tar.gz
   

2. Extract the archive and navigate into the directory:

   tar -xvf guacamole-server-1.5.4.tar.gz
   cd guacamole-server-1.5.4/
   

3. Run the configure script, then compile and install:

   ./configure --with-systemd-dir=/etc/systemd/system
   make
   sudo make install
   

   The --with-systemd-dir flag ensures that the systemd service file for guacd is created in the correct location.

4. Update the library cache and start the daemon:
   bash
sudo ldconfig
sudo systemctl daemon-reload
sudo systemctl start guacd
sudo systemctl enable guacd

   Verify its status to ensure it’s running correctly: sudo systemctl status guacd.

Step 5: Install the Guacamole Client and Database Connector

Now we’ll install the web application (the client) and connect it to our MariaDB database.

1. Create the Guacamole configuration directory:

   sudo mkdir /etc/guacamole
   

2. Download the Guacamole Client .war file. This should match the version of the server you just compiled.

   wget https://apache.org/dyn/closer.lua/guacamole/1.5.4/binary/guacamole-1.5.4.war
   

3. Move the .war file to the Tomcat webapps directory:

   sudo mv guacamole-1.5.4.war /var/lib/tomcat9/webapps/guacamole.war
   

   Renaming it to guacamole.war makes the URL cleaner (e.g., http://your-ip/guacamole).

4. Download the JDBC database connector for MariaDB/MySQL. This allows Guacamole to communicate with the database.

   wget https://downloads.mysql.com/archives/get/p/3/file/mysql-connector-j-8.0.33.tar.gz
   tar -xvf mysql-connector-j-8.0.33.tar.gz
   sudo cp mysql-connector-j-8.0.33/mysql-connector-j-8.0.33.jar /etc/guacamole/
   

5. Create symbolic links so Guacamole can find the connector and its extensions.
   bash
sudo mkdir /usr/share/tomcat9/.guacamole
sudo ln -s /etc/guacamole/mysql-connector-j-8.0.33.jar /usr/share/tomcat9/.guacamole/


Step 6: Configure Guacamole and Import Schema

This is the final configuration step where we tell Guacamole how to connect to guacd and our database.

1. Create the guacamole.properties configuration file:

   sudo nano /etc/guacamole/guacamole.properties
   

   Paste the following content into the file. Remember to replace 'your-strong-password' with the database password you created earlier.

   # Guacamole Server Connection
   guacd-hostname: localhost
   guacd-port: 4822
   
   # Database Authentication
   mysql-hostname: localhost
   mysql-port: 3306
   mysql-database: guacamole_db
   mysql-username: guacamole_user
   mysql-password: your-strong-password
   

2. Download the database authentication extension and place it in the correct directory.

   wget https://apache.org/dyn/closer.lua/guacamole/1.5.4/binary/guacamole-auth-jdbc-1.5.4.tar.gz
   tar -xvf guacamole-auth-jdbc-1.5.4.tar.gz
   sudo cp guacamole-auth-jdbc-1.5.4/mysql/guacamole-auth-jdbc-mysql-1.5.4.jar /etc/guacamole/extensions/
   

3. Import the database schema. The authentication extension comes with an SQL script to create the necessary tables in your database.

   cat guacamole-auth-jdbc-1.5.4/mysql/schema/*.sql | sudo mysql -u root -p guacamole_db
   

   You will be prompted for your MariaDB root password.

4. Restart Tomcat and guacd to apply all changes.
   bash
sudo systemctl restart tomcat9
sudo systemctl restart guacd


You should now be able to access your Guacamole instance at http://your-server-ip:8080/guacamole. The default login is guacadmin for both the username and password. Change this immediately after your first login!

Security Tip: Set Up a Reverse Proxy with Nginx and SSL

Exposing Tomcat directly to the internet is not recommended. A reverse proxy like Nginx adds a crucial layer of security and allows you to use a clean domain name and enable HTTPS.

1. Install Nginx:

   sudo apt install -y nginx
   

2. Create an Nginx server block configuration file:

   sudo nano /etc/nginx/sites-available/guacamole
   

   Paste the following configuration. Replace guacamole.yourdomain.com with your actual domain.

   server {
       listen 80;
       server_name guacamole.yourdomain.com;
   location / {
       return 301 https://$host$request_uri;
   }
   }
   server {
   
   listen 443 ssl;
   
   server_name guacamole.yourdomain.com;
   # SSL Configuration - This is a placeholder
   # Use Certbot to generate these lines automatically
   # ssl_certificate /etc/letsencrypt/live/guacamole.yourdomain.com/fullchain.pem;
   # ssl_certificate_key /etc/letsencrypt/live/guacamole.yourdomain.com/privkey.pem;
   
   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;
       access_log off;
   }
   }
   
   

3. Enable the site:

   sudo ln -s /etc/nginx/sites-available/guacamole /etc/nginx/sites-enabled/
   

4. Install Certbot and obtain a free SSL certificate from Let’s Encrypt:

   sudo apt install -y certbot python3-certbot-nginx
   sudo certbot --nginx -d guacamole.yourdomain.com
   

   Certbot will automatically edit your Nginx file to include the correct SSL certificate paths and set up auto-renewal.

5. Restart Nginx:
   bash
sudo systemctl restart nginx


You can now access your secure Guacamole portal at https://guacamole.yourdomain.com.

Conclusion

Congratulations! You have successfully deployed a powerful, secure, and self-hosted remote access gateway. With Apache Guacamole, you can now manage and access all your servers and desktops from a single, convenient web interface. Your next steps are to log in, change the default administrator password, and start adding new users and connections for your RDP, VNC, or SSH machines.

Source: https://kifarunix.com/install-apache-guacamole-on-ubuntu-22-04/