OPNsense - ACME-Client für Let's Encrypt-Zertifikate
Auf einen Blick
| Gilt für | OPNsense 26.1 und 26.7 mit Plugin os-acme-client 4.17 (acme.sh) |
|---|---|
| Bereich | IT-Security |
| Dauer | ca. 20 Minuten (erstes Zertifikat mit DNS-01) |
| Rechte | Administrator (OPNsense-WebUI), API-Zugang beim DNS-Anbieter |
| Stand | Oktober 2026 (OPNsense 26.7.5, os-acme-client 4.17) |
Der ACME-Client in OPNsense (Plugin os-acme-client) stellt kostenlose, öffentlich vertrauenswürdige TLS-Zertifikate von Let's Encrypt und anderen Zertifizierungsstellen aus und erneuert sie vollautomatisch. Die Zertifikate landen direkt in der Zertifikatsverwaltung der Firewall und können für die Weboberfläche, HAProxy, NGINX, Postfix oder VPN-Dienste genutzt und per Automation sogar auf andere Geräte wie Proxmox, Synology oder FRITZ!Box verteilt werden.
Dieser Artikel zeigt die Einrichtung Schritt für Schritt (Stand Oktober 2026): Konto anlegen, DNS-01-Validierung mit Wildcard-Zertifikat, Automations, Einsatz in der OPNsense – und was die kürzeren Zertifikatslaufzeiten ab 2027 für die Erneuerungseinstellungen bedeuten.
Der ACME-Client in OPNsense im Überblick
Das Plugin basiert auf dem Shell-Client acme.sh und implementiert das ACME-Protokoll vollständig. Nach der Installation unter System → Firmware → Plugins (os-acme-client) erscheint Services → ACME Client mit folgenden Bereichen:
| Menüpunkt | Zweck |
|---|---|
| Settings | Plugin aktivieren, automatische Erneuerung (Cron-Job), HAProxy-Integration, Log-Level |
| Accounts | Konto bei der Zertifizierungsstelle (CA): Let’s Encrypt, ZeroSSL, Google, Buypass, SSL.com oder eigene ACME-CA |
| Challenge Types | Wie der Besitz der Domain nachgewiesen wird: DNS-01, HTTP-01 oder TLS-ALPN-01 |
| Certificates | Die eigentlichen Zertifikate mit Namen, Schlüsseltyp, Laufzeit-Einstellungen und Automations |
| Automations | Aktionen nach Ausstellung/Erneuerung: Dienste neu laden oder Zertifikat auf andere Systeme hochladen |
| Log Files | System Log und ausführliches Acme Log |
Ausgestellte Zertifikate werden automatisch unter System → Trust → Certificates (und die ausstellende CA unter Authorities) abgelegt und stehen damit allen Diensten der Firewall zur Verfügung.
Welcher Challenge Type?
| Challenge Type | Funktionsweise | Wildcard | Einschätzung |
|---|---|---|---|
| DNS-01 (Standard) | Ein TXT-Eintrag _acme-challenge wird per API beim DNS-Anbieter gesetzt |
ja | Empfohlen. Keine offenen Ports nötig, funktioniert auch für interne Namen und hinter NAT. Rund 120 DNS-Anbieter werden unterstützt. |
| HTTP-01 | Die CA ruft http://name/.well-known/acme-challenge/… auf Port 80 ab; OPNsense setzt dazu eine temporäre Portweiterleitung oder nutzt das HAProxy-Frontend |
nein | Seit Plugin-Version 4.11 als veraltet (deprecated) markiert, noch ohne Termin für die Entfernung. Nur noch, wenn kein DNS-API verfügbar ist. |
| TLS-ALPN-01 | Nachweis über einen speziellen TLS-Handshake auf Port 443 (temporärer Webserver von acme.sh) | nein | Sonderfall, wenn nur Port 443 erreichbar ist. |
Für deutsche Unternehmen interessant: Unterstützt werden u. a. IONOS, Hetzner (DNS und Cloud), netcup, INWX, All-Inkl.com, AutoDNS (InterNetX), hosting.de, united-domains Reselling, Variomedia, Cloudflare, AWS Route 53, Azure DNS sowie nsupdate (RFC 2136) und das OPNsense-BIND-Plugin für eigene Nameserver.
Schritt 1: Plugin installieren und aktivieren
- System → Firmware → Plugins: os-acme-client installieren und die Seite neu laden.
- Services → ACME Client → Settings: Enable Plugin und Auto Renewal aktivieren. Auto Renewal legt einen Cron-Job an, der regelmäßig prüft, welche Zertifikate fällig sind; der Zeitplan lässt sich unter System → Settings → Cron anpassen.
- Nur bei Einsatz von HAProxy mit HTTP-01: HAProxy Integration aktivieren.
Schritt 2: ACME-Konto anlegen
Services → ACME Client → Accounts → +:
| Feld | Empfehlung |
|---|---|
| Name | z. B. LE-Produktiv |
| E-Mail Address | Funktionspostfach der IT (für Mitteilungen der CA) |
| ACME CA | Let’s Encrypt Test CA für erste Versuche, danach Let’s Encrypt – so werden bei Fehlversuchen keine Rate Limits der Produktiv-CA verbraucht |
| Key Identifier / HMAC Key | nur bei CAs mit External Account Binding (EAB), z. B. ZeroSSL, Google oder SSL.com |
Nach dem Speichern über das Symbol Register account das Konto bei der CA anmelden.
Schritt 3: Challenge Type DNS-01 einrichten
Services → ACME Client → Challenge Types → +:
- Challenge Type: DNS-01
- DNS Service: den eigenen DNS-Anbieter wählen und die angezeigten API-Zugangsdaten eintragen (z. B. API-Token bei Hetzner oder Cloudflare, Prefix und Secret bei IONOS).
- DNS Sleep Time: 0 (Standard) – der Client prüft dann alle 10 Sekunden für bis zu 20 Minuten, ob der TXT-Eintrag öffentlich sichtbar ist. Nur bei Anbietern mit sehr langsamer Verteilung einen festen Wert setzen.
_acme-challenge.example.com zeigt auf eine separate Validierungszone, und nur diese wird per API beschrieben.Schritt 4: Zertifikat anlegen
Services → ACME Client → Certificates → +:
| Feld | Beispiel / Empfehlung |
|---|---|
| Common Name | example.com
|
| Alt Names | *.example.com (Wildcard – nur mit DNS-01) oder einzelne Namen wie fw.example.com, mx.example.com
|
| ACME Account | LE-Produktiv |
| Challenge Type | der DNS-01-Eintrag aus Schritt 3 |
| Auto Renewal | aktiviert |
| Renewal Interval | 30 Tage (Standard 60 – siehe Abschnitt Zertifikatslaufzeiten) |
| Key Length | ec-256 oder ec-384 (kompakt und schnell); 4096 bit RSA (Standard) nur, wenn Altgeräte es erfordern |
| OCSP Must Staple | aus – Let’s Encrypt unterstützt OCSP nicht mehr; Anfragen mit dieser Option schlagen fehl |
| Certificate Profile | leer (Standardprofil classic) oder ein Profil der CA, z. B. tlsserver oder shortlived |
| Automations | siehe Schritt 5 |
Speichern und über das Symbol Issue or renew certificate die erste Ausstellung starten. Den Fortschritt zeigt Log Files → Acme Log. Nach Erfolg erscheint das Zertifikat unter System → Trust → Certificates; bei jeder Erneuerung wird dieser Eintrag automatisch aktualisiert.
Schritt 5: Automations – Zertifikat ausrollen
Dienste laden ein erneuertes Zertifikat meist erst nach einem Neustart. Unter Services → ACME Client → Automations werden deshalb Aktionen angelegt und im Zertifikat ausgewählt:
| Automation | Einsatz |
|---|---|
| Restart OPNsense Web UI | Zertifikat der Weboberfläche |
| Restart HAProxy / Restart Nginx / Reload Caddy (OPNsense plugin) | Reverse Proxys auf der Firewall |
| System or Plugin Command | beliebiger configd-Befehl, z. B. Neustart von Postfix oder anderen Plugins |
| Upload certificate via SFTP / Remote Command via SSH | Zertifikat auf Linux-Server kopieren und dort einen Dienst neu laden |
| Upload certificate to Proxmox VE / Proxmox Backup Server | Weboberfläche der Virtualisierung bzw. des Backup-Servers |
| Upload certificate to Synology DSM, TrueNAS, FRITZ!Box, Palo Alto Networks, Ruckus, Zyxel GS1900, HashiCorp Vault, Unifi | Geräte und Dienste im Netz zentral mitversorgen |
So wird die OPNsense zur zentralen Zertifikatsstelle für das Netzwerk: Ein Wildcard-Zertifikat wird einmal ausgestellt und automatisch an alle Systeme verteilt, die keinen eigenen ACME-Client haben oder keinen Internetzugang besitzen.
Zertifikate in der OPNsense verwenden
- Weboberfläche: System → Settings → Administration → SSL Certificate auswählen; Automation Restart OPNsense Web UI hinterlegen. Zugriff dann über den Namen aus dem Zertifikat (der interne DNS muss ihn auf die LAN-Adresse auflösen, z. B. per Host Override in Unbound).
- HAProxy: im Public Service unter Certificates auswählen, Automation Restart HAProxy – Details im Artikel OPNsense - HAProxy Reverse Proxy und Load Balancer.
- NGINX: im HTTP Server als TLS Certificate – siehe OPNsense - NGINX Reverse Proxy und WAF.
- Caddy: Caddy holt sich Zertifikate normalerweise selbst; für Wildcard-Zertifikate bei DNS-Anbietern ohne Caddy-Integration wird das ACME-Client-Zertifikat in der Caddy-Domain unter Certificate ausgewählt (Automation Reload Caddy) – siehe OPNsense - Caddy Reverse Proxy.
- Postfix: als Server Certificate für den MX-Namen – siehe OPNsense - Postfix Mail-Gateway.
- Stunnel, Captive Portal, OpenVPN-Webdienste und andere Plugins: Auswahl jeweils aus System → Trust.
Zertifikatslaufzeiten: Was sich bis 2029 ändert
Die Branchenvorgaben des CA/Browser Forums verkürzen die maximale Laufzeit öffentlicher TLS-Zertifikate schrittweise bis 2029 auf 47 Tage. Let’s Encrypt setzt das so um:
| Ab | Profil | Laufzeit | Wiederverwendung der Domain-Validierung |
|---|---|---|---|
| heute | classic (Standard) | 90 Tage | 30 Tage |
| 13.05.2026 | tlsserver (opt-in) | 45 Tage | – |
| 10.02.2027 | classic | 64 Tage | 10 Tage |
| 16.02.2028 | classic | 45 Tage | 7 Stunden |
| – | shortlived (opt-in) | 6 Tage | – |
Konsequenzen für den ACME-Client:
- Renewal Interval in jedem Zertifikat auf 30 Tage setzen – bei 45 Tagen Laufzeit bleiben so 15 Tage Puffer für Störungen. Der Standardwert 60 führt ab Februar 2027 zu abgelaufenen Zertifikaten.
- Da die Domain-Validierung künftig kaum noch zwischengespeichert wird, muss die Validierung bei jeder Erneuerung funktionieren – ein stabiles DNS-01-Setup ist dafür die robusteste Lösung.
- Automations für alle Dienste einrichten, die das Zertifikat nutzen – bei häufigeren Erneuerungen fallen vergessene Neustarts schneller auf.
- Ablaufdaten überwachen, z. B. mit dem Zabbix-Agent oder einem Web-Monitoring der veröffentlichten Dienste.
Sicherheitsempfehlungen
- DNS-01 statt HTTP-01 – keine Portfreigaben, keine temporären Portweiterleitungen und Wildcard-Unterstützung.
- API-Token mit minimalen Rechten bzw. DNS Alias Mode für die Validierung.
- Zuerst mit der Test CA arbeiten; Let’s Encrypt begrenzt u. a. Duplikate und fehlgeschlagene Validierungen pro Stunde.
- Wildcard-Zertifikate nur auf vertrauenswürdige Systeme verteilen; Automations mit SSH/SFTP über eigene Schlüssel und eingeschränkte Benutzer betreiben.
- Konfigurationssicherung verschlüsseln: Sie enthält die privaten Schlüssel und die API-Zugangsdaten des DNS-Anbieters.
- Certificate Transparency beachten: Alle Namen eines öffentlichen Zertifikats sind in CT-Logs öffentlich einsehbar – interne Hostnamen gegebenenfalls über ein Wildcard-Zertifikat abdecken.
Typische Probleme und Lösungen
| Symptom | Ursache und Lösung |
|---|---|
| Acme Log: TXT-Eintrag wird nicht gefunden | API-Zugangsdaten falsch, Token ohne Rechte auf die Zone, falsche Zone gewählt oder sehr langsame Verteilung – DNS Sleep Time erhöhen. |
| HTTP-01 schlägt fehl | Port 80 nicht von außen erreichbar, Name zeigt nicht auf die WAN-Adresse, vorgeschaltete NAT/Portweiterleitung oder Webserver fängt die Anfrage ab – besser auf DNS-01 umstellen. |
| too many certificates / rateLimited | Rate Limit der Produktiv-CA erreicht – warten und künftig mit der Test CA testen. |
| Ausstellung scheitert mit OCSP-Fehler | OCSP Must Staple deaktivieren. |
| Zertifikat erneuert, Dienst zeigt noch das alte | Automation fehlt oder Automation Timeout zu kurz – Automation ergänzen und manuell auslösen. |
| Zertifikat läuft trotz Auto Renewal ab | Cron-Job fehlt (Auto Renewal unter Settings), Zertifikat deaktiviert oder Renewal Interval länger als die Laufzeit. |
| Weboberfläche nach Umstellung nicht erreichbar | Aufruf per IP statt Namen bzw. DNS-Name intern nicht auflösbar; ggf. über die Konsole das Standardzertifikat zurücksetzen. |
Ausführliche Meldungen liefert Settings → Log Level = debug; danach wieder zurückstellen, da Debug-Logs sensible Daten enthalten können.
Fazit
Der ACME-Client macht die OPNsense zur zentralen, automatischen Zertifikatsstelle: Mit DNS-01 entstehen Wildcard-Zertifikate ohne offene Ports, und Automations versorgen Weboberfläche, Reverse Proxys, Mail-Gateway und Geräte wie Proxmox oder Synology ohne manuelles Zutun. Wichtig für 2027 und 2028: Die kürzeren Laufzeiten bei Let’s Encrypt erfordern eine Renewal Interval von 30 Tagen – wer das jetzt umstellt, vermeidet abgelaufene Zertifikate.
Unterstützung von m.a.x. it
Sie möchten Zertifikate auf Ihren Firewalls und Servern automatisieren oder bestehende Installationen für die kürzeren Laufzeiten vorbereiten? 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
- OPNsense - Unbound DNS Resolver
- ACME
- Let's Encrypt
- Zertifikat
- TLS
- PKI
- OPNsense - HAProxy Reverse Proxy und Load Balancer
- OPNsense - NGINX Reverse Proxy und WAF
- OPNsense - Caddy Reverse Proxy
- OPNsense - Postfix Mail-Gateway
- OPNsense - Plugin-Liste
Links und Quellen
- Quellcode des Plugins os-acme-client
- Let’s Encrypt – Decreasing Certificate Lifetimes to 45 Days
- acme.sh – ACME-Client
- acme.sh – unterstützte DNS-APIs und benötigte Zugangsdaten
- m.a.x. it – OPNsense-Firewall-Services
Ü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?
