Apache Guacamole: Remote Desktop im Browser ohne Client-Software
Manchmal brauchst du kurz deinen Windows-PC oder eine Linux-Shell, sitzt aber an einem fremden Rechner, auf dem du nichts installieren darfst. Apache Guacamole löst genau das: Du öffnest eine Webseite und bekommst den Desktop oder das Terminal direkt im Browser. In diesem Guide richtest du Guacamole auf Proxmox ein, legst eine RDP-Verbindung zu einem Windows-PC und eine SSH-Verbindung an, aktivierst Zwei-Faktor-Login und sorgst dafür, dass das Ganze nicht offen im Internet hängt.
Kurz erklärt
- Guacamole ist ein Remote-Desktop-Gateway. Es spricht RDP, VNC und SSH mit deinen Rechnern und zeigt das Bild im Browser an.
- Auf dem Gerät, von dem aus du zugreifst, brauchst du nur einen aktuellen Browser.
- Es eignet sich für alle, die mehrere Rechner und Server von einer Stelle aus erreichen wollen.
- Du brauchst einen Proxmox-Host oder einen Rechner mit Docker, dazu Zielrechner mit aktiviertem RDP oder SSH.
So funktioniert Guacamole
Guacamole besteht aus zwei Teilen. guacd ist ein Hintergrunddienst, der die eigentlichen Verbindungen per RDP, VNC oder SSH aufbaut. Die Web-App läuft in Tomcat (einem Java-Webserver), übernimmt Login und Verwaltung und schickt das Bild an deinen Browser. Benutzer und Verbindungen speichert sie in einer Datenbank, hier MariaDB. Von außen siehst du nur die Web-App. Die Zielrechner müssen also nur vom Guacamole-Server aus erreichbar sein, nicht von deinem Laptop.
Das brauchst du
- Einen Proxmox-VE-Host mit Shell-Zugriff. Der Container bekommt standardmäßig 1 Kern, 2 GB RAM und 4 GB Disk. Alternativ einen Linux-Rechner mit Docker und Docker Compose.
- Einen Windows-PC mit Windows Pro, Enterprise oder Education. Windows Home kann keine eingehenden RDP-Verbindungen annehmen.
- Optional einen Linux-Server mit laufendem SSH-Dienst.
- Ein Smartphone mit Authenticator-App für die Zwei-Faktor-Anmeldung.
- Für den Zugriff von unterwegs Tailscale oder einen Reverse Proxy mit zusätzlichem Login.
Schritt 1: Guacamole installieren
Ich nutze die Proxmox VE Helper-Scripts der Community. Das Script legt einen Debian-LXC an, kompiliert guacd aus dem Quellcode, installiert Tomcat 9 und MariaDB und richtet die Datenbank-Anmeldung ein. Du startest es in der Shell des Proxmox-Hosts:
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/apache-guacamole.sh)"Lies das Script vorher auf GitHub, bevor du es als root ausführst. Das Kompilieren dauert ein paar Minuten. Danach erreichst du Guacamole unter http://192.168.1.x:8080/guacamole. Bei mir läuft so Guacamole 1.6.0 in einem LXC mit einem Kern und 2 GB RAM, und das reicht für ein paar gleichzeitige Sitzungen locker. Updates holst du später, indem du in der Konsole des LXC update eingibst.
Ohne Proxmox nimmst du die offiziellen Docker-Images guacamole/guacd und guacamole/guacamole plus eine PostgreSQL-Datenbank. Guacamole legt seine Tabellen nicht selbst an. Das passende SQL-Script erzeugst du laut Doku mit dem initdb.sh aus dem Image und legst es in einen Ordner, den der Postgres-Container beim ersten Start automatisch einspielt:
mkdir -p guacamole/initdb && cd guacamole
docker run --rm guacamole/guacamole:1.6.0 /opt/guacamole/bin/initdb.sh --postgresql > initdb/initdb.sqlDaneben legst du die Datei docker-compose.yml an:
services:
guacd:
image: guacamole/guacd:1.6.0
restart: unless-stopped
postgres:
image: postgres:16
restart: unless-stopped
environment:
POSTGRES_DB: guacamole_db
POSTGRES_USER: guacamole_user
POSTGRES_PASSWORD: <dein-db-passwort>
volumes:
- ./initdb:/docker-entrypoint-initdb.d:ro
- ./db:/var/lib/postgresql/data
guacamole:
image: guacamole/guacamole:1.6.0
restart: unless-stopped
depends_on:
- guacd
- postgres
environment:
GUACD_HOSTNAME: guacd
POSTGRESQL_HOSTNAME: postgres
POSTGRESQL_DATABASE: guacamole_db
POSTGRESQL_USERNAME: guacamole_user
POSTGRESQL_PASSWORD: <dein-db-passwort>
ports:
- "8080:8080"Ersetz <dein-db-passwort> an beiden Stellen durch dasselbe lange Passwort und starte mit docker compose up -d. Danach erreichst du Guacamole unter http://192.168.1.x:8080/guacamole. Postgres spielt das Schema nur beim allerersten Start in eine leere Datenbank ein. Ging dabei etwas schief, stoppst du mit docker compose down, löschst den Ordner db und startest neu. Der Rest dieses Guides gilt für beide Wege, wo sich der Docker-Weg unterscheidet, steht er extra dabei.
Schritt 2: Erster Login und Standard-Zugang ersetzen
Das Datenbank-Schema von Guacamole legt einen Standard-Benutzer an: Benutzername guacadmin, Passwort guacadmin. Diese Daten kennt jeder, der die Doku gelesen hat. Ersetze sie deshalb sofort nach dem ersten Login, noch bevor du irgendeine Verbindung anlegst. Am saubersten geht das mit einem eigenen Admin-Konto:
- Melde dich mit
guacadminan. - Klick oben rechts auf den Benutzernamen und öffne Settings, dort den Reiter Users.
- Leg mit New User einen eigenen Benutzer mit starkem Passwort an und setz bei den Berechtigungen den Haken bei Administer system.
- Melde dich ab und mit dem neuen Konto wieder an.
- Öffne unter Users den Benutzer
guacadminund lösch ihn oder deaktivier ihn zumindest.
Die Oberfläche folgt der Sprache deines Browsers. Bei deutschem Browser heißen die Menüs entsprechend Einstellungen, Benutzer und so weiter. Wenn du guacadmin lieber behalten willst, ändere wenigstens das Passwort unter Settings und Preferences.
Schritt 3: RDP-Verbindung zu einem Windows-PC
Auf dem Windows-PC aktivierst du zuerst Remotedesktop unter Einstellungen, System, Remotedesktop. Gib dem PC im Router eine feste IP. Dann legst du in Guacamole die Verbindung an: Settings, Connections, New Connection.
| Feld | Wert |
|---|---|
| Name | Windows-PC |
| Protocol | RDP |
| Hostname | 192.168.1.x |
| Port | 3389 |
| Username / Password | Dein Windows-Benutzer und Passwort |
| Security mode | NLA (Network Level Authentication) oder Any |
| Ignore server certificate | Haken setzen |
| Keyboard layout | German (Qwertz) |
Windows nutzt für RDP ein selbstsigniertes Zertifikat, deshalb der Haken bei Ignore server certificate. NLA heißt, dass du dich schon vor dem Aufbau der Sitzung anmeldest. Das ist der Windows-Standard und sicherer als die alten Modi. Wenn du dich mit einem Microsoft-Konto anmeldest, gibst du die E-Mail-Adresse und das Kontopasswort ein, nicht die Windows-Hello-PIN. Lässt du Benutzer und Passwort leer, fragt Guacamole sie beim Verbinden ab.
Nach dem Speichern taucht die Verbindung auf der Startseite auf. Ein Klick öffnet den Desktop im Browser-Tab. Mit Strg+Alt+Shift öffnest du das Guacamole-Menü. Darüber tauschst du die Zwischenablage aus, lädst Dateien hoch oder trennst die Verbindung.
Schritt 4: SSH-Verbindung zu einem Linux-Server
Eine SSH-Verbindung legst du genauso an. Als Protocol wählst du SSH, als Hostname die IP des Servers, als Port 22 und als Username deinen Linux-Benutzer. Statt eines Passworts kannst du einen Private Key hinterlegen. Dafür fügst du den kompletten Inhalt der Schlüsseldatei in das Feld Private key ein. Guacamole erwartet das OpenSSH-Format, wie es ssh-keygen erzeugt. Erstell dafür am besten ein eigenes Schlüsselpaar nur für Guacamole:
ssh-keygen -t ed25519 -f ~/.ssh/guacamole -C guacamole
ssh-copy-id -i ~/.ssh/guacamole.pub benutzer@192.168.1.xDen Inhalt von ~/.ssh/guacamole kopierst du in Guacamole. So kannst du den Schlüssel jederzeit auf dem Server aus authorized_keys entfernen, ohne deine anderen Zugänge anzufassen. Bei Bedarf stellst du unter Display noch Schriftgröße und Farbschema des Terminals ein.
Schritt 5: Zwei-Faktor-Login mit TOTP
TOTP sind die sechsstelligen Codes aus einer Authenticator-App. Guacamole bringt dafür eine offizielle Erweiterung mit, die beim Community-Script aber nicht vorinstalliert ist. Im LXC lädst du sie passend zu deiner Version herunter und kopierst sie in den Extensions-Ordner. Deine Version zeigt dir guacd -v. Für 1.6.0 sieht das so aus, bei einer neueren Version passt du nur die erste Zeile an:
VER=1.6.0
cd /tmp
curl -fsSLO https://downloads.apache.org/guacamole/$VER/binary/guacamole-auth-totp-$VER.tar.gz
tar -xzf guacamole-auth-totp-$VER.tar.gz
cp guacamole-auth-totp-$VER/guacamole-auth-totp-$VER.jar /etc/guacamole/extensions/
systemctl restart tomcatBeim nächsten Login zeigt Guacamole nach dem Passwort einen QR-Code. Den scannst du mit der Authenticator-App und bestätigst mit dem ersten Code. Ab dann fragt Guacamole bei jedem Login nach dem Code. Richte TOTP zuerst für dein Admin-Konto ein und prüf den Login in einem privaten Browserfenster, bevor du dich im normalen Fenster abmeldest. Das Update-Script der Community erkennt die installierte TOTP-Erweiterung und aktualisiert sie mit. Im Docker-Setup reicht die Zeile TOTP_ENABLED: "true" im Block environment des Dienstes guacamole. Danach erstellst du den Container mit docker compose up -d neu.
Auf dieselbe Weise kannst du die Erweiterung guacamole-auth-ban nachrüsten. Sie sperrt eine IP nach fünf fehlgeschlagenen Logins für fünf Minuten. Im Docker-Image ist sie bereits aktiv. Bei der nativen Installation legst du sie selbst in den Extensions-Ordner:
VER=1.6.0
cd /tmp
curl -fsSLO https://downloads.apache.org/guacamole/$VER/binary/guacamole-auth-ban-$VER.tar.gz
tar -xzf guacamole-auth-ban-$VER.tar.gz
cp guacamole-auth-ban-$VER/guacamole-auth-ban-$VER.jar /etc/guacamole/extensions/
systemctl restart tomcatDas update des Community-Scripts aktualisiert TOTP mit, die Ban-Erweiterung aber nicht. Nach einem Update auf eine neue Guacamole-Version löschst du deshalb die alte guacamole-auth-ban-*.jar aus /etc/guacamole/extensions und wiederholst die Befehle oben mit der neuen Versionsnummer.
Schritt 6: Sicher von unterwegs zugreifen
Guacamole ist ein Schlüssel zu allen Rechnern, die du darin einträgst. Wer reinkommt, steht direkt auf deinem Windows-Desktop oder in deiner Server-Shell. Gib Port 8080 deshalb niemals per Portfreigabe im Router frei.
Der einfachste sichere Weg ist Tailscale. Du installierst Tailscale auf dem Guacamole-LXC oder nutzt einen Subnet-Router in deinem LAN und rufst Guacamole von unterwegs über die Tailscale-Adresse auf. Es ist dann kein einziger Port offen. Wenn du Guacamole auch auf Geräten ohne Tailscale brauchst, etwa am Arbeitsrechner, setz einen Reverse Proxy mit HTTPS davor. Mit Caddy sieht das so aus:
remote.example.de {
redir / /guacamole/
reverse_proxy 192.168.1.x:8080
}Caddy reicht die Websocket-Verbindungen, über die Guacamole das Bild überträgt, automatisch durch. In diesem Fall gehören TOTP und die Sperre nach Fehlversuchen zwingend dazu. Besser ist noch ein vorgeschalteter Login wie Authelia oder Authentik und ein Filter gegen Scanner. Wie ich das mit CrowdSec mache, steht in CrowdSec mit Caddy.
Hinter einem Reverse Proxy sieht Tomcat sonst bei jedem Login nur die IP von Caddy. Die Sperre nach Fehlversuchen würde dann den Proxy selbst sperren und damit alle Benutzer. Damit Guacamole die echte Client-IP aus dem Header X-Forwarded-For liest, trägst du im LXC in /opt/apache-guacamole/tomcat9/conf/server.xml innerhalb des Abschnitts <Host> das RemoteIpValve ein. Pfad und Service-Name tomcat stammen aus der aktuellen Version des Community-Scripts (Stand Oktober 2026). Ältere oder neuere Script-Versionen können andere Pfade nutzen. Mit systemctl cat tomcat siehst du in der Zeile CATALINA_BASE, wo Tomcat bei dir liegt. Statt 192\.168\.1\.x setzt du die IP deines Caddy-Servers ein, mit Backslash vor jedem Punkt:
<Valve className="org.apache.catalina.valves.RemoteIpValve"
internalProxies="192\.168\.1\.x"
remoteIpHeader="x-forwarded-for"
remoteIpProxiesHeader="x-forwarded-by"
protocolHeader="x-forwarded-proto" />Danach startest du Tomcat mit systemctl restart tomcat neu. Im Docker-Setup reicht stattdessen REMOTE_IP_VALVE_ENABLED: "true" im Block environment des Dienstes guacamole. Ohne weitere Angabe vertraut das Image dann Proxys aus privaten IP-Bereichen.
Schritt 7: Backups
In Guacamole steckt mehr Arbeit, als man denkt: Benutzer, TOTP-Schlüssel, alle Verbindungen mit Zugangsdaten. Das liegt in der Datenbank. Am einfachsten sicherst du beim Community-Script den ganzen LXC regelmäßig per Proxmox-Backup (vzdump) auf ein NAS. Zusätzlich ziehst du im LXC einen Dump der Datenbank, die das Script guacamole_db nennt:
mariadb-dump -u root guacamole_db > /root/guacamole-$(date +%F).sqlZurückspielen geht mit mariadb -u root guacamole_db < /root/guacamole-DATUM.sql. Sichere außerdem den Ordner /etc/guacamole, dort liegen die Konfiguration mit dem Datenbank-Passwort und die Erweiterungen. Im Docker-Setup sicherst du die Datenbank mit docker compose exec -T postgres pg_dump -U guacamole_user guacamole_db > guacamole-$(date +%F).sql und dazu die docker-compose.yml. Diese Dumps enthalten deine Zugangsdaten, leg sie also nicht ungeschützt ab.
So prüfst du, ob es läuft
Im LXC laufen drei Dienste, die du einzeln prüfen kannst:
systemctl status guacd tomcat mariadb
ss -tlnp
ls /etc/guacamole/extensionsIn ss -tlnp solltest du Java auf Port 8080 sehen, guacd auf 4822 und MariaDB auf 3306, die beiden letzten nur an 127.0.0.1. Im Extensions-Ordner liegen die JDBC-Erweiterung für die Datenbank und, falls installiert, TOTP und Ban. Danach meldest du dich im Browser an und öffnest jede Verbindung einmal.
Im Docker-Setup zeigt dir docker compose ps, ob alle drei Container laufen. Fehler beim Start findest du mit docker compose logs guacamole, meist ist dann die Datenbank nicht initialisiert oder das Passwort stimmt nicht überein.
Typische Probleme
- RDP bricht sofort mit Fehler ab: Fast immer der Security mode oder das Zertifikat. Setz Ignore server certificate und probier nacheinander NLA und Any. Den genauen Grund zeigt
journalctl -u guacd -f(Docker:docker compose logs -f guacd), während du verbindest. - Login am Windows-PC schlägt fehl: Bei Microsoft-Konten funktioniert nur das Kontopasswort. Wenn Windows auf reine Hello-Anmeldung eingestellt ist, schalte unter Konten und Anmeldeoptionen die Option aus, die für Microsoft-Konten nur Windows Hello erlaubt.
- Verbindung zu Windows Home klappt nicht: Windows Home hat keinen RDP-Server. Hier hilft nur ein VNC-Server auf dem PC oder ein Upgrade auf Pro.
- Falsche Sonderzeichen oder vertauschtes Y und Z: Das Keyboard layout steht nicht auf German (Qwertz).
- Unter der IP kommt nur eine leere Seite oder Tomcat: Die Web-App liegt unter
/guacamole, nicht direkt unter der IP. - Nach Update startet die Anmeldung nicht mehr: Die Version von Erweiterungen wie TOTP muss zur Guacamole-Version passen. Die Fehlermeldung steht in
/opt/apache-guacamole/tomcat9/logs/catalina.out, bei Docker indocker compose logs guacamole.
Fazit
Mit Guacamole hast du alle Rechner im Homelab in einem Browser-Tab, ohne Client-Software und auf jedem Gerät. Die Installation per Community-Script dauert ein paar Minuten. Wichtiger als die Installation sind die nächsten zehn Minuten: Standard-Login ersetzen, TOTP aktivieren und den Zugriff über Tailscale oder einen abgesicherten Reverse Proxy regeln. Wenn das steht, ist Guacamole eines der praktischsten Tools im ganzen Setup. Einen Überblick, wie mein Homelab sonst aufgebaut ist, findest du in Mein Homelab an zwei Standorten.
Hat dir der Guide geholfen? Dann spendier mir gern einen Kaffee auf Ko-fi. Damit bleibt MappleBox werbefrei.
