How to install Guacamole remote desktop tool on Ubuntu 22.04

Estimated reading: 10 minutes 54 views

This guide covers all the steps required to install Guacamole Remote Desktop on Ubuntu 22.04

In case you never got the Memo, Ubuntu 22.04 LTS was released as the new Long Term Release. It comes will improvements and today we are going to take advantage of this new broom in the house to sweep our access operations clean. As we know, the convenience of having one place to access your servers is something most administrators can consider having in their main course meal every single day. In order to satiate this need, this guide goes into the details of setting up one such platform. By the end of this guide, we should have set up a working Apache Guacamole Server on the new Ubuntu release that can be leveraged to provide one place to access all of your servers. Whether they are Windows or Linux, Apache Guacamole is here for you.

Guacamole is separated into two pieces: guacamole-server, which provides the guacd proxy and related libraries, and guacamole-client, which provides the client to be served by your servlet container. In most cases, the only source you will need to build is a guacamole-server, and downloading the latest guacamole.war from the project website will be sufficient to provide the client.

1. Server Preparation

Apache Guacamole has many dependencies and we are going to deal with most of them in this step. Let us get ahead and install each and every one of the dependencies that our Guacamole server will require to breathe and live. Get them all installed as follows:

apt update
apt install -y gcc nano vim curl wget g++ libcairo2-dev libjpeg-turbo8-dev libpng-dev libtool-bin libossp-uuid-dev

Install other dependencies:

apt install -y libavcodec-dev  libavformat-dev libavutil-dev libswscale-dev build-essential libpango1.0-dev libssh2-1-dev libvncserver-dev libtelnet-dev libpulse-dev libvorbis-dev libwebp-dev

Install FreeRDP2

We are going to install the FreeRDP2 version hosted in the Remmina PPA as follows:

apt update
apt install freerdp2-dev freerdp2-x11 -y

That should complete the packages and libraries Guacamole demands of us and we should now get to the business of installing it.

2. Get Apache Tomcat Installed

In this step, we are going to install the Apache Tomcat Java servlet container which will run the Guacamole Java war file and thus serves the Guacamole Java client. Since it is in Java, we will have to get Java installed first:

apt install default-jdk

Once it is installed, you can check the version installed

$ java --version

Install Apache Tomcat

Apache Tomcat exists in the default Ubuntu 22.04 repositories and can be installed using the command:

apt install tomcat9 tomcat9-admin tomcat9-common tomcat9-user

Once installed, ensure the service has been started and enabled:

systemctl enable --now tomcat9

And Tomcat should be running with a dash of happiness like the below:

$ systemctl status tomcat9

Tomcat listens on port 8080 by default and as you can guess, we need to allow access to the application remotely by allowing the port on the firewall. This is as simple as a one-line command as shown below:

ufw allow 8080/tcp

3. Build the Guacamole Server from source

Guacamole-server contains all the native, server-side components required by Guacamole to connect to remote desktops. It provides a common C library, libguac, which all other native components depend on, as well as separate libraries for each supported protocol, and a proxy daemon, guacd, the heart of Guacamole.

Download the Latest stable version of guacamole-server

cd ~/

Extract the source tarball after download

tar xzf ~/guacamole-server-1.5.4.tar.gz

Change into the guacamole server source code directory;

cd ~/guacamole-server-1.5.4/

Then execute the configure script to check if any required dependency is missing and to adapt the Guacamole server to your system.

./configure --disable-guacenc --with-init-dir=/etc/init.d

The command above will lead to a long trickle of output. When it ends, you should see the following output which should have a yes on the following: RDP, SSH, Telnet, and VNC.

After that, simply run the make command as advised on the last message


Give it some time while it does its thing. Once it finishes, install the guacamole server as follows

make install

To finish it all, run the ldconfig command to create the necessary links and cache to the most recent shared libraries found in the guacamole server directory.

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

Create guacd.conf configuration file:

$ nano /etc/guacamole/guacd.conf
pid_file = /var/run/
#log_level = debug

#bind_host = localhost
bind_host =
bind_port = 4822

#server_certificate = /etc/ssl/certs/guacd.crt
#server_key = /etc/ssl/private/guacd.key

Refresh systemd for it to find the guacd (Guacamole proxy daemon) service installed in /etc/init.d/ directory.

systemctl daemon-reload

Once reloaded, start and enable the guacd service.

systemctl restart guacd
systemctl enable guacd

And to have that mood put on turbo lift, check its status.

$ systemctl status guacd

4. Install the Guacamole Web Application

There are two critical files involved in the deployment of Guacamole: guacamole.war, which is the file containing the web application, and, the main configuration file for Guacamole. The recommend way to set up Guacamole involves placing these files in standard locations, and then creating symbolic links to them so that Tomcat can find them.

guacamole-client contains all Java and Maven components of Guacamole (guacamole, guacamole-common, guacamole-ext, and guacamole-common-js). These components ultimately make up the web application that will serve the HTML5 Guacamole client to users that connect to your server. This web application will connect to guacd, part of guacamole-server, on behalf of connected users in order to serve them any remote desktop they are authorized to access.

Install Guacamole Client

The Guacamole client is available as a binary. To install it, just pull it from the Guacamole binaries downloads page as shown below, copy it to /etc/guacamole/ directory and rename it at the same time.

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

5. Configure Guacamole Server

After the installation of the Guacamole server daemon, you need to define how to Guacamole client will connect to the Guacamole server (guacd) under the /etc/guacamole/ configuration file. Within this configuration, you need to simply define Guacamole server hostname, port, and authentication provider.

GUACAMOLE_HOME is the name given to Guacamole’s configuration directory, which is located at /etc/guacamole by default. All configuration files, extensions, etc. reside within this directory.

Create GUACAMOLE_HOME environment variable

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

Create /etc/guacamole/ config file and populate it as shown below:

$ nano /etc/guacamole/
guacd-hostname: localhost
guacd-port:     4822

6. Setup Guacamole Database Authentication

Guacamole’s default authentication method reads all users and connections from a single file called user-mapping.xml. However, this method should only be used for testing purposes. For production-ready, we need to set up database authentication.

Ensure MySQL or MariaDB has been installed on your system. That can be achieved by following the below guides:

Once installed, download the  MySQL Connector/J (Java Connector). Export the latest available version for the page:


Now download the archive using the command:

cd ~/

Extract the file and copy it to the /etc/guacamole/lib/ directory:

tar -xf mysql-connector-j-8.3.0.tar.gz
cp mysql-connector-j-8.3.0/mysql-connector-j-8.3.0.jar /etc/guacamole/lib/

For MariaDB specific check available connectors

You also need the JDBC auth plugin for Guacamole. Export the latest version available:


Then download it with the command:


Extract it and move it to /etc/guacamole/extensions/ as shown:

tar -xf guacamole-auth-jdbc-1.5.4.tar.gz
mv guacamole-auth-jdbc-1.5.4/mysql/guacamole-auth-jdbc-mysql-1.5.4.jar /etc/guacamole/extensions/

Now login to the database server using the root user and password:

mysql -u root -p

Once connected, create a database and user for Guacamole:

CREATE DATABASE guacamole_db;
CREATE USER 'guacamole_user'@'localhost' IDENTIFIED BY 'Greeen@1234';
GRANT SELECT,INSERT,UPDATE,DELETE ON guacamole_db.* TO 'guacamole_user'@'localhost';

Switch to the extracted JDBC plugin path:

cd guacamole-auth-jdbc-1.5.4/mysql/schema

Import the SQL schemas:

cat *.sql | mysql -u root -p guacamole_db

Provide the password for the root user to import the schemas. Next, modify the properties of Guacamole

nano /etc/guacamole/

In the file, add these lines for the created database:

###MySQL properties
mysql-port: 3306
mysql-database: guacamole_db
mysql-username: guacamole_user
mysql-password: Greeen@1234

Save the file and restart all the services:

systemctl restart tomcat9 guacd

7. Accessing Guacamole Web Interface

Thus far, we have set up everything well and we should therefore be ready to access the application we have been toiling to bring up. To access Guacamole’s web interface, simply point your browser to http://ip-or-domain-name:8080/guacamole and you should be greeted with a login screen as shown below:

Login using guacadmin as the username and guacadmin as the password

Once connected, you can create a new admin and delete the default one for security purposes. To do that, click on the guacadmin user drop-down arrow and go to Settings ->User->New User.

Ensure all the required permissions have been assigned then click Create. Once the user has been created, log out and log in using the new admin user.

You can then navigate to the setting and delete the old admin user.

Create SSH connection

By default, the user does not have SSH connections. We can create a new connection by clicking on Settings ->Connection->New Connection

You need to provide the name for the connection, then the IP/hostname and port for the server, username and password under the Parameters->Network.

If you have SSH key authentication configured on the remote hosts, consider adding the below lines to the SSH config to avoid the error “ssh handshake failed.”

$ nano /etc/ssh/sshd_config
HostKeyAlgorithms +ssh-rsa
PubkeyAcceptedKeyTypes +ssh-rsa

Restart the service:

systemctl restart sshd

Once created, you can test the connection by navigating to Home(drop-down on username)

Simply click on the one you would wish to connect to and you will be prompted with a username and password whether via SSH or RDP depending on the Operating System.

Ending Remarks

Get your environment organized and easy to use even for new users in your environment by taking advantage of Apache Guacamole to use its cool features as you will see after installation. Check it out and leverage on its flexibility and convenience.