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:
| ls
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.
| <VirtualHost *:80>
ServerName example.io ServerAlias www.example.io Redirect permanent / https://example.io/ </VirtualHost> <VirtualHost *:443> ServerName example.io ServerAlias www.example.io <If “%{HTTP_HOST} == ‘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 <Location /guacamole/> 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> <Location /guacamole/websocket-tunnel> 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.
