Aufsetzen eines Apache Guacamole Proxy

Um remote auf bwLehrpool-Clients zugreifen zu können (Remotenutzung von bwLehrpool), benötigen Sie einen Apache Guacamole-Server.

In dieser Anleitung wird Ubuntu 20.04.2 LTS als Basis-OS genutzt und Guacamole in der Version 1.3.0 verwendet.

Sie können Guacamole entweder direkt aus den Sources bauen und installieren oder alternativ in Docker-Containern bereitstellen. Zusätzlich wird ein Webserver benötigt (im Beispiel wird Apache verwendet).

Installation von Guacamole

  • Installation benötigter Abhängigkeiten
    apt install apache2 freerdp2-dev gcc libavcodec-dev libavformat-dev libavutil-dev libcairo2-dev libjpeg-turbo8-dev libossp-uuid-dev libpango1.0-dev libpng-dev libpulse-dev libssh2-1-dev libssl-dev libswscale-dev libtool-bin libvncserver-dev libvorbis-dev libwebp-dev libwebsockets-dev make tomcat9
  • Guacamole 1.3.0 herunterladen

    mkdir /usr/src && cd /usr/src
    wget http://mirror.ibcp.fr/pub/apache/guacamole/1.3.0/binary/guacamole-1.3.0.war
    wget http://mirror.ibcp.fr/pub/apache/guacamole/1.3.0/binary/guacamole-auth-ldap-1.3.0.tar.gz
    wget http://mirror.ibcp.fr/pub/apache/guacamole/1.3.0/source/guacamole-server-1.3.0.tar.gz
  • Sources entpacken

    tar xzf guacamole-server-1.3.0.tar.gz
  • Configure aufrufen

    cd /usr/src/guacamole-server-1.3.0
    ./configure --with-systemd-dir=/etc/systemd/system  
  • Die Ausgabe sollte bei korrekter Installation der Abhängigkeiten in etwa so aussehen:

    #------------------------------------------------
    guacamole-server version 1.3.0
    #------------------------------------------------
     
       Library status:
     
         freerdp2 ............ yes
         pango ............... yes
         libavcodec .......... yes
         libavformat.......... yes
         libavutil ........... yes
         libssh2 ............. yes
         libssl .............. yes
         libswscale .......... yes
         libtelnet ........... no
         libVNCServer ........ yes
         libvorbis ........... yes
         libpulse ............ yes
         libwebsockets ....... yes
         libwebp ............. yes
         wsock32 ............. no
     
       Protocol support:
     
          Kubernetes .... yes
          RDP ........... yes
          SSH ........... yes
          Telnet ........ no
          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.
     
  • Kompilieren und Installieren

      make
      make install
      ldconfig
  • Guacamole Server Service

    systemctl enable guacd
    systemctl start guacd
  • GUACAMOLE_HOME anlegen und setzen

    # GUACAMOLE_HOME dir anlegen
    mkdir /etc/guacamole
    echo 'GUACAMOLE_HOME="/etc/guacamole"' >> /etc/environment

Guacamole-Client installieren und starten

  cp /usr/src/guacamole-1.3.0.war /var/lib/tomcat9/webapps/guacamole.war
 
  # Verlinke die Konfigurationsdateien 
  ln -s /etc/guacamole /usr/share/tomcat9/.guacamole
 
  # Service neustarten
  systemctl restart tomcat9.service
  systemctl restart guacd.service

LDAP-Plugin installieren

Authentifizieren via LDAP ermöglichen.

cd /usr/src/
tar xvzf guacamole-auth-ldap-1.3.0.tar.gz
 
# extensions Verzeichnis anlegen
mkdir /etc/guacamole/extensions
cp /usr/src/guacamole-auth-ldap-1.3.0/guacamole-auth-ldap-1.3.0.jar /etc/guacamole/extensions/

Update guacamole.properties für LDAP

Die Konfigurationsdatei guacamole.properties unter `/etc/guacamole/` muss entsprechend für LDAP erweitert werden. Hinweis: Kein Whitespace vor Lineendings!

vi /etc/guacamole/guacamole.properties
# LDAP Einstellungen für Active Directory
# IP-Adresse oder DNS-Name eines Domänencontrollers
ldap-hostname:
# Port Nummer von LDAP
ldap-port:
# Verschlüsslungsmethode für LDAP-Verbindung
ldap-encryption-method:
# DN des Benutzer der für die Abfrage genutzt werden
ldap-user-base-dn:
# Set searchbase to search for users in subtree
ldap-search-bind-dn:
# rename attribute name to cn (default: uid)
ldap-username-attribute:

Guacamole LDAP - weitere Informationen

LDAP Cert installieren

Falls Ihr LDAP Server verschlüsselt kommuniziert, müssen Sie evtl. ein entsprechendes Zertifikat importieren.

# Copy your CA to dir /usr/local/share/ca-certificates/
cp CERT.crt /usr/local/share/ca-certificates/
 
# Update CA Store:
update-ca-certificates
 
# Tomcat neustarten
systemctl restart tomcat9

BWLP-Plugin installieren

In diesem Schritt verknüpfen Sie Guacamole mit Ihrem Satellitenserver. Sie müssen dazu das aktuelle bwlp-guac-plugin herunterladen.

Achten Sie darauf, dass immer nur ein bwlp-Plugin verwendet wird! Löschen Sie ältere Pluginversionen, da es ansonsten zu Fehlverhalten kommen kann.

# Das aktuelle bwlp-plugin muss im Guacamole extensions Verzeichnis abgelegt werden
cd /etc/guacamole/extensions/
rm -i bwlp-guac*.jar
wget https://files.bwlp.ks.uni-freiburg.de/satellit/guacamole/bwlp-guac-1.3.1-SNAPSHOT.jar
 
# Um das Plugin mit dem bwLehrpool-Satellitenserver zu verbinden, folgende Zeile in '/etc/guacamole/guacamole.properties' einfügen:
slx-client-list-url: https://<SAT-IP>/slx-admin/api.php?do=remoteaccess

Alternative: Container Setup

Guacamole-Server und -Client sind auch als Container Images verfügbar. Nachfolgend wird die Einrichtung mit der Docker Engine durchgeführt. Als Webserver für das Routing und die Zertifikatsverwaltung dient eine lokale Installation des Apache-Webserver.

Setup bwLehrpool-Remote

Nachdem der Docker-Host vorbereitet ist, kann das Setup für die Anwendungs-Container durchgeführt werden.

  1. Starten des Guacamole-Server (guacd).

    docker run --log-driver local --name guacd -d \
     --restart unless-stopped \
     guacamole/guacd
  2. Entsprechend der folgenden Struktur die Verzeichnisse für das GUACAMOLE_HOME anlegen. In guacamole.properties die Zeile slx-client-list-url: https://<SAT-IP>/slx-admin/api.php?do=remoteaccess mit der SAT-IP einfügen.

    |/guacamole
    |-- guacamole.properties
    |-- extensions/
    |    |-- bwlp-guac-<VERSION>.jar
    |    |-- guacamole-auth-ldap-1.3.0.jar
  3. Danach ist ein Container des Guacamole-Clients zu starten, hierbei muss für Betrieb und Authentifizierung eine Datenbank oder LDAP konfiguriert werden. Die LDAP-Konfiguration ist entsprechend der lokalen LDAP-Instanz individuell festzulegen. Um das bwLehrpool-Plugin in der Container-Lösung verfügbar zu machen, das erstellte Verzeichnis in den Container mounten und als GUACAMOLE_HOME deklarieren.

    docker run --log-driver local --name guacamole \
     --link guacd:guacd \
     -e LDAP_HOSTNAME=<LDAP-HOSTNAME> \
     -e LDAP_PORT=<PORT> [389|363]\
     -e LDAP_ENCRYPTION_METHOD= ["none"|"ssl"|"starttls"] \
     -e LDAP_USER_BASE_DN=<ou="",o=""> \
     -e LDAP_SEARCH_BIND_DN=<ou="",o=""> \
     -e LDAP_USERNAME_ATTRIBUTE= <DEFAULT=uid> \
     -d \
     --restart unless-stopped \
     -p 8080:8080 \
     -v /guacamole:/guacamole \
     -e GUACAMOLE_HOME=/guacamole \
     guacamole/guacamole:1.3.0
  4. Falls ein Zertifikat für den LDAP-Server erforderlich ist, muss dieses noch innerhalb des Containers gesetzt werden.

    docker cp CERT.crt guacamole:/usr/local/share/ca-certificates/
    docker exec -it guacamole update-ca-certificates

Apache Reverse Proxy einrichten

Reverse Proxy-Konfiguration für Apache anlegen und entsprechende Module aktivieren.

# Apache Module aktivieren
a2enmod rewrite
a2enmod proxy_http
a2enmod ssl
a2enmod proxy_wstunnel

Nachfolgender Inhalt in .conf datei einfügen

vi /etc/apache2/sites-available/bwlehrpool-remote.hs-xyz.de.conf

IP (10.9.8.7) und FQDN (bwlehrpool-remote.hs-xyz.de) sind Platzhalter und müssen entsprechend angepasst werden:

<VirtualHost 10.9.8.7:80>
        ServerName bwlehrpool-remote.hs-xyz.de
        ServerAdmin webmaster@test.de
 
        RewriteEngine On
        RewriteCond %{HTTPS} !=on
        RewriteRule ^/?(.*) https://%{SERVER_NAME}/$1 [R,L]
</VirtualHost>
 
 
<VirtualHost 10.9.8.7:443>
        ServerName bwlehrpool-remote.hs-xyz.de
        ServerAdmin webmaster@test.de
 
        SSLEngine on
        SSLProtocol All -SSLv2 -SSLv3
        SSLCertificateFile /etc/ssl/certs/apache-selfsigned.crt
        SSLCertificateKeyFile /etc/ssl/private/apache-selfsigned.key
 
        RewriteEngine  on
        RewriteRule    "^/guacamole"  "/" [R]
 
        ProxyPass / http://10.9.8.7:8080/guacamole/ flushpackets=on
        ProxyPassReverse / http://10.9.8.7:8080/guacamole/
        ProxyPassReverseCookiePath /guacamole /
 
        <Location /websocket-tunnel>
                Order allow,deny
                Allow from all
                ProxyPass ws://10.9.8.7:8080/guacamole/websocket-tunnel
                ProxyPassReverse ws://10.9.8.7:8080/guacamole/websocket-tunnel
        </Location>
        SetEnvIf Request_URI "^/tunnel" dontlog
        CustomLog  /var/log/apache2/guac.log common env=!dontlog
</VirtualHost>
# Selbst signiertes Zertifikat erstellen (besser Let's Encrypt oder korrektes Hochschulzertifikat verwenden)
openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /etc/ssl/private/apache-selfsigned.key -out /etc/ssl/certs/apache-selfsigned.crt
 
# Seite aktivieren:
a2ensite bwlehrpool-remote.hs-xyz.de.conf
 
# Webserver neustarten
systemctl restart apache2

Docker-Compose

Weiterhin ist es auch möglich, sämtliche Services die für den Remotezugang erforderlich sind, als Docker-Compose zu starten bzw. zu verwalten. Die erfoderliche Struktur und nötigen Konfigurationen sind in dem Archive bwlp-remote.tgz zusammengefasst.

Voraussetzung

Vorbereitung

Laden Sie das Archive bwlp-remote.tgz auf ihren Server herunter und entpacken Sie es. Danach müssen grundlegende Eigenschaften in Form von Umgebungsvariablen gesetzt werden. Nutzten Sie hierzu die bereitgestellte Konfigurationstemplate bwlp-remote/.env.tmpl und erstellen Sie eine eigene Konfigurationsdatei .env. Nachfolgend werden die unterschiedlichen Konfigurationsschritte aufgelistet.

Apache

Für Übetragung zwischen Anwender und Guacamole-Client wird ein Apache Webserver eingesetzt. Damit die Übertragung gesicht ist müssen Sie das Serverzertifikat und Schlüssel bereitstellen, legen Sie diese in bwlp-remote/apache/cert ab. Nachfolgend müssen folgende Variablen in bwlp-remote/.env gesetzt werden.

  • BWLP_REMOTE_HOSTNAME: Setzten Sie hier den FQDN des Servers.
  • BWLP_REMOTE_SERVERADMIN: (Optional) setzten Sie einen Serveradmin.
  • BWLP_REMOTE_SSL_CERT: Dateinamen des Serverzertifikats
  • BWLP_REMOTE_SSL_KEY: Dateinamen des Serverschlüssels

LetsEncrypt

Sollten für die Bereitstellung von Serverzertifikaten auf [[https://certbot.eff.org/|CertBot]] von Let's Encrypt zurückgegriffen werden, müssen diese entsprechend in den Container durchgereicht und referenziert werden. Passen Sie hierzu wie folgend die Variablen entsprechend an

BWLP_REMOTE_SSL_DIR_HOST="/etc/letsencrypt"
BWLP_REMOTE_SSL_DIR_CONTAINER="/etc/letsenrypt"
 
BWLP_REMOTE_SSL_DIR=${BWLP_REMOTE_SSL_DIR_CONTAINER}/live/${BWLP_REMOTE_HOSTNAME}
BWLP_REMOTE_SSL_CERT=fullchain.pem
BWLP_REMOTE_SSL_KEY=privkey.pem

Guacamole

Als nächstes werden Einstellungen betreffs des Guacamole Clients vorgenommen.

  • BWLP_LOCAL_BRANDING: Als URL angegebenes Logo des Instituts.
  • BWLP_SAT_HOST: IP-Adresse oder FQDN des bwLehrpool Satelliten
  • BWLP_GUAC_LDAP_CERT: Dateinamen des LDAP-Server-Zertifikats, Datei muss unter bwlp-remot/guac-sat/cert abgelegt sein.
LDAP

Für eine Authentisierung mittels LDAP sind als letztes noch die entsprechenden Umgebungsvariablen zu setzten. Wie bereits in der Anleitung zu Docker beschrieben, müssen diese entsprechend den Vorgaben Ihrer Campus-IT gesetzt werden. Ist zudem ein Serverzertifikat für die Kommunikation zum LDAP-Server erforderlich, muss dieses in bwlp-remot/guac-sat/cert abgelegt sein und der Dateiname durch die Variable BWLP_GUAC_LDAP_CERT festgelegt werden.

Service Verwaltung

Sind alle Arbeiten an der Konfigurationsdateie abgeschlossen, gilt es die Services, als komplett Einheit zu verwalten. Nachfolgend sind die wenigen Aufrufe aufgelistet, um die Servises zu starten, zu stoppen und die Logs zu betrachten.

Hinweis Alle Aufrufe finden dabei im Ordner bwlp-remote statt.

  • Starten der Services
    docker-compose up -d --build
  • Stoppen der Services bzw Löschen aller Container und Artefakte.
    docker-compose down
  • Anzeigen der Logs

    docker-compose logs --follow
     

Problembehebung

Wenn nach dem Login an der Guacamole-Anmeldemaske keine Raumgruppen oder Clients angezeigt werden, kann evtl. die Liste vom Satellitenserver nicht abgerufen werden. Prüfen Sie die guacamole.properties auf den Wert der slx-client-list-url. Diese muss dem Schema https://<SAT-IP>/slx-admin/api.php?do=remoteaccess entsprechen. Achten Sie auch auf HTTP bzw. HTTPS. Im Webinterface des Satellitenservers, können Sie die HTTPS-Verschlüsselung im Menüpunkt "Web-Schnittstelle" aktivieren.

Sie können zur Kontrolle die Metadaten des Satelliten direkt auf dem Guacamole-Server manuell abrufen. Führen Sie auf dem Guacamole-Proxy folgen Befehl aus: curl -k -L -v http://<SAT-IP>/slx-admin/api.php?do=remoteaccess

Dabei sollte eine json-Struktur herauskommen, die die Liste von Clients und Gruppen enthält. Wenn dies fehlschlägt sollte allerdings auch im Log (/var/log/tomcat9/catalina.out) entsprechendes auftauchen.

Guacamole-Logs auswerten

  • Für Server
    journalctl -u guacd
  • Für Client-Plugin
    tail -n 200 -f /var/log/tomcat9/catalina.<date>.log
Drucken/exportieren