OPNsense - Caddy Reverse Proxy

Auf einen Blick

Gilt für	OPNsense 26.1/26.7 mit Plugin os-caddy 2.2 (Caddy 2.10 oder neuer)
Bereich	IT-Security
Dauer	ca. 30 Minuten (Grundeinrichtung und erste Webanwendung), Walkthrough komplett ca. 2 Stunden
Rechte	Administrator (OPNsense-WebUI), Zugriff auf die öffentliche DNS-Zone
Stand	Oktober 2026

Caddy ist ein moderner Webserver und Reverse Proxy mit automatischem HTTPS: Für jede eingetragene Domain besorgt und verlängert Caddy selbstständig ein Zertifikat von Let's Encrypt oder ZeroSSL. Mit dem Plugin os-caddy wird die OPNsense so in wenigen Minuten zum sicheren Eingangstor für interne Webanwendungen wie Nextcloud, Grafana, Home-Office-Portale oder die Weboberflächen von Servern – inklusive Zugriffsbeschränkung, Basic Auth, Client-Zertifikaten und Single Sign-On über authentik.

Dieser Artikel stellt das Plugin vor und führt in einem durchgehenden Walkthrough von der Installation bis zu fortgeschrittenen Szenarien.

Was ist Caddy und wann ist es die richtige Wahl?

Automatisches HTTPS: Zertifikate werden ohne zusätzliche Konfiguration ausgestellt und verlängert; HTTP wird automatisch auf HTTPS umgeleitet.
Einfache Oberfläche: Domains und Handler (Weiterleitungen an interne Dienste) statt komplexer Frontend/Backend-Logik.
Moderne Protokolle: HTTP/1.1, HTTP/2 und optional HTTP/3 (QUIC), WebSockets.
Zugriffsschutz pro Domain: Access Lists, Basic Auth, mTLS und Forward Auth (authentik, Authelia).
Layer4-Proxy: TCP/UDP-Weiterleitung, auch mit Protokollerkennung (SSH, RDP, TLS mit SNI, OpenVPN u. a.).

Kriterium	Caddy (os-caddy)	HAProxy (os-haproxy)	OPNWAF (os-OPNWAF)
Schwerpunkt	Einfacher Reverse Proxy mit Auto-HTTPS	Lastverteilung, sehr fein steuerbar	Reverse Proxy mit Web Application Firewall
Zertifikate	Automatisch integriert	Über os-acme-client	Integriert
Einrichtung	Sehr einfach	Komplex	Mittel
WAF	Nein	Nein	Ja
Lizenz	Open Source (Community-Plugin)	Open Source	Kommerziell (Business Edition)

Für die meisten Veröffentlichungen interner Webdienste in kleinen und mittleren Umgebungen ist Caddy die bequemste Lösung. Wer eine Web Application Firewall benötigt, greift zu OPNWAF; für komplexe Lastverteilung zu HAProxy (siehe OPNsense - HAProxy mit Passwortauthentifizierung).

Datei:OPNsense-Caddy-Walkthrough.png

Walkthrough-Szenario: Caddy auf der OPNsense nimmt HTTPS-Anfragen für mehrere Domains an, besorgt die Zertifikate automatisch und leitet je nach Domain an Nextcloud, an das per authentik geschützte Grafana oder – nur intern – an die OPNsense-Weboberfläche weiter.

Das Walkthrough-Szenario

Domain	Ziel (Upstream)	Schutz
`cloud.example.com`	Nextcloud, `http://192.168.10.30:80`	öffentlich (Anmeldung in Nextcloud)
`grafana.example.com`	Grafana, `http://192.168.10.40:3000`	nur nach Anmeldung bei authentik (Forward Auth)
`wiki.example.com`	interner Webserver, `https://192.168.10.50` (selbstsigniert)	nur aus internen Netzen (Access List)
`opn.example.com`	OPNsense-Weboberfläche	nur intern, Access List

Öffentliche IPv4-Adresse der Firewall: 203.0.113.1.

Schritt 1: Plugin installieren und OPNsense vorbereiten

Installation

System → Firmware → Plugins: os-caddy installieren und die Seite neu laden. Das Menü befindet sich anschließend unter Services → Caddy mit den Punkten General Settings, Reverse Proxy, Layer4 Proxy, Diagnostics und Log File.

Ports 80 und 443 freimachen

Caddy benötigt die Ports 80 und 443 – die OPNsense-Weboberfläche darf sie nicht mehr belegen:

System → Settings → Administration: TCP Port auf z. B. 8443 ändern.
HTTP Redirect – Disable web GUI redirect rule aktivieren.
Speichern und die Weboberfläche künftig über https://<firewall>:8443 aufrufen. Auf dem LAN regelt die Anti-Lockout-Regel den Zugriff automatisch; auf anderen Interfaces eigene Regeln anlegen.

DNS-Einträge

Für jede Domain einen öffentlichen A-Record (bei IPv6 zusätzlich AAAA) auf die WAN-Adresse setzen, z. B. cloud.example.com → 203.0.113.1. Alternativ ein Wildcard-Eintrag *.example.com (siehe Schritt 6).

Firewall-Regeln

Unter Firewall → Rules auf dem Interface WAN und ebenso auf LAN (damit interne Clients die Dienste unter demselben Namen erreichen):

Protokoll	Quelle	Ziel	Port	Zweck
TCP	any	This Firewall	80 (HTTP)	ACME-Challenge und Umleitung auf HTTPS
TCP	any	This Firewall	443 (HTTPS)	Reverse Proxy
UDP	any	This Firewall	443	nur wenn HTTP/3 (QUIC) aktiviert wird

Eine Portweiterleitung (Destination NAT), NAT Reflection oder Split-DNS ist nicht nötig: Caddy läuft auf der Firewall selbst, und auch interne Zugriffe auf die öffentliche Adresse bleiben innerhalb der OPNsense. Regeln von der Firewall zu den internen Servern sind ebenfalls nicht nötig.

Schritt 2: Caddy aktivieren

Services → Caddy → General Settings:

Enable Caddy aktivieren.
ACME Email: eine gültige Adresse eintragen – Pflicht für automatische Zertifikate.
Auto HTTPS: On (default).
HTTP Versions: Standard ist HTTP/1.1 und HTTP/2. HTTP/3 nur bei Bedarf ergänzen (dann UDP 443 freigeben).
Apply.

Schritt 3: Erste Anwendung veröffentlichen (Nextcloud)

Domain anlegen

Services → Caddy → Reverse Proxy → Domains → +:

Feld	Wert
Protocol	`https://`
Domain	`cloud.example.com`
Port	leer (443)
Certificate	Auto HTTPS
Description	Nextcloud

Handler anlegen

Reverse Proxy → Handlers → +:

Feld	Wert
Domain	`https://cloud.example.com`
Path (Abschnitt Handler)	leer (alle Pfade)
Protocol (Abschnitt Upstream)	`http://`
Upstream Domain	`192.168.10.30`
Upstream Port	`80`

Save und Apply. Caddy holt nun automatisch das Zertifikat. Unter Services → Caddy → Log File erscheint bei Erfolg certificate obtained successfully; das Zertifikat ist zudem unter System → Trust → Certificates und im Dashboard-Widget sichtbar.

Test: https://cloud.example.com von außen und von innen aufrufen.

Hinweis

Schritt 4: Zugriff auf interne Netze beschränken (Access List)

Ein Reverse Proxy nimmt zunächst Verbindungen von überall an. Eine Firewall-Regel würde alle Domains gleichzeitig betreffen – Access Lists wirken dagegen pro Domain.

Reverse Proxy → HTTP Access → Access Lists → +: Name intern, Client IP Addresses 192.168.0.0/16, 172.16.0.0/12, 10.0.0.0/8 (zusätzlich ggf. das VPN-Tunnelnetz).
Domain wiki.example.com anlegen und im Abschnitt Access die Access List intern auswählen.
Handler für wiki.example.com anlegen (siehe Schritt 5) und Apply.

Verbindungen von außen werden nun abgewiesen. Im advanced mode der Access List lässt sich statt des Verbindungsabbruchs ein HTTP-Statuscode (z. B. 403) zurückgeben – hilfreich für Monitoring-Systeme.

Alternativen: Basic Auth und Client-Zertifikate

Basic Auth: Unter HTTP Access → Basic Auth Benutzer mit Passwort anlegen und im Abschnitt Access der Domain auswählen – eine einfache Passwortabfrage vor der Anwendung.
Client Auth (mTLS): Für höchsten Schutz im Abschnitt Access der Domain unter Client Auth Trust Pool die eigene CA (aus System → Trust) auswählen und den Client Auth Mode festlegen – nur Geräte mit einem Zertifikat dieser CA kommen durch.

Schritt 5: Interne HTTPS-Server mit selbstsignierten Zertifikaten

Viele interne Dienste (z. B. wiki.example.com auf https://192.168.10.50) sprechen nur HTTPS mit selbstsigniertem Zertifikat. Zwei Möglichkeiten:

Sauber: Das Zertifikat (bzw. die interne CA) unter System → Trust → Authorities importieren und im Handler unter TLS Trust Pool auswählen; unter TLS Server Name den Namen aus dem Zertifikat (SAN) eintragen.
Schnell (nur in vertrauenswürdigen Netzen): Im Handler https:// wählen und TLS Insecure Skip Verify aktivieren.

Caddy akzeptiert keine Zertifikate, die den Namen nur im Common Name (ohne SAN) tragen.

Sonderfall: OPNsense-Weboberfläche über Caddy

Domain opn.example.com mit Access List intern anlegen.
Das selbstsignierte Zertifikat der Weboberfläche im Browser exportieren und unter System → Trust → Authorities als opnsense-selfsigned importieren.
Handler: Upstream https://, 127.0.0.1, Port 8443, TLS Trust Pool opnsense-selfsigned, TLS Server Name = SAN des Zertifikats (z. B. OPNsense.localdomain).
Unter System → Settings → Administration bei Alternate Hostnames opn.example.com eintragen – sonst meldet die Weboberfläche einen HTTP_REFERER-Fehler.

Schritt 6: Wildcard-Domain mit DNS-01-Challenge

Statt jede Subdomain einzeln mit eigenem Zertifikat zu betreiben, kann Caddy ein Wildcard-Zertifikat *.example.com verwenden – praktisch bei vielen Diensten und um interne Hostnamen nicht in öffentlichen Zertifikatsprotokollen (Certificate Transparency) zu veröffentlichen.

Mit Cloudflare-DNS: General Settings → DNS Provider: Cloudflare, API-Token eintragen, Resolvers z. B. 1.1.1.1. Dann die Domain *.example.com mit aktivierter DNS-01 Challenge anlegen und darunter Subdomains wie cloud.example.com erstellen; Handler zeigen dann auf Domain *.example.com + Subdomain.
Mit anderen DNS-Anbietern: Seit Plugin-Version 2.0 ist Cloudflare der einzige integrierte DNS-Provider. Für andere Anbieter das Wildcard-Zertifikat mit os-acme-client ausstellen, in der Caddy-Domain als Certificate auswählen und im ACME-Client eine Automatisierung anlegen, die Caddy nach jeder Verlängerung neu lädt (nicht neu startet).

Ein Wildcard-Zertifikat enthält nicht die Basisdomain example.com – dafür bei Bedarf eine eigene Domain anlegen.

Schritt 7: Single Sign-On mit authentik (Forward Auth)

Mit Forward Auth fragt Caddy vor jedem Zugriff bei authentik nach, ob der Benutzer angemeldet und berechtigt ist. So lassen sich auch Anwendungen ohne eigene Benutzerverwaltung mit SSO und MFA schützen – im Walkthrough Grafana.

In authentik

Applications → Create with Provider: Name Grafana, Provider-Typ Proxy Provider im Modus Forward auth (single application), External host https://grafana.example.com.
Die Anwendung dem Embedded Outpost zuweisen (Applications → Outposts).
Zugriff über Policy / Group / User Bindings auf die gewünschte Gruppe beschränken.

In Caddy

General Settings (advanced mode), Bereich Forward Auth: Forward Auth Provider Authentik, Protocol http:// bzw. https://, Forward Auth Domain = authentik-Server (z. B. 192.168.10.60), Forward Auth Port 9000 (HTTP) bzw. 9443, Forward Auth URI /outpost.goauthentik.io/auth/caddy. Speichern.
Domain grafana.example.com und Handler zu http://192.168.10.40:3000 anlegen; im Handler (advanced mode) Forward Auth aktivieren.
Apply.

Das Plugin ergänzt automatisch die nötige Weiterleitung von /outpost.goauthentik.io/* an authentik und übergibt die authentik-Header (Benutzername, Gruppen, E-Mail) an die Anwendung. Auf derselben Domain sollten dann keine Access Lists oder Basic Auth zusätzlich gesetzt werden.

Schritt 8: Kontrolle und Diagnose

Services → Caddy → Diagnostics zeigt das erzeugte Caddyfile und die JSON-Konfiguration – ideal, um zu prüfen, was die Oberfläche tatsächlich konfiguriert hat.
Log File für Zertifikatsausstellung, Fehler bei Upstreams und Startprobleme; für Detailanalysen in den Log Settings das Log-Level erhöhen.
Das Dashboard-Widget zeigt Domains und Gültigkeit der Zertifikate.

Fortgeschrittene Funktionen

Mehrere Handler pro Domain

Pro Domain können mehrere Handler mit unterschiedlichen Pfaden angelegt werden, z. B. /api/* an einen anderen Server als der Rest. Handler ohne Pfad werden automatisch zuletzt ausgewertet. Mit handle_path wird der Pfad vor der Weiterleitung entfernt, mit handle bleibt er erhalten. Access Lists und Basic Auth lassen sich auch pro Handler setzen – etwa um nur /admin/* auf interne Netze zu beschränken.

Lastverteilung und Health Checks

Werden in einem Handler mehrere Upstream Domains eingetragen, verteilt Caddy die Last. Passive und aktive Health Checks nehmen ausgefallene Server automatisch aus der Verteilung.

Header anpassen (vHosts)

Erwartet ein interner Webserver einen anderen Hostnamen, unter Reverse Proxy → Headers einen Eintrag header_up Host {upstream_hostport} anlegen und im Handler auswählen.

ACME-Challenge an interne Server durchreichen

Braucht eine Anwendung hinter Caddy ein eigenes Zertifikat (HTTP-01), in der Domain (advanced mode) unter HTTP-01 Challenge Redirection die IP des internen Servers eintragen. Caddy nutzt dann selbst TLS-ALPN-01 und reicht die HTTP-01-Challenge durch.

Layer4-Proxy

Nach Aktivieren von Enable Layer4 Proxy kann Caddy unter Services → Caddy → Layer4 Proxy auch Nicht-HTTP-Verkehr weiterleiten:

listener_wrappers: Auf Port 443 wird z. B. SSH erkannt und an einen Server weitergeleitet, während HTTPS weiter beim Reverse Proxy landet.
global: Beliebige freie TCP/UDP-Ports, optional mit Protokollerkennung (TLS mit SNI, RDP, SSH, OpenVPN, WireGuard, DNS u. a.) – z. B. TLS-Durchleitung ohne Entschlüsselung an einen Server, der sein Zertifikat selbst verwaltet.

Der Layer4-Proxy ist für fortgeschrittene Szenarien gedacht und sollte bei Problemen zuerst deaktiviert werden.

CrowdSec-Anbindung

Caddy bietet keine Web Application Firewall, lässt sich aber mit CrowdSec (Plugin os-crowdsec) kombinieren, das anhand der Zugriffslogs bekannte Angreifer-IPs sperrt. Einrichtung, Funktionsweise und weitere Möglichkeiten von CrowdSec beschreibt der Artikel OPNsense - CrowdSec. Für Caddy genügen folgende Schritte:

General Settings → Log Settings: Log HTTP Access in JSON Format aktivieren, in jeder überwachten Domain unter Access HTTP Access Log einschalten.
Per SSH die CrowdSec-Collection installieren und die Logquelle eintragen:

cscli collections install crowdsecurity/caddy
cat > /usr/local/etc/crowdsec/acquis.d/caddy.yaml <<'EOF'
filenames:
  - /var/log/caddy/access/*.log
force_inotify: true
poll_without_inotify: true
labels:
  type: caddy
EOF

CrowdSec in der Weboberfläche neu starten.

Hochverfügbarkeit (CARP)

Bei zwei Firewalls mit CARP muss auch die Backup-Firewall Zertifikate erhalten. Möglich sind eigene Zertifikate aus System → Trust, die DNS-01 Challenge oder die HTTP-01 Challenge Redirection auf die Sync-Adresse der Backup-Firewall – jeweils mit Synchronisation per XMLRPC.

Caddy ohne Root-Rechte

Unter General Settings → Advanced Settings kann Caddy als Benutzer www laufen. Dann sind nur Ports ab 1024 möglich (z. B. 8080/8443); die Standardports werden per Destination NAT dorthin weitergeleitet.

Typische Probleme und Lösungen

Symptom	Ursache und Lösung
Caddy startet nicht, Port belegt	Weboberfläche oder ein anderes Plugin nutzt noch Port 80/443 – Schritt 1 prüfen.
Kein Zertifikat, Fehler im Log	A/AAAA-Record fehlt oder zeigt woanders hin; WAN-Regel für Port 80/443 fehlt; bei IPv6 ohne globale Adresse auf dem WAN schlägt TLS-ALPN-01 fehl.
Fehler 502 Bad Gateway	Upstream nicht erreichbar oder falsches Protokoll (http/https) bzw. Port im Handler.
Upstream-HTTPS-Fehler	Zertifikat des internen Servers nicht vertrauenswürdig – TLS Trust Pool + TLS Server Name setzen oder (intern) TLS Insecure Skip Verify.
Anwendung erzeugt falsche Links/Umleitungen	Anwendung kennt den Proxy nicht – Trusted Proxy, Base URL bzw. `overwriteprotocol` in der Anwendung setzen.
Internes ACME der Anwendung scheitert	Caddy fängt `/.well-known/acme-challenge` ab – HTTP-01 Challenge Redirection nutzen.
Echte Client-IP fehlt (hinter Cloudflare)	Trusted Proxies auf die Cloudflare-Netze und Client IP Headers auf `Cf-Connecting-Ip` setzen.

Sicherheitsempfehlungen

Nur veröffentlichen, was nötig ist – interne Dienste per Access List auf interne Netze/VPN beschränken.
Anwendungen ohne starke Anmeldung per Forward Auth (authentik mit MFA) oder mTLS schützen; Basic Auth nur als einfache Zusatzhürde.
Anwendungen aktuell halten – der Reverse Proxy schützt nicht vor Schwachstellen der Anwendung; dafür ist eine WAF (OPNWAF) oder zumindest CrowdSec sinnvoll.
Port 80 schließen, wenn Anwendungen Cookies ohne Secure-Flag setzen und keine HTTP-01-Challenge benötigt wird (dann DNS-01 nutzen).
Logs auswerten: Zugriffslogs (JSON) an ein SIEM weiterleiten, z. B. ein Open-Source-SIEM auf Wazuh-Basis.

Fazit

Mit os-caddy wird die OPNsense zum komfortablen Reverse Proxy: Domain anlegen, Handler definieren, fertig – die Zertifikate kümmern sich um sich selbst. Access Lists, Basic Auth, mTLS und Forward Auth mit authentik bieten abgestufte Schutzmöglichkeiten, und für Spezialfälle stehen Wildcard-Zertifikate, Lastverteilung, Layer4-Routing und CrowdSec bereit. Für die Veröffentlichung interner Webdienste in kleinen und mittleren Unternehmen ist Caddy damit eine der elegantesten Lösungen auf der OPNsense.

Unterstützung von m.a.x. it

Sie möchten interne Webanwendungen sicher veröffentlichen, Single Sign-On mit authentik vorschalten oder Ihren Reverse Proxy um eine Web Application Firewall ergänzen? m.a.x. it unterstützt Sie als OPNsense-Gold-Partner mit OPNsense-Firewall-Services von m.a.x. it und einer Managed Firewall von m.a.x. it.

Siehe auch

Links und Quellen

Über m.a.x. it Die m.a.x. Informationstechnologie AG ist seit über 30 Jahren IT-Partner mittelständischer und großer Unternehmen in München und bietet maßgeschneiderte Lösungen und Services in den Bereichen Cloud, Cybersecurity, Netzwerk, Windows, Linux und Softwareentwicklung. Sie haben eine Frage zu diesem Artikel oder brauchen Unterstützung? Kontakt aufnehmen

Anonym

Suche