Apache Guacamole est un bastion d’administration prennant en charge les protocoles SSH, RDP et VNC. Un bastion est utile car il va permettre de centraliser ses connexions (homelab entre autres), ce qui est pratique car il nous évite d’installer sur chaque appareil un client SSH, RDP ou VNC. Seuls prérequis seront un client Tailscale et un navigateur internet (car dans ce guide on va utiliser Tailscale pour y accéder en dehors de chez soi). On est pas obligé de forcément tout centraliser dans Guacamole du sens où seule les connexions SSH ne pourront se faire seulement que dans Guacamole pas en parallèle dans un terminal ou client autre que Guacamole mais cela reste tout de même possible.

Schéma de fonctionnement de Guacamole avec Tailscale

Les fonctionnalités clés

Centralisation et suivi des connexions : qui, quand, où, combien de temps, depuis où
Aucun client lourd à installer, l’accès s’effectue en mode web grâce au HTML5
Authentification multi-facteurs pour l’accès aux connexions, via un code TOTP
Authentification SSO, compatible avec SAML, OpenID Connect, CAS ou encore LDAP
Enregistrements vidéos des sessions, c’est-à-dire quand une connexion est en cours d’utilisation
Gestion des autorisations pour l’accès aux connexions, par groupes ou par utilisateurs

Mise en place du serveur

Guacamole sera installé pour ma part dans une machine virtuelle sous Ubuntu Server 24.04 LTS. Sous Debian 12 ça fonctionne aussi et c’est globalement la même chose.

Au moment de rédiger cette documentation, je dédiais cette installation à Debian 13 mais au vu des difficultés rencontrées (soucis de compatibilité entre Guacamole et FreeRDP 3.x…) j’ai préféré utiliser Ubuntu Server 24.04 LTS.

Conditions d’installation

Dans mon cas à titre personnel Guacamole sera :

Installé sur Ubuntu Server 24.04.4.1 LTS
Installé en version 1.6.0 (dernière version au moment de rédiger ces lignes)
Tomcat en version 10.1.16 et MariaDB 10.11.14

Installation des prérequis

On s’assure que le système est à jour et on installe les dépendances via cette commande là :

sudo apt update && sudo apt full-upgrade

sudo apt-get install -y build-essential libcairo2-dev libjpeg-turbo8-dev libpng-dev libtool-bin uuid-dev libossp-uuid-dev \
  libvncserver-dev freerdp2-dev libssh2-1-dev libssl-dev libtelnet-dev libpango1.0-dev libwebsockets-dev \
  libavcodec-dev libavformat-dev libavutil-dev libswscale-dev libvorbis-dev libwebp-dev libpulse-dev \
  tomcat10 mariadb-server nginx certbot tomcat-jakartaee-migration wget curl

Jusqu’ici le serveur n’est pas encore prêt car nous n’avons pas encore installé de serveur Tomcat (et on s’en occupera après).

Compilation du serveur

Il y a une partie serveur à installer et à compiler localement sur la machine.

cd /tmp
wget https://downloads.apache.org/guacamole/1.6.0/source/guacamole-server-1.6.0.tar.gz

A l’heure de rédiger ces lignes la dernière version est la 1.6.0. Toutefois cela peut changer. Pour être sur de télécharger la bonne version on se rend sur le site officiel de Guacamole.

Pour extraire le contenu du fichier compressé :

tar -xzf guacamole-server-1.6.0.tar.gz
cd guacamole-server-1.6.0/

Puis pour préparer la compilation :

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

Si la sortie ressemble à ça :

------------------------------------------------
guacamole-server version 1.6.0
------------------------------------------------

   Library status:

     freerdp ............. yes (2.x)
     pango ............... yes
     libavcodec .......... yes
     libavformat ......... yes
     libavutil ........... yes
     libssh2 ............. yes
     libssl .............. yes
     libswscale .......... yes
     libtelnet ........... yes
     libVNCServer ........ yes
     libvorbis ........... yes
     libpulse ............ yes
     libwebsockets ....... yes
     libwebp ............. yes
     wsock32 ............. no

   Protocol support:

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

C’est que Guacamole est prêt pour être compilé. En revanche si dans le support des protocoles tout n’est pas en yes c’est qu’il manque des dépendances à installer.

On compile :

sudo make

Et on installe :

sudo make install

Si tout s’est bien passé avec succès, on peut en conclure que la partie serveur s’est bien installée. Mais ce n’est pas encore fini il nous reste encore d’autre choses à faire.

On va saisir cette commande qui va mettre à jour les liens entre guacamole-server et les librairies :

sudo ldconfig

Il est normal que cette commande retourne aucun résultat.

Ensuite, on va démarrer le service “guacd” correspondant à Guacamole et activer son démarrage automatique :

sudo systemctl daemon-reload
sudo systemctl enable --now guacd

On vérifie l’état de guacd :

sudo systemctl status guacd

Déployer l’application web Guacamole

L’application web est un fichier WAR qui exécute à l’intérieur un Tomcat, on va le télécharger :

cd /tmp
wget https://downloads.apache.org/guacamole/1.6.0/binary/guacamole-1.6.0.war

Sous Ubuntu 24.04, Tomcat 10 utilise l’espace de noms Jakarta EE au lieu de l’ancien espace de noms javax. Le fichier WAR de Guacamole utilisant toujours javax en interne, il doit être converti. Sans cette étape, vous obtiendrez une page blanche après la connexion. Le paquet tomcat-jakartaee-migration, que vous avez installé précédemment, fournit l’outil de conversion :

sudo javax2jakarta /tmp/guacamole-1.6.0.war /var/lib/tomcat10/webapps/guacamole.war

Redémarrer Tomcat pour déployer le WAR converti :

sudo systemctl restart tomcat10

Tomcat devrait décompresser le fichier WAR dans /var/lib/tomcat10/webapps/guacamole/ en quelques secondes.

Configurer MariaDB

Bien que Guacamole puisse utiliser un simple fichier XML pour la gestion des utilisateurs, l’utilisation d’une base de données en arrière-plan est préférable pour un environnement de production. Cette solution offre une gestion des utilisateurs via l’interface web, le regroupement des connexions ainsi que l’historique des sessions.

Commencez par créer la base de données et l’utilisateur :

sudo mysql -e "CREATE DATABASE guacamole_db CHARACTER SET utf8mb4;"
sudo mysql -e "CREATE USER 'guacamole_user'@'localhost' IDENTIFIED BY 'MonMotDePasseSuperFort';"
sudo mysql -e "GRANT SELECT,INSERT,UPDATE,DELETE ON guacamole_db.* TO 'guacamole_user'@'localhost';"
sudo mysql -e "FLUSH PRIVILEGES;"

⚠ Remplacez bien MonMotDePasseSuperFort par un mot de passe robuste si cette instance sera mise en production.

Ensuite, on va télécharger l’extension d’authentification JDBC :

cd /tmp
wget https://downloads.apache.org/guacamole/1.6.0/binary/guacamole-auth-jdbc-1.6.0.tar.gz
tar -xzf guacamole-auth-jdbc-1.6.0.tar.gz

Importez le schéma MySQL dans la base de données :

cat /tmp/guacamole-auth-jdbc-1.6.0/mysql/schema/*.sql | sudo mysql guacamole_db

Créez le répertoire des extensions Guacamole et convertissez le fichier JAR JDBC vers l’espace de noms Jakarta :

sudo mkdir -p /etc/guacamole/extensions
sudo javax2jakarta /tmp/guacamole-auth-jdbc-1.6.0/mysql/guacamole-auth-jdbc-mysql-1.6.0.jar /etc/guacamole/extensions/guacamole-auth-jdbc-mysql-1.6.0.jar

Le fichier JAR JDBC nécessite également la conversion javax-vers-jakarta, car il s’exécute au sein de Tomcat 10. Omettre cette étape entraîne des échecs d’authentification.

Téléchargez maintenant le pilote MySQL Connector/J pour permettre à Guacamole de communiquer avec MariaDB :

sudo mkdir -p /etc/guacamole/lib
cd /tmp
wget https://dev.mysql.com/get/Downloads/Connector-J/mysql-connector-j-9.2.0.tar.gz
tar -xzf mysql-connector-j-9.2.0.tar.gz
sudo cp mysql-connector-j-9.2.0/mysql-connector-j-9.2.0.jar /etc/guacamole/lib/

MySQL Connector/J 9.2.0 fonctionne aussi bien avec MySQL qu’avec MariaDB.

Configurer guacamole.properties

Guacamole lit sa configuration principale dans le fichier /etc/guacamole/guacamole.properties. Ce fichier indique à l’application web où trouver guacd et quelle base de données utiliser pour l’authentification.

echo "guacd-hostname: localhost
guacd-port: 4822
mysql-hostname: localhost
mysql-port: 3306
mysql-database: guacamole_db
mysql-username: guacamole_user
mysql-password: MonMotDePasseSuperFort
mysql-auto-create-accounts: true" | sudo tee /etc/guacamole/guacamole.properties

Utilisez le même mot de passe que celui défini lors de la création de l’utilisateur MariaDB.

Restreignez les permissions du fichier, car il contient un mot de passe de base de données :

sudo chmod 600 /etc/guacamole/guacamole.properties
sudo chown tomcat:tomcat /etc/guacamole/guacamole.properties

Créez un lien vers le répertoire d’accueil de Guacamole afin que Tomcat puisse le trouver :

sudo ln -sf /etc/guacamole /var/lib/tomcat10/.guacamole

Redémarrez Tomcat pour prendre en compte la nouvelle configuration :

sudo systemctl restart tomcat10

A partir de cet instant là Guacamole est accessible dans le navigateur via le port 8080 mais seulement si on ajoute /guacamole à la fin de l’URL. On peut mettre Guacamole derrière un reverse proxy pour pouvoir afficher normalement Guacamole sans à ajouter /guacamole à chaque fois et éventuellement si il est exposé sur Internet lui attribuer un certificat SSL.

Bonus : mettre Guacamole derrière un reverse proxy avec certificat SSL

Vous pouvez passer cette étape si vous ne souhaitez pas exposer Guacamole via un nom de domaine ou bien tout simplement que vous n’en possédez pas un. Si vous souhaitez tout de même y accéder en dehors de votre réseau local vous pouvez utiliser Tailscale.

On installe nginx via :

sudo apt install nginx

Exécuter Guacamole derrière Nginx avec un certificat SSL permet de bénéficier de connexions chiffrées et de le rendre accessible via une URL propre, sans le suffixe de chemin “/guacamole”. Commencez par obtenir un certificat Let’s Encrypt via cette commande :

sudo certbot certonly --standalone -d guacamole.domaine.fr --non-interactive --agree-tos -m mail@domaine.fr

Remplacez guacamole.domaine.fr par votre véritable nom de domaine. Certbot a besoin que le port 80 soit libre donc par conséquent, arrêtez temporairement Nginx s’il est déjà en cours d’exécution (sudo systemctl stop nginx) avant de lancer Certbot.

Créez la configuration de l’hôte virtuel Nginx :

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

Ajoutez la configuration suivante. Les en-têtes WebSocket sont importantes car Guacamole utilise des WebSocket pour le tunnel du bureau distant :

server {
    listen 443 ssl http2;
    server_name guacamole.domaine.fr;

    ssl_certificate /etc/letsencrypt/live/guacamole.domaine.fr/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/guacamole.domaine.fr/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8080/guacamole/;
        proxy_buffering off;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $http_connection;
        proxy_cookie_path /guacamole/ /;
    }
}

server {
    listen 80;
    server_name guacamole.domaine.fr;
    return 301 https://$host$request_uri;
}

Activez le site et testez la configuration :

sudo ln -sf /etc/nginx/sites-available/guacamole /etc/nginx/sites-enabled/
sudo rm -f /etc/nginx/sites-enabled/default
sudo nginx -t

Si le resultat de la commande sudo nginx -t ne retourne aucune erreur alors démarrez Nginx :

sudo systemctl enable --now nginx

Si vous avez un pare-feu sur votre système :

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw reload

Vérifiez que le renouvellement automatique du certificat fonctionne :

sudo certbot renew --dry-run

Apache Guacamole fonctionne dés à présent accessible via https://guacamole.domaine.fr.

Bien évidemment il s’agit d’un domaine fictif donc cela devrait fonctionner depuis votre nom de domaine ou adresse IP locale.

Créer un utilisateur

Par défaut le nom d’utilisateur et le mot de passe pour se connecter est guacadmin, il est recommandé de changer le mot de passe du compte ou de le désactiver puis par la suite de créer un utilisateur administrateur. Pensez à créer un utilisateur qui possède le rôle d’administrateur avant de désactiver guacadmin si vous comptez le faire. Démo utilisateurs

En ce qui est de la création de compte, le formulaire est assez complet puisque vous avez la possiblité d’y ajouter des restrictions au niveau du compte comme :

forcer l’expiration du mot de passe qui va inviter l’utilisateur à le changer
autoriser l’accès au compte pendant une plage horaire donnée
activer et désactiver le compte pendant une plage horaire donnée
modifier son fuseau horaire

Ainsi que des permissions :

Administration du système
Audit system
Créer de nouveaux utilisateurs
Créer de nouveaux groupes d’utilisateurs
Créer de nouvelles connexions
Créer de nouveaux groupes de connexion
Créer de nouveaux profils de partage
Modifier son propre mot de passe

Audit system : est une option permettant la traçabilité des évènements lié à l’utilisation de Guacamole sous un compte où l’option est activée. Les évènements enregistrés sont les connexions et déconnexions des utilisateurs, les tentatives d’authentification (réussies ou échouées), l’ouverture et la fermeture de sessions RDP, SSH ou VNC. les modifications de la configuration (création/suppression de connexions, changements de groupes, permissions, etc.) et les opérations d’administration (création d’utilisateurs, modification des droits, etc.).

Ajouter un hôte

Pour ajouter un hôte SSH, il faut se rendre dans le menu en haut à droite en cliquant sur l’utilisateur puis dans le menu qui se déroule il faut cliquer sur Paramètres. Dans cette section se trouve différents onglets et celui qui nous intéresse est Connexions.

Paramètres

Et on clique sur Nouvelle connexion. Par ailleurs il y a aussi possibilité de créer un groupe de connexions avec possibilité là encore d’ajouter des limites :

Nombre maximum de connexions
Nombre maximum de connexions par utilisateur
Activer l’affinité de session

Pour ajouter un hôte il y a de nombreuses options qui sont à notre disposition. l’authentification par clé SSH est possible. Vous avez également possibilité de faire du Wake On LAN.

Documentation d’Apache Guacamole

Les fonctionnalités clés#

Mise en place du serveur#

Conditions d’installation#

Installation des prérequis#

Compilation du serveur#

Déployer l’application web Guacamole#

Configurer MariaDB#

Configurer guacamole.properties#

Bonus : mettre Guacamole derrière un reverse proxy avec certificat SSL#

Créer un utilisateur#

Ajouter un hôte#