Install Guacamole Remote Desktop on Debian 11 / Debian 10

In day-to-day life, most system admins consider having access to a server as an integral part of their occupation. This article goes deep to demonstrate how to set up such a platform. By the end of this guide, one should be equipped with knowledge on how to install and use Guacamole Remote Desktop on Debian 11 (Bullseye) / Debian 10 (Buster).

Before we dive into the nub of this tool, it is necessary that we elucidate and get to know what this tool is all about. Guacamole is an HTML web application that provides remote access to servers. It supports protocols such as RDP, SSH, and VNC. Guacamole is useful as it provides access to one or multiple desktops remotely from your device either computer, mobile phone, or tablet. Some of the advantages of Guacamole Remote Desktop are:

• Allows one to access computers from any device.
• Provides easy access to a group.
• Enables one to add HTML5 remote access to the existing infrastructure.

Guacamole consists of two pieces:

1. Guacamole-server- this provides the proxy (guacd) and the required libraries.
2. Guacamole-client- this is the client to be served by your servlet container.

Step 1: Install Dependencies

Let’s start by updating our system and installing the dependencies required by Guacamole Remote Desktop.

sudo apt update
sudo apt install -y vim build-essential libcairo2-dev libjpeg62-turbo-dev libpng-dev \
libtool-bin libossp-uuid-dev libavcodec-dev libavformat-dev libavutil-dev libswscale-dev \
libpango1.0-dev libssh2-1-dev libvncserver-dev libtelnet-dev \
libssl-dev libvorbis-dev libwebp-dev libpulse-dev

Another tool we need to install is FreeRDP2 which is hosted in the Remmina PPA

echo "deb http://deb.debian.org/debian $(lsb_release -cs)-backports main" | sudo tee /etc/apt/sources.list.d/backports.list
sudo apt update
sudo apt install freerdp2-x11 freerdp2-dev

Step 2: Install Apache Tomcat on Debian

Since we are using Apache Tomcat to run the Guacamole Java war file we need to install Java on our Debian system.

sudo apt install openjdk-11-jdk

Check the installed version

$ java --version
openjdk 11.0.16 2022-07-19
OpenJDK Runtime Environment (build 11.0.16+8-post-Debian-1deb11u1)
OpenJDK 64-Bit Server VM (build 11.0.16+8-post-Debian-1deb11u1, mixed mode, sharing)

Install Apache Tomcat on Debian

To install Tomcat on Debian 11 / Debian 10, issue the command:

sudo apt install tomcat9 tomcat9-admin tomcat9-common tomcat9-user

Ensure that the service has been started and enabled:

sudo systemctl enable --now tomcat9

Check if Tomcat is running:

$ systemctl status tomcat9
 tomcat9.service - Apache Tomcat 9 Web Application Server
     Loaded: loaded (/lib/systemd/system/tomcat9.service; enabled; vendor preset: enabled)
     Active: active (running) since Wed 2023-08-16 13:27:41 EDT; 2min 48s ago
       Docs: https://tomcat.apache.org/tomcat-9.0-doc/index.html
   Main PID: 18458 (java)
      Tasks: 29 (limit: 4660)
     Memory: 101.3M
        CPU: 5.938s
     CGroup: /system.slice/tomcat9.service
             └─18458 /usr/lib/jvm/java-11-openjdk-amd64/bin/java -Djava.util.logging.config.file=/var/lib/tomcat9/conf/logging.properties -Djava.util.logging.manager=org.apache.juli.ClassLo>
~
....

Tomcat listens on port 8080, so we need to allow this port on the firewall. First, install ufw using sudo apt install ufw

sudo ufw allow 8080/tcp

Step 3: Download Guacamole Remote Server

Guacamole Remote Server contains all the native and server components required for remote desktop connections. It provides all the libraries which all native components depend on as well as guacd which is the hub of Guacamole.

Check for the latest stable available version of Guacamole Server from the release page.

Alternatively, download using Wget as below. set the Version variable

VER=1.5.3

Then download it:

wget https://archive.apache.org/dist/guacamole/$VER/source/guacamole-server-$VER.tar.gz

Extract the downloaded file.

tar xzf guacamole-server-$VER.tar.gz

Navigate into the Guacamole directory.

cd guacamole-server-$VER

Then issue the configure script, which checks the available dependencies and adapts the Guacamole server to them.

./configure --with-init-dir=/etc/init.d

Sample Output for the above command:

...
------------------------------------------------
guacamole-server version 1.5.3
------------------------------------------------

   Library status:

     freerdp2 ............ yes
     pango ............... yes
     libavcodec .......... yes
     libavformat.......... yes
     libavutil ........... yes
     libssh2 ............. yes
     libssl .............. yes
     libswscale .......... yes
     libtelnet ........... yes
     libVNCServer ........ yes
     libvorbis ........... yes
     libpulse ............ yes
     libwebsockets ....... no
     libwebp ............. yes
     wsock32 ............. no

   Protocol support:

      Kubernetes .... no
      RDP ........... yes
      SSH ........... yes
      Telnet ........ yes
      VNC ........... yes

   Services / tools:

      guacd ...... yes
      guacenc .... yes
      guaclog .... yes

   FreeRDP plugins: /usr/lib/x86_64-linux-gnu/freerdp2
   Init scripts: /etc/init.d
   Systemd units: no

Type "make" to compile guacamole-server.

Step 4: Install Guacamole Remote Desktop on Debian

After making the above check, now it is time to install Guacamole into our Debian system. We need to compile Guacamole-server by issuing the make command as below.

make

The make command takes some time, once it is complete, now proceed to install Guacamole-server.

sudo make install

Now issue the ldconfig command, this command links the cache to the recently shared libraries

sudo ldconfig

Create the required Guacamole directories:

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

Create guacd.conf configuration file:

$ sudo vim /etc/guacamole/guacd.conf
[daemon]
pid_file = /var/run/guacd.pid
#log_level = debug

[server]
#bind_host = localhost
bind_host = 127.0.0.1
bind_port = 4822

#[ssl]
#server_certificate = /etc/ssl/certs/guacd.crt
#server_key = /etc/ssl/private/guacd.key

Then reload daemons to find the added guacd service.

sudo systemctl daemon-reload

Start and enable guacd to run on boot

sudo systemctl start guacd
sudo systemctl enable guacd

Verify if the process is running.

$ systemctl status guacd
● guacd.service - LSB: Guacamole proxy daemon
     Loaded: loaded (/etc/init.d/guacd; generated)
     Active: active (running) since Wed 2023-08-16 13:34:38 EDT; 5s ago
       Docs: man:systemd-sysv-generator(8)
      Tasks: 1 (limit: 4660)
     Memory: 9.9M
        CPU: 12ms
     CGroup: /system.slice/guacd.service
             └─32087 /usr/local/sbin/guacd -p /var/run/guacd.pid

Download Guacamole client binary same version. set the version variable:

VER=1.5.3

Pull the archive:

wget https://archive.apache.org/dist/guacamole/$VER/binary/guacamole-$VER.war

Copy the file to the Tomcat web app directory:

sudo mv guacamole-$VER.war /var/lib/tomcat9/webapps/guacamole.war

Step 5: Configure Apache Guacamole on Debian

Guacamole has two main config files i.e

• stored at /etc/guacamole referenced by GACAMOLE_HOME environment variable
• stored at /etc/guacamole/guacamole.properties this is the main file used by Guacamole and its extensions.

Create a GUACAMOLE_HOME environment variable.

sudo echo "GUACAMOLE_HOME=/etc/guacamole" | sudo tee -a /etc/default/tomcat

Then define how Guacamole communicates with guacd by creating the guacamole.properties file under /etc/guacamole as shown.

sudo vim /etc/guacamole/guacamole.properties

Edit your file as below:

guacd-hostname: localhost
guacd-port:    4822
#user-mapping:    /etc/guacamole/user-mapping.xml
#auth-provider:    net.sourceforge.guacamole.net.basic.BasicFileAuthenticationProvider

Step 6: Set Guacamole Database Authentication Method

By default, Guacamole’s authentication method reads all users and connections from a single file named user-mapping.xml. In this file, all users to access Guacamole web UI, servers to connect to as well as the connection methods are defined. But this method of defining authentication is not recommended. For production, you can use database, LDAP or DUO authentication.

In this guide, we will use database authentication. First, install MySQL or MariaDB on your Debian system.

• Install MariaDB on Debian
• Install MySQL on Debian

Once installed, access the shell as the root user:

sudo mysql -u root -p

Create a user and database for Guacamole with the SQL commands below:

CREATE DATABASE guacamole_db;
CREATE USER 'guacamole_user'@'localhost' IDENTIFIED BY 'Passw0rd!';
GRANT SELECT,INSERT,UPDATE,DELETE ON guacamole_db.* TO 'guacamole_user'@'localhost';
FLUSH PRIVILEGES;
QUIT

Next, download the MySQL Java Connector. You can also export the latest version:

VER=8.1.0

Then download it with the command:

wget https://dev.mysql.com/get/Downloads/Connector-J/mysql-connector-j-$VER.tar.gz

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

tar -xf mysql-connector-j-*.tar.gz
sudo cp mysql-connector-j-$VER/mysql-connector-j-$VER.jar /etc/guacamole/lib/

The other thing required is the JDBC auth plugin. On the site check the latest available version:

VER=1.5.3

Download the specified version above:

wget https://downloads.apache.org/guacamole/$VER/binary/guacamole-auth-jdbc-$VER.tar.gz

Extract it and copy it to the /etc/guacamole/extensions/ directory:

tar -xf guacamole-auth-jdbc-$VER.tar.gz
sudo mv guacamole-auth-jdbc-$VER/mysql/guacamole-auth-jdbc-mysql-$VER.jar /etc/guacamole/extensions/

We now need to import the SQL schema for Guacamole. Navigate to the JDBC path with the command:

cd guacamole-auth-jdbc-*/mysql/schema

Import the schemas

cat *.sql | sudo mysql -u root -p guacamole_db

You will be required to provide the MySQL root password to proceed. Once imported, you need to modify Guacamole settings:

sudo vim /etc/guacamole/guacamole.properties

In the opened file, add these lines:

###MySQL properties
mysql-hostname: 127.0.0.1
mysql-port: 3306
mysql-database: guacamole_db
mysql-username: guacamole_user
mysql-password: Passw0rd!

Save the file and restart the related services:

sudo systemctl restart tomcat9 guacd

Step 7: Accessing Guacamole Remote Desktop Web Interface

Now Apache Guacamole is set up, we can now access it from the browser using the URL:

http://server-IP:8080/guacamole

You should be able to see the login screen below:

Login using the default creds guacadmin as the username and guacadmin as the password. Once connected, it is recommended to delete the default admin user and create a new one.

To create a new admin user, navigate to Settings ->User->New User.

Once the user has been created, you can log out and log in using the new user. Then proceed and delete the old default user:

Create New Guacamole Connections

To be able to make SSH, VNC, RDP connections, we need to define them on Guacamole. To achieve that, navigate to Settings ->Connection->New Connection

When creating the connection, provide the protocol and also the IP/hostname and port for the server, username and password under the Parameters->Network.

If you have SSH key authentication configured previously on the remote systems, you need to make the below adjustments to avoid an issue with SSH “ssh handshake failed.”

$ sudo vim /etc/ssh/sshd_config
HostKeyAlgorithms +ssh-rsa
PubkeyAcceptedKeyTypes +ssh-rsa

Apply the changes:

sudo systemctl restart sshd

Now your connections will appear on your Guacamole Home as shown:

Click on the desired connection to initiate it. For example, for ssh login to the Rocky8 server, click on it and you will see the login prompt as shown:

End the session using exit on your terminal you can still reconnect/ go to the Home page/ Logout from the Guacamole server whenever you want from any device i.e. computer, phone, tablet etc.

You can also use other Authentication Methods as shown here:

• Guacamole Integration with Active Directory, OTP, and Duo 2FA

To configure SSL check out our article:

• Configure Nginx Proxy For Guacamole With Let’s Encrypt SSL

Conclusion

That is it! You can add more connections to your Guacamole Remote Desktop server. I have triumphantly demonstrated how to install and use Guacamole Remote Desktop on Debian Linux system. I hope this was helpful.

See more articles:

• Install and Use Guacamole Remote Desktop on CentOS 8
• Install and Use Guacamole Remote Desktop on Ubuntu
• Install NoMachine Remote Desktop Tool on Ubuntu & Debian
• The Future of Remote Desktop on Smartphone