How to Install Guacamole to Access Your Computers from Anywhere in Ubuntu

Apache Guacamole is a clientless open-source web-based gateway that provides remote access to servers and even client PCs via a web browser using protocols such as SSH, VNC and RDP.

Apache Guacamole comprises 2 main components:

  • Guacamole Server: This provides all the server-side and native components required by Guacamole to connect to remote desktops.
  • Guacamole Client: This is an HTML 5 web application and a client that allows you to connect to your remote servers/desktops. This is underpinned by the Tomcat server.

In this article, we will walk you through the installation of Apache Guacamole on Ubuntu 20.04.


Before you start, ensure that you have the following:

Let’s now delve in and install Guacamole on Ubuntu 20.04 LTS.

On this page

Step 1: Installing Apache Guacamole in Ubuntu Server

1. The installation of Apache Guacamole is done by compiling the source code. For this to be achieved, some build tools are required as a prerequisite. Therefore, run the following apt command:

$ sudo apt-get install make 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 libvncserver-dev libtelnet-dev libssl-dev libvorbis-dev libwebp-dev

2. Once the installation of the build tools is complete, proceed and download the latest tarball source file from Guacamole’s release page. At the time of penning down this guide, the latest release is Guacamole version 1.2.0. To download the latest tarball file, just run the wget command below.

$ wget

3. Next, extract the Guacamole tarball file and navigate into the uncompressed folder.

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

4. Thereafter, execute the configure script to verify if there are any missing dependencies. This usually takes two minutes or so, so be patient as the script performs the dependency check. A barrage of output will be displayed including details about the server version as shown.

$ ./configure --with-init-dir=/etc/init.d
Run Guacamole Configure Script
Run Guacamole Configure Script

5. To compile and install Guacamole, run the commands below, one after the other.

$ sudo make
$ sudo make install

6. Then run the ldconfig command to create any relevant links and cache to the most recently shared libraries in the Guacamole server directory.

$ sudo ldconfig

7. To get the Guacamole server running, we will start the Guacamole Daemon – guacd – and enable it on boot-up and verify the status as shown.

$ sudo systemctl start guacd
$ sudo systemctl enable guacd
$ sudo systemctl status guacd
Check Guacamole Status
Check Guacamole Status

Step 2: Installing Tomcat on Ubuntu Server

8. Tomcat server is a requirement as it will be used to serve the Guacamole client content to users who connect to the server through a browser. Therefore, run the following command to get Tomcat installed:

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

9. Upon installation, the Tomcat server should be up and running. You can confirm the status of the server as shown:

$ sudo systemctl status tomcat
Check Tomcat Status
Check Tomcat Status

10. If Tomcat is not running, start and enable it on boot:

$ sudo systemctl start tomcat
$ sudo systemctl enable tomcat

11. By default, Tomcat runs on port 8080 and if you have the UFW running, you need to allow this port as shown:

$ sudo ufw allow 8080/tcp
$ sudo ufw reload

Step 3: Installing Guacamole Client in Ubuntu

12. With the Tomcat server installed, We will proceed to install the Guacamole client which is a Java-based web application that allows users to connect to the server.

First, we will create a configuration directory as shown.

$ sudo mkdir /etc/guacamole

13. We are going to download the Guacamole client binary to the /etc/guacamole directory using the command as shown.

$ sudo wget -O /etc/guacamole/guacamole.war

14. Once downloaded, create a symbolic link to the Tomcat WebApps directory as shown.

$ ln -s /etc/guacamole/guacamole.war /var/lib/tomcat9/webapps/

15. To deploy the web app, restart both the Tomcat server and the Guacamole daemon.

$ sudo systemctl restart tomcat9
$ sudo systemctl restart guacd

Step 4: Configuring Guacamole Client in Ubuntu

There are 2 major configuration files associated with Guacamole; the /etc/guacamole and the /etc/guacamole/ file which is used by Guacamole and it’s extensions.

16. Before proceeding, We need to create directories for the extensions and libraries.

$ sudo mkdir /etc/guacamole/{extensions,lib}

17. Next, configure the home directory environment variable and append it to the /etc/default/tomcat9 configuration file.

$ sudo echo "GUACAMOLE_HOME=/etc/guacamole" >> /etc/default/tomcat9

Step 5: Configuring Guacamole Server Connections in Ubuntu

18. To determine how Guacamole connects to the Guacamole daemon – guacd – we will create the file as shown.

$ sudo vim /etc/guacamole/

Add the content below and save the file.

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

19. Next, we will create the user-mapping.xml file that defines the users that can connect and login to Guacamole via the web interface on a browser.

Before doing so we need to generate a hashed password for the login user as shown. Be sure to replace your strong password with your own password.

$ echo -n yourStrongPassword | openssl md5

You should get something like this.

(stdin)= efd7ff06c71f155a2f07fbb23d69609

Copy the hashed password and save it somewhere as you will need this in the user-mapping.xml file.

20. Now create the user-mapping.xml file.

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

Paste the content below.

<user-mapping> <authorize username="tecmint" password="efd7ff06c71f155a2f07fbb23d69609" encoding="md5"> <connection name="Ubuntu20.04-Focal-Fossa"> <protocol>ssh</protocol> <param name="hostname"></param> <param name="port">22</param> <param name="username">root</param> </connection> <connection name="Windows Server"> <protocol>rdp</protocol> <param name="hostname"></param> <param name="port">3389</param> </connection> </authorize>

We have defined two connection profiles that allow you to connect to 2 remote systems which are online:

  • Ubuntu 20.04 Server – IP: via SSH protocol
  • Windows Server – IP: via RDP protocol

21. To effect the changes, restart the Tomcat server and Guacamole:

$ sudo systemctl restart tomcat9
$ sudo systemctl restart guacd

To this point, the Guacamole server and client has been configured. Let’s now access Guacamole web UI using the browser.

Step 6: Accessing Guacamole Web UI

22. To access the Guacamole web UI, open your browser and browse your server’s address as shown:

Apache Guacamole Login
Apache Guacamole Login

23. Login using the credentials that you specified in the user-mapping.xml file. Upon logging in, you will find the server connections that you defined in the file listed at the button under the ALL CONNECTIONS section.

Guacamole Server Connections
Guacamole Server Connections

24. To access the Ubuntu 20.04 LTS server, click on the connection and this initiates an SSH connection to the remote Ubuntu server. You will be prompted for the password and once you type it in and hit ENTER, you will be logged in to the remote system as shown.

Access Ubuntu Server Using Guacamole Web
Access Ubuntu Server Using Guacamole Web

For the Windows server machine, click on the respective server connection and provide the password to log in to the server via RDP.

And this wraps up our guide where we showed you how to install and configure Guacamole on Ubuntu 20.04 LTS.

Posted by Contributor