Install and Use Guacamole Remote Desktop on Ubuntu 20.04

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 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.

Before getting into the crux of this tool, wouldn’t it be good if we knew what it is all bout? Right, let us go ahead and demystify this tool. Apache Guacamole is a clientless remote desktop gateway that supports standard protocols like VNC, RDP, and SSH. Thanks to HTML5, once Guacamole is installed on a server, all you need to access your desktops is a web browser.

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 guacamole-server, and downloading the latest guacamole.war from the project website will be sufficient to provide the client.

For CentOS refer to: Install and Use Guacamole Remote Desktop on CentOS 8

Step 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 all the dependencies that our Guacamole server will require to breathe and live. Get them all installed as follows:

sudo apt update
sudo apt install -y gcc vim curl wget g++ libcairo2-dev libjpeg-turbo8-dev libpng-dev libtool-bin libossp-uuid-dev libavcodec-dev  libavformat-dev libavutil-dev libswscale-dev build-essential libpango1.0-dev libssh2-1-dev libvncserver-dev libtelnet-dev libpulse-dev libssl-dev libvorbis-dev libwebp-dev libwebsockets-dev

Install FreeRDP2

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

sudo add-apt-repository ppa:remmina-ppa-team/remmina-next-daily
sudo apt update
sudo apt install freerdp2-dev freerdp2-x11 -y

Once the prerequisites are dealt with, we now have the opportunity of having the main course meal which involves a couple of more steps covered next.

Step 2: Install Apache Tomcat

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 Guacamole java client. Since it is in Java, we will have to get Java installed first.

sudo apt install openjdk-11-jdk

Once it is installed, you can check the version installed

$ java --version
openjdk 11.0.17 2022-10-18
OpenJDK Runtime Environment (build 11.0.17+8-post-Ubuntu-1ubuntu220.04)
OpenJDK 64-Bit Server VM (build 11.0.17+8-post-Ubuntu-1ubuntu220.04, mixed mode, sharing)

Install Tomcat and all the required packages with the command:

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

Once installed, start and enable the service:

sudo systemctl enable --now tomcat9

And Tomcat should be running happily

$ systemctl status tomcat9
 tomcat9.service - Apache Tomcat 9 Web Application Server
     Loaded: loaded (/lib/systemd/system/tomcat9.service; enabled; vendor preset: enabled)
     Active: active (running) since Wed 2023-08-16 13:27:41 EDT; 2min 48s ago
       Docs: https://tomcat.apache.org/tomcat-9.0-doc/index.html
   Main PID: 18458 (java)
      Tasks: 29 (limit: 4660)
     Memory: 101.3M
        CPU: 5.938s
     CGroup: /system.slice/tomcat9.service
             └─18458 /usr/lib/jvm/java-11-openjdk-amd64/bin/java -Djava.util.logging.config.file=/var/lib/tomcat9/conf/logging.properties -Djava.util.logging.manager=org.apache.juli.ClassLo>
~

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:

sudo ufw allow 8080/tcp

Step 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 ~/
VER=1.5.3
wget https://archive.apache.org/dist/guacamole/$VER/source/guacamole-server-$VER.tar.gz

Extract the source tarball after download

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

Change into the guacamole server source code directory;

cd ~/guacamole-server-*/

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

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

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

guacamole-server version 1.5.3
------------------------------------------------

   Library status:

     freerdp2 ............ yes
     pango ............... yes
     libavcodec .......... yes
     libavformat.......... no
     libavutil ........... yes
     libssh2 ............. yes
     libssl .............. yes
     libswscale .......... yes
     libtelnet ........... yes
     libVNCServer ........ yes
     libvorbis ........... yes
     libpulse ............ no
     libwebsockets ....... no
     libwebp ............. yes
     wsock32 ............. no

   Protocol support:

      Kubernetes .... no
      RDP ........... yes
      SSH ........... yes
      Telnet ........ yes
      VNC ........... yes

   Services / tools:

      guacd ...... yes
      guacenc .... no
      guaclog .... yes

   FreeRDP plugins: /usr/lib/x86_64-linux-gnu/freerdp2
   Init scripts: /etc/init.d
   Systemd units: no

Type "make" to compile guacamole-server.

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

make

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

sudo 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.

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

Create guacd.conf configuration file:

$ sudo vim /etc/guacamole/guacd.conf
[daemon]
pid_file = /var/run/guacd.pid
#log_level = debug

[server]
#bind_host = localhost
bind_host = 127.0.0.1
bind_port = 4822

#[ssl]
#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.

sudo systemctl daemon-reload

Once reloaded, start and enable the guacd service.

sudo systemctl start guacd
sudo systemctl enable guacd

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

$ systemctl status guacd
● guacd.service - LSB: Guacamole proxy daemon
     Loaded: loaded (/etc/init.d/guacd; generated)
     Active: active (running) since Wed 2023-08-16 13:34:38 EDT; 5s ago
       Docs: man:systemd-sysv-generator(8)
      Tasks: 1 (limit: 4660)
     Memory: 9.9M
        CPU: 12ms
     CGroup: /system.slice/guacd.service
             └─32087 /usr/local/sbin/guacd -p /var/run/guacd.pid
...

Step 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 guacamole.properties, the main configuration file for Guacamole. The recommended 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.

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.

VER=1.5.3
wget https://archive.apache.org/dist/guacamole/$VER/binary/guacamole-$VER.war
sudo mkdir /etc/guacamole

To install the Guacamole client binary, move the Guacamole client to Tomcat webapps directory as shown below;

sudo mv guacamole-$VER.war /var/lib/tomcat9/webapps/guacamole.war

Step 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/guacamole.properties configuration file. Within this configuration, you need to simply define Guacamole server hostname, port, user mapping configuration file, 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" | sudo tee -a /etc/default/tomcat
echo "export GUACAMOLE_HOME=/etc/guacamole" | sudo tee -a /etc/profile

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

$ sudo vim /etc/guacamole/guacamole.properties
guacd-hostname: localhost
guacd-port:    4822

After the configuration is as pretty as above, save it and proceed to set the required authentication as shown below.

Step 6: Setup Guacamole Database Authentication

Guacamole’s default authentication method reads all users and connections from a single file called user-mapping.xml. In this file, you need to define the users allowed to access Guacamole web UI, the servers to connect to and the method of connection. But there, we will use database authentication which is recommended for production environments.

First, ensure that MariaDB or MySQL has been installed:

• How to Install MariaDB on Ubuntu
• How to Install MySQL on Ubuntu

Once installed, log in as the root user:

sudo mysql -u root -p

Create the required database and user for Guacamole:

REATE DATABASE guacamole_db;
CREATE USER 'guacamole_user'@'localhost' IDENTIFIED BY 'Passw0rd!';
GRANT SELECT,INSERT,UPDATE,DELETE ON guacamole_db.* TO 'guacamole_user'@'localhost';
FLUSH PRIVILEGES;
QUIT

Next, we need to install the MySQL Java Connector. First, export the latest available version:

VER=8.1.0

Now pull the archive:

wget https://dev.mysql.com/get/Downloads/Connector-J/mysql-connector-j-$VER.tar.gz

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

tar -xf mysql-connector-j-*.tar.gz
sudo cp mysql-connector-j-$VER/mysql-connector-j-$VER.jar /etc/guacamole/lib/

We also need to download the JDBC auth plugin. Also here, export the latest available version:

VER=1.5.3

Download the archive:

wget https://downloads.apache.org/guacamole/$VER/binary/guacamole-auth-jdbc-$VER.tar.gz

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

tar -xf guacamole-auth-jdbc-$VER.tar.gz
sudo mv guacamole-auth-jdbc-$VER/mysql/guacamole-auth-jdbc-mysql-$VER.jar /etc/guacamole/extensions/

You now need to import database schemas. To do so, switch to the below directory:

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

Import schemas by running the below command:

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

Remember to provide your MySQL root password to proceed.

Now adjust your Guacamole config to accommodate your database as shown:

sudo vim /etc/guacamole/guacamole.properties

Add your database details in the file:

##MySQL properties
mysql-hostname: 127.0.0.1
mysql-port: 3306
mysql-database: guacamole_db
mysql-username: guacamole_user
mysql-password: Passw0rd!

Save the file and restart the services:

sudo systemctl restart tomcat9 guacd

Step 7: Getting 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:

On the above page, log in with the default creds guacadmin as the username and guacadmin as the password. Once authenticated, you need to create another admin user and delete the old default user.

To add a new user, navigate to Settings ->User->New User.

Ensure all the permissions are enabled for the new admin user. Once created, log out and log in using the new admin user. You can then proceed and delete the old default user:

Create Connections on Guacamole

You can then add the desired remote connections to Guacamole. This is done by navigating to Settings ->Connection->New Connection

Set the preferred name, protocol and the hostname/IP address and port under the Parameters->Network as shown above. For SSH protocol, you can get the error “ssh handshake failed” if you previously has SSH authentication enabled between the hosts. To solve the error, you need to modify the SSH config on the remote system as shown:

$ sudo vim /etc/ssh/sshd_config
HostKeyAlgorithms +ssh-rsa
PubkeyAcceptedKeyTypes +ssh-rsa

Restart the service:

sudo systemctl restart sshd

The added connection should now appear on your Guacamole home as shown here:

To initiate a connection, click on it. If all is okay, the connection should be launched as shown:

You can also use other Authentication Methods as shown here:

• Guacamole Integration with Active Directory, OTP, and Duo 2FA

To configure SSL check out our article:

• Configure Nginx Proxy For Guacamole With Let’s Encrypt SSL

Culmination

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 especially during this season where most of us will be making memories with the ones we care about.

Other guides that might interest you include:

• Install and Use Guacamole Remote Desktop on CentOS 8
• Easy way to Create SSH tunnels on Linux CLI
• Install and Configure OpenSSH Server on Windows Server 2019
• Set Up Two factor (2FA) Authentication for SSH on CentOS / RHEL 7/8