Unterschiede

Hier werden die Unterschiede zwischen zwei Versionen angezeigt.

Link zu dieser Vergleichsansicht

Beide Seiten der vorigen RevisionVorhergehende Überarbeitung
Nächste Überarbeitung
Vorhergehende Überarbeitung
allgemein:guacamole_installation [2023/07/17 16:26 CEST] – gelöscht - Externe Bearbeitung (Unbekanntes Datum) 127.0.0.1allgemein:guacamole_installation [2023/11/03 13:42 CET] (aktuell) sritter
Zeile 1: Zeile 1:
 +<!DOCTYPE markdown>
 +<WRAP 900px>
 +
 +# 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 <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 \[\[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 <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. 
 +
 +</WRAP>
 +
 +
 +## 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 (**<SAT-IP> anpassen**):
 +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.
 +
 +++++
 +
 +
 +
 +
 +
 +
  
Drucken/exportieren