Install Guacamole for Remote Linux/Windows Access in Ubuntu

As a system administrator, you may find yourself (today or in the future) working in an environment where Windows and Linux coexist.

It is no secret that some big companies prefer (or have to) run some of their production services in Windows boxes and others in Linux servers.

[ You might also like: 11 Best Tools to Access Remote Linux Desktop ]

If that is your case, you will welcome this guide with open arms (otherwise go ahead and at least make sure to add it to your bookmarks).

Install Guacamole for Remote Desktop and SSH Access
Install Guacamole for Remote Desktop and SSH Access

In this article, we will introduce you to guacamole, a remote desktop gateway powered by Tomcat that only needs to be installed on a central server.

[ You might also like: How to Access Remote Linux Desktop Using TightVNC ]

Guacamole will provide a web-based control panel that will allow you to switch quickly from one machine to another – all within the same web browser window.

Testing Environment

In this article, we have used the following machines. We will install Guacamole in an Ubuntu box and use it to access a Windows 10 box over Remote Desktop Protocol (RDP) and an RHEL box using SSH network protocol:

Guacamole server: Ubuntu 20.04 - IP
Remote SSH box: RHEL 8 – IP
Remote desktop box: Windows 10 – IP

That said, let’s get started.

Installing Guacamole Server in Ubuntu

1. Before installing guacamole, you will need to take care of its dependencies first.

$ 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 freerdp2-dev libwebsockets-dev \
libssl-dev libvorbis-dev libwebp-dev tomcat9 tomcat9-admin tomcat9-user

2. Download and extract the tarball. As of early February 2021, the latest version of Guacamole is 1.3.0. You can refer to the Guacamole Downloads page to find out the latest version at a given time.

$ wget 
$ tar zxf guacamole-server-1.3.0.tar.gz  

3. Compile the software.

$ cd guacamole-server-1.3.0/
$ ./configure

As it is to be expected, configure will check your system for the presence of the required dependencies and for supported communication protocols (as can be seen in the highlighted square, Remote Desktop Protocol (RDP) and SSH are supported by the dependencies installed earlier).

If everything goes as expected you should see this when it completes (otherwise, make sure you installed all the necessary dependencies):

Guacamole Server Installation
Guacamole Server Installation

As the last line in the above image suggests, run make and make install to compile the program:

$ make 
$ sudo make install

4. Update the cache of installed libraries.

$ sudo ldconfig 

and hit Enter.

Installing Guacamole Client in Ubuntu

After completing the above steps, the guacamole server will have been installed. The following instructions will now help you to set up guacd (the proxy daemon that integrates Javascript with communication protocols such as RDP or SSH) and guacamole.war (the client), the component that makes up the final HTML5 application that will be presented to you.

Note that both components (guacamole server and client) need to be installed on the same machine – there is no need to install a so-called client on the machines you want to connect to).

To download the client, follow these steps:

5. Download the web application archive and change its name to guacamole.war.

Note: Depending on your distribution, the Tomcat libraries directory may be located at /var/lib/tomcat.

$ cd /var/lib/tomcat9/
$ sudo wget
$ sudo mv guacamole-1.3.0.war webapps/guacamole.war

6. Create the configuration file (/etc/guacamole/ This file contains the instructions for Guacamole to connect to guacd:

$ sudo mkdir /etc/guacamole
$ sudo mkdir /usr/share/tomcat9/.guacamole
$ sudo nano /etc/guacamole/

Insert the following contents to /etc/guacamole/ Note that we are referencing a file we will create in the next step (/etc/guacamole/user-mapping.xml):

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

And create a symbolic link for Tomcat to be able to read the file:

$ sudo ln -s /etc/guacamole/ /usr/share/tomcat9/.guacamole/

7. Guacamole uses the user-mapping.xml, create this file to define which users are allowed to authenticate to the Guacamole web interface (between <authorize> tags) and which connections they can use (between <connection> tags):

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

The following user mapping grants access to the Guacamole web interface to a user tecmint with password tecmint01. Then, inside the SSH connection, we need to place a valid username to log in to the RHEL box (you will be prompted to enter the corresponding password when Guacamole initiates the connection).

In the case of the Windows 10 box, there is no need to do that as we will be presented with the login screen over RDP.

To obtain the md5 hash of the password tecmint01, type the following command:

# printf '%s' "tecmint01" | md5sum

Then insert the output of the command in the password field inside the <authorize> tags:

                <connection name="RHEL 8">
                        <param name="hostname"></param>
                        <param name="port">22</param>
                        <param name="username">gacanepa</param>
                <connection name="Windows 10">
                        <param name="hostname"></param>
                        <param name="port">3389</param>

As it is the case with all files that contain sensitive information, it is important to restrict the permissions and change the ownership of the user-mapping.xml file:

$ sudo chmod 600 /etc/guacamole/user-mapping.xml
$ sudo chown tomcat:tomcat /etc/guacamole/user-mapping.xml

Start Tomcat and guacd.

$ sudo service tomcat9 start
$ sudo /usr/local/sbin/guacd &

Launching the Guacamole Web Interface

8. To access the Guacamole web interface, launch a browser and point it to http://server:8080/guacamole where the server is the hostname or IP address of your server (in our case it is and log in with the credentials given earlier (username: tecmint, password: tecmint01):

Apache Guacamole Login
Apache Guacamole Login

9. After clicking on Login, you will be taken to the administrative interface where you will see the list of connections user tecmint has access to, as per user-mapping.xml:

Guacamole User Connections
Guacamole User Connections

10. Go ahead and click on the RHEL 8 box to log in as gacanepa (the username specified in the connection definition).

Note how the connection source is set to (the IP of the Guacamole server), regardless of the IP address of the machine that you use to open the web interface:

Guacamole: Access Remote Linux
Guacamole: Access Remote Linux

11. If you want to close the connection, type exit and hit Enter. You will be prompted to return to the main interface (Home), reconnect, or log out from Guacamole:

Guacamole Session Disconnection
Guacamole Session Disconnection

12. Now it’s time to try the remote desktop connection to Windows 10:

Connect Windows Machine from Linux
Connect Windows Machine from Linux

Congratulations! Now you can access a Windows 10 machine and an RHEL 8 server from within a web browser.


In this article, we have explained how to install and configure Guacamole to allow access to remote machines over RDP and SSH. The official website provides extensive documentation to help you set up access using other protocols, such as VNC and other authentication mechanisms, such as DB-based…

As always, don’t hesitate to drop us a note if you have any questions or suggestions about this article. We also look forward to hearing your success stories.

If you liked this article, then do subscribe to email alerts for Linux tutorials. If you have any questions or doubts? do ask for help in the comments section.

If You Appreciate What We Do Here On TecMint, You Should Consider:

TecMint is the fastest growing and most trusted community site for any kind of Linux Articles, Guides and Books on the web. Millions of people visit TecMint! to search or browse the thousands of published articles available FREELY to all.

If you like what you are reading, please consider buying us a coffee ( or 2 ) as a token of appreciation.

Support Us

We are thankful for your never ending support.

67 thoughts on “Install Guacamole for Remote Linux/Windows Access in Ubuntu”

  1. Hi there,

    in step 1 you are missing dependencies for Kubernetes (libwebsockets) and RDP (FreeRDP) – as shown in step 3… For anyone wondering, just run this command between step 1 and step 2:

    $ sudo apt install -y freerdp2-dev libwebsockets-dev

    anyway, thanks for the tutorial =)

  2. Thanks for documentation and install tutorial.

    Kindly guide us how to integrate with Active Directory users group can automatically login with there user name.How AD user can access the Machine using two factor authentication.??

  3. Hi,

    I am getting below error, please help to resovle.

    Protocol "rdp" selected
    Oct  2 14:56:17 kaarRDP guacd[22166]: Connection ID is "$d673354c-cd35-4db7-b196-078c60a0fed5"
    Oct  2 14:56:17 kaarRDP guacd[22166]: No security mode specified. Defaulting to RDP.
    Oct  2 14:56:17 kaarRDP guacd[22166]: Loading keymap "base"
    Oct  2 14:56:17 kaarRDP guacd[22166]: Loading keymap "en-us-qwerty"
    Oct  2 14:56:17 kaarRDP guacd[22166]: Failed to load guacdr plugin. 
    Drive redirection and printing will not work. Sound MAY not work.
    Oct  2 14:56:17 kaarRDP guacd[22166]: Failed to load guacsnd alongside guacdr plugin. 
    Sound will not work. Drive redirection and printing MAY not work.
    Oct  2 14:56:17 kaarRDP guacd[22166]: Error connecting to RDP server
    Oct  2 14:56:17 kaarRDP guacd[22166]: Connection did not succeed
  4. Thanks for your tutorial,

    I have guacamole installed on vps actually it remote access a local pc with DHCP IP,

    My question is how to switch from one machine to another – all within the same web browser window ?

  5. Thanks for the tutorial.

    I had to make following changes to make it work with 0.9.14 release:
    step 2. Download and extract the tarball.
    extract the gauc-client tarball to /var/lib/tomcat7/webapps.

    step 6. add following line to configuration file (/etc/guacamole/

    # Location to read extra .jar's from
    lib-directory:  /var/lib/tomcat7/webapps/guacamole/WEB-INF/classes

    I hope it helps others find it helpful.

    Please update the tutorial for 0.9.14 release.

  6. Thank’s for the discovery of guacamole. I have to take a look at this very interesting program !

    I hope it can help me to replace the client side of vnc on my servers (clients computers)

    Thank you again !


Got something to say? Join the discussion.

Have a question or suggestion? Please leave a comment to start the discussion. Please keep in mind that all comments are moderated and your email address will NOT be published.

This site uses Akismet to reduce spam. Learn how your comment data is processed.