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

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.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 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
````

Zuletzt angesehen: • guacamole_installation_deprecated

Drucken/exportieren