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/vncserver@.service

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 vncserver@1.service

Enable auto-start at boot time.

sudo systemctl enable vncserver@1.service

Check its status:

systemctl status vncserver@1.service

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 you@example.com -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 you@example.com -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]

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

  • Victor Stadnichenko
    4 months 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?

  • 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?

    • Audio output is enabled by default in Guacamole. Do you have a sound card on the remote host?

      • Yes, i work in a Raspberry 4

      • yeah, no sound for me too. im running a ubuntu 20.04 LTS on a vps. i enable the pulseaudio(‘pulseaudio -D’) still no sound. the output is ‘dummy’. any advice is appreciate. thanks.

        p/s – i notice this setup is really resource hungry. cant even run firefox with an entry level vps. what spec would you suggest for this?

  • darkaser
    4 months ago

    hello, works the configuration with windows 10?

  • Excellent !!! How we
    can admin guacamole?

  • 香菇肥牛
    4 months 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
    4 months 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

    • Bruno Forcier
      3 months ago

      Replying to my own question.

      Just disable default apache site and reload.

  • Stuck on nano ~/.vnc/xstartup

    VNCServer did not create any such dir that I can find, nor did it create the files.. I’m lost

    • Nevermind, I feel so dumb. The internet I am on takes forever to install anything from the internet (satellite) and it didn’t occur to me to just keep reading. #facepalm

  • 2 things after I have successfully build a Guac server:

    1: What port do I forward to on modem side to access my RDP? Presumably, I go to domain.com or guac.domain.com and it should go to port 80? But 80 takes me to the tomcat page.

    and 2: is there a way to manage Guac “Servers” and view log ins and such?

  • Bruno Forcier
    3 months ago

    Hi,

    I’d like it to log out and go back to login screen or at least lock out session after 5 minutes of inactivity for example.

    I’ve done some google searching and apparently this is done through this command:

    localadmin@virtmgr:~#vncserver −MaxIdleTime 300

    But I haven’t seen any reference as to how to put it in the ~/.vnc/xstartup config file?

    Also, does this keep the vncserver session alive but requiring a new login or does it kill the VNC session? If so, how to make sure the session is restarted if killed?

    I sometimes make the mistake of logging out of the GUI within the guacamole page and it bothers me as I have to ssh and restart the session, any way to have a sort of watchdog that’d respawn the session?

    Regards

    Thanks

  • I rather not install a desktop on a server, can i jump that configuration part? I just want to provide someone with the link to the server and have them put in a password so that I may access their desktop.

    I think having a desktop on the server itself only uses spaces and eats memory in my case.

    • “provide someone with the link to the server and have them put in a password so that I may access their desktop”?

      I’m not sure what you are going to achieve.

      If you simply want to control someone else’s computer, maybe using AnyDesk will be better.

  • I’m looking to create a few users that can login to the server on demand, when instructed to so that we may help them. They are remote users, and they all have different systems. Nota all are using the company’s computer.

    Any desk would be fine, except for the pricing and exchange rate killing this option right now.

    TeamViewer also works but it’s expensive as well. In a team of 4 techs the cost is too much and business is not as strong as before the pandemic. The coast of a self hosted tool is alot cheaper and easier to absorb right now.

    We’ve tried mesh commander as well but the program is always getting removed by the antivirus.

    Anyway. The idea is to make a bridged between the connected computers of a tech and a user.

  • Would it be able to buy a full Hyper-V VM from you, with Guacamole on Ubuntu server. Willing to pay say NZ$100.00?

  • Charles Cox
    3 months ago

    All worked except when i got to the vncserver -kill:1

    david@arcadia:~/Downloads$ sudo nano /etc/systemd/system/vncserver@.service
    david@arcadia:~/Downloads$ vncserver -kill :1
    david@arcadia:~/Downloads$ sudo systemctl start vncserver@1.service
    Job for vncserver@1.service failed because the control process exited with error code.
    See "systemctl status vncserver@1.service" and "journalctl -xe" for details.
    david@arcadia:~/Downloads$ sudo systemctl enable vncserver@1.service
    Created symlink /etc/systemd/system/multi-user.target.wants/vncserver@1.service → /etc/systemd/system/vncserver@.service.
    david@arcadia:~/Downloads$ systemctl status vncserver@1.service
    ● vncserver@1.service - a wrapper to launch an X server for VNC
         Loaded: loaded (/etc/systemd/system/vncserver@.service; enabled; vendor preset: enabled)
         Active: failed (Result: exit-code) since Mon 2020-08-31 14:17:14 CDT; 37s ago
    
    Aug 31 14:17:13 arcadia systemd[1]: Starting a wrapper to launch an X server for VNC...
    Aug 31 14:17:14 arcadia vncserver[117932]: vncserver: Can't fixup permissions of startup script '/home/david/.vnc/xstartu>
    Aug 31 14:17:14 arcadia systemd[1]: vncserver@1.service: Control process exited, code=exited, status=1/FAILURE
    Aug 31 14:17:14 arcadia systemd[1]: vncserver@1.service: Failed with result 'exit-code'.
    Aug 31 14:17:14 arcadia systemd[1]: Failed to start a wrapper to launch an X server for VNC.
    
    david@arcadia:~/Downloads$ sudo ss -lnpt | grep vnc
    david@arcadia:~/Downloads$ sudo systemctl start vncserver@1.service
    Job for vncserver@1.service failed because the control process exited with error code.
    See "systemctl status vncserver@1.service" and "journalctl -xe" for details.
    david@arcadia:~/Downloads$ cd /
    david@arcadia:/$ sudo systemctl start vncserver@1.service
    Job for vncserver@1.service failed because the control process exited with error code.
    See "systemctl status vncserver@1.service" and "journalctl -xe" for details.
    david@arcadia:/$ 
    • i am also getting this same error
      root@apachequacomole:~/.vnc# sudo systemctl restart apache2
      root@apachequacomole:~/.vnc# sudo systemctl start vncserver@1.service
      Job for vncserver@1.service failed because the control process exited with error code.
      See “systemctl status vncserver@1.service” and “journalctl -xe” for details.
      root@apachequacomole:~/.vnc# systemctl status vncserver@1.service
      ● vncserver@1.service
      Loaded: loaded (/etc/systemd/system/vncserver@.service; enabled; vendor preset: enabled)
      Active: failed (Result: exit-code) since Thu 2020-10-22 14:34:29 UTC; 8s ago
      Process: 59630 ExecStartPre=/usr/bin/vncserver -kill :1 > /dev/null 2>&1 (code=exited, status=0/SUCCESS)
      Process: 59645 ExecStart=/usr/bin/vncserver -depth 24 -geometry 1280×800 -localhost :1 (code=exited, status=1/FAILURE)

      Oct 22 14:34:29 apachequacomole systemd[1]: Starting vncserver@1.service…
      Oct 22 14:34:29 apachequacomole vncserver[59645]: You will require a password to access your desktops.
      Oct 22 14:34:29 apachequacomole vncserver[59650]: getpassword error: Inappropriate ioctl for device
      Oct 22 14:34:29 apachequacomole vncserver[59650]: Password:
      Oct 22 14:34:29 apachequacomole systemd[1]: vncserver@1.service: Control process exited, code=exited, status=1/FAILURE
      Oct 22 14:34:29 apachequacomole systemd[1]: vncserver@1.service: Failed with result ‘exit-code’.
      Oct 22 14:34:29 apachequacomole systemd[1]: Failed to start vncserver@1.service.
      Oct 22 14:34:37 apachequacomole systemd[1]: /etc/systemd/system/vncserver@.service:1: Unknown section ‘unit’. Ignoring.
      root@apachequacomole:~/.vnc#

  • I have installed and am getting the login, and a connected message, but then it just hangs never paints any session.

    I’ve only got ssh and rdp clients configured and neither connect.

    I’ve traced guad, and it’s spinning on a connection to it’s port, but getting no action.

    Any suggestions on further debugging? I have turned on the logging from one clue for guacamole but it’s not spitting out much of any clues either into the catalina logs. there are messages there, but not very useful ones, and no “fail” or obvious error messages.

    • This tutorial shows how to connect to a remote VNC desktop. To Connect to SSH or RDP, you need to add additional configs in /etc/guacamole/user-mapping.xml file.

  • ganesh
    1 week ago

    after logging im getting this page please help, can anyone help me explain whats going on ?

  • Jan-Geert Wesselink
    3 seconds ago

    Thanks for the great and fully working instruction. I tried to install Guacamole using different tutorials in ran into issues with non-supported packages. This install guide does only use the Ubuntu native packages, so no not only installation is easy, but packages are also updates using apt. Only guacamole itself is not updated automatically, but that is not possible as it is not an package (yet).

    I am really happy accessing my RDP server at home from anywhere using any native HTML-5 browser. I am using a Cisco ASA Clientless VPN as reverse proxy.

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.