Dies ist eine alte Version des Dokuments!

Inhaltsverzeichnis

Apache Guacamole
Container Setup

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

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

(Anmerkung: Das derzeit aktuelle Debian 11 „Bullseye“ beinhaltet kein libjpeg-turbo8-dev, jedoch libjpeg62-turbo-dev.)

Guacamole 1.3.0 herunterladen

  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:

  #------------------------------------------------
  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

Bitte fahren Sie zum Abschluß der Installation mit dem Punkt „Apache Reverse Proxy einrichten“ fort.

Zuletzt angesehen: • guacamole_installation