From the project page:

Although not its primary purpose, Guacamole can also be used to share a screen, or even a single window, among multiple participants in a manner similar to Zoom or other platforms which support conference calling.

All of the installation methods on this page, to some degree or another, install code which is not packaged by Debian. When you do this you will not get support on such software by the Debian security team and will have to setup your own processes to monitor the discovery of security vulnerabilities and available patches.

Installation on Debian Bullseye (11)

Docker Install

Simplest might be to install the package and deploy Guacamole using Docker. But this is only supported (by on the amd64 architecture.

Native Install

To run natively, the prerequisites are the guacd and tomcat9 packages.

You will also need the latest guacamole.war file from Apache. This is the java server software executed by Tomcat (or some other such server of your choice) and is no longer supplied by Debian. Recent releases are backwards compatible with the guacd version which is in Debian but it wouldn't hurt to read the docs and check before deciding which`guacamole.war to download. Apache has installation instructions but all you need to do is put the file in $CATALINA_BASE/webapps, which, under Debian, is /var/lib/tomcat9/webapps/. Tomcat must be restarted to recognize the new application.

It is likely that you will also want to reverse-proxy through a webserver such as provided by the apache2 or nginx packages. Apache provides instructions with sample configurations for these two webservers.

User Authentication

Guacamole requires that users authenticate. The simplest way to construct a database of users is to write the XML file /etc/guacamole/user-0mapping.xml. Apache has instructions which include samples. A number of other authentication database stores can be configured as well.

Connection Configuration

Guacamole supports a number of screen sharing protocols, VNC, RDP, SSH (for text based access), and others. These must be configured. Apache has instructions.

You choice of connection protocol may depend on your purpose. E.g. the x11vnc VNC server allows "export" of an X session which already exists, making available the screen of an already logged-in user or even a single X window. (Use xwininfo to obtain the X window id.) The Apache configuration instructions has suggestions and recommendations.

Installation on Debian Stretch (9)


Install / upgrade script

It can also be used to upgrade from 1.0.0 to 1.1.0 in Debian Buster.

Unresolved bugs

Requirements installation

Note: in this example the password is "some_password", change it accordingly.

Create the required directories:

# mkdir -p /etc/guacamole/lib /etc/guacamole/extensions

Install Tomcat 8 application server and MariaDB server:

# apt install tomcat8 mariadb-server -y

Complete the initial database configuration:

# mysql_secure_installation

(follow the script prompts)

Create the Guacamole database, setup its permissions:

# mysql -u root -p
Enter password: ***
Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 233
Server version: 5.5.29-0ubuntu0.12.10.1 (Ubuntu)

Copyright (c) 2000, 2012, Oracle and/or its affiliates. All rights reserved.

Oracle is a registered trademark of Oracle Corporation and/or its
affiliates. Other names may be trademarks of their respective

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

mysql> CREATE DATABASE guacamole_db; 
Query OK, 1 row affected (0.00 sec)

mysql> CREATE USER 'guacamole_user'@'localhost' IDENTIFIED BY 'some_password';
Query OK, 0 rows affected (0.00 sec)

mysql> GRANT SELECT,INSERT,UPDATE,DELETE ON guacamole_db.* TO 'guacamole_user'@'localhost';
Query OK, 0 rows affected (0.00 sec)

Query OK, 0 rows affected (0.02 sec)

mysql> quit;

Install the Java database (JDBC) driver for MySQL / MariaDB, link it from the Guacamole configuration:

# apt install libmysql-java
# ln -s /usr/share/java/mysql-connector-java.jar /etc/guacamole/lib/

Download the JDBC Guacamole authentication component and copy it to the appropriate location:

# wget -c
# tar -xzvf guacamole-auth-jdbc-0.9.9.tar.gz
# mv guacamole-auth-jdbc-0.9.9/mysql/guacamole-auth-jdbc-mysql-0.9.9.jar /etc/guacamole/extensions

Use the database scripts to populate the database with the initial application data (first "guacadmin user", etc.):

# ls guacamole-auth-jdbc-0.9.9/mysql/schema/
001-create-schema.sql  002-create-admin-user.sql  upgrade
# cat guacamole-auth-jdbc-0.9.9/mysql/schema/*.sql | mysql -u root -p guacamole_db

Application installation

Guacamole server, from Debian packages (v 0.9.9)

Install the Guacamole server:

# apt install guacd -y

Guacamole server, from sources (v 0.9.14)

This is required if you want to use PKA in SSH connections (see above, Unresolved bugs).

# apt-get install libcairo2-dev libossp-uuid-dev libavcodec-dev libavutil-dev libswscale-dev libfreerdp-dev libpango1.0-dev libssh2-1-dev libtelnet-dev libvncserver-dev libpulse-dev libssl-dev libvorbis-dev libwebp-dev libjpeg62-turbo-dev libpng-dev libpng16-16 git

# git clone git://
autoreconf -fi
./configure --with-init-dir=/etc/init.d
# make && make install
# ldconfig
# systemctl enable guacd
# /etc/init.d/guacd start

If you had initially installed an older version don't forget to also update the corresponding guacamole-auth-jdbc, guacamole.war and also update the database - see "If you are upgrading from an older version of Guacamole..." as indicated in the official documentation.

Configuration files

Create the configuration file and link the configuration directory from the Tomcat setup:

# touch /etc/guacamole/

Add this information to the configuration file:

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

# MySQL properties
mysql-hostname: localhost
mysql-port: 3306
mysql-database: guacamole_db
mysql-username: guacamole_user
mysql-password: some_password

Link the file to your Tomcat setup:

# ln -s /etc/guacamole/ /var/lib/tomcat8/.guacamole

Get the Guacamole web application:

# wget

The file is about 7M big, consider checking its MD5 checksum to see if it matches the one below:

# md5sum guacamole-0.9.9.war
324c17aa305a077a2127378a2d0a7a51  guacamole-0.9.9.war

Copy it to Tomcat for deployment and restart Tomcat:

# mv guacamole-0.9.9.war /var/lib/tomcat8/webapps/guacamole.war
# service tomcat8 restart

Note: using a more recent version of the Guacamole web application (.war file) may work with Debian's Guacamole server (guacd) v. 0.9.9 but is not recommended or supported.

You can now access the application at http://<youserverip>:8080/guacamole. The default user and password are both "guacadmin".


The login page can be re-branded to customize its logo and message. For more details see this extension:

* Guacamole Extension to Customize/Brand the Login Screen