Come installare Guacamole su Ubuntu 22.04

Architettura di Guacamole su Ubuntu 22.04

Guacamole non è un semplice pacchetto da installare e basta: su Ubuntu 22.04 la strada più pulita è separare i componenti. Ti servono guacd come broker delle sessioni, Tomcat per pubblicare l’applicazione web e un database MySQL o MariaDB per conservare utenti, connessioni e permessi. Se fai tutto su una sola macchina, la configurazione resta semplice; se invece prevedi più carico o vuoi ridurre il blast radius, il database può essere spostato senza cambiare il modello applicativo.

La scelta pratica su Ubuntu 22.04 è questa: installi i pacchetti dai repository, scarichi il file WAR di Guacamole, configuri il database con lo schema ufficiale, colleghi Tomcat a guacd e poi limiti l’esposizione al solo HTTPS. Il punto da non saltare è la parte di verifica: se Guacamole si apre ma non salva le connessioni, di solito il problema è nel file di properties o nei permessi del database, non nel front-end.

Prerequisiti e scelte operative

Assumo una VM o un server Ubuntu 22.04 aggiornato, accesso root o sudo, DNS già puntato al nome host che userai per Guacamole e almeno 2 GB di RAM. Con meno memoria si installa comunque, ma Tomcat e il database iniziano a competere con il resto del sistema appena apri più sessioni contemporanee.

Per ridurre i problemi, conviene definire subito tre scelte: porta di ascolto interna, nome FQDN pubblico e backend database. Nell’esempio userò MariaDB locale, Tomcat 9 e Guacamole esposto dietro Apache con HTTPS. Se preferisci Nginx come reverse proxy, il modello non cambia: cambia solo la parte di terminazione TLS e forwarding verso Tomcat.

Aggiornamento base e pacchetti necessari

Prima di installare Guacamole, aggiorna il sistema e porta in casa i pacchetti base. Questo evita di inseguire bug già risolti in sicurezza o dipendenze mancanti di Java, database e compilazione nativa.

Comandi consigliati:

sudo apt update
sudo apt -y upgrade
sudo apt -y install build-essential libcairo2-dev libjpeg-turbo8-dev libpng-dev \
    libtool-bin libossp-uuid-dev libavcodec-dev libavformat-dev libavutil-dev \
    libswscale-dev freerdp2-dev libpango1.0-dev libssh2-1-dev libtelnet-dev \
    libvncserver-dev libpulse-dev libwebsockets-dev ghostscript \
    tomcat9 tomcat9-admin tomcat9-common mariadb-server wget curl unzip

Su alcune installazioni alcuni pacchetti possono avere nomi leggermente diversi in base ai repository abilitati. Se `apt` segnala un pacchetto non trovato, verifica con `apt-cache search nomepacchetto` e sostituisci solo il nome mancante, non l’intero blocco.

Installazione di guacd e compilazione dei moduli nativi

Su Ubuntu i pacchetti di Guacamole presenti nei repository non sono sempre allineati alla versione web che scarichi dal sito ufficiale. Per evitare mismatch, il metodo più robusto è installare guacd dai repository e usare il file WAR corrispondente alla stessa versione della libreria client.

Installa il demone:

sudo apt -y install guacd libguac-client-*

Se il wildcard non viene risolto dal tuo mirror o dai repository, usa l’elenco dei pacchetti disponibili con:

apt-cache search guac

Il servizio deve risultare attivo prima di andare oltre:

systemctl status guacd --no-pager

Atteso: stato active (running) e ascolto sulla porta locale 4822. Se non parte, controlla i log con journalctl -u guacd -b --no-pager e verifica che le librerie installate siano coerenti con la versione del pacchetto.

Database MariaDB: schema e utente dedicato

Guacamole salva autenticazione e definizioni delle connessioni nel database. Qui conviene essere rigorosi: utente dedicato, privilegi minimi, password forte generata e mai scritta in chiaro in documenti condivisi.

Proteggi MariaDB se non l’hai già fatto:

sudo mysql_secure_installation

Crea database e utente applicativo:

sudo mysql -u root -p

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

Non riuso la password in chiaro nel testo: va generata con un password manager o con un comando temporaneo e poi redatta dal tuo sistema di documentazione. Il punto non è estetico, è ridurre l’esposizione accidentale.

Scarica lo schema ufficiale della versione che stai installando. L’errore classico è importare uno schema non corrispondente al WAR. Dopo il download, estrai i file SQL e importa prima le tabelle base e poi i dati iniziali.

Esempio operativo:

cd /tmp
wget https://downloads.apache.org/guacamole/1.5.5/binary/guacamole-auth-jdbc-1.5.5.tar.gz
wget https://downloads.apache.org/guacamole/1.5.5/binary/guacamole-1.5.5.war
mkdir -p /tmp/guacamole
cd /tmp/guacamole
sudo tar -xzf /tmp/guacamole-auth-jdbc-1.5.5.tar.gz
sudo mysql -u root -p guacamole_db < /tmp/guacamole/guacamole-auth-jdbc-1.5.5/mysql/schema/*.sql

Se il path dello schema cambia nella tua release, esplora l’archivio con find. L’obiettivo è chiaro: il database deve contenere le tabelle di Guacamole prima del primo avvio dell’app.

Configurazione di Guacamole Server

Il file chiave è /etc/guacamole/guacamole.properties. Qui dici a Guacamole dove trova il database e il demone guacd. Se sbagli un indirizzo o una porta, l’interfaccia web può aprirsi ma le sessioni non partono.

Crea la directory di configurazione e definisci il file:

sudo mkdir -p /etc/guacamole
sudo tee /etc/guacamole/guacamole.properties > /dev/null <<'EOF'
guacd-hostname: localhost
guacd-port: 4822
mysql-hostname: localhost
mysql-port: 3306
mysql-database: guacamole_db
mysql-username: guacamole_user
mysql-password: PASSWORD_FORTE_GENERATA
EOF

Subito dopo crea il link per il contesto di Tomcat e la variabile di ambiente che punta alla directory di configurazione:

sudo mkdir -p /etc/guacamole/extensions
sudo mkdir -p /etc/guacamole/lib
sudo ln -sfn /etc/guacamole /usr/share/tomcat9/.guacamole

Copiando il driver JDBC e le estensioni nel posto giusto, eviti il classico errore “l’app parte ma non vede il database”. I file vanno in /etc/guacamole/lib e /etc/guacamole/extensions.

Installa il driver JDBC e l’estensione database:

sudo cp /tmp/guacamole/guacamole-auth-jdbc-1.5.5/mysql/guacamole-auth-jdbc-mysql-1.5.5.jar /etc/guacamole/extensions/
sudo cp /usr/share/java/mysql-connector-java.jar /etc/guacamole/lib/ 2>/dev/null || true

Se il connector non è presente nel path indicato, individua il jar corretto con dpkg -L o installa il pacchetto dedicato del driver MySQL/MariaDB disponibile nella tua release. Qui non va improvvisato: il nome cambia tra versioni Ubuntu.

Deploy del WAR in Tomcat

Ora metti il WAR nella directory di deploy di Tomcat. Su Ubuntu 22.04 il percorso tipico è /var/lib/tomcat9/webapps/. Quando Tomcat vede il file, lo espande e pubblica l’applicazione sotto il nome del file o sotto la radice se rinomini il WAR in ROOT.war.

Comandi:

sudo cp /tmp/guacamole/guacamole-1.5.5.war /var/lib/tomcat9/webapps/guacamole.war
sudo chown tomcat:tomcat /var/lib/tomcat9/webapps/guacamole.war
sudo systemctl restart tomcat9
sudo systemctl status tomcat9 --no-pager

Se l’app non si espande, guarda i log di Tomcat in /var/log/tomcat9/catalina.out o nel journal di sistema. Il sintomo tipico è un errore Java di classpath o un driver JDBC mancante.

Test funzionale: login e prima connessione

A questo punto apri il browser su http://IP_SERVER:8080/guacamole oppure sul path che hai scelto dietro reverse proxy. Al primo accesso, se lo schema è stato importato correttamente, dovresti poter entrare con le credenziali iniziali previste dalla tua versione o con l’utente creato via SQL, se hai già predisposto autenticazione esterna.

Per una verifica minima, crea una connessione RDP o SSH verso un host di test. Se la pagina si apre ma il tunnel fallisce, il problema è quasi sempre in uno di questi punti: guacd non raggiungibile, driver mancante, regole firewall o credenziali remote errate.

Controlli rapidi da shell:

curl -I http://127.0.0.1:8080/guacamole
ss -lntp | grep -E '(:8080|:4822|:3306)'
journalctl -u guacd -b --no-pager | tail -n 50
journalctl -u tomcat9 -b --no-pager | tail -n 50

Atteso: HTTP 200 o 302 sul front-end, porta 4822 in ascolto per guacd e nessun errore ripetuto nel journal. Se trovi errori di connessione al database, torna al file /etc/guacamole/guacamole.properties e verifica hostname, porta e credenziali.

Reverse proxy HTTPS con Apache

Esporre Tomcat direttamente su Internet non è una buona idea. La pratica corretta è mettere Apache davanti, terminare TLS e inoltrare verso Tomcat in locale. In questo modo riduci l’esposizione, centralizzi i certificati e puoi aggiungere header di sicurezza senza toccare l’applicazione.

Abilita i moduli necessari:

sudo apt -y install apache2 certbot python3-certbot-apache
sudo a2enmod proxy proxy_http proxy_wstunnel headers rewrite ssl
sudo systemctl restart apache2

Configurazione virtual host essenziale:

<VirtualHost *:443>
    ServerName guacamole.example.com

    SSLEngine on
    ProxyPreserveHost On
    ProxyRequests Off

    RequestHeader set X-Forwarded-Proto "https"
    ProxyPass /guacamole http://127.0.0.1:8080/guacamole
    ProxyPassReverse /guacamole http://127.0.0.1:8080/guacamole

    ProxyPass /guacamole/websocket ws://127.0.0.1:8080/guacamole/websocket
    ProxyPassReverse /guacamole/websocket ws://127.0.0.1:8080/guacamole/websocket
</VirtualHost>

Dopo aver salvato il file in /etc/apache2/sites-available/guacamole.conf, abilita il sito e ricarica Apache. Se usi Certbot, lascia che generi anche il redirect da HTTP a HTTPS.

Verifica TLS con:

sudo apache2ctl configtest
sudo systemctl reload apache2
curl -Ik https://guacamole.example.com/guacamole

Atteso: nessun errore di sintassi, risposta 200/302 e certificato valido. Se il websocket non passa, la sessione si connette ma resta in caricamento o si disconnette subito: in quel caso ricontrolla il modulo proxy_wstunnel e la direttiva sul path websocket.

Autenticazione e hardening di base

Guacamole funziona già con il database locale, ma in produzione conviene pensare subito all’autenticazione e alla superficie esposta. Se lo lasci pubblicamente raggiungibile, il minimo sindacale è MFA tramite provider esterno, password robuste e accesso limitato a IP fidati quando possibile.

Pratiche sane da applicare subito:

• limita l’accesso a 443 con firewall o security group;
• non esporre Tomcat su Internet se Apache fa da reverse proxy;
• mantieni aggiornati Java, Tomcat, MariaDB e il WAR;
• ruota periodicamente le credenziali del database e degli account amministrativi;
• se usi LDAP, OIDC o SSO, valida prima i flussi su ambiente di test.

Con UFW, un profilo minimo può essere questo:

sudo ufw allow 22/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status verbose

Il controllo da fare dopo è semplice: da una rete esterna deve restare visibile solo il servizio web pubblicato, non la porta 8080 di Tomcat né la 4822 di guacd.

Backup e ripristino senza sorprese

Il vero valore di Guacamole sta nei dati nel database. Backup del WAR o dei file di configurazione senza dump SQL serve a poco. La base minima di protezione è: dump del database, copia di /etc/guacamole/guacamole.properties e inventario delle estensioni installate.

Esempio di backup coerente:

sudo mysqldump guacamole_db > /root/backup-guacamole-db.sql
sudo tar -czf /root/backup-guacamole-conf.tgz /etc/guacamole

Per il ripristino, il flusso è inverso: database prima, configurazione poi, restart di guacd e Tomcat, infine test di login. Se la versione del WAR è cambiata, controlla la compatibilità dello schema prima di importare il dump. In caso di rollback di un cambio recente, torna al backup del file properties e al WAR precedente, non solo al dump del database.

Problemi tipici e lettura rapida dei sintomi

Ci sono alcuni errori che tornano quasi sempre. Pagina bianca o errore 500: controlla Tomcat e il classpath. Login riuscito ma nessuna connessione: guacd non raggiungibile o driver mancante. Interfaccia lenta: spesso non è Guacamole, ma il server remoto, il DNS, o un proxy che non gestisce bene i websocket. Se il browser mostra un caricamento infinito sulla sessione, guarda subito i log lato Tomcat e la reachability verso la porta 4822.

Un controllo sintetico utile è questo:

sudo ss -lntp | grep 4822
sudo journalctl -u guacd -b --no-pager | tail -n 20
sudo journalctl -u tomcat9 -b --no-pager | tail -n 50
sudo tail -n 50 /var/log/apache2/error.log

Se vuoi un’installazione stabile nel tempo, il punto non è solo farla partire: devi anche sapere dove guardare quando qualcosa si rompe. Con Guacamole il triangolo da tenere sotto controllo è sempre lo stesso: Tomcat, guacd, database. Se quei tre elementi sono sani, il resto di solito è rete o credenziali.

Assunzione operativa: installazione single-node su Ubuntu 22.04 con Apache davanti, MariaDB locale e Guacamole usato per accesso remoto amministrativo.