Install and Use Guacamole Remote Desktop on Debian 10 (Buster)

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 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 access computers from any device.
• Provides easy access to a group.
• Enables one 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.

Getting Started

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

sudo apt update
sudo apt install -y 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

sudo echo "deb http://deb.debian.org/debian buster-backports main" > /etc/apt/sources.list.d/backports.list
sudo apt update
sudo apt install freerdp2-dev/buster-backports

Step 1: Install Apache Tomcat on Debian 10

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

sudo apt install openjdk-11-jdk

Check the installed version

$ java --version
openjdk 11.0.12 2021-07-20
OpenJDK Runtime Environment (build 11.0.12+7-post-Debian-2deb10u1)
OpenJDK 64-Bit Server VM (build 11.0.12+7-post-Debian-2deb10u1, mixed mode, sharing)

Create Tomcat user

This user is used to run the Apache Tomcat application.

sudo useradd -m -U -d /opt/tomcat -s /bin/false tomcat

Download and Install Apache Tomcat on Debian 10

Install the latest version of Apache Tomcat from the official downloads page. At the time of this article, the latest version was 9.0.52

wget https://downloads.apache.org/tomcat/tomcat-9/v9.0.52/bin/apache-tomcat-9.0.52.tar.gz

Extract your download to /opt/tomcat as below:

sudo tar -xzf apache-tomcat-9.0.52.tar.gz -C /opt/tomcat/
sudo mv /opt/tomcat/apache-tomcat-9.0.52 /opt/tomcat/tomcatapp

Tomcat is run by Tomcat user, so we grant privileges of the file to tomcat users as below.

sudo chown -R tomcat: /opt/tomcat

Then we make the files executable:

sudo chmod +x /opt/tomcat/tomcatapp/bin/*.sh

Add Tomcat’s systemd service by creating the configuration file at /etc/systemd/system/tomcat.service

sudo vi /etc/systemd/system/tomcat.service

In the created file, paste these lines.

[Unit]
Description=Tomcat 9 servlet container
After=network.target

[Service]
Type=forking

User=tomcat
Group=tomcat

Environment="JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64"
Environment="JAVA_OPTS=-Djava.security.egd=file:///dev/urandom -Djava.awt.headless=true"

Environment="CATALINA_BASE=/opt/tomcat/tomcatapp"
Environment="CATALINA_HOME=/opt/tomcat/tomcatapp"
Environment="CATALINA_PID=/opt/tomcat/tomcatapp/temp/tomcat.pid"
Environment="CATALINA_OPTS=-Xms512M -Xmx1024M -server -XX:+UseParallelGC"

ExecStart=/opt/tomcat/tomcatapp/bin/startup.sh
ExecStop=/opt/tomcat/tomcatapp/bin/shutdown.sh

[Install]
WantedBy=multi-user.target

Start and enable the service to run on boot.

sudo systemctl daemon-reload
sudo systemctl enable --now tomcat

Check the status of the service.

$ sudo systemctl status tomcat
tomcat.service - Tomcat 9 servlet container
   Loaded: loaded (/etc/systemd/system/tomcat.service; enabled; vendor preset: e
   Active: active (running) since Wed 2021-08-11 18:48:32 EDT; 6s ago
  Process: 14440 ExecStart=/opt/tomcat/tomcatapp/bin/startup.sh (code=exited, st
 Main PID: 14447 (java)
    Tasks: 19 (limit: 4915)
   Memory: 137.0M
   CGroup: /system.slice/tomcat.service
           └─14447 /usr/lib/jvm/java-11-openjdk-amd64/bin/java -Djava.util.loggi

Aug 11 18:48:32 debian systemd[1]: Starting Tomcat 9 servlet container...
Aug 11 18:48:32 debian startup.sh[14440]: Tomcat started.
Aug 11 18:48:32 debian systemd[1]: Started Tomcat 9 servlet container.

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 2: Download Guacamole Remote Server on Debian 10

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.3.0

Then download it:

wget https://downloads.apache.org/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 the script, this checks the available dependencies and adapts Guacamole server to them.

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

Sample Output for the above command:

------------------------------------------------
guacamole-server version 1.3.0
------------------------------------------------

   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 3: Install Guacamole Remote Desktop on Debian 10

After making the above check, now it is time to install Guacamole to our Debian 10 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

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.

$ sudo systemctl status guacd
 guacd.service - LSB: Guacamole proxy daemon
   Loaded: loaded (/etc/init.d/guacd; generated)
   Active: active (running) since Wed 2021-08-11 19:00:44 EDT; 13s ago
     Docs: man:systemd-sysv-generator(8)
    Tasks: 1 (limit: 4915)
   Memory: 10.2M
   CGroup: /system.slice/guacd.service
           └─25680 /usr/local/sbin/guacd -p /var/run/guacd.pid

Aug 11 19:00:43 debian systemd[1]: Starting LSB: Guacamole proxy daemon...
Aug 11 19:00:43 debian guacd[25678]: Guacamole proxy daemon (guacd) version 1.3.
Aug 11 19:00:43 debian guacd[25677]: Starting guacd: guacd[25678]: INFO:        
Aug 11 19:00:44 debian guacd[25677]: SUCCESS
Aug 11 19:00:44 debian systemd[1]: Started LSB: Guacamole proxy daemon.
Aug 11 19:00:44 debian guacd[25680]: Listening on host 127.0.0.1, port 4822

Step 4: Configure Apache Guacamole on Debian 10

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.

Additionally, there are also extensions and library configs. You’ll need to create this directory.

mkdir /etc/guacamole

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 vi /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

Create a link between the Guacamole configurations directory and Tomcat servlet.

sudo ln -s /etc/guacamole /opt/tomcat/tomcatapp/.guacamole

Step 5: Set Guacamole 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. Begin by generating MD5 passwords to be used for logging on to Guacamole’s web UI. Remember to replace Passw0rd with your desired strong password

$ echo -n Passw0rd | openssl md5
(stdin)= d41e98d1eafa6d6011d3a70f1a5b92f0

Alternatively use:

$ printf '%s' Passw0rd | md5sum
d41e98d1eafa6d6011d3a70f1a5b92f0  -

Next, create the user authentication file (user-mapping.xml) as below.

sudo vi /etc/guacamole/user-mapping.xml

In the created file, add this content replacing the appropriate details

<user-mapping>
        
    <!-- Per-user authentication and config information -->

    <!-- A user using md5 to hash the password
         guacadmin user and its md5 hashed password below is used to 
             login to Guacamole Web UI-->
    <authorize 
            username="admin"
            password="5f4dcc3b5aa765d61d8327deb882cf99"
            encoding="md5">

        <!-- First authorized Remote connection -->
        <connection name="Ubuntu 20.04 Server SSH">
            <protocol>ssh</protocol>
            <param name="hostname">192.168.1.15</param>
            <param name="username">thor</param>
            <param name="port">22</param>
        </connection>

        <!-- Second authorized remote connection -->
        <connection name="Windows 10 RDP">
            <protocol>rdp</protocol>
            <param name="hostname">192.168.1.20</param>
            <param name="port">3389</param>
            <param name="username">techviewleo</param>
            <param name="ignore-cert">true</param>
        </connection>

    </authorize>

</user-mapping>

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

VER=1.3.0

Then download it as below

wget https://downloads.apache.org/guacamole/$VER/binary/guacamole-$VER.war -O /etc/guacamole/guacamole.war

mv /etc/guacamole/guacamole.war /opt/tomcat/tomcatapp/webapps/guacamole.war

With these changes made, we need to restart both Tomcat and guacd.

sudo systemctl restart tomcat guacd

Allow guacd port through the firewall.

sudo ufw allow 4822/tcp

Step 6: 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:

Enter the set credentials you set above. (I created an admin user with password as Passw0rd) On successful login, you should see this Guacamole dashboard and the added connections.

Click on the name to initiate the remote connection. for example, for ssh login to the ubuntu server, click on it and you will see the login prompt as shown:

Enter the password and connect to the remote server.

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 e.t.c.

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 10 (Buster). I hope this was helpful.

See more articles: