How to Install Apache Guacamole on Debian 11

Apache Guacamole is a free and open-source remote desktop gateway that allows you to connect to your computer/server remotely using different protocols such as SSH, RDP, and VNC. Apache Guacamole is maintained by Apache Software Foundation, and licensed with Apache License 2.0.

Apache Guacamole is a clientless remote desktop gateway. You can access Apache Guacamole using only a web browser from anywhere at any time. Using Apache Guacamole is recommended if you have multiple remote operating systems with different protocols, such as Windows with RDP, Linux system with VNC and SSH.

In this tutorial, you'll install and configure the Apache Guacamole to a Debian 11 Bullseye. This includes installing some packages dependencies and the Apache Tomcat 9, then building the Guacamole-server and installing the Java application, Guacamole web application. In the end, you'll set up Nginx as a reverse proxy for the Guacamole web application that allows you to access your servers from anywhere, as long as you have a web browser.


To complete this tutorial, you'll need the following requirements:

  • A server with at least 2GB RAM running Debian 11 Bullseye.
  • A use or non-root user with root privileges.
  • Basic knowledge with nano editor. Or you can use your preferred editor such as vim.

Installing Build Dependencies

At first, you'll install some build dependencies for building the Apache Guacamole server. This includes some basic packages such as 'libvncserver-dev' that enable supports for the VNC protocol, 'libssh2-1' for the SSH protocol, 'freerdp2-dev' for the RDP protocol, and 'libwebsockets-dev' for the Kubernetes support.

For consideration, you'll not install the 'libtelnet-dev' for the Telnet supports. This is because telnet is considered an old protocol and not secure.

1. Now, update your package list by running the apt command below.

sudo apt update

2. After that, install dependencies for building the Apache Guacamole server by running the following command.

sudo apt install -y freerdp2-dev libavcodec-dev libavformat-dev libavutil-dev libswscale-dev libcairo2-dev libjpeg62-turbo-dev libjpeg-dev libpng-dev libtool-bin libpango1.0-dev libpango1.0-0 libssh2-1 libwebsockets16 libwebsocketpp-dev libossp-uuid-dev libssl-dev libwebp-dev libvorbis-dev libpulse-dev libwebsockets-dev libvncserver-dev libssh2-1-dev openssl

This command may take some time to finish, depending on your server internet's connection.

Installing Apache Tomcat 9

After installing build dependencies, you'll install the Apache Tomcat 9. This package is required for the Guacamole web application, which is a web application written in Java.

1. Run the following command to install the Apache Tomcat 9 to your system.

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

2. After the Apache Tomcat 9 is installed, start and enable the Apache Tomcat service by running the command below. On the Debian-based systems, Apache Tomcat 9 comes with the service called 'tomcat9'.

sudo systemctl enable --now tomcat9

3. Now, if everything looks okay, verify the status of the 'tomcat9' service by running the command below.

sudo systemctl status tomcat9

You'll receive the following output. Make sure the 'tomcat9' service is 'active (running)'.

Enable Apache Tomcat9 service

Compiling Guacamole-server

In this section, you'll download and compile the Guacamole-server. This is the main component of Apache Guacamole, which contains libraries for connecting to remote servers and desktops. The Guacamole-server contains the C library 'libguacd' and all libraries for supported protocols, as well the heart of Guacamole, guacd.

The guacd handles all client connections that are tunneled from the guacamole web application, then connects to remote servers and desktops on their behalf. By building and compiling Guacamole-server, you'll have a new service 'guacd' on your system.

1. Start by navigating the working directory to '/usr/src'. All source code for building and compiling stuff goes to this directory.

cd /usr/src

2. Now, you'll download the Guacamole-server source code by running the wget command below. Be sure to check the Guacamole Download page and copy the latest version of Guacamole-server. At the time of this writing, the latest version is 1.3.0.


3. Then, extract the source code and you'll get a new directory 'guacamole-server-VERSION-NUMBER'. Navigate into that directory.

tar -xzvf guacamole-server-1.3.0.tar.gz
cd guacamole-server-*/

4. Now, verify all system requirements for building the Guacamole-server and set up your environment by running the following command. The option '--with-systemd-dir=/etc/systemd/system/' is used to set up systemd service file, which will be available at the directory '/etc/systemd/system/'.

./configure --with-systemd-dir=/etc/systemd/system/

You'll receive output similar to this:

guacamole-server version 1.3.0

   Library status:

     freerdp2 ............ yes
     pango ............... yes
     libavcodec .......... yes
     libavformat.......... yes
     libavutil ........... yes
     libssh2 ............. yes
     libssl .............. yes
     libswscale .......... yes
     libtelnet ........... no
     libVNCServer ........ yes
     libvorbis ........... yes
     libpulse ............ yes
     libwebsockets ....... yes
     libwebp ............. yes
     wsock32 ............. no

   Protocol support:

      Kubernetes .... yes
      RDP ........... yes
      SSH ........... yes
      Telnet ........ no
      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.

Take a look at the 'Libraries status' and 'Protocol support' sections. You can adjust protocol supports by installing additional dependencies and libraries.

5. Next, compile and install the Guacamole-server by running the command below.

make install

The compilation and installation process may take some time to complete.

6. Now, after everything is completed, run the following command to apply all new system libraries.

sudo ldconfig

In this section, you have installed the Guacamole-server package. Next, you'll create some necessary configurations for the Guacamole-server.

Setting Up Guacamole-Server

To make Guacamole-server work, you'll create configuration directory '/etc/guacamole/', then create new file '' as the default Guacamole-server configuration, file 'logback.xml' for Guacamole logging system, and file 'user-mapping.xml' for defining Guacamole users authentication and connections to remote servers and desktops.

1. To start, run the following command to create a new directory '/etc/guacamole/' within additional directories 'extensions' and 'lib' inside. Then add the environment variable 'GUACAMOLE_HOME=/etc/guacamole' to the file '/etc/default/tomcat9'. This will tell the Tomcat 9 servlet container to look up the 'GUACAMOLE_HOME' directory to the '/etc/guacamole/'.

mkdir -p /etc/guacamole/{extensions,lib}
echo 'GUACAMOLE_HOME=/etc/guacamole' >> /etc/default/tomcat9

2. Now, create the main configuration '' using nano or your preferred editor.

sudo nano /etc/guacamole/

Enter the following configuration:

# Hostname and port of guacamole proxy
guacd-hostname: localhost
guacd-port:     4822

# user mapping and user connections
user-mapping:    /etc/guacamole/user-mapping.xml
  • The option 'guacd-hostname' defines the hostname or IP address which the guacd service will be running at. This tutorial uses the localhost to run the guacd service.
  • The option 'guacd-port' defines the default port for guacd service. This tutorial uses the port '4822' for guacd service.
  • The option 'user-mapping' defines the file configuration for users' authentication and a list of available connections. This tutorial uses the file '/etc/guacamole/user-mapping.xml' to define users and connections for the Guacamole-server. You may be interested to use another authentication method, check the Guacamole Documentation.

Save and close the file.

3. Next, create a new configuration 'loogback.xml' for logging and debugging. By default, the Guacamole will log to the console only. Using this configuration allows Guacamole to log via the Logback logging framework.

sudo nano /etc/guacamole/logback.xml

Add the following configuration lines.


    <!-- Appender for debugging -->
    <appender name="GUAC-DEBUG" class="ch.qos.logback.core.ConsoleAppender">
            <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>

    <!-- Log at DEBUG level -->
    <root level="debug">
        <appender-ref ref="GUAC-DEBUG"/>


Save and close the configuration file.

4. Now, you'll generate a new md5 password hash and create a new file for Guacamole user authentication and connections.

Run the following command to generate the md5 password hash. And make sure to change the password with your strong password.

echo -n StrongPasswordUserJohnDoe | openssl md5

You'll receive an output of the mod5 hashed password. Copy it to your note.

(stdin)= aca22211ffcfb8aa8ad7627195ad4fce

5. After that, create a new file 'user-mapping.xml' using nano editor.

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

Input these following configurations. And make sure to change the 'username' and 'password'. Also, take a look at the '<connection>...</connection>' section and add your connection details to servers or desktops.


    <!-- Another user, but using md5 to hash the password
         (example below uses the md5 hash of "PASSWORD") -->

        <!-- First authorized connection -->
        <connection name="SSH localhost">
            <param name="hostname">localhost</param>
            <param name="port">22</param>
            <param name="username">johndoe</param>
            <param name="password">SSHPASSWORD</param>

        <!-- Second authorized connection -->
        <connection name="localhost">
            <param name="hostname">localhost</param>
            <param name="port">5901</param>
            <param name="password">VNCPASS</param>

        <!-- Third authorized connection -->
        <connection name="otherhost">
            <param name="hostname">otherhost</param>
            <param name="port">5900</param>
            <param name="password">VNCPASS</param>



Save and close the file.

Now you've completed the configuration of Guacamole-server. Next, you'll install and configure the Guacamole web application, which is the web application you'll see on your browser.

Installing Guacamole Client Web Application

In this section, you'll install the Guacamole web application to your system. This can be done by downloading the compiled binary file of the Guacamole web application and deploying it to the Tomcat 'webaps' directory.

1. Navigate your working directory to '/usr/src' and download the compiled Guacamole web application '.war' using the wget command. Ensure to visit the Guacamole download page and copy the link for the latest version Guacamole web application.

cd /usr/src

2. Now, deploy the Java binary application 'guacamole-VERSION.war' to the Tomcat directory '/var/lib/tomcat9/webapps/' by running the following command. This makes the Guacamole web application accessible through the Apache Tomcat servlet container.

sudo cp guacamole-1.3.0.war /var/lib/tomcat9/webapps/guacamole.war

3. After that, restart the Tomcat 9 service to apply a new web application.

sudo systemctl restart tomcat9

4. Next, start and enable the 'guacd' service by running the command below.

sudo systemctl enable --now guacd

Then verify it using the following command.

sudo systemctl status guacd

You'll receive the output like the screenshot below.

Enable guacd service Apache Guacamole

At this point, you've completed the installation of the Guacamole-server application (backend) and the Guacamole web application (front-end). Next, you'll set up Nginx as a reverse proxy for the Guacamole web application.

Setup Nginx Reverse proxy for Guacamole

In this section, you'll install the Nginx web server and configure it as a reverse proxy for the Guacamole web application. This allows you to set up the domain name for your Guacamole web application and secure it with SSL certificates.

1. To get started, run the following 'apt' command to install Nginx packages.

sudo apt install nginx -y

2. After all Nginx packages are installed, create a new virtual host file 'guacamole' on the directory '/etc/nginx/sites-available'. All configurations related to the Guacamole reverse proxy will be stored in this file.

sudo nano /etc/nginx/sites-available/guacamole

Input this following configuration. And make sure to change the domain name and path of SSL certificates. This example uses the domain '' with the SSL private key 'privkey.pem' and the public key 'fullchain.pem', and bot certificates available at the directory '/etc/letsencrypt/live/'.

server {
    listen      80;
    rewrite     ^   https://$server_name$request_uri? permanent;

server {
    listen      443 ssl http2;

    root /var/www/html;
    index index.html;

    location / {
       try_files $uri $uri/ =404;

    ssl_certificate /etc/letsencrypt/live/;
    ssl_certificate_key /etc/letsencrypt/live/;

    access_log /var/log/nginx/guacamole-access.log;
    error_log /var/log/nginx/guacamole-error.log;

    location /guacamole/ {
        proxy_buffering off;
        proxy_http_version 1.1;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $http_connection;
        access_log off;

Save and close the file.

3. Now, activate the virtual host file 'guacamole' by creating a new symbolic link to the directory '/etc/nginx/sites-enabled/'. Then verify all Nginx configurations to check if there are any syntax errors.

sudo ln -s /etc/nginx/sites-available/guacamole /etc/nginx/sites-enabled/
sudo nginx -t

You'll receive an output 'Syntax OK', which means the configuration has no error.

Set up Nginx as a reverse proxy Apache Guacamole

4. Next, restart the Nginx service to apply a new configuration, then verify its status by running the following command.

sudo systemctl restart nginx
sudo systemtl status nginx

You'll receive the output similar to the screenshot below. The Nginx service is 'active (running)'.

Verify Nginx service status

5. Additionally, if you want to deploy Guacamole web-application in different sub-URL, change the option 'location /guacamole/ { ... }' to new path 'location /new-path/ { ... }' and add the option 'proxy_cookie_path' to your new path as below.

location /new-path/ {
    proxy_buffering off;
    proxy_http_version 1.1;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $http_connection;
    proxy_cookie_path /guacamole/ /new-path/;
    access_log off;

In this section, you've completed the Nginx installation and configuration as a reverse proxy for the Guacamole web application. At this point, your Apache Guacamole installation is completed, and it's accessible from your domain name.

Verify Apache Guacamole Installation

In this section, you'll verify the Apache Guacamole installation.

First off, open up your web browser and type the domain name for your Guacamole installation with the default path '/guacamole'.

Now, you'll see the Guacamole login page below. Input your username and password that you've configured in file 'user-mapping.xml', then click the Login button.

Apache Guacamole Login Page

After logging in, you'll see a list of defined connections for your users.

Apache Guacamole List Connections

Click on the connection name to connect to the target server. This example will connect to the local server with SSH protocol.

Now, you will see a new ssh terminal session on your server.

Guacamole SSH to Local Server


Congratulation! In this tutorial, you've learned how to install Apache Guacamole on the Debian 11 Bullseye. Also, you've learned how to set up user authentication and connections using the configuration file 'user-mapping.xml' and set up Nginx as a reverse proxy for the Guacamole web application, which enables you to run Guacamaloe using the domain name and secure it using SSL certificates.

Share this page:

2 Comment(s)

Add comment

Please register in our forum first to comment.


By: Mathieu

I had to install the build-essential package group in order to run configure successfully

sudo apt install -y build-essential

By: Marcus

But my JohnDoe has no Admin Rights ?