Install and use Guacamole remote desktop on Ubuntu 20.04

You can download this article in PDF format via the link below to support us.Download the guide in PDF formatClose

Most administrators consider the convenience of having a location to access the server in the main course every day. In order to meet this need, this guide details the establishment of such a platform. Before the end of this guide, we should have installed a working Apache Guacamole server, which can be used to provide a location to access all servers. Whether it is Windows or Linux, Apache Guacamole can serve you.

Before getting into the crux of this tool, wouldn’t it be great if we knew all the results? Yes, let us continue to uncover the mystery of this tool. Apache Guacamole is a clientless remote desktop gateway that supports standard protocols such as VNC, RDP and SSH. Thanks to HTML5, after installing guacamole on the server, you can access the desktop just by using a web browser.

Guacamole is divided into two parts: guacamole-server and guacamole-client, which provides guacd proxy and related libraries, while guacamole-client provides the client to be served by the servlet container. In most cases, the only resource you need to build is guacamole-server, and downloading the latest guacamole.war from the project website is enough to provide customers.

For CentOS, please refer to: Install and use Guacamole Remote Desktop on CentOS 8

Step 1: Server preparation

Apache Guacamole has many dependencies and we will deal with most of them in this step. Let’s go ahead and install every dependency that Guacamole server needs to breathe and survive. Follow the steps below to install them:

sudo apt update
sudo apt install -y gcc vim curl wget g++ libcairo2-dev libjpeg-turbo8-dev libpng-dev 
libtool-bin libossp-uuid-dev libavcodec-dev libavutil-dev libswscale-dev build-essential 
libpango1.0-dev libssh2-1-dev libvncserver-dev libtelnet-dev 
libssl-dev libvorbis-dev libwebp-dev

Install FreeRDP2

We will install the FreeRDP2 version hosted in the remmina PPA as follows:

sudo add-apt-repository ppa:remmina-ppa-team/freerdp-daily
sudo apt update
sudo apt install freerdp2-dev freerdp2-x11 -y

Once the prerequisites are met, we now have the opportunity to enjoy the main course, which includes more steps to be introduced next.

Step 2: Install Apache Tomcat

In this step, we will install the Apache Tomcat Java servlet container, which will run the Guacamole Java war file and therefore serve the Guacamole Java client. Since it is the Java language, we must first install Java.

sudo apt install openjdk-11-jdk

After the installation is complete, you can check the installed version

$ java --version

openjdk 2020-11-04
OpenJDK Runtime Environment (build
OpenJDK 64-Bit Server VM (build, mixed mode, sharing)

Create Tomcat system user

It is recommended to use a user other than root in the system to run the application. For tomcat, we will create a user that will be used to run the tomcat application.

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

Get Apache Tomcat

You can obtain the Apache Tomcat binary distribution from the following URL: Tomcat official download page. At the time of writing this guide, the latest stable version is 9.0.41.

wget -P ~

The download will be completed, and you will unzip the tar file to the /opt/tomcat directory as follows:

sudo mkdir /opt/tomcat
sudo tar -xzf apache-tomcat-9.0.41.tar.gz -C /opt/tomcat/
sudo mv /opt/tomcat/apache-tomcat-9.0.41 /opt/tomcat/tomcatapp

Since the tomcat user is the user who will run Apache Tomcat, we must grant this user the necessary permissions to the /opt/tomcat directory.Run the following command to achieve this

sudo chown -R tomcat: /opt/tomcat

Then make all shell scripts in the /opt/tomcat/tomcatapp/bin directory executable

sudo chmod +x /opt/tomcat/tomcatapp/bin/*.sh

Next, we are ready to add Tomcat’s Systemd service so that it can be started and stopped as easily as other services in the server.To do this, we will have to create a new file and then populate it with the correct configuration as shown below

$ sudo vim /etc/systemd/system/tomcat.service

Description=Tomcat 9 servlet container



Environment=" -Djava.awt.headless=true"

Environment="CATALINA_OPTS=-Xms512M -Xmx1024M -server -XX:+UseParallelGC"



Our new systemd file is clean. Save it, and then reload the daemon so that the SystemD daemon can read it.

sudo systemctl daemon-reload

Then start the service

sudo systemctl enable --now tomcat

And tomcat should run happily

$ 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 2020-12-18 13:36:34 UTC; 2s ago
    Process: 53538 ExecStart=/opt/tomcat/tomcatapp/bin/ (code=exited, status=0/SUCCESS)
   Main PID: 53545 (java)
      Tasks: 27 (limit: 2204)
     Memory: 137.3M
     CGroup: /system.slice/tomcat.service
             └─53545 /usr/lib/jvm/java-11-openjdk-amd64/bin/java -Djava.util.logging.config.file=/opt/tomcat/to

Tomcat listens on port 8080 by default, you can guess that we need to allow remote access to the application by allowing the port on the firewall. This is as simple as a one-line command, as follows:

sudo ufw allow 8080/tcp

Step 3: Build a guacamole server from source code

guacamole-server contains all the native server-side components that Guacamole needs to connect to the remote desktop. It provides the general C library libguac on which all other native components depend, as well as independent libraries for each supported protocol, and the proxy daemon guacd (the core of guacamole).

download The latest stable version of the Guacamole server

wget -P ~

Extract the source compressed package after downloading

tar xzf ~/guacamole-server-1.2.0.tar.gz

Go to the source code directory of the guacamole server;

cd ~/guacamole-server-1.2.0

Then execute the configure script to check if any required dependencies are missing and adapt the Guacamole server to your system.

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

The above command will result in a long list of output. At the end, you should see the following output with “yes” on the following: RDP, SSH, Telnet, and VNC.

guacamole-server version 1.2.0

   Library status:

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

   Protocol support:

      Kubernetes .... no
      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: /etc/init.d
   Systemd units: no

Type "make" to compile guacamole-server.

After that, just run the make command as suggested by the last message


Please take some time while it performs its operations.Once completed, please follow the steps below to install the Guacamole server

sudo make install

To complete everything, run the ldconfig command to create the necessary links and cache to the latest shared library found in the guacamole server directory.

sudo ldconfig

Refresh it to find the guacd (guacamole agent daemon) service installed in the /etc/init.d/ directory.

sudo systemctl daemon-reload

After reloading, start and enable the guacd service.

sudo systemctl start guacd
sudo systemctl enable guacd

And want to put it on the turbocharger, please check its status.

$ systemctl status guacd

● guacd.service - LSB: Guacamole proxy daemon
     Loaded: loaded (/etc/init.d/guacd; generated)
     Active: active (running) since Fri 2020-12-18 14:03:06 UTC; 8s ago
       Docs: man:systemd-sysv-generator(8)
    Process: 76312 ExecStart=/etc/init.d/guacd start (code=exited, status=0/SUCCESS)
      Tasks: 1 (limit: 2204)
     Memory: 10.1M
     CGroup: /system.slice/guacd.service
             └─76324 /usr/local/sbin/guacd -p /var/run/

Step 4: Install the Guacamole web application

The deployment of Guacamole involves two key files: guacamole.war (it is the file containing the web application) and, which is the main configuration file of Guacamole. The recommended way to use Guacamole is to put these files in a standard location and then create a symbolic link to them so that Tomcat can find them.

guacamole-client contains all the Java and Maven components of Guacamole (guacamole, guacamole-common, guacamole-ext and guacamole-common-js). These components ultimately constitute a web application that will provide an HTML5 guacamole client to users connecting to the server. This web application will connect to the guacd part of the guacamole server on behalf of connected users in order to provide them with any remote desktops they have access to.

Install Guacamole Client on Ubuntu 20.04

The guacamole client can be used as a binary file. To install it, just pull it from the Guacamole binary download page as shown below, copy it to the /etc/guacamole/ directory and rename it at the same time.

sudo mkdir /etc/guacamole
wget -P ~
sudo mv ~/guacamole-1.2.0.war /etc/guacamole/guacamole.war

To install the Guacamole client binaries, create a symbolic link from the guacamole client to the Tomcat webapps directory as shown below;

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

Step 5: Configure the guacamole server

After installing the Guacamole server daemon, you need to define how to connect the Guacamole client to the Guacamole server (guacd) in the /etc/guacamole/ configuration file. In this configuration, you only need to define the hostname, port, user mapping profile, and authentication provider of the Guacamole server.

GUACAMOLE_HOME is the name of Guacamole’s configuration directory, which is located at /etc/guacamole by default. All configuration files, extensions, etc. are located in this directory.

Create GUACAMOLE_HOME environment variable

echo "GUACAMOLE_HOME=/etc/guacamole" | sudo tee -a /etc/default/tomcat

Create and fill in the /etc/guacamole/ configuration file as shown below:

$ sudo vim /etc/guacamole/
guacd-hostname: localhost
guacd-port:    4822
user-mapping:    /etc/guacamole/user-mapping.xml

After configuring as shown above, save it and link the Guacamole configuration directory to the Tomcat servlet directory as shown below.

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

Step 6: Set up the guacamole authentication method

Guacamole’s default authentication method reads all users and connections from a file called user-mapping.xml. In this file, you need to define the users who are allowed to access the Guacamole Web UI, the server to connect to, and the connection method.

Generate an MD5 hash of the password for the user who will be used to log in to the Guacamole web user interface. Replace your password accordingly.

$ echo -n StrongPassword | openssl md5
(stdin)= 0f6e4a1df0cf5ee97c2066953bed21b2

After preparing the password, create a user mapping file with the following sample content. You can put any hostname, username and host according to your environment.

$ sudo vim /etc/guacamole/user-mapping.xml


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

        <!-- First authorized Remote connection -->
        <connection name="RHEL 7 Maipo">
            <param name="hostname"></param>
            <param name="port">22</param>

        <!-- Second authorized remote connection -->
        <connection name="Windows Server 2019">
            <param name="hostname"></param>
            <param name="port">3389</param>
            <param name="username">tech</param>
            <param name="ignore-cert">true</param>



Our progress is very smooth. After completing all operations, restart Tomcat and guacd to implement the changes.

sudo systemctl restart tomcat guacd

If you are running a firewall and have not yet allowed the port, you can do so as quickly as possible as follows:

sudo ufw allow 4822/tcp

Step 7: Get the guacamole web interface

So far, we have set everything up well, so we should be ready to access the application we have been working on. To access Guacamole’s web interface, simply point your browser to http://ip-or-domain-name:8080/guacamole, and the login screen shown below will appear:

As you can see, you have loaded the connection (namely the server name) we established in the configuration file when you logged in.


Simply click on the one you want to connect to and you will be prompted to enter your username and password, whether via SSH or RDP, depending on the operating system.

If the credentials are correct, you should be allowed to enter the server


ul off

Take full advantage of Apache Guacamole to make your environment organized and easy to use, even for new users in your environment. Check it out and take advantage of its flexibility and convenience, especially in this season, in this season, most of us will leave memories with those we care about.

Other guides that may be of interest to you include:

Install and use Guacamole remote desktop on CentOS 8

The easy way to create an SSH tunnel on Linux CLI

Install and configure OpenSSH Server on Windows Server 2019

How to set up two-factor (2FA) authentication for SSH on CentOS/RHEL 7/8

You can download this article in PDF format via the link below to support us.Download the guide in PDF formatClose