allgemein:guacamole_installation

Diese Seite ist nicht editierbar. Sie können den Quelltext sehen, jedoch nicht verändern. Kontaktieren Sie den Administrator, wenn Sie glauben, dass hier ein Fehler vorliegt.
<!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.

# Docker Setup

Die folgende Anleitung setzt ein gewisses Basiswissen zu Docker voraus, auf das hier nicht näher eingegangen werden kann. Bitte orientieren Sie sich an der offiziellen Dokumentation unter \[\[https://docs.docker.com/\]\].

Es ist zudem ratsam Docker nicht aus den Paketquellen Ihrer Linux-Distribution zu installieren. Folgen Sie stattdessen auch hier der offiziellen Anleitung:

\[\[https://docs.docker.com/engine/install/\]\]




# Guacamole 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 __in dem Verzeichnis aus__, in dem auch die Datei '**docker-compose.yml**' liegt:

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

++++
Zuletzt angesehen: • remotenutzung_von_bwlehrpool • was_ist_bwlehrpool • anwendertreffen2018 • teilnahme_an_bwlehrpool • raeume_orte
Suche

Navigation

Drucken/exportieren

Werkzeuge
