Check-Repository-Referenz

Repository-Typen, wie octoja sie synchronisiert und der registry.json-Aufbau, den ein Check-Repository veröffentlichen muss, damit seine Monitoring-Checks in der Check-Bibliothek erscheinen.

Check-Repository-Referenz

Ein Check-Repository ist eine Quelle für Monitoring-Check-Definitionen. octoja liest ein Repository, speichert dessen Check-Liste zwischen und zeigt die Checks in der Check-Bibliothek, damit du sie Geräten zuweisen kannst. Diese Referenz beschreibt die Repository-Typen, wie octoja sie synchronisiert und den genauen Aufbau, den ein Repository veröffentlichen muss. Die Schritt-für-Schritt-Anleitung zum Anbinden findest du unter Ein Community-Check-Repository anbinden.

Repository-Typen

Typ	Woher es stammt	Von einer URL synchronisiert?
Offiziell	octojas eigenes gepflegtes Repository unter `https://repo.octoja.com`. Standardmäßig vorhanden und schreibgeschützt.	Ja — von octoja verwaltet
Community	Ein Repository, das du per URL anbindest — eine Website von dir oder einem Dritten oder eine andere octoja-Instanz, die ihre eigenen Checks freigibt. Bearbeitbar, synchronisierbar und entfernbar.	Ja
Benutzerdefiniert	Deine eigenen Checks, in octoja unter Konfiguration → Check-Bibliothek erstellt.	Nein — sie liegen bereits in octoja

Wie die Synchronisation funktioniert

octoja synchronisiert jedes URL-basierte Repository automatisch einmal pro Stunde.
Die stündliche Synchronisation lädt nur, wenn die Registry des Repositories einen generated-Zeitstempel meldet, der neuer als deine letzte Synchronisation ist — ein unverändertes Repository wird übersprungen. Die manuelle Aktion Jetzt synchronisieren erzwingt immer eine vollständige Aktualisierung.
Jedes Repository wird unabhängig synchronisiert: ein nicht erreichbares oder fehlerhaftes Repository stoppt die anderen nicht, und eine fehlgeschlagene Synchronisation lässt die zuvor zwischengespeicherte Check-Liste unangetastet.
Bei jeder erfolgreichen Synchronisation ersetzt octoja den zwischengespeicherten Eintrag jedes Checks anhand der id, sodass Aktualisierungen eines Checks sich in die Check-Bibliothek übertragen. Ein aus der Registry entfernter Check bleibt in der Check-Bibliothek, bis du das Repository löschst.
Das UI-Manifest eines Checks wird nur dann erneut geladen, wenn die Registry eine uiVersion meldet, die sich von der zwischengespeicherten unterscheidet. Lässt eine Registry uiVersion weg, wird jedes Manifest bei jeder Synchronisation geladen, weil es nichts zu vergleichen gibt.
Nutzt das Repository HTTP-Basic-Authentifizierung, werden dieselben Zugangsdaten beim Abruf der Registry, beim Abruf des Manifests jedes Checks und bei jedem Binär-Download gesendet.

Was ein Repository veröffentlichen muss

Ein Check-Repository ist eine einfache HTTP- oder HTTPS-Website. octoja löst jeden Pfad gegen die Basis-URL auf, die du registrierst — nicht gegen die baseUrl in der registry.json — und erwartet:

Pfad (relativ zur Basis-URL)	Was es ist
`registry.json`	Der Index aller Checks, die das Repository anbietet. Wird bei jeder Synchronisation zuerst abgerufen.
`checks/{id}/{version}/ui.json`	Das UI-Manifest einer Check-Version — die Eingabefelder und die Ergebnisdarstellung.
die `downloadUri` jedes Executables	Das Check-Binary, das der Agent auf dem Gerät herunterlädt und ausführt.

Die gesamte Website darf hinter einem einzigen HTTP-Basic-Auth-Bereich liegen; gib die Zugangsdaten beim Anbinden des Repositories an. Ein Repository, das Zugangsdaten verlangt, muss über https:// veröffentlicht werden: einen Benutzernamen kombiniert octoja nur bei Loopback-Adressen wie localhost mit einfachem http://, und ein Passwort nimmt octoja nur zusammen mit einem Benutzernamen an.

registry.json

Feld	Typ	Beschreibung
`version`	string	Die eigene Versionskennung der Registry.
`generated`	timestamp	Wann die Registry erzeugt wurde. octoja vergleicht dies mit der letzten Synchronisation, um zu entscheiden, ob die stündliche Synchronisation laden muss. Erhöhe ihn, wann immer du eine Änderung veröffentlichst.
`baseUrl`	string	Die eigene Basis-URL des Repositories. Nur informativ: octoja löst die Pfade zu Manifest und Binaries gegen die URL auf, die du für das Repository registriert hast, nicht gegen diesen Wert.
`checks`	array	Ein Eintrag je Check, den das Repository anbietet (siehe unten).

{
  "version": "1.0",
  "generated": "2026-07-08T10:00:00Z",
  "baseUrl": "https://checks.example.com/",
  "checks": [
    {
      "id": "disk-temperature",
      "name": { "en": "Disk Temperature", "de": "Festplattentemperatur" },
      "description": { "en": "Reports the temperature of each drive.", "de": "Meldet die Temperatur jeder Festplatte." },
      "author": "Example MSP",
      "icon": { "type": "component", "library": "lucide", "name": "thermometer" },
      "category": "hardware",
      "tags": ["disk", "temperature"],
      "platforms": ["win-x64", "linux-x64"],
      "version": "1.2.0",
      "uiVersion": "9f2c41e7",
      "interval": 15,
      "timeoutSeconds": 120,
      "executionLocation": "Device",
      "executable": {
        "win-x64": {
          "downloadUri": "https://checks.example.com/checks/disk-temperature/1.2.0/win-x64/check.exe",
          "executableName": "check.exe",
          "fileType": "Exe",
          "executionType": "Exe"
        }
      }
    }
  ]
}

Felder einer Check-Definition

Jeder Eintrag in checks[] beschreibt einen Check. Lokalisierte Textfelder (name, description) nehmen ein Objekt mit den Schlüsseln en, de, fr und nl; en wird verwendet, wenn die Sprache des Lesers fehlt.

Feld	Typ	Beschreibung
`id`	string	Stabile Kennung des Checks. Dient als Schlüssel in der Check-Bibliothek und als Pfadsegment für Manifest und Binaries.
`name`	localized string	Anzeigename in der Check-Bibliothek.
`description`	localized string	Kurzbeschreibung auf der Check-Karte.
`author`	string	Autor oder Maintainer, auf der Karte angezeigt.
`icon`	object	Icon-Deskriptor. `{ "type": "component", "library": "lucide", "name": "<lucide-icon>" }` für ein eingebautes Icon oder `{ "type": "embedded", "name": "<svg-oder-base64>" }` für ein eingebettetes Bild.
`category`	string	Gruppierung in der Check-Bibliothek. Eine übersetzte Bezeichnung gibt es für `backup`, `hardware`, `network`, `services`, `security` und `custom`. Jeder andere Wert funktioniert ebenfalls, wird aber unübersetzt als Rohwert angezeigt.
`tags`	string array	Freie Tags für Suche und Filter der Bibliothek.
`platforms`	string array	Laufzeit-Kennungen, die der Check unterstützt (zum Beispiel `win-x64`, `linux-x64`, `osx-arm64`).
`version`	string	Die Version, die octoja anbietet. Zugleich das Pfadsegment `{version}` für UI-Manifest und Binaries.
`uiVersion`	string	Inhaltskennung der `ui.json` des Checks. Ändere sie, wenn sich nur das Manifest geändert hat — so erscheint eine neue Darstellung ohne neue `version`, und die Geräte laden kein identisches Binary erneut. Lässt du sie weg, ruft octoja das Manifest bei jeder Synchronisation ab.
`interval`	number	Standard-Ausführungsintervall in Minuten.
`timeoutSeconds`	number	Wie lange ein Durchlauf dauern darf, bevor er abgebrochen wird, in Sekunden. Standard: `300`.
`executionLocation`	string	`Device` (Standard) führt den Check auf dem Agent aus; `Server` wertet ihn serverseitig aus. Für einen normalen Geräte-Check weglassen.
`executable`	object	Zuordnung von Plattform-Kennung zum Binary für diese Plattform (siehe unten).

executable-Einträge

Feld	Beschreibung
`downloadUri`	Absolute URL, von der der Agent das Check-Binary herunterlädt.
`executableName`	Dateiname, unter dem das Binary auf dem Gerät abgelegt wird.
`fileType`	Was heruntergeladen wird: `Exe`, `Zip`, `Ps1` oder `Bash`. Jeder andere Wert wird als `Exe` gelesen.
`executionType`	Wie der Agent es ausführt: `Exe`, `PowerShell` oder `Bash`. Jeder andere Wert wird als `Exe` gelesen.

UI-Manifest je Check (ui.json)

octoja ruft das Manifest jedes Checks unter checks/{id}/{version}/ui.json ab, wobei {version} die version des Checks aus der Registry ist. Das Manifest definiert zwei Dinge:

input — die Parameter, die beim Zuweisen des Checks an ein Gerät angezeigt werden, per Parametername. Jedes Feld deklariert seinen Typ, den lokalisierten Titel und die Beschreibung, ob es erforderlich ist, einen Standardwert und (bei Auswahlfeldern) seine Optionen. Die Feldtypen sind string (der Rückfallwert für einen unbekannten Typ), text, password, integer, number, boolean, select, radio und array; separator zeichnet statt eines Feldes eine Trennlinie. Nutze password für Geheimnisse — der Wert wird in der Oberfläche maskiert und bei der Zuweisung gespeichert, muss also nie im Repository liegen. Ein Feld kann zusätzlich visibleIf tragen, um nur zu erscheinen, wenn ein anderes Feld einen bestimmten Wert hat.
output — wie das Ergebnis des Checks dargestellt wird: ein Detail-Renderer für den Checks-Tab des Geräts, ein History-Renderer für vergangene Ergebnisse und ein Widget-Renderer für Dashboard-Kacheln.

Die Eingabe-Schlüssel entscheiden außerdem, ob ein Check auf Netzwerkgeräten angeboten wird — Geräten, die ohne Agent von einem deiner vorhandenen Agenten überwacht werden. Ein Feld vom Typ string, dessen Schlüssel host, ip, ipaddress, target, url, endpoint oder address lautet (Groß- und Kleinschreibung spielt keine Rolle), oder ein Feld vom Typ array mit string-Einträgen und dem Schlüssel hosts, targets oder endpoints, markiert den Check als Abfrage eines entfernten Ziels. Ein solcher Check erscheint im Dialog Check hinzufügen eines Netzwerkgeräts; das Feld selbst wird dort ausgeblendet, und octoja setzt bei jedem Lauf die Adresse des Geräts ein. Der Typ muss exakt stimmen: text zählt nicht — trotz des Namens ist es kein Texteingabefeld, sondern eine statische Beschriftung zwischen den Feldern — und ebenso wenig zählt ein endpoints-Array, dessen Einträge Objekte statt Strings sind. Wie die Ersetzung zur Laufzeit funktioniert — einschließlich der SNMP-Zugangsdaten-Schlüssel —, beschreibt Einen Custom-Script-Check konfigurieren.

Ein Check, dessen UI-Manifest nicht abgerufen werden kann, wird trotzdem gelistet. Bei der ersten Synchronisation erscheint er ohne eigene Eingabefelder und Ergebnisdarstellung; bei einer späteren Synchronisation bleibt das Manifest erhalten, das octoja bereits hat — ein still gewordenes Repository lässt eine funktionierende Darstellung also unangetastet. Ein einzelnes unlesbares Manifest hält den Rest der Registry nicht auf.

Ergebnisprotokoll eines Checks

Jeder Check, der auf einem Gerät läuft, spricht dasselbe Protokoll — unabhängig davon, in welcher Sprache er geschrieben ist. octoja startet ihn gemäß seinem executionType — powershell -ExecutionPolicy Bypass -File bei PowerShell, bash bei Bash oder die heruntergeladene Datei selbst bei Exe — schreibt die Konfiguration des Checks auf die Standardeingabe und liest das Ergebnis von der Standardausgabe. Beachte: der PowerShell-Aufruf nutzt kein -NoProfile, ein systemweites PowerShell-Profil läuft also vor dem Check.

Aspekt	Verhalten
Eingabe	Die konfigurierten Eingabewerte als eine Zeile base64-kodiertes JSON auf der Standardeingabe, gefolgt von einem Zeilenumbruch; danach wird der Datenstrom geschlossen. Ein Check ohne konfigurierte Eingaben erhält die Base64-Kodierung von `{}`.
Ausgabe	Base64-kodiertes JSON auf der Standardausgabe. octoja liest die Bytes zwischen `<<<OCTO_RESULT_BEGIN>>>` und `<<<OCTO_RESULT_END>>>`. Fehlen diese Marker, wird ersatzweise die gesamte getrimmte Ausgabe als Nutzlast gelesen — ein Check ohne Marker bricht also, sobald irgendetwas anderes auf die Standardausgabe schreibt.
Status	Aus dem Feld `checkResult` des dekodierten JSON. Der Feldname wird ohne Beachtung der Groß- und Kleinschreibung erkannt, der Wert darf die Zahl oder der Statusname sein.
Exit-Code	Muss `0` sein. Bei einem Exit-Code ungleich null verwirft octoja die Ausgabe und meldet Failure, unabhängig vom Inhalt der Nutzlast.
Diagnose	Die Standardfehlerausgabe wird nicht ausgewertet. Der Agent legt sie in seinem Check-Log auf dem Gerät ab, sodass sie zur Fehlersuche verfügbar bleibt.
Größe	Die dekodierte Nutzlast ist auf 1 MB begrenzt. Darüber bleibt der Status erhalten, die Feldwerte entfallen.
Timeout	Der Durchlauf wird abgebrochen, sobald er `timeoutSeconds` (Standard `300`) überschreitet; der Check meldet dann Failure.
Arbeitsverzeichnis	Nicht auf den eigenen Ordner des Checks gesetzt. Ein Skript, das Dateien neben sich liest, muss deren Pfade ausdrücklich auflösen.

Werte von checkResult

Zahl	Name	Bedeutung
`0`	`Success`	Der überwachte Zustand ist in Ordnung.
`1`	`Warning`	Beachtenswert, aber noch nicht kritisch.
`2`	`Critical`	Der Check lief und hat einen kritischen Zustand festgestellt.
`3`	`Failure`	Der Check selbst konnte nicht korrekt ausgeführt werden.

Wer die Marker schreibt. Ein Check aus einem Repository wird unverändert heruntergeladen und ausgeführt — sein eigenes Skript muss die Marker also selbst um die Nutzlast setzen. Bei einem in octoja gebauten Custom-Script-Check ist es umgekehrt: octoja umhüllt das Skript und setzt die Marker selbst, und ein Skript, das sie ein zweites Mal schreibt, zerstört sein eigenes Ergebnis. Ein durchgearbeitetes Beispiel für einen Repository-Check, der dieses Protokoll umsetzt, findest du unter Ein eigenes Community-Check-Repository veröffentlichen.

Eine andere octoja-Instanz als Repository

Eine octoja-Instanz kann die eigenen Checks, die du auswählst, genau in diesem Format veröffentlichen — eine zweite Instanz bindet sie dann als Community-Repository an. Die Angaben dazu findest du auf der veröffentlichenden Instanz unter Einstellungen → Repository-Zugriff.

Aspekt	Was die veröffentlichende Instanz tut
Basis-URL	`<Instanz-Adresse>/api/custom-check-repository/`. Die Seite zeigt sie als Repository-URL an und kopiert sie in die Zwischenablage.
Authentifizierung	HTTP-Basic-Auth gegen Repository-Zugangsdaten. Jeder Pfad verlangt sie, die anbindende Instanz trägt also immer Benutzername und Passwort ein — und braucht damit eine `https://`-URL, sofern die Adresse keine Loopback-Adresse ist.
Welche Checks erscheinen	Nur die eigenen Checks, die unter Freigegebene eigene Checks für die verwendeten Zugangsdaten ausgewählt sind. Zwei Zugangsdaten derselben Instanz können unterschiedliche Auswahlen freigeben.
Versionen	octoja leitet `version` aus den Skripten des Checks und `uiVersion` aus seinem Manifest ab — wer ein Skript oder ein Ergebnis-Layout bearbeitet, veröffentlicht damit automatisch eine neue Version.
Berechtigung	Verwaltung benutzerdefinierter Checks (`custom-checks.manage`) auf der veröffentlichenden Instanz.

Ergebnisse des Verbindungstests

Die Schaltfläche Verbindung prüfen in den Dialogen zum Hinzufügen und Bearbeiten prüft das Repository über denselben Codepfad, den eine echte Synchronisation nutzt.

Meldung	Bedeutung
Verbunden — N Checks gefunden.	`registry.json` wurde abgerufen und gelesen. N ist die Anzahl der gelisteten Checks.
Verbindung fehlgeschlagen: Das Repository ist nicht erreichbar. Bitte URL und Netzwerkverbindung prüfen.	octoja konnte die URL nicht erreichen — falsche Adresse, Netzwerk-/DNS-/TLS-Problem oder abgelehnte Basic-Auth-Zugangsdaten.
Verbindung fehlgeschlagen: Das Repository hat geantwortet, aber die registry.json konnte nicht gelesen werden.	Die URL hat geantwortet, aber unter der Basis-URL kam keine lesbare `registry.json` zurück.

Berechtigungen

Berechtigung	Erforderlich für
Check-Repository-Verwaltung (`check-repositories.manage`)	Hinzufügen, Bearbeiten, Löschen und Synchronisieren von Check-Repositories.
Monitoring-Check-Verwaltung (`monitoring-checks.manage`)	Durchsuchen der Check-Bibliothek und Zuweisen der gelisteten Checks.
Verwaltung benutzerdefinierter Checks (`custom-checks.manage`)	Eigene Checks bauen sowie Repository-URL und Zugangsdaten unter Repository-Zugriff ausgeben.

octoja GmbH

Check-Repository-Referenz