Files
rust-discovery/proto/BACKEND_CONTRACT.md
T
2026-11-18 18:46:04 +01:00

4.8 KiB

Geräteprotokoll und Skriptaufträge

Linux- und Windows-Agenten bauen die Verbindung zum Gateway ausgehend auf. Eine eingeschriebene Installation authentisiert sich mit ihrem Clientzertifikat. Der Server ermittelt daraus Kunde und Agent. Die Nachrichtenfelder stehen in der Protobuf-Datei und den zugehörigen Rust-Typen. Gateway-Routen · Nachrichtenformat · Rust-Typen

Nachrichten auf dem Gerätekanal

HTTPS-Endpunkt Anfrage Antwort
POST /agent/v1/messages Ein ClientHello eröffnet die Verbindung. Weitere MessageBatch-Anfragen übertragen unter anderem Inventar, Abgleich, Auftragsstatus und Ergebnisse. Ein MessageBatch enthält die Antworten des Servers.
POST /agent/v1/poll Ein PollRequest enthält einen Heartbeat und die gewünschte Wartezeit von 0 bis 25 Sekunden. Das Gateway bestätigt den Heartbeat und liefert vorhandene Arbeit mit derselben Antwort. Im Leerlauf genügt die Bestätigung.

Heartbeats können eine passive Ressourcenmessung übermitteln. cpu_usage_basis_points liegt zwischen 0 und 10.000, ram_available_bytes und ram_total_bytes bilden gemeinsam einen Messwert. Das Gateway speichert je authentisierter Installation den letzten gültigen CPU-Wert und das letzte gültige RAM-Wertepaar mit ihrem jeweiligen Zeitpunkt. Ein zusätzlicher Poll-Heartbeat ohne Ressourcendaten lässt die gespeicherten Messwerte bestehen.

Beide Endpunkte verwenden application/x-protobuf und Protokollversion 1. Eine Nachricht trägt unter anderem die Gerätekennung, die Generationen von Einschreibung und Verbindung, die Boot-ID, Sequenznummer und Nachrichten-ID. Für gespeicherte Meldungen wie ein Skriptergebnis bestätigt der Server die ursprüngliche Nachrichten-ID. HTTP-Verarbeitung · Speicherung und Bestätigung

Vom Antrag bis zum Ergebnis

  1. WebUI oder MCP bindet ein einmaliges Skript oder eine feste Bibliotheksrevision an Ziele und Ausführungsidentität. Der Plan hält Skriptbytes, Prüfsummen, Zeitfenster, Laufzeit, Ausgabegrenze und Versuche fest. Für den weiteren Ablauf gelten drei Kennungen. plan_id öffnet die Planprüfung, operation_id bezeichnet den eingereichten Auftrag, job_id die Ausführung auf einem Gerät. Plan und Auftragsabfragen · Skriptbibliothek
  2. Einreichen erzeugt pending_approval. Die berechtigte Person entscheidet in der WebUI. Erst bei Genehmigung legt der Server die geplanten Jobs und die Zustellung an. Die Tokenrechte für Kunde, Planung, Einreichung und Skriptkontext werden serverseitig geprüft. Genehmigungen · MCP-Zugriff
  3. Der Agent empfängt JobOffer, speichert den Versuch und antwortet mit JobAccepted. Vor dem Start fordert er die signierte ExecutionPermit an. Sie bindet unter anderem Kunde, Installation, Versuch, Planhash, Nutzdatenhash, Ausführungsidentität und Frist. Das Dienstkonto führt reguläre Skripte aus. Ein für die Installation eingerichteter Helper führt Linux-Skripte als root beziehungsweise Windows-Skripte als SYSTEM aus. Startrecht · Prüfung und Ausführungsjournal
  4. JobResult übermittelt Status, Exitcode, Standardausgabe, Fehlerausgabe und ein Kennzeichen für abgeschnittene Ausgabe. Bei erneutem Kontakt gleichen Agent und Server ihre Journale ab. Eine wiederholte Zustellung desselben Versuchs bewahrt dessen ursprüngliches Ergebnis. Bei unklarer Wirkung wird der Versuch abgeglichen. Ergebnistypen · Journalabgleich

Auch ein Neustart ist ein Skriptauftrag. Sein erfolgreicher Exitcode bestätigt die Annahme durch das Betriebssystem. Bootwechsel, authentisierter Kontakt derselben Installation und ein erfolgreicher Folgeauftrag belegen den Wiederanlauf. Abnahme auf beiden Plattformen

Erstaufnahme und Selbstupdate

Frische Geräte laden /install/linux.sh oder /install/windows.ps1 über HTTPS. Für die Erstaufnahme verwenden sie den Aufnahmeweg des Kunden. Eingeschriebene Geräte fragen die veröffentlichte Agentversion über /agent/v1/releases/current ab. Der Updater prüft das signierte Manifest und die gebundenen Artefakte. Bei einer bereits installierten administrativen Helper-Version zählt für die Manifestgültigkeit der Zeitpunkt ihrer Registrierung im Katalog. Bei Neuinstallationen und Updates zählt die aktuelle Zeit. Implementierung der Release-Routen · Produktbeschreibung