How to install Apache Guacamole on Debian

Before you begin

The purpose of this guide is to make it easier to install Apache Guacamole 1.1.0 on Debian 10. If you find it usefull or if you find some kind of error, please leave a comment.

Apache Guacamole is a convenient way to connect to your home server from remote. You use your browser, it’s really a fantastic piece of software.

Please note that this guide is intended for use at home or in a test environment, use it with caution. It works on my server – it might not work on yours. Please refeer to the Guacamole manual at any time.

This guide requires basic knowledge of working with the linux command line and also knowledge about how to create a virtual machine and install a linux operating system.

If your are planning to use Apache Guacamole in a production environment please use The Guacamole Manual, only use this guide as a complement.

Install Debian 10

Use a virtual (or physical machine) and install Debian 10. Install it without graphical interface and with ssh-server.

Create a user and give it sudo rights and then log in with SSH – if using Windows I recommend a program like Putty.

Install Apache Tomcat 9

Begin with installing Apache Tomcat 9. I used this guide from Digital Ocean. I used the latest tar-package from Apache Tomcat.

See if the installation work by surfing to your server using your favorite browser. If you see a webpage then you’ve successfully installed Tomcat.


Install Guacamole server and client

This guide is based on the Guacamole manual. Please check it out to know more about what you are doing. The most important part when installing is chapter 2 – installing Guacamole nativley.

Install dependencies for Debian

Check the manual what dependencies you may possible need – below is for basic SSH, VNC and RDP support.

$ sudo apt install libcairo2-dev libjpeg62-turbo-dev libpng-dev libtool-bin libossp-uuid-dev freerdp2-dev libpango1.0-dev libssh2-1-dev libvncserver-dev libssl-dev libwebp-dev make

Download source code for Apache Guacamole 1.1.0 server (guacamole-server), build and install it

Go to the download page to download the source code for Apache Guacamole 1.1.0.

You can also download it with the following command:

$ wget --trust-server-names ''

If you are downloading some other version of the software, change the above command accordingly.

Then use the following commands.

$ tar -xzf guacamole-server-1.1.0.tar.gz
$ cd guacamole-server-1.1.0/
$ ./configure --with-init-dir=/etc/init.d

Once you have run the above configure-command, you’ll se what libraries was found and what the server supports – please see the manual, chapter 2 for more information about what this command does.

$ make

$ sudo make install

$ sudo ldconfig

Now the server should be installed. You can start it by running the following command (please note that you with this guide have to enter this command every time you restart your server):

$ sudo guacd

Download and deploy the Apache Guacamole 1.1.0 client (guacamole-client)

Move to a temporary directory.

$ cd /tmp/

Go to the download page to download the prebuilt version of guacamole client (guacamole-1.1.0.war).

You can also download it with the following command:

$ wget --trust-server-names ''

If you are downloading some other version of the software, change the above command accordingly.

Change the name of the file once downloaded.

$ mv guacamole-1.1.0.war guacamole.war

Copy the file to the webapps directory of Apache Tomcat. If you followed the Digital Ocean guide then you would use the following command.

$ sudo cp guacamole.war /opt/tomcat/webapps/

Then restart the Apache Tomcat-server.

$ sudo service tomcat restart

The above command could be different if you installed Apache Tomcat in another way.

Configure Apache Guacamole

This part of the guide is based on chapter 5 of the manual, I recommend to read it before you continue.

Guacamole’s config files are located in /etc/guacamole (the GUACAMOLE_HOME), but you have to create the directories by yourself.

Please note that the above home of configuration files can be altered – please see the manual Chapter 5.

Create the basic files and directory

$ sudo mkdir /etc/guacamole
$ cd /etc/guacamole
$ sudo touch
$ sudo touch user-mapping.xml

Enter basic configuration

The following is examples of the files that works for me:

guacd-hostname: localhost
guacd-port: 4822

user-mapping.xml: (please note that you can create md5 hashes to secure your passwords)

The second line below will be the actual login to Guacamole.


<authorize username="username" password="password">

<connection name="LinuxServer">
<param name="hostname"></param>
<param name="port">22</param>
<param name="username">serverusername</param>

<connection name="WindowsServer2019">
<param name="hostname"></param>
<param name="port">3389</param>
<param name="security">nla</param>
<param name="ignore-cert">true</param>
<param name="username">serverusername</param>
<param name="password">serveruserpassword</param>



Example of user entry with password thas is generated with a md5 hash:

<authorize username="USERNAME2" password="319f4d26e3c536b5dd871bb2c52e3178" encoding="md5">

Log in to your Apache Guacamole-server

To enter your server open your favorite web browser:


Proxying Guacamole with Apache

For more information, see the manual chapter 4.

Edit your default (or any other suitable config file) Apache configuration file (default-ssl.conf), this assumes you have a website up and running of some kind.

I strongly recommend that you use HTTPS – Let’s Encrypt is a good solution, using certbot to automatically renew your certificate.

Install the requried mods.

$ sudo a2enmod proxy proxy_wstunnel

Add the following to your default-ssl.conf (between <VirtualHost *:443> … </VirtualHost>:

<Location /guacamole/>
Order allow,deny
Allow from all
ProxyPass http://IP-OF-SERVER:8080/guacamole/ flushpackets=on
ProxyPassReverse http://IP-OF-SERVER:8080/guacamole/

After the above text, enter the following.

<Location /guacamole/websocket-tunnel>
Order allow,deny
Allow from all
ProxyPass ws://IP-OF-SERVER:8080/guacamole/websocket-tunnel
ProxyPassReverse ws://IP-OF-SERVER:8080/guacamole/websocket-tunnel

Also add the following to the Apache Tomcat configuration. Edit the file /opt/tomcat/conf/server.xml, add in the <Host> section.

<Valve className="org.apache.catalina.valves.RemoteIpValve"
               protocolHeader="x-forwarded-proto" />

Restart the Apache Tomcat Server.

$ sudo service tomcat restart

Also restart Apache2.

$ sudo service apache2 restart

You should now be able to access you Guacamole-site on:

Please leave a comment on this blog post if you found some kind of error or if you have some other thing to add.

Future improvements of this guide

I’m going to add information about using MySQL-server support to this configuration.


Bloggande IT-bibliotekarie och linuxnörd. Brinner för frågor om fri programvara, personlig integritet på nätet och teknik som befriar snarare än stänger in.

Du gillar kanske också...

Lämna ett svar