How To Install the Apache Guacamole Remote Desktop Gateway

Ivory

There is no shortage of applications that enable administrators to connect to their servers. But using different applications for different purposes can get hectic, to say the least.

Thankfully, there’s a smarter way to do things – and it’s existed since 2013.

Enter: Apache Guacamole.

It is a clientless remote desktop gateway that supports the RDP, VNC, and SSH protocols. The best thing about it is that you only need a web browser to work with it once it’s set up. No extensions or tools are needed to use this open-source tool!

Here’s a quick guide to setting up Apache Guacamole.

Installing Guacamole’s Dependencies

Before getting into installing the packages dependencies, bear in mind these prerequisites:

Linux server (we’re using the Ubuntu 20.04 server)
Root/admin access
MariaDB database
A domain name connected to the server’s IP

Guacamole is split into two pieces: the server and the client. The server must be installed using the source code manually. The client is a Java serverlet web app front end that runs under Tomcat.

To install the dependencies, launch a terminal, connect to your server, and run the following:

sudo apt install build-essential libcairo2-dev libjpeg-turbo8-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 libtelnet-dev libvncserver-dev libwebsockets-dev libpulse-dev libssl-dev libvorbis-dev libwebp-dev -y

You will also need to install Tomcat 9 for the web app:

sudo apt install tomcat9 -y

The next two commands will start and enable Tomcat 9, and verify its status, respectively:

sudo systemctl enable –now tomcat9

sudo systemctl status tomcat9

Compiling and Installing the Guacamole Server

Begin by running the following wget command to download the required source code:

wget https://dlcdn.apache.org/guacamole/1.4.0/source/guacamole-server-1.4.0.tar.gz

Now that you have the file on your machine, extract it with this command:

tar -xzf guacamole-server-1.4.0.tar.gz

Next, change your directory to the extracted file like so:

cd guacamole-server-1.4.0/

Set up the server with this script:

./configure –with-systemd-dir=/etc/systemd/system/ –disable-dependency-tracking

The first option in the command above automatically installs the script to the mentioned directory in /etc. The second option disables dependency tracking, shortening the build time.

The output will show you the Guacamole version, library status, protocol support, and tools/services that come with Guacamole. If you see this output, you’re on track to installing Guacamole.

The commands below will compile Guacamole server and install the binary files in usr/local/bin and usr/local/sbin. The libraries will be installed in usr/local/lib.

make

make install

Then, use the following commands to update the symbolic links of the system libraries and reload systemd:

sudo ldconfig

sudo systemctl daemon-reload

Finally, start and enable the Guacamole server and verify its status with these commands:

sudo systemctl enable –now guacd

sudo systemctl status guacd

You should see an output indicating that guacd is running.

Creating the Configuration and Setting the Directory

The Guacamole installation needs a configuration directory to work. Creating the /etc/guacamole/ directory is where Guacamole will store the configuration files.

The command below will create an environment variable “GUACAMOLE_HOME” and set it up for the Tomcat configuration, ensuring that Tomcat always loads the Guacamole config directory.

echo GUACAMOLE_HOME=/etc/guacamole >> /etc/default/tomcat9

Running the command below will create the actual configuration directory, along with the “extensions” and “lib” directories.

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

Finally, you can create the configuration files like so:

touch /etc/guacamole/{guacamole.properties,guacd.conf}

Setting Up the MariaDB Database

Begin by logging into the MariaDB shell as the root user:

mysql -u root -p

Then, create a new database, and exit the shell:

CREATE DATABASE guacamole_db;

exit

To proceed, you need the database authentication extension for Guacamole. Run this to download it:

wget https://dlcdn.apache.org/guacamole/1.4.0/binary/guacamole-auth-jdbc-1.4.0.tar.gz

Extract it and switch your directory to the extracted file like so:

tar -xf guacamole-auth-jdbc-1.4.0.tar.gz

cd guacamole-auth-jdbc-1.4.0/mysql/

Import the Guacamole MariaDB database scheme to the newly-created database:

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

You will need to enter the MariaDB root user’s password. After you do, run the command below to log into the MariaDB shell again.

mysql -u root -p

We’re logging in again to create a new MariaDB user for Guacamole. Run these, and you’ll be good to go:

CREATE USER ‘guacamole_user’@’localhost’ IDENTIFIED BY ‘StrongPassword’;

GRANT SELECT,INSERT,UPDATE,DELETE ON guacamole_db.* TO ‘guacamole_user’@’localhost’;

FLUSH PRIVILEGES;

exit

Installing the Database Authentication Extension and MySQL/J Library

The extension in question enables you to set up Guacamole with database authentication. Though we’re using MariaDB, you can use PostgreSQL.

Use these commands to change your working directory to the desired mysql folder and then list the files:

cd guacamole-auth-jdbc-1.4.0/mysql/

ls -lah

All that’s left to do is installing the extension with the following command:

cp guacamole-auth-jdbc-mysql-1.4.0.jar /etc/guacamole/extensions/guacamole-auth-jdbc-mysql.jar

We must also install a MySQL/J library to connect to MariaDB. Let’s begin by downloading it:

wget https://cdn.mysql.com//Downloads/Connector-J/mysql-connector-java_8.0.28-1ubuntu20.04_all.deb

Next, use the dpkg command to install the connector:

dpkg -i mysql-connector-java_8.0.28-1ubuntu20.04_all.deb

Before we move on, copy the connector library to the /lib folder in /etc/guacamole so Guacamole can use it to connect to MariaDB:

cp /usr/share/java/mysql-connector-java-8.0.28.jar /etc/guacamole/lib/mysql-connector.jar

Connecting Guacamole with MariaDB

Although you’ve installed the extension and connector, they won’t do anything unless you use the database authentication. You will apply the authentication through the configuration in the guacamole.properties file.

Open /etc/guacamole/guacamole.properties with any text editor and paste the following configuration in the file:

mysql-hostname: localhost

mysql-port: 3306

mysql-database: guacamole_db

mysql-username: guacamole_user

mysql-password: StrongPassword

Next, you must set the guacd binding IP address in the /etc/guacamole/guacd.conf. Put the following in the file:

[server]

bind_host = 0.0.0.0

bind_port = 4822

Run the following commands to apply the changes you’ve made:

sudo systemctl restart guacd

sudo systemctl restart tomcat9

Installing the Guacamole Client

You’ve reached the penultimate leg of the Guacamole setup. Begin by downloading a pre-built Guacamole client package, like so:

wget <https://dlcdn.apache.org/guacamole/1.4.0/binary/guacamole-1.4.0.war>

Then, run these commands to rename the package and move it to the webapps directory in /var/lib/tomcat9:

mv guacamole-1.4.0.war guacamole.war

cp guacamole.war /var/lib/tomcat9/webapps

ls /var/lib/tomcat9/webapps

Moving the file is necessary to make the client accessible from the path URL.

Setting Up Apache as a Reverse Proxy for the Client

Before you can finally begin using Guacamole, you must install and configure a webserver with a virtual host config. The idea is to use the webserver as a the client’s reverse proxy.

Begin by getting a free LetsEncrypt SSL certificate for your domain name using the certbot documentation. Next, use this command to install Apache webserver:

sudo apt install apache2 -y

This command will enable the modules for the reverse proxy:

sudo a2enmod proxy proxy_wstunnel proxy_http ssl rewrite

Create a virtual host configuration file /etc/apache2/sites-available/guacamole.conf and paste the configuration below. Bear in mind that you must change the example.io domain name with the domain name you have. The same goes for the path of the SSL certificate.

ServerName example.io

ServerAlias www.example.io

Redirect permanent / https://example.io/

</VirtualHost>

ServerName example.io

ServerAlias www.example.io

Redirect permanent / https://example.io/

</If>

ErrorLog /var/log/apache2/example.io-error.log

CustomLog /var/log/apache2/example.io-access.log combined

SSLEngine On

SSLCertificateFile /etc/letsencrypt/live/example.io/fullchain.pem

SSLCertificateKeyFile /etc/letsencrypt/live/example.io/privkey.pem

Order allow,deny

Allow from all

ProxyPass http://127.0.0.1:8080/guacamole/ flushpackets=on

ProxyPassReverse http://127.0.0.1:8080/guacamole/

</Location>

Order allow,deny

Allow from all

ProxyPass ws://127.0.0.1:8080/guacamole/websocket-tunnel

ProxyPassReverse ws://127.0.0.1:8080/guacamole/websocket-tunnel

</Location>

</VirtualHost>

Activate the configuration and verify it by running:

a2ensite guacamole.conf

apachectl configtest

Open the Tomcat configuration in /etc/tomcat9/server.xml and paste the following in the <Host> section:

<Valve className=”org.apache.catalina.valves.RemoteIpValve”

internalProxies=”127.0.0.1″

remoteIpHeader=”x-forwarded-for”

remoteIpProxiesHeader=”x-forwarded-by”

protocolHeader=”x-forwarded-proto” />

Apply the changes by running:

sudo systemctl restart apache2

sudo systemctl restart tomcat9

And that’s it, you’ve set up Guacamole! The web app runs under Tomcat on port 8080 and has the path /guacamole.