Die OPNsense-API sagte nur „failed“ — schuld waren Klammern im Beschreibungstext

Was passiert ist: Ich wollte per API eine DHCP-Option setzen, damit die Geräte im Netz wieder meinen eigenen DNS-Server zugewiesen bekommen statt den des Routers — Werbefilterung und lokale Namen gelten sonst nur für die Geräte, die man von Hand umgestellt hat.

Der Aufruf antwortete mit:

{ "result": "failed" }

Mehr nicht. Kein Feldname, keine Validierungsmeldung, kein Hinweis worauf sich das bezieht. Der HTTP-Status war unauffällig.

Die Ursache: Nicht der eigentliche Wert war das Problem, sondern der Beschreibungstext daneben. Ich hatte dort Klammern und Sonderzeichen untergebracht — so, wie man einen Kommentar eben schreibt. Die Feldvalidierung lehnt das ab, und genau diese Meldung geht auf dem Weg nach draußen verloren. Übrig bleibt das nackte failed.

Mit einer schlichten Beschreibung ohne Sonderzeichen ging derselbe Aufruf sofort durch.

Was ich daraus mitnehme: Wenn die OPNsense-API still mit failed antwortet, ist der erste Reflex, den Feldsatz zu prüfen — fehlt ein Pflichtfeld, ist ein Feldname falsch? Der bessere erste Schritt ist, die Feldwerte zu vereinfachen: Sonderzeichen raus, Text kürzen, dann erneut. Ein abgelehnter Wert in einem völlig nebensächlichen Feld sieht von außen genauso aus wie ein grundsätzlich falscher Aufruf.

Das ist keine OPNsense-Eigenheit, die man einmal lernt und nie wieder braucht — es ist das übliche Muster, wenn eine Weboberfläche und eine API dieselbe Validierung benutzen, die Fehlermeldung aber nur für die Oberfläche gedacht ist.

Wie man einen API-Zugang dafür überhaupt einrichtet, steht im Guide OPNsense-API nutzen; für reine Abfragen reicht ein Benutzer mit Leserechten.

Nachtrag zur Sache selbst: Die Option ist aktiv, die Geräte übernehmen den neuen DNS-Server mit ihrer nächsten Adresserneuerung. Damit hängt die Namensauflösung im ganzen Netz wieder an einem einzigen Dienst — das ist eine bewusste Entscheidung, kein Versehen. Der Rückweg ist eine Zeile: Option zurückstellen oder löschen, dann verteilt der Router wieder sich selbst.