OPNsense - HAProxy Reverse Proxy und Load Balancer

Auf einen Blick

Gilt für	OPNsense 26.1/26.7 mit Plugin os-haproxy 5.1 (HAProxy 3.2), os-acme-client
Bereich	IT-Security
Dauer	ca. 45 Minuten (erste Veröffentlichung), Walkthrough komplett ca. 2–3 Stunden
Rechte	Administrator (OPNsense-WebUI), Zugriff auf die öffentliche DNS-Zone
Stand	Oktober 2026

HAProxy ist einer der bekanntesten Open-Source-Load-Balancer und Reverse Proxys – eingesetzt von großen Webplattformen und Cloud-Anbietern. Mit dem Plugin os-haproxy steht der volle Funktionsumfang auf der OPNsense zur Verfügung: SSL-Offloading, Lastverteilung auf mehrere Server, Health Checks, Sitzungsbindung, regelbasierte Weiterleitung nach Domain oder Pfad, Ratenbegrenzung, Statistik und Wartungsmodus. Die Einarbeitung ist anspruchsvoller als bei Caddy, dafür ist HAProxy außerordentlich flexibel und leistungsfähig.

Dieser Artikel erklärt die Begriffe des Plugins und führt in einem Walkthrough durch eine typische Unternehmenskonfiguration.

HAProxy, Caddy oder NGINX?

Kriterium	HAProxy	Caddy	NGINX
Stärke	Lastverteilung, Health Checks, Regeln, Hochlast	Einfachheit, automatisches HTTPS	Webserver + Proxy, integrierte WAF (NAXSI)
Zertifikate	über os-acme-client (mit HAProxy-Integration)	automatisch integriert	über os-acme-client
Lernkurve	hoch	niedrig	mittel
Typischer Einsatz	mehrere Server pro Dienst, Hochverfügbarkeit, komplexe Weiterleitungslogik	Veröffentlichung einzelner Webdienste	Webdienste mit WAF-Bedarf, Streams

Die Bausteine des Plugins

HAProxy wird unter Services → HAProxy → Settings konfiguriert. Die Oberfläche ordnet die HAProxy-Begriffe so:

Reiter (Plugin)	HAProxy-Begriff	Aufgabe
Real Servers	server	Die tatsächlichen Server (IP/FQDN und Port), an die weitergeleitet wird
Virtual Services → Backend Pools	backend	Gruppe von Servern für denselben Dienst – mit Lastverteilung, Health Check und Persistenz. Auch bei nur einem Server erforderlich.
Virtual Services → Public Services	frontend	Lauscht auf Adresse/Port, terminiert TLS und leitet an einen Backend Pool weiter
Rules & Checks → Health Monitors	health check	Prüft, ob Server antworten (HTTP, TCP, LDAP, SMTP, SQL u. a.)
Rules & Checks → Conditions	ACL	Bedingungen, z. B. „Host-Header ist cloud.example.com“
Rules & Checks → Rules	http-request / use_backend …	Aktionen, wenn Bedingungen zutreffen, z. B. „verwende Backend Pool X“
User Management	userlist	Benutzer und Gruppen für Basic Auth
Settings	global / defaults	Dienst aktivieren, globale und Standardparameter, Logging, Statistik, Cache, Peers

Reihenfolge der Einrichtung laut Plugin: Real Servers → Backend Pools → Public Services → Dienst aktivieren – und die Firewall-Regeln manuell anlegen.

Datei:OPNsense-HAProxy-Walkthrough.png

Walkthrough-Szenario: Ein HTTPS-Frontend auf der OPNsense verteilt Anfragen nach Host-Header auf zwei Backend Pools – den Shop mit zwei Servern (Lastverteilung, Health Checks) und Nextcloud. Ein zweites Frontend auf Port 80 leitet auf HTTPS um und reicht ACME-Challenges durch.

Das Walkthrough-Szenario

Domain	Backend Pool	Server
`shop.example.com`	pool_shop (Round Robin, Health Check, Sitzungsbindung)	`192.168.20.11:80`, `192.168.20.12:80`
`cloud.example.com`	pool_cloud	`192.168.10.30:80`

Ein Zertifikat mit beiden Namen (oder ein Wildcard-Zertifikat) wird per os-acme-client bezogen.

Schritt 1: Vorbereitung

Plugins installieren

System → Firmware → Plugins: os-haproxy und os-acme-client installieren.

Ports 80 und 443 freimachen

System → Settings → Administration: TCP Port der Weboberfläche z. B. auf 8443 ändern und HTTP Redirect – Disable web GUI redirect rule aktivieren.
Speichern und die Weboberfläche künftig über Port 8443 aufrufen.

DNS und Firewall

Öffentliche A-/AAAA-Records für shop.example.com und cloud.example.com auf die WAN-Adresse.
Firewall → Rules, Interface WAN (und ggf. LAN): TCP 80 und 443 von any auf This Firewall erlauben. HAProxy legt keine Regeln automatisch an.

Schritt 2: Zertifikat mit os-acme-client

Services → ACME Client:

Unter Accounts ein Konto bei Let’s Encrypt anlegen.
Unter Challenge Types den Typ HTTP-01 anlegen und die HAProxy-Integration aktivieren (Auswahl des HAProxy-Frontends, das die Challenge beantwortet) – alternativ DNS-01 mit der API des DNS-Anbieters, dann ist auch ein Wildcard-Zertifikat möglich.
Unter Certificates ein Zertifikat für shop.example.com mit Alt Name cloud.example.com anlegen und unter Automations einen Neustart bzw. Reload von HAProxy nach Erneuerung hinterlegen.

Die HTTP-01-Integration funktioniert erst, wenn das HTTP-Frontend aus Schritt 5 existiert – bei HTTP-01 daher Schritt 5 zuerst einrichten oder DNS-01 wählen.

Schritt 3: Real Servers

Real Servers → +, für jeden Server:

Feld	shop1	shop2	cloud1
Name or Prefix	`shop1`	`shop2`	`cloud1`
Type	static	static	static
FQDN or IP	`192.168.20.11`	`192.168.20.12`	`192.168.10.30`
Port	`80`	`80`	`80`
SSL	aus (Backend spricht HTTP)	aus	aus

Spricht ein Server selbst HTTPS, SSL aktivieren und entweder Verify SSL Certificate mit passender CA (SSL Verify CA) nutzen oder – nur in vertrauenswürdigen Netzen – die Prüfung deaktivieren.

Schritt 4: Health Monitor und Backend Pools

Health Monitor

Rules & Checks → Health Monitors → +: Name hc_http, Type HTTP, Methode GET, Request URI z. B. / oder ein eigener Status-Pfad, Check Interval 2s.

Backend Pools

Virtual Services → Backend Pools → +:

Feld	pool_shop	pool_cloud
Mode	HTTP (Layer 7)	HTTP (Layer 7)
Balancing Algorithm	Round Robin	Source-IP Hash (Standard)
Servers	shop1, shop2	cloud1
Enable Health Checking / Health Monitor	aktiv / hc_http	aktiv / hc_http
X-Forwarded-For header	aktiv	aktiv
Persistence type	Cookie-based persistence (Cookie SRVID) – Shop-Sitzungen bleiben auf einem Server	–

Fällt ein Shop-Server aus, nimmt der Health Check ihn automatisch aus der Verteilung und fügt ihn nach Wiederherstellung wieder hinzu.

Schritt 5: Public Services (Frontends)

HTTPS-Frontend

Virtual Services → Public Services → +:

Feld	Wert
Name	`fe_https`
Listen Addresses	`0.0.0.0:443` (bzw. `WAN-IP:443`; für IPv6 zusätzlich `[::]:443`)
Type	HTTP / HTTPS (SSL offloading)
Default Backend Pool	leer (die Zuordnung übernehmen Regeln) oder ein Standard-Pool
Enable SSL offloading	aktiv
Certificates / Default certificate	das ACME-Zertifikat
Minimum SSL Version	TLSv1.2 (Advanced SSL settings)
Enable HSTS	nach erfolgreichem Test aktivieren
Enable HTTP/2	aktiv (Standard)
Select Rules	rule_shop, rule_cloud (Schritt 6)

HTTP-Frontend für Umleitung und ACME

Zweites Public Service fe_http: Listen Address 0.0.0.0:80, Type HTTP / HTTPS (SSL offloading) ohne SSL. Als Regel eine http-request-Umleitung auf HTTPS (Aktion redirect, scheme https, Code 301) hinterlegen. Bei HTTP-01 fügt der ACME-Client die Challenge-Weiterleitung über seine HAProxy-Integration selbst hinzu.

Schritt 6: Conditions und Rules

Conditions

Rules & Checks → Conditions → +:

cond_shop: Condition type hdr – HTTP Host Header matches, Wert shop.example.com
cond_cloud: Condition type hdr – HTTP Host Header matches, Wert cloud.example.com

Rules

Rules & Checks → Rules → +:

rule_shop: Select conditions cond_shop, Rule type Use specified Backend Pool, Use backend pool pool_shop
rule_cloud: entsprechend mit cond_cloud → pool_cloud

Die Regeln im HTTPS-Frontend unter Select Rules auswählen.

HinweisBei vielen Domains ist eine Map File (Advanced → Map Files) übersichtlicher: eine Liste Domain → Backend Pool und eine einzige Regel vom Typ Map domains to backend pools using a map file.

Schritt 7: Aktivieren, testen, anwenden

Settings → Service Settings: Enable HAProxy aktivieren.
Unten auf Test syntax klicken – HAProxy prüft die Konfiguration vor dem Anwenden und zeigt Fehler sowie eine Konfigurations-Diff.
Apply.
https://shop.example.com und https://cloud.example.com aufrufen.
Unter Services → HAProxy → Statistics (Reiter Status) prüfen, ob alle Server UP sind und wie sich die Last verteilt. Die erzeugte Konfiguration zeigt Services → HAProxy → Config Export.

Weitere Funktionen

Wartungsmodus

Services → HAProxy → Maintenance → Server: Einen Server auf drain (keine neuen Verbindungen) oder maint setzen, um ihn ohne Unterbrechung zu aktualisieren – danach wieder ready.

Zugriff einschränken

Nach IP: Condition vom Typ src – Source IP matches specified IP (z. B. interne Netze, in der Condition negiert) und eine Regel vom Typ http-request mit der Aktion deny, die diese Condition verwendet.
Basic Auth: Benutzer unter User Management anlegen und im Backend Pool bzw. Public Service unter Basic Authentication auswählen – Details im Artikel OPNsense - HAProxy mit Passwortauthentifizierung.
Client-Zertifikate: Im Public Service unter Client Certificate Auth eine CA hinterlegen – nur Clients mit gültigem Zertifikat werden verbunden.

Ratenbegrenzung gegen Brute Force und Bots

Im Public Service eine Stick-table (Table type ipv4, Stored data HTTP request rate, Periode z. B. 10 s) aktivieren und eine Regel http-request deny mit einer Condition auf die Anfragerate (z. B. mehr als 100 Anfragen in 10 s) anlegen. Seit Plugin 5.0 werden alle Stick-Table-Datentypen und Zähler unterstützt; mit silent-drop lassen sich Angreifer ohne Antwort abweisen.

TCP-Modus und SNI-Durchleitung

Sollen Server ihre Zertifikate selbst verwalten (Ende-zu-Ende-TLS), arbeitet das Frontend im Typ SSL / HTTPS (TCP mode). Mit der Condition ssl_sni – SNI TLS extension matches (TCP request content inspection) wird anhand des Servernamens im TLS-Handshake ohne Entschlüsselung an den passenden Backend Pool (Mode TCP) weitergeleitet. Auch beliebige TCP-Dienste (z. B. RDP-Gateways, Datenbanken, LDAP) lassen sich so verteilen.

HTTP/3, Komprimierung und Cache

Seit Plugin 5.0 unterstützt HAProxy HTTP/3 über QUIC im Frontend (dann UDP 443 freigeben), HTTP-Komprimierung per Regel und einen einfachen Cache (Settings → Cache Configuration).

Hochverfügbarkeit

Mit zwei Firewalls (CARP) lauschen beide HAProxy-Instanzen auf der virtuellen IP (dafür unter Settings → Global Parameters das Binden an nicht lokale Adressen erlauben bzw. auf die CARP-Adresse binden). Unter Peers / Session Sync werden Stick-Tables (z. B. Sitzungsbindung, Ratenzähler) zwischen beiden Knoten synchronisiert; die Konfiguration wird per XMLRPC-Sync übertragen.

PROXY-Protokoll

Benötigt ein Backend die echte Client-IP auf TCP-Ebene (z. B. ein zweiter Proxy oder Mailserver), im Backend Pool Proxy Protocol Version 1 oder 2 aktivieren – das Backend muss das Protokoll unterstützen.

Typische Probleme und Lösungen

Symptom	Ursache und Lösung
HAProxy startet nicht, Port belegt	Weboberfläche oder anderer Dienst nutzt Port 80/443 – Schritt 1 prüfen; Test syntax zeigt Details.
503 Service Unavailable	Keine Regel greift (Host-Header falsch geschrieben, kein Default Backend Pool) oder alle Server im Pool sind laut Health Check DOWN.
Server dauerhaft DOWN	Health-Check-URI liefert keinen 2xx/3xx-Status (z. B. Umleitung auf Login) – eigenen Status-Pfad oder TCP-Check verwenden.
Anmeldung in der Webanwendung „springt“	Ohne Persistenz landen Anfragen auf wechselnden Servern – Cookie-basierte Persistenz oder Source-IP Hash nutzen.
Anwendung erzeugt HTTP-Links oder falsche Client-IP	X-Forwarded-For/Forwarded-Header aktivieren und der Anwendung den Proxy als vertrauenswürdig bekannt machen.
Zertifikat wird nicht erneuert	ACME-Challenge erreicht das HTTP-Frontend nicht oder Automation zum HAProxy-Reload fehlt.

Sicherheitsempfehlungen

Nur benötigte Dienste veröffentlichen und interne Oberflächen per IP-Bedingung oder Client-Zertifikat schützen.
TLS 1.2 als Minimum, HSTS nach erfolgreichem Test, moderne Cipher.
Ratenbegrenzung für Login-Seiten und APIs einrichten.
HAProxy ist keine WAF – Webanwendungen aktuell halten und bei Bedarf eine WAF vorschalten.
Logs auswerten: Unter Settings → Logging Configuration detailliertes Logging aktivieren und an ein SIEM weiterleiten, z. B. ein Open-Source-SIEM auf Wazuh-Basis.

Fazit

HAProxy ist auf der OPNsense die erste Wahl, wenn es um mehr als eine einfache Weiterleitung geht: Lastverteilung mit Health Checks, Sitzungsbindung, regelbasiertes Routing, Ratenbegrenzung, Wartungsmodus und Hochverfügbarkeit. Die Einarbeitung lohnt sich – und mit der klaren Reihenfolge Real Servers → Backend Pools → Public Services → Regeln bleibt auch eine große Konfiguration beherrschbar.

Unterstützung von m.a.x. it

Sie möchten Webanwendungen hochverfügbar und lastverteilt bereitstellen oder Ihren bestehenden HAProxy auf der OPNsense optimieren? 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