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

Apache Guacamole ist ein clientloses Remote-Desktop-Gateway des Apache Software Foundation: Du öffnest eine URL im Browser und bekommst sofort einen vollwertigen Windows-Desktop per RDP, eine Linux-Shell per SSH oder einen grafischen Desktop per VNC – ohne Browser-Plugin, ohne installierte Client-Software. Für KMU ist das der ideale Ersatz für offene RDP-Ports (3389) oder direkt exponierte SSH-Zugänge: Ein einziger HTTPS-Endpunkt mit TOTP-Zwei-Faktor-Authentifizierung übernimmt die Zugangskontrolle, alle Verbindungen laufen intern über den guacd-Daemon. Wer sein Synology NAS ohnehin betreibt, hat damit bereits die nötige Plattform – kein separater Server, kein Cloud-Abonnement.

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) – wird für die initdb.sh-Ausführung benötigt
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

Öffne die File Station in DSM und lege 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 (empfohlen, weil du SSH für Schritt 2 ohnehin brauchst):

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)

Dieser Schritt ist der häufigste Fallstrick: Das Guacamole-Datenbankschema wird nicht automatisch beim ersten Start angelegt. Du musst es vorab erzeugen und in den init-Ordner legen, damit MariaDB es beim ersten Container-Start einspielt.

Verbinde dich per SSH mit dem NAS und führe folgenden Befehl aus:

docker run --rm guacamole/guacamole:1.6.0 /opt/guacamole/bin/initdb.sh --mysql \
  > /volume1/docker/guacamole/init/initdb.sql

Der Befehl startet kurz einen temporären Container, lässt ihn das Schema-SQL ausgeben und schreibt das Ergebnis direkt in die Datei. Der Container wird danach automatisch entfernt (--rm).

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

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

Erwartete Ausgabe: Mehrere hundert Zeilen, mindestens 200. Ein Wert von 0 bedeutet, dass etwas schiefgelaufen ist – dann den Befehl wiederholen.

Schritt 3: compose.yaml erstellen

Lege die Datei /volume1/docker/guacamole/compose.yaml mit folgendem Inhalt an. Ersetze die Platzhalter-Passwörter durch deine zuvor festgelegten, sicheren Werte – beide Felder 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_USER: 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. Port 8080: Falls dieser Port auf deinem NAS bereits belegt ist (z. B. durch Portainer oder DSM selbst), ändere den Host-Port auf 8081:8080 oder 8082:8080.
2. guacd-Port 4822 wird bewusst nicht exponiert – er hat keinen eigenen Authentifizierungsmechanismus und ist ausschließlich für die interne Container-Kommunikation gedacht. Niemals in der Router-Firewall öffnen.
3. TOTP_ENABLED=true erfordert zwingend das konfigurierte Datenbank-Backend – ohne MYSQL_*-Variablen funktioniert TOTP nicht.
4. Passwörter in Anführungszeichen: Sonderzeichen wie !, $ oder & in Passwörtern müssen in doppelte Anführungszeichen gesetzt werden, sonst kommt es zu Shell-Interpretation oder Compose-Parsing-Fehlern.

Verifizieren: Die Datei muss syntaktisch korrekt sein:

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

Erwartete Ausgabe: Die vollständige, expandierte Compose-Konfiguration ohne Fehlermeldungen. Rot hervorgehobene Fehler deuten auf YAML-Einrückungsprobleme hin – YAML verwendet ausschließlich Leerzeichen, keine Tabs.

Schritt 4: Stack im Container Manager starten

Öffne den Container Manager in DSM, wähle links „Projekt“ und klicke auf „Erstellen“. Vergib den Projektnamen guacamole, wähle als Pfad /volume1/docker/guacamole und bestätige – Container Manager liest die vorhandene compose.yaml automatisch ein.

Alternativ per SSH:

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

Docker lädt nun drei Images herunter (guacd: ca. 123 MB, guacamole: ca. 395 MB, mariadb: ca. 400 MB). Der erste Start dauert je nach Internetverbindung 3–5 Minuten.

Wichtig: depends_on stellt nur sicher, dass die Container gestartet werden, nicht dass MariaDB den TCP-Port bereits akzeptiert. Warte nach dem Start 30–60 Sekunden, bevor du zum nächsten Schritt übergehst.

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

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

Zeigt ein Container „Restarting“ oder „Exited“, prüfe die Logs mit docker logs guacamole-db bzw. docker logs guacamole.

Schritt 5: Datenbankschema verifizieren

Bevor du dich in der Web-Oberfläche anmeldest, bestätige, dass MariaDB das Schema korrekt importiert hat. Dieser Schritt erspart dir frustrierende 500-Fehler beim ersten Login:

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

Ersetze das Passwort durch dein eigenes. Erwartete Ausgabe – mindestens diese Tabellen müssen erscheinen:

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

Siehst du keine Zeilen oder die Fehlermeldung „Table does not exist“, fehlt das initdb.sql. Lösung: Alle Container stoppen, das Verzeichnis /volume1/docker/guacamole/dbdata leeren, Schritt 2 wiederholen und neu starten.

Verifizieren: Die Ausgabe listet Tabellen mit dem Präfix guacamole_ auf. Bleibt die Liste leer, wurde das Schema aus Schritt 2 nicht eingespielt – initdb.sh erneut erzeugen und den Datenbank-Container mit leerem Datenordner neu aufsetzen.

Schritt 6: Erster Login und Passwort ändern

Öffne im Browser:

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

Die Login-Maske erscheint. Melde dich mit den Standard-Zugangsdaten an:

Sofortmaßnahme nach dem ersten Login: Wähle oben rechts den Benutzernamen > „Einstellungen“ > „Profil“ und ändere das Passwort auf ein starkes, einzigartiges Passwort. Da Guacamole potenziell öffentlich erreichbar ist, ist das ein kritisches Sicherheitsrisiko, wenn es unterbleibt.

Wenn TOTP aktiviert ist (TOTP_ENABLED=true), wirst du beim nächsten Login aufgefordert, einen QR-Code mit Google Authenticator, Authy oder 1Password zu scannen. Danach ist jeder Login mit einem zeitbasierten Einmalcode gesichert.

Verifizieren: Du siehst 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ähle im Dashboard oben rechts Benutzername > Einstellungen > Verbindungen > „Neue Verbindung“:

Speichere die Verbindung. Wichtig: Der Windows-PC muss RDP aktiviert haben (Systemsteuerung > System > Remoteeinstellungen), aber Port 3389 muss nicht im Router geöffnet sein – guacd stellt die Verbindung intern her.

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. Weiterführende Härtungsmaßnahmen für SSH-Server beschreibt die Anleitung SSH-Hardening Deep-Dive: sshd_config, Match-Blöcke und ssh-audit.

Verifizieren: Klicke im Dashboard auf die neue Verbindung. Der Browser öffnet ein HTML5-Fenster und zeigt den Windows-Desktop (oder die SSH-Shell). Eine schwarze Fläche für 3–5 Sekunden ist normal (Verbindungsaufbau). Bleibt der Bildschirm schwarz oder erscheint eine Fehlermeldung, prüfe 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)

Für den Produktivbetrieb solltest du Guacamole nicht direkt über HTTP erreichbar machen – vor allem wenn TOTP-Codes übertragen werden. Der Synology Reverse Proxy mit Let's Encrypt-Zertifikat ist die einfachste Lösung.

Öffne DSM > Anmeldungsportal > Erweitert > Reverse Proxy und lege eine neue Regel an:

Aktiviere unter „Benutzerdefinierter Header“ die WebSocket-Unterstützung (Schaltfläche „Erstellen > WebSocket“). Füge außerdem die Umgebungsvariable REMOTE_IP_VALVE_ENABLED=true dem guacamole-Container hinzu (in der compose.yaml unter environment:), damit Tomcat die echten Client-IPs korrekt protokolliert.

Das Let's Encrypt-Zertifikat vergibst du in DSM > Systemsteuerung > Sicherheit > Zertifikat. Der Router muss Port 443 auf die NAS-IP weiterleiten – und nur dieser Port, nicht 8080, 4822 oder 3389.

Verifizieren: Öffne https://guac.deinedomain.de/guacamole/ im Browser. Das Schloss-Symbol zeigt ein gültiges Let's Encrypt-Zertifikat. Die Guacamole-Anmeldemaske erscheint ohne Sicherheitswarnung. Wenn die Seite nicht lädt, prüfe die Reverse-Proxy-Regel, die WebSocket-Einstellung und ob Port 443 im Router weitergeleitet wird.

Eckdaten-Übersicht

Troubleshooting / Typische Fehler

1. „Table guacamole_user does not exist“ / HTTP 500 beim Login: Das initdb.sql fehlt oder war beim ersten Start leer. Container stoppen, /volume1/docker/guacamole/dbdata leeren (achtung: löscht alle Daten!), Schritt 2 wiederholen, dann neu starten.
2. guacamole-Container startet, verbindet sich aber nicht mit der DB: MariaDB war beim guacamole-Start noch nicht bereit. Lösung: docker restart guacamole nach 60 Sekunden. Das ist kein dauerhaftes Problem – nach dem ersten erfolgreichen Start läuft alles stabil.
3. „port already in use“ beim Start: Host-Port 8080 ist belegt (z. B. durch Portainer). Ändere in der compose.yaml den Host-Port auf "8081:8080" oder "8082:8080".
4. TOTP-Feld erscheint, Code wird nie akzeptiert: TOTP_ENABLED=true ohne gültige MYSQL_*-Variablen gesetzt. TOTP benötigt zwingend ein Datenbank-Backend – prüfe die Umgebungsvariablen im Container Manager.
5. Reverse Proxy: Seite lädt, aber WebSocket-Verbindung bricht ab: WebSocket-Header fehlen im Synology Reverse Proxy. Unter „Benutzerdefinierter Header“ den Eintrag „WebSocket“ aktivieren und REMOTE_IP_VALVE_ENABLED=true in der guacamole-Konfiguration setzen.
6. Verbindung zu Windows-PC schlägt fehl (schwarzer Bildschirm oder Fehler): RDP auf dem Ziel-PC aktivieren (Systemsteuerung > System > Remoteeinstellungen > „Remoteverbindungen zulassen“). NLA-Modus kann bei bestimmten Windows-Versionen Probleme machen – dann Sicherheitsmodus auf „Any“ setzen.
7. Nach Update (z. B. 1.5.x auf 1.6.0) startet guacamole mit DB-Fehlern: Das Schema hat sich geändert. Backup der Datenbank erstellen, dann dbdata leeren und das Schema mit dem neuen initdb.sh neu einzuspielen.
8. Browser zeigt alte URL nach WEBAPP_CONTEXT-Änderung: Browser-Cache oder gespeicherte Redirects. InPrivate-/Inkognito-Fenster öffnen oder Cache löschen (Strg+Shift+Del).

Häufige Fragen

Kann ich Guacamole ohne eigene Domain und ohne HTTPS betreiben?

Technisch ja – HTTP auf Port 8080 funktioniert für Tests im Heimnetz. Für den Produktivbetrieb ist das aber nicht empfehlenswert: TOTP-Codes werden dann im Klartext übertragen. Schalte mindestens im Heimnetz mit selbst signiertem Zertifikat auf HTTPS um, oder nutze den Synology Reverse Proxy mit einem öffentlichen Let's Encrypt-Zertifikat, sobald du Guacamole von außen erreichbar machen möchtest.

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 stattdessen RDP direkt ins Internet exponiert, sollte die Anleitung Remote Desktop Services einrichten und lizenzieren lesen, um die Risiken und korrekte Konfiguration zu verstehen.

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

Neue Verbindung in Guacamole: Protokoll SSH, Hostname = interne IP des NAS (oder 172.17.0.1 wenn der Container im Standard-Docker-Netzwerk läuft), Port 22. SSH muss in DSM unter Systemsteuerung > Terminal & SNMP aktiviert sein. Empfehlung: SSH-Zugang nur intern nutzen und Port 22 keinesfalls im Router weiterleiten – 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?

Es gibt kein hartes Software-Limit; die Grenze liegt beim CPU/RAM des NAS und der Netzwerkbandbreite. Auf einem typischen KMU-NAS (z. B. DS923+ mit 8 GB RAM) sind 5–15 gleichzeitige Verbindungen realistisch. Pro Verbindung verbraucht guacd je nach Protokoll ca. 10–50 MB RAM. RDP ist dabei ressourcenschonender als VNC, da guacd das RDP-Protokoll nativ versteht.

Wie aktiviere ich Session-Recordings?

Setze in der compose.yaml unter dem guacamole-Container die Umgebungsvariable RECORDING_SEARCH_PATH=/record. Das Volume /record muss in beiden Containern (guacd und guacamole) gemountet sein – was in der Compose-Konfiguration oben bereits so vorgesehen ist. Recordings sind danach in der Guacamole-Admin-Oberfläche als Video abrufbar.

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

Vom Apache Guacamole-Projekt offiziell nicht. Community-Images wie jwetzell/guacamole existieren, sind aber keine offiziellen Apache-Images und erhalten möglicherweise keine zeitnahen Sicherheitsupdates. Für einen produktiven KMU-Einsatz empfiehlt sich ausschließlich der offizielle Drei-Container-Stack mit den Images unter dem guacamole/-Namespace auf Docker Hub.

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

Guacamole ist ein Gateway-Konzept: Alle Verbindungen laufen zentral durch das NAS, werden protokolliert, und Benutzer brauchen keinen Client. RustDesk ist eher ein Peer-to-Peer-Fernwartungs-Tool für unbeaufsichtigte Zugriffe – ähnlich TeamViewer. Wer beides kennenlernen möchte: Die Anleitung RustDesk-Server auf dem Synology NAS installieren zeigt den RustDesk-Ansatz im direkten Vergleich.

Fazit

Apache Guacamole auf dem Synology NAS ist eine der wenigen Self-Hosted-Lösungen, die echten KMU-Mehrwert ohne große Infrastruktur liefern: Ein zentrales, auditiertes Zugangssystem mit TOTP-MFA, das offene RDP-Ports im Router überflüssig macht. Der Drei-Container-Stack ist nach einmaliger Einrichtung stabil und wartungsarm – vorausgesetzt, das Datenbankschema wird korrekt initialisiert. Wer HTTPS via Synology Reverse Proxy ergänzt, hat ein vollständiges, produktiv nutzbares Remote-Access-Gateway für das gesamte interne Netzwerk.

Die Images werden aktiv gepflegt (Stand Juni 2026: letzter Push vor weniger als 24 Stunden), und das Apache Software Foundation-Projekt ist als Top-Level-Projekt langfristig verankert. Für KMU, die bisher RDP oder SSH direkt ins Internet exponiert haben, ist der Umstieg auf Guacamole eine der wirkungsvollsten Sicherheitsmaßnahmen mit vergleichsweise geringem Aufwand.

Weiterführende Anleitungen und Quellen

1. Remote Desktop Services einrichten und lizenzieren: Terminalserver für KMU – wer Windows RDS parallel zu Guacamole betreibt, findet hier die Lizenz- und Konfigurationsgrundlagen
2. SSH-Hardening Deep-Dive: sshd_config, Match-Blöcke und ssh-audit für KMU-Server – SSH-Verbindungen über Guacamole sind sicherer, wenn auch der SSH-Daemon selbst gehärtet ist
3. RustDesk-Server auf dem Synology NAS installieren: Fernwartung als TeamViewer-Alternative – der ergänzende Peer-to-Peer-Ansatz für unbeaufsichtigte Fernzugriffe

Offizielle Quellen: Dieser Artikel basiert auf der offiziellen Apache Guacamole-Dokumentation Version 1.6.0 (guacamole.apache.org) sowie den Docker-Hub-Seiten der offiziellen Images. Bei Widersprüchen zwischen Community-Anleitungen und offizieller Dokumentation wurde stets der offiziellen Quelle gefolgt – insbesondere hinsichtlich Drei-Container-Architektur, initdb.sh-Pflicht und TOTP-Konfiguration.