Apache Guacamole auf dem Synology NAS installieren: RDP, SSH und VNC im Browser

Apache Guacamole ist ein clientloses Remote-Desktop-Gateway der Apache Software Foundation: Im Browser erhalten Sie einen Windows-Desktop per RDP, eine Linux-Shell per SSH oder einen Desktop per VNC, ohne Plugin oder Client-Software. Für KMU ersetzt das offene RDP-Ports (3389) und direkt erreichbare SSH-Zugänge: Ein HTTPS-Endpunkt mit TOTP-Zwei-Faktor-Authentifizierung übernimmt die Zugangskontrolle, alle Verbindungen laufen intern über den guacd-Daemon.

Voraussetzungen

1. Synology NAS mit DSM 7.2 oder neuer und aktiviertem Container Manager (Package Center)
2. CPU-Architektur x86_64 (z. B. DS923+, DS720+, DS1522+) – ARM64 (z. B. DS223) ist mit dem gepinnten Tag :1.6.0 ebenfalls möglich, nicht mit :latest
3. Mindestens 2 GB freier RAM für den Drei-Container-Stack
4. Mindestens 5 GB freier Speicherplatz auf /volume1 für Images und Datenbankdaten
5. Feste interne IP-Adresse für das NAS (DHCP-Reservierung im Router empfohlen)
6. SSH-Zugang zum NAS aktiviert (DSM > Systemsteuerung > Terminal & SNMP): Das Datenbankschema in Schritt 2 lässt sich nur per docker run auf der Kommandozeile erzeugen
7. Zwei sichere, voneinander verschiedene Passwörter für MYSQL_ROOT_PASSWORD und MYSQL_PASSWORD vorab festlegen
8. Optional: Domainname oder DynDNS-Eintrag für HTTPS mit Let's Encrypt über den Synology Reverse Proxy

Schritt 1: Verzeichnisstruktur anlegen

Legen Sie in der File Station folgende Ordnerstruktur unter /volume1/docker/guacamole an:

/volume1/docker/guacamole/
├── init/        ← SQL-Initialisierungsskript (wird von MariaDB einmalig ausgeführt)
├── dbdata/      ← MariaDB-Datenbankdateien, persistent
├── drive/       ← Gemeinsamer Dateibereich für Client-↔-Remote-Übertragungen
└── record/      ← Optionale Session-Recordings

Alternativ per SSH (SSH brauchen Sie für Schritt 2 ohnehin):

mkdir -p /volume1/docker/guacamole/{init,dbdata,drive,record}

Verifizieren: In der File Station oder per ls /volume1/docker/guacamole/ müssen alle vier Unterordner sichtbar sein:

dbdata  drive  init  record

Schritt 2: Datenbankschema erzeugen (initdb.sh)

Das Datenbankschema wird nicht automatisch angelegt. Sie erzeugen es vorab im init-Ordner, damit MariaDB es beim ersten Container-Start einspielt.

Führen Sie per SSH auf dem NAS folgenden Befehl aus (meist mit sudo):

sudo docker run --rm guacamole/guacamole:1.6.0 /opt/guacamole/bin/initdb.sh --mysql \
  | sudo tee /volume1/docker/guacamole/init/initdb.sql > /dev/null

Ein temporärer Container gibt das Schema-SQL aus und wird danach entfernt (--rm).

Verifizieren: Die Datei muss existieren und darf nicht leer sein:

wc -l /volume1/docker/guacamole/init/initdb.sql

Erwartet: mindestens 200 Zeilen. 0 bedeutet, dass der Befehl fehlgeschlagen ist; wiederholen Sie ihn.

Schritt 3: compose.yaml erstellen

Legen Sie /volume1/docker/guacamole/compose.yaml an und ersetzen Sie die Platzhalter-Passwörter durch Ihre Werte, beide unterschiedlich:

services:

  guacd:
    image: guacamole/guacd:1.6.0
    container_name: guacd
    restart: unless-stopped
    volumes:
      - /volume1/docker/guacamole/drive:/drive:rw
      - /volume1/docker/guacamole/record:/record:rw

  mariadb:
    image: mariadb:11
    container_name: guacamole-db
    restart: unless-stopped
    environment:
      MYSQL_ROOT_PASSWORD: "AendernSie_RootPW_123!"
      MYSQL_DATABASE: guacamole_db
      MYSQL_USER: guacamole_user
      MYSQL_PASSWORD: "AendernSie_UserPW_456!"
    volumes:
      - /volume1/docker/guacamole/dbdata:/var/lib/mysql
      - /volume1/docker/guacamole/init:/docker-entrypoint-initdb.d:ro

  guacamole:
    image: guacamole/guacamole:1.6.0
    container_name: guacamole
    restart: unless-stopped
    depends_on:
      - guacd
      - mariadb
    environment:
      GUACD_HOSTNAME: guacd
      MYSQL_HOSTNAME: mariadb
      MYSQL_DATABASE: guacamole_db
      MYSQL_USERNAME: guacamole_user
      MYSQL_PASSWORD: "AendernSie_UserPW_456!"
      TOTP_ENABLED: "true"
      TOTP_ISSUER: "Mein Unternehmen"
    ports:
      - "8080:8080"
    volumes:
      - /volume1/docker/guacamole/drive:/drive:rw
      - /volume1/docker/guacamole/record:/record:rw

Wichtige Hinweise zur Konfiguration:

1. MYSQL_USERNAME: Im guacamole-Container seit 1.6.0 der richtige Name; MYSQL_USER ist dort veraltet und erzeugt eine Log-Warnung. Im mariadb-Container bleibt MYSQL_USER richtig.
2. Port 8080: Ist er belegt (z. B. durch Portainer), Host-Port auf 8081:8080 oder 8082:8080 ändern.
3. guacd-Port 4822 wird bewusst nicht exponiert: ohne eigene Authentifizierung, nur für interne Container-Kommunikation. Niemals in der Router-Firewall öffnen.
4. Passwörter in Anführungszeichen: Passwörter mit Sonderzeichen in Anführungszeichen setzen; $ in Compose als $$ schreiben.

Verifizieren: Die Datei muss syntaktisch korrekt sein:

sudo docker compose -f /volume1/docker/guacamole/compose.yaml config

Erwartet: die vollständige Compose-Konfiguration ohne Fehler. Fehler deuten meist auf Einrückung hin; YAML erlaubt nur Leerzeichen, keine Tabs.

Schritt 4: Stack im Container Manager starten

Wählen Sie im Container Manager links „Projekt“ > „Erstellen“, Projektname guacamole, Pfad /volume1/docker/guacamole, und übernehmen Sie die vorhandene compose.yaml.

Alternativ per SSH:

cd /volume1/docker/guacamole && sudo docker compose up -d

Docker lädt drei Images mit zusammen rund 900 MB herunter.

Wichtig: depends_on sorgt nur für den Start der Container, nicht dafür, dass MariaDB schon Verbindungen annimmt. Warten Sie 30 bis 60 Sekunden.

Verifizieren: Alle drei Container müssen den Status „Wird ausgeführt“ (grün) zeigen:

sudo docker ps --filter "name=guacd" --filter "name=guacamole" --format "table {{.Names}}\t{{.Status}}"

Erwartete Ausgabe:

NAMES           STATUS
guacamole       Up 45 seconds
guacamole-db    Up 45 seconds
guacd           Up 45 seconds

Bei „Restarting“ oder „Exited“ prüfen Sie docker logs guacamole-db bzw. docker logs guacamole.

Schritt 5: Datenbankschema verifizieren

Prüfen Sie vor dem ersten Login, ob MariaDB das Schema importiert hat; das vermeidet HTTP-500-Fehler:

sudo docker exec guacamole-db mariadb -u guacamole_user -p'AendernSie_UserPW_456!' guacamole_db \
  -e "SHOW TABLES LIKE 'guacamole_%';" 2>/dev/null

Ersetzen Sie das Passwort durch Ihr eigenes. Erwartete Ausgabe, mindestens diese Tabellen:

+----------------------------------+
| Tables_in_guacamole_db           |
+----------------------------------+
| guacamole_connection             |
| guacamole_connection_group       |
| guacamole_entity                 |
| guacamole_system_permission      |
| guacamole_user                   |
+----------------------------------+

Verifizieren: Die Ausgabe listet Tabellen mit dem Präfix guacamole_ auf. Bleibt die Liste leer, wurde das Schema nicht eingespielt: Container stoppen, dbdata leeren (bei einer Neuinstallation ohne Datenverlust), Schritt 2 wiederholen und neu starten. MariaDB führt Skripte aus init nur bei leerem Datenordner aus.

Schritt 6: Erster Login und Passwort ändern

Öffnen Sie im Browser:

http://[NAS-IP]:8080/guacamole/

Melden Sie sich mit den Standard-Zugangsdaten an:

Sofortmaßnahme nach dem ersten Login: Oben rechts Benutzername > „Einstellungen“ > „Profil“, Passwort ändern. Besser: eigenen Administrator anlegen und guacadmin löschen, denn die Standard-Zugangsdaten sind öffentlich bekannt.

Mit TOTP_ENABLED=true fordert Guacamole beim Login zum Scannen eines QR-Codes mit einer Authenticator-App auf; danach verlangt jeder Login einen zeitbasierten Einmalcode.

Verifizieren: Sie sehen das Guacamole-Dashboard ohne Fehlermeldungen, und unter Einstellungen > Verbindungen ist die Oberfläche leer (noch keine Verbindungen angelegt). Fehler 500 beim Login weisen auf ein fehlerhaftes Datenbankschema hin – zurück zu Schritt 5.

Schritt 7: Erste Verbindung anlegen (RDP-Beispiel)

Wählen Sie im Dashboard oben rechts Benutzername > Einstellungen > Verbindungen > „Neue Verbindung“:

Speichern Sie die Verbindung. Auf dem Windows-PC muss RDP aktiviert sein (Systemsteuerung > System > Remoteeinstellungen); Port 3389 muss nicht im Router offen sein, guacd verbindet intern.

Für eine SSH-Verbindung zum NAS selbst: Protokoll SSH, Hostname = NAS-IP, Port 22. SSH muss in DSM unter Systemsteuerung > Terminal & SNMP aktiviert sein. Härtungsmaßnahmen für SSH-Server beschreibt die Anleitung SSH-Hardening Deep-Dive: sshd_config, Match-Blöcke und ssh-audit.

Verifizieren: Klicken Sie im Dashboard auf die neue Verbindung. Der Browser öffnet ein HTML5-Fenster und zeigt den Windows-Desktop (oder die SSH-Shell). Einige Sekunden Schwarz beim Verbindungsaufbau sind normal. Bleibt der Bildschirm schwarz oder erscheint eine Fehlermeldung, prüfen Sie die Erreichbarkeit des Zielsystems im lokalen Netz (ping 192.168.1.50 vom NAS) und ob RDP auf dem Zielsystem aktiviert ist.

Schritt 8: HTTPS mit Synology Reverse Proxy (empfohlen)

Produktiv machen Sie Guacamole nicht per HTTP erreichbar, da Passwörter und TOTP-Codes sonst im Klartext liefen. Am einfachsten ist der Synology Reverse Proxy mit Let's-Encrypt-Zertifikat.

Öffnen Sie DSM > Systemsteuerung > Anmeldeportal > Erweitert > Reverse Proxy und legen Sie eine neue Regel an:

Aktivieren Sie unter „Benutzerdefinierter Header“ die WebSocket-Unterstützung („Erstellen > WebSocket“). Ergänzen Sie im guacamole-Container unter environment: REMOTE_IP_VALVE_ENABLED=true, damit Tomcat die echten Client-IPs protokolliert.

Das Let's-Encrypt-Zertifikat vergeben Sie unter DSM > Systemsteuerung > Sicherheit > Zertifikat. Der Router leitet nur Port 443 an das NAS weiter, nicht 8080, 4822 oder 3389.

Verifizieren: https://guac.ihre-domain.de/guacamole/ zeigt die Anmeldemaske ohne Zertifikatswarnung, und eine Verbindung aus Schritt 7 öffnet sich auch über diese Adresse. Lädt die Seite nicht, prüfen Sie Reverse-Proxy-Regel, WebSocket-Header und die Portweiterleitung 443.

Eckdaten-Übersicht

Troubleshooting / Typische Fehler

1. „Table guacamole_user does not exist“ / HTTP 500 beim Login: initdb.sql fehlte oder war leer. Container stoppen, /volume1/docker/guacamole/dbdata leeren (Achtung: löscht alle Daten), Schritt 2 wiederholen, neu starten.
2. guacamole-Container startet, verbindet sich aber nicht mit der DB: MariaDB war noch nicht bereit. Nach 60 Sekunden sudo docker restart guacamole; nach dem ersten erfolgreichen Start tritt das nicht mehr auf.
3. „port already in use“ beim Start: Host-Port 8080 belegt; in der compose.yaml auf "8081:8080" oder "8082:8080" ändern.
4. TOTP-Feld erscheint, Code wird nie akzeptiert: TOTP_ENABLED=true ohne gültige MYSQL_*-Variablen; TOTP braucht ein Datenbank-Backend. Umgebungsvariablen und NAS-Uhrzeit (NTP) prüfen, da TOTP eine genaue Uhrzeit voraussetzt.
5. Reverse Proxy: Seite lädt, aber Verbindungen brechen ab: WebSocket-Header fehlen (Schritt 8).
6. Verbindung zu Windows-PC schlägt fehl (schwarzer Bildschirm oder Fehler): RDP am Ziel-PC aktivieren („Remoteverbindungen zulassen“). NLA kann bei bestimmten Windows-Versionen Probleme machen; dann Sicherheitsmodus „Any“.
7. Nach Update (z. B. 1.5.x auf 1.6.0) startet guacamole mit DB-Fehlern: Das Schema hat sich geändert. Datenbank sichern und upgrade-pre-1.6.0.sql aus /opt/guacamole/extensions/guacamole-auth-jdbc/mysql/schema/upgrade/ des neuen Images einspielen. dbdata nicht leeren, sonst sind alle Benutzer und Verbindungen verloren.
8. Browser zeigt alte URL nach WEBAPP_CONTEXT-Änderung: Cache oder gespeicherte Weiterleitung; privates Fenster nutzen oder Cache leeren.

Häufige Fragen

Kann ich Guacamole ohne eigene Domain und ohne HTTPS betreiben?

Für Tests im LAN funktioniert HTTP auf Port 8080, produktiv laufen Passwörter und TOTP-Codes dann im Klartext. Intern mindestens ein selbst signiertes Zertifikat, von außen den Reverse Proxy mit Let's Encrypt (Schritt 8).

Muss Port 3389 (RDP) im Router offen sein?

Nein, das ist der zentrale Sicherheitsvorteil von Guacamole. Der guacd-Daemon stellt die RDP-Verbindung intern im Netzwerk her; der Windows-PC muss nur aus dem lokalen Netz des NAS erreichbar sein. Im Router muss lediglich der HTTPS-Port (443) auf das NAS weitergeleitet werden. Wer Windows-Terminalserver betreibt, findet Hintergründe in der Anleitung Remote Desktop Services einrichten und lizenzieren.

Wie richte ich SSH-Zugang zum NAS selbst über Guacamole ein?

Neue Verbindung in Guacamole: Protokoll SSH, Hostname = interne LAN-IP des NAS (nicht localhost, das wäre der Container selbst), Port 22. SSH muss in DSM unter Systemsteuerung > Terminal & SNMP aktiviert sein. Leiten Sie Port 22 nicht im Router weiter. Die Härtungsmaßnahmen für sshd beschreibt der Artikel SSH-Hardening Deep-Dive: sshd_config, Match-Blöcke und ssh-audit im Detail.

Wie viele gleichzeitige Verbindungen verträgt Guacamole auf einem Synology NAS?

Kein festes Software-Limit; die Grenze setzen CPU, RAM und Bandbreite des NAS. Messen Sie mit sudo docker stats den RAM von guacd pro Sitzung. Hohe Auflösungen und VNC mit viel Bildänderung belasten die CPU stärker.

Wie aktiviere ich Session-Recordings?

Setzen Sie im guacamole-Container RECORDING_SEARCH_PATH=/record; das Volume /record ist in guacd und guacamole bereits eingebunden. Tragen Sie in jeder Verbindung unter „Bildschirmaufzeichnung“ den Pfad ${HISTORY_PATH}/${HISTORY_UUID} ein und aktivieren Sie „Pfad automatisch erstellen“. Die Aufzeichnungen lassen sich dann im Verlauf abspielen.

Gibt es ein All-in-One-Image, das alle drei Dienste zusammenfasst?

Offiziell nicht. Community-Images stammen nicht vom Projekt und erhalten Sicherheitsupdates womöglich verzögert. Produktiv empfiehlt sich der offizielle Drei-Container-Stack aus dem guacamole/-Namespace auf Docker Hub.

Guacamole oder RustDesk – was passt besser für KMU-Fernwartung?

Guacamole ist ein Gateway: Alle Verbindungen laufen zentral durch das NAS, werden protokolliert, und Benutzer brauchen keinen Client. RustDesk ist ein Fernwartungswerkzeug mit Client auf jedem Gerät, ähnlich TeamViewer. Die Anleitung RustDesk-Server auf dem Synology NAS installieren zeigt den RustDesk-Ansatz im direkten Vergleich.

Fazit

Guacamole auf dem Synology NAS liefert ein zentrales, protokolliertes Zugangssystem mit TOTP ohne offene RDP- und SSH-Ports. Bei korrekt initialisiertem Schema ist der Stack wartungsarm.

Updates planen: Tag in der compose.yaml anheben, vorher die Datenbank sichern, bei neuen Versionen das Upgrade-Skript einspielen.

Weiterführende Anleitungen und Quellen

1. Remote Desktop Services einrichten und lizenzieren: Terminalserver für KMU
2. SSH-Hardening Deep-Dive: sshd_config, Match-Blöcke und ssh-audit für KMU-Server
3. RustDesk-Server auf dem Synology NAS installieren: Fernwartung als TeamViewer-Alternative

Offizielle Quellen: Guacamole 1.6.0: Docker-Installation, Guacamole 1.6.0: MariaDB/MySQL-Anbindung, Guacamole 1.6.0: TOTP, Docker Hub: guacamole/guacamole.