Install Guacamole for Remote Linux/Windows Access in Ubuntu

In today's interconnected world, remote access to Linux and Windows machines is essential for efficient system administration and troubleshooting. Guacamole is an open-source clientless remote desktop gateway that allows you to access your machines from anywhere using just a web browser. In this article, we will guide you through the process of installing Guacamole on Ubuntu and demonstrate how to access Linux and Windows systems remotely.


Before we begin, ensure that you have the following prerequisites in place −

  • A machine running Ubuntu (version 18.04 or later) with administrative privileges.

  • A stable internet connection.

  • Let's get started!

Step 1: Update System Packages

To begin, let's update the system packages on your Ubuntu machine by running the following commands −

sudo apt update
sudo apt upgrade -y

These commands will update your package lists and upgrade any outdated packages on your system.

Step 2: Install Dependencies

Guacamole requires several dependencies to function properly. Run the following command to install them −

sudo apt install -y libcairo2 libjpeg-turbo8 libjpeg-turbo8-dev libpng-dev libossp-uuid-dev libavcodec-dev libavutil-dev libswscale-dev freerdp2-dev libpango1.0-dev libssh2-1-dev libtelnet-dev libvncserver-dev libpulse-dev libssl-dev libvorbis-dev libwebp-dev tomcat9 tomcat9-admin tomcat9-common tomcat9-user

This command will install the necessary libraries and tools for Guacamole to function correctly.

Step 3: Download and Install Guacamole Server

Now, let's download and install the Guacamole server component by following these steps −


Download the Guacamole server source code archive using wget −



--2023-06-29 12:00:00--
Resolving (,,, ...
Connecting to (||:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 2483457 (2.4M) [application/x-gzip]
Saving to: ‘guacamole-server-1.3.0.tar.gz’

guacamole-server-1.3.0.tar.gz            100%[====================================================================>]   2.37M  --.-KB/s    in 0.1s

2023-06-29 12:00:00 (23.4 MB/s) - ‘guacamole-server-1.3.0.tar.gz’ saved [2483457/2483457]

Extract the downloaded archive −


tar -xzf guacamole-server-1.3.0.tar.gz



Change to the extracted directory −


cd guacamole-server-1.3.0

Configure the build −

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


checking for a BSD-compatible install... /usr/bin/install -c
checking whether build environment is sane... yes
checking for a thread-safe mkdir -p... /bin/mkdir -p
checking for gawk... no
checking for mawk... mawk
checking whether make sets $(MAKE)... yes
checking whether make supports nested variables... yes
checking whether UID '1000' is supported by ustar format... yes
checking whether GID '1000' is supported by ustar format... yes
checking how to create a ustar tar archive... gnutar
checking whether make supports nested variables... (cached) yes
checking for style of include used by make... GNU
checking for gcc... gcc
checking whether the C compiler works... yes
checking for C compiler default output file name... a.out
checking for suffix of executables...
checking whether we are cross compiling... no
checking for suffix of object files... o
checking whether we are using the GNU C compiler... yes
checking whether gcc accepts -g... yes

Build and install Guacamole server −


sudo make install
sudo ldconfig


make[1]: Entering directory '/path/to/package'
make[2]: Entering directory '/path/to/package/src'
/bin/mkdir -p '/usr/local/bin'
/bin/mkdir -p '/usr/local/lib'
/usr/bin/install -c program_name '/usr/local/bin'
/usr/bin/install -c -m 644 '/usr/local/lib'
/usr/bin/install -c -m 644 header.h '/usr/local/include'
make[2]: Leaving directory '/path/to/package/src'
make[1]: Leaving directory '/path/to/package'

Step 4: Configure Guacamole

After installing the server, it's time to configure Guacamole. Here's how you can do it −

Copy the example Guacamole configuration file −

sudo cp guacamole-server-1.3.0/guacamole-server/src/main/webapp/WEB-INF/ /etc/guacamole/

Edit the configuration file using a text editor of your choice. For example −

sudo nano /etc/guacamole/

In this file, you can customize various settings such as database connection details, authentication mechanisms, and more. Make sure to save your changes after editing the file.

Step 5: Deploy Guacamole Web Application

To deploy the Guacamole web application on your Ubuntu machine, follow these steps −

Download the Guacamole web application archive −

wget -O guacamole.war

Move the downloaded archive to the Tomcat webapps directory −

sudo mv guacamole.war /var/lib/tomcat9/webapps/guacamole.war

Restart Tomcat for the changes to take effect −

sudo systemctl restart tomcat9

Step 6: Access Guacamole Web Interface

At this point, Guacamole is installed and ready to use. To access the Guacamole web interface, open your web browser and enter the following URL −


Replace <your-server-ip> with the IP address or domain name of your Ubuntu machine. You should see the Guacamole login screen.

Step 7: Configure Guacamole Users and Connections

To start using Guacamole, you need to configure users and connections. Here's how you can do it −

Open the Guacamole configuration file −

sudo nano /etc/guacamole/

Uncomment the # auth-provider: line and save the file.

Create a new file for user authentication −

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

Add user and connection configurations to the user-mapping.xml file. Here's an example configuration for a Linux machine −

<?xml version="1.0" encoding="UTF-8"?>
   <authorize username="user1" password="password1">
      <connection name="Linux Server">
         <param name="hostname"></param>
         <param name="port">22</param>
         <param name="username">remoteuser</param>

In this example, a user named "user1" with password "password1" is configured to connect to a Linux server with SSH.

Save the user-mapping.xml file.

Restart Tomcat to apply the configuration changes −

sudo systemctl restart tomcat9


Congratulations! You have successfully configured users and connections in Guacamole, allowing you to access your remote Linux and Windows machines with ease. Guacamole provides a convenient and secure way to manage your systems remotely through a web browser.

Remember to regularly update and maintain your Guacamole installation to benefit from the latest features and security patches.

Enjoy the convenience of remote access with Guacamole!

Updated on: 17-Jul-2023


Kickstart Your Career

Get certified by completing the course

Get Started