Documentation
Linux
Debian
How To Install Guacamole on Debian 12

How To Install Guacamole on Debian 12

Overview

This document outlines how to install Guacamole on Debian 12 and then rebrand it with the Datafort branding

Dependencies

We will be building guacamole from source, so we will need the build dependencies installed.

sudo apt install -y build-essential \
	libcairo2-dev \
	libjpeg62-turbo-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 \
	libvncserver-dev \
	libtelnet-dev \
	libwebsockets-dev \
	libssl-dev \
	libvorbis-dev \
	libwebp-dev \
	libpulse-dev \
	sudo \
	ffmpeg \
    vim

We will use a shell variable to keep versioning straight forward. We will create a build directory and download and extract the source into it:

export VER=1.5.4
mkdir guac_build
cd guac_build
wget https://downloads.apache.org/guacamole/$VER/source/guacamole-server-$VER.tar.gz
tar xzf guacamole-server-$VER.tar.gz
cd guacamole-server-$VER

Building guacd

Now that we have everything ready, we will build this from source.

We will configure the installer to have it build systemd jobs for us. This also disabled guacenc which is having problems building.

./configure --with-systemd-dir=/etc/systemd/system/ --disable-guacenc

Ensure the output looks good. Fix missing dependencies if they arise. Now, run make to start compiling.

make
sudo make install
sudo ldconfig

Configuring guacd Daemon

First things first, we need to comment out the ipv6 addresses in the hosts file, or else guacd will only listen on ipv6

sed -i '/^::1/s/^/#/g' /etc/hosts

Now we can enable and start the service, and then make sure it’s running and listening on localhost:

sudo systemctl daemon-reload
sudo systemctl enable --now guacd
sudo systemctl status guacd
● guacd.service - Guacamole Server
     Loaded: loaded (/etc/systemd/system/guacd.service; enabled; preset: enabled)
     Active: active (running) since Sat 2024-02-10 18:12:39 EST; 2s ago
       Docs: man:guacd(8)
   Main PID: 71849 (guacd)
      Tasks: 1 (limit: 9471)
     Memory: 10.0M
        CPU: 13ms
     CGroup: /system.slice/guacd.service
             └─71849 /usr/local/sbin/guacd -f

Feb 10 18:12:39 dfs-noc-01 systemd[1]: Started guacd.service - Guacamole Server.
Feb 10 18:12:39 dfs-noc-01 guacd[71849]: Guacamole proxy daemon (guacd) version 1.5.4 started
Feb 10 18:12:39 dfs-noc-01 guacd[71849]: guacd[71849]: INFO:        Guacamole proxy daemon (guacd) version 1.5.4 started
Feb 10 18:12:39 dfs-noc-01 guacd[71849]: guacd[71849]: INFO:        Listening on host 127.0.0.1, port 4822
Feb 10 18:12:39 dfs-noc-01 guacd[71849]: Listening on host 127.0.0.1, port 4822

Configure guacd to run as a service user, which will allow for RDP to work correctly:

sudo su -
useradd -M -d /var/lib/guacd/ -r -s /sbin/nologin -c "Guacd User" guacd
mkdir /var/lib/guacd
chown -R guacd: /var/lib/guacd
sed -i 's/daemon/guacd/' /etc/systemd/system/guacd.service
systemctl daemon-reload
systemctl restart guacd

Install Tomcat Service

We will add the tomcat repo, so we can install the tomact server from the apt repository:

echo "deb http://deb.debian.org/debian/ bullseye main" | sudo tee -a /etc/apt/sources.list.d/bullseye.list
sudo apt update
sudo apt install tomcat9 tomcat9-admin tomcat9-common tomcat9-user -y
sudo rm /etc/apt/sources.list.d/bullseye.list
sudo apt update

Ensure the tomcat server is running:

sudo systemctl status tomcat9
● tomcat9.service - Apache Tomcat 9 Web Application Server
     Loaded: loaded (/lib/systemd/system/tomcat9.service; enabled; preset: enabled)
     Active: active (running) since Sat 2024-02-10 18:20:01 EST; 1min 13s ago
       Docs: https://tomcat.apache.org/tomcat-9.0-doc/index.html
    Process: 74325 ExecStartPre=/usr/libexec/tomcat9/tomcat-update-policy.sh (code=exited, status=0/SUCCESS)
   Main PID: 74329 (java)
      Tasks: 37 (limit: 9471)
     Memory: 183.0M
        CPU: 6.786s
     CGroup: /system.slice/tomcat9.service
             └─74329 /usr/lib/jvm/default-java/bin/java -Djava.util.logging.config.file=/var/lib/tomcat9/conf/logging.properties -Djava.ut>

Feb 10 18:20:03 dfs-noc-01 tomcat9[74329]: Deployment of deployment descriptor [/etc/tomcat9/Catalina/localhost/host-manager.xml] has fini>
Feb 10 18:20:03 dfs-noc-01 tomcat9[74329]: Deploying deployment descriptor [/etc/tomcat9/Catalina/localhost/manager.xml]
Feb 10 18:20:03 dfs-noc-01 tomcat9[74329]: The path attribute with value [/manager] in deployment descriptor [/etc/tomcat9/Catalina/localh>
Feb 10 18:20:04 dfs-noc-01 tomcat9[74329]: At least one JAR was scanned for TLDs yet contained no TLDs. Enable debug logging for this logg>
Feb 10 18:20:04 dfs-noc-01 tomcat9[74329]: Deployment of deployment descriptor [/etc/tomcat9/Catalina/localhost/manager.xml] has finished >
Feb 10 18:20:04 dfs-noc-01 tomcat9[74329]: Deploying web application directory [/var/lib/tomcat9/webapps/ROOT]
Feb 10 18:20:05 dfs-noc-01 tomcat9[74329]: At least one JAR was scanned for TLDs yet contained no TLDs. Enable debug logging for this logg>
Feb 10 18:20:05 dfs-noc-01 tomcat9[74329]: Deployment of web application directory [/var/lib/tomcat9/webapps/ROOT] has finished in [640] ms
Feb 10 18:20:05 dfs-noc-01 tomcat9[74329]: Starting ProtocolHandler ["http-nio-8080"]
Feb 10 18:20:05 dfs-noc-01 tomcat9[74329]: Server startup in [2513] milliseconds

Installing Guacamole Client

We will need to download the guacamole client

sudo su -
mkdir /etc/guacamole
export VER=1.5.4
wget \
https://downloads.apache.org/guacamole/$VER/binary/guacamole-$VER.war \
-O /etc/guacamole/guacamole.war
ln -s /etc/guacamole/guacamole.war /var/lib/tomcat9/webapps/
systemctl restart tomcat9 guacd
mkdir extensions lib
echo "GUACAMOLE_HOME=/etc/guacamole" >> /etc/default/tomcat9
cat > /etc/guacamole/guacamole.properties << EOL
guacd-hostname: 127.0.0.1
guacd-port: 4822
user-mapping:   /etc/guacamole/user-mapping.xml
auth-provider:  net.sourceforge.guacamole.net.basic.BasicFileAuthenticationProvider
EOL
ln -s /etc/guacamole /usr/share/tomcat9/.guacamole

Setting up mySQL Authentication

This assumes a working mariadb (mysql) instance is already present.

Setting up the Database

Login to your database system and create Guacamole database and database user (names used are not standard, hence feel free to change them, and of course the password);

mysql -u root -p
create database guacd;
create user guacd_admin@localhost identified by 'ChangeME';
grant SELECT,UPDATE,INSERT,DELETE on guacd.* to guacd_admin@localhost;
flush privileges;
quit

Install Guacamole database authentication extension

Download the Guacamole database authentication extension that matches your current version of Guacamole from the releases page.

export VER=1.5.4
wget https://dlcdn.apache.org/guacamole/$(VER)/binary/guacamole-auth-jdbc-${VER}.tar.gz

The tarball comes with extensions for PostgreSQL, MySQL as well as SQL servers. Thus, extract only the MySQL extension;

tar xzf guacamole-auth-jdbc-${VER}.tar.gz guacamole-auth-jdbc-${VER}/mysql

Copy the Guacamole extension (.jar) file to GUACAMOLE_HOME/extensions directory;

cp guacamole-auth-jdbc-${VER}/mysql/guacamole-auth-jdbc-mysql-1.4.0.jar /etc/guacamole/extensions/

Next, Import Guacamole MySQL database schema (001-create-schema.sql and 002-create-admin-user.sql) into the Guacamole database created above;

mysql -u root -p guacd < guacamole-auth-jdbc-${VER}/mysql/schema/001-create-schema.sql
mysql -u root -p guacd < guacamole-auth-jdbc-${VER}/mysql/schema/002-create-admin-user.sql

Install MySQL JDBC connector in the Guacamole lib directory;

wget https://dev.mysql.com/get/Downloads/Connector-J/mysql-connector-java-8.0.28.tar.gz
tar xzf mysql-connector-java-8.0.28.tar.gz
cp mysql-connector-java-8.0.28/mysql-connector-java-8.0.28.jar /etc/guacamole/lib/

Configure Guacamole MySQL Database Authentication

Next, configure Guacamole for database authentication by defining the following, at the very least, in the guacamole.properties file.

  • Database hostname
  • database name
  • database user and password
cat >> /etc/guacamole/guacamole.properties << EOL
auth-provider: net.sourceforge.guacamole.net.auth.mysql.MySQLAuthenticationProvider
mysql-hostname: localhost
mysql-database: guacd
mysql-username: guacd_admin
mysql-password: ChangeME
EOL

Verify Guacamole Database Authentication

You can now restart your serverlet (Tomcat service) and login to Guacamole to test the database authentication;

systemctl restart tomcat9

The default Guacamole database authentication credentials are:

  • Username: guacadmin
  • Password: guacadmin
How To Set up a Docker Registry on Debian 12How To Install OVPN Client in Debian 12