Reverse Proxy Routen einrichten

Du hast einen Dienst, den du aus dem Internet unter deiner eigenen Domain erreichen willst — z.B. Nextcloud auf der NAS als cloud.example.com, oder Home Assistant als home.example.com, oder einen SSH-Server auf ssh.example.com:22. Alles drei geht über den Routen-Wizard, aber mit leicht unterschiedlichen Settings.

Diese Anleitung zeigt die drei typischen Szenarien und geht Schritt für Schritt durch den 6-stufigen Wizard.

Die drei Szenarien

Szenario	Wann?	Target-Kind	Route-Typ
A: Direkt zum Peer	Auf dem Zielgerät läuft GateControl-Client + WireGuard	`peer`	`http` oder `l4`
B: Via Home-Gateway ins LAN	Zielgerät hat nichts installiert (typisch für NAS-WebUIs, Router-Admin, IoT)	`gateway`	`http` oder `l4`
C: L4-Port-Forward	Beliebiger TCP/UDP-Dienst, kein HTTP (SSH, Minecraft, MQTT)	`peer` oder `gateway`	`l4`

In allen drei Fällen arbeitest du dich durch denselben Wizard, aber an Step 1 (Ziel) und Step 2 (Transport) wählst du andere Optionen.

Vorbereitung: DNS-Record setzen

Egal welches Szenario — vor dem Anlegen muss der DNS-Record stehen.

Im DNS-Panel deines Domain-Providers einen A-Record anlegen:
- Name: cloud (oder home, ssh, …)
- Wert: die öffentliche IPv4 deines GateControl-Servers
- TTL: 300 (5 min, damit du später schnell korrigieren kannst)
Wenn der Provider Proxy-Modus anbietet (Cloudflare):
- Für HTTP-Routen: Proxy aus. Caddy holt das Cert direkt bei Let's Encrypt — das geht mit Cloudflare-Proxy davor nicht, weil LE dann die falsche IP sieht.
- Für L4-Routen: Proxy aus. Cloudflare proxyt nur HTTP/HTTPS.
Propagation abwarten (meist 1–5 min):
```
dig +short cloud.example.com
```
muss deine Server-IP zurückgeben.

Im Wizard gibt es am Ende von Step 1 einen DNS-Check (POST /api/v1/routes/check-dns). Der ist eine Warning wenn's nicht passt, kein harter Stopper. Sprich: speichern kannst du auch bei falschem DNS, aber das Cert wird nicht kommen.

Szenario A: Direkter Peer (HTTP)

Beispiel: Nextcloud läuft auf deinem Home-NAS, und die NAS hat den GateControl-Client installiert (WG-Peer, bekommt die IP 10.8.0.12). Nextcloud hört auf http://10.8.0.12:80 (oder einem anderen Port).

Routen → + Hinzufügen → Wizard öffnet sich.
Step 1 — Ziel
- Route-Typ: HTTP
- Domain: cloud.example.com
- Target-Kind: Peer (Default)
- Peer auswählen: home-nas
- Ziel-Port: 80
Step 2 — Transport
- Backend-HTTPS: aus (Nextcloud spricht HTTP intern).
- Falls das Backend HTTPS ist (z.B. Synology DSM :5001): Haken an + Self-Signed akzeptieren an.
Step 3 — Authentifizierung
- Keine, Basic-Auth oder Route-Auth (Email+Password mit Passkey).
- Nextcloud hat eigene Auth → keine Zusatz-Auth nötig.
Step 4 — Zugriff
- IP-Whitelist/-Blacklist (CIDR-Liste).
- Peer-ACL: nur bestimmte Peers dürfen zugreifen.
- Default: offen für alle. Für eine intern zugängliche Nextcloud reicht das — Nextcloud hat ja eigene Auth.
Step 5 — Zuverlässigkeit
- Uptime-Monitoring, Rate-Limiting, Request-Mirroring, Circuit-Breaker, Retry. Alles optional. Für den Start: aus lassen.
Step 6 — Übersicht
- Nochmal alles durchlesen, Speichern.

Caddy lädt die neue Config, registriert den Let's-Encrypt-Cert (HTTP-01-Challenge, Port 80 muss frei sein), und nach ~30 Sekunden öffnest du https://cloud.example.com im Browser.

Szenario B: Via Home-Gateway ins LAN (HTTP)

Beispiel: Synology DSM auf 192.168.1.10:5001 (HTTPS mit Self-Signed-Cert), kein GateControl-Client installiert. Du hast einen Home-Gateway-Container laufen, siehe first-gateway-setup.md.

Vorarbeit: Home-Gateway-Peer ist online, zu sehen unter Peers & Clients → Home Gateways.

Routen → + Hinzufügen.
Step 1 — Ziel
- Route-Typ: HTTP
- Domain: dsm.example.com
- Target-Kind: Gateway
- Gateway-Peer auswählen: homeserver-nuc
- Ziel-LAN-Host: 192.168.1.10 (die IP/Hostname im LAN des Gateways, nicht eine VPN-IP)
- Ziel-LAN-Port: 5001
Step 2 — Transport
- Backend-HTTPS: an (DSM spricht HTTPS).
- Self-Signed akzeptieren: an (DSM hat in der Default-Config ein self-signed Cert).
Step 3 — Authentifizierung
- DSM hat eigene Auth → Route-Auth und Basic-Auth nicht nötig. Wenn du möchtest, eine Basic-Auth davor hängen.
Step 4 — Zugriff
- IP-Whitelist sinnvoll (z.B. nur deine Heim-IP + Büro-IP). DSM wird sonst von Scannern permanent befragt.
Step 5 — Zuverlässigkeit
- Bei Gateway-Routen kann Uptime-Monitoring nützlich sein, um Gateway-Ausfälle vom Route-Ausfall zu trennen.
Step 6 — Speichern.

Wie das intern läuft: Caddy sendet die Anfrage an die WG-IP des Gateways, der Gateway-Container empfängt den Request, liest den X-Gateway-Target-Header raus und proxyt auf 192.168.1.10:5001 im LAN. TLS terminiert Caddy auf dem Server, der Gateway-→-LAN-Hop geht entweder HTTP (wenn Backend-HTTPS aus) oder HTTPS (wenn an).

Szenario C: L4-Port-Forward

Beispiel: SSH-Zugriff auf eine LAN-Box. Öffentlich als ssh.example.com:22.

Routen → + Hinzufügen.
Step 1 — Ziel
- Route-Typ: L4
- Domain: ssh.example.com (optional — L4-Routen ohne Domain gehen auch, sind dann aber nur per Server-IP:Port erreichbar)
- L4-Listen-Port: 22 (der Port auf dem GateControl-Server, den der Client von außen ansteuert)
- L4-Protokoll: TCP
- Target-Kind: peer oder gateway
- Bei gateway: Ziel-LAN-Host 192.168.1.20, Ziel-LAN-Port 22
Step 2 — Transport
- TLS-Modus (drei Optionen):
  - none — purer TCP/UDP-Proxy, kein Cert. Richtig für SSH, Minecraft, MQTT-plain, MySQL etc.
  - passthrough — Caddy terminiert TLS nicht, reicht die TLS-Session ans Backend durch. Nur sinnvoll wenn das Backend selbst ein gültiges Cert hat, z.B. Nginx im LAN mit eigenem LE.
  - terminate — Caddy terminiert TLS am Server mit Let's-Encrypt-Cert und spricht dann plain TCP zum Backend. Nur für HTTPS-ähnliche Protokolle; für SSH/Minecraft sinnlos.
Step 3 — Authentifizierung
- Für L4 kein Server-seitiges Auth-Plugin verfügbar (wie auch bei SSH — die Auth macht das Backend-Protokoll selbst).
Step 4 — Zugriff
- IP-Filter für SSH dringend empfohlen. Peer-ACL wirkt nur für Clients mit WG-Tunnel, hilft bei öffentlich erreichbaren L4-Routen also nicht.
Step 5 — Zuverlässigkeit
- L4 hat kein Mirror, kein Retry, kein Rate-Limit — die Optionen sind ausgegraut. Uptime-Monitoring geht (TCP-Connect-Check).
Step 6 — Speichern.

Testen:

ssh -p 22 user@ssh.example.com

Auth davor hängen (optional)

Wenn das Backend keine eigene Auth hat (z.B. ein Grafana ohne Login, ein internes Wiki) kannst du Route-Auth vorschalten:

Basic-Auth: simple user/password, HTTP-Auth-Dialog im Browser.
Route-Auth (Email+Password): Server zeigt eine GateControl-Login-Seite, User muss sich mit seinen Admin-Credentials oder einem separaten Route-User anmelden. Passkey-Flow verfügbar.

Beides findest du in Step 3 des Wizards. Weiterführend ../AUTHENTICATION.md.

Troubleshooting

502 Bad Gateway

Die häufigste Fehlerseite, wenn eine frische Route nicht funktioniert.

Prüfschritte:

Backend erreichbar? Vom GateControl-Host aus:

curl -v http://10.8.0.12:80       # Szenario A
curl -vk https://192.168.1.10:5001 # Szenario B (vom Gateway aus testen!)

Bei Gateway-Routen: Gateway-Container online? Heartbeat frisch? (Siehe first-gateway-setup.md — Troubleshooting.)
Firewall am Backend-Host: Viele NAS-Firewalls blocken per Default fremde Subnetze. Der Gateway bringt die Anfrage aus 10.8.0.0/24, das muss erlaubt sein. Alternative: Gateway-Host in die LAN-Firewall-Allowlist aufnehmen.
Port stimmt? Tippfehler in target_lan_port / target_port werfen nicht direkt 502 auf Config-Level, aber silent auf Connect-Fail.

DNS-Fehler im Wizard-Check

Der Wizard zeigt "DNS zeigt nicht auf Server-IP".

Mögliche Ursachen:

Record noch nicht propagiert → 5 min warten, dig +short … prüfen.
Cloudflare-Proxy an → Proxy aus (orange Wolke grau machen).
Falscher A-Record (CNAME statt A kann gehen, muss aber letztlich auf deine IP auflösen).
Mehrere IPs im A-Record → nur eine davon ist der Server.

Der Wizard ist hier tolerant: die Warning blockiert Save nicht. Aber solange DNS falsch ist, kommt kein Cert.

Zertifikat kommt nicht

Siehe die ausführliche Anleitung in certificates.md. Kurz:

Port 80 auf dem Server erreichbar? (ACME HTTP-01)
DNS richtig? (Point 1)
Let's Encrypt Rate-Limit getroffen? (50 Certs / Woche / Registered Domain)
Caddy-Logs: docker logs gatecontrol 2>&1 | grep -i "acme\|tls.obtain"

Route auf Synology DSM: "Backend kaputt" aber DSM läuft

DSM mit Self-Signed-Cert auf :5001: Backend-HTTPS an und Self-Signed akzeptieren an. Sonst scheitert Caddy am Zertifikat-Verify. Nicht verwechseln: self_signed_accept ist ein Per-Route-Flag, kein globaler Schalter.

L4-Route mit tls_mode=terminate will kein Cert

L4-TLS funktioniert anders als HTTP-TLS in Caddy — siehe Abschnitt "L4-Route mit TLS-terminate" in certificates.md.

Weiterführend

../HTTP-VS-L4-ROUTING.md — tiefere Abgrenzung HTTP vs. L4.
../BACKEND-HTTPS.md — Backend-HTTPS-Feinheiten.
../AUTHENTICATION.md — Route-Auth, Basic-Auth, Passkey.
../IP-ACCESS-CONTROL.md + ../PEER-ACCESS-CONTROL.md
configuring-rdp.md — spezialisierter RDP-Wizard.
certificates.md — TLS-Probleme debuggen.