Install Guacamole on Debian 11

In this guide, you will learn how to install Guacamole on Debian 11. Apache Guacamole is a client-less HTML5 web based remote desktop gateway which provides remote access to servers and desktops through a web browser. It supports standard protocols like VNC, RDP, and SSH.

Using Debian 12? Try this guide below;

How to Install Guacamole on Debian 12

Installing Guacamole on Debian 11

Guacamole is made up of two parts;

• guacamole-server, which provides the guacd proxy and all the native, server-side components required by Guacamole to connect to remote desktops.
• guacamole-client which provides the client to be served by the servlet container which is usually Tomcat.

You need to install both of these components to setup Apache Guacamole web-based remote desktop client.

Install Guacamole Server on Debian 11

Run system Update

Ensure your system package cache is up-to-date;

apt update

Install Required Build Tools

To install guacamole-server, you need to build it from the source. This, therefore, requires that you need install the required build tools before you can start to build guacamole-server component;

apt install -y build-essential libcairo2-dev libjpeg62-turbo-dev \
libpng-dev libtool-bin libossp-uuid-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 vim

A comprehensive description of these dependency tools is available on required dependencies section.

Download Guacamole Source Code Tarball

To install Guacamole, we will build it from the source code. Hence download the latest source archive tarball from Guacamole releases page.

Apache Guacamole 1.3.0 is the latest release version as of this writing.

You can simply run the command below to download Apache Guacamole 1.3.0.

To make this easy, just set a variable for the current stable release version on the terminal.

VER=1.3.0

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

Once the download is done, extract the source tarball.

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

Install Apache Guacamole on Debian 11

Navigate to guacamole server source code directory;

cd guacamole-server-$VER

Run the configure script to check if any required dependency is missing and to adapt Guacamole server to your system.

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

For more configure options, run, ./configure --help.

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

   Library status:

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

   Protocol support:

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

   Services / tools:

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

   FreeRDP plugins: /usr/lib/x86_64-linux-gnu/freerdp2
   Init scripts: no
   Systemd units: /etc/systemd/system/

Type "make" to compile guacamole-server.

Pay attention to out of the configure script.

Compile and install Guacamole Server on Debian 11;

make

make install

Next, run the ldconfig command to create the necessary links and cache to the most recent shared libraries found in the guacamole server directory.

ldconfig

Running Guacamole-Server on Debian 11

Reload systemd configuration files and start and enable guacd (Guacamole Daemon) to run on boot after the installation.

systemctl daemon-reload

systemctl enable --now guacd

To check the status;

systemctl status guacd

● guacd.service - Guacamole Server
     Loaded: loaded (/etc/systemd/system/guacd.service; enabled; vendor preset: enabled)
     Active: active (running) since Sat 2021-09-11 20:37:14 EAT; 9s ago
       Docs: man:guacd(8)
   Main PID: 27120 (guacd)
      Tasks: 1 (limit: 1133)
     Memory: 10.1M
        CPU: 29ms
     CGroup: /system.slice/guacd.service
             └─27120 /usr/local/sbin/guacd -f

Sep 11 20:37:14 debian11 systemd[1]: Started Guacamole Server.
Sep 11 20:37:14 debian11 guacd[27120]: Guacamole proxy daemon (guacd) version 1.3.0 started
Sep 11 20:37:14 debian11 guacd[27120]: Listening on host 127.0.0.1, port 4822
Sep 11 20:37:15 debian11 guacd[27120]: guacd[27120]: INFO:        Guacamole proxy daemon (guacd) version 1.3.0 started
Sep 11 20:37:15 debian11 guacd[27120]: guacd[27120]: INFO:        Listening on host 127.0.0.1, port 4822

Install Tomcat Servlet

Apache Tomcat is used to serve guacamole client content to users that connects to guacamole server via the web browser. To install Tomcat, run the command below;

apt install tomcat9 tomcat9-admin tomcat9-common tomcat9-user -y

Tomcat9 is started and enabled to run on system boot upon installation. Check the status by running the command below;

systemctl status tomcat9.service

● tomcat9.service - Apache Tomcat 9 Web Application Server
     Loaded: loaded (/lib/systemd/system/tomcat9.service; enabled; vendor preset: enabled)
     Active: active (running) since Sat 2021-09-11 20:41:13 EAT; 1min 10s ago
       Docs: https://tomcat.apache.org/tomcat-9.0-doc/index.html
    Process: 28792 ExecStartPre=/usr/libexec/tomcat9/tomcat-update-policy.sh (code=exited, status=0/SUCCESS)
   Main PID: 28796 (java)
      Tasks: 29 (limit: 1133)
     Memory: 88.5M
        CPU: 5.298s
     CGroup: /system.slice/tomcat9.service
             └─28796 /usr/lib/jvm/default-java/bin/java -Djava.util.logging.config.file=/var/lib/tomcat9/conf/logging.properties -Djava.util.logging.manager=org.apache.jul>

Sep 11 20:41:17 debian11 tomcat9[28796]: Deployment of deployment descriptor [/etc/tomcat9/Catalina/localhost/manager.xml] has finished in [2,068] ms
Sep 11 20:41:17 debian11 tomcat9[28796]: Deploying deployment descriptor [/etc/tomcat9/Catalina/localhost/host-manager.xml]
Sep 11 20:41:17 debian11 tomcat9[28796]: The path attribute with value [/host-manager] in deployment descriptor [/etc/tomcat9/Catalina/localhost/host-manager.xml] has been>
Sep 11 20:41:18 debian11 tomcat9[28796]: At least one JAR was scanned for TLDs yet contained no TLDs. Enable debug logging for this logger for a complete list of JARs that>
Sep 11 20:41:18 debian11 tomcat9[28796]: Deployment of deployment descriptor [/etc/tomcat9/Catalina/localhost/host-manager.xml] has finished in [843] ms
Sep 11 20:41:18 debian11 tomcat9[28796]: Deploying web application directory [/var/lib/tomcat9/webapps/ROOT]
Sep 11 20:41:19 debian11 tomcat9[28796]: At least one JAR was scanned for TLDs yet contained no TLDs. Enable debug logging for this logger for a complete list of JARs that>
Sep 11 20:41:19 debian11 tomcat9[28796]: Deployment of web application directory [/var/lib/tomcat9/webapps/ROOT] has finished in [931] ms
Sep 11 20:41:19 debian11 tomcat9[28796]: Starting ProtocolHandler ["http-nio-8080"]
Sep 11 20:41:19 debian11 tomcat9[28796]: Server startup in [4047] milliseconds

Apache Tomcat listens on port 8080/tcp by default;

ss -altnp | grep 80

LISTEN 0      100                *:8080            *:*    users:(("java",pid=24615,fd=37))

To allow external access to the serverlet, open the serverlet port 8080/tcp on UFW, if at all UFW is installed and enabled.

ufw allow 8080/tcp

Install Guacamole Client on Debian 11

guacamole-client contains provides web application that will serve the HTML5 Guacamole client to users that connect to your server. The web application will then connect to guacd on behalf of connected users in order to serve them any remote desktop they are authorized to access.

Create Guacamole configuration directory;

mkdir /etc/guacamole

Download Guacamole-client Binary

Guacamole client can be installed from source code or from ready binary. Binary installation is used in this demo.

Download Guacamole-client from Guacamole releases page for the respective latest version (v1.3.0 as of this writing) and store it in the configuration directory created above.

To download the current release version, v1.3.0 as of this writing, simply run the command below;

Similarly, we use the same client version variable;

VER=1.3.0

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

Create a symbolic link of the guacamole client to Tomcat webapps directory as shown below;

ln -s /etc/guacamole/guacamole.war /var/lib/tomcat9/webapps/

Restart Tomcat and Guacamole server to deploy the new web application;

systemctl restart tomcat9 guacd

Configure Apache Guacamole on Debian 11

Guacamole has two major configuration files;

• /etc/guacamole which is referenced by the GUACAMOLE_HOME environment variable
• /etc/guacamole/guacamole.properties which is the main configuration file used by Guacamole and its extensions.

There are also guacamole extensions and libraries configurations. You need to create the directories for these configs;

mkdir /etc/guacamole/{extensions,lib}

Set the guacamole home directory environment variable and add it to /etc/default/tomcat9 configuration file.

echo "GUACAMOLE_HOME=/etc/guacamole" >> /etc/default/tomcat9

Configure Guacamole Server Connections

To define how Guacamole connects to guacd, create the guacamole.properties file under /etc/guacamole directory with the following content.

cat > /etc/guacamole/guacamole.properties << EOL
guacd-hostname: localhost
guacd-port: 4822
user-mapping:   /etc/guacamole/user-mapping.xml
auth-provider:  net.sourceforge.guacamole.net.basic.BasicFileAuthenticationProvider
EOL

Next, link the Guacamole configurations directory to Tomcat servlet directory as shown below.

ln -s /etc/guacamole /usr/share/tomcat9/.guacamole

Configure Guacamole Authentication Method

Guacamole’s default authentication method reads all users and connections from a single file called user-mapping.xml.

In this file,you need to define the users allowed to access Guacamole web UI, the servers to connect to and the method of connection.

Other authentication methods are supported, but beyond the scope of this tutorial.

To begin with, generate the MD5 hash of passwords for the user to be used for logging into Guacamole web user interface.

Replace your password accordingly;

echo -n password | openssl md5

Output;

(stdin)= 5f4dcc3b5aa765d61d8327deb882cf99

or

printf '%s' password | md5sum

Output;

5f4dcc3b5aa765d61d8327deb882cf99  -

Be sure to replace password with your strong password.

Next, create the default user authentication file, user-mapping.xml with the following contents.

vim /etc/guacamole/user-mapping.xml

<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="guacadmin"
            password="5f4dcc3b5aa765d61d8327deb882cf99"
            encoding="md5">

        <!-- First authorized Remote connection -->
        <connection name="Rocky Linux 8 Server SSH">
            <protocol>ssh</protocol>
            <param name="hostname">192.168.60.19</param>
            <param name="port">22</param>
        </connection>

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

    </authorize>

</user-mapping>

If you dont specify the username and password in the file, you will be prompted to provide them while attempting to login, which i consider it abit secure.

If you need to explicitly define usernames and passwords in the configuration file, add the parameters;

<param name="username">USERNAME</param>
<param name="password">PASSWORD</param>

Save and exit the configuration file.

Restart both Tomcat and guacd to effect the changes.

systemctl restart tomcat9 guacd

Be sure to check the syslog, /var/log/syslog or /var/log/tomcat9/ log files for any issues.

Accessing Apache Guacamole from Browser

Apache Guacamole server is now setup. You can access it from web browser using the address http://server-IP:8080/guacamole.

Use the credentials for the user whom you generated an MD5 hash for its password above.

Upon successful login, you get to Apache Guacamole web dashboard and you should be able to see the added connections.

Click on a connection to name to initiate remote login.

For example, to ssh into Rocky Linux server, just click on the connection name. This will get you a login prompt;

To login to Windows 7 via RDP, just click on Windows 7;

How to fix RDP server closed/refused connection: Security negotiation failed (wrong security type?)

If you encounter CONNECTION ERROR, and upon checking the logs;

tail -f /var/log/syslog

Sep 11 21:45:45 debian11 guacd[1109]: FreeRDP initialization may fail: The current user's home directory ("/usr/sbin") is not writable, but FreeRDP generally requires a writable home directory for storage of configuration files and certificates.
Sep 11 21:45:45 debian11 guacd[1109]: guacd[1109]: WARNING:#011FreeRDP initialization may fail: The current user's home directory ("/usr/sbin") is not writable, but FreeRDP generally requires a writable home directory for storage of configuration files and certificates.
Sep 11 21:45:45 debian11 guacd[1109]: No security mode specified. Defaulting to security mode negotiation with server.
Sep 11 21:45:45 debian11 guacd[1109]: guacd[1109]: INFO:#011No security mode specified. Defaulting to security mode negotiation with server.
Sep 11 21:45:45 debian11 guacd[1109]: Resize method: none

Sep 11 21:45:45 debian11 guacd[1109]: guacd[1109]: INFO:#011RDP server closed/refused connection: Security negotiation failed (wrong security type?)

Then fix it as follows;

Guacamole server (guacd) service runs as user daemon by default.

ps aux | grep -v grep| grep guacd

daemon       635  0.0  1.4 625480 14864 ?        Ssl  21:08   0:00 /usr/local/sbin/guacd -f
daemon       680  0.3  4.1 449468 41944 ?        Sl   21:09   0:08 /usr/local/sbin/guacd -f
daemon       804  0.0  3.9 359520 39488 ?        Sl   21:41   0:00 /usr/local/sbin/guacd -f

Create a guacd system user account which can be used to run guacd instead of running as daemon user.

useradd -M -d /var/lib/guacd/ -r -s /sbin/nologin -c "Guacd User" guacd

mkdir /var/lib/guacd

chown -R guacd: /var/lib/guacd

Next, update the Guacd service user;

sed -i 's/daemon/guacd/' /etc/systemd/system/guacd.service

Reload systemd daemon;

systemctl daemon-reload

Restart Guacd Service;

systemctl restart guacd

At this point, RDP should work without any issues.

You can now add more connections to your Guacamole. Check Guacamole connections page on how to configure.

Related guides;

Install Apache Guacamole on Rocky Linux 8

Setup Apache Guacamole OpenLDAP Authentication

Configure Guacamole SSL/TLS with Nginx Reverse Proxy

How to Enable RDP/SSH File Transfer Over Guacamole