Zum Inhalt springen
IDO DNS Service
Menü
Anmelden Konto anlegen
Alle Themen

OPNsense: Zertifikat automatisch abholen und einspielen

Fernzugriff · OPNsense 26.1 und neuer

Zuletzt überarbeitet am

Für OPNsense-Firewalls, deren Weboberfläche mit einer Warnung aufgeht. Am Ende holt sich die Firewall ihr Zertifikat selbst ab und erneuert es, ohne dass jemand daran denken muss.

Diese Anleitung gehört zu Fernzugriff von IDO DNS Service — was die Leistung kann und was sie kostet.

Fünf Stellen, an denen es lautlos schiefgeht:

  1. Die Konsole von root ist keine sh. OPNsense meldet root in der csh an. Dort bedeutet : etwas anderes, und jeder Befehl mit "$KEY:$SECRET" scheitert mit „Bad : modifier in $“ — was nach einem Tippfehler aussieht und keiner ist. Tippen Sie als Erstes sh.
  2. Die Firewall legt ihr Zertifikat nicht als Datei ab. Es steht in /conf/config.xml; /var/etc/cert.pem entsteht daraus bei jedem Anwenden neu. Das gewöhnliche Linux-Skript würde melden „Neues Zertifikat eingespielt“ — und ausgeliefert würde weiter das alte.
  3. /etc/cron.d gibt es, gelesen wird es nicht. Ein Testeintrag „jede Minute“ hat nach zwei Minuten nichts hinterlassen. Deshalb trägt sich die Abholung in OPNsense’ eigene Zeitsteuerung ein — dort ist sie auch in der Weboberfläche zu sehen.
  4. Die apikey.txt schreibt klein. Sie enthält key= und secret= in Kleinbuchstaben. Wer sie umbenennt oder abtippt, bekommt HTTP 401 — und das sieht aus wie ein falscher Schlüssel, ist aber ein leerer. Legen Sie die Datei unverändert ab.
  5. Kein sh -x zur Fehlersuche. Die Schnittstelle der Firewall gibt bei einer Abfrage die vollständigen Datensätze zurück — samt privatem Schlüssel, und zwar von jedem Zertifikat der Kiste. Eine Ablaufverfolgung schreibt das wörtlich auf den Bildschirm. Das Skript selbst sagt in jedem Fehlerfall, woran es lag; das reicht.

Was Sie brauchen

Ein Name und ein Zertifikat im Kundenbereich, ein API-Zugang der Firewall — und eine bereits eingerichtete Weboberfläche mit einem eigenen Zertifikat. Der letzte Punkt ist keine Förmlichkeit: Das Skript ersetzt genau den Eintrag, auf den die Oberfläche zeigt, statt einen neuen danebenzulegen. Deshalb müssen Sie unter System → Einstellungen → Administration nie wieder etwas umstellen.

Geprüft auf OPNsense 26.1.10 (FreeBSD 14.3). Auf älteren Fassungen ab 24.7 sollte es ebenso laufen — dort gibt es die Trust-Schnittstelle bereits; nachgemessen haben wir es nicht.

Einrichten

  1. Im Kundenbereich Namen, Zertifikat und Abholung anlegen

    Fernzugriff → Kunde → Namen und Zertifikat: einen Namen für die Firewall anlegen, das Zertifikat ausstellen lassen, dann Automatisch abholen. Sie bekommen mehrere Fassungen zu sehen — nehmen Sie die mit der Überschrift „OPNsense-Firewall“. Der Zugang steht darin schon eingesetzt und wird nur dieses eine Mal angezeigt.

  2. Einen API-Zugang der Firewall erzeugen

    System → Zugriff → Benutzer → root → bearbeiten → API-Schlüssel → +

    Es lädt eine apikey.txt mit zwei Zeilen herunter. Diese beiden Werte sind Vollzugriff auf die Firewall — sie gehören nirgendwo hin außer auf die Kiste selbst.

  3. Auf der Firewall: erst in die sh, dann den Zugang ablegen

    Per SSH als root anmelden, Menüpunkt 8. Dann als Allererstes: 

    sh

    Danach:

    mkdir -p /usr/local/etc/ido && chmod 700 /usr/local/etc/ido

    Die apikey.txt kommt unverändert nach /usr/local/etc/ido/api — Kleinschreibung inklusive. Danach: 

    chmod 600 /usr/local/etc/ido/api

  4. Das Skript ablegen

    Kommen Sie über einen Windows-Rechner? Dann stehen im Skript Windows-Umbrüche, und die Konsole scheitert schon beim Start — mit einer Meldung, die sich selbst überschreibt. Deshalb geht es hier durch tr und nicht durch cp: 

    tr -d '\r' < /root/abholen-opnsense.sh > /usr/local/sbin/ido-zertifikat
chmod 700 /usr/local/sbin/ido-zertifikat

    700 und nicht 755: Der Zugang zu unserem Dienst steht in der Datei.

  5. Einmal von Hand laufen lassen

    /usr/local/sbin/ido-zertifikat holen

    Erwartet wird eine Zeile: „Neues Zertifikat eingespielt, gültig bis …“ Die Weboberfläche startet dabei kurz neu; Ihre angemeldete Sitzung bleibt bestehen.

    Danach sieht das Skript selbst nach, was die Oberfläche wirklich ausliefert, und vergleicht den Fingerabdruck. Stimmt er nicht, spielt es das alte Zertifikat zurück. Ein Zertifikatstausch, der die Verwaltung einer Firewall aussperrt, wäre der unangenehmste Fehler dieser ganzen Kette — und der einzige, bei dem der Weg zurück nicht mehr über dieselbe Oberfläche führt.

    Deshalb schreibt es gar nicht erst, wenn es das bisherige Zertifikat nicht sichern konnte. Ein Lauf, der nichts tut, kostet einen Tag — der nächste ist ja morgen. Ein Lauf, der aussperrt, kostet eine Anfahrt.

  6. Die tägliche Abholung einrichten

    /usr/local/sbin/ido-zertifikat einrichten

    Das legt eine eigene Aktion an und nennt Ihnen vier Werte. Die trägt man einmal in der Weboberfläche ein, weil OPNsense seine Zeitsteuerung in der Konfiguration führt und nicht in Dateien: System → Einstellungen → Cron → +

    Der Befehl ist kein Text zum Abschreiben. OPNsense bietet dort eine Auswahlliste an und zeigt darin die Beschreibung der Aktion — Sie suchen also den Eintrag „IDO-Zertifikat abholen“ und nicht den internen Namen, den das Skript nennt.

    Die Minute ist absichtlich krumm. Das Skript würfelt sie aus. Wer die Abholung auf zwanzig Geräten einrichtet, ließe sie sonst alle in derselben Sekunde bei uns anfragen — und in unserem Protokoll sähe das aus wie ein Angriff.

    Nicht crontab -e benutzen. OPNsense erzeugt /var/cron/tabs/root bei jeder Konfigurationsänderung neu aus der Konfiguration. Ein Eintrag von Hand wäre irgendwann kommentarlos verschwunden — und aufgefallen wäre es am abgelaufenen Zertifikat.

  7. Prüfen

    Die Weboberfläche der Firewall zeigt keine Zertifikatswarnung mehr — sofern Sie sie unter dem Namen aufrufen, auf den das Zertifikat lautet. Unter ihrer IP-Adresse warnt der Browser weiter, und das zu Recht.

    „Zuletzt abgeholt“ im Kundenbereich beweist die Zeitsteuerung nicht. Der Zähler ist schon durch Ihren Lauf von Hand aus Schritt 5 gestiegen; er stünde genauso da, wenn der Cron-Eintrag fehlte. Sehen Sie deshalb auf der Firewall selbst nach, dass er wirklich angelegt ist: 

    grep -c idozertifikat /conf/config.xml

    Eine Zahl größer null heißt: Der Eintrag steht in der Konfiguration und überlebt einen Neustart. Der eigentliche Beweis kommt am nächsten Morgen — im Kundenbereich muss dann ein zweiter Abruf stehen.

Was täglich passiert

Fast nichts, und das ist der Zweck. Das Skript fragt einen Wert ab, vergleicht ihn mit dem, was zuletzt eingespielt wurde, und ist fertig. Erst wenn sich etwas geändert hat, wird geschrieben und die Oberfläche neu geladen.

Weshalb täglich und nicht alle 80 Tage: Ein einzelner Lauf alle 80 Tage wäre ein einzelner Punkt, an dem alles hängt. Fällt er aus — die Firewall war neu gestartet, das Netz war weg —, ist der nächste Versuch lange nach dem Ablauf. Täglich heißt: Der nächste Versuch ist morgen, und es bleiben Wochen Puffer.

Wenn es nicht klappt

Bad : modifier in $ '$'
Sie sind in der csh. sh eintippen, dann noch einmal. Das ist die häufigste Meldung überhaupt an dieser Stelle, und sie sieht nach einem Tippfehler aus.
Abholung fehlgeschlagen (HTTP 401)
Der Zugang zu unserem Dienst stimmt nicht. Meist wurde im Kundenbereich inzwischen ein neuer Zugang erzeugt, und auf der Firewall liegt noch das alte Skript. Das Skript lässt sich nicht noch einmal ansehen — es wird genau einmal angezeigt, danach liegt bei uns nur sein Hash. Es hilft nur Neuen Zugang erzeugen, und dann muss das neue Skript auf jede Kiste, die mit dem alten abgeholt hat: Der bisherige Zugang gilt danach nicht mehr.
Die Zertifikatsliste war nicht abrufbar (HTTP 401)
Diesmal der API-Zugang der Firewall. Prüfen Sie, ob in /usr/local/etc/ido/api wirklich Werte stehen — ein OPNsense-Schlüssel ist rund 80 Zeichen lang: awk -F= '{print $1, length($2)}' /usr/local/etc/ido/api. Steht dort eine kleine Zahl, ist ein Platzhalter drin geblieben.
Zu <ssl-certref> gibt es keinen Eintrag
Die Weboberfläche benutzt kein Zertifikat aus dem eigenen Speicher. Spielen Sie das Zertifikat einmal von Hand ein (System → Sicherheit → Zertifikate → +) und stellen Sie die Administration darauf um; ab dann übernimmt das Skript.
Die Firewall hat nicht gespeichert
Darunter steht, was sie beanstandet hat. Am häufigsten: Das Zertifikat passt nicht zur eingetragenen Ausgabestelle. Dann muss unter System → Sicherheit → Zertifizierungsstellen (ältere Fassungen: Vertrauen) die Ausgabestelle liegen, die es unterschrieben hat.
Die Oberflaeche liefert nicht das neue Zertifikat aus
Lesen Sie die nächste Zeile, sie entscheidet alles. Steht dort „Das alte Zertifikat ist wieder eingespielt“, ist der Rückweg gelaufen und Sie stehen da, wo Sie vorher waren — schicken Sie uns die Meldung.
ACHTUNG: Auch das Zurueckspielen ist misslungen
Der eine Fall, in dem jemand sofort an die Konsole muss. Die Oberfläche der Firewall ist möglicherweise nicht mehr erreichbar. Das bisherige Zertifikat liegt als /usr/local/etc/ido/rueckweg.crt und .prv bereit; über die serielle Konsole oder SSH lässt es sich von Hand wieder einsetzen. Rufen Sie uns an.
Das bisherige Zertifikat liess sich nicht vollstaendig sichern
Das Skript hat nichts geändert — es hat abgebrochen, statt ohne Rückweg zu schreiben. Die Oberfläche läuft unverändert weiter. Meist steckt eine Eigenheit im vorhandenen Eintrag dahinter; schicken Sie uns die Meldung.
Es steht einfach da, ohne ein Zeichen
Dann liegt eine Fassung vor September 2026 auf der Firewall. Sie las die Antworten mit sed, und das sed des FreeBSD-Grundsystems verfolgt zurück: Auf einer Zeile mit Hunderten von Anführungszeichen explodiert die Zahl der Versuche. Gemessen auf einem Datensatz von 14709 Zeichen: über 20 Sekunden ohne Ergebnis, gegen 4 Millisekunden mit der heutigen Fassung. Neu herunterladen.

Wie es weitergeht

Ab morgen früh läuft die Abholung ohne Sie: Im Kundenbereich unter „Namen und Zertifikat“ steht dann der zweite Abruf, und die Firewall zeigt ihr Zertifikat, bis Let’s Encrypt ein neues ausstellt — dann tauscht das Skript es aus, ohne dass jemand daran denkt. Dasselbe gibt es für die anderen Geräte im Kundennetz: den Windows-Server unter Remotedesktop ohne Zertifikatswarnung und das QNAP-NAS, das auf QTS eine eigene Fassung braucht.

Wer die Firewall nicht nur selbst erreichen, sondern den Kunden im Browser bedienen will, ohne auf dessen Rechner etwas einzurichten, nimmt die Fernwartung im Browser. Und der Server hinter der OPNsense sichert sich durch denselben Tunnel mit BorgBackup in den Cloud-Speicher.

Weiter im selben Bereich

Ihr Gerät ist nicht dabei? Alle Anleitungen

Kommen Sie nicht weiter? Sehen Sie zuerst unter Häufige Fragen nach.

Steht die Antwort dort nicht, schreiben Sie uns an info@idodns.de — mit dieser Anleitung im Betreff. Was mehrfach gefragt wird, steht danach hier.