Set Up Apache Guacamole Remote Desktop on Ubuntu 20.04 Server

This tutorial will be showing you how to set up Guacamole remote desktop on Ubuntu 20.04 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 Ubuntu 20.04 server and install dependency packages.

sudo apt update

sudo apt install build-essential libcairo2-dev libjpeg-turbo8-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

guacamole server ubuntu 20.04

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

Guacamole proxy daemon

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

sudo ss -lnpt | grep guacd

guacd port 4822

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

ubuntu 20.04 apache tomcat listen port guacamole

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="1060b7b46a3bd36b3a0d66e0127d0517"
         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 Ubuntu 20.04 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 with VNC, so install it with the following command.

sudo apt install xfce4 xfce4-goodies firefox

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

Step 5: Install a VNC Server on Ubuntu 20.04 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.

guacamole tightvncserver password ubuntu 20.04

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 vncserver command creates two files under your home directory.

  • ~/.Xauthrirty
  • ~/.vnc/xstartup

The xstartup file specifies the applications that will be started by TigerVNC server. Edit this file.

nano ~/.vnc/xstartup

Change

#!/bin/sh

to

#!/bin/bash

Because Bash is the standard Shell on Linux. Then comment out the following lines. (Add a # character at the beginning of each line).

xsetroot -solid grey
export XKL_XMODMAP_DISABLE=1
/etc/X11/Xsession

Next, add the following line at the bottom, which will make TigerVNC server start the LXQT desktop environment. The startxfce4 binary is installed by the xfce4-session package.

startxfce4 &

Save and close the file.

Troubleshooting

If your tigerVNC server didn’t create the ~/.vnc/xstartup file and the VNC server failed like below:

tigervncserver -xstartup

Then you can manually create the file.

nano ~/.vnc/xstartup

Add the following lines in the file.

#!/bin/sh

xrdb $HOME/.Xresources
startxfce4 &

Save and close the file.

Creating A Systemd Service

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/vncserv[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).

systemctl status vncserver@1.service ubuntu 20.04

Now TigerVNC Server listens on port 5901.

sudo ss -lnpt | grep vnc

ubuntu 20.04 tigervncserver listening port

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 Ubuntu 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 Ubuntu 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 Ubuntu 20.04.

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

apache guacamole remote desktop login page

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

gucamole xfce remote desktop

Wrapping UP

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

Rate this tutorial
[Total: 5 Average: 5]

11 Responses to “Set Up Apache Guacamole Remote Desktop on Ubuntu 20.04 Server

  • Victor Stadnichenko
    2 weeks ago

    Great, thanks a lot!
    Please add a few lines on its usage.

  • Hello, thanks for the guide, it’s dope!

    I’d like to ask a silly question, kindly bear with me. Which IP in particular would guacamole.example.com point to?

  • Nicolas
    1 week ago

    hi, another excellent tutorial.
    I tried to add to /etc/guacamole/user-mapping.xml this line comand:true and localhost but yet i dont have audio. Some advice?

  • darkaser
    5 days ago

    hello, works the configuration with windows 10?

  • Excellent !!! How we
    can admin guacamole?

  • 香菇肥牛
    4 days ago

    Great guide! Getting rid of VNC client software is extremely useful.

    sudo make

    A useless note here, `make` does not need `sudo` privilege.

  • Bruno Forcier
    1 second ago

    Hi,

    Should I disable and remove the default site?

    Everything works except the reverse proxy…

    Going to :8080/gucamole works though?

    Going to / brings Apache2 It works! web page…

    Any suggestion?

    Thanks

Leave a Comment

  • Comments with links are moderated by admin before published.
  • Your email address will not be published.
  • Use <pre> ... </pre> HTML tag to quote the output from your terminal/console.
  • Please use the community (https://community.linuxbabe.com) for questions unrelated to this article.
  • I don't have time to answer every question. Making a donation would incentivize me to spend more time answering questions.


The maximum upload file size: 2 MB.
You can upload: image.