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.

Geschrieben von Stefan Steuer

Zuletzt aktualisiert Vor 8 Tagen

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

TypWoher es stammtVon einer URL synchronisiert?
Offizielloctojas eigenes gepflegtes Repository unter https://repo.octoja.com. Standardmäßig vorhanden und schreibgeschützt.Ja — von octoja verwaltet
CommunityEin Repository, das du per URL anbindest. Bearbeitbar, synchronisierbar und entfernbar.Ja
BenutzerdefiniertDeine eigenen Checks, in octoja unter Konfiguration → Eigene Checks 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.
  • 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. Ausgehend von der Basis-URL, die du registrierst, erwartet octoja:

Pfad (relativ zur Basis-URL)Was es ist
registry.jsonDer Index aller Checks, die das Repository anbietet. Wird bei jeder Synchronisation zuerst abgerufen.
checks/{id}/{version}/ui.jsonDas UI-Manifest einer Check-Version — die Eingabefelder und die Ergebnisdarstellung.
die downloadUri jedes ExecutablesDas 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.

registry.json

FeldTypBeschreibung
versionstringDie eigene Versionskennung der Registry.
generatedtimestampWann 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.
baseUrlstringDie Basis-URL des Repositories.
checksarrayEin 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",      "interval": 15,      "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.

FeldTypBeschreibung
idstringStabile Kennung des Checks. Dient als Schlüssel in der Check-Bibliothek und als Pfadsegment für Manifest und Binaries.
namelocalized stringAnzeigename in der Check-Bibliothek.
descriptionlocalized stringKurzbeschreibung auf der Check-Karte.
authorstringAutor oder Maintainer, auf der Karte angezeigt.
iconobjectIcon-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.
categorystringGruppierung in der Check-Bibliothek (zum Beispiel hardware, network, services, security).
tagsstring arrayFreie Tags für Suche und Filter der Bibliothek.
platformsstring arrayLaufzeit-Kennungen, die der Check unterstützt (zum Beispiel win-x64, linux-x64, osx-arm64).
versionstringDie Version, die octoja anbietet. Zugleich das Pfadsegment {version} für UI-Manifest und Binaries.
intervalnumberStandard-Ausführungsintervall in Minuten.
executionLocationstringDevice (Standard) führt den Check auf dem Agent aus; Server wertet ihn serverseitig aus. Für einen normalen Geräte-Check weglassen.
executableobjectZuordnung von Plattform-Kennung zum Binary für diese Plattform (siehe unten).

executable-Einträge

FeldBeschreibung
downloadUriAbsolute URL, von der der Agent das Check-Binary herunterlädt.
executableNameDateiname, unter dem das Binary auf dem Gerät abgelegt wird.
fileType / executionTypeTeilen dem Agent mit, um welche Art von Artefakt es sich handelt und wie es auszuführen ist.

UI-Manifest je Check (ui.json)

Für jeden Check ruft octoja checks/{id}/{version}/ui.json ab. 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.
  • 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.

Ein Check, dessen UI-Manifest nicht abgerufen werden kann, wird trotzdem gelistet — jedoch ohne seine eigenen Eingabefelder und Ergebnisdarstellung.

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.

ErgebnisBedeutung
Verbunden — N Checks gefundenregistry.json wurde abgerufen und gelesen. N ist die Anzahl der gelisteten Checks.
Repository nicht erreichbaroctoja konnte die URL nicht erreichen — falsche Adresse, Netzwerk-/DNS-/TLS-Problem oder abgelehnte Basic-Auth-Zugangsdaten.
Ungültige RegistryDie URL hat geantwortet, aber unter der Basis-URL konnte keine gültige registry.json gelesen werden.

Berechtigungen

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

Verwandte Artikel