Custom-Script-Check-Referenz

octoja kennt zwei Wege, ein Skript als Check auszuliefern — und unter der Haube sind das nicht dasselbe Plugin. Diese Referenz trennt beide klar, damit du den richtigen ohne Überraschungen konfigurierst.

• Eingebauter Custom-Script-Check — ein vorgefertigtes Check-Plugin, das du über ein Konfigurationspaket einem Gerät zuweist. Du fügst ein einzelnes PowerShell- oder bash-Skript in die Check-Definition ein; der Agent führt es unverändert aus und wandelt den Exit-Code in einen Status um.
• Selbstdefinierte Custom-Checks — Checks, die du selbst auf der Seite Custom Checks im Dashboard schreibst. Jedes Skript wird zum Zeitpunkt der Auslieferung von octoja in einen Wrapper umhüllt, damit es typisierte Eingaben deklarieren, typisierte Ausgaben emittieren und den gebündelten SNMP-Worker verwenden kann.

Die beiden Wege teilen weder den Status-Mechanismus noch den Output-Vertrag. Lies den Abschnitt, der zum konfigurierten Check passt.

Eingebauter Custom-Script-Check

Plugin-Kennung octo/custom-script. Der Agent führt das Skript direkt aus — über powershell.exe unter Windows oder /bin/bash -s unter Linux und macOS. Kein Wrapper, keine Helper, keine Sentinel-Marker — der Check stützt sich vollständig auf den Exit-Code und eine kleine stdout/stderr-Erfassung.

Statuscodes (Exit-Code-Mapping)

Der Exit-Code bestimmt das Ergebnis. Jeder Custom-Script-Check trägt einen SuccessExitCode, eine WarningExitCodes-Liste und eine CriticalExitCodes-Liste:

Du kannst jede Liste pro Check überschreiben — etwa 0 und 3 als Success akzeptieren, wenn du ein Legacy-Werkzeug umhüllst. Die Critical-Liste wird vor der Warning-Liste ausgewertet — ein Exit-Code, der in beiden Listen steht, ergibt also Critical. Es gibt für dieses Plugin keinen Helper im Skript; das Ergebnis ist immer der Exit-Code des Prozesses.

Was du zurückbekommst

Bei jedem Lauf liefert der Check diese Felder an octoja:

Ausführungsgrenzen

Was den Check zerstört

Selbstdefinierte Custom-Checks

Diese Checks schreibst du auf der Seite Custom Checks im Dashboard — der Editor deckt Skripte pro Plattform, typisierte Eingaben, typisierte Ausgaben und das Ausführungsintervall ab. (Community-Check-Repositories, die per Name und URL hinzugefügt werden, liefern fertige Checks aus einer externen Quelle — sie sind nicht der Weg, eigene Checks zu schreiben.) Jeder Check wird von octoja umhüllt, bevor er den Agent erreicht. Der Wrapper stellt dem Skript typisierte Eingaben bereit, liefert Helper zum Emittieren typisierter Ausgaben und grenzt die Result-Payload mit Sentinel-Markern ab, damit beliebige andere stdout-Ausgaben sie nicht beschädigen können.

Wenn du nur ein Linux-Skript hinterlegst, führt der Agent es auch auf macOS aus — über den osx-x64 / osx-arm64-Fallback.

Der Wrapper-Vertrag

Der Wrapper erledigt drei Dinge rund um dein Skript: Er dekodiert die konfigurierten Eingaben und stellt sie bereit ($checkInput / INPUT_JSON), belegt den Ausgabe-Container mit checkResult = 0 vor ($output / _OCTO_OUTPUT), und nachdem dein Skript gelaufen ist, serialisiert er die Ausgabe nach base64 und gibt sie zwischen den Result-Markern aus. Deine Aufgabe ist der mittlere Teil: Eingaben lesen, Arbeit erledigen, Ausgabefelder und den Status setzen. Der Agent extrahiert nur die Bytes zwischen <<<OCTO_RESULT_BEGIN>>> und <<<OCTO_RESULT_END>>>, sodass Write-Output, Write-Host, echo oder ConvertTo-Json aus deinem Skript den Wrapper nicht brechen.

Status — das checkResult-Sentinel

Umhüllte Checks nutzen kein Exit-Code-Mapping. Der Status ist das checkResult-Feld der serialisierten Output-Payload, das der Agent in eine CheckResultStatus-Enum decodiert. Setze es über den Helper deiner Sprache:

Die bash- und macOS-Wrapper liefern set_result 0|1|2 als Kurzform zum Setzen von checkResult. String-Werte sind beim Decodieren case-insensitive.

PowerShell — $checkInput und $output

Alles, was du an $output hängst, wird serialisiert und an octoja gesendet. Mappe deine Output-Keys auf die Ausgabefelder, die du in der Check-Definition deklariert hast — sonst kann der Dashboard-Renderer sie nicht an UI-Bausteine binden.

Der Wrapper injiziert außerdem zwei SNMP-Helper, die an den im Agent gebündelten SNMP-Worker delegieren. Beide nehmen benannte Parameter:

Beachte den Parameternamen: -TargetHost, nicht -Host. $Host ist eine automatische PowerShell-Variable, also vermeidet der Wrapper ihn. Beide Helper sind nur verfügbar, wenn der Agent seinen SNMP-Worker über die Umgebungsvariable OCTOJA_WORKER_BIN bereitstellt; ist die Variable nicht gesetzt, werfen die Helper eine Ausnahme und dein Skript sollte sauber zurückfallen.

Bash (Linux) — Helper

Die SNMP-Helper sind flag-basiert (--host, --community, …), nicht positional. Das Output-Array heißt _OCTO_OUTPUT (assoziativ). Verwende die Helper; das Array direkt anzufassen ist nicht Teil des Vertrags.

Bash (macOS) — Helper

Identische Schnittstelle wie unter Linux — get_input, set_output, set_result und dieselben flag-basierten snmp_get / snmp_walk, wenn OCTOJA_WORKER_BIN gesetzt ist — aber die Implementierung verwendet Python 3 statt jq. Selbst wenn dein Skript mitten im Lauf beendet wird oder abstürzt, entsteht noch ein sauberer Result-Envelope. Wenn du kein macOS-spezifisches Skript hinterlegst, wird das Linux-Skript wiederverwendet.

Eingabeschema

Eingaben werden auf der Check-Definition deklariert (Art, Label, Standardwert, erforderlich) und erreichen das Skript als JSON-Objekt. Die unterstützten Feldarten entsprechen dem InputFieldDefinition-Modell der Plattform — string, number, boolean, list und so weiter. Lies sie mit $checkInput.Key (PowerShell) oder get_input "key" (bash/macOS).

Ausgabeschema

Ausgaben werden auf der Check-Definition als Liste von OutputFieldDefinition deklariert. Jeder Eintrag hat:

checkResult ist implizit; deklariere zusätzliche Felder, die du tatsächlich im Dashboard verwendest.

Ausführungsgrenzen

Was den Check zerstört

Diagnose-Ausgabe während der Entwicklung gehört auf stderr — Write-Error / >&2 echo — und wird vom Agent erfasst, ohne den Wrapper-Vertrag zu brechen.

Encoding

Beide Check-Varianten übertragen und führen Skripte durchgehend als UTF-8 aus. Du musst nichts konvertieren und keine Byte-Order-Mark setzen — füge das Skript im Dashboard ein, octoja kümmert sich um das Encoding.

• Was octoja garantiert: Das Skript wird zeichengetreu als UTF-8 übertragen. Unter Windows wird es aus einer Skriptdatei mit UTF-8-Byte-Order-Mark ausgeführt, sodass Windows PowerShell 5.1 und PowerShell 7 es als UTF-8 lesen — Umlaute, ° und andere Nicht-ASCII-Zeichen kommen exakt so im Skript an, wie du sie geschrieben hast, und werden nie in einer Legacy-Codepage wie Windows-1252 uminterpretiert. Unter Linux und macOS wird das Skript als UTF-8 ohne BOM ausgeliefert, Windows-Zeilenenden werden normalisiert, damit die Shebang-Zeile gültig bleibt.
• Ausgabe: Beim eingebauten Custom-Script-Check erzwingt der Agent vor dem Lauf deines Skripts UTF-8 als PowerShell-Ausgabe-Encoding und erfasst stdout/stderr als UTF-8 — Nicht-ASCII-Ausgaben wie °C oder Umlaute erreichen das Dashboard unverändert. Bei selbstdefinierten Custom-Checks wird die Result-Payload als UTF-8-JSON serialisiert und Base64-kodiert zwischen den Result-Markern transportiert — konstruktionsbedingt immun gegen Output-Encoding-Probleme.
• Worauf du weiterhin achten musst: octoja ersetzt niemals Zeichen — was du einfügst, ist exakt das, was PowerShell oder bash parst. Editoren, Chat-Tools und Textverarbeitungen ersetzen gern gerade Anführungszeichen durch typografische (“ ”) und - oder -- durch Halbgeviert-/Geviertstriche (– —). Das sieht richtig aus, sind aber andere Zeichen; je nach Stelle im Skript führt das zu Syntaxfehlern oder still zu anderem Verhalten. Ersetze typografische Anführungszeichen und Striche durch ihre einfachen ASCII-Gegenstücke, bevor du den Check speicherst.

Skripte, die du über den Check-Importer übernimmst, können dieselben typografischen Zeichen aus ihrer ursprünglichen Quelle mitbringen — dort gilt derselbe Rat.

Verwandte Artikel

• Einen Custom-Script-Check konfigurieren — Schritt-für-Schritt-Anleitung für Autoren.