<> From the project page: [[http://guacamole.apache.org/|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. {{{#!wiki caution 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 [[https://guacamole.apache.org/doc/1.4.0/gug/guacamole-docker.html|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 [[https://guacamole.apache.org/releases/|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 [[https://guacamole.apache.org/doc/1.4.0/gug/installing-guacamole.html#deploying-guacamole|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 [[https://guacamole.apache.org/doc/1.4.0/gug/reverse-proxy.html|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 [[https://guacamole.apache.org/doc/1.4.0/gug/configuring-guacamole.html#using-the-default-authentication|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 [[https://guacamole.apache.org/doc/1.4.0/gug/configuring-guacamole.html#configuring-connections|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 [[https://guacamole.apache.org/doc/1.4.0/gug/configuring-guacamole.html#using-the-default-authentication|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 === * [[https://github.com/MysticRyuujin/guac-install|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 === * [[https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=887465|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 [[https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=888321|Bug #888321 migrate to freerdp2]]) - also carefully check upstream's issue, [[https://issues.apache.org/jira/browse/GUACAMOLE-249|Update RDP plugin support to 2.0.0 releases]]. * [[https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=887464|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 * [[https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=888973|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..." [[https://guacamole.apache.org/doc/gug/jdbc-auth.html#jdbc-auth-installation|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://: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: * [[https://github.com/Zer0CoolX/guacamole-customize-loginscreen-extension|Guacamole Extension to Customize/Brand the Login Screen]] == References and useful links == * [[https://guacamole.apache.org|Guacamole]] - project page * [[https://guacamole.apache.org/doc/gug/jdbc-auth.html#jdbc-auth-mysql|MariaDB database authentication configuration]] - official documentation