Dies ist eine alte Version des Dokuments!


Apache Guacamole

Um mittels Remotezugriff auf bwLehrpool-Clients zugreifen zu können, benötigen Sie einen Apache Guacamole-Server.

Guacamole ist eine Art VNC-Proxy, den Sie entweder lokal kompilieren und installieren oder mittels Docker in Containern betreiben können. Mit einem zusätzlichen bwLehrpool-Plugin können Sie dann über eine einfache Weboberfläche Ihre bwLehrpool-Clients per Webbrowser zugänglich machen.

Da Inbetriebnahme und Updates von Guacamole mit Docker deutlich einfacher und schneller als eine lokale Installation ist, beschränken wir uns hier auf die Containerlösung.

Container Setup

Sie finden ein vorgefertigtes Docker-Compose File nebst README und Beispielen zur Konfiguration in unserem Git-Repository (./deployment/docker). Die Konfiguration wird über die Datei '.env' gesteuert.

Beachten Sie, dass unter Linux Dateien die mit einem '.' (Punkt) beginnen evtl. nicht sichtbar sind. Nutzen Sie daher ggf. das Kommando 'ls -la', um auch versteckte Dateien anzuzeigen.

Klonen Sie das Repository und kopieren als ersten Schritt die Konfigurationsdatei '.env.example' nach '.env'.

git clone https://git.openslx.org/bwlp/bwlp-guacamole-ext.git
cd bwlp-guacamole-ext/deployment/docker
cp .env.example .env

Editieren Sie dort mindestens IP/Hostname der Variablen SLX_CLIENT_LIST_URL, damit diese auf Ihren Satellitenserver verweist.

Für den LDAP-Login müssen Sie noch die notwendingen LDAP_*-Variablen anpassen. Es stehen weitere Konfigurationsoptionen zur Verfügung, falls nötig https://guacamole.apache.org/doc/gug/guacamole-docker.html#ldap-authentication .

Optional: Falls Ihr LDAP-Server ein selbstsigniertes SSL-Zertifikat verwendet, ist es unter Umständen notwendig, dass Sie dieses in das Docker-Image importieren. Editieren Sie dazu die Datei 'Dockerfile' und passen die auskommentierten Zeilen an. Legen Sie dann das notwendige Zertifikat z.B. unter './data' ab. Falls Sie kein spezielles Zertifikat benötigen, können Sie diesen Teil überspringen.

Kopieren Sie als nächstes das für Ihre Guacamole Version passende 'bwlp-guac-plugin' nach './data/extensions'. Die aktuell zur Verfügung stehenden Plugins finden Sie unter https://files.bwlp.ks.uni-freiburg.de/satellit/guacamole/ .

Achten Sie darauf, dass immer nur ein bwlp-Plugin in diesem Ordner liegt!

Um die Container zu starten führen Sie abschließend einfach folgenden Befehl aus:

docker compose up --build -d

Um zu prüfen, ob die Container laufen bzw. um Logs zu inspizieren:

docker ps
docker logs -f <container-name>

Wenn Sie auf eine andere Guacamole-Version wechseln möchten, editieren Sie einfach wieder die .env-Datei und starten die Container mit folgendem Kommando neu:

docker compose up --build --force-recreate -d

Reverse Proxy einrichten

Im oben genannten Repository ist auch eine entsprechende Beispielkonfiguration für den Apache Webserver enthalten (./deployment/apache2/). Alternativ ist auch nginx als Webserver möglich. Weitere Infos dazu finden Sie in der Apache Guacamole Dokumentation.

# Apache installieren
apt install apache2 

# Module aktivieren
a2enmod rewrite
a2enmod proxy_http
a2enmod ssl
a2enmod proxy_wstunnel

# Konfiguration kopieren und aktivieren
cp bwlp-guacamole-ext/deployment/bwlehrpool-remote.conf /etc/apache2/sites-available/bwlehrpool-remote.conf
a2ensite bwlehrpool-remote.conf

Passen Sie IP (10.9.8.7) und FQDN (bwlehrpool-remote.hs-xyz.de) auf Ihre Umgebung an.

# 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

# Webserver neustarten
systemctl restart apache2

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, ob der Wert der Variablen 'SLX_CLIENT_LIST_URL' korrekt auf Ihren Satellitenserver verweist. 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 Satellitenservers direkt innerhalb des Guacamole-Containers abrufen.

docker exec -it <container-name> /bin/bash
curl -k -L -v https://<SAT-IP>/slx-admin/api.php?do=remoteaccess

Dabei sollte eine json-Struktur herauskommen, die die Liste von Clients und Gruppen enthält. Verfügbare Clients müssen im 'state: IDLE' sein und ein 'password' gesetzt haben, damit eine Verbindung möglich ist.

Lokale Installation (old-way)

Der Vollständigkeit halber finden Sie hier noch die alte Anleitung zur lokalen Installation. Diese wird derzeit jedoch nicht mehr gepflegt und wir empfehlen Ihnen die Nutzung der Docker Container.

Anleitung ausklappen

Drucken/exportieren