OPNsense: read-only API-User fürs Monitoring statt Root-Key

Kurz gesagt: Lege unter System → Access → Users einen eigenen Benutzer monitoring an, gib ihm ausschließlich die Diagnose- und Status-Privilegien, die dein Exporter laut seiner Doku braucht, und erzeuge für ihn einen API-Key. Trage diesen Key im Monitoring-Tool ein — nicht den Root-Key. Der Schlüssel liegt danach zwar weiterhin im Klartext auf dem Monitoring-Host, öffnet dort aber nur noch Lesezugriff auf Statuswerte statt der kompletten Firewall.

Wer sein Homelab überwacht, hängt früher oder später auch die OPNsense an Prometheus oder ein anderes Monitoring. Der schnellste Weg dorthin ist ein API-Key aus dem Administrator-Konto — er funktioniert sofort, und genau deshalb bleibt er oft für immer. Das Problem ist nicht die Einrichtung, sondern der Ort, an dem dieser Schlüssel danach liegt: in einer .env-Datei auf dem Monitoring-Host, gelesen von einem Container, mitgesichert von jedem Backup.

Dieser Guide zeigt den sauberen Weg: ein eigener Benutzer, der nur lesen darf. Der Aufwand liegt bei etwa zehn Minuten.

Warum Least Privilege hier konkret etwas bringt #

Least Privilege heißt: Jeder Zugang bekommt genau die Rechte, die er für seine Aufgabe braucht — nicht mehr. Der Begriff klingt nach Firmen-IT, wird im Homelab aber schnell praktisch, sobald Dienste miteinander reden.

Ein Monitoring-Exporter fragt Statuswerte ab: Interface-Zähler, aktive Dienste, DHCP-Leases, WireGuard-Status. Dafür genügt Lesezugriff auf einige Diagnoseseiten. Läuft er stattdessen mit dem Root-Key, gilt: Wer den Key in die Hände bekommt, kann Firewallregeln umschreiben, sich einen VPN-Zugang anlegen oder die gesamte Konfiguration herunterladen. Der Unterschied zwischen beiden Varianten ist kein theoretischer — er entscheidet, ob ein gelesenes .env-File ein Ärgernis oder ein Totalschaden ist.

Dazu kommt ein praktischer Nebeneffekt: Ein eigener Benutzer taucht im Audit-Log unter eigenem Namen auf. Du siehst also, welche Zugriffe vom Monitoring kommen und welche von dir.

Der einfache Weg: Benutzer und Key in der Weboberfläche #

Für die meisten Setups ist das der richtige Weg.

1. Benutzer anlegen: System → Access → Users → +. Als Benutzername etwas Sprechendes wie monitoring wählen. Ein Passwort ist nötig, wird für den reinen API-Zugriff aber nicht verwendet — vergib ein langes Zufallspasswort und speichere es im Passwortmanager.
2. Shell-Zugang aus lassen: Bei Login shell nichts setzen. Der Benutzer soll sich nicht anmelden können, sondern nur über die API gelesen werden.
3. Privilegien zuweisen: Im Feld Effective Privileges die Seiten auswählen, die dein Exporter braucht (siehe nächster Abschnitt). Bei einem einzelnen Benutzer kannst du die Rechte direkt am Konto vergeben — eine eigene Gruppe lohnt erst, wenn mehrere Konten dieselben Rechte brauchen.
4. API-Key erzeugen: Den Benutzer speichern, erneut öffnen und unter API keys auf + klicken. OPNsense lädt daraufhin eine Datei mit key und secret herunter. Das Secret wird nur dieses eine Mal angezeigt — es liegt auf der Firewall ausschließlich als Hash. Geht es verloren, erzeugst du einen neuen Key.

Danach trägst du Key und Secret im Monitoring-Tool ein und entfernst den alten Root-Key aus dessen Konfiguration.

Welche Privilegien ein Monitoring-Exporter braucht #

Die genaue Liste steht in der Dokumentation deines Exporters — sie nennt die GUI-Seiten, deren Daten er abfragt. Für einen typischen OPNsense-Exporter, der Interfaces, Dienste, DNS, VPN und Systemzustand ausliest, sind es rund 17 Einträge aus diesen Bereichen:

Ein hilfreicher Trick, wenn du die Rechte skripten willst: Die internen IDs hinter diesen Klartextnamen — etwa page-diagnostics-pf-info — liefert die OPNsense selbst über den Endpunkt api/auth/priv/search. Damit lässt sich die Liste aus der Exporter-Doku sauber auf IDs abbilden, statt sie durch Ausprobieren zusammenzusuchen.

Grundsatz bei der Auswahl: Nimm ausschließlich Seiten aus Diagnostics, Status, Reporting und lesende System-Seiten. Sobald eine Konfigurationsseite in der Liste steht, ist der Benutzer nicht mehr read-only.

Der Automatisierungs-Weg: Benutzer und Key per API anlegen #

Wer die Einrichtung reproduzierbar halten will, kann alles über die API erledigen — mit einer Besonderheit, die einiges an Suchzeit kostet.

Benutzer und Privilegien lassen sich direkt anlegen:

# Privilegien-IDs zu den Klartextnamen aus der Exporter-Doku finden
curl -sk -u "<KEY>:<SECRET>" \
  https://<OPNSENSE-HOST>/api/auth/priv/search
 
# Benutzer mit den ermittelten Privilegien anlegen
curl -sk -u "<KEY>:<SECRET>" \
  -H 'Content-Type: application/json' \
  -d @user.json \
  https://<OPNSENSE-HOST>/api/auth/user/add

Die Stolperfalle: Für das Erzeugen eines API-Keys gibt es keinen Endpunkt. Aufrufe wie auth/user/newApiKey liefern auf OPNsense 26.1 schlicht 404 — die Core-Auth-API kennt kein eigenes Kommando dafür.

Der Weg führt stattdessen über das apikeys-Feld des Benutzers, das direkt beschreibbar ist. Key und Secret erzeugst du lokal, das Secret wird gehasht gespeichert — exakt so, wie es die Weboberfläche intern auch macht:

# Key und Secret lokal erzeugen
openssl rand -base64 60
 
# Secret als sha512crypt-Hash ablegen (nur der Hash landet auf der Firewall)
openssl passwd -6 '<SECRET>'

Anschließend schreibst du den Wert im Format key|hash über api/auth/user/set ins apikeys-Feld des Benutzers. Das Klartext-Secret speicherst du nur dort, wo der Exporter es braucht — auf der Firewall bleibt ausschließlich der Hash.

Funktioniert der Key? Kurz gegenprüfen #

Ein Aufruf genügt, um Key und Rechte zu testen:

curl -sk -u "<KEY>:<SECRET>" \
  https://<OPNSENSE-HOST>/api/core/system/status

Kommt eine JSON-Antwort zurück, ist der Zugang aktiv. Im Monitoring selbst prüfst du danach die Metrik opnsense_up — steht sie auf 1 und meldet der Exporter keine Endpoint-Fehler, reichen die vergebenen Rechte für alle aktiven Collectors.

Erst wenn das läuft, entfernst du den Root-Key: In der Weboberfläche beim Administrator-Konto löschen, vorher im Passwortmanager sichern, falls andere Automatisierungen daran hängen.

Zwei Stolperfallen aus der Praxis #

Fehlende Werte sind nicht immer fehlende Rechte. Gateway-Metriken wie Latenz und Paketverlust entstehen erst, wenn das Gateway-Monitoring (dpinger) aktiv ist; Firmware-Metriken erst nach einem einmaligen Update-Check. Beides wird in der Weboberfläche in je einer Minute angestoßen — ohne diese Schritte bleiben die Metriken leer, egal wie viele Privilegien du nachträglich vergibst.

Privilegien verschwinden zwischen Versionen. Auf OPNsense 26.1 mit Dnsmasq als DHCP-Server existiert das frühere Privileg für DHCP-Leases nicht mehr. Die zugehörige API antwortete im Test trotzdem, ohne dass ein Zusatzrecht nötig war. Wenn ein in der Doku genanntes Privileg in deiner Version nicht auftaucht, ist das also nicht zwingend ein Fehler — prüfe erst, ob der Endpunkt trotzdem Daten liefert, bevor du breitere Rechte vergibst.

Was du dir damit eingehandelt hast #

Ein Monitoring, das die Firewall lesen, aber nicht verändern kann. Der API-Key liegt weiterhin im Klartext auf dem Monitoring-Host — daran ändert dieser Guide nichts. Aber der Schaden bei einem Leak ist ein anderer: statt voller Kontrolle über das Netz nur noch der Blick auf Werte, die dein Dashboard ohnehin anzeigt.

Wenn du das Monitoring selbst noch aufbaust, passen dazu die Guides zu Uptime Kuma und Beszel für die Dienst- und Host-Überwachung sowie zum SMART-Monitoring mit smartctl_exporter für die Festplattengesundheit.