Contents
From the project page:
Apache Guacamole is a clientless remote desktop gateway. It supports standard protocols like VNC, RDP, and SSH. We call it clientless because no plugins or client software are required. Thanks to HTML5, once Guacamole is installed on a server, all you need to access your desktops is a web browser.
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 docker.io package and deploy Guacamole using Docker. But this is only supported (by Apache.org) 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)
Notes:
- This section assumes you wish to authenticate from a MySQL database store.
This documentation has been tested in Debian Stretch, it includes manual installation of the web application. Normally using the guacamole package would be the preferred installation method but it's broken - see Unresolved bugs below.
- Version 0.9.9 is used here as that's the Guacamole server version that is currently packaged in Debian 9. The latest version can be installed too, see below.
Install / upgrade script
This script automatically performs the steps described below, although using only source packages for Guacamole and Java components for version 1.1.0. It also uses the libmysql-java package now. Read it carefully before executing it.
It can also be used to upgrade from 1.0.0 to 1.1.0 in Debian Buster.
Unresolved bugs
Bug #887565 - Please update to new upstream version
There is ongoing discussion to decide if RDP support is completely dropped to have an updated package. This depends on Bug #888321 migrate to freerdp2) - also carefully check upstream's issue, Update RDP plugin support to 2.0.0 releases.
Bug #887464 - Can't set language or remote protocol, can't create connections - this bug makes the web application unusable, as such it must be manually installed
Bug #888973 - guacd segfaults, error 6 in libcrypto.so.1.1, can't connect via SSH when using PKA - this prevents using PKA on SSH connections, as a workaround install guacd manually (see below)
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 owners. 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) mysql> FLUSH PRIVILEGES; Query OK, 0 rows affected (0.02 sec) mysql> quit; Bye
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 https://sourceforge.net/projects/guacamole/files/current/extensions/guacamole-auth-jdbc-0.9.9.tar.gz # 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://github.com/apache/incubator-guacamole-server.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/guacamole.properties
Add this information to the guacamole.properties 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 guacamole.properties file to your Tomcat setup:
# ln -s /etc/guacamole/ /var/lib/tomcat8/.guacamole
Get the Guacamole web application:
# wget https://sourceforge.net/projects/guacamole/files/current/binary/guacamole-0.9.9.war
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".
Branding
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
References and useful links
Guacamole - project page
MariaDB database authentication configuration - official documentation