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.

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.


        <connection name="Ubuntu20.04-Focal-Fossa">
            <param name="hostname"></param>
            <param name="port">22</param>
            <param name="username">root</param>
        <connection name="Windows Server">
            <param name="hostname"></param>
            <param name="port">3389</param>

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.

James Kiarie
This is James, a certified Linux administrator and a tech enthusiast who loves keeping in touch with emerging trends in the tech world. When I'm not running commands on the terminal, I'm taking listening to some cool music. taking a casual stroll or watching a nice movie.

Each tutorial at TecMint is created by a team of experienced Linux system administrators so that it meets our high-quality standards.

Join the TecMint Weekly Newsletter (More Than 156,129 Linux Enthusiasts Have Subscribed)
Was this article helpful? Please add a comment or buy me a coffee to show your appreciation.


Leave a Reply
  1. Ubuntu20.04-Focal-Fossa>

    causes login problems, it should be


    there is a missing end quote at the end.

  2. lcladm@Guac:$ echo “GUACAMOLE_HOME=/etc/guacamole” >> /etc/default/tomcat9
    -bash: /etc/default/tomcat9: Permission denied

    Can’t login.. with the user in the user-mapping.xml

  3. James, I’m not sure I saw many say thanks in the comments! So … Thank you! Saved me quite a bit of time to get my environment running. I had a couple of challenges after the installation but googled the solutions.

    1) Newer Windows (>7/2012r2) systems use NLA security. Adding “nla” to your RDP protocol block will help with that.
    2) Adding true to your RDP protocol block will also make your life a little easier.

    Thank you again for your awesome instructions!!!

  4. Hi,

    I am able to get to the webpage of guacamole , but the login fails. What gives? i have same probleme i cannot log in to my page guacamole i followed all the steps and i can open the page guacamole but cant’t login on it. Can someone explain to me why? the usrename I use guadmin and password guacadmin also my version is ubuntu 20.0.4.

  5. Hi,

    In my server it didn’t find on the systemd on this step:

    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.

    ubuntu@faizal-ubuntu-1804:~/guacamole-server-1.2.0$ sudo /etc/init.d/guacd status
    guacd is not running.

    is there any step missing?

    Thank you.

    • Hey Faizal, kindly follow all the steps outlined in the guide. Also, I hope you are using Ubuntu 20.04 and later versions?

    • Hey Bud, kindly ensure that you’ve specified the correct username and password. The password, in this case, should be the password you hashed in Step 5, point no. 19.

          • I am finding this in logs when trying to log in:

            /var/log/tomcat9/localhost_access_log.2021-08-01.txt <==
   – – [01/Aug/2021:22:38:54 +0200] "POST /guacamole/api/tokens HTTP/1.1" 403 279
   – – [01/Aug/2021:22:40:30 +0200] "POST /guacamole/api/tokens HTTP/1.1" 403 279

            by the way, I m using Linux Mint.

            4.15.0-54-generic #58-Ubuntu SMP Mon Jun 24 10:55:24

          • I found the problem should be there is a missing end quote to the server name here. once fixed I got in.

    • I’m using sudo since I’m creating a configuration file in the /etc directory which can only be done using elevated privileges. In other words, that’s a reserve for the root user, hence the use of sudo.

  6. I used docker. It’s a much better way to go for ease of upgrade and no changes to the actual system. The guacamole system consists of a database, guacd, and the guacamole server. I recommend docker and don’t try to install this all on your primary system. It’s messy.

  7. Hello,

    Can you protect it with fail2ban?

    I have tried many regex without success.

    #failregex = ^.*\nWARN: o.a.g.r.auth.AuthenticationService - Authentication attempt from  for user "[^"]*" failed\.$
    #failregex = Authentication attempt from  for user "[^"]*" failed\.$
    #failregex = \bAuthentication attempt from \[(?:,.*)?\] for user ".*" failed\.
    #failregex = ^.*WARN  o\.a\.g\.r\.auth\.AuthenticationService - Authentication attempt from  for user "[^"]*" failed\.$
    #datepattern = ^%%H:%%M:%%S\.%%f
    #failregex = ^\s*\[[^\]]+\] \S+ \S*auth.AuthenticationService - (?:Anonymous )?[Aa]authentication 
    attempt from \[(?:,[^\]]*)?\] (?:for user (?:"[^"]*" )?)?failed\.\s*$
    #failregex = ^.*WARN  o\.a\.g\.r\.auth\.AuthenticationService - Authentication attempt from  for user "[^"]*" failed\.$
    failregex = \bAuthentication attempt from \[(?:,.*)?\] for user ".*" failed\.

Got Something to Say? Join the Discussion...

Thank you for taking the time to share your thoughts with us. We appreciate your decision to leave a comment and value your contribution to the discussion. It's important to note that we moderate all comments in accordance with our comment policy to ensure a respectful and constructive conversation.

Rest assured that your email address will remain private and will not be published or shared with anyone. We prioritize the privacy and security of our users.