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