imported>TechCorner-Redaktion: Verlinkung auf den Artikel OPNsense - ACME-Client für Let's Encrypt-Zertifikate ergänzt

2026-10-08T00:00:00Z

Verlinkung auf den Artikel OPNsense - ACME-Client für Let's Encrypt-Zertifikate ergänzt

Neue Seite

{{Steckbrief
| gilt_fuer = OPNsense 26.1/26.7 mit Plugin os-nginx 1.36, os-acme-client
| bereich = IT-Security
| dauer = ca. 45 Minuten (erste Veröffentlichung), Walkthrough inkl. WAF ca. 3 Stunden plus Lernphase
| rechte = Administrator (OPNsense-WebUI), Zugriff auf die öffentliche DNS-Zone
| stand = Oktober 2026
}}
'''NGINX''' ist einer der meistgenutzten Webserver und '''[[Reverse Proxy|Reverse Proxys]]''' der Welt. Das Plugin '''os-nginx''' bringt ihn auf die OPNsense – mit einem Funktionsumfang, der über einen reinen Proxy deutlich hinausgeht: Lastverteilung, Caching, IP-Zugriffslisten, Basic Auth, Client-Zertifikate, Sicherheits-Header, automatische Sperre von Angreifern und vor allem eine integrierte '''[[Web Application Firewall]] (WAF)''' auf Basis von '''NAXSI'''. Zusätzlich kann NGINX TCP- und UDP-Datenströme weiterleiten und anhand des TLS-Servernamens (SNI) verteilen.

Dieser Artikel stellt die Bausteine des Plugins vor und führt in einem '''Walkthrough''' von der ersten Veröffentlichung bis zur WAF.

== Wann NGINX auf der OPNsense? ==
* Wenn eine '''WAF''' gegen SQL-Injection und Cross-Site-Scripting vor einer Webanwendung gewünscht ist – ohne kommerzielle Lizenz.
* Wenn '''Caching''', '''Sicherheits-Header''' oder '''Bot-/Angreifersperren''' direkt am Proxy umgesetzt werden sollen.
* Wenn neben HTTP auch '''TCP/UDP-Streams''' und '''SNI-basiertes Routing''' benötigt werden.
Für die einfache Veröffentlichung mit automatischem HTTPS ist [[OPNsense - Caddy Reverse Proxy|Caddy]] bequemer, für komplexe Lastverteilung [[OPNsense - HAProxy Reverse Proxy und Load Balancer|HAProxy]].

== Die Bausteine des Plugins ==
Die Konfiguration befindet sich unter '''Services → Nginx → Configuration''' und ist in Reiter gegliedert:
{| class="wikitable"
! Bereich !! Element !! Aufgabe
|-
| '''Upstream''' || Upstream Server || Ein einzelner Zielserver (IP/Name, Port, Priorität)
|-
| || Upstream || Gruppe von Upstream Servern mit Lastverteilung und TLS-Einstellungen zum Backend
|-
| '''HTTP(S)''' || Location || Ordnet URL-Pfade einem Upstream (oder Verzeichnis) zu – inkl. WAF, Auth, Caching
|-
| || HTTP Server || Der eigentliche virtuelle Host: Server Name, Ports, Zertifikat, Locations, Sicherheitseinstellungen
|-
| || Naxsi WAF Policy / Rule || Regeln und Richtlinien der Web Application Firewall
|-
| || Security Headers, Error Pages, Cache Path, URL Rewriting || Zusatzfunktionen für HTTP Server und Locations
|-
| '''Access''' || IP ACLs, User List, Credential, Limit Zone, Connection Limits || Zugriffssteuerung und Begrenzungen
|-
| '''Data Streams''' || Stream Servers, SNI Based Routing || TCP/UDP-Weiterleitung, Routing nach SNI
|}
Weitere Menüpunkte: '''Banned''' (automatisch gesperrte IPs), '''TLS Fingerprints''', '''Traffic Statistic''' sowie die Logs für HTTP- und Stream-Zugriffe und -Fehler.

[[Datei:OPNsense-NGINX-Walkthrough.png|thumb|center|750px|Aufbau in NGINX: Upstream Server werden zu einem Upstream gruppiert, eine Location ordnet Pfade dem Upstream zu und aktiviert WAF und Zugriffsschutz, der HTTP Server bündelt Domain, Zertifikat und Locations.]]

== Das Walkthrough-Szenario ==
{| class="wikitable"
! Domain !! Ziel !! Schutz
|-
| <code>portal.example.com</code> || Webanwendung auf <code>192.168.10.70:8080</code> || öffentlich, '''NAXSI-WAF''', Sicherheits-Header, Honeypot
|-
| <code>intern.example.com</code> || Intranet auf <code>https://192.168.10.50</code> || nur interne Netze (IP ACL) + Basic Auth
|}

== Schritt 1: Vorbereitung ==
# '''System → Firmware → Plugins''': '''os-nginx''' und '''os-acme-client''' installieren.
# '''System → Settings → Administration''': '''TCP Port''' der Weboberfläche z. B. auf <code>8443</code> ändern und '''HTTP Redirect – Disable web GUI redirect rule''' aktivieren.
# Öffentliche A-/AAAA-Records für beide Domains auf die WAN-Adresse setzen.
# '''Firewall → Rules''', Interface ''WAN'' (und ''LAN''): TCP 80 und 443 von ''any'' auf ''This Firewall''. Eine Portweiterleitung ist nicht nötig – NGINX läuft direkt auf der Firewall.

== Schritt 2: Zertifikate ==
Das Plugin besorgt keine Zertifikate selbst, arbeitet aber mit '''[[OPNsense - ACME-Client für Let's Encrypt-Zertifikate|os-acme-client]]''' zusammen:
* '''HTTP-01:''' Im HTTP Server die Option '''Enable Let's Encrypt Plugin Support''' aktivieren – NGINX reicht dann die ACME-Challenges an den ACME-Client weiter.
* '''DNS-01:''' Unabhängig vom Webserver und auch für Wildcard-Zertifikate geeignet (API des DNS-Anbieters im ACME-Client hinterlegen).
Im ACME-Client unter ''Automations'' einen '''Neustart von NGINX''' nach jeder Erneuerung hinterlegen. Die Zertifikate erscheinen anschließend unter ''System → Trust → Certificates'' und lassen sich im HTTP Server auswählen.

== Schritt 3: Upstream Server und Upstream ==
=== Upstream Server ===
'''Upstream → Upstream Server''' → '''+''':
* '''Description:''' <code>portal1</code>, '''Server:''' <code>192.168.10.70</code>, '''Port:''' <code>8080</code>, '''Server Priority:''' <code>1</code>
* Für das Intranet entsprechend <code>intranet1</code> mit <code>192.168.10.50</code>, Port <code>443</code>.
''Maximum Failures'' und ''Fail Timeout'' steuern, wann ein Server vorübergehend aus der Verteilung genommen wird.

=== Upstream ===
'''Upstream → Upstream''' → '''+''':
{| class="wikitable"
! Feld !! up_portal !! up_intranet
|-
| Server Entries || portal1 (weitere für Lastverteilung) || intranet1
|-
| Load Balancing Algorithm || Weighted Round Robin (Standard) oder IP Hash || Standard
|-
| Enable TLS (HTTPS) || aus (Backend spricht HTTP) || '''an'''
|-
| TLS: Verify Certificate || – || an, mit '''TLS: Trusted Certificate''' (interne CA) und '''TLS: Servername override''' = Name im Zertifikat
|}
{{Hinweis|Die Zertifikatsprüfung zum Backend ist standardmäßig aktiv. Damit sie gelingt, muss die OPNsense der ausstellenden CA vertrauen (CA unter ''System → Trust → Authorities'' importieren) und der Servername muss passen. Nur in vertrauenswürdigen Netzen und bewusst die Prüfung deaktivieren.}}

== Schritt 4: Locations ==
'''HTTP(S) → Location''' → '''+''':
{| class="wikitable"
! Feld !! loc_portal !! loc_intranet
|-
| URL Pattern || <code>/</code> || <code>/</code>
|-
| Match Type || leer (Präfix-Abgleich) || leer
|-
| Upstream Servers || up_portal || up_intranet
|-
| Force HTTPS || an || an
|-
| WebSocket Support || bei Bedarf || –
|-
| Enable Security Rules (WAF) || zunächst aus (Schritt 7) || –
|-
| Basic Authentication / Basic Credentials List || – || an / Benutzerliste (Schritt 6)
|-
| IP ACL || – || ''nur_intern'' (Schritt 6)
|}

== Schritt 5: HTTP Server ==
'''HTTP(S) → HTTP Server''' → '''+''' (je ein Server pro Domain):
{| class="wikitable"
! Feld !! Wert (portal.example.com)
|-
| HTTP Listen Address / HTTPS Listen Address || <code>80</code> / <code>443</code>
|-
| Server Name || <code>portal.example.com</code>
|-
| Locations || loc_portal
|-
| TLS Certificate || das ACME-Zertifikat
|-
| Enable Let's Encrypt Plugin Support || an (bei HTTP-01)
|-
| HTTPS Only || an
|-
| HTTP/2 || an; HTTP/3 (QUIC) optional (dann UDP 443 freigeben)
|-
| TLS Protocols || TLSv1.2, TLSv1.3
|-
| Block Configuration Files || an
|-
| Security Header || Richtlinie aus Schritt 8
|-
| Default Server || bei genau einem Server als Fallback, sonst einen eigenen „Catch-all“-Server anlegen
|}
Anschließend unten auf '''Apply''' klicken. Über '''Config Preview''' lässt sich die erzeugte NGINX-Konfiguration ansehen und testen. Danach <code><nowiki>https://portal.example.com</nowiki></code> aufrufen.

== Schritt 6: Zugriff beschränken (IP ACL und Basic Auth) ==
=== IP ACL ===
'''Access → IP ACLs''' → '''+''': Name ''nur_intern'', Einträge <code>192.168.0.0/16</code>, <code>172.16.0.0/12</code>, <code>10.0.0.0/8</code> (ggf. VPN-Netz) mit ''allow'', Standardaktion ''deny''. Die ACL in der Location ''loc_intranet'' (oder im HTTP Server) auswählen.

=== Basic Auth ===
# '''Access → Credential''': Benutzer mit Passwort anlegen.
# '''Access → User List''': Benutzer zu einer Liste zusammenfassen.
# In der Location '''Basic Authentication''' aktivieren und die Liste unter '''Basic Credentials List''' wählen.
Mit '''Satisfy''' ''any'' genügt wahlweise IP oder Passwort, mit ''all'' müssen beide Bedingungen erfüllt sein.

=== Client-Zertifikate (mTLS) ===
Für Maschine-zu-Maschine-Zugriffe oder besonders schützenswerte Dienste im HTTP Server unter '''Client CA Certificate''' die eigene CA wählen und '''Verify Client Certificate''' auf ''on'' setzen – ohne gültiges Client-Zertifikat wird die Verbindung abgewiesen.

== Schritt 7: Web Application Firewall (NAXSI) ==
'''NAXSI''' prüft Anfragen auf typische Angriffsmuster (SQL-Injection, Cross-Site-Scripting, Directory Traversal) und vergibt Punkte; überschreitet eine Anfrage die Schwelle, wird sie blockiert.
# '''Regeln laden:''' In der Plugin-Oberfläche die Schaltfläche '''Download NAXSI Rules''' wählen und der Lizenz der NAXSI-Kernregeln zustimmen (sie dürfen aus Lizenzgründen nicht direkt mitgeliefert werden).
# '''In der Location aktivieren:''' In ''loc_portal'' '''Enable Security Rules''' und zunächst '''Learning Mode''' einschalten. Die Schwellen '''Block XSS Score''' und '''Block SQL Injection Score''' auf Standardwerten belassen.
# '''Lernphase:''' Die Anwendung einige Tage normal nutzen. Unter ''Logs / HTTP Error'' erscheinen Regelverletzungen, die im Lernmodus nur protokolliert werden.
# '''Fehlalarme ausnehmen:''' Für legitime Treffer unter ''HTTP(S) → Naxsi WAF Rule'' Ausnahmen (Whitelist-Regeln für bestimmte Regel-IDs, Parameter oder Pfade) anlegen, zu einer ''Naxsi WAF Policy'' zusammenfassen und in der Location als ''Custom Security Policy'' auswählen.
# '''Scharf schalten:''' Learning Mode deaktivieren. Blockierte Anfragen erhalten die unter ''Violation Error Page'' gewählte Fehlerseite.
{{Hinweis|Eine WAF ersetzt keine sichere Anwendung und keine Updates. Ohne Lernphase drohen Fehlalarme, die legitime Nutzer aussperren – besonders bei Anwendungen mit komplexen Formularen oder APIs. Unter ''Naxsi Trusted Source IPs'' im HTTP Server lassen sich z. B. interne Prüfsysteme von der WAF ausnehmen.}}

== Schritt 8: Sicherheits-Header, Bot-Schutz und automatische Sperren ==
* '''Security Headers''' (''HTTP(S) → Security Headers''): Richtlinie mit '''HSTS''', '''Content-Security-Policy''', ''X-Content-Type-Options'', ''X-Frame-Options'' und ''Referrer-Policy'' anlegen und im HTTP Server auswählen. Die CSP vorsichtig einführen und mit den Browser-Entwicklertools testen.
* '''Bot-Schutz:''' Bekannte Bot- und Scanner-User-Agents werden standardmäßig blockiert (abschaltbar über ''Disable Bot Protection'').
* '''Honeypot''' (advanced mode): In einer eigenen Location für einen Köderpfad (z. B. <code>/wp-admin</code> oder <code>/phpmyadmin</code> auf einer Seite, die diese nicht nutzt) '''Honeypot''' aktivieren. Wer den Pfad aufruft, landet in einem besonderen Log und als Adresse in einem '''Firewall-Alias''' – unter ''Firewall → Rules'' auf dem WAN eine Block-Regel mit diesem Alias als Quelle anlegen, damit die Sperre greift. Die erfassten Adressen zeigt '''Services → Nginx → Banned'''. Vorsicht: Auch Suchmaschinen oder Nutzer können versehentlich gesperrt werden.
* '''Limit Requests''' (''Access → Limit Zone'' und ''Connection Limits''): Anfragen pro IP begrenzen, z. B. für Login-Seiten.

== Weitere Funktionen ==
=== Caching ===
Mit einem '''Cache Path''' (''HTTP(S) → Cache Path'') und den Cache-Optionen in der Location speichert NGINX Antworten zwischen – entlastet langsame Backends und beschleunigt statische Inhalte. Über ''Response Code Caching'' wird festgelegt, welche Antworten wie lange gecacht werden.

=== TCP/UDP-Streams und SNI-Routing ===
Unter '''Data Streams''':
* '''Stream Servers''' leiten TCP- oder UDP-Dienste an Upstreams weiter (z. B. DNS, proprietäre Protokolle) – optional mit TLS-Terminierung.
* '''SNI Based Routing''' verteilt TLS-Verbindungen anhand des Servernamens im Handshake an verschiedene Upstreams, '''ohne''' sie zu entschlüsseln – ideal, wenn Server ihre Zertifikate selbst verwalten.
Protokolle mit Zusatzverbindungen wie FTP oder SIP funktionieren nicht.

=== Statistik und Logs ===
'''Traffic Statistic''' zeigt Anfragen, Antwortcodes und Datenvolumen pro Server und Upstream; die HTTP-Zugriffs- und Fehlerlogs lassen sich direkt in der Oberfläche filtern und per ''SYSLOG Targets'' an externe Systeme senden.

== Typische Probleme und Lösungen ==
{| class="wikitable"
! Symptom !! Ursache und Lösung
|-
| NGINX startet nicht, Port belegt || Weboberfläche nutzt noch Port 80/443 – Schritt 1; ''Config Preview'' zeigt Syntaxfehler.
|-
| 502 Bad Gateway || Backend nicht erreichbar, falscher Port oder TLS-Prüfung zum Backend schlägt fehl (CA/Servername prüfen).
|-
| Falsche Seite/Zertifikat für eine Domain || Server Name falsch oder anderer HTTP Server ist ''Default Server''.
|-
| Legitime Anfragen werden blockiert || WAF ohne Lernphase scharfgeschaltet – Learning Mode aktivieren, Treffer im Error-Log auswerten, Whitelist-Regeln anlegen.
|-
| Eigene IP wurde gesperrt || Unter ''Banned'' entsperren; Honeypot-Pfad und Ratenbegrenzung prüfen.
|-
| Zertifikat wird nicht erneuert || ''Enable Let's Encrypt Plugin Support'' im HTTP Server fehlt oder Automation zum Neustart nicht hinterlegt.
|}

== Sicherheitsempfehlungen ==
* '''WAF mit Lernphase''' für öffentlich erreichbare Anwendungen einsetzen, interne Oberflächen per IP ACL/mTLS schützen.
* '''TLS 1.2/1.3''', HSTS und Sicherheits-Header konsequent nutzen.
* '''Backend-Zertifikate prüfen''' statt die Verifizierung abzuschalten.
* '''Logs zentral auswerten''' (WAF-Treffer, Sperren, Fehler), z. B. in einem [https://www.max-it.de/it-services/siem-open-source/ Open-Source-SIEM auf Wazuh-Basis].
* '''Plugin und Anwendungen aktuell halten''' – auch NAXSI-Regeln regelmäßig neu laden.

== Fazit ==
Das NGINX-Plugin ist der funktionsreichste Reverse Proxy auf der OPNsense: Mit Upstreams, Locations und HTTP Servern ist die Grundstruktur schnell aufgebaut, und darauf setzen WAF, Sicherheits-Header, Honeypot, Ratenbegrenzung, Caching und Stream-Routing auf. Wer eine Web Application Firewall ohne Zusatzlizenz benötigt und bereit ist, eine Lernphase einzuplanen, findet in os-nginx eine sehr gute Lösung.

== Unterstützung von m.a.x. it ==
Sie möchten Webanwendungen mit einer Web Application Firewall schützen, die Lernphase von NAXSI begleiten lassen oder Ihre Reverse-Proxy-Landschaft auf der OPNsense neu aufstellen? m.a.x. it unterstützt Sie als OPNsense-Gold-Partner mit [https://www.max-it.de/it-services/opnsense/ OPNsense-Firewall-Services von m.a.x. it] und [https://www.max-it.de/it-services/cybersecurity/ Cybersecurity-Leistungen von m.a.x. it].

== Siehe auch ==
* [[OPNsense - ACME-Client für Let's Encrypt-Zertifikate]]
* [[OPNsense - Caddy Reverse Proxy]]
* [[OPNsense - HAProxy Reverse Proxy und Load Balancer]]
* [[OPNsense - HAProxy mit Passwortauthentifizierung]]
* [[OPNsense - Plugin-Liste]]
* [[Reverse Proxy]]
* [[Web Application Firewall]]
* [[Let's Encrypt]]
* [[HTTP/3]]

== Links und Quellen ==
* [https://docs.opnsense.org/manual/how-tos/nginx.html OPNsense-Doku – nginx (Einstieg und Unterseiten zu WAF, IP ACL, TLS-Auth, Streams, Header)]
* [https://docs.opnsense.org/manual/how-tos/nginx_waf.html OPNsense-Doku – nginx Web Application Firewall]
* [https://nginx.org/en/docs/ NGINX – offizielle Dokumentation]
* [https://github.com/opnsense/plugins/tree/master/www/nginx Quellcode und Changelog des Plugins os-nginx]
* [https://www.max-it.de/it-services/opnsense/ m.a.x. it – OPNsense-Firewall-Services]

{{Uebermax}}
[[Kategorie:IT-Security]]

OPNsense - NGINX Reverse Proxy und WAF - Versionsgeschichte

imported>TechCorner-Redaktion: Verlinkung auf den Artikel OPNsense - ACME-Client für Let's Encrypt-Zertifikate ergänzt