Unterschiede

Hier werden die Unterschiede zwischen zwei Versionen angezeigt.

Link zu dieser Vergleichsansicht

Beide Seiten der vorigen RevisionVorhergehende Überarbeitung
allgemein:guacamole_installation_deprecated [2023/07/17 16:26 CEST] – gelöscht - Externe Bearbeitung (Unbekanntes Datum) 127.0.0.1allgemein:guacamole_installation_deprecated [2023/07/17 16:26 CEST] (aktuell) – ↷ Seitename wurde von allgemein:guacamole_installation auf allgemein:guacamole_installation_deprecated geändert sritter
Zeile 1: Zeile 1:
 +<WRAP justify 1200px>
 +
 +# 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.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
 +  ````bash
 +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.3.0 herunterladen  
 +  ````bash
 +  mkdir /usr/src && cd /usr/src
 +  wget https://dlcdn.apache.org/guacamole/1.3.0/binary/guacamole-1.3.0.war
 +  wget https://dlcdn.apache.org/guacamole/1.3.0/binary/guacamole-auth-ldap-1.3.0.tar.gz
 +  wget https://dlcdn.apache.org/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:
 +  ````bash
 +  #------------------------------------------------
 +  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  
 +  ````bash
 +  systemctl enable guacd
 +  systemctl start guacd
 +  ````
 +
 +- GUACAMOLE_HOME anlegen und setzen
 +
 +  ````bash
 +  # GUACAMOLE_HOME dir anlegen
 +  mkdir /etc/guacamole
 +  echo 'GUACAMOLE_HOME="/etc/guacamole"' >> /etc/environment
 +  ````
 +
 +### Guacamole-Client installieren und starten
 +  ````bash
 +  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.
 +
 +````bash
 +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! 
 +
 +````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.
 +
 +<span style="color:red">
 +**Achten Sie darauf, dass immer nur ein bwlp-Plugin verwendet wird! Löschen Sie ältere Pluginversionen, da es ansonsten zu Fehlverhalten kommen kann.**
 +</span>
 +
 +````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.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
 +````
 +
 +Bitte fahren Sie zum Abschluß der Installation mit dem Punkt [„Apache Reverse Proxy einrichten“](#apache_reverse_proxy_einrichten) fort.
 +
 +
 +## Alternative: Container Setup
 +
 +Guacamole-Server und -Client sind auch als [Container Images](https://guacamole.apache.org/doc/gug/guacamole-docker.html) 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).
 +   ````bash
 +   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. 
 +   ````bash
 +   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. 
 +   ````bash
 +   docker cp CERT.crt guacamole:/usr/local/share/ca-certificates/
 +   docker exec -it guacamole update-ca-certificates
 +   ````
 +   
 +
 +## 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](https://www.bwlehrpool.de/wiki/lib/exe/fetch.php/client/bwl_remote/bwlp-remote.tgz) zusammengefasst.
 +
 +### Voraussetzung
 + 
 +- [Docker](https://docs.docker.com/engine/install/)
 +- [Docket-Compose](https://docs.docker.com/compose/install/)
 +
 +### Vorbereitung
 +
 +Laden Sie das Archive [bwlp-remote.tgz](https://www.bwlehrpool.de/wiki/lib/exe/fetch.php/client/bwl_remote/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 
 +
 +```shell
 +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
 +  ```shell
 +  docker-compose up -d --build
 +  ```
 +- Stoppen der Services bzw Löschen aller Container und Artefakte. 
 +  ```shell
 +  docker-compose down
 +  ```
 +- Anzeigen der Logs
 +  ```shell
 +  docker-compose logs --follow
 +  
 +
 +## Apache Reverse Proxy einrichten
 +
 +Reverse Proxy-Konfiguration für Apache anlegen und entsprechende Module aktivieren. 
 +
 +````bash
 +# Apache Module aktivieren
 +a2enmod rewrite
 +a2enmod proxy_http
 +a2enmod ssl
 +a2enmod proxy_wstunnel
 +````
 +
 +Nachfolgender Inhalt in .conf datei einfügen
 +
 +````bash
 +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:
 +
 +````bash
 +<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>
 +````
 +
 +````bash
 +
 +# 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
 +````
 +
 +## 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
 +  ````
 +
 +</WRAP>
  

Zuletzt angesehen:

Drucken/exportieren