4/29/24, 11:18 AM Apache Guacamole for a remote lab |

 Post 

Apache Guacamole for a remote lab

By Sysblob 5 min read

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.

https://sysblob.com/posts/guacamole/ 1/12
4/29/24, 11:18 AM Apache Guacamole for a remote lab |

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.

https://sysblob.com/posts/guacamole/ 2/12
4/29/24, 11:18 AM Apache Guacamole for a remote lab |

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.

https://sysblob.com/posts/guacamole/ 3/12
4/29/24, 11:18 AM Apache Guacamole for a remote lab |

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

https://sysblob.com/posts/guacamole/ 4/12
4/29/24, 11:18 AM Apache Guacamole for a remote lab |

Guacamole has a lot of dependencies based on what connections you intend to run. Let’s install the
usual suspects.

 Shell 
1 sudo apt install build-essential libcairo2-dev libjpeg-turbo8-dev libpng-dev lib
2 libavformat-dev libavutil-dev libswscale-dev freerdp2-dev libpango1.0-dev \
3 libssh2-1-dev libtelnet-dev libvncserver-dev libwebsockets-dev \
4 libpulse-dev libssl-dev libvorbis-dev libwebp-dev

Next let’s download Guacamole to our server.

 Shell 
1 wget https://downloads.apache.org/guacamole/1.5.2/source/guacamole-server-1.5.2.

Extract the file and navigate to its directory.

 Shell 
1 tar -xvf guacamole-server-1.5.2.tar.gz
2 cd guacamole-server-1.5.2

Build the installation based off the source files.

 Shell 
1 sudo ./configure --with-init-dir=/etc/init.d --enable-allow-freerdp-snapshots
2 sudo make
3 sudo make install

Update installed library cache and reload systemd.

 Shell 
1 sudo ldconfig
2 sudo systemctl daemon-reload

Start Guacd and enable it to start at boot.

https://sysblob.com/posts/guacamole/ 5/12
4/29/24, 11:18 AM Apache Guacamole for a remote lab |

 Shell 
1 sudo systemctl start guacd
2 sudo systemctl enable guacd

Create a directory to store Guacamole configuration files and extensions. These directories are
used in later steps.

 Shell 
1 sudo mkdir -p /etc/guacamole/{extensions,lib}

Installing Tomcat

Install Apache Tomcat and modules.

 Shell 
1 sudo apt install tomcat9 tomcat9-admin tomcat9-common tomcat9-user

Download the Guacamole client.

 Shell 
1 wget https://downloads.apache.org/guacamole/1.5.2/binary/guacamole-1.5.2.war

Move the client to the Tomcat web directory.

 Shell 
1 sudo mv guacamole-1.5.2.war /var/lib/tomcat9/webapps/guacamole.war

Restart both Apache Tomcat and Guacd.

 Shell 
1 sudo systemctl restart tomcat9 guacd

Setting up a Database

https://sysblob.com/posts/guacamole/ 6/12
4/29/24, 11:18 AM Apache Guacamole for a remote lab |

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)

 Shell 
1 sudo apt install mysql-server

Run the following commands to perform the initial security configuration:

 Shell 
1 sudo mysql
2 ALTER USER 'root'@'localhost' IDENTIFIED WITH mysql_native_password BY 'SetRootP
3 exit
4 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.

 Shell 
1 wget https://dev.mysql.com/get/Downloads/Connector-J/mysql-connector-java-8.0.26

Extract the tar file and copy it to /etc/guacamole/lib/.

 Shell 
1 tar -xf mysql-connector-java-8.0.26.tar.gz
2 sudo cp mysql-connector-java-8.0.26/mysql-connector-java-8.0.26.jar /etc/guacamo

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.
https://sysblob.com/posts/guacamole/ 7/12
4/29/24, 11:18 AM Apache Guacamole for a remote lab |

 Shell 
1 wget https://downloads.apache.org/guacamole/1.5.2/binary/guacamole-auth-jdbc-1.5

Extract the tar file and copy it to /etc/guacamole/extensions/.

 Shell 
1 tar -xf guacamole-auth-jdbc-1.5.2.tar.gz
2 sudo mv guacamole-auth-jdbc-1.5.2/mysql/guacamole-auth-jdbc-mysql-1.5.2.jar /etc

Log in to mysql as the root user.

 Shell 
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.

 Shell 
1 ALTER USER 'root'@'localhost' IDENTIFIED BY 'password';
2 CREATE DATABASE guacamole_db;
3 CREATE USER 'guacamole_user'@'localhost' IDENTIFIED BY 'password';
4 GRANT SELECT,INSERT,UPDATE,DELETE ON guacamole_db.* TO 'guacamole_user'@'localho
5 FLUSH PRIVILEGES;

Exit the MySQL prompt by typing quit .

Locate the scheme files in the extracted directory for the JDBC plugin.

 Shell 
1 cd guacamole-auth-jdbc-1.5.2/mysql/schema

https://sysblob.com/posts/guacamole/ 8/12
4/29/24, 11:18 AM Apache Guacamole for a remote lab |

Import those sql schema files into the MySQL database.

 Shell 
1 cat *.sql | mysql -u root -p guacamole_db

Create the properties file for Guacamole.

 Shell 
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.

 Text 
1 # MySQL properties
2 mysql-hostname: 127.0.0.1
3 mysql-port: 3306
4 mysql-database: guacamole_db
5 mysql-username: guacamole_user
6 mysql-password: [password]

Restart all related services.

 Shell 
1 sudo systemctl restart tomcat9 guacd mysql

All done

Guacamole should now be accessible at:

 Text 
1 [ip]:8080/guacamole

https://sysblob.com/posts/guacamole/ 9/12
4/29/24, 11:18 AM Apache Guacamole for a remote lab |

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.

https://sysblob.com/posts/guacamole/ 10/12
4/29/24, 11:18 AM Apache Guacamole for a remote lab |

 homelabbing

 guacamole remote ssh rdp

This post is licensed under CC BY 4.0 by the author. Share:    

Further Reading

Aug 18, 2023

Plex and the *ARR stack

Aug 21, 2023

Everything Bookstack
Bookstack is a self-hosted wiki that makes editing and storing your documentation in an organized and secure
fashion fast, efficient, and easy. Link: https://www.bookstackapp.com/ Refer to the Ta...

https://sysblob.com/posts/guacamole/ 11/12
4/29/24, 11:18 AM Apache Guacamole for a remote lab |

Aug 23, 2023

Homelabbing (Sysblob.com)
Hello World - and welcome to Sysblob.com, a website dedicated to homelabbing. I’ve been a fan of tinkering
and computers for a while now, and I’ve made a career of it as a Linux Administrator. Howe...

OLDER NEWER

A deep dive into Docker Customizing your image with Cloud-init

© 2024 Sysblob. Some rights reserved.

https://sysblob.com/posts/guacamole/ 12/12