Set Up Apache Guacamole Remote Desktop on Debian 10 Buster

This tutorial will be showing you how to set up Guacamole remote desktop on Debian 10 server. Guacamole is a free, open-source remote desktop gateway developed by the Apache software foundation.

Guacamole Features

• It allows you to access your remote desktop from a web browser. No other software needs to be installed on the client-side.
• Supports standard protocols like VNC, RDP, SSH and Kubernetes.
• VNC sessions can be recorded graphically.
• Single Sign-on with CAS, OpenID Connect or SAML 2.0
• Wake-on-LAN
• Easily manage multiple remote desktop sessions.
• Supports TOTP two-factor authentication.
• Supports clipboard (copy and paste) and file transfer via SFTP.
• Supports audio input and output
• and more.

Guacamole itself is not a remote desktop protocol. It’s a proxy between the remote desktop and the client, so the remote desktop can be displayed and controlled in a web browser.

Step 1: Build the Guacamole Server From Source

Log in to your Debian 10 server and install dependency packages.

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

Download the latest stable version of guacamole-server.

wget http://mirror.cc.columbia.edu/pub/software/apache/guacamole/1.2.0/source/guacamole-server-1.2.0.tar.gz

Extract the archive.

tar -xvf guacamole-server-1.2.0.tar.gz

Change to the extracted directory.

cd guacamole-server-1.2.0

Configure the build environment.

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

Then compile guacamole-server.

sudo make

Install the guacamole-server.

sudo make install

Update the system’s cache of installed libraries.

sudo ldconfig

Reload systemd, so it can find the guacd (Guacamole proxy daemon) service installed in /etc/init.d/ directory.

sudo systemctl daemon-reload

Start the guacd service.

sudo systemctl start guacd

Enable auto-start at boot time.

sudo systemctl enable guacd

Check its status.

systemctl status guacd

As you can see, it’s active (running).

Guacd listens on 127.0.0.1:4822, as can be shown with the ss utility.

sudo ss -lnpt | grep guacd

Step 2: Install the Guacamole Web Application

The Guacamole web application is written in Java, so we need to install a Java Servlet container like Apache Tomcat.

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

Apache Tomcat will listen on port 8080, as can been shown with:

sudo ss -lnpt | grep java

If you have other software that listens on port 8080, then Tomcat can’t bind to port 8080. You should configure the other process to use a different port, then restart Tomcat (sudo systemctl restart tomcat9).

Next, download the Guacamole web application.

wget https://downloads.apache.org/guacamole/1.2.0/binary/guacamole-1.2.0.war

Move the file to the web application directory (/var/lib/tomcat9/webapps) and rename the file at the same time (delete the version number).

sudo mv guacamole-1.2.0.war /var/lib/tomcat9/webapps/guacamole.war

Restart Tomcat and guacd.

sudo systemctl restart tomcat9 guacd

Step 3: Configure Guacamole

Create a configuration directory for Guacamole.

sudo mkdir /etc/guacamole/

Create a configuration file.

sudo nano /etc/guacamole/guacamole.properties

Add the following lines in this file. Some folks might say you don’t need to add these lines because they are the default values. I show you a basic configuration, so you can customize it when the need arises.

# Hostname and port of guacamole proxy
guacd-hostname: localhost
guacd-port:     4822

# Auth provider class (authenticates user/pass combination, needed if using the provided login screen)
auth-provider: net.sourceforge.guacamole.net.basic.BasicFileAuthenticationProvider
basic-user-mapping: /etc/guacamole/user-mapping.xml

Save and close the file. The default authentication module in Guacamole reads usernames and passwords from an XML file: /etc/guacamole/user-mapping.xml. Before creating this file, we need to generate an MD5 hash for your password with the following command. Replace your_password with your preferred password.

echo -n your_password | openssl md5

Sample output:

(stdin)= 1060b7b46a3bd36b3a0d66e0127d0517

Next, create the user mapping XML file.

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

Add the following lines. Here we specify that the backend will use VNC (Vritual Network Computing) protocol. Replace the username and the password hash. We will create a VNC password later.

<user-mapping>

    <!-- Per-user authentication and config information -->
    <authorize
         username="your_preferred_username"
         password="1060b7b46a3bd36b3a0d66e0127d051"
         encoding="md5">
      
       <connection name="default">
         <protocol>vnc</protocol>
         <param name="hostname">localhost</param>
         <param name="port">5901</param>
         <param name="password">vnc_password</param>
       </connection>
    </authorize>

</user-mapping>

Save and close the file. Restart Tomcat and guacd.

sudo systemctl restart tomcat9 guacd

Step 4: Install a Desktop Environment on Debian 10 Server

Since we are going to set up a remote desktop, we need a desktop environment. Make sure your server has enough RAM before installing a desktop environment. There are many desktop environments. I found the lightweight XFCE desktop environment works well in VNC, so install it with the following command.

sudo apt update
sudo apt install xfce4 xfce4-goodies

During installation, you may be asked to choose a default display manager. This choice doesn’t matter much, because you will not see the login screen in a VNC session.

Since there’s a desktop environment running on the server, it’s strongly recommended that you use a firewall like UFW to restrict access and open only the necessary ports to the public. You can read the following tutorial to learn how to enable and use UFW on Debian.

• How to Use UFW Firewall on Debian, Ubuntu, Linux Mint

Step 5: Install a VNC Server on Debian 10 Server

There are several VNC server software available for Linux users. We are going to use TigerVNC server because it works best with Guacamole.

sudo apt install tigervnc-standalone-server

Run the following command to start the VNC server.

vncserver

When TigerVNC first starts, it asks you to set a VNC password. Note that the password should not be more than 8 characters. Then you can choose if you need a view-only password.

Now you should edit the /etc/guacamole/user-mapping.xml file and change the VNC password. Then restart Tomcat and guacd.

sudo systemctl restart tomcat9 guacd

The tigervnc-standalone-server package ships with a file /etc/X11/Xvnc-session which tells TigerVNC to launch an X server when it starts.

TigerVNC server doesn’t ship with any systemd service units. To make it start at boot time, we need to create a systemd service unit.

sudo nano /etc/systemd/system/[email protected]

Add the following lines in the file. Replace username with your real username.

[Unit]
Description=a wrapper to launch an X server for VNC
After=syslog.target network.target

[Service]
Type=forking
User=username
Group=username
WorkingDirectory=/home/username

ExecStartPre=-/usr/bin/vncserver -kill :%i > /dev/null 2>&1
ExecStart=/usr/bin/vncserver -depth 24 -geometry 1280x800 -localhost :%i
ExecStop=/usr/bin/vncserver -kill :%i

[Install]
WantedBy=multi-user.target

Save and close the file. Stop the current VNC server instance.

vncserver -kill :1

Start the VNC server with systemd.

sudo systemctl start [email protected]

Enable auto-start at boot time.

sudo systemctl enable [email protected]

Check its status:

systemctl status [email protected]

As you can see, it’s active (running).

Now TigerVNC Server listens on port 5901.

sudo ss -lnpt | grep vnc

Step 6: Set Up a Reverse Proxy for the Guacamole Web Application

Apache Tomcat is listening on port 8080. To have an easy way to access the Guacamole web application, we can set up a reverse proxy with Apache or Nginx, so end-users will be able to use a domain name to access the web application. It also allows us to easily install a TLS certificate to encrypt the connection.

Apache

If you prefer to use Apache, then install Apache from the default Debian software repository.

sudo apt install apache2

To use Apache as a reverse proxy, we need to enable the proxy modules and the header module.

sudo a2enmod proxy proxy_http headers proxy_wstunnel

Then create a virtual host file for Guacamole.

sudo nano /etc/apache2/sites-available/guacamole.conf

Add the following lines in the file. Replace guacamole.example.com with your own domain name. Remember to create an A record for the sub-domain in your DNS manager. If you don’t have a real domain name, I recommend going to NameCheap to buy one. The price is low and they give whois privacy protection free for life.

<VirtualHost *:80>
      ServerName guacamole.example.com

      ErrorLog ${APACHE_LOG_DIR}/guacamole_error.log
      CustomLog ${APACHE_LOG_DIR}/guacamole_access.log combined

      <Location />
          Require all granted
          ProxyPass http://localhost:8080/guacamole/ flushpackets=on
          ProxyPassReverse http://localhost:8080/guacamole/
      </Location>

     <Location /websocket-tunnel>
         Require all granted
         ProxyPass ws://localhost:8080/guacamole/websocket-tunnel
         ProxyPassReverse ws://localhost:8080/guacamole/websocket-tunnel
     </Location>

     Header always unset X-Frame-Options
</VirtualHost>

Save and close the file. Test the Syntax.

sudo apachectl -t

If Syntx is Ok, then enable this virtual host.

sudo a2ensite guacamole.conf

Restart Apache

sudo systemctl restart apache2

Now you can access the Apache Guacamole login page via guacamole.example.com. If you see the “invalid request” or a similar error message, it could mean that Apache Tomcat can’t bind to port 8080, because this port is already taken by another process on the server. You should configure the other process to use a different port, then restart Tomcat.

Nginx

If you prefer to use Nginx, then install Nginx from the default Debian software repository.

sudo apt install nginx

Create a server block file for Guacamole.

sudo nano /etc/nginx/conf.d/guacamole.conf

Add the following lines in the file. Replace guacamole.example.com with your own domain name. Remember to create an A record for the sub-domain in your DNS manager. If you don’t have a real domain name, I recommend going to NameCheap to buy one. The price is low and they give whois privacy protection free for life.

server {
        listen 80;
        listen [::]:80;
        server_name guacamole.example.com;

        access_log  /var/log/nginx/guac_access.log;
        error_log  /var/log/nginx/guac_error.log;

        location / {
                    proxy_pass http://127.0.0.1:8080/guacamole/;
                    proxy_buffering off;
                    proxy_http_version 1.1;
                    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
                    proxy_set_header Upgrade $http_upgrade;
                    proxy_set_header Connection $http_connection;
                    proxy_cookie_path /guacamole/ /;
        }

}

Save and close this file. Then test Nginx configuration.

sudo nginx -t

If the test is successful, reload Nginx for the change to take effect.

sudo systemctl reload nginx

Now you can access the Apache Guacamole login page via guacamole.example.com. If you see the “invalid request” or a similar error message, it could mean that Apache Tomcat can’t bind to port 8080, because this port is already taken by another process on the server. You should configure the other process to use a different port, then restart Tomcat.

Enable HTTPS

To encrypt the HTTP traffic when you visit the Guacamole web interface, we can enable HTTPS by installing a free TLS certificate issued from Let’s Encrypt. Run the following command to install Let’s Encrypt client (certbot) on Debian 10.

sudo apt install certbot

If you use Apache, then you need to install the Certbot Apache plugin.

sudo apt install python3-certbot-apache

Next, run the following command to obtain and install TLS certificate.

sudo certbot --apache --agree-tos --redirect --hsts --staple-ocsp --email [email protected] -d guacamole.example.com

If you use Nginx, then you also need to install the Certbot Nginx plugin.

sudo apt install python3-certbot-nginx

Next, run the following command to obtain and install TLS certificate.

sudo certbot --nginx --agree-tos --redirect --hsts --staple-ocsp --email [email protected] -d guacamole.example.com

Where:

• --nginx: Use the nginx plugin.
• --apache: Use the Apache plugin.
• --agree-tos: Agree to terms of service.
• --redirect: Force HTTPS by 301 redirect.
• --hsts: Add the Strict-Transport-Security header to every HTTP response. Forcing browser to always use TLS for the domain. Defends against SSL/TLS Stripping.
• --staple-ocsp: Enables OCSP Stapling. A valid OCSP response is stapled to the certificate that the server offers during TLS.

The certificate should now be obtained and automatically installed.

And you can access Guacamole web interface via HTTPS. (https://guacamole.example.com).

After logging in, you will be able to use the remote desktop.

Wrapping UP

I hope this tutorial helped you set up Apache Guacamole remote desktop on Debian 10 server. As always, if you found this post useful, then subscribe to our free newsletter to get more tips and tricks. Take care 🙂