Learn how to - Install Guacamole Remote Desktop on Debian 11 / Debian 10

Felix Williams Debian How to Linux Tutorials April 23, 2023

Learn how to – 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 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:

Guacamole-server- this provides the proxy (guacd) and the required libraries.
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)

Create Tomcat user

This user is used to run the Apache Tomcat application.

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

Install Apache Tomcat on Debian

Install the latest version of Apache Tomcat from the official downloads page.

cd ~/
VER="9.0.75"
wget https://downloads.apache.org/tomcat/tomcat-9/v${VER}/bin/apache-tomcat-${VER}.tar.gz -P ~

Extract your download to /opt/tomcat as below:

sudo tar -xzf apache-tomcat-*.tar.gz -C /opt/tomcat/
sudo mv /opt/tomcat/apache-tomcat-*/ /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 vim /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.

$ systemctl status tomcat
● tomcat.service - Tomcat 9 servlet container
     Loaded: loaded (/etc/systemd/system/tomcat.service; enabled; vendor preset: enabled)
     Active: active (running) since Fri 2023-01-27 09:14:45 UTC; 10s ago
    Process: 12100 ExecStart=/opt/tomcat/tomcatapp/bin/startup.sh (code=exited, status=0/SUCCESS)
   Main PID: 12107 (java)
      Tasks: 29 (limit: 4556)
     Memory: 156.0M
        CPU: 3.361s
     CGroup: /system.slice/tomcat.service
             └─12107 /usr/lib/jvm/java-11-openjdk-amd64/bin/java -Djava.util.logging.config.file=/opt/tomcat/tomcatapp/conf/logging.properties -Djava.util.logging.manager=org.apache.juli.ClassLoade>

Jan 27 09:14:45 debian11 systemd[1]: Starting Tomcat 9 servlet container...
Jan 27 09:14:45 debian11 startup.sh[12100]: Tomcat started.
Jan 27 09:14:45 debian11 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 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.2

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

   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 to 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 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 Fri 2023-01-27 09:21:05 UTC; 15s ago
       Docs: man:systemd-sysv-generator(8)
      Tasks: 1 (limit: 4556)
     Memory: 9.9M
        CPU: 27ms
     CGroup: /system.slice/guacd.service
             └─23813 /usr/local/sbin/guacd -p /var/run/guacd.pid

Jan 27 09:21:05 debian11 systemd[1]: Starting LSB: Guacamole proxy daemon...
Jan 27 09:21:05 debian11 guacd[23811]: Guacamole proxy daemon (guacd) version 1.5.2 started
Jan 27 09:21:05 debian11 guacd[23810]: Starting guacd:
Jan 27 09:21:05 debian11 guacd[23811]: guacd[23811]: INFO:        Guacamole proxy daemon (guacd) version 1.5.2 started
Jan 27 09:21:05 debian11 guacd[23810]: SUCCESS
Jan 27 09:21:05 debian11 guacd[23813]: Listening on host 127.0.0.1, port 4822
Jan 27 09:21:05 debian11 systemd[1]: Started LSB: Guacamole proxy daemon.

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.

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

sudo 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 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

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

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

Step 6: 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 StrongUserPassw0rd | openssl md5
(stdin)= d41e98d1eafa6d6011d3a70f1a5b92f0

Alternatively use:

$ printf '%s' StrongUserPassw0rd | md5sum
d41e98d1eafa6d6011d3a70f1a5b92f0  -

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

sudo vim /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. set the version variable:

VER=1.5.2

Then download it as below

wget https://archive.apache.org/dist/guacamole/$VER/binary/guacamole-$VER.war -O guacamole.war
sudo mv 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 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:

Install Guacamole Remote Desktop on Debian 11 / Debian 10 1

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.

Install Guacamole Remote Desktop on Debian 11 / Debian 10 2

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:

Install Guacamole Remote Desktop on Debian 11 / Debian 10 3

Enter the password and connect to the remote server.

Install Guacamole Remote Desktop on Debian 11 / Debian 10 4

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.

Install Guacamole Remote Desktop on Debian 11 / Debian 10 5

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:

Cart

Learn how to – Install Guacamole Remote Desktop on Debian 11 / Debian 10