Apache Guacamole for a remote lab
Apache Guacamole is a browser based experience for remote SSH and RDP access. In a nut shell you run a self-hosted server which you connect to via a web GUI. From within this site you can add connections to your various networked devices - and they work right there in your browser. Guacamole supports many connection types and encryption protocols so you’re sure to find what you need.
An Introduction
Let’s jump right in and take a look at some of the interface of Guacamole.
Guacamole has a clean interface for quickly getting at your saved connections. It even features a preview mode in each box so you can have an idea of what you’re connecting to. Guacamole supports the following protocols:
- Kubernetes
- RDP
- SSH
- Telnet
- VNC
For SSH Guacamole supports username and password based authentication or SSH keys. If you plan on using SSH though, see the note below.
For SSH key algorithms Guacamole is very picky. You’re required to use PEM format. To generate a key compatible with Guacamole try “ssh-keygen -t rsa -b 4096 -m PEM”
Guacamole allows for User management and has some minimal settings. No distractions here from adding connections and getting going.
When adding an SSH connection Guacamole wants you to specify your key in the OpenSSH format as shown. Guac allows for some terminal customization if you prefer a certain color when you hack away. I think the green on black looks the smoothest as seen below.
Now that we’ve taken a look at the straight forward settings of Guacamole. Let’s go through setting up a Guacamole server.
Setup
This installation is based off a fresh Ubuntu 22.04 server.
Installing Guacd
Guacamole has a lot of dependencies based on what connections you intend to run. Let’s install the usual suspects.
1
2
3
4
sudo apt install build-essential libcairo2-dev libjpeg-turbo8-dev libpng-dev libtool-bin 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
Next let’s download Guacamole to our server.
1
wget https://downloads.apache.org/guacamole/1.5.2/source/guacamole-server-1.5.2.tar.gz
Extract the file and navigate to its directory.
1
2
tar -xvf guacamole-server-1.5.2.tar.gz
cd guacamole-server-1.5.2
Build the installation based off the source files.
1
2
3
sudo ./configure --with-init-dir=/etc/init.d --enable-allow-freerdp-snapshots
sudo make
sudo make install
Update installed library cache and reload systemd.
1
2
sudo ldconfig
sudo systemctl daemon-reload
Start Guacd and enable it to start at boot.
1
2
sudo systemctl start guacd
sudo systemctl enable guacd
Create a directory to store Guacamole configuration files and extensions. These directories are used in later steps.
1
sudo mkdir -p /etc/guacamole/{extensions,lib}
Installing Tomcat
Install Apache Tomcat and modules.
1
sudo apt install tomcat9 tomcat9-admin tomcat9-common tomcat9-user
Download the Guacamole client.
1
wget https://downloads.apache.org/guacamole/1.5.2/binary/guacamole-1.5.2.war
Move the client to the Tomcat web directory.
1
sudo mv guacamole-1.5.2.war /var/lib/tomcat9/webapps/guacamole.war
Restart both Apache Tomcat and Guacd.
1
sudo systemctl restart tomcat9 guacd
Setting up a Database
While Apache Guacamole does support basic user authentication via a user-mapping.xml file, it should only be used for testing. For this guide, we will use production-ready database authentication through MySQL/MariaDB.
Install either MySQL or MariaDB on your system. (This guide follows MySQL)
1
sudo apt install mysql-server
Run the following commands to perform the initial security configuration:
1
2
3
4
sudo mysql
ALTER USER 'root'@'localhost' IDENTIFIED WITH mysql_native_password BY 'SetRootPasswordHere';
exit
sudo mysql_secure_installation
Before populating the database, we need to install a few things. Mainly we need to install the MySQL Connector/J library and Guacamole JDBC authenticator plugin.
Download the MySQL Connector/J (Java Connector). For this guide, download the platform independent archived file.
1
wget https://dev.mysql.com/get/Downloads/Connector-J/mysql-connector-java-8.0.26.tar.gz
Extract the tar file and copy it to /etc/guacamole/lib/.
1
2
tar -xf mysql-connector-java-8.0.26.tar.gz
sudo cp mysql-connector-java-8.0.26/mysql-connector-java-8.0.26.jar /etc/guacamole/lib/
Download the JDBC auth plugin for Apache Guacamole. This file can be found on https://guacamole.apache.org/releases/ by selecting the release version and then locate the “jdbc” file.
1
wget https://downloads.apache.org/guacamole/1.5.2/binary/guacamole-auth-jdbc-1.5.2.tar.gz
Extract the tar file and copy it to /etc/guacamole/extensions/.
1
2
tar -xf guacamole-auth-jdbc-1.5.2.tar.gz
sudo mv guacamole-auth-jdbc-1.5.2/mysql/guacamole-auth-jdbc-mysql-1.5.2.jar /etc/guacamole/extensions/
Log in to mysql as the root user.
1
mysql -u root -p
The prompt should change again to mysql>.
While in the mysql prompt we run the commands below. The goal is to change the root password, create a database, and create a new user for that database. When running the commands, replace any instance of password with a secure password string for the mysql root user and the new user for your database, respectively.
1
2
3
4
5
ALTER USER 'root'@'localhost' IDENTIFIED BY 'password';
CREATE DATABASE guacamole_db;
CREATE USER 'guacamole_user'@'localhost' IDENTIFIED BY 'password';
GRANT SELECT,INSERT,UPDATE,DELETE ON guacamole_db.* TO 'guacamole_user'@'localhost';
FLUSH PRIVILEGES;
Exit the MySQL prompt by typing quit
.
Locate the scheme files in the extracted directory for the JDBC plugin.
1
cd guacamole-auth-jdbc-1.5.2/mysql/schema
Import those sql schema files into the MySQL database.
1
cat *.sql | mysql -u root -p guacamole_db
Create the properties file for Guacamole.
1
sudo nano /etc/guacamole/guacamole.properties
Paste in the following configuration settings, replacing [password] with the password of the new guacamole_user that you created for the database.
1
2
3
4
5
6
# MySQL properties
mysql-hostname: 127.0.0.1
mysql-port: 3306
mysql-database: guacamole_db
mysql-username: guacamole_user
mysql-password: [password]
Restart all related services.
1
sudo systemctl restart tomcat9 guacd mysql
All done
Guacamole should now be accessible at:
1
[ip]:8080/guacamole
Connection tips
I’ve discovered a couple quirks when it comes to setting up Guacamole connections. Here are some tips.
- For Windows RDP connections set the security mode to NLA Authentication
- For both linux and windows connections make sure to check the box to ignore certificate warnings
- For SSH the entry only requires hostname, port 22, your username, and the SSH key in the format seen below.
- I’ve found Guacamole doesn’t seem to do well with DNS so I use IP addresses. This could be my own issues.