Install Apache Guacamole on Ubuntu 20.04

Last Updated:

In this guide, we are going to learn how to install Apache Guacamole on Ubuntu 20.04. Apache Guacamole is a clientless 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.

Installing Guacamole on Ubuntu 20.04

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.

Installing Guacamole Server on Ubuntu 20.04

Install Required Build Tools

To install Guacamole, 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 gcc g++ libcairo2-dev libjpeg-turbo8-dev \
libpng-dev libtool-bin libossp-uuid-dev libavcodec-dev \
libavutil-dev libswscale-dev freerdp2-dev libpango1.0-dev \
libssh2-1-dev build-essential libvncserver-dev libtelnet-dev \
libssl-dev libvorbis-dev libwebp-dev libwebsockets-dev libpulse-dev libavformat-dev

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

Building Guacamole-Server on Ubuntu 20.04

To build guacamole-server, download the latest source archive tarball from Guacamole releases page. Guacamole 1.4.0 is the latest release version as of this writing. You can simply run the command below;


Once the download is done, extract the source tarball.

tar xzf guacamole-server-1.4.0.tar.gz

Navigate to guacamole server source code directory;

cd guacamole-server-1.4.0

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

   Library status:

     freerdp2 ............ yes
     pango ............... yes
     libavcodec .......... yes
     libavformat.......... yes
     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 .... yes
      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 Ubuntu 20.04;

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.


Running Guacamole-Server

Start and enable guacd (Guacamole Daemon) to run on boot after the installation.

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 2022-04-09 07:51:36 EAT; 2s ago
       Docs: man:guacd(8)
   Main PID: 21478 (guacd)
      Tasks: 1 (limit: 2318)
     Memory: 9.8M
     CGroup: /system.slice/guacd.service
             └─21478 /usr/local/sbin/guacd -f

Elb 09 07:51:36 koromicha systemd[1]: Started Guacamole Server.
Elb 09 07:51:36 koromicha guacd[21478]: Guacamole proxy daemon (guacd) version 1.4.0 started
Elb 09 07:51:36 koromicha guacd[21478]: guacd[21478]: INFO:        Guacamole proxy daemon (guacd) version 1.4.0 started
Elb 09 07:51:36 koromicha guacd[21478]: Listening on host, port 4822
Elb 09 07:51:36 koromicha guacd[21478]: guacd[21478]: INFO:        Listening on host, 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.

If UFW is running, allow Tomcat  through it.

ufw allow 8080/tcp

Installing Guacamole Client on Ubuntu 20.04

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 a 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.4.0 as of this writing) and store it in the configuration directory created above;

wget -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 to deploy the new web application;

systemctl restart tomcat9

Restart guacd daemon as well;

systemctl restart guacd

Configure Apache Guacamole on Ubuntu 20.04

Guacamole has two major configuration files; /etc/guacamole which is referenced by the GUACAMOLE_HOME environment variable and /etc/guacamole/ 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 file under /etc/guacamole directory with the following content.

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

After that, save the configuration file and 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.

Therefore, run the command below to create this file with the following contents.

vim /etc/guacamole/user-mapping.xml

Be sure to replace password with your strong password.

    <!-- 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="CentOS-Server">
            <param name="hostname"></param>
            <param name="port">22</param>

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



Generate the MD5 hash of passwords for the user used for logging into Guacamole web user interface. Replace you password accordingly;

echo -n password | openssl md5
printf '%s' password | md5sum

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

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

Save and exit the configuration file.

You can check how to enable Guacamole OpenLDAP Authentication;

Setup Apache Guacamole OpenLDAP Authentication

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/CATALINA-* for any issues.

Accessing Apache Guacamole from Browse

Once Guacamole is setup, you can access it from web browser using the address http://server-IP:8080/guacamole.

Install Apache Guacamole on Ubuntu 20.04

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

guacamole web

Click on a connection to name to initiate remote login. For example, SSHing into my CentOS-serve gets a me password prompt since we already defined the user;

guacamole ssh

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

windows7 guacamole

And there you go. Enter your password and proceed to your desktop.

You can now add more connections to your Guacamole. That marks the end of our guide on install Apache Guacamole.

Read more on Guacamole User Guide.

Related Tutorials

How to Setup Guacamole Web-based Remote Desktop Access Tool on Ubuntu 18.04


We're passionate about sharing our knowledge and experiences with you through our blog. If you appreciate our efforts, consider buying us a virtual coffee. Your support keeps us motivated and enables us to continually improve, ensuring that we can provide you with the best content possible. Thank you for being a coffee-fueled champion of our work!

Photo of author
I am the Co-founder of, Linux and the whole FOSS enthusiast, Linux System Admin and a Blue Teamer who loves to share technological tips and hacks with others as a way of sharing knowledge as: "In vain have you acquired knowledge if you have not imparted it to others".

6 thoughts on “Install Apache Guacamole on Ubuntu 20.04”

  1. Hello,

    Thank you for the good documentation.
    I’ve found two issues on this documentation.

    1.) On the first command you forgot to add “build-essential” as a package.
    If you follow this guide on a brand new ubuntu 20.04 you will get a “command not found” at the first “make” command

    2.) The version of FreeRDP2 that comes in the official repo for Ubuntu 20.04 is probably broken it the same way as the one from Ubuntu 18.04.

    I would suggest to install the version hosted in the remmina PPA before starting the installation

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

  2. Hi!

    Thanks for your tutorial!

    I tried to follow it but had no success.

    The first error could be fixed by myself and is addressed in the first comment: Missing build-essentials.

    The error I can’t fix is that trying to start the service guacd raises the error

    Failed to start guacd.service: Unit guacd.service not found.

    Compiling worked fine, also make install. I can start guacd via /etc/init.d but not with systemctl.

    Using Ubuntu 20.04 LTS, completely updated.

    Thanks in advance

    regards Marc

    • I had a similar issue. I think it might have been permission issues on the service script. The following seems to have worked for me:
      sudo chmod +x /etc/init.d/guacd
      sudo update-rc.d guacd defaults
      sudo systemctl start guacd
      sudo systemctl enable guacd


Leave a Comment