Installation d'Apache Guacamole 1.6.0 sur Ubuntu Server - guide complet : mon retour d'expérience complet

Dans mon poste de DevSecOps, j'ai eu besoin de mettre en place un bastion d'accès sécurisé pour permettre aux équipes d'accéder à des serveurs distants sans exposer les ports SSH/RDP directement sur Internet. Mon choix s'est porté sur Apache Guacamole - un client de bureau à distance sans agent, accessible depuis un simple navigateur web.

Ce que tu vas apprendre dans cet article : installer Guacamole 1.6.0 from scratch sur Ubuntu Server, configurer la base de données MariaDB, activer l'enregistrement de sessions, et résoudre les bugs que j'ai rencontrés en chemin. Parce que oui, il y en a eu.

Prérequis : Ubuntu Server 22.04, accès root ou sudo, connexion internet.

C'est quoi Guacamole et pourquoi l'utiliser ?

Apache Guacamole est une passerelle d'accès à distance open source. Concrètement, tu accèdes à tes serveurs SSH, RDP ou VNC depuis ton navigateur - sans installer aucun client. Tout passe par le serveur Guacamole qui fait le pont.

L'architecture est composée de deux parties :

guacd - le démon proxy qui parle les protocoles distants (SSH, RDP, VNC)
guacamole-client - l'application web Java déployée sur Tomcat

Étape 1 : Compiler le serveur Guacamole depuis les sources

Installer les dépendances

La première chose à faire c'est d'installer toutes les bibliothèques nécessaires à la compilation. Chaque bibliothèque correspond à un protocole ou une fonctionnalité :

sudo apt update
sudo apt install build-essential libcairo2-dev libjpeg-turbo8-dev libpng-dev \
  libtool-bin libossp-uuid-dev libvncserver-dev freerdp2-dev libssh2-1-dev \
  libtelnet-dev libwebsockets-dev libpulse-dev libvorbis-dev libwebp-dev \
  libssl-dev libpango1.0-dev libswscale-dev libavcodec-dev libavutil-dev \
  libavformat-dev

Pourquoi autant de dépendances ? Chaque lib correspond à quelque chose de précis :

freerdp2-dev - support du protocole RDP (Windows)
libssh2-1-dev - support SSH
libvncserver-dev - support VNC
libssl-dev - chiffrement HTTPS
libpango1.0-dev - rendu du texte à l'écran

Télécharger et extraire les sources

wget https://archive.apache.org/dist/guacamole/1.6.0/source/guacamole-server-1.6.0.tar.gz
tar -xvzf guacamole-server-1.6.0.tar.gz
mv guacamole-server-1.6.0 guacamole-server
cd guacamole-server

Ou directement depuis GitHub :

git clone https://github.com/apache/guacamole-server.git
cd guacamole-server

Compiler

autoreconf -fi
./configure --with-systemd-dir=/usr/local/lib/systemd/system
make
sudo make install
sudo ldconfig

Explication des commandes :

autoreconf -fi - régénère les scripts de configuration (obligatoire si tu clones depuis Git)
./configure - vérifie que toutes les dépendances sont présentes et prépare le build. L'option --with-systemd-dir indique où placer le fichier service systemd.
make - compile le code source
sudo make install - installe les binaires compilés sur le système
sudo ldconfig - met à jour le cache des bibliothèques partagées

Après le ./configure, tu verras un résumé des protocoles supportés. Vérifie que SSH, RDP et VNC sont bien activés :

Protocol support:
  RDP ............ yes
  SSH ............ yes
  VNC ............ yes

Démarrer le service guacd

sudo systemctl daemon-reload
sudo systemctl start guacd
sudo systemctl enable guacd
systemctl status guacd

Pour vérifier que guacd écoute bien sur le port 4822 :

sudo ss -lnpt | grep guacd
# Résultat attendu :
# LISTEN 0  5  [::1]:4822  [::]:*  users:(("guacd",pid=XXXX,fd=4))

Étape 2 : Installer l'application web Guacamole

Guacamole est une application Java. Elle a besoin d'un conteneur de servlets Java - Apache Tomcat.

Installer Tomcat

sudo apt install tomcat9 tomcat9-admin tomcat9-common tomcat9-user

Tomcat démarre automatiquement et écoute sur le port 8080. Pour vérifier :

sudo ss -lnpt | grep java
# LISTEN 0  100  *:8080  *:*  users:(("java",pid=XXXX,fd=37))

Note : Si un autre service écoute déjà sur le port 8080, Tomcat ne pourra pas démarrer. Configure l'autre service sur un autre port, puis redémarre Tomcat : sudo systemctl restart tomcat9.

Télécharger le fichier WAR de Guacamole

Au lieu de compiler le client depuis les sources (ce qui nécessite Maven et prend du temps), on télécharge directement le fichier WAR précompilé :

wget https://downloads.apache.org/guacamole/1.6.0/binary/guacamole-1.6.0.war
sudo mv guacamole-1.6.0.war /var/lib/tomcat9/webapps/guacamole.war

Le fichier WAR est l'équivalent d'un .jar pour les applications web Java. En le plaçant dans le répertoire webapps de Tomcat, il sera automatiquement déployé.

sudo systemctl restart tomcat9
sudo systemctl start guacd
sudo systemctl enable tomcat9
sudo systemctl enable guacd

Étape 3 : Configurer la base de données MariaDB

Par défaut, Guacamole stocke les utilisateurs et connexions dans des fichiers XML. Pour une utilisation en production, on utilise une base de données. J'ai choisi MariaDB.

Installer et sécuriser MariaDB

sudo apt install mariadb-server
sudo systemctl start mariadb
sudo systemctl enable mariadb
sudo mysql_secure_installation

Pendant mysql_secure_installation, réponds comme suit :

Switch to unix_socket authentication → N
Change the root password → Y (mets un mot de passe fort)
Remove anonymous users → Y
Disallow root login remotely → Y
Remove test database → Y
Reload privilege tables → Y

Créer la base de données Guacamole

mysql -u root -p

CREATE DATABASE guacamole_db;
CREATE USER 'guacamole_user'@'localhost' IDENTIFIED BY 'YOUR_DB_PASSWORD';
GRANT SELECT,INSERT,UPDATE,DELETE ON guacamole_db.* TO 'guacamole_user'@'localhost';
FLUSH PRIVILEGES;
quit;

Pourquoi donner uniquement SELECT, INSERT, UPDATE, DELETE et pas tous les droits ? C'est le principe du moindre privilège - l'application n'a accès qu'à ce dont elle a besoin. Si le compte est compromis, l'attaquant ne peut pas supprimer la base ou créer de nouveaux utilisateurs MySQL.

Installer le module d'authentification MySQL

wget https://downloads.apache.org/guacamole/1.6.0/binary/guacamole-auth-jdbc-1.6.0.tar.gz
tar -xvf guacamole-auth-jdbc-1.6.0.tar.gz
sudo mkdir -p /etc/guacamole/extensions
sudo cp guacamole-auth-jdbc-1.6.0/mysql/guacamole-auth-jdbc-mysql-1.6.0.jar \
  /etc/guacamole/extensions/

Importer le schéma SQL

cat guacamole-auth-jdbc-1.6.0/mysql/schema/*.sql | mysql -u root -p guacamole_db

Cette commande importe toutes les tables nécessaires à Guacamole dans ta base de données.

Installer le pilote JDBC MySQL

wget https://repo1.maven.org/maven2/com/mysql/mysql-connector-j/8.0.33/mysql-connector-j-8.0.33.jar
sudo mkdir -p /etc/guacamole/lib
sudo mv mysql-connector-j-8.0.33.jar /etc/guacamole/lib/
sudo systemctl restart mariadb

Le pilote JDBC est le pont entre Java (Tomcat/Guacamole) et MySQL/MariaDB. Sans lui, l'application ne peut pas parler à la base de données.

Étape 4 : Configurer Guacamole

sudo mkdir -p /etc/guacamole/{extensions,lib}
sudo nano /etc/guacamole/guacamole.properties

Contenu du fichier :

# Connexion à guacd
guacd-hostname: 0.0.0.0
guacd-port: 4822

# Base de données MySQL
mysql-hostname: localhost
mysql-port: 3306
mysql-database: guacamole_db
mysql-username: guacamole_user
mysql-password: YOUR_DB_PASSWORD

# Enregistrement de sessions
recording-search-path: /var/lib/guacamole/recordings
enable-shared-connections: true

Bug rencontré : guacd écoute sur ::1 au lieu de 0.0.0.0

C'est le bug qui m'a le plus bloquée. Après le démarrage, guacd écoutait uniquement sur ::1 (localhost IPv6) alors que Tomcat essayait de s'y connecter via IPv4. Résultat : Connection refused à chaque tentative de connexion.

La solution : créer le fichier /etc/guacamole/guacd.conf :

sudo nano /etc/guacamole/guacd.conf

[server]
bind_host = 0.0.0.0
bind_port = 4822

sudo systemctl daemon-reload
sudo systemctl restart tomcat9 guacd

Après ça, guacd écoute bien sur toutes les interfaces :

sudo ss -lnpt | grep guacd
# LISTEN 0  5  0.0.0.0:4822  0.0.0.0:*

Étape 5 : Activer l'enregistrement de sessions

L'enregistrement de sessions est une fonctionnalité indispensable dans un contexte professionnel - elle permet de rejouer chaque session SSH/RDP pour des audits ou investigations.

wget https://archive.apache.org/dist/guacamole/1.6.0/binary/guacamole-history-recording-storage-1.6.0.tar.gz
tar -xzf guacamole-history-recording-storage-1.6.0.tar.gz
sudo cp guacamole-history-recording-storage-1.6.0/guacamole-history-recording-storage-1.6.0.jar \
  /etc/guacamole/extensions/

sudo mkdir -p /var/lib/guacamole/recordings
sudo mkdir -p /var/lib/guacamole/typescripts
sudo chown -R daemon:daemon /var/lib/guacamole/recordings
sudo chown -R daemon:daemon /var/lib/guacamole/typescripts
sudo usermod -aG daemon tomcat
sudo chmod -R 750 /var/lib/guacamole/recordings
sudo chmod -R 750 /var/lib/guacamole/typescripts
sudo systemctl restart guacd tomcat9

Pourquoi cette méthode fonctionne - et pas les autres

C'est le point qui m'a pris le plus de temps à comprendre. Guacamole implique deux processus distincts qui ont besoin d'accéder aux enregistrements :

guacd (qui tourne sous l'utilisateur daemon) - c'est lui qui écrit les fichiers d'enregistrement pendant les sessions
Tomcat (qui tourne sous l'utilisateur tomcat) - c'est lui qui lit les fichiers pour les afficher dans l'historique

Le problème : si tu mets le propriétaire à tomcat, guacd ne peut pas écrire. Si tu mets daemon, Tomcat ne peut pas lire. C'est une impasse.

La solution élégante :

On donne la propriété des dossiers à daemon - guacd peut écrire
On ajoute tomcat au groupe daemon avec usermod -aG daemon tomcat - Tomcat hérite des droits de groupe
On met les permissions à 750 - le propriétaire (daemon) a tous les droits, le groupe (dont tomcat fait maintenant partie) peut lire et exécuter

drwxr-x--- 2 daemon daemon  recordings/   ← daemon écrit, groupe daemon (tomcat) lit
drwxr-x--- 2 tomcat tomcat  typescripts/  ← tomcat écrit et lit

J'avais d'abord essayé de tout mettre en 777 pour débloquer rapidement - ça marche mais c'est une mauvaise pratique de sécurité. N'importe quel processus sur le serveur peut alors lire tes enregistrements de sessions. La méthode ci-dessus respecte le principe du moindre privilège.

Bug rencontré : colonne Journaux vide dans l'historique

Après avoir activé l'enregistrement, la colonne "Journaux" dans l'historique restait vide. Le problème : Guacamole ne savait pas où chercher les fichiers d'enregistrement.

Solution - il manquait la colonne history_uuid dans la table guacamole_connection_history :

sudo mysql -u root -p guacamole_db < \
  /home/ubuntu/guacamole-auth-jdbc-1.6.0/mysql/schema/upgrade/upgrade-pre-1.6.0.sql

mysql -u root -p guacamole_db -e \
  "ALTER TABLE guacamole_connection_history ADD COLUMN history_uuid CHAR(36) DEFAULT NULL;"

mysql -u root -p guacamole_db -e \
  "CREATE TRIGGER guacamole_connection_history_uuid BEFORE INSERT ON
  guacamole_connection_history FOR EACH ROW SET NEW.history_uuid = UUID();"

Accéder à Guacamole

Redémarre les services et accède à l'interface :

sudo systemctl restart tomcat9 guacd

Ouvre ton navigateur sur http://IP_SERVEUR:8080/guacamole

Les identifiants par défaut sont guacadmin / guacadmin. Change-les immédiatement après ta première connexion et crée un nouvel utilisateur admin, puis supprime le compte par défaut.

Ce que j'ai appris

Cette installation m'a appris quelque chose d'important : toujours lire les logs. La majorité des bugs que j'ai rencontrés étaient clairement expliqués dans /var/log/tomcat9/catalina.out. Quand quelque chose ne marche pas, c'est la première commande à lancer :

sudo tail -f /var/log/tomcat9/catalina.out

Dans le prochain article, je couvrirai l'intégration SSO avec Keycloak via OpenID Connect - pour que tes utilisateurs se connectent à Guacamole avec leur compte Keycloak sans avoir de compte Guacamole séparé.

Tags : Guacamole, Admin Linux, Bastion, Ubuntu, DevSecOps, SSH