# Apache Guacamole Um mittels [[allgemein:remotenutzung_von_bwlehrpool|Remotezugriff auf bwLehrpool-Clients]] zugreifen zu können, benötigen Sie einen \[\[https://guacamole.apache.org/|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 ``` ---- 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 \[\[https://guacamole.apache.org/doc/gug/|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 /bin/bash curl -k -L -v https:///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 | # Aufsetzen eines Apache Guacamole Proxy Um remote auf bwLehrpool-Clients zugreifen zu können ([Remotenutzung von bwLehrpool](https://www.bwlehrpool.de/doku.php/allgemein/remotenutzung_von_bwlehrpool)), benötigen Sie einen [Apache Guacamole](https://guacamole.apache.org)-Server. In dieser Anleitung wird **Ubuntu 20.04.2 LTS** als Basis-OS genutzt und **Guacamole in der Version 1.5.3** 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 ``` (Anmerkung: Das derzeit aktuelle Debian 11 „Bullseye“ beinhaltet kein libjpeg-turbo8-dev, jedoch libjpeg62-turbo-dev.) - Guacamole 1.5.3 herunterladen ````bash VER=1.5.3 mkdir -p /usr/src && cd /usr/src wget https://dlcdn.apache.org/guacamole/$VER/binary/guacamole-$VER.war wget https://dlcdn.apache.org/guacamole/$VER/binary/guacamole-auth-ldap-$VER.tar.gz wget https://dlcdn.apache.org/guacamole/$VER/source/guacamole-server-$VER.tar.gz ```` - Sources entpacken und Configure aufrufen ```` tar xzf guacamole-server-$VER.tar.gz cd /usr/src/guacamole-server-$VER ./configure --with-systemd-dir=/etc/systemd/system ```` - Die Ausgabe sollte bei korrekter Installation der Abhängigkeiten in etwa so aussehen: ````bash #------------------------------------------------ guacamole-server version 1.5.3 #------------------------------------------------ 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_HOME anlegen und setzen ````bash # GUACAMOLE_HOME dir anlegen mkdir /etc/guacamole echo 'GUACAMOLE_HOME="/etc/guacamole"' >> /etc/environment ```` - Guacamole Server Service ````bash systemctl --now enable guacd ```` ### Guacamole-Client installieren und starten ````bash cp /usr/src/guacamole-$VER.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 ```` ### GUACD konfigurieren Unter Umständen lauscht guacd fälschlicherweise ausschließlich auf IPv6, während Tomcat sich mit IPv4 zu verbinden versucht. Sie können das mittels 'ss -plunt' bzw 'netstat -plunt' prüfen. ```` Ergänzen Sie '/etc/guacamole/guacamole.properties' mit folgender Zeile: guacd-hostname: 127.0.0.1 Erstellen Sie die Datei /etc/guacamole/guacd.conf mit folgendem Inhalt: [server] bind_host = 127.0.0.1 bind_port = 4822 Nehmen Sie explizit '127.0.0.1' und nicht 'localhost'. # Service neustarten systemctl restart tomcat9.service systemctl restart guacd.service ```` ### LDAP-Plugin installieren Authentifizieren via LDAP ermöglichen. ````bash cd /usr/src/ tar xvzf guacamole-auth-ldap-$VER.tar.gz # extensions Verzeichnis anlegen mkdir /etc/guacamole/extensions cp /usr/src/guacamole-auth-ldap-$VER/guacamole-auth-ldap-$VER.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! ````bash vi /etc/guacamole/guacamole.properties ```` ````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](https://guacamole.apache.org/doc/gug/ldap-auth.html) #### LDAP Cert installieren Falls Ihr LDAP Server verschlüsselt kommuniziert, müssen Sie evtl. ein entsprechendes Zertifikat importieren. ````bash # 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.** ````bash # 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.5.0-SNAPSHOT.jar # Um das Plugin mit dem bwLehrpool-Satellitenserver zu verbinden, folgende Zeile in '/etc/guacamole/guacamole.properties' einfügen (** anpassen**): slx-client-list-url: https:///slx-admin/api.php?do=remoteaccess ```` Bitte fahren Sie zum Abschluß der Installation mit dem Punkt [„Apache Reverse Proxy einrichten“](#apache_reverse_proxy_einrichten) fort. ++++