Benutzerdefiniertes Skript

Der Check Benutzerdefiniertes Skript führt ein einzelnes Skript aus — PowerShell unter Windows, bash unter Linux und macOS — und wandelt dessen Exit-Code in einen Status um. Er läuft alle 15 Minuten unter Windows, Linux und macOS (jeweils als x64- und Arm64-Build), und du weist ihn über ein Konfigurationspaket einem Gerät zu. Er hat die Plugin-Kennung custom-script.

Brauchst du typisierte Eingaben, typisierte Ausgaben oder den gebündelten SNMP-Worker, baust du stattdessen einen eigenen Check unter Konfiguration → Check-Bibliothek. octoja umhüllt dessen Skript bei der Auslieferung mit einem Wrapper; der Check läuft in einem festen Intervall, meldet ein Ergebnis an octoja zurück und erscheint danach neben den eingebauten Checks, wenn du Checks einem agentenverwalteten Gerät zuweist. Für ein Netzwerkgerät braucht er einen zusätzlichen Parameter — siehe Den Check für Netzwerkgeräte verfügbar machen weiter unten.

Die beiden Wege teilen weder den Status-Mechanismus noch den Ausgabevertrag: Benutzerdefiniertes Skript wertet den Exit-Code aus, ein eigener Check das Feld checkResult seiner Ausgabe. Lies jeweils den Abschnitt, der zum konfigurierten Check passt.

Voraussetzungen

Für eigene Checks:

• Du benötigst Monitoring-Check-Verwaltung für die Check-Bibliothek und zusätzlich Verwaltung benutzerdefinierter Checks, um einen eigenen Check anzulegen oder zu bearbeiten.
• Monitoring-Check-Verwaltung ist auch für die Live-Test-Leiste des Editors (Schritt 8) und das Zuweisen des Checks an ein Gerät (Schritt 10) erforderlich.
• Du brauchst ein Zielgerät, auf dem der Agent installiert und verbunden ist. Bei einem Netzwerkgerät — einem Switch, Router oder einer Firewall ohne eigenen Agenten — ist das sein Überwachungsgerät, also der Agent, der es für dich abfragt.
• Unter Linux benötigt der Skript-Wrapper des Agents jq zum Lesen der Parameter und zum Serialisieren der Ausgabe. Der Linux-Installer des Agents installiert jq für dich, wenn apt, dnf oder yum verfügbar ist; auf einer aktuellen Installation ist es also bereits vorhanden. Von Hand nachinstallieren musst du es nur auf Agents, die davor installiert wurden, oder wenn der Installer keinen unterstützten Paketmanager gefunden hat. Unter macOS nutzt der Wrapper das eingebaute osascript, dort ist also nichts zu installieren.
• Jedes weitere Tool, das dein Skript aufruft (zum Beispiel awk, bc), muss ebenfalls auf dem Zielgerät installiert sein — der Agent bringt skript-seitige Abhängigkeiten nicht selbst mit.

Schritte

So baust du einen eigenen Check und weist ihn zu:

1. Öffne Konfiguration → Check-Bibliothek in der Seitenleiste. Mit Nur eigene Checks findest du vorhandene eigene Checks; ein Klick öffnet ihren Editor. Repository-Verbindungen und Repository-Zugriffe verwaltest du unter Einstellungen, nicht im Check-Editor.
2. Klicke auf Neuer Check.
3. Gib einen Namen ein. octoja leitet daraus automatisch eine eindeutige Check-ID ab. Optional kannst du unter Klonen von einen bestehenden Check als Kopiervorlage wählen. Klicke auf Check erstellen.
4. Lasse im Tab Allgemein den Modus auf Erweitertes Skript (die Alternative Einfaches SNMP ersetzt die Skript-Tabs durch einen SNMP-Editor; siehe den Abschnitt unten). Setze Beschreibung, Symbol, Kategorie, Tags, das Check-Intervall in Minuten — Standard 5, erlaubter Bereich 5–1440 — und das Timeout in Minuten, also die maximale Dauer eines einzelnen Laufs (Standard 5, erlaubter Bereich 5 Sekunden bis 60 Minuten).
5. Öffne den Tab Skript. Füge für jede Plattform, die du unterstützen möchtest (Windows / Linux / macOS), dein Skript ein — Beispiele weiter unten. Plattformen ohne Skript stehen nicht zur Zuweisung bereit. Schreibe nur deine Check-Logik: Der Agent ergänzt die Ein-/Ausgabe-Behandlung automatisch.
6. Öffne den Tab Parameter und definiere alle Eingabeparameter, die dein Skript benötigt (Schlüssel, Typ, Beschriftungen, Pflichtfeld, Standardwert). Sie erscheinen als konfigurierbare Felder, sobald der Check einem Gerät zugewiesen wird. Soll der Check auch auf Netzwerkgeräten auswählbar sein, muss einer davon ein Host- oder Ziel-Parameter sein — siehe Den Check für Netzwerkgeräte verfügbar machen weiter unten.
7. Öffne den Tab Ausgabe-Schema und deklariere die Felder, die dein Skript schreibt — Schlüssel, Typ, Einheit und Label. Über die Tabs Detail-Layout und Verlaufs-Layout legst du fest, wie diese Felder auf dem Checks-Tab des Geräts angezeigt werden. Optional gestaltest du unter Ergebnistext einen Kurztext und eine ausführliche Beschreibung; siehe Ergebnistexte eigener Checks. Die Textvorschau führt kein Skript aus; dafür nutzt du den Live-Test im nächsten Schritt.
8. Nutze die Live-Test-Leiste oben im Editor: Wähle ein verbundenes Gerät aus und klicke auf Ausführen. Definiert der Check Parameter, öffnet sich zuerst der Dialog Testeingabe — fülle ihn aus und klicke auf Test starten. Anschließend zeigt ein Badge den Check-Status — OK, Warnung, Kritisch oder Fehlgeschlagen — samt Laufzeit in Millisekunden; klicke darauf, um die Details der Testausführung zu öffnen (Testausführung erfolgreich bzw. Testausführung fehlgeschlagen) — mit Prüfergebnis, der Rohausgabe des Skripts, etwaigen Fehlern und der Geparsten Ausgabe — ohne auf ein Check-Intervall zu warten.
9. Klicke auf Speichern.
10. Weise den Check zu: Gehe zu Geräte, öffne das Zielgerät, klicke auf den Tab Checks → Check hinzufügen, wähle deinen eigenen Check aus (er erscheint neben den eingebauten Checks — bei einem Netzwerkgerät nur, wenn er einen Host-Parameter deklariert), fülle die von dir definierten Parameter aus und klicke auf Check hinzufügen.

Einstellungen

Benutzerdefiniertes Skript

Der Agent schreibt dein Skript in eine kurzlebige Skriptdatei, führt sie als Kindprozess aus — powershell -NoProfile -NonInteractive -ExecutionPolicy Bypass -File <script>.ps1 unter Windows, bash <script>.sh unter Linux und macOS — und löscht die Datei danach wieder. Keine Helper, keine Sentinel-Marker: Der Check stützt sich auf den Exit-Code und eine kleine stdout/stderr-Erfassung.

Unter Windows hängt der Agent eine Zeile an, die den Exit-Code aus $LASTEXITCODE und $? neu ableitet. Der -File-Modus von PowerShell endet sonst mit 0, selbst wenn die letzte Anweisung einen nicht-terminierenden Fehler ausgelöst hat — ein kaputtes Skript würde also als Success gemeldet. Ein explizites exit oder throw in deinem Skript gewinnt weiterhin; ein abschließendes Write-Error oder ein fehlschlagendes letztes Cmdlet ergibt Exit-Code 1.

Eigene Checks

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

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.

Ergebnisse

Benutzerdefiniertes Skript

Der Exit-Code bestimmt das Ergebnis:

SuccessExitCode ist ein einzelner Code, keine Liste — genau ein Exit-Code kann Success bedeuten. Die Warning- und Critical-Listen nehmen beliebig viele Codes auf: Ein Legacy-Werkzeug, das bei einem leichten Problem 3 zurückgibt, ordnest du zu, indem du 3 in WarningExitCodes aufnimmst. 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.

Bei jedem Lauf liefert der Check diese Felder an octoja:

Eigene Checks

Dein Skript meldet seinen Status, indem es checkResult in der Ausgabe setzt — $output.checkResult in PowerShell, set_result in bash. Der Startwert ist 0 (OK); ein Skript, das nichts setzt, meldet also OK. Umhüllte Checks nutzen kein Exit-Code-Mapping; der Agent decodiert checkResult in eine CheckResultStatus-Enum:

Du kannst den Status auch per Name statt per Zahl setzen: $output.checkResult = "Critical" (PowerShell) oder set_result Critical (bash). String-Werte sind beim Decodieren case-insensitive.

Ausgaben bis 1 MB werden vollständig als aktuelles Ergebnis des Checks gespeichert, die aktuellen Werte werden also immer angezeigt. Begrenzt ist nur die historisierte Kopie: Ein Ergebnis, dessen Ausgabe größer als 16 KB ist, wird im Verlauf des Checks nur als Status abgelegt.

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.

Wie der Agent eigene Checks ausführt

• Der Agent lädt dein Skript inklusive des Ein-/Ausgabe-Wrappers vom Webservice herunter, speichert es als Datei und führt es mit powershell -ExecutionPolicy Bypass -File unter Windows bzw. bash unter Linux und macOS aus.
• Das Skript läuft mit den Rechten des Agent-Dienstes: als SYSTEM unter Windows und als root unter Linux und macOS.
• Die bei der Zuweisung konfigurierten Parameter werden dem Skript über die Standardeingabe übergeben; der Wrapper dekodiert sie und stellt sie bereit ($checkInput / INPUT_JSON), du liest sie über $checkInput (PowerShell) oder get_input (bash).
• Der Wrapper belegt den Ausgabe-Container mit checkResult = 0 vor ($output / _OCTO_OUTPUT). Nachdem dein Skript gelaufen ist, serialisiert er die Ausgabe nach base64 und gibt sie zwischen den Result-Markern aus. Der Agent extrahiert nur die Bytes zwischen <<<OCTO_RESULT_BEGIN>>> und <<<OCTO_RESULT_END>>>; alles andere, was auf stdout landet — Write-Output, Write-Host, echo oder ConvertTo-Json —, wird ignoriert und bricht den Wrapper nicht.
• Der Status kommt aus dem checkResult-Wert deiner Ausgabe — nicht aus Text, den dein Skript ausgibt, und nicht aus dem Exit-Code.
• Der Wrapper führt dein Skript in einem try/finally (PowerShell) beziehungsweise hinter einem EXIT-Trap (bash) aus, sodass die Result-Payload auch dann geschrieben wird, wenn dein Skript exit oder return aufruft. Ein Exit-Code ungleich Null lässt den Check aber Fehlgeschlagen melden und verwirft die gesamte strukturierte Ausgabe — unabhängig davon, welchen Status oder welche Felder das Skript zuvor gesetzt hat. exit 0 und return sind unbedenklich; exit 1 wirft alles weg, was du gesetzt hast.
• Jeder Lauf wird gestoppt, sobald er das Timeout des Checks überschreitet (Tab Allgemein) — Standard 5 Minuten, bis auf 60 Minuten erhöhbar — und der Check meldet Fehlgeschlagen.
• Oberhalb von 1 MB behält das Ergebnis seinen Status, aber die Feldwerte werden verworfen und es wird als gekürzt markiert.

Skripte für eigene Checks schreiben

PowerShell (Windows)

Der Wrapper stellt $checkInput (die geparsten Eingabeparameter) und $output (eine Hashtable, vorbelegt mit checkResult = 0) bereit. Schreibe deine Ergebnisse in $output. Achtung: Die Variable heißt $checkInput, nicht $input — $input ist eine reservierte automatische PowerShell-Variable.

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.

# Einen Eingabeparameter lesen (im Tab Parameter definiert)
$threshold = $checkInput.threshold

# Arbeit erledigen
$cpuLoad = (Get-Counter '\Processor(_Total)\% Processor Time').CounterSamples.CookedValue

# Ergebnisse in $output schreiben
$output["cpuLoad"] = [math]::Round($cpuLoad, 1)
if ($cpuLoad -ge $threshold) {
    $output["checkResult"] = 2  # Kritisch
    $output["message"] = "CPU-Auslastung $cpuLoad% überschreitet Schwellenwert $threshold%"
} elseif ($cpuLoad -ge ($threshold * 0.8)) {
    $output["checkResult"] = 1  # Warnung
} else {
    $output["checkResult"] = 0  # OK
}

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)

Der Wrapper stellt diese Helper bereit:

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.

THRESHOLD=$(get_input "threshold")
LOAD=$(uptime | awk -F'load average:' '{print $2}' | awk -F',' '{print $1}' | xargs)
set_output "loadAverage" "$LOAD"
if (( $(echo "$LOAD > $THRESHOLD" | bc -l) )); then
    set_result 2   # Kritisch
    set_output "message" "Load Average $LOAD überschreitet Schwellenwert $THRESHOLD"
else
    set_result 0   # OK
fi

Bash (macOS)

Unter macOS verwendet der Agent einen separaten Wrapper mit identischer Schnittstelle — get_input, set_output, set_result und dieselben flag-basierten snmp_get / snmp_walk, wenn OCTOJA_WORKER_BIN gesetzt ist. Er baut aber auf dem in macOS eingebauten osascript statt auf jq auf und vermeidet bash-Funktionen, die das mit macOS ausgelieferte bash 3.2 nicht unterstützt. Auf dem Mac muss dafür nichts zusätzlich installiert werden, und selbst wenn dein Skript mitten im Lauf beendet wird oder abstürzt, entsteht noch ein sauberer Result-Envelope. Dein Skript-Code sieht genauso aus wie im Linux-Beispiel oben.

Wenn du kein macOS-spezifisches Skript hinterlegst, führt der Agent dein Linux-Skript auch auf macOS aus. Das funktioniert für portables bash, scheitert aber, sobald du auf ein Linux-spezifisches Tool angewiesen bist.

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).

Einige Schlüssel sind bei Netzwerkgeräten reserviert: Host- und Ziel-Schlüssel sowie SNMP-Zugangsdaten werden dort von octoja belegt. Verwende diese Schlüsselnamen deshalb für nichts anderes — siehe Den Check für Netzwerkgeräte verfügbar machen.

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.

Alternative: SNMP-Werte ohne Alarmregeln erfassen

Wenn du nur SNMP-OIDs abfragen möchtest, wähle im Tab Allgemein den Modus Einfaches SNMP statt eines Skripts. Lege im SNMP-Editor die OIDs mit Ausgabefeld und Werttyp an. Warn- und Kritisch-Schwellen für Zahlen sowie Textmuster für Zeichenketten sind optional: Lasse sie leer, um einen Wert nur anzuzeigen oder in ein eigenes Feld zu schreiben, ohne ihn gegen Alarmregeln zu prüfen. Fehlende OIDs, Abfragefehler oder ein nicht numerischer Wert für eine numerische OID bleiben Fehler. Prüfe die Ausgabe mit Live-Test, speichere den Check und weise ihn dem Zielgerät zu.

Bei sinkenden numerischen SNMP-Werten alarmieren

Wähle für die Batterieladung den numerischen OID-Typ und unter Auslösen wenn die Option Wert ≤ Schwellenwert. Setze Warnung ab auf 50 und Kritisch ab auf 20. Gib Zahlen ein, keine Nagios-Ausdrücke wie 50:.

Der Vergleich schließt den Schwellenwert selbst ein. Für strikt „unter 50“ und „unter 20“ nutze ein erweitertes Skript — oder 49 und 19, aber nur wenn das Gerät ausschließlich ganze Prozentwerte liefert. Eine andere OID kann den Gesamtstatus des Checks weiterhin verschlechtern.

Der Fortschrittsbalken im Detail-Layout ist von dieser Statusauswertung getrennt: Seine Farbschwellen bewerten derzeit höhere Werte als schlechter und lassen sich nicht umkehren. Nutze für die verbleibende Ladung eine reine Zahlenanzeige, statt die Balkenfarbe einer vollen Batterie als Check-Ergebnis zu deuten.

Den Check für Netzwerkgeräte verfügbar machen

Ein Netzwerkgerät, das du ohne Agent-Installation hinzugefügt hast — ein Switch, ein Router oder eine Firewall —, hat keinen eigenen Agenten. Seine Checks laufen auf dem Überwachungsgerät, das du beim Hinzufügen des Geräts ausgewählt hast: Dieser Agent fragt das Gerät über das Netzwerk ab, und Ergebnis und Verlauf bleiben beim Netzwerkgerät. Derselbe Filter gilt für die eingebauten Checks, weshalb der Katalog eines Netzwerkgeräts deutlich kürzer ist als der eines agentenverwalteten Geräts. Auch ein eigener Check kann ein Netzwerkgerät überwachen — aber nur, wenn du ihn dafür baust.

Einen Host- oder Ziel-Parameter deklarieren

octoja bietet einen eigenen Check für ein Netzwerkgerät nur dann an, wenn der Check einen Parameter vom Typ Text deklariert, dessen Schlüssel host, ip, ipaddress, target, url, endpoint oder address lautet, oder einen Parameter vom Typ Tag List mit dem Schlüssel hosts, targets oder endpoints. Die Groß- und Kleinschreibung des Schlüssels spielt keine Rolle, Host und ipAddress zählen also ebenfalls.

Der Schlüssel muss exakt passen — targetHost, firewallIp und andere Namen, die einen der Schlüssel nur enthalten, zählen nicht.

Kein anderer Typ zählt: nicht Number, nicht Password, nicht Dropdown und nicht Toggle. Eine Tag List zählt nur mit einem der Schlüssel hosts, targets oder endpoints — ein host-Parameter vom Typ Tag List zählt nicht. Bei einer passenden Tag List trägt octoja die IP-Adresse des Geräts als einzigen Eintrag ein.

Dieser Parameter ist das Signal, dass der Check ein entferntes Ziel abfragt. Ein Check ohne ihn erscheint im Dialog Check hinzufügen eines Netzwerkgeräts überhaupt nicht — er fehlt schlicht, ohne Meldung und ohne ausgegrauten Eintrag. Auch der Tab Parameter weist nicht darauf hin, dass der Schlüssel eine Rolle spielt. Denk deshalb zuerst an diese Regel, wenn sich ein gerade gebauter Check auf einer Firewall nicht auswählen lässt.

Den Parameter musst du nicht selbst ausfüllen. Auf einem Netzwerkgerät blendet octoja das Feld aus und trägt die IP-Adresse des Geräts ein, sobald der Check an den Agenten übergeben wird — stattdessen zeigt der Dialog den Hinweis Die IP-Adresse und die hinterlegten Verbindungseinstellungen des Geräts werden automatisch verwendet. Dein Skript liest den Parameter wie jeden anderen, mit $checkInput.host oder get_input "host". Änderst du später die IP des Geräts, übernimmt der Check sie beim nächsten Abgleich der Zuweisungen, also innerhalb von etwa einer halben Stunde.

Über ein Konfigurationspaket läuft das anders. Der Katalog des Pakets wird überhaupt nicht gefiltert, ein Check ohne Host-Parameter lässt sich also auch einem Paket hinzufügen, das nur auf Firewalls passt — er wird zugewiesen und ausgeführt, und weil ihn nichts auf das Gerät richtet, meldet er unbemerkt das Überwachungsgerät. Dort bleibt der Host-Parameter sichtbar und ist als optional markiert: Lässt du ihn leer, trägt octoja die Adresse des jeweils passenden Netzwerkgeräts ein, sobald der Check an dessen Agenten übergeben wird. Bei einem agentenverwalteten Gerät, auf das dasselbe Paket passt, geschieht das nicht — dort bleibt ein leeres Host-Feld leer.

Einen Parameter ergänzen statt umbenennen

Wenn dein Check bereits einen Parameter für das Ziel hat — etwa firewallAddress —, benenne ihn nicht in ip um, nur damit die Regel erfüllt ist. octoja belegt jeden Parameter, der zugleich auf der Schlüsselliste steht und vom Typ Text ist: Auf einem Netzwerkgerät wird das Feld ausgeblendet und sein Wert durch die IP-Adresse des Geräts ersetzt — was du vorher darüber übergeben hast, geht damit verloren. Der Check läuft und meldet weiterhin, und genau das macht es leicht, den Fehler zu übersehen.

Lege stattdessen einen zusätzlichen host-Parameter neben deinen eigenen an. Der Check funktioniert dann auf beiden Gerätearten — bei einem Netzwerkgerät füllt octoja host für dich aus, bei einem agentenverwalteten Gerät füllst du ihn selbst aus.

Das Gerät aus deinem Skript heraus erreichen

octoja übergibt deinem Skript die Adresse des Geräts, nimmt dir den Zugriff darauf aber nicht ab. Alles, was der Check misst, muss dein Skript selbst über das Netzwerk von dieser Adresse holen. Die Beispiele weiter oben lesen die Maschine aus, auf der das Skript läuft — kopierst du eines davon in einen Check für ein Netzwerkgerät, meldet er die CPU-Auslastung oder die Last des Überwachungsgeräts unter dem Namen der Firewall. Der Check wird grün und sagt dir nichts über die Firewall. Nutze den Host-Parameter in jedem Befehl, der Werte abruft.

Ein Beispiel: einen Wert über SNMP lesen

Deklariere einen Text-Parameter host und einen Text-Parameter community — beide füllt octoja bei einem Netzwerkgerät für dich aus — und erreiche das Gerät dann über den Helper Get-Snmp des Wrappers, der die angefragten OIDs als Nachschlagetabelle zurückgibt:

# 1.3.6.1.2.1.1.3.0 ist sysUpTime, in Hundertstelsekunden
$oid  = '1.3.6.1.2.1.1.3.0'
$snmp = Get-Snmp -TargetHost $checkInput.host -Community $checkInput.community -Oid $oid
$uptimeHours = [math]::Round([double]$snmp[$oid] / 360000, 1)

$output["uptimeHours"] = $uptimeHours
if ($uptimeHours -lt 1) {
    $output["checkResult"] = 1  # Warnung — das Gerät ist in der letzten Stunde neu gestartet
    $output["message"] = "Firewall vor $uptimeHours h neu gestartet"
}

In bash lautet derselbe Aufruf snmp_get --host "$(get_input "host")" --community "$(get_input "community")" 1.3.6.1.2.1.1.3.0. Beide Helper laufen über den mitgelieferten SNMP-Worker des Agents; die vollständige Helper-Referenz steht unter Skripte für eigene Checks schreiben.

SNMP-Zugangsdaten kommen vom Gerät

Deklariert dein Check einen Parameter namens community, v3User, authPassword oder privPassword, übernimmt octoja seinen Wert aus den auf dem Netzwerkgerät hinterlegten SNMP-Einstellungen — zusammen mit jedem version-, snmpVersion-, authProtocol-, privProtocol-, port- oder snmpPort-Parameter, den der Check deklariert. So musst du die Zugangsdaten nicht für jedes Gerät erneut eingeben. Mindestens einer dieser vier Zugangsdaten-Schlüssel muss vorhanden sein: Ein Check, der nur port oder version deklariert, bleibt unangetastet.

Übernommen wird nur, was das Gerät tatsächlich gespeichert hat. Ein Gerät, das über TR-064 angebunden ist oder bei dem SNMP ausgeschaltet ist, liefert nichts — dort gelten deine eingetragenen Werte. Und auf einem v2c-Gerät, das nur eine Community speichert, behält ein deklariertes authPassword ebenfalls das, was du eingetragen hast.

Diese Felder verhalten sich anders als der Host-Parameter. Sie bleiben im Dialog Check hinzufügen sichtbar und bearbeitbar, und der Checks-Tab des Geräts zeigt weiterhin das an, was du eingetragen hast — der Lauf verwendet aber das, was auf dem Gerät gespeichert ist. Verwende diese Schlüsselnamen deshalb für nichts anderes.

Die Skript-Plattform auf das Überwachungsgerät abstimmen

Da das Skript auf dem Überwachungsgerät läuft, braucht der Check ein Skript für das Betriebssystem dieses Agenten — nicht für das Netzwerkgerät, das selbst nie etwas ausführt.

Der Katalog eines Netzwerkgeräts filtert nicht nach Plattform, denn das Gerät hat kein Betriebssystem, nach dem sich filtern ließe. Ein reiner Windows-Check wird deshalb auch für eine Firewall angeboten, deren Überwachungsgerät unter Linux läuft — und liefert nach der Zuweisung überhaupt kein Ergebnis: Der Agent verwirft die Zuweisung, sobald er seine Check-Liste lädt, und am Check selbst ist davon nichts zu sehen. Vergleiche die Plattform-Badges neben jedem Check im Katalog mit dem Betriebssystem des Überwachungsgeräts, bevor du ihn zuweist, und ergänze im Tab Skript ein Skript für diese Plattform.

Den Check auf dem Netzwerkgerät testen

Wähle in der Live-Test-Leiste des Editors das Netzwerkgerät selbst aus. octoja leitet das Skript an dessen Überwachungsgerät weiter, wählt die Skript-Variante nach dem Betriebssystem dieses Agenten und trägt in den Host-Parameter die IP-Adresse des Geräts ein — ein grüner Live-Test auf dem Netzwerkgerät bestätigt damit Parameter, Plattform und Skript in einem Schritt. Du brauchst dafür die Berechtigung, Skripte sowohl auf dem Netzwerkgerät als auch auf seinem Überwachungsgerät auszuführen. Die Auswahl listet nur Geräte, die online sind — ein Netzwerkgerät, dessen Online-Status-Check gerade fehlschlägt, taucht dort nicht auf.

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 Check Benutzerdefiniertes Skript 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 eigenen 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.

Was du nicht tun solltest

Troubleshooting

Der Check zeigt Fehlgeschlagen mit einer Fehlermeldung. Das Skript hat sich mit einem Exit-Code ungleich Null beendet, einen Fehler geworfen, oder auf einem Linux-Gerät fehlt jq — der Check meldet dann, dass jq nicht installiert ist. Der Linux-Installer des Agents installiert jq automatisch; auf einem Agent, der davor installiert wurde, ergänzt du es mit apt install jq oder dnf install jq. Führe das Skript über die Live-Test-Leiste des Editors aus: Die Fehlerausgabe erscheint unter Fehler in den Details der Testausführung.

Der Check zeigt OK, obwohl du Warnung oder Kritisch erwartet hast. Wahrscheinlich hast du vergessen, $output["checkResult"] (PowerShell) zu setzen oder set_result (bash) aufzurufen — der Standard ist 0 / OK. Prüfe außerdem die Werte: 1 ist Warnung und 2 ist Kritisch.

Der Check meldet Fehlgeschlagen, nachdem er lange gelaufen ist. Das Skript hat das Timeout des Checks überschritten (Tab Allgemein, Standard 5 Minuten). Erhöhe das Timeout — auf bis zu 60 Minuten —, mache das Skript schneller oder teile es in mehrere kleinere Checks auf.

Das Dashboard zeigt den Status, aber keine Werte. Die Feldschlüssel, die dein Skript schreibt, müssen den im Tab Ausgabe-Schema deklarierten Schlüsseln entsprechen, und sehr große Ausgaben (über 1 MB) werden auf den Status gekürzt. Im Verlauf des Checks werden Ergebnisse über 16 KB nur als Status abgelegt, ein vergangener Lauf kann also einen Status ohne Werte anzeigen.

Der Check lässt sich auf einem Netzwerkgerät nicht auswählen. Der Check deklariert keinen Host- oder Ziel-Parameter und wird deshalb aus dem Dialog Check hinzufügen für Netzwerkgeräte herausgefiltert. Lege im Tab Parameter einen an: einen Parameter vom Typ Text mit dem Schlüssel host — exakt dieser Schlüssel, nicht eine Annäherung wie targetHost. Stimmt der Schlüssel bereits, prüfe den Typ — host zählt nur als Text; eine Tag List zählt nur mit dem Schlüssel hosts, targets oder endpoints.

Der Check ist einem Netzwerkgerät zugewiesen, liefert aber nie ein Ergebnis. Der Check hat kein Skript für das Betriebssystem, unter dem das Überwachungsgerät läuft — etwa ein reiner PowerShell-Check, der über ein Linux-Überwachungsgerät ausgeführt werden soll. Wie oben beschrieben verwirft der Agent die Zuweisung stillschweigend. Führe ihn zur Bestätigung direkt aus — über die Play-Schaltfläche neben dem Eintrag im Checks-Tab des Geräts; dafür brauchst du die Geräteaktion Wartung ausführen. Bei einer nicht unterstützten Plattform meldet er Dieser Check wird vom Betriebssystem des Zielgeräts nicht unterstützt. Ergänze im Tab Skript ein Skript für diese Plattform.

Der Check auf einem Netzwerkgerät meldet die Werte der falschen Maschine. Das Skript läuft auf dem Überwachungsgerät; jeder Befehl, der das lokale System ausliest, misst also diesen Agenten statt des Netzwerkgeräts. Hole jeden Wert stattdessen über das Netzwerk, mit der Adresse aus dem Host-Parameter.

Ein eigener Check liefert keine Ergebnisse auf dem Gerät. Am schnellsten prüfst du ihn über die Live-Test-Leiste des Editors: Wähle ein verbundenes Gerät aus und klicke auf Ausführen, um Status, Laufzeit, Ausgabe und geparste Felder sofort zu sehen. Nach der Zuweisung führt octoja den Check im konfigurierten Intervall aus; das Ergebnis siehst du im Checks-Tab des Geräts im von dir definierten Layout. Liefert der Check dort kein Ergebnis, prüfe das Agent-Log auf Skriptfehler — bei einem Netzwerkgerät liegt dieses Log auf seinem Überwachungsgerät, denn das Netzwerkgerät selbst führt nichts aus.

Verwandte Artikel

• Ein Netzwerkgerät ohne Agent hinzufügen — wie Netzwerkgeräte und Überwachungsgeräte zusammenspielen.

FAQ