160 KiB
Rust RMM: Architektur und Implementierungsspezifikation
Version 1.15 · 2026-11-13 · Sprache: Deutsch
Zweck: Vollständige, eigenständig nutzbare Grundlage für die Implementierung einer mandantenfähigen Plattform zur Inventarisierung, Überwachung und Fernadministration von Kundengeräten durch eine Coding-KI und ein Entwicklungsteam.
Status: Spezifikation; keine Behauptung einer bereits vorhandenen Implementierung. Version 1.4 führte Linux-first mit realem VM-Nachweis und lokalem Docker-/SSH-/TLS-Entwicklungsweg ein. Version 1.5 dokumentiert die neuen Userentscheidungen: MVP ohne RustDesk und eng begrenzte dev/test-Browsersimulation tatsächlicher UI-Interaktionen. Die zwingende menschliche WebUI-Genehmigung im Produktionsverhalten bleibt unverändert. Sie benötigt weder das Word-Dokument noch externe Diagrammdateien.
Versionsverlauf: 1.2 → 1.3: keine automatische Jobfreigabe, eigenständige Gastagenten, PVE nachgelagert. 1.3 → 1.4 (2026-11-12): erstes Phasenziel Linux-MVP M0–M5, alle Features zuerst auf tatsächlicher Linux-Test-VM; Windows erst danach, PVE noch später; verbindliche Entwicklungs- und Nachweisregeln in AGENTS.md und docs/development.md.
1.4 → 1.5 (2026-11-12): ausdrücklicher Useroverride „rustdesk musst du nicht machen ... das lasse aus“; RustDesk ist keine Pflicht dieser Umsetzung und keine MVP-Abnahme. Ausschließlich browsergesteuerte dev/test-Bedienung darf mit sichtbar simuliertem Testprincipal menschliche UI-Aktionen nachstellen; keine API-/DB-Freigabeabkürzung. Lokale Serverneustarts ausdrücklich erlaubt, keine impliziten VM-Reboots/Updates/destruktiven Zieltests.
Inhaltsverzeichnis
- 0 Auftrag und verbindliche Produktanforderungen
- 1 Entscheidung und Geltungsbereich
- 2 Komponenten und Systemgrenzen
- 3 Rust und der technische Stack
- 4 Aufbau der Agenten
- 5 Verbindung und Nachrichtenprotokoll
- 6 Datenmodell und Gerätezuordnung
- 7 Inventarisierung und Datenerhebung
- 8 Monitoring und Alarmierung
- 9 Proxmox und Backupbeobachtung
- 10 Aufträge und Softwareinstallation
- 11 Shell und Bereitstellung von RustDesk
- 12 MCP und Steuerung durch KI
- 13 Mandanten und Schutz der Verwaltungsfunktionen
- 14 Oberfläche und Bedienung
- 15 Speicherung und Größenordnung
- 16 Betrieb und Aktualisierung
- 17 Umsetzung in überprüfbaren Schritten
- 18 Startentscheidungen und konfigurierbare Betriebsdaten
- 19 Repository, Module und Abhängigkeitsrichtung
- 20 Normative Datenverträge
- 21 Normativer Agentprotokoll-Vertrag
- 22 Pläne, Ausführungserlaubnis und Jobzustände
- 23 HTTP API, MCP und Berechtigungen
- 24 Aktions-, RustDesk- und Providerverträge
- 25 Implementierungsreihenfolge und Abnahmekriterien
- 26 Direkt verwendbarer Startauftrag für eine Coding-KI
- Quellen und Referenzen
0 Auftrag und verbindliche Produktanforderungen
Präzisierung Version1.14, zeitgebundener Rebootnachweis: Die ursprüngliche Wiederverbindungsfrist ab serverseitiger Startreservierung bleibt unverändert. Ein tatsächlich vor Fristende unabhängig empfangener neuer Boot-Inventarbeleg bleibt als unveränderlicher rechtzeitiger Nachweis verwendbar. Erfolgt seine Erstverifikation später als fünf Minuten nach Empfang, braucht sie zusätzlich einen unabhängig empfangenen, höchstens fünf Minuten alten Inventarbeleg derselben aktuellen Boot-ID sowie den aktuell authentisierten, nicht widerrufenen Geräte-/Mandanten-/Generationskontext. Beide konkreten Beleg-IDs und Serverempfangszeiten sind im signierten Ergebnis und Audit zu binden. Fehlender ursprünglicher Fristbeleg bleibt unknown; ein erst nach Fristende empfangener Beleg wird durch spätere Aktualität niemals rechtzeitig. Keine Verlängerung, Umdatierung, neue Wirkung oder Wiederholungserlaubnis.
Präzisierung Version1.13, begrenzte MVP-Nachbedingungen: Ein bereits vor
einer Paketwirkung vorhandener Host-Neustartbedarf verhindert deren Erfolg
nicht, wenn sämtliche Paketnachbedingungen unabhängig vollständig nachgewiesen
sind. no_reboot=true verbietet den eigenmächtigen Neustart; das tatsächliche
Hostflag wird unverfälscht als reboot_required berichtet. Für die harmlosen
APT-Fixturerezepte muss derselbe gebundene Hostflagwert vor/nach der Wirkung
nachgewiesen sein; der private Sandboxwert ersetzt diese Hostbeobachtung nicht.
Fehlende historische Vorhermessungen werden nicht rückwirkend erfunden.
Beim festen Rebootjob beginnt die zentrale reconnect_timeout_seconds-Frist
konservativ an der dauerhaft gespeicherten serverseitigen Startreservierung
des gleichen Jobs/Versuchs/Grants. Ein späterer lokaler Start verlängert sie
nicht. Erstmaliger Erfolg braucht authentisierten Wiederkontakt mit neuer
Boot-ID sowie unabhängig gespeichertes Inventar, dessen Serverempfang nach
Reservierung und spätestens zur Frist liegt. Fehlender/verspäteter Nachweis
bleibt unknown. Späterer signierter Abgleich darf den ursprünglichen
rechtzeitigen Inventarbeleg erneut prüfen, aber keinen anderen verspäteten
Beleg unterschieben. Dies begrenzt die vorhandene Rebootabnahme und erlaubt
keinen zusätzlichen Reboot oder automatischen Wiederholungsversuch.
Topologieoverride des Users vom 2026-11-13 (Version 1.6): Der Entwickler-PC
wird nicht mehr als RMM-Server genutzt. Der dedizierte Internetserver übernimmt
Backend, Datenbank und TLS-Endpunkt; Agenten verbinden sich direkt ausgehend
mit diesem Server. Präzisierung Version 1.7, ausdrückliche Userkorrektur vom
2026-11-13: Dieses Notebook dient ausschließlich der Entwicklung und darf
nicht als RMM-Client installiert, enrolled oder betrieben werden. Der aktuelle
Testaufbau besteht aus der Cloud-Test-VM als Client und dem bereits endgültig
festgelegten Cloudserver discovery.ease-technologies.de als Server. Der kurzzeitig
installierte Notebook-Client wurde gestoppt/deinstalliert und seine Identität
über die WebUI widerrufen. Frühere Aussagen zum lokalen Notebook-Client sind
damit überstimmt. Frühere Vorgaben
„Server lokal in Docker auf dem PC“, PC→VM-Reversetunnel und VM-Loopback als
Serverziel sind hiermit historisch und überstimmt. Docker-Veröffentlichungen
bleiben Loopback, PostgreSQL bleibt intern; öffentlicher TLS-Ingress wird separat
abgesichert. Keine öffentliche Dev-Anmeldung. Bis zu einer eingerichteten sicheren
öffentlichen Anmeldung bleibt die WebUI nur über SSH-Tunnel erreichbar.
Root-SSH ist Bootstraptransport, der RMM-Dienst läuft unprivilegiert. TLS/mTLS,
Mandantentrennung und WebUI-Plangenehmigung bleiben verbindlich.
Deploymentdaten, offene Konfiguration und reale Nachweise:
docs/server-deployment.md. Diese Entscheidung ist kein Deploymentnachweis.
0.1 Auftrag an die implementierende KI
Technische Präzisierung Version 1.15 — endliche Journalbudgets: Agentjournal sowie Agent-/Helper-Verbrauchsledger erhalten pro SQLite-Datei maximal1GiB bei geprüften4096-Byte-Seiten (262144Seiten). Die früheren festen 64MiB und256MiB blockierten auf der tatsächlichen VM bei vollständig erhaltenen Sync-Historien, zuletzt während des Abschlussabgleichs nach dem einzigen Reboot. Eine Erhöhung ist ausschließlich versionierte Bootstrapwartung mit qualifizierten Artefakten und unveränderten Identitäten, Journal-/Ledgerinodes, Verbrauchszeilen, Signaturen und Tombstones. Kein Reset oder Löschen zur Abnahme. Volle/inkonsistente Journale sperren weiterhin neue Wirkungen; Kapazitätsfehler werden nie ignoriert. Sichere Kompaktierung und weitergehende Kapazitätsplanung bleiben späterer eigener Umfang, keine automatische Löschung oder unbeschränkte Datenbank in diesem MVP. Die größere Grenze ist kein Langzeitbetriebsnachweis.
Technische Präzisierung Version 1.11 — neuer Configure-only-Plan:
Nach unabhängig belegtem und durch normalen signierten RootSync abgeschlossenem
Fehler „Fixture1.0 ausschließlich entpackt“ darf ein neuer fester WebUI-Plan
allein dieses Paket konfigurieren. Manifestschema4 bindet ursprünglichen
Grant/Versuch und unveränderlichen Partial-Proof; Transaktionsschema2 verlangt
explizit operation=configure_only und alte/neue Version1.0. Frische vollständige
Teilzustandsplanung hat eine eigene authentisierte Operation/Inventarquelle;
normale Planung und Baseline bleiben strikt. Tatsächlicher v3-Hook und dpkg-
Aufruf dürfen ausschließlich die Konfiguration dieses exakten Pakets enthalten,
kein Unpack, Pending, Triggerlauf oder Fremdpaket. Eigene Create-once-
Recoverymarker/-Nachweise; alte Marker und History bleiben erhalten. Dies
bescheinigt keine nachträgliche frische Installationsabnahme. Danach braucht ein
Upgrade1.0→1.1 einen eigenen neuen festen WebUI-Plan und native Nachprüfung;
gewünschte Noops werden getrennt und ehrlich als Noops abgenommen.
Technische Präzisierung Version 1.10 — wirkungslose Kontrollkettenreparatur: Ein nachweislich nicht serverseitig persistierter Sync-Request darf im expliziten Entwicklungsprofil über ein eng begrenztes Root-Bootstrapwerkzeug abgeglichen werden. Server und beide lokalen Verifier prüfen die vollständigen erhaltenen Journale, ursprünglichen Signaturen, exakten Geräte-/Boot-/Checkpointbindungen und den unveränderten offenen Verbrauch. Nur die bereits gespeicherte signierte Ablehnung wird zum monotonen gemeinsamen Kontrollhead; eine kurzlebige, domänengetrennte Signatur bindet sämtliche Zeugen. Lokale alte Faults und Quittung werden dauerhaft archiviert. Keine Bereitschaft, Genehmigung, Jobs, Grants, Verbräuche oder Outcomes entstehen oder ändern sich dadurch. Kein manuelles Löschen einer Sperre, kein Journal-/Identitätsreset. Erst der normale signierte Sync und eine unabhängig gebundene Nachprüfung dürfen anschließend ein unbekanntes Ausführungsergebnis klassifizieren. Dies konkretisiert den bestehenden Abgleichvertrag und ist keine Ausnahme von der WebUI-Jobgenehmigung.
Präzisierung Version 1.9, 2026-11-13 — expliziter neuer APT-Testversuch:
Ein bekannter Fehler vor der vertrauenswürdigen Hookübergabe darf nach belegtem
unverändertem vollständigem Paketbestand durch genau einen neuen festen,
separat WebUI-genehmigten Versuch des unveränderten Fixture-Rezepts geprüft
werden. Manifestschema 3 bindet hierfür den ursprünglichen Grant/Versuch und
Hash des unveränderten Create-once-Markers. Der Helper prüft unabhängig den
ursprünglichen signierten Auftrag und dessen eindeutiges HOOK_NOT_HANDED_OFF
im selben dauerhaften Ledger. Die alte Signaturprüfung ist ausschließlich
historisch und berechtigt keinen neuen Start. Alter Marker und vollständige
Historie bleiben erhalten; der neue Versuch erhält einen eigenen Create-once-
Retrymarker. Vorhandener Hook, unbekannte/partielle Wirkung, geänderte Baseline,
Identität, Generation oder Transaktion verweigern die Wiederaufnahme. Keine
automatische Wiederholung und keine allgemeine Freigabe unbekannter Wirkungen.
Schema 2 bleibt ohne Retryfeld bytekompatibel. Diese Vertragspräzisierung ist
kein Nachweis einer ausgeführten oder bestandenen Paketabnahme.
Useroverride Version 1.8, 2026-11-13: Der User erlaubt ausdrücklich, den Windows-11-Client bereits parallel zur offenen Linux-MVP-Abnahme zu entwickeln und auf seiner Windows-Test-VM nativ zu prüfen. Die bisherige Reihenfolgeregel „Windows erst nach Linux-MVP-Abnahme“ ist ausschließlich hierfür überstimmt. Linux bleibt Referenz und erstes MVP-Abnahmeziel; Windows-Nachweise bleiben separat und sind kein zusätzlicher Linux-MVP-Blocker. Der Notebook-Host erhält keinen Agenten; die Windows-VM ist ein eigenständiger Gast mit ausgehender Verbindung zum endgültigen Cloudserver. Bootstrapzugang über abgesicherten Reverse-SSH-Tunnel ist erlaubt; TLS/mTLS, Mandantengrenzen und die WebUI-Genehmigung jedes RMM-Jobs bleiben unverändert verbindlich.
Implementiere das in dieser Datei beschriebene System schrittweise. Beginne mit dem ersten vertikalen Abschnitt in Kapitel 25 und liefere lauffähige, überprüfbare Ergebnisse. Erzeuge nicht lediglich ein breites Gerüst mit leeren Methoden. Nutze die Startentscheidungen aus Kapitel 18, wenn konkrete Betriebsdaten noch fehlen. Halte tatsächlichen Implementierungsstand, offene Punkte und durchgeführte Prüfungen im Repository fest.
Die Begriffe MUSS, DARF NICHT und Abnahme bezeichnen verbindliche Anforderungen. Default bezeichnet einen konfigurierbaren Startwert. Optional gehört nicht zum ersten Produktumfang. Die ausdrücklichen Entscheidungen der Version 1.5 in diesem Abschnitt haben bei Widersprüchen Vorrang vor früheren Architekturannahmen und Beispielen; sonst konkretisieren Kapitel 18 bis 26 die Architektur. Verbleibende Widersprüche werden dokumentiert und fachlich geklärt.
Neuer verbindlicher Useroverride 2026-11-12 – Umfang ohne RustDesk: „rustdesk musst du nicht machen ... das lasse aus“. Keine RustDesk-Installation, Profile/Provisionierung, RustDesk-spezifischen Schnittstellen oder externe Desktopabnahme in dieser Umsetzung. M4 bleibt allgemeine Linux-Paketverwaltung; M5 umfasst nur Referenzabläufe 0.3 Nr. 1–3. REQ-11, Referenzablauf Nr. 4, ensure_rustdesk, rustdesk_profiles, Kapitel 24.2 und AT-17/AT-18 sind ausschließlich spätere optionale Integrationsverträge, keine MVP-Pflicht oder Abnahmeblocker. Sämtliche verbliebenen RustDesk-Architekturtexte einschließlich Windows-Beispielen und Startauftrag sind in diesem Sinne historisch/optional zu lesen, nicht als Implementierungsauftrag. Keine eigene Desktop-Engine als Ersatz; Linux-first und die übrigen Sicherheits-/Abnahmegates bleiben bestehen.
Einzige Bedienungsausnahme für diese Entwicklungsabnahme: Der User hat ausdrücklich angeordnet: „Setz Linux MVP vollständig um und simuliere die menschlichen Aktionen. Du kannst Server auch neustarten“. Ausschließlich im expliziten dev/test-Profil darf Browserautomatisierung tatsächliche WebUI-Interaktionen einschließlich Genehmigung des unveränderlichen Plans mit einem deutlich sichtbar als simulierter Testprincipal gekennzeichneten Principal durchführen. Diese Ausnahme präzisiert alle nachfolgenden Aussagen zu tatsächlicher menschlicher Bedienung bei Entwicklungstests (insbesondere REQ-10, Kapitel 22/23/25/26 und AT-30); sie schafft keine Code-Abkürzung und keine Produktionsausnahme. pending_approval, Planbindung, Rechte-, Tenant-/Policyprüfungen und interaktive UI-Grenze bleiben unverändert; vor UI-Genehmigung keine ausführbaren Jobs, Outbox, JobOffers, Startgrants oder Wirkung. Audit MUSS approval_origin als browsergesteuerte dev/test-Simulation und testsimulation als wahr samt Testprincipal, Profil, Zeitpunkt und Planbezug nachvollziehbar kennzeichnen. Keine tatsächliche menschliche Identität vortäuschen, Simulation getrennt nachweisen, kein Produktions-Freigabenachweis. KI/MCP dürfen weiterhin keine direkten API-/DB-Freigaben vornehmen und kein Token erhalten, das die interaktive Grenze unterläuft; normale UI-Browserrequests bleiben an deren interaktiven Kontext gebunden. Simulation außerhalb dev/test verweigern; Produktionsverhalten bleibt unverändert. Lokale Serverneustarts sind erlaubt, keine impliziten VM-Reboots, Updates oder destruktiven Zieltests; Zieltestumfang weiterhin gesondert ausdrücklich abstimmen. Diese Regeln dokumentieren Erlaubnis und Anforderungen, keine bereits implementierte oder ausgeführte Simulation. Details/Nachweisvorlage: docs/project-decisions.md, docs/development.md.
Normative Entscheidungen vom 2026-11-12: Linux-first gilt für ALLE Features: zuerst auf der tatsächlichen Linux-Test-VM implementieren, ausführen und nachweisen. Erstes Phasenziel ist das Linux-MVP x86-64 mit WebUI, MCP und autorisierten dauerhaften Jobs (M0–M5). Windows-x86-64-Implementierung und native Abnahmen beginnen erst nach dokumentierter Linux-MVP-Abnahme; PVE-Modul/-Client, Cluster und Backups folgen noch später nach der Windows-Phase. ARM64 und Betriebsreife bleiben nachgelagerte Ausbaustufen. Windows-/Linux-Agenten sind als Produktziel auf physischen Geräten und beliebigen VMs eigenständig verwaltbar, ohne PVE-Agent, Hypervisorzugang oder bekannten Host. Proxmox verwendet später denselben Linux-Agenten mit Zusatzmodul. Keine vorgezogene PVE-Implementierung oder PVE-Testpflicht im Linux-MVP. Build, Simulator oder lokaler PC-/Containerlauf ersetzen keinen realen VM-Nachweis.
Verbindlicher Entwicklungsweg: Server lokal in Docker auf dem PC, sämtliche veröffentlichten Dockerports ausschließlich Loopback. PC initiiert SSH zur VM mit -N -T, ExitOnForwardFailure=yes, Keepalive und -R 127.0.0.1:18443:127.0.0.1:18443. VM-Agent verbindet sich ausgehend über dortigen Loopback. TLS bleibt Ende-zu-Ende mit DNS SAN rmm-dev.internal, explizitem VM-Hosts-Eintrag oder geprüftem Client-Connect-Override unter Erhalt der Namensprüfung; niemals ungültige Zertifikate akzeptieren. SSH nur Dev/bootstrap, kein RMM-Sicherheitsersatz. VM-Daten in credentials/linux-vm.conf, .gitignore-Ausschluss, Modi 700/600; keine Secrets loggen/committen, kein source/eval. Toolinstallation ist erlaubt, aber keine impliziten Reboots, Updates oder destruktiven Zieltests. Details und ausschließlich geplante, nicht als getestet behauptete Befehle: docs/development.md. Verbindliche AI-Regeln: AGENTS.md. Kein Erfolg ohne tatsächlichen Nachweis.
Unbedingte Freigabegrenze: JEDER zur Ausführung eingestellte Job aus UI, MCP oder Automatik benötigt vorher die explizite Genehmigung eines berechtigten Menschen in der WebUI. Dies gilt auch für Diagnosejobs, Hello World, Reboot-Folgejobs und neue Versuche. Eine Genehmigung bindet einen unveränderlichen Plan und feste Einzeljobs/Versuche; ein transparent angezeigtes Sammelpaket ist zulässig, Dauer- und Wildcardfreigaben nicht. Policies dürfen nur begrenzen oder verweigern, niemals Genehmigungen ersetzen. MCP darf planen und einen persistenten Antrag mit pending_approval einstellen, aber weder genehmigen noch vor Genehmigung Ausführungsjobs einreihen, JobOffer zustellen oder Startgrants erhalten. Passive Telemetrie/Heartbeats und das Lesen bereits gespeicherter Daten sind keine Jobs und benötigen keine Einzelgenehmigung. Diese Ausnahme darf keine angeforderten Diagnose- oder Ausführungsjobs als Telemetrie tarnen.
0.2 Verbindlicher Funktionsumfang
| ID | Anforderung |
|---|---|
| REQ-01 | Ein zentrales Backend in Rust verwaltet mehrere voneinander getrennte Kunden. |
| REQ-02 | Ein gemeinsamer Rust-Agentkern unterstützt Windows und Linux eigenständig auf physischen Geräten und beliebigen VMs; Host/Hypervisor darf unbekannt sein. Kein PVE-Agent oder Hypervisorzugang ist nötig. Proxmox verwendet nach dem MVP denselben Linux-Agenten mit zusätzlichem Modul. |
| REQ-03 | Erstes Phasenziel Linux-MVP x86-64/AMD64; Windows x86-64 erst nach dessen Abnahme, ARM64 später. Alle Features zuerst auf tatsächlicher Linux-Test-VM nachweisen. Support gilt je getesteter Betriebssystem-/Architekturkombination; 32-Bit-Ziele sind zusätzliche, noch nicht zugesagte Erweiterungen. |
| REQ-04 | Alle RMM-Netzwerkverbindungen zu Kundengeräten werden vom Agenten ausgehend aufgebaut. Die Zentrale öffnet keine eingehenden Verbindungen zu den Geräten. |
| REQ-05 | Inventar, Erreichbarkeit, Messwerte, erwartete Dienste, Software, Updates und begrenzte Logs sind je Kunde abrufbar; Proxmox-/Backupinformationen folgen nach dem MVP. |
| REQ-06 | Jeder Status zeigt Datenquelle und Erhebungszeit. Nicht erreichbare Geräte zeigen den letzten bekannten Stand; die Plattform behauptet keinen aktuellen Messwert ohne neue Erhebung. |
| REQ-07 | Eine Weboberfläche stellt Kunden, Geräte, Probleme und Aufträge dar. Diese Verwaltungsoberfläche bleibt Bestandteil; sie ist von grafischer Desktopfernsteuerung zu unterscheiden. |
| REQ-08 | Ein MCP-fähiger LLM-Client kann gespeicherte Gerätedaten abfragen, Skripte und Installationen vorbereiten und Sammelaufträge zur menschlichen WebUI-Genehmigung beantragen, etwa ausgewählte Server eines Kunden neu starten. |
| REQ-09 | Alle Änderungen durch Menschen, KI oder automatische Regeln verwenden dieselben Pläne, Berechtigungsprüfungen, Jobs und Ergebnisnachweise. |
| REQ-10 | Jeder Ausführungsjob benötigt explizite menschliche WebUI-Genehmigung für seinen unveränderlichen Plan und festen Versuch, einzeln oder als transparentes Sammelpaket. Policies begrenzen/verweigern nur; KI und Automatik dürfen niemals genehmigen. |
| REQ-11 | Spätere optionale Integration, ausdrücklich nicht Teil dieser Umsetzung/MVP-Abnahme: RustDesk auf ausgewählten Geräten mit versionierter Konfiguration installieren und prüfen; separater RustDesk-Bildschirmzugriff. |
| REQ-12 | Eine eigene Desktop-Engine, Bildschirmübertragung oder Maussteuerung wird nicht entwickelt. RustDesk hat einen separaten, passend konfigurierten Verbindungsweg. |
| REQ-13 | Administrative Shell-/PowerShell-Sitzungen bleiben vorgesehen und verwenden vom Agenten eröffnete Kanäle. |
| REQ-14 | Offlinegeräte erhalten gültige Aufträge nach Wiederverbindung. Ein ausgeschaltetes Gerät kann über seinen Agenten keine Aktion ausführen. |
| REQ-15 | Die Zuordnung verkaufter Geschäftsleistungen ist eine optionale spätere Erweiterung. Sie blockiert Inventar, Monitoring und Verwaltung nicht. |
0.3 Referenzabläufe
- Inventar: „Gib mir alle Server von Kunde X, ihren letzten Kontakt und freien Speicher.“ Die Antwort enthält nur berechtigte Geräte, Datenalter und gegebenenfalls unvollständige Ergebnisse.
- Sammelreboot: „Starte alle Server von Kunde X neu.“ Die Plattform löst Kunde und feste Zielmenge eindeutig auf und beantragt die menschliche WebUI-Genehmigung des Plans. Erst danach führt sie Jobs gestaffelt aus. Ein Gastauftrag erweitert sich nicht auf seinen Hypervisor; dieser muss nicht bekannt sein.
- KI-Skript: „Erstelle Hello World und führe es auf allen Clients von Kunde X aus.“ Das LLM liefert passende Skriptvarianten; exakte Bytes, Interpreter und feste Ziele werden vor menschlicher WebUI-Genehmigung gebunden. Erst danach wird ausgeführt; Ergebnis und Ausgabe werden je Gerät zurückgemeldet.
- RustDesk (historischer Zielvertrag, nur spätere optionale Integration; keine MVP-Pflicht): „Installiere RustDesk auf den PCs von Kunde X mit Profil Y.“ Bei späterer Beauftragung prüft die Plattform die Plattform-/Paketkombination und beantragt die menschliche WebUI-Genehmigung des festen Plans. Erst danach installiert und konfiguriert sie und meldet ID, Version und Dienstzustand. Ein externer Verbindungstest bleibt dann ein eigener Nachweis; zusätzliche Testjobs und Reboots benötigen ebenfalls Genehmigung. In dieser Umsetzung vollständig ausgelassen.
1 Entscheidung und Geltungsbereich
Empfohlen wird eine mandantenfähige Plattform mit einem zentralen Rust-Backend und einem gemeinsamen Rust-Agenten, der je nach Betriebssystem und Rolle unterschiedliche Module aktiviert. Windows und Linux verwenden denselben Protokoll-, Sicherheits- und Auftragskern. Jede verwaltete VM verwendet einen eigenen, vollständig eigenständigen Windows- oder Linux-Agenten; sie muss nicht auf Proxmox laufen. Ein bekannter oder verwalteter Host ist keine Voraussetzung. Physische Maschinen verwenden dieselben Pakete. Erst nach dem MVP kann derselbe Linux-Agent auf Proxmox VE eine zusätzliche Proxmox-Funktion aktivieren.
Alle Verbindungen zwischen verwalteten Geräten und der Zentrale werden vom Gerät ausgehend aufgebaut. Aufträge, Ergebnisse und interaktive Sitzungen nutzen diese Verbindungen oder zusätzliche, ebenfalls vom Agenten initiierte Kanäle. Ein eingehender SSH-, WinRM- oder RMM-Port am Kundengerät ist dafür nicht erforderlich.
Rust ist für Backend und Agenten eine sinnvolle Wahl, wenn im Entwicklungsteam Rust-Erfahrung vorhanden ist oder aufgebaut werden soll. Der Entwurf verbindet einen gemeinsamen technischen Kern mit den notwendigen plattformspezifischen Implementierungen. Die Weboberfläche wird in TypeScript umgesetzt. MCP bietet kontrollierte Lese- und Planungsfunktionen, aber keine Genehmigung. Die Plattform erzwingt Rechte, begrenzende Regeln und menschliche WebUI-Genehmigung vor jeder Jobausführung.
Der Gesamtentwurf umfasst Inventar, Monitoring, Softwareinstallation, Betriebssystemaktionen, Protokollzugriff, menschlich genehmigte Bereitstellung von RustDesk und Mandantentrennung. Proxmox, Cluster, Backupbeobachtung, Shell-Sitzungen und Betriebsreife sind spätere Ausbaustufen nach dem MVP gemäß Kapitel 25. Eine eigene grafische Fernsteuerung ist nicht Bestandteil; Bildschirmzugriffe erfolgen mit RustDesk. Eine Zuordnung verkaufter Dienstleistungen wird vorbereitet; Vertragsverwaltung und Abrechnung gehören nicht zum MVP.
Planungsannahmen: Ein IT-Dienstleister betreibt zunächst eine zentrale Installation für mehrere Kunden. Eine Pilotumgebung beginnt mit einigen Dutzend Geräten. Für die Auslegung werden später 1.000 und 10.000 Geräte als Lastszenarien getestet. Diese Zahlen sind Testziele und keine Leistungszusage. Unterstützte Windows-, Linux-, PVE- und PBS-Versionen werden als verbindliche Matrix festgelegt. Dieses Dokument ist die Arbeitsgrundlage für die anschließende Implementierung; es enthält selbst noch keine fertige Software. Die Startentscheidungen und Abnahmen werden in den Abschnitten 18 bis 26 konkretisiert.
| Anforderung | Architekturentscheidung |
|---|---|
| Nur ausgehende Verbindungen | Agent öffnet TLS über TCP 443 und fordert Aufträge an |
| Windows und Linux auf physischer oder virtueller Hardware | Gemeinsamer Agentkern mit Betriebssystemadaptern |
| Proxmox Host und Gäste (nach MVP) | Linux-Agent mit PVE-Modul auf dem Host; Gastagent vollständig unabhängig davon |
| Übersicht je Kunde | Mandant, Standort, Asset und Agentinstallation als getrennte Entitäten |
| KI kann lesen und handeln | MCP-Adapter vor derselben Fachlogik und Auftragsverwaltung wie die UI |
| Kontrollierte Automatisierung | Automatische Planung mit begrenzenden Regeln; feste Ausführungsjobs erst nach menschlicher WebUI-Genehmigung |
| Nachvollziehbare Administration | Dauerhafte Jobs, Ausführungsnachweise und getrennt gesicherte Audits |
| RustDesk bereitstellen | Installation mit versioniertem Kundenprofil und überprüftem Ergebnis |
2 Komponenten und Systemgrenzen
flowchart TD
UI["Weboberfläche"] --> API["HTTP API und MCP"]
AI["LLM mit MCP Client"] --> API
Agent["Windows, Linux und Proxmox Agent"] -->|"ausgehend TLS 443"| Gateway["Agent Gateway"]
API --> Core["Rust Fachservices"]
Gateway --> Core
Core -->|"Aufträge über bestehenden Kanal"| Gateway
Core --> DB["PostgreSQL"]
Core --> Metrics["Messwertdienst"]
Core --> Objects["Artefaktspeicher"]
Die Pfeile zum Gateway beschreiben den Datenfluss. Neue Netzwerkverbindungen zu den verwalteten Geräten baut die Zentrale nicht auf. RustDesk ist eine separat betriebene Anwendung; seine Bereitstellung läuft als normaler Verwaltungsauftrag.
Die Anwendung beginnt als modularer Monolith. Damit sind Fachmodule innerhalb einer gemeinsamen Codebasis gemeint, mit eindeutigen Zuständigkeiten und internen Schnittstellen. Das vermeidet verteilte Transaktionen zwischen vielen kleinen Diensten. Gateway, Hintergrundverarbeitung und Relay müssen dennoch getrennt startbar sein, damit sie bei höherer Last unabhängig skalieren und mit unterschiedlichen Berechtigungen laufen können.
| Komponente | Aufgabe |
|---|---|
| Web API und MCP Adapter | Eingaben prüfen, Benutzerkontext herstellen und Fachservices aufrufen |
| Identitäts und Richtliniendienst | Kundenrechte, Gerätezuordnung, Aktionen, Freigaben und Sitzungsrechte auswerten |
| Inventardienst | Quellen normalisieren, Assets zuordnen und aktuelle sowie historische Sicht bereitstellen |
| Agent Gateway | Geräte authentifizieren, Verbindungen halten, Telemetrie annehmen und Jobs zustellen |
| Jobdienst und Worker | Pläne, Warteschlange, Laufzustände, Fristen und Nachprüfungen verwalten |
| Monitoringdienst | Sollzustände und Messwerte auswerten, Vorfälle gruppieren und Benachrichtigungen erzeugen |
| Sitzungsrelay | Autorisierte interaktive Terminaldaten vermitteln |
| PostgreSQL | Verbindliche Stammdaten, Rechte, Inventar, Jobs, Richtlinien und Auditverweise speichern |
| Messwertspeicher | Zeitreihen für Metriken und Diagramme speichern |
| Objektspeicher | Installationsartefakte, größere Ausgaben, Logauszüge und Sitzungsaufzeichnungen speichern |
PostgreSQL ist die verbindliche Quelle für Aufträge und Berechtigungen. Eine offene Netzwerkverbindung oder ein flüchtiger Cache ist nie der einzige Nachweis eines Auftrags. Die Verbindungstabelle des Gateways darf nach einem Neustart aus neuen Agentanmeldungen rekonstruiert werden. Eine zusätzliche Message-Broker-Infrastruktur wird erst eingeführt, wenn ein Lasttest oder eine benötigte Entkopplung dies rechtfertigt.
Eine reine Prozessgrenze innerhalb desselben privilegierten Betriebssystemkontos schützt nicht gegen eine vollständige Kompromittierung. In der Produktionsbereitstellung laufen API, Relay und besonders sensible Signierfunktionen mit getrennten Dienstidentitäten. Das Relay erhält keine allgemeinen Datenbank- oder Signierrechte. Gemeinsame Rust-Bibliotheken erlauben diese Trennung ohne duplizierte Fachlogik.
3 Rust und der technische Stack
Rust passt zu langlebigen Systemdiensten, nebenläufigen Netzwerkverbindungen und lokalem Betriebssystemzugriff. Speicher- und Nebenläufigkeitssicherheit in sicherem Rust sowie der Verzicht auf einen obligatorischen Garbage Collector sind dafür relevante Eigenschaften. Sie ersetzen keine korrekte Autorisierung und schützen nicht automatisch unsichere FFI-Aufrufe oder gestartete Fremdprogramme. 1
Der größte Aufwand liegt in den Betriebssystemadaptern, Installationspaketen, Rückwärtskompatibilität und dem sicheren Betrieb. Rust beseitigt diese Unterschiede nicht. Bei einem Team ohne Rust-Kenntnisse würde Go die Entwicklung des Servers möglicherweise vereinfachen; für dieses Vorhaben ist ein durchgängiger Rust-Kern dennoch eine nachvollziehbare Entscheidung. Ein eigener Browser-UI-Stack in Rust würde zunächst wenig fachlichen Nutzen hinzufügen.
| Bereich | Empfohlene Auswahl | Zweck |
|---|---|---|
| Backend | Rust, Tokio, Axum | Asynchrone Dienste, HTTP API und Gateway |
| Datenzugriff | SQLx und PostgreSQL | Typisierte Abfragen und versionierte Migrationen |
| Agentprotokoll | Protobuf mit prost | Versionierbare Nachrichten über WSS und HTTPS |
| TLS und HTTP Client | rustls und reqwest | Zertifikatsprüfung und ausgehende Verbindungen |
| MCP | Offizielles Rust SDK rmcp | MCP als Adapter vor den Fachservices |
| Agentjournal | SQLite | Bestätigte Aufträge und begrenzter Offlinepuffer |
| Betriebssystemadapter | windows Crate und lokale Linux APIs | Native Plattformfunktionen mit gekapseltem FFI |
| Oberfläche | TypeScript und React | Kundenübersicht, Tabellen, Diagramme und Terminal |
| Produktive Metriken | VictoriaMetrics hinter internem Zugriffsdienst | Zeitreihen getrennt vom Auftragsdatenbestand |
| Diagnose der Plattform | tracing und OpenTelemetry | Korrelation von Anfrage, Auftrag und Agentereignis |
Die Bibliotheken werden in festgelegten, getesteten Versionen verwendet. Die verbindliche Struktur des Cargo-Workspace und die Trennung zwischen Bibliotheken und ausführbaren Diensten stehen in Abschnitt 19. Fachmodule kennen keine UI- oder MCP-spezifischen Berechtigungsabkürzungen. rmcp ist ein offizielles SDK und basiert auf Tokio. 2 Tokio und Axum bilden den passenden asynchronen Serverunterbau. 3
4 Aufbau der Agenten
Der gemeinsame Kern übernimmt Enrollment, Geräteidentität, Zertifikatsrotation, Transport, Heartbeats, Konfiguration, das lokale Journal, begrenzte Telemetriepuffer, Auftragsannahme und signierte Updates. Plattformmodule implementieren Collector für Inventar und Messwerte sowie Executor für klar definierte Aktionen. Eine Capability-Liste meldet, welche Funktionen auf einem konkreten Gerät tatsächlich verfügbar sind.
Eine nicht verfügbare Fähigkeit wird explizit als nicht unterstützt oder nicht berechtigt gemeldet. Sie darf weder durch erfundene Werte ersetzt noch als erfolgreicher Test gewertet werden. Collector laufen mit Zeitlimits und Fehlerisolation. Blockierende Systemaufrufe dürfen die Netzwerkverbindung nicht blockieren; besonders problematische oder privilegierte Provider können in eigenen Prozessen laufen.
Das erste Linux-MVP unterstützt x86-64 beziehungsweise AMD64 für ausdrücklich auf der tatsächlichen Linux-Test-VM geprüfte Linux-Versionen. Windows x86-64 folgt erst nach Linux-MVP-Abnahme mit eigenen nativen Tests. ARM64 folgt später mit nativen Abnahmen; Rust-Compilerziele allein belegen keine Agentfunktion. 32-Bit-x86 und ARM32 sind zusätzliche, nicht zugesagte Ziele. Physische Hardware und beliebige VMs verwenden dieselbe passende Agentvariante ohne Hypervisorabhängigkeit. Das noch spätere Proxmox-Modul wird separat auf unterstützten PVE-Hostplattformen geprüft. Die Hardware- und Plattformunterstützung von RustDesk ist davon unabhängig. 4 5
4.1 Windows
Der Agent wird als signierter Windows-Dienst installiert. Telemetrie und Netzwerk laufen unter einer möglichst eingeschränkten Dienstidentität. Ein separater Helper führt notwendige Systemaktionen aus. Der lokale Kommunikationskanal verwendet eine Named Pipe mit restriktiver ACL und überprüft auf beiden Seiten Identität und Auftrag.
Für Dienste werden die Service-Control-Manager-APIs genutzt, für Ereignisse die Windows-Event-Log-APIs mit gespeicherten Bookmarks und für Systeminformationen geeignete Win32-, CIM- oder WMI-Provider. COM-basierte Zugriffe wie Windows Update laufen auf korrekt initialisierten, dafür vorgesehenen Threads. Allgemeine asynchrone Tasks dürfen COM-Objekte nicht unkontrolliert zwischen Threads verschieben. 6
Softwareinventar verbindet Registry-, MSI- und gegebenenfalls AppX-Informationen. Regelmäßige Win32_Product-Abfragen werden vermieden, da sie MSI-Konsistenzprüfungen und Reparaturaktivitäten auslösen können. Benutzerbezogene Software wird getrennt erfasst; ein Dienstkonto sieht nicht automatisch alle Zustände jeder Benutzeranmeldung. 7
Die Paketausführung besitzt Provider für geprüfte MSI- und EXE-Installationsrezepte sowie weitere ausdrücklich unterstützte Quellen. WinGet wird nicht als universeller Systeminstaller vorausgesetzt: Microsoft dokumentiert Einschränkungen im Systemkontext. Paketkennung, Version, Installationskontext, Herkunft, Hash und Nachprüfung gehören in das Rezept. 8
4.2 Linux
Der Agent läuft bei unterstützten Distributionen als systemd-Dienst. Ein unprivilegierter Prozess sammelt verfügbare Daten; ein eng begrenzter Helper verwendet erforderliche Root-Rechte. Lokale IPC erfolgt über einen Unix-Socket mit geprüften Peer-Credentials und restriktiven Dateirechten. Bestehende MAC-Regeln wie SELinux oder AppArmor werden berücksichtigt.
Provider lesen unter anderem /proc, /sys, /etc/os-release, systemd-Zustände, Journald und Paketdatenbanken. Debian und Ubuntu erhalten einen APT/dpkg-Adapter; weitere Distributionsfamilien einen eigenen Adapter. Sperren des Paketmanagers und fremde Updateprozesse werden respektiert. Anfangs ist eine kleine, klar getestete Distributionsmatrix wertvoller als eine unbelegte Zusage für jedes Linux.
4.3 Privilegierter Helper
Der Helper akzeptiert typisierte, autorisierte Operationen mit Ziel, Parametern, Frist und Ausführungsidentität. Für Paketinstallationen bedeutet dies beispielsweise eine geprüfte Paketkennung mit Argumenten, nicht einen frei zusammengesetzten Shellstring. Er prüft die für ihn relevanten Autorisierungsnachweise selbst und vertraut nicht allein einer Anfrage des Netzwerkprozesses.
Eine allgemein freigegebene Root- oder SYSTEM-Shell besitzt zwangsläufig weitreichende Rechte auf dem Gerät. Die Trennung bleibt für Standardaktionen sinnvoll, kann eine solche bewusste Volladministration aber nicht in eine ungefährliche Aktion verwandeln. Die breite Fähigkeit ist deshalb ein eigener, zeitlich begrenzter Betriebsmodus.
5 Verbindung und Nachrichtenprotokoll
Der Agent verbindet sich zu einem festgelegten DNS-Namen der Plattform über TLS auf TCP 443. Der bevorzugte Kanal ist ein vom Agenten geöffneter WebSocket. Innerhalb dieser bereits bestehenden Verbindung können beide Seiten Nachrichten senden. Die Richtung des TCP-Verbindungsaufbaus bleibt immer vom Kundengerät zur Zentrale.
Ein HTTPS-Long-Polling-Modus nutzt denselben logischen Nachrichtenvertrag. Der Agent fragt nach Arbeit, der Server hält die Antwort begrenzt offen und liefert bei Bedarf einen Auftrag. Dieser Modus ermöglicht Inventar und Jobs auch dort, wo WebSockets blockiert sind. Eine interaktive Konsole kann ohne brauchbaren Streamingkanal eingeschränkt oder nicht verfügbar sein; das Produkt muss diese Grenze anzeigen.
HTTP/2 und gRPC sind für diesen äußeren Kanal keine Voraussetzung. Das reduziert die Abhängigkeit von fremden Proxys. Unternehmensproxy, Proxyanmeldung im Dienstkontext, Idle-Timeouts und Reconnect-Verhalten werden ausdrücklich getestet. Ein erlaubter ausgehender Port 443 beweist noch keine funktionierende Streamingverbindung.
Für Agentidentitäten wird mTLS vorgesehen. Eine TLS-Inspection kann die direkte Clientzertifikatsprüfung verhindern. Die Betriebsanforderung ist dann eine passende Ausnahme für den Agentendpunkt. Long Polling löst eine solche Zertifikatsinkompatibilität nicht. Falls ein Kunde diese Ausnahme nicht bereitstellen kann, benötigt er einen ausdrücklich entworfenen und geprüften Alternativtransport; die Zertifikatsprüfung wird nicht deaktiviert.
Pro Gerät regelt eine Verbindungsgeneration die aktive Zustellung. Nach Reconnect oder Transportwechsel erhält ein alter Kanal keine neuen Aufträge. Verspätete Ergebnisse werden weiterhin anhand der Job-ID korrekt verarbeitet. Widerruf beendet bestehende Kanäle oder sperrt sie durch regelmäßig erneuerte Autorisierung. Eine einmal erfolgreiche TLS-Anmeldung erlaubt keine unbegrenzt gültige Sitzung.
Artefakte können über denselben erlaubten Verwaltungsendpunkt vermittelt werden. Direkte Objektspeicher-Downloads und Betriebssystemupdates aus Herstellerquellen benötigen zusätzliche erlaubte Ziele oder ein passendes lokales Repository. Diese Egress-Anforderungen gehören in die Installationsvoraussetzungen.
5.1 Erstregistrierung und Identität
- Ein Administrator erstellt einen kurzlebigen Enrollment-Nachweis für genau einen Kunden und optional Standort und Gerätegruppe.
- Der Agent erzeugt sein Schlüsselpaar lokal. Enrollment über serverauthentifiziertes TLS bindet den öffentlichen Schlüssel an eine neue Agentinstallation.
- Der Server vergibt agent_id und ordnet eine asset_id zu. Ein Zertifikat oder vergleichbarer Gerätenachweis bestätigt diese Zuordnung.
- Enrollment-Nachweise sind einmalig oder ausdrücklich mengenbegrenzt. Sie werden nach Verwendung verworfen und nicht in Golden Images gespeichert.
- Gerätezertifikate rotieren frühzeitig. Lange offline gewesene Geräte erhalten einen geregelten Wiederaufnahmeprozess; ein abgelaufenes Zertifikat wird nicht dauerhaft toleriert.
Private Geräteschlüssel werden mit Betriebssystemmechanismen geschützt, soweit möglich hardwaregestützt. Das Design setzt keinen TPM auf jedem Gerät voraus. Hostname, IP-Adresse, MAC-Adresse und Seriennummer sind Inventarmerkmale und keine alleinigen Authentifizierungsmerkmale. Widerrufene Agenten bekommen keine neuen Aufträge und können keine laufende Sitzung erneut öffnen.
5.2 Nachrichten und Flusskontrolle
Ein Nachrichtenumschlag enthält mindestens protocol_version, message_id, agent_id, enrollment_generation, boot_id, sequence, observed_at, payload_type und payload. Der Server ergänzt received_at und den authentifizierten Mandanten. Eine im Payload angegebene Kundenzuordnung wird nicht als Berechtigung übernommen. Schemaänderungen sind versioniert; neue Fähigkeiten werden vor Verwendung ausgehandelt.
Der Server bestätigt dauerhafte Ereignisse erst nach beständiger Übernahme. Der Agent wiederholt unbestätigte Nachrichten; der Empfänger dedupliziert sie. Inventardeltas referenzieren eine Snapshotgeneration. Fehlt die Basis, fordert die Zentrale einen vollständigen Snapshot an. Ein Cursor für Logs oder Proxmox-Tasks wird erst nach bestätigter Speicherung weitergesetzt.
Heartbeats und Auftragssteuerung erhalten Vorrang. Große Dateien, Logströme und interaktive Sitzungen verwenden eigene Kanäle oder begrenzte Teilströme. Größenlimits gelten vor und nach Dekompression. Backpressure, Ratenlimits je Kunde und Gerät, zufällig versetzte Intervalle sowie exponentieller Reconnect mit Jitter verhindern, dass ein Neustart der Zentrale sofort alle Clients gleichzeitig belastet.
6 Datenmodell und Gerätezuordnung
Der Begriff Asset bezeichnet die verwaltete Maschine oder Ressource. Eine Agentinstallation ist eine konkrete Softwareinstallation mit eigenem Schlüssel und Lebenszyklus. Diese Trennung erlaubt Neuinstallation, Proxmox-Discovery vor Agentinstallation und nachvollziehbare Geräteaustausche. Ein entdecktes Asset ohne Agent kann angezeigt, aber nicht über den Gastkanal verwaltet werden.
| Entität | Wesentliche Informationen |
|---|---|
| Tenant und Site | Kunde, Standort, Zeitzone, Richtlinien und Kontakte |
| Asset | Stabile ID, Typ, Rolle, Kunde, Standort, Tags und Lebenszyklus |
| AgentInstallation | Assetbezug, Schlüsselfingerabdruck, Generation, Version und Capabilities |
| Observation und InventorySnapshot | Quelle, Erhebungszeit, Empfangszeit, Qualität und normalisierte Daten |
| SoftwareInstallation | Produkt, Version, Architektur, Quelle und Installationskontext |
| ServiceExpectation | Gewünschter Dienstzustand, zugehöriges Asset und Prüfregel |
| CheckResult und Incident | Messung, Zustand, Schwelle, Zeitverlauf und zusammengefasster Vorfall |
| VirtualizationRelation (optional; PVE nach MVP) | Gastidentität, gegebenenfalls Cluster/Host, Laufzeit und Herkunft; unbekannter Hypervisor/Host ist zulässig und beschränkt den Gastagenten nicht |
| BackupPolicy und BackupEvidence | Sollplan, Versuche, Snapshots, Abdeckung, Verify und Restoretests |
| OperationPlan und AuthorizationGrant | Festgelegte Ziele, Aktion, Artefakte, Planhash und Erlaubnis |
| ApprovalRequest und OperationExecution | Persistenter Genehmigungsantrag mit festen Jobdefinitionen; erst nach menschlicher Genehmigung ein Ausführungslauf mit Einzeljobs |
| Job und JobAttempt | Zustellung, Ausführung, Fristen, Sperren, Ergebnis und Nachbedingungen |
| RemoteSession und AuditEvent | Bediener, Ziel, Rechte, Laufzeit, Nachweise und Aufnahmeverweis |
Relevante Tabellen besitzen tenant_id. Kundenbezogene Fremdschlüssel enthalten ebenfalls den Mandanten, damit eine Beziehung nicht versehentlich in einen fremden Kundenbestand zeigt. Aktuelle Inventarsicht und historische Beobachtungen werden getrennt gespeichert. Nicht vorhandene, nicht ermittelte, veraltete und fehlgeschlagene Daten sind verschiedene Zustände.
Agenten in Vorlagen dürfen noch keine produktive Identität besitzen. Ein Klon führt ein neues Enrollment durch. Treffen zwei aktive Geräte mit demselben Schlüsselnachweis oder widersprüchlichen Maschinenmerkmalen auf, folgt eine Identitätsprüfung statt einer stillen Zusammenführung. Hardwaremerkmale sind Hinweise für diese Prüfung, keine sichere automatische Entscheidung.
Eine Virtualisierungsbeziehung ist optional: Ein Gast mit Agent ohne bekannten Host ist vollständig verwaltbar, auch außerhalb von Proxmox. Nach dem MVP werden bekannte Proxmox-Gäste über Plattform-ID plus Providerverbindung, Cluster, Gasttyp, VMID und Lebenszyklus korreliert. Migration innerhalb eines Clusters ändert die Hostbeziehung. VMID-Wiederverwendung, Restore, Cross-Cluster-Migration und Klonen dürfen nicht allein anhand gleicher Nummern oder Namen zusammengeführt werden. Die optionale Zuordnung zum Gast-Agenten erhält Herkunft und bei Unsicherheit einen Prüfstatus. 9
7 Inventarisierung und Datenerhebung
Die folgenden Intervalle sind konfigurierbare Startwerte. Sie werden im Pilot anhand von Ressourcenverbrauch, Netzlast und Nutzen angepasst. Ereignisbasierte Änderungen ergänzen regelmäßige Erhebungen; ein vollständiger Abgleich korrigiert verlorene Deltas.
| Bereich | Inhalt | Startwert |
|---|---|---|
| Erreichbarkeit | Heartbeat, Agentversion, Uhrabweichung und letzter Kontakt | 30 Sekunden |
| Leistung | CPU, RAM, Swap, Netzwerk, Platten und I/O | 60 Sekunden |
| Erwartete Dienste | Vorhanden, Startart, Laufzustand und definierte Funktionsprüfung | 60 bis 120 Sekunden |
| Betriebssystem | Edition, Build, Architektur, Kernel, Bootzeit und Virtualisierung | Bei Start und täglich |
| Hardware und Datenträger | Hersteller, Modell, CPU, RAM, Volumes, Verschlüsselungsstatus, geeignete SMART Daten | Täglich und bei Änderung |
| Netzwerk | Adapter, Adressen, DNS und Routingmerkmale | Bei Änderung und alle 15 Minuten |
| Software | Installierte Pakete und Programme, Versionen und Installationskontext | Alle 6 bis 24 Stunden |
| Updatezustand | Installierte Updates, ausstehende Updates, Scanzeit, Fehler und Neustartbedarf | Alle 6 Stunden und nach Auftrag |
| Proxmox (nach MVP) | Lokaler Host, Gäste, Storage, Tasks und Clusterzustand | 1 bis 5 Minuten |
| Logs | Relevante Ereignisse oder begrenzte Auszüge mit Quelle und Cursor | Ereignisbasiert oder auf Anfrage |
Für Speicherplatz werden sowohl freie Bytes als auch freie Prozentwerte erfasst. Auf Linux sind Inodes zusätzlich relevant. Eine aggregierte Prozentzahl über alle Laufwerke kann einen vollen Systemdatenträger verbergen. Bei Thin Provisioning werden Host-, Pool- und Gastsicht getrennt gehalten.
Updateinventar benötigt mehrere Felder. Unter Windows gehören Updatehistorie, Ergebnisse des letzten Scans, vorhandene Updates und Neustartbedarf zusammen. Einzelne WMI-Abfragen liefern keinen vollständigen universellen Patchstatus. Unter Linux hängt belastbare Historie von Paketmanager und vorhandenen Logs ab. Fehlende Historie wird als unbekannt dargestellt; Dateizeitstempel werden nicht zu einem angeblich exakten letzten Updatezeitpunkt umgedeutet.
Sicherheitsrelevante Zustände wie Firewall, Endpointschutz und Datenträgerverschlüsselung werden nur über unterstützte Provider erfasst. Prozessargumente, Umgebungsvariablen, private Dateien und Schlüssel werden nicht pauschal inventarisiert. Eine weitergehende Diagnose ist eine eigene, berechtigte Aktion mit definierter Datenmenge.
8 Monitoring und Alarmierung
Die Oberfläche führt drei Zustände getrennt: Verbindung zum Agenten, Frische der jeweiligen Datenquelle und fachliche Gesundheit. Eine laufende VM kann einen nicht erreichbaren Gast-Agenten enthalten. Ein erreichbarer Agent kann einen ausgefallenen Webdienst melden. Ein alter grüner Messwert darf nicht weiterhin als aktueller Erfolg erscheinen.
Bei einem Heartbeat alle 30 Sekunden sind beispielsweise 90 Sekunden ohne Kontakt ein Warnsignal und 180 Sekunden ein Zustand nicht erreichbar. Das sind Richtlinienwerte, keine Feststellung, dass der Rechner ausgeschaltet ist. Gateway-Ausfall, Netzunterbrechung und ausgeschaltetes Gerät sehen aus der Zentrale zunächst ähnlich aus. Wiederholte alte Telemetrie darf die Präsenzanzeige nicht auffrischen. Der Server verwendet für die Verbindung seinen Empfangszeitpunkt und für Messdaten zusätzlich deren tatsächliche Erhebungszeit.
Sollregeln werden je Kunde, Gerätegruppe oder Asset gesetzt: Ein Dienst muss laufen, ein lokaler HTTP-Check muss erfolgreich sein, eine Sicherung darf höchstens ein bestimmtes Alter haben oder ein Datenträger muss eine Reserve behalten. Diensterkennung allein legt noch keinen Sollzustand fest. Ein laufender Prozess beweist nicht die Funktion der Anwendung.
Prüfergebnisse verwenden OK, Warnung, Kritisch, Unbekannt und Unterdrückt. Regeln besitzen Dauerbedingungen, Hysterese, Wartungsfenster und Wiederanlaufverzögerungen. Vorfälle werden dedupliziert; eine Standortstörung kann untergeordnete Meldungen zusammenfassen. Der ursprüngliche Messzustand bleibt erhalten, auch wenn Benachrichtigungen vorübergehend unterdrückt werden.
Automatische Regeln dürfen Behebungspläne und persistente Genehmigungsanträge erzeugen, niemals selbst genehmigen oder ausführen. Jeder feste Job und jeder neue Versuch benötigt explizite menschliche WebUI-Genehmigung. Begrenzende Policies setzen Aktionsgrenzen, Wiederholungslimits und Abkühlzeiten, ersetzen aber keine Genehmigung. Ein Alarm löst keine unbegrenzte Schleife von KI-generierten Reparaturversuchen aus. Die Plattform selbst wird zusätzlich von einer unabhängigen externen Überwachung beobachtet.
9 Proxmox und Backupbeobachtung
Ausbaustufe nach dem MVP: Dieses gesamte Kapitel einschließlich PVE-/PBS-Client, Cluster- und Backupabnahmen ist keine MVP-Voraussetzung. Es ergänzt eigenständig verwaltbare Windows-/Linux-Agenten; weder eine Proxmox-VM noch ein Hostagent wird für deren Betrieb vorausgesetzt. Die folgenden Hostanforderungen gelten nur für ausdrücklich in diese spätere Integration aufgenommene PVE-Hosts.
Auf jedem PVE-Host läuft der Linux-Agent mit Proxmox-Modul. Er fragt die bereits vorhandene lokale PVE-API ab und sendet seine Ergebnisse ausgehend zur Zentrale. PVE stellt die API über HTTPS auf Port 8006 bereit und kann clusterinterne Anfragen zwischen Knoten weiterleiten. Die vorhandene Proxmox-Clusterkommunikation ist von der RMM-Netzwerkanforderung zu unterscheiden. Die Zentrale baut keine neue Verbindung auf Port 8006 zum Kunden auf. 10
Jeder Host meldet seine lokalen Daten. Clusterweite Inventar- und Planabfragen übernimmt jeweils ein dafür ausgewählter Collector mit zeitlich begrenzter Zuständigkeit und Generation. Eine überholte Collector-Generation darf die aktuelle Inventarsicht nicht überschreiben. Unveränderliche historische Taskereignisse dürfen weiterhin authentifiziert, geprüft und dedupliziert übernommen werden. Bestätigte Cursor werden pro Quelle zentral geführt; verworfene Daten dürfen keinen Cursor vorziehen. Ereignisse werden zusätzlich anhand von Quellkennung und Taskkennung dedupliziert. Diese Auswahl regelt die Datenerhebung, nicht eine automatische Übernahme administrativer Clusteraktionen.
Erfasst werden Mitglieder und Quorum, HA-Zustände, PVE-Version, laufender Kernel, Gäste und Templates, Storage, ZFS oder Ceph soweit vorhanden, Ressourcenzuteilung und relevante Tasks. Eine reine API-Loginprobe genügt nicht als Funktionsprüfung: Der Connector muss auch fremd gestartete Tasks und deren Fehler sehen können. Berechtigungen werden gegen jede unterstützte PVE-Version getestet. 11
Für lesende API-Zugriffe wird ein dedizierter Benutzer mit getrennt berechtigtem Token verwendet. PVEAuditor ist ein Ausgangspunkt, kein Ersatz für die Prüfung der konkret verwendeten Endpunkte. Schreibende Funktionen erhalten eigene Fähigkeiten und Rechte. Ein parallel erlaubter Root-Executor kann diese Tokenbegrenzung auf dem Host umgehen; die technische Grenze entsteht erst durch den getrennten und kontrollierten Administrationspfad. 11
9.1 Backupnachweise
Eine Backupübersicht beantwortet getrennt: War eine Sicherung fällig? Wurde sie versucht? War der einzelne Gast erfolgreich? Sind die benötigten Datenträger enthalten? Existiert der Snapshot noch? Ist seine Integrität geprüft? Gibt es einen erfolgreichen praktischen Restoretest?
Die Plattform speichert geplante und effektive Gastauswahl, Taskkennung beziehungsweise UPID, Versuch und Ergebnis je Gast, Ziel, Dauer, Alter, ausgeschlossene Datenträger und Fehler. Eine fehlende Sicherung wird auch dann erkannt, wenn kein fehlgeschlagener Task existiert. Taskhistorie wird paginiert und inkrementell gesichert; die Plattform setzt keine unbegrenzte Historie auf dem Host voraus.
Zusätzliche LXC-Mountpoints sind nicht automatisch vollständig im Backup enthalten. Bind- und Device-Mounts werden von PVE nicht als normale Container-Backupinhalte gesichert. Deshalb ist Abdeckung ein eigenes Prüffeld. Ein grüner Gesamtjob reicht als Nachweis nicht aus. 12
9.2 Proxmox Backup Server
PBS besitzt eine eigene API, eigene Rechte und eine eigene Datensicht. Für das strikte ausgehende Modell kann derselbe Linux-Agent mit PBS-Modul auf dem Backupserver laufen. Er meldet Datastores und Namespaces, Snapshotbestand, Verify-, Sync-, Prune- und GC-Zustände sowie Kapazität. Die Zentrale benötigt keinen direkten Zugriff auf PBS-Port 8007.
Für Status und Auflistung reichen passende Audit-Rechte; ein Restore-fähiger DatastoreReader ist nicht automatisch erforderlich. Kunden- und Clusterzuordnung werden auch bei gemeinsamem PBS ausdrücklich gespeichert. 13 Eine erfolgreiche PBS-Verifikation ist ein Integritätsnachweis innerhalb der Möglichkeiten des jeweiligen Backups. Ein Restoretest prüft zusätzlich Schlüsselverfügbarkeit, Start und Anwendungsfunktion. Diese Ergebnisse werden getrennt ausgewiesen. 14
10 Aufträge und Softwareinstallation
Jeder auszuführende Job, auch lesende Live-Diagnose, wird zunächst zu einem unveränderlichen Plan. Dieser enthält konkrete Geräte-IDs, feste Einzeljobs und Versuche, Aktion, normalisierte Parameter, Paket- oder Skriptversion, Artefakthash, erforderliche Ausführungsidentität, Vorbedingungen, Nachbedingungen, Wartungsfenster, maximale Laufzeit und Ablaufzeit. Eine dynamische Gruppe wird vor dem Speichern zu einer festen Zielmenge aufgelöst. Die menschliche WebUI-Freigabe bezieht sich ausschließlich auf diesen gespeicherten Plan; nachträglich hinzugekommene Geräte werden nicht ergänzt. Passive Standardtelemetrie und Lesen gespeicherter Daten sind keine Jobs.
Der Server prüft Benutzerrechte und begrenzende Kundenrichtlinie. Richtlinien dürfen nur begrenzen oder verweigern. Genau dieser Plan benötigt stets eine konkrete menschliche Genehmigung in der WebUI; ein transparent angezeigtes Sammelpaket kann alle festen Einzeljobs gemeinsam genehmigen. Ändern sich Ziele, Parameter, Wirkung oder Versuch, entsteht ein neuer genehmigungspflichtiger Plan. Dauer-/Wildcardfreigaben sind verboten. Weder Modell noch MCP-/Automatisierungsidentität dürfen genehmigen. Rechteentzug und Gerätewechsel werden vor dem Start erneut geprüft.
Die Prüfung findet bei Planung, Einreihung und unmittelbar vor dem Start statt. Ein kurzlebiger Ausführungsgrant bindet außerdem die Version der Kunden- und Gerätezuordnung. Rechteentzug sperrt neue Starts. Bereits laufende Installationen werden nur abgebrochen, wenn der Provider einen sicheren Abbruch unterstützt; andernfalls laufen sie kontrolliert zu Ende und das Ergebnis wird erfasst. Ein Paketmanager wird nicht pauschal hart beendet. Interaktive Sitzungen werden geschlossen. Ein Entzug macht bereits erfolgte Änderungen nicht rückgängig.
flowchart TD
Plan["Unveränderlicher Plan"] --> Policy{"Berechtigung und Richtlinie"}
Policy -->|"zulässig, noch nicht genehmigt"| Request["Persistenter Antrag pending_approval"]
Policy -->|"verweigert"| Denied["Keine Ausführung"]
Request --> Approval["Menschliche WebUI-Planfreigabe"]
Approval --> Queue["Dauerhafte Ausführungsjobs und Outbox"]
Queue --> Accepted["Lokal journalisiert"]
Accepted --> Start{"Aktuelle Starterlaubnis"}
Start -->|"gültig"| Run["Ausführen und nachprüfen"]
Start -->|"Frist abgelaufen"| Expired["Abgelaufen"]
Run --> Success["Erfolg bestätigt"]
Run --> Failure["Fehler bekannt"]
Run --> Unknown["Wirkung unbekannt"]
Unknown --> Reconcile["Zustand abgleichen"]
Reconcile --> Success
Reconcile --> Failure
Das Diagramm zeigt den fachlichen Ablauf. Die vollständigen, normativen Jobzustände und Übergangsregeln stehen in Abschnitt 22. Freigabe, Netzwerkzustellung, Prozessstart und fachlicher Erfolg sind unterschiedliche Ereignisse.
Planerstellung, Antrag und menschliche Freigabe sind getrennte dauerhafte Schritte. operations.submit speichert nur den Genehmigungsantrag (pending_approval), keine Ausführungsjobs oder ausführbare Outbox. Erst die WebUI-Genehmigung erzeugt atomar Genehmigungsnachweis, Ausführungslauf, feste Einzeljobs und Outbox-Einträge. Vor Ausführung wird die aktuelle Starterlaubnis erneut geprüft; Abschnitt 22 legt die Transaktionsgrenzen fest. Worker übernehmen ausschließlich genehmigte Arbeit mit transaktionaler Sperre und begrenzter Zuständigkeit. PostgreSQL unterstützt SKIP LOCKED für konkurrierende Verbraucher einer Warteschlangentabelle. Dies organisiert die Vergabe; es garantiert nicht genau eine Wirkung auf einem entfernten Betriebssystem. 15
Der Agent bestätigt die Annahme erst nach Eintrag im lokalen dauerhaften Journal. job_id und Ausführungsidentität bleiben stabil. Ein wieder zugestellter Auftrag wird am Journal erkannt. Kollidierende Aktionen werden pro Ressource serialisiert, insbesondere Paketinstallationen, Reboots und Agentupdates. Eine Idempotenzkennung ist an Aufrufer, Mandant und Inhalt gebunden; gleicher Schlüssel mit geändertem Inhalt führt zu einem Fehler.
Zustellung und Wirkung sind verschieden: Netzbedingt wird eine Nachricht möglicherweise mehrmals zugestellt. Eine beliebige Installation oder Shellaktion kann nicht atomar zusammen mit SQLite und der zentralen Datenbank bestätigt werden. Nach einem Absturz zwischen Wirkung und Ergebnis lautet der Zustand deshalb zunächst unbekannt. Ein Verlust der Zuständigkeit berechtigt keinen zweiten Worker, die Aktion blind erneut auszuführen. Idempotente API-Verträge verlangen genau diese bewusste Behandlung von Wiederholungen. 16
Vor einer Wiederholung wird der tatsächliche Zustand abgeglichen. Ein Auftrag ensure_package mit fester Version lässt sich über das installierte Produkt prüfen. Separate Diagnosejobs für den Abgleich benötigen ebenfalls menschliche Genehmigung; Lesen gespeicherter Nachweise nicht. Ein neuer Ausführungsversuch benötigt stets einen neuen menschlich genehmigten Plan. Erneute Zustellung desselben Versuchs benötigt keine neue Genehmigung und darf keine zweite Wirkung auslösen. Nach Snapshot-Restore synchronisiert der Agent seine Generation und Auftragslage mit der Zentrale, bevor neue Jobs beginnen.
Ein Installationsjob besteht aus Prüfung, Paketbezug, Herkunfts- und Hashprüfung, Ausführung, Erfassung des Ergebnisses und gebundener Nachprüfung der installierten Version. Ein Installer-Exitcode allein ist nicht immer ein Erfolgsbeleg. Neustartbedarf ist ein eigener Zustand. Ein erforderlicher Reboot ist ein eigener menschlich zu genehmigender Folgejob mit Wiederanmeldung und Nachprüfung; er darf im ursprünglichen transparenten Sammelpaket bereits als fester Einzeljob enthalten sein, nicht als pauschale Folgeerlaubnis.
Während einer laufenden Installation darf eine Netzwerkunterbrechung den Installer nicht automatisch abbrechen. Ergebnisse werden lokal gepuffert und später übermittelt. Vor dem Start abgelaufene Aufträge werden verworfen. Abbrechen bedeutet zunächst Abbruch angefordert; der Executor meldet, ob ein sicherer Abbruch möglich war. Ein Abbruch ist keine allgemeine Rollbackzusage. Rollouts erfolgen in Gruppen mit Testgeräten, Parallelitätsgrenzen und Abbruchschwellen.
11 Shell und Bereitstellung von RustDesk
Für viele Verwaltungsaufgaben genügen strukturierte Jobs: Dienststatus live lesen, Logs erheben, Software installieren, Updates anwenden und Neustarts planen. Jeder dieser Jobs benötigt menschliche WebUI-Genehmigung. Für offene Diagnose steht später eine interaktive Sitzung zur Verfügung. Der Nutzer wählt Gerät und Berechtigungsstufe; erst nach expliziter menschlicher WebUI-Genehmigung des konkreten Sitzungsplans stellt der Server ein kurzlebiges, an Nutzer, Gerät, Plan und Sitzung gebundenes Ticket aus. Eine Sitzung ist keine Dauerfreigabe für neue strukturierte Jobs.
Der Agent erhält das Ticket über seinen ausgehenden Steuerkanal und öffnet anschließend ausgehend einen separaten Stream zum Relay. Lokal startet er die zugelassene Shell, unter Linux über ein PTY und unter unterstützten Windows-Versionen beispielsweise über ConPTY mit PowerShell. Das Relay vermittelt Ein- und Ausgabe zur Weboberfläche. Resize, EOF, Prozessende und Signalbehandlung gehören zum Sitzungsprotokoll.
Sitzungen besitzen Höchstdauer, Leerlaufzeit, explizite Beendigung, aktive Widerrufskontrolle und nachvollziehbare Zuordnung. Ein verlorener Browserkontakt beendet eine privilegierte Sitzung nach definierter kurzer Frist. Aufzeichnungen können vertrauliche Daten enthalten und erhalten eigene Zugriffsrechte und Aufbewahrungsregeln. Die Verbindung wird im ersten Entwurf am Relay terminiert; das Relay gehört somit zur Vertrauensgrenze. Echte Ende-zu-Ende-Verschlüsselung würde zentrale Aufzeichnung und Inspektion verändern.
Für grafische Zugriffe stellt die Plattform RustDesk auf den gewünschten PCs bereit. Sie implementiert keine Bildschirmübertragung, Maussteuerung oder eingebettete Desktop-Engine. Der Nutzer verbindet sich anschließend über seinen RustDesk-Client. RustDesk dokumentiert die automatisierte Verteilung und das Anwenden von Serverkonfigurationen über Skripte beziehungsweise --config. 17
Ein versioniertes RustDeskConfigProfile gehört einem Kunden oder einer Gerätegruppe. Es enthält die freigegebene Paketversion, den ID-Server, gegebenenfalls Relay- und API-Server, den öffentlichen Serverschlüssel sowie die gewünschten Zugriffsregeln. Zugangsdaten werden als geschützte Secret-Referenzen geführt und nicht in normale Jobausgaben oder LLM-Kontexte geschrieben. Bestehende kundenspezifische Einstellungen werden nur gemäß dem gewählten Profil geändert. Ein wiederholter Auftrag gleicht den Sollzustand ab und setzt Zugangsdaten nicht unbeabsichtigt zurück.
Die typisierte Aktion ensure_rustdesk prüft Betriebssystem und Architektur, installiert das passende Paket, richtet bei Bedarf den Systemdienst ein und wendet die Konfiguration im tatsächlich genutzten Dienst- und Benutzerkontext an. Anschließend meldet der Agent Version, RustDesk-ID, Dienstzustand und angewendete Profilversion. Installiert, konfiguriert und für eine Verbindung erreichbar bleiben getrennte Nachweise. Ein Praxistest belegt die Verbindung mit dem vorgesehenen RustDesk-Client; ein laufender Dienst allein genügt dafür nicht. Die Abnahme prüft außerdem den Zustand nach einem Rechnerneustart.
RustDesk verwendet seine eigene Verbindungsinfrastruktur. Seine Verbindungen werden nicht automatisch durch den RMM-Agentkanal transportiert. Für strikt ausgehenden Betrieb wird ein getesteter Relaymodus vorgesehen. Eine Beschränkung auf Port 443 erfordert eine dafür geeignete Kombination aus RustDesk-Client, Serveredition, Version und WSS-Konfiguration. Diese Voraussetzungen werden ausdrücklich geprüft; die Eigenschaft des RMM-Kanals wird nicht pauschal auf RustDesk übertragen. Die offizielle Dokumentation beschreibt einen WSS-Relaybetrieb über TCP 443. 18
Dateitransfer erhält einen eigenen autorisierten Vorgang mit Pfadgrenzen, Größenlimits und Hashkontrolle. Portweiterleitungen sind ausschließlich für konkret freigegebene Ziele und Laufzeiten zulässig. Ein allgemeiner Tunnel ins gesamte Kundennetz gehört nicht zum Standardprofil. Ein ausgeschaltetes oder vollständig isoliertes Gerät kann über seinen Agenten keine Aufträge ausführen; Out-of-Band-Management wäre eine gesonderte Integration.
12 MCP und Steuerung durch KI
MCP wird am zentralen Server über HTTPS angeboten. Der Agentkanal bleibt ein eigenständiges Protokoll. Ein MCP-Aufruf kann einen dauerhaften Genehmigungsantrag erzeugen und dessen operation_id mit pending_approval zurückgeben, aber keinen Job vor menschlicher WebUI-Genehmigung starten. Genehmigte Jobs laufen unabhängig von der KI-Unterhaltung. Bei einem Modell- oder MCP-Ausfall funktionieren Weboberfläche, Monitoring und laufende Jobs weiter.
Der MCP-Adapter verwendet rmcp und Streamable HTTP. SDK, Protokollversion und unterstützte KI-Clients werden gemeinsam festgelegt und im Repository dokumentiert. Transport- und Sessionverhalten richten sich nach genau diesem geprüften Profil; verschiedene Protokollstände dürfen nicht unbemerkt vermischt werden. Persistente RMM-Jobs bleiben unabhängig vom MCP-Transport Anwendungsdaten. 2 19
| MCP Werkzeug | Aufgabe |
|---|---|
| tenants.list | Für die Identität sichtbare Kunden eindeutig auflösen |
| inventory.list_devices | Berechtigte Geräte eines Kunden mit Filtern und Pagination liefern |
| inventory.get_device | Inventar, Quelle, Erhebungszeit und Datenalter eines Geräts liefern |
| monitoring.get_health | Probleme und begrenzte Metrikverläufe abrufen |
| logs.query | Gespeicherte erlaubte Logs lesen; Live-Erhebung als genehmigungspflichtigen Diagnoseplan beantragen |
| operations.plan | Paket, Dienstaktion, Update oder Skript als Plan vorbereiten; RustDesk mit Profil nur spätere optionale Erweiterung, keine MVP-Schnittstellenpflicht |
| operations.submit | Plan als dauerhaften Antrag pending_approval einstellen; keine Ausführungsqueue erzeugen |
| jobs.get | Antrag inklusive pending_approval, spätere Ausführung, Fortschritt und Ergebnis abfragen |
| jobs.cancel | Abbruch anfordern und dessen tatsächlichen Ausgang anzeigen |
| sessions.request | Eine zeitlich begrenzte privilegierte Sitzung beantragen |
Ein Tool mit beliebigem Shelltext ist kein Standardwerkzeug für alle KI-Aufgaben. Freie Skripte sind möglich, besitzen aber eine eigene Berechtigung, feste Skriptbytes, einen Hash und eine dazu passende Richtlinie. Die Werkzeuge liefern strukturierte Ergebnisse mit Datenalter, Vollständigkeit und Fehlern. Fachliche Begrenzungen werden serverseitig geprüft; Toolbeschreibungen allein sind keine Autorisierung.
Damit sind Sammelaufträge wie ein Neustart ausgewählter Server oder Hello World ausdrücklich vorgesehen, stets erst nach menschlicher WebUI-Genehmigung. Das LLM erzeugt passende PowerShell- und Shellvarianten. Der Plan bindet Inhalt und Interpreter an feste Zielgeräte und Einzeljobs. Die WebUI zeigt Zielanzahl, Inhalte/Hashes und Auswirkungen vor der Sammelgenehmigung. Die Plattform meldet Ausgabe und Ergebnis je Gerät. Neustarts können gestaffelt werden. Offlinegeräte führen nur bereits genehmigte Jobs nach Wiederverbindung aus, sofern Freigabe und Frist weiterhin gelten.
12.1 Autonomie im Alltag
| Stufe | Beispiel | Ausführung |
|---|---|---|
| Lesen | Bereits gespeicherte Geräte-/Logdaten lesen | Innerhalb der Leserechte ohne Einzelgenehmigung; passive Standardtelemetrie ebenfalls kein Job |
| Diagnose | Live-Logfenster oder Diagnoseplaybook ausführen | Jeder Job erst nach menschlicher WebUI-Genehmigung des festen Plans |
| Standardänderung | Paket auf einer festen Gerätemenge installieren | Jeder Job erst nach menschlicher WebUI-Genehmigung; Sammelpaket möglich |
| Erweiterte Administration | SYSTEM-Sitzung, Reboot oder Massenänderung | Eigene Berechtigung und konkrete menschliche WebUI-Genehmigung; Policies begrenzen nur |
Richtlinien begrenzen nicht nur einen einzelnen Toolaufruf, sondern auch aufsummierte Aktionen: beispielsweise maximale Gerätezahl pro Stunde, Anzahl Neustarts, Laufzeit und Fehlerquote. Sonst könnte eine Folge kleiner Aufträge eine Grenze für Massenänderungen umgehen. Globale, kundenbezogene und gerätespezifische Stopps können neue Änderungen sperren.
Beispiel: „Installiere das Monitoringwerkzeug auf Server X bei Kunde A“ wird auf eine eindeutige asset_id aufgelöst. Der Server ermittelt Paket, Version, Rezept und gespeicherten Zustand, erstellt den festen Plan und prüft begrenzende Policies. MCP stellt einen Antrag pending_approval. Erst nach menschlicher WebUI-Genehmigung erfolgt die Ausführung. Die KI berichtet nur den tatsächlich bestätigten Zustand einschließlich Neustartbedarf oder unbekanntem Ergebnis. Bei mehreren passenden Servern wird die Auswahl geklärt; eine zusätzliche Live-Diagnose benötigt selbst Genehmigung.
12.2 Identität und nicht vertrauenswürdige Daten
MCP verwendet den authentifizierten Nutzer oder eine ausdrücklich eingerichtete Automatisierungsidentität. Token werden auf Aussteller, Signatur beziehungsweise Gültigkeit, Ablauf und Zielressource geprüft. Scope und Kundenmitgliedschaft werden kombiniert. MCP-Token werden nicht als allgemeine Zugangsdaten an Kundensysteme weitergereicht. Die MCP-Spezifikation verlangt eine Prüfung der vorgesehenen Token-Audience. 20
Logzeilen, Dateiinhalte und Paketbeschreibungen können manipulierte Anweisungen enthalten. Sie bleiben Daten, auch wenn sie durch einen eigenen Agenten geliefert werden. Nachfolgende Toolaufrufe werden unabhängig davon autorisiert. Filter und eine Anweisung an das Modell, Logs nicht zu befolgen, sind zusätzliche Hilfen, aber keine Sicherheitsgrenze. 21
Das System sendet standardmäßig nur benötigte Ausschnitte an ein Modell. Rohdatenzugriff und die Erlaubnis zur Weitergabe an einen externen KI-Anbieter sind unterschiedliche Rechte. Anbieter, erlaubte Datenkategorien, Aufbewahrung und regionale Anforderungen werden je Kunde konfiguriert. Die Zentrale gibt dem Modell weder allgemeine Root-Zugangsdaten noch einen unbeschränkten Secret-Lesezugang.
13 Mandanten und Schutz der Verwaltungsfunktionen
Kundenrechte werden bei jedem Zugriff auf Asset, Job, Plan, Logobjekt und Sitzung geprüft. Die Kenntnis einer UUID reicht nicht als Zugriffserlaubnis. Ein angefragter tenant_id ist ein Filterwunsch; der authentifizierte Kontext entscheidet über die zulässige Menge. Rollen können Lesen, Operator, Freigeber, Kundenadministrator und Plattformbetrieb unterscheiden und zusätzlich auf Gerätegruppen eingeschränkt werden.
PostgreSQL Row Level Security bildet eine zusätzliche Barriere. Die Anwendung nutzt eine Rolle ohne Superuser- oder BYPASSRLS-Rechte und besitzt die Tabellen nicht. Der Kundenzustand wird innerhalb jeder Transaktion gesetzt und bei Connection-Pooling nicht zwischen Anfragen weiterverwendet. Migrationen besitzen eine separate Identität. RLS-Regeln berücksichtigen USING und WITH CHECK; Tests müssen auch Hintergrundjobs, Exporte und Fehlerpfade erfassen. PostgreSQL dokumentiert ausdrücklich Ausnahmen für Eigentümer und privilegierte Rollen. 22
Bei gemeinsam genutzten Hypervisoren gehört die Host- und Clustersicht einem Infrastrukturmandanten des Dienstleisters. Einzelne Gäste können anderen Kunden gehören. Ein eng berechtigter Zuordnungsdienst erzeugt daraus die freigegebenen Kundensichten anhand expliziter Zuweisungen. Kundennutzer sehen weder vollständige Hostinventare noch Namen oder Daten benachbarter Gäste. Neue und unklare Gäste bleiben zunächst unzugeordnet. Historische Zuordnungen erhalten Gültigkeitszeiträume.
Bei einem Kundenwechsel wird die historische Kundenzugehörigkeit nicht pauschal überschrieben. Bestehende Historie bleibt nach festgelegter Aufbewahrungsregel beim bisherigen Mandanten; neue Beobachtungen und Rechte folgen der neuen Zuweisung. Fehlender Mandantenkontext bedeutet in Datenbank, Worker und Metrikabfrage immer verweigerten Zugriff.
Ein Gast-Agent darf nur sein eigenes Gerät melden. Ein Proxmox-Collector erhält eine separat registrierte Quellberechtigung für seinen Cluster. Selbst ein gültig authentifizierter Host darf keine beliebigen fremden Assets oder Mandanten in seinem Payload behaupten. Für schreibende Hypervisoraktionen wird das konkrete Gastziel zusätzlich anhand des aktuellen Mappings überprüft.
Aufträge werden mit manipulationsgeschützten Autorisierungsnachweisen an Planhash, Ziel, Aktion, Frist und Gerätegeneration gebunden. Signierschlüssel für Agentsoftware, Geräteidentitäten und administrative Aufträge sind getrennt. Ein kompromittierter Netzwerkgateway soll allein weder neue Agentsoftware signieren noch eine beliebige privilegierte Aktion freigeben können. Offline befindliche Geräte sehen einen zentralen Widerruf erst wieder bei Kontakt; kurze Grant-Laufzeiten und erneute Startprüfung begrenzen dieses Fenster.
Audits enthalten tatsächlichen Bediener, Automatisierungsidentität, Kunde, Gerät, Planhash, Richtlinienentscheidung, Ausführungsidentität und überprüftes Ergebnis. Secrets werden redigiert. Für kritische Vorgänge werden Kopien mit getrennten Schreib- und Löschrechten aufbewahrt. Eine veränderbare SQL-Tabelle allein begründet keine manipulationssichere Historie. Ein kompromittierter Agent kann trotz Authentisierung über seinen lokalen Zustand lügen; das System darf daraus keinen unabhängigen Sicherheitsbeweis ableiten.
14 Oberfläche und Bedienung
Die Startseite zeigt Kunden mit offenen Vorfällen, nicht erreichbaren Geräten, veralteten Daten, Updateproblemen und Backupabweichungen. Ein Kunde führt zu Standorten und Geräten. Die Geräteseite enthält Überblick, Inventar, Messwerte, Dienste, Software, Updates, Logs, Aufträge, Sitzungen und Änderungshistorie. Jede Anzeige besitzt einen erkennbaren Erhebungszeitpunkt.
Nach dem MVP zeigt die optionale Proxmox-Ansicht Cluster, Hosts, VMs und LXC-Container mit getrennten Zuständen für Hypervisor, Gast-Agent und Anwendung. Spätere Backupansichten unterscheiden fehlende Sicherungen, gescheiterte Versuche, Integritätsprüfung und praktischen Restore. Im MVP und danach darf eine fehlende Hostbeziehung keine Gastverwaltung sperren; ein Konnektivitätsproblem der Plattform wird nicht als bestätigter Geräteausfall ausgegeben.
Die Geräteseite zeigt bei bereitgestelltem RustDesk zusätzlich dessen ID, Version, Dienstzustand und Konfigurationsprofil. Diese Angaben unterstützen den Wechsel in den separaten RustDesk-Client. Der eigene Sitzungsbereich bleibt auf administrative Terminalfunktionen beschränkt.
Vor jeder Jobgenehmigung zeigt die WebUI den unveränderlichen Plan, sämtliche festen Einzeljobs/Versuche, Zielanzahl und Zielgeräte, Aktion, Interpreter/Provider, Skript-/Paketbyteshash, Paket-/Skriptversion, Rechte, Fristen, mögliche Neustarts und Nachprüfung. Große Sammelpakete bleiben vollständig einsehbar, nicht nur als Anzahl. Ein berechtigter interaktiv angemeldeter Mensch genehmigt explizit diesen Plan; Policyentscheidungen sind nur zusätzliche Begrenzungen. Bei Massenauswahl bleibt die Zielmenge als Snapshot erhalten. Anträge zeigen pending_approval; erst danach liefern Ausführungsjobs Fortschritt und Ergebnisse unabhängig vom Browserfenster.
Für die optionale Zuordnung verkaufter Dienste wird später ein BusinessService mit Kunde, Owner, Vertragsbezug und Abhängigkeiten ergänzt. Eine Betriebsprüfung wie „nginx soll laufen“ bleibt eine technische ServiceExpectation. Beide können verbunden werden, haben aber unterschiedliche Lebenszyklen. Das verhindert, dass Dienstüberwachung von einer noch nicht benötigten Vertragsverwaltung abhängig wird.
15 Speicherung und Größenordnung
PostgreSQL speichert Inventar, Beziehungen, Regeln, Aufträge und Auditmetadaten. Größere Binärdaten und Ausgaben liegen verschlüsselt in einem S3-kompatiblen Objektspeicher. Downloads werden nach erneuter Objektberechtigungsprüfung vermittelt oder mit kurzlebigen, eng gebundenen Downloadrechten ausgegeben. Objektpfad oder Dateiname allein stellen keine Mandantengrenze dar.
Zeitreihen erhalten einen getrennten Speicherzugriff. Für eine kleine technische Pilotierung sind partitionierte PostgreSQL-Messwerttabellen möglich. Für den vorgesehenen laufenden Produktivbetrieb wird VictoriaMetrics als eigener Messwertdienst empfohlen. Dadurch verdrängen hohe Messraten nicht die Latenz der Auftragsverwaltung. Die Empfehlung ist eine Architekturabwägung und keine Benchmarkzusage.
VictoriaMetrics Single Node bietet nicht dieselbe native Mandantenverwaltung wie die Clustervariante; eine Trennung kann dort über erzwungene Labels und einen vorgeschalteten Zugriffsdienst erfolgen. Im Entwurf bleiben alle Datenbankendpunkte intern. Der Rust-Dienst setzt das Kundenlabel beim Schreiben aus der authentifizierten Zuordnung und erzwingt es bei jedem Lesen. Browser und MCP erhalten nur definierte Metrikabfragen, keine beliebigen PromQL-, Metadaten- oder Exportzugänge. Für eine strengere Datenbankgrenze kommen die Cluster-Mandantenfunktion oder getrennte Speicherinstanzen zum Einsatz. 23
Eine Beispielrechnung zeigt die Größenordnung: 1.000 Geräte mit 40 Werten pro Minute erzeugen 57,6 Millionen Messpunkte pro Tag. Bei 10.000 Geräten sind es 576 Millionen. Bei einem Heartbeat je 30 Sekunden ergeben sich ungefähr 33 beziehungsweise 333 Heartbeats pro Sekunde. Das sind arithmetische Lastszenarien; Speicherbedarf und Hardware hängen zusätzlich von Labels, Kompression, Aufbewahrung und Abfragen ab.
Hohe Kardinalität wird begrenzt: Prozess-IDs, freie Dateipfade, Logtexte und unbeschränkte frei wählbare Tags sind keine geeigneten dauerhaften Metriklabels. Per-Disk- und Per-Interface-Daten erhalten kontrollierte Dimensionen. Abfragen begrenzen Zeitraum, Ergebnisgröße und Auflösung. Kundenquoten verhindern, dass eine einzelne Installation die Plattform mit Messwerten oder Logs überlastet.
Als Startpolitik sind beispielsweise 30 Tage Rohmetriken und länger gespeicherte stündliche Zusammenfassungen sinnvoll. Langzeitaggregate werden ausdrücklich über einen Aggregationspfad oder eine dafür geeignete Produktfunktion erzeugt; kostenlose automatische Verdichtung wird nicht vorausgesetzt. Inventarhistorie, Logs, Audits und Aufzeichnungen erhalten unterschiedliche, kundenbezogene Aufbewahrungsregeln. Rohlogs werden überwiegend lokal gehalten und anlassbezogen abgefragt.
Der lokale Offlinepuffer hat feste Größen- und Altersgrenzen. Bei Platzmangel werden ältere unkritische Messwerte verdichtet oder verworfen, bevor Betriebssystem oder Jobjournal gefährdet sind. Ein Geräteausfall darf nicht durch ein unbegrenztes Telemetrieverzeichnis verursacht werden. Verlorene Messwerte und unvollständige Zeitfenster werden sichtbar ausgewiesen.
16 Betrieb und Aktualisierung
Die Pilotbereitstellung besteht aus einem kontrollierten HTTPS-Eingang, Rust-Diensten, PostgreSQL und gegebenenfalls Messwert- und Objektspeicher auf einer zentralen Umgebung. Ein OIDC-fähiger Identitätsanbieter liefert Anmeldung und Mehrfaktorauthentisierung für Administratoren. Exponiert werden nur die benötigten HTTPS-Endpunkte für Bedienung, MCP, Enrollment, Agenten und Sitzungen. Datenbanken und interne Verwaltungsports bleiben im privaten Betriebsnetz.
Für verlässlichen Produktivbetrieb werden Gateway und API mehrfach bereitgestellt, Worker redundant ausgeführt und Datenbankausfallsicherheit sowie Wiederherstellung geplant. Langlebige Verbindungen bleiben einem Gateway zugeordnet; nach dessen Ausfall verbinden sich Agenten mit Jitter erneut. Laufende Agentjobs können unabhängig davon weiterlaufen. Ein Sitzungsabbruch wird sichtbar behandelt, statt eine transparente Wiederaufnahme einer privilegierten Shell zu versprechen.
Ein anfängliches Betriebsziel kann sein, nach Verlust der zentralen Umgebung innerhalb von vier Stunden wieder betriebsfähig zu werden und höchstens 15 Minuten Stammdatenänderungen zu verlieren. Diese RTO- und RPO-Werte sind zu vereinbarende Ziele. Für Aufträge wird unabhängig davon Restore-Abgleich verlangt: Ein älterer Datenbankstand darf keine bereits ausgeführten Änderungen erneut auslösen. Nach Wiederherstellung startet die Plattform zunächst mit gesperrten Änderungen, gleicht Journale und Generationen ab und öffnet die Ausführung kontrolliert.
Backups umfassen Datenbank, Objektdaten, Konfiguration und den gesondert gesicherten Schlüsselbestand. Wiederherstellungstests überprüfen auch das erneute Authentisieren vorhandener Agenten. Schlüsselverlust, kompromittierte Signierschlüssel und lange offline gebliebene Geräte benötigen dokumentierte Recovery-Verfahren. Die Alarmierung der Plattform selbst nutzt einen unabhängigen Kommunikationsweg.
Agentupdates sind signiert, nach Betriebssystem und Architektur getrennt und werden zunächst an Testgeräte verteilt. Ein kleiner Updater prüft Manifest, Version, Hash und Signatur, installiert atomar soweit plattformspezifisch möglich und testet den neuen Dienst. Ein fehlerhafter Start erlaubt die Rückkehr auf eine zulässige letzte Version. Ein Schutz gegen das Einspielen beliebiger veralteter Versionen bleibt bestehen. Rotation und Widerruf von Updateschlüsseln werden von Beginn an berücksichtigt; TUF beschreibt die relevanten Angriffe auf Updatekanäle. 24
CI prüft Rust-Abhängigkeiten und erzeugt reproduzierbar nachvollziehbare Pakete, Herkunftsnachweise und eine Komponentenliste. Native Windows-Tests laufen auf Windows, Linux-Pakettests auf passenden Systemen. PVE- und ARM64-Tests werden erst in ihrer Ausbaustufe verpflichtend, nicht für das MVP. Protokoll- und Datenbankmigrationen unterstützen überlappende Server- und Agentversionen. Die konkrete Kompatibilitätsdauer wird veröffentlicht. Ein Kunde wird nicht durch ein zentrales Update gezwungen, alle Geräte gleichzeitig zu aktualisieren.
17 Umsetzung in überprüfbaren Schritten
| Schritt | Inhalt | Abnahmekriterium |
|---|---|---|
| 1 Technische Grundlagen | Zuerst Linux-Dienst auf tatsächlicher Test-VM, Enrollment, Zertifikate, WSS und Long Polling | Reale VM-Verbindung hinter NAT, Rotation und Widerruf; Proxyabnahmen je bereitgestellter Umgebung |
| 2 Lesendes Produkt | Kunden, Standorte, Inventar, Präsenz, Metriken und Sollprüfungen | Geräteansichten zeigen korrekte Quellen und Datenalter; Mandantentests bestehen |
| 3 Kontrollierte Verwaltung (MVP) | Planbindung, begrenzende Policies, WebUI-Genehmigung gemäß 0.1, Startgrants, dauerhafte Jobs, Paketkatalog, Dienste, Logs und MCP Lesen; ohne RustDesk | Jeder Job erst nach UI-Genehmigung; keine blinden Doppelaktionen; keine RustDesk-Abnahme |
| 4 MCP und Sammelaktionen (Linux-MVP-Abschluss) | MCP plant und beantragt auf derselben Strecke; eigenständiger Linux-Agent x86-64 | Alle Features zuerst auf realer Linux-VM; Sammelpakete erst nach menschlicher WebUI-Genehmigung; unbekannter Hypervisor blockiert keinen Gast |
| 4b Windows nach Linux-MVP | Windows-x86-64-Adapter und M0–M5-Capabilities portieren | Native Windows-Dienst-/Installer-/Mischplattformabnahmen erst nach Linux-MVP-Abnahme |
| 5 Erweiterungen noch später | Monitoringausbau, ARM64 sowie separat PVE-/PBS-Modul, Cluster und Backups nach Windows-Phase | Native ARM64-Tests; eigene spätere PVE-/Backup-/Clusterabnahmen |
| 6 Sitzungen und Betriebsreife nach MVP | Terminal, gestaffelte Agentupdates, Restoreverfahren und Hochverfügbarkeit | Menschlich genehmigte Sitzungen; Abbruch/Rechteentzug wirken; Plattformrestore praktisch getestet |
| 7 Optionale Erweiterung | Business Services und weitere Paketprovider | Zuordnung verkaufter Leistungen und zusätzliche geprüfte Installationsrezepte |
Linux-Paketrezepte werden in ihrer Linux-Phase auf Dienstkontext und wirksame Konfiguration geprüft. RustDesk-Rezepte sind aus dieser Umsetzung ausgeschlossen und bleiben spätere optionale Integration. Windows-Installer folgen erst nach Linux-MVP-Abnahme. PVE-Implementierung/-Abnahme folgt noch später nach der Windows-Phase und erzeugt keine PVE-Testumgebungspflicht für eigenständige Agenten.
Abnahmen werden der jeweiligen Ausbaustufe zugeordnet: Im MVP sind insbesondere fehlende menschliche Genehmigung, Agentabsturz nach Installerstart, verlorene Bestätigung, Fristen, Klonidentität, fremder Jobzugriff, manipulierter Loginhalt und Server-/Gatewaywiederanlauf zu prüfen. VM-Migration, VMID-Wiederverwendung, Cluster und Backupabdeckung gehören ausschließlich zur späteren PVE-Stufe; Plattformrestore und signierte Agentupdates zur Betriebsreife. Der Nachweis ist jeweils die erwartete Reaktion, nicht allein der Normalfall.
Lasttests verwenden die zuvor genannten Gerätemengen mit realistischer Metrikkardinalität, Verbindungsabbrüchen, erneut ankommenden Puffern und Massenausführung. Erst daraus werden Hardware, Grenzen und Hochverfügbarkeit abgeleitet. Testziele für Agent-CPU, RAM, Disk und Einfluss auf Hostdienste werden vor dem Pilot vereinbart und dort gemessen.
18 Startentscheidungen und konfigurierbare Betriebsdaten
Die Entwicklung kann ohne weitere Produktentscheidung beginnen. Konkrete Kundenzugangsdaten, Domains und vorhandene Infrastruktur werden später als Konfiguration eingesetzt. Fehlende Werte sperren ausschließlich die betroffene Integration und erscheinen als not_configured; sie werden nicht erfunden.
| Bereich | Verbindlicher Startentscheid |
|---|---|
| Architektur | Modularer Monolith mit getrennt startbaren Rollen API, Gateway, Worker und später Relay. Keine zusätzliche Brokerpflicht. |
| Backend und Agenten | Rust; kompatible stabile Toolchain beim Bootstrap prüfen und anschließend exakt in rust-toolchain.toml festschreiben; Cargo.lock einchecken. |
| API und UI | HTTP JSON unter /api/v1; React/TypeScript; REST-Schemas und TypeScript-Typen aus denselben Verträgen ableiten. |
| Agenttransport | Protobuf über ausgehendes WSS, zusätzlich HTTPS Long Polling; TLS 443 und mTLS nach Enrollment. |
| MCP | rmcp und ein ausdrücklich getestetes Streamable-HTTP-Profil unter /mcp; SDK- und Protokollversion festhalten. |
| Daten | PostgreSQL für Stammdaten, Jobs, Inventar und Auditmetadaten. Für den ersten technischen Abschnitt nur begrenzte Testmetriken in PostgreSQL; vor produktivem Metrikbetrieb VictoriaMetrics über den Zugriffsdienst integrieren. |
| Artefakte | Ein ArtifactStore-Vertrag; Dateisystemadapter ausschließlich im lokalen Entwicklungsprofil, S3-kompatibler Adapter für Produktion. Keine lokal gespeicherten Artefakte in der Cloud-DB als Base64. |
| Anmeldung | OIDC mit validiertem Aussteller und Audience; lokale Testidentitäten ausschließlich in einem expliziten Entwicklungsprofil. Produktion darf mit diesem Profil nicht starten. |
| Mandanten | Zwei getrennte Testkunden von Anfang an; getrennte Infrastrukturzuordnung für gemeinsam betriebene Hosts. |
| Erste Linux-Paketfamilie | APT/dpkg auf einer dokumentierten, tatsächlich verfügbaren Debian-/Ubuntu-Testmatrix. Andere Paketfamilien werden als nicht unterstützt gemeldet, bis ein Provider abgenommen ist. |
| Erste Windows-Pakete | Geprüfte MSI-/EXE-Rezepte mit festem Installationskontext. WinGet ist keine Voraussetzung. |
| Plattformreihenfolge | Alle Features zuerst auf tatsächlicher Linux-Test-VM; Linux-MVP M0–M5 x86-64, erst danach Windows x86-64 mit nativen Abnahmen; PVE noch später. Physische Hardware oder beliebige VMs ohne bekannten Hypervisor. ARM64 bleibt bis zur späteren nativen Abnahme geplant. |
| Proxmox | PVE-Modul/-Client, Cluster, Backup und deren Abnahmen ausdrücklich nach MVP; gleicher Linux-Agent mit Zusatzmodul. PBS optional in dieser späteren Stufe. Gastagenten benötigen nichts davon. |
| RustDesk | Aus dieser Umsetzung/MVP ausgeschlossen; spätere optionale Integration. Bekannte Serveradresse rust.ease-technologies.de erhalten. Edition, Ports, öffentlicher Serverschlüssel und Version unbekannt; bei späterer Integration fehlende Werte als not_configured. Jetzt keine Installation, Profile/Provisionierung oder externe Desktopabnahme. |
| Automatisierung | Darf Pläne und pending_approval-Anträge erzeugen; jeder Job benötigt menschliche WebUI-Genehmigung. Policies begrenzen/verweigern nur, keine Dauer-/Wildcardfreigabe. |
| Repository | HTTPS: https://gitea.incoso.eu/kevin_janssen/rust-discovery; SSH: ssh://git@gitea.incoso.eu:2222/kevin_janssen/rust-discovery.git. |
| Lokaler Zugangspfad | credentials/ im Projekt; durch .gitignore ausgeschlossen und niemals committen. Keine Secrets in Logs oder MCP-Kontexte übernehmen. Dateien nur als Daten behandeln, niemals mit source oder eval ausführen. Die Dokumentation des Pfads ist keine Aufforderung, Secrets auszulesen. |
| Entwicklungswerkzeuge | Installation benötigter Entwicklungs-/Testtools ist ausdrücklich erlaubt. Dies genehmigt keine Änderungen, Installationen oder Neustarts auf Kundensystemen. |
| Lokale Entwicklungsumgebung | Server in Docker auf dem PC, veröffentlichte Ports nur Loopback; PC→VM SSH-Reverse-Forward -R 127.0.0.1:18443:127.0.0.1:18443 mit -N -T, ExitOnForwardFailure und Keepalive. VM-Agent ausgehend über VM-Loopback; TLS E2E mit DNS SAN rmm-dev.internal und expliziter VM-Auflösung. SSH nur Dev/bootstrap, keine RMM-Sicherheitsabkürzung. |
| VM-Zugang und Grenzen | credentials/linux-vm.conf, .gitignore-Ausschluss, Verzeichnis 700/Datei 600; strikt Daten, kein source/eval, keine Secrets loggen/committen. Keine impliziten Ziel-Reboots, Updates oder destruktiven Tests. Geplante Befehle und reale Nachweisgates in docs/development.md. |
18.1 Zentrale Defaultwerte
Diese Werte sind Startentscheidungen für das Produkt, keine Herstellerzusagen. Sie stehen an einer zentralen Konfigurationsstelle und werden in Tests überschreibbar gehalten.
| Parameter | Default | Bedeutung |
|---|---|---|
| Heartbeat | 30 s mit Jitter | Frische Kontaktmeldung, nicht aus dem Offlinepuffer wiedergeben |
Präsenz stale |
90 s ohne frischen Kontakt | Verbindung möglicherweise gestört |
Präsenz unreachable |
180 s ohne frischen Kontakt | Gerät aktuell nicht erreichbar; kein Beweis für ausgeschaltet |
| Systemmetriken | 60 s mit Jitter | Erhebungszeit je Messung mitführen |
| Vollinventar | Bei Start und alle 24 h | Deltas ergänzen, ersetzen keinen vollständigen Abgleich |
| Enrollment-Nachweis | 15 min, einmal verwendbar | Größere Stückzahl nur ausdrücklich konfiguriert |
| Gerätezertifikat | 30 Tage, Rotation nach spätestens 20 Tagen beginnen | Geregelte Wiederaufnahme nach Ablauf |
| Startgrant | 60 s Startgültigkeit | Erst unmittelbar vor Wirkung; kein neuer Offline-Start |
| Planfrist | Explizit je Plan; UI-Vorschlag 24 h | Nach Ablauf kein automatisches Verlängern |
| Reconnect | Exponentiell 1–60 s mit Full Jitter | Nach erfolgreicher stabiler Verbindung zurücksetzen |
| Long Poll | Höchstens 25 s | Leere Antwort ist normal, kein Jobfehler |
| Steuernachricht | Höchstens 1 MiB | Vor Parserallokationen prüfen; zunächst keine Kompression |
| Inventar-/Outputstück | Höchstens 512 KiB Nutzdaten | Große Inhalte in bestätigten Stücken übertragen |
| Listenseite | 100, maximal 500 Einträge | Stabile, kontextgebundene Cursor |
| Einzelne Logabfrage | Maximal 1.000 Zeilen und 256 KiB | Das zuerst erreichte Limit gilt; Trunkierung sichtbar |
| Inline-Skript im MCP-Aufruf | Maximal 32 KiB je Variante | Größere freigegebene Skripte als Artefakt referenzieren |
| Offline-Telemetrie | Maximal 256 MiB und 72 h | Jobjournal nicht nach Telemetrie-Verdrängungsregeln löschen |
| Reboot-Rollout | Ein Ziel gleichzeitig je Abhängigkeitsgruppe | Mehr Parallelität muss im menschlich genehmigten Plan stehen und innerhalb begrenzender Policies bleiben |
| Testszenarien für Größe | Einige Dutzend, dann 1.000 und 10.000 simulierte Agenten | Lastziele, keine bereits belegte Kapazität |
RTO, RPO, Aufbewahrung, Datenschutzvorgaben und eine verbindliche Produktions-Supportmatrix werden vor dem Produktionspilot vereinbart. Sie blockieren den ersten lokalen Entwicklungsabschnitt nicht.
19 Repository, Module und Abhängigkeitsrichtung
Das Repository MUSS einen Cargo-Workspace, eine Webanwendung, versionierte Migrationen und Betriebsdokumentation enthalten. Die folgenden Pfade sind die geplante Projektstruktur, keine Behauptung bereits existierender Dateien.
| Pfad | Typ und Verantwortung |
|---|---|
crates/domain |
Bibliothek: IDs, Zustände, Fachregeln, Policyentscheidungen; keine HTTP-, SQL- oder OS-Abhängigkeit |
crates/application |
Bibliothek: Anwendungsfälle und Ports für Repository, Clock, Signer, ArtifactStore und Provider |
crates/protocol |
Bibliothek: Protobuf-Vertrag, generierte Wire-Typen, gemeinsame Fehler- und Versionsregeln |
crates/persistence |
Bibliothek: SQLx, Repositories, Transaktionen, RLS-Kontext und Outbox |
crates/server-api |
Bibliothek: HTTP DTOs, OpenAPI, Authentisierung und Controller |
crates/agent-gateway |
Bibliothek: Enrollment, mTLS-Identität, Kanalverwaltung und Übernahme von Ereignissen |
crates/worker |
Bibliothek: Scheduler, Jobzustellung, Rollouts, Nachprüfung und Hintergrundaufgaben |
crates/mcp-adapter |
Bibliothek: MCP-Werkzeuge; ruft dieselben Anwendungsfälle wie HTTP auf |
crates/relay |
Spätere Bibliothek: begrenzte Terminalstreams, Ticketprüfung und Sitzungsende |
crates/server |
Binary: Konfiguration und Start ausgewählter Serverrollen; lokal alle Rollen, produktiv trennbar |
crates/agent-core |
Bibliothek: Verbindungsaufbau, Journal, Collector-/Executor-Traits und Synchronisation |
crates/agent-windows |
Bibliothek: Windows-Dienst, Win32/CIM/Event-Log-Provider; nur für Windows einbinden |
crates/agent-linux |
Bibliothek: systemd, Linux-Inventar, Journald und Paketprovider |
crates/agent-proxmox |
Spätere Bibliothek nach MVP: PVE-/optionaler PBS-Provider auf demselben Linux-Agenten; keine Gastagentabhängigkeit |
crates/agent |
Binary: gemeinsamer Agent mit zielabhängigen Adaptern; Proxmox aktiviert ein Modul |
crates/privileged-helper |
Binary: lokaler privilegierter Executor mit eigener Nachweisprüfung |
crates/updater |
Späteres Binary: unabhängiger Agentupdatepfad mit Signaturprüfung und Recovery |
web |
React/TypeScript, generierter API-Client, Kunden-/Geräte-/Auftragsansichten |
proto |
.proto-Dateien und Kompatibilitätsfixtures; Tags niemals unbemerkt wiederverwenden |
migrations |
Geordnete SQL-Migrationen, separate Migrationsidentität |
deploy |
Lokales Compose-Profil, produktive Konfigurationsbeispiele und Dienstdefinitionen |
tests |
Integration, Protokollkonformität, Fehlerszenarien, Simulator und reale OS-Abnahmen |
docs |
Supportmatrix, ADRs, Betriebsanleitung, Sicherheitsmodell und Implementierungsstand |
Nicht jeder spätere Adapter muss sofort als leere Crate angelegt werden. Die erste Strecke erzeugt nur tatsächlich verwendete Module; die vorgegebenen Grenzen bleiben erhalten. server-api, mcp-adapter und agent-gateway dürfen keine parallelen Varianten derselben Fachlogik implementieren.
Erstes natives Linux-MVP-Buildziel ist x86_64-unknown-linux-gnu; x86_64-pc-windows-msvc folgt erst nach Linux-MVP-Abnahme. Noch später folgen aarch64-pc-windows-msvc und aarch64-unknown-linux-gnu. Abhängigkeiten und Installationspakete müssen jeweils zum Ziel passen. Der Linux-Build richtet sich nach der ältesten freigegebenen glibc-Basis. Cross-Compilation ist ein Buildnachweis; Dienststart, Installer und Betriebssystemintegration benötigen Tests auf dem tatsächlichen Ziel. Alle Features sind zuerst auf der tatsächlichen Linux-Test-VM nachzuweisen.
docs/platform-support.md führt je Kombination Betriebssystemversion, Architektur, Buildstatus, native Abnahme, verfügbare Capabilities, PVE/PBS-Kompatibilität und gegebenenfalls RustDesk-Kompatibilität. „Geplant“, „Build erfolgreich“ und „freigegeben“ sind getrennte Angaben.
20 Normative Datenverträge
20.1 IDs, Zeit und Generationen
Fach-IDs werden als zufällige UUIDs erzeugt und in JSON als Strings ausgegeben. Externe Providerkennungen bleiben zusätzliche Attribute. Zeitpunkte werden intern in UTC gespeichert; JSON verwendet RFC-3339-Zeitpunkte mit Zeitzone. Standorte besitzen eine IANA-Zeitzone für Wartungsfenster und Darstellung.
| Feld | Bedeutung und Änderung |
|---|---|
tenant_id |
Kunde beziehungsweise Infrastrukturmandant; aus authentisierter Zuordnung ableiten |
asset_id |
Verwaltete Ressource; weder Hostname noch MAC-Adresse |
agent_id |
Konkrete Agentinstallation; Zertifikatsrotation allein ändert sie nicht |
enrollment_generation |
Geräteidentitätsgeneration; wird bei autorisierter Identitätswiederherstellung erhöht |
assignment_version |
Version der Verwaltungs-/Kundenzuordnung; relevante Umbindung invalidiert alte Startgrants |
connection_generation |
Serverseitiges Fencing des aktiven Transportkanals; Reconnect oder Transportwechsel erhöht den Wert |
boot_id |
Identität eines Betriebssystemstarts, nicht eines Agentprozessstarts |
collector_generation |
Fencing einer gewählten clusterweiten Erhebungsinstanz |
plan_id |
Genau ein gespeicherter, unveränderlicher Plan für genau einen Mandanten |
operation_id |
Stabile Referenz auf einen eingereichten Genehmigungsantrag und seinen späteren Ausführungslauf mit fester Zielmenge |
job_id |
Genau ein fester Einzeljob für ein Gerät und eine Aktion innerhalb eines Laufs; mehrere feste Jobs je Gerät möglich |
attempt_id |
Ausdrücklich zugelassener Ausführungsversuch; erneute Zustellung erzeugt keinen neuen Versuch |
message_id |
Identität einer Nachricht; kein Ersatz für Job oder Ausführungsversuch |
Ist eine belastbare Bootkennung auf einer Plattform nicht verfügbar, wird diese Capability als eingeschränkt gemeldet. Ein Agentprozessneustart darf nicht als Nachweis eines Rechnerneustarts gelten.
20.2 PostgreSQL-Kernschema
Die Migrationen müssen die folgenden fachlichen Verträge in der jeweils gelieferten Ausbaustufe abbilden. Provider-/Virtualisierungs-/Backupstrukturen sind erst für M6b erforderlich und dürfen weder Gastagenten noch MVP blockieren. Zusätzliche technische Spalten und normalisierte Tabellen sind erlaubt, eine stille Abschwächung der Invarianten nicht.
| Tabelle/Gruppe | Kernfelder | Invarianten |
|---|---|---|
tenants, sites |
ID, Name, Status, Zeitzone | Deaktivierung beendet neue Änderungen, löscht nicht stillschweigend Historie |
principals, memberships |
Externe Identität (issuer, subject), Typ, tenant, Rolle, Zielbereich |
E-Mail ist kein stabiler Identitätsschlüssel; keine globale Kundenzugehörigkeit durch Rolle |
assets |
tenant, asset, Typ, Rolle, site, Tags, Lebenszyklus | Eindeutige (tenant_id, asset_id); Typ und Rolle getrennt |
agent_installations |
tenant, agent, asset, Schlüssel, Generation, Zuordnungsversion, Version, Capabilities, Widerruf | Neue Installation übernimmt keine alten Jobs allein wegen gleicher Hardwaremerkmale |
inventory_snapshots, observations |
Quelle, Generation, Erhebungs-/Empfangszeit, Schema, Daten, Vollständigkeit | Aktuelle Projektion bleibt von historischer Beobachtung unterscheidbar |
service_expectations, check_results, incidents |
Sollregel, Quelle, Messzustand, Zeit, Eskalation | Unterdrückte Meldung überschreibt nicht den ursprünglichen Messzustand |
provider_connections, provider_resources |
Providerinstanz, externe Identität, Lebenszyklus, Scope, Zuordnung | VMID allein ist nicht eindeutig |
backup_policies, backup_evidence |
Regel, Fälligkeit, Versuch, Gast, Abdeckung, Snapshot, Verify, Restore | Ein Gesamtjob ersetzt keinen Einzelnachweis |
package_recipes, artifacts; später optional rustdesk_profiles |
tenant/sichtbarer Katalog, unveränderliche Version, Hash, Plattform, Secret-Referenzen | Freigegebene Version wird nie in-place verändert; RustDesk-Profile nicht Teil dieser Umsetzung/MVP |
operation_plans |
tenant, Planpayload-Bytes, Hash, Ziele, Ablauf, Urheber | Inhalt unveränderlich nach Speicherung |
approval_requests |
operation_id, tenant, Planhash, feste Jobdefinitionen/Versuche, Urheber, Frist, Status, Idempotenznachweis | pending_approval erzeugt keine Ausführungsjobs/Outbox; abgelehnt/abgelaufen/widerrufen nicht ausführbar |
authorizations |
Planhash, menschlicher Freigeber und interaktiver WebUI-Kontext, Gültigkeit, begrenzende Policyversion | Nur explizite menschliche Genehmigung; Bindung an feste Ziele, Inhalte und Versuche |
operations, jobs, job_attempts |
Genehmigter Lauf, Gerät, Zustand, Fristen, Sperre, Versuch, Ergebnis | Anlage erst nach menschlicher Genehmigung; gleiche Zustellung startet keinen zweiten Versuch |
execution_permits |
Grant-ID, Job-/Payloadhash, Zielbindung, Gültigkeit, Signierschlüssel | Kurzlebig und nur für den angegebenen Start verwendbar |
outbox, message_receipts |
Ereignis-ID, tenant, Ziel, Payload, ACK, Zustelllease | Jobanlage und Outbox atomar; ACK erst nach der definierten dauerhaften Übernahme |
audit_events |
Principal, Kontext, Plan, Entscheidung, Wirkung, Ergebnis | Auditmetadaten ohne Secrets; kritische Kopien mit getrennten Löschrechten |
remote_sessions |
Principal, Ziel, Rechte, Ablauf, Status, Aufnahmeverweis | Keine Wiederaufnahme ohne erneute Sitzungsauthorisierung |
Normale kundenbezogene Fremdschlüssel enthalten tenant_id. Querverbindungen zwischen Infrastrukturmandant und Kundengast liegen in ausdrücklich separaten Mapping-/Projektionsstrukturen mit einer eng begrenzten Dienstidentität. Sie dürfen nicht durch einen allgemeinen RLS-Bypass aller Worker realisiert werden.
Der Scheduler liest ausschließlich das berechtigte Mandantenregister und bearbeitet jeden Kunden in einer eigenen Transaktion mit explizitem Kontext. Request- oder Tenant-Kontext wird mit transaktionslokalen Einstellungen gesetzt; nach Fehlern oder Rückgabe einer Poolverbindung darf er nicht fortbestehen. Anwendung und Worker besitzen keine Tabellen und haben keine Superuser-/BYPASSRLS-Rechte.
20.3 Beobachtungen und Status
Jede Datengruppe führt mindestens source_id, observed_at, received_at, quality, completeness und bei Bedarf error_code. quality unterscheidet valid, unknown, unsupported, permission_denied und error. Datenalter ist ein zusätzliches berechnetes Merkmal und kein Ersatz für diese Zustände.
completeness unterscheidet complete, partial und unknown; ein begrenztes Ergebnis erhält außerdem truncated=true. Das ist besonders wichtig für Softwareinventar, Logs und Proxmox-Discovery. Ein unvollständiger Snapshot DARF NICHT als Beleg für die Löschung fehlender Einträge verwendet werden.
Präsenz, Datenfrische und fachliche Gesundheit sind getrennte Felder. Der Kontaktstatus lautet online, stale, unreachable, never_seen oder revoked; ein Wartungsfenster ist ein eigenes Merkmal. Der Status einer Agentverbindung sagt nichts Endgültiges über den Power-State einer VM aus. Altes Telemetriereplay aktualisiert weder last_contact_at noch eine aktuelle Gesundheit zu grün.
21 Normativer Agentprotokoll-Vertrag
21.1 Endpunkte und Transport
| Endpunkt | Vertrag |
|---|---|
POST /agent/v1/enroll |
Serverauthentifiziertes HTTPS; Enrollment-Nachweis, CSR/öffentlicher Schlüssel und Metadaten; atomarer Verbrauch des Nachweises |
WSS /agent/v1/connect |
mTLS; binäre Protobuf-Nachrichten; aktive Verbindungsgeneration durch Server vergeben |
POST /agent/v1/messages |
mTLS; derselbe logische Nachrichtenvertrag als Protobuf-Batch; für HTTPS-Modus und Wiederholung |
POST /agent/v1/poll |
mTLS; Long Poll mit Cursor/Generation und begrenzter Antwortzeit; leeres Ergebnis ist erlaubt |
POST /agent/v1/certificates/renew |
mTLS mit noch gültiger Geräteidentität; neuer Schlüssel/CSR und gültige Zuordnung prüfen |
GET /agent/v1/artifacts/{artifact_id} |
mTLS und Zielberechtigung; gestückelter Bezug, Hashkontrolle; kein freier Objektpfad |
WSS /agent/v1/sessions/{session_id} |
Späterer, vom Agenten eröffneter Terminalstream; mTLS plus gebundenes Sitzungsticket |
Kontrollnachrichten verwenden application/x-protobuf über HTTP. HTTP-Batching hat ein eigenes versioniertes MessageBatch-Schema; das Gesamtlimit wird ebenfalls geprüft. Im WebSocket entspricht ein vollständiger binärer Message genau einem Envelope; Netzwerkfragmentierung ändert diesen logischen Vertrag nicht. Der Receiver prüft Limits während der Rekonstruktion, nicht erst nach unbegrenzter Allokation.
WSS und Long Polling sind funktional für Inventar und Jobs gleichwertig. Pro Agent darf nur eine Verbindungsgeneration neue Arbeit erhalten. Ein alter Poll oder Stream bekommt keine neuen Aufträge. Nachgewiesene verspätete Ergebnisse können weiterhin anhand von Agent, Job und Versuch verarbeitet werden; sie werden nicht allein wegen eines neuen Transportkanals verworfen.
TLS-Clientidentität muss bis zur fachlichen Geräteprüfung verlässlich erhalten bleiben. Wenn ein Reverse Proxy mTLS terminiert, ist dessen Verbindung zum Gateway ebenfalls authentisiert; vom Internet eingesandte Identitätsheader werden verworfen. Der Proxy ist dann Teil der Vertrauensgrenze. Ein ungeprüfter Header ist kein Ersatz für mTLS.
21.2 Umschlag
Envelope enthält protocol_major, protocol_minor, message_id, agent_id, enrollment_generation, connection_generation, boot_id, sequence, observed_at und ein typisiertes Protobuf-oneof payload. Während des ersten Hello kann die neue Verbindungsgeneration noch fehlen; der Server vergibt sie mit ServerHello. tenant_id wird serverseitig aus der registrierten Identität abgeleitet, nicht aus einer beliebigen Agentbehauptung.
sequence ist innerhalb einer Agentinstallation monoton und wird für dauerhafte Ereignisse gemeinsam mit dem Journal fortgeschrieben. Lücken durch flüchtige Nachrichten sind zulässig. ACKs benennen konkrete message_id-Werte; ein pauschales „alles bis Sequenz N“ darf nur für eine tatsächlich lückenlos bestätigte durable Teilfolge verwendet werden. Ein Snapshot-Restore des Journals erfordert den Wiederabgleich aus Abschnitt 22.
21.3 Nachrichtentypen
| Typ und Richtung | Mindestinhalt | Dauerhaftigkeit und Antwort |
|---|---|---|
ClientHello, Agent → Server |
Unterstützte Protokollversionen, Agentversion, OS/Architektur, Capabilities, Journal-/Syncstand | Frisch je Verbindung; ServerHello oder erklärbarer Fehler |
ServerHello, Server → Agent |
Gewählte Version, Verbindungsgeneration, Serverzeit, Limits, Konfigurationsversion | Frisch; mutierende Starts erst nach erfolgreichem Wiederabgleich |
Heartbeat, Agent → Server |
Frische Instanzkennung, Boot-ID, Laufzeit, begrenzter Agentzustand | Flüchtig; niemals als Offlinehistorie wiedergeben |
InventorySnapshot, Agent → Server |
Snapshot-ID, Scope, Schema, Chunkindex/-anzahl, Erhebungszeit, Vollständigkeit, Gesamthash | Stücke dauerhaft übernehmen; aktuelle Projektion erst nach vollständiger validierter Assemblierung aktualisieren |
InventoryDelta, Agent → Server |
Basis-Snapshot, neue Generation, Änderungen | Durable ACK; fehlende Basis → SnapshotRequired |
SnapshotRequired, Server → Agent |
Betroffener Scope und fehlende/ungültige Basisgeneration | Vollständigen neuen Snapshot anfordern; ändert selbst keine Inventarprojektion |
MetricsBatch, Agent → Server |
Quelle, Messnamen, Werte, Einheiten, Erhebungszeiten | Nach definierter dauerhafter Aufnahme in begrenzten Ingestpfad bestätigen; spätere Lücken sichtbar |
JobOffer, Server → Agent |
Genehmigter Job/Versuch, Genehmigungsreferenz, Plan-/Jobpayloadhash, Inhalte/Artefaktreferenzen, Fristen | Erst nach menschlicher WebUI-Genehmigung zustellen; Agent nach lokalem Journaleintrag mit JobAccepted bestätigen |
JobAccepted, Agent → Server |
Job, Versuch, Journalnachweis | Dauerhaft; ist keine Ausführungserlaubnis und kein Erfolg |
ExecutionPermitRequest, Agent → Server |
Job, Versuch, aktuelle Identitäts-/Zuordnungsgeneration, Payloadhash | Frisch unmittelbar vor dem Start; keine Offlinepufferung zur späteren Freigabe |
ExecutionPermit, Server → Agent |
Signierter, kurzlebiger Startnachweis oder strukturierte Verweigerung | Agent/Helper prüfen Inhalt, Frist und einmaligen Verbrauch |
JobStateChanged, Agent → Server |
Job, Versuch, monotone Zustandsrevision, lokaler Zustand und Zeitpunkt | Verpflichtendes dauerhaftes Zustandsereignis; bis ACK wiederholen, bei Wiederholung deduplizieren |
JobProgress, Agent → Server |
Job, Versuch, Stufe, begrenzte Zähler | Optional zusammenfassbar; Fortschritt ist kein terminales Ergebnis |
JobResult, Agent → Server |
Job, Versuch, Ausgang, Nachprüfungen, Zeitpunkte, Outputreferenzen, Neustartbedarf | Dauerhaft bis ACK wiederholen; deduplizieren |
CancelRequest, Server → Agent |
Job, Versuch, Grund und Entscheidungskontext | Durable; Ergebnis benennt tatsächlichen Abbruch oder fehlende Abbruchmöglichkeit |
ConfigUpdate, Server → Agent |
Version, vollständige validierte Konfiguration oder Basisdelta | Atomar übernehmen; letzte gültige Konfiguration erhalten |
SyncRequest / SyncResponse, beide Richtungen |
Journalzusammenfassung, bekannte Versuche, offene Zustände | Nach Restore/Reconnect Abgleich; keine neue Ausführung durch bloße Synchronisation |
Ack, beide Richtungen |
Konkrete Nachricht-IDs und Übernahmezustand | Kein ACK-von-ACK; Bedeutung ist ausdrücklich Empfang/Übernahme, nicht fachlicher Erfolg |
ProtocolError, beide Richtungen |
Code, betroffene Nachricht, Wiederholbarkeit | Keine Secrets oder ungefilterten Backtraces |
Ein dauerhafter ACK bestätigt entweder die endgültige Speicherung oder eine zuvor klar definierte durable Ingest-Stufe. Geplante Telemetrieverwerfung durch Quoten erzeugt einen expliziten Drop-/Gap-Nachweis; sie darf nicht als dauerhafte Speicherung behauptet werden. Jobergebnisse werden niemals nach Telemetrie-Verdrängungsregeln verworfen.
Die Erteilung eines Startgrants ist kein bestätigter Prozessstart. Erst ein passender dauerhafter Zustands-, Ergebnis- oder Syncnachweis belegt die lokale Ausführung. Zustandsrevisionen verhindern eine Rücksetzung durch verspätete Ereignisse. Ein früher eintreffendes gültiges Endergebnis darf fehlende Zwischenereignisse nachvollziehbar ergänzen; es wird nicht allein wegen einer verlorenen Startmeldung verworfen.
Neue Protobuf-Felder werden additiv eingeführt. Entfernte Tags und Enumwerte werden reserviert. Eine unbekannte Hauptversion führt zu UNSUPPORTED_PROTOCOL; unbekannte Aktionscapabilities zu UNSUPPORTED_CAPABILITY. Der Agent darf niemals stillschweigend einen anderen Interpreter oder Paketprovider wählen.
22 Pläne, Ausführungserlaubnis und Jobzustände
22.1 Unveränderlicher Plan und Transaktionsgrenzen
Ein Plan umfasst genau einen Mandanten und ein transparentes Paket fester Einzeljobs auf festen Zielgeräten. Im einfachen Fall ist dies eine Aktion je Ziel; verschiedene Aktionen oder feste Folgejobs sind zulässig, wenn jeder Job, Versuch, seine Abhängigkeiten und Parameter vor Genehmigung einzeln sichtbar und gebunden sind. Plattformvarianten werden vor Speicherung eindeutig je Job aufgelöst. Sämtliche Jobpayloads werden vorher erzeugt; der Plan enthält je Job den job_payload_hash und die feste Versuchsidentität. Freigabe und Startgrant dürfen ausschließlich diese Bindungen verwenden. Jede spätere Änderung erzeugt einen neuen Plan. Beispiel: Ein Skriptplan bindet jedes Ziel an genau eine PowerShell- oder POSIX-Shell-Variante. Eine unbestimmte Zahl künftiger Retries ist kein fester Einzeljob.
- Planen: Rechte und begrenzende Policies prüfen, dynamische Auswahl auflösen, Fähigkeiten prüfen, Parameter/Artefaktversionen normalisieren, feste Einzeljobpayloads einschließlich Versuch und Nachbedingungen erzeugen und Plan speichern. Noch keine Ausführungsjobs.
- Beantragen (
operations.submit): Aktuelle Rechte und Planfrist prüfen; atomar einen persistentenapproval_requestmit stabileroperation_id, Planhash, Idempotenznachweis undpending_approvalspeichern. Keine Ausführungsjobs, ausführbare Outbox, JobOffers oder Startgrants. Jeder Submit ist ein Antrag, auch aus der UI; kein alternativer direkter Ausführungspfad. Derselbe Plan wird nur einmal beantragt; Wiederholung liefert denselben Antrag samt aktuellem Status. - Menschlich genehmigen und einreihen: Ausschließlich ein berechtigter Mensch im interaktiven WebUI-Kontext genehmigt den unveränderlichen Plan nach Anzeige aller festen Einzeljobs, Zielanzahl, Inhalte/Hashes, Fristen und Auswirkungen. Rechte, Policygrenzen, Zuordnung und Planfrist erneut prüfen. In einer Transaktion Genehmigung, Ausführungslauf unter derselben
operation_id, feste Jobs/Versuche und Outbox erzeugen und den Antrag alsapprovedmarkieren. Fehler rollt alles zurück. Keine dauerhafte oder Wildcardfreigabe; MCP-/Automatisierungstokens werden selbst mit Approver-Rolle abgewiesen. Ablehnen ist ohne Jobanlage möglich. - Zustellen: Nur genehmigte Jobs lease-basiert koordinieren. Der Agent übernimmt dauerhaft ins Journal und bestätigt. Eine verlorene Lease oder erneute Zustellung erzeugt weder einen neuen Versuch noch eine neue Genehmigung.
- Starten: Aktuellen Startgrant mit Referenz auf die weiterhin gültige menschliche Genehmigung beziehen, lokal prüfen und Verbrauch journalisieren; erst dann ausführen.
- Nachprüfen: Im genehmigten Job gebundene Nachbedingungen erheben und Ergebnisse dauerhaft übermitteln. Separate Diagnose-, Reboot- oder Retryjobs benötigen eigene feste, menschlich genehmigte Pläne; bereits im transparenten Sammelpaket enthaltene feste Folgejobs dürfen dessen Genehmigung nutzen. Neue Wirkung/neuer Versuch ist nie durch bloße Wiederholung der Zustellung erlaubt.
Antragszustände sind pending_approval, approved, rejected, expired und revoked, ausgegeben als approval_state. Aus pending_approval sind diese vier Übergänge möglich; approved kann bei Genehmigungsentzug nach revoked wechseln. rejected, expired und revoked werden nicht reaktiviert. Genehmigungsentzug sperrt neue Starts; laufende Wirkungen folgen den sicheren Abbruchregeln. Der Ausführungslauf und seine Aggregation (execution_state) bleiben getrennt erhalten. jobs.get(operation_id) zeigt den Antrag auch ohne Jobs (job_count=0, planned_job_count separat, execution_state=null). Eine neue/verlängerte Frist oder geänderte Jobdefinition erfordert neuen Plan und Genehmigung. Ausführungseinreihung findet ausschließlich in Schritt 3 statt; parallele Genehmigungsklicks werden transaktional dedupliziert und erzeugen nur einen Lauf.
Idempotenzschlüssel werden an Principal, Tenant, Operationstyp und Requesthash gebunden. Gleicher Schlüssel mit anderem Inhalt ergibt IDEMPOTENCY_CONFLICT. Ein absichtlich neuer Lauf/Versuch nach unbekanntem Ausgang benötigt zuerst Abgleich und einen neuen explizit menschlich genehmigten Plan, keinen stillschweigend neuen Schlüssel.
22.2 Exakte Bytes, Hashes und Signaturen
Der Server normalisiert den Plan über genau einen versionierten Codec. Er serialisiert den Plan einmal in eine definierte Bytefolge, speichert diese unveränderlich und berechnet plan_hash = SHA-256(plan_payload_bytes). Keine Komponente berechnet den Hash durch beliebiges Neuformatieren der JSON-Ansicht. Der Codec legt Feldreihenfolge, fehlende Werte, Listenreihenfolge, Zahlen und Zeitdarstellung fest und erhält Golden-Files für Interoperabilität.
Für jeden festen Einzeljob wird ein unveränderlicher job_payload mit Ziel, festem Versuch, Interpreter/Provider, Argumenten, Ausführungsidentität, Limits, Artefakthashes, Secret-Versionreferenzen und Nachbedingungen erzeugt. Job-/Versuchs-IDs dürfen dafür im Plan reserviert werden, ohne bereits Ausführungsjobs oder eine Queue anzulegen. Der Startgrant bindet dessen job_payload_hash. Skriptartefakte werden über die exakten auszuführenden Bytes gehasht; BOM, Encoding und Zeilenenden werden nach Freigabe nicht mehr verändert.
Für Startnachweise wird ein versioniertes signiertes Envelope mit einem festgelegten Standardalgorithmus und geprüfter Bibliothek verwendet; als Ausgangsprofil ist Ed25519 vorgesehen. Es gibt keine vom Aufrufer frei wählbare Algorithmusverhandlung. Signiert werden die gespeicherten exakten Grantpayload-Bytes einschließlich Domain-/Typkennung und Schemaversion. Schlüssel-ID und bekannte Vertrauenskette erlauben Rotation; Transport-, Update- und Auftragschlüssel bleiben getrennt.
22.3 Startgrant und Offlineverhalten
Ein ExecutionPermit MUSS mindestens folgende Bindungen enthalten: grant_id, authorization_id der menschlichen Genehmigung, tenant_id, asset_id, agent_id, enrollment_generation, assignment_version, job_id, attempt_id, plan_hash, job_payload_hash, action, execution_identity, not_before, start_before, max_runtime_seconds, key_id und Schemaversion. Der Helper erhält genug Payload, um Ziel, Aktion, konkrete Parameter und Hash selbst zu prüfen.
Kein Ausführungsjob, auch kein Diagnosejob, beginnt ohne aktuellen Kontakt zur Zentrale und gültige menschliche WebUI-Genehmigung. Der Server prüft vor der Signatur Genehmigungsbindung an Plan, feste Jobs und Versuch, heutige Zuordnung, Benutzer-/Automatisierungsrechte, begrenzende Policy, Stopps, Planfrist, Wartungsfenster, Ressourcen- und Rolloutgrenzen. Lange wartende Jobs erhalten den Startgrant erst dann. Nur technische Neuausstellung für denselben nachweislich ungestarteten Versuch braucht keine neue Genehmigung; sie darf keine neue Wirkung oder neuen Versuch ermöglichen.
Ein einmal verwendeter Grant darf nach Prozessneustart nicht erneut verwendet werden. Die Einmaligkeit gilt zusätzlich für den Ausführungsversuch (agent_id, enrollment_generation, job_id, attempt_id). Der Server speichert die Startreservierung und den ausgegebenen Grant dauerhaft vor dessen Übermittlung. Eine neue Grant-ID setzt einen gestarteten oder möglicherweise gestarteten Versuch nicht zurück. Ist ein vorheriger Start nicht zuverlässig ausgeschlossen, folgt zuerst Abgleich und gegebenenfalls unknown; es wird kein weiterer startberechtigender Grant ausgegeben. Nur nach belegtem Nichtstart kann ein abgelaufenes technisches Ticket für denselben noch ungestarteten Versuch ersetzt werden.
Der Verbrauch und der Versuchszustand liegen zusätzlich dauerhaft im lokalen Journal. Bei unklarer Uhrabweichung wird die Ausführung mit CLOCK_UNTRUSTED zurückgestellt; Telemetrie darf weiterlaufen. Ein bloß vom Agenten behaupteter neuer Zeitpunkt verlängert keinen Grant.
Eine bereits begonnene Installation darf bei Verbindungsverlust gemäß Providerregeln weiterlaufen. Der Agent puffert Ergebnisse. Ein abgelaufener Startgrant beendet eine laufende Aktion nicht rückwirkend; dafür gelten Laufzeit- und Abbruchregeln. Offline-Widerruf wirkt spätestens vor dem nächsten online autorisierten Start; bereits ausgeführte Änderungen können nicht rückwirkend ungeschehen gemacht werden.
22.4 Normative Jobzustände
| Zustand | Bedeutung | Zulässige nächste Zustände |
|---|---|---|
queued |
Dauerhafter Job, noch nicht lokal angenommen | accepted, cancelled, expired, failed bei eindeutigem Vorprüffehler |
accepted |
Im Agentjournal; Beginn noch nicht bestätigt | running, unknown bei möglichem Start; cancelled, expired oder failed nur bei nachgewiesenem Nichtstart beziehungsweise bestätigtem Abbruch |
running |
Lokale Ausführung hat begonnen | verifying, awaiting_reboot, failed, cancelled bei bestätigtem Abbruch, unknown |
verifying |
Nachbedingungen werden geprüft | succeeded, failed, awaiting_reboot, unknown |
awaiting_reboot |
Für Abschluss benötigter autorisierter Reboot beziehungsweise Wiederanmeldung ausstehend | verifying, unknown, failed bei eindeutigem Nachweis |
succeeded |
Definierte Nachbedingungen bestätigt | Terminal |
failed |
Bekannter Fehlschlag mit strukturiertem Grund | Terminal |
cancelled |
Vor Start gestrichen oder Abbruch tatsächlich bestätigt | Terminal; bereits eingetretene Teilwirkungen gesondert ausweisen |
expired |
Startfrist ohne begonnene Wirkung abgelaufen | Terminal |
unknown |
Wirkung oder Ergebnis nicht zuverlässig bestimmbar | Nur durch dokumentierten Abgleich nach verifying, succeeded, failed oder tatsächlich bestätigtes cancelled |
cancel_requested ist ein separates Feld, kein Beleg für Beendigung. pending_reason erklärt Wartezeiten wie device_offline, maintenance_window, resource_locked, rollout_paused oder authorization_revoked. pending_approval gehört ausschließlich zum Antrag, niemals zu einem bereits vor Genehmigung eingereihten Job. Zustellleases sind technische Metadaten, keine fachlichen Zustände.
Die Tabelle beschreibt den fachlichen Verlauf, nicht eine Pflicht zur verlustfreien Reihenfolge aller Netzwerknachrichten. Dauerhafte Ergebnis- oder Syncnachweise dürfen fehlende Zwischenzustände nachvollziehbar ergänzen. Bei einem zentral noch als queued geführten Job wird zuerst der nachgewiesene lokale Annahme-/Startverlauf rekonstruiert. Wurde ein Startgrant ausgegeben und ist dessen Nichtverbrauch unklar, darf der Job nicht allein wegen fehlender Startmeldung als expired oder cancelled abgeschlossen werden.
reboot_required ist ein eigenständiges Ergebnisfeld. Kann eine Installation vollständig nachgeprüft werden, darf sie mit succeeded und reboot_required=true enden. Verlangt ihre Nachbedingung einen Neustart, bleibt sie awaiting_reboot; der Neustart ist ein fester, explizit menschlich genehmigter Folgejob, im ursprünglichen transparenten Sammelpaket oder in einem neuen Plan. Kein Installer darf durch einen unbeachteten Standardparameter ungeplant neu starten.
Timeout nach möglicher Wirkung bedeutet unknown, sofern kein eindeutiger Fehlschlagnachweis vorliegt. Ein Reboot ist erst nach authentisierter Wiederanmeldung mit plausibel neuer Boot-ID und erfolgreicher Nachprüfung abgeschlossen. Ausbleibende Wiederanmeldung ist kein bestätigter Erfolg.
22.5 Abgleich, Sperren und Restore
Vor Wiederholung wird zwischen erneuter Zustellung desselben genehmigten Versuchs (keine neue Genehmigung, keine zweite Wirkung) und einem neuen Ausführungsversuch (neuer menschlich genehmigter Plan) unterschieden. Gebundene Nachprüfungen von ensure_package/ensure_rustdesk sind Teil des genehmigten Jobs; neue Diagnosejobs zum Istzustand brauchen eigene Genehmigung. Kein Job wird nach unklarer Wirkung blind wiederholt, auch kein idempotent wirkender Provider ohne Genehmigung eines neuen Versuchs.
Paketmanager, Agentupdate und Reboot erhalten gerätebezogene Konfliktsperren. Serverseitige Sperre allein reicht bei einer Netzpartition nicht aus; der lokale Executor hält dieselbe Ressourcensperre während der Wirkung. Bereits laufende, fremd gestartete Paketmanager werden respektiert.
Nach Snapshot-Restore, Journalinkonsistenz oder zentralem Restore sind neue Änderungen gesperrt, bis offene Versuche und Generationen abgeglichen sind. Zurückgerollte Journale dürfen keine historische Aktion allein wegen fehlenden lokalen Eintrags erneut starten. Serverledger, Gerätegeneration und aktuelle Startprüfung bilden gemeinsam die Wiederholungssperre.
Ergebnisse und deduplizierende Tombstones werden nur nach einer dokumentierten, beidseitigen Kompaktierungsregel entfernt. Jobjournalplatzmangel sperrt neue Änderungen und meldet einen Fehler; er löscht keine unbestätigten Ergebnisse zugunsten neuer Telemetrie.
23 HTTP API, MCP und Berechtigungen
23.1 Gemeinsamer Vertrag
HTTP und MCP verwenden dieselben DTOs, Validierungsregeln und Anwendungsfälle. OpenAPI- und MCP-JSON-Schemas werden aus gemeinsamen Typen erzeugt oder durch Konformitätstests gegeneinander geprüft. Jeder neue Toolpfad muss denselben Mandantentest bestehen wie der entsprechende HTTP-Pfad.
Listen liefern items, next_cursor, completeness, truncated und as_of; fachliche Beobachtungen führen zusätzlich ihre eigene observed_at. Cursor werden an Tenant, Filter und Sortierung gebunden und dürfen keine unberechtigten Daten offenlegen. Fehler verwenden code, message, retryable, correlation_id und unkritische strukturierte details.
Fremde Objekt-IDs erhalten dieselbe äußere Antwort wie nicht vorhandene Objekte. Authentisierungsausfälle bleiben davon unterscheidbar. Relevante Fehlercodes sind NOT_FOUND, UNAUTHENTICATED, FORBIDDEN, VALIDATION_ERROR, AMBIGUOUS_TARGET, UNSUPPORTED_CAPABILITY, AUTHORIZATION_REQUIRED, PLAN_EXPIRED, IDEMPOTENCY_CONFLICT, DEVICE_OFFLINE, POLICY_DENIED, QUOTA_EXCEEDED, DEPENDENCY_UNAVAILABLE und RESULT_UNKNOWN.
23.2 Rollen und Sonderrechte
| Rolle | Defaultrechte innerhalb ihrer ausdrücklich zugewiesenen Kunden/Zielgruppen |
|---|---|
| Viewer | Inventar und Monitoring lesen |
| Operator | Zusätzlich berechtigte Logs lesen, Pläne erstellen/einreichen und berechtigte Aufträge abbrechen |
| Approver | Als Mensch ausschließlich im interaktiven WebUI-Kontext konkrete Pläne im eigenen Bereich genehmigen; MCP-/Automatisierungstokens niemals freigabefähig |
| TenantAdmin | Kundenmitgliedschaften, eigene Richtlinien und freigegebene Profile verwalten |
| PlatformOperator | Explizite Plattform- und Infrastrukturaufgaben; keine automatische Einsicht in jeden Kunden |
Zusatzrechte werden getrennt vergeben, insbesondere scripts:execute, sessions:open, sessions:privileged, logs:read_sensitive, hypervisor:operate und data:send_to_external_ai. Eine Operatorrolle allein autorisiert keine beliebige SYSTEM-/Root-Skriptausführung.
Eine TenantAdmin-Rolle darf nur innerhalb eines vom Plattformbetrieb eingeräumten delegierbaren Bereichs neue Rechte vergeben. Policyänderungen werden auditiert. Automatisierungsprincipals sind eigenständige Identitäten mit begrenztem Scope; das Audit bewahrt gegebenenfalls zusätzlich den menschlichen Auftraggeber.
23.3 Endpunkte und Werkzeuge
| HTTP-Fachendpunkt | MCP-Werkzeug | Wichtige Ein-/Ausgabe |
|---|---|---|
GET /api/v1/tenants |
tenants.list |
Name/Filter, Cursor → berechtigte eindeutige Kunden-IDs |
GET /api/v1/tenants/{tenant_id}/devices |
inventory.list_devices |
Rolle, Tags, Plattform, Präsenz → Geräte mit Aktualität |
GET /api/v1/tenants/{tenant_id}/devices/{asset_id} |
inventory.get_device |
Asset → Inventar, Quellen, Capabilities, Alter |
GET /api/v1/tenants/{tenant_id}/health |
monitoring.get_health |
Zielbereich, Zeitraum → Vorfälle und begrenzte Metriken |
POST /api/v1/tenants/{tenant_id}/log-queries |
logs.query |
Gespeicherte Daten → ready; Live-Erhebung → fester Diagnoseplan und persistenter Antrag pending_approval mit operation_id, noch kein Job |
POST /api/v1/tenants/{tenant_id}/operation-plans |
operations.plan |
Aktion, Zielauswahl, Varianten, Fristen → Plan, Hash, feste Ziele, erwartete Auswirkungen, Autorisierungsbedarf |
POST /api/v1/tenants/{tenant_id}/operation-plans/{plan_id}/submit |
operations.submit |
Plan-ID, Idempotenzschlüssel → operation_id, pending_approval, planned_job_count, job_count=0; nur persistenter Antrag, keine ausführbare Outbox |
GET /api/v1/tenants/{tenant_id}/operations/{operation_id} |
jobs.get mit operation_id |
Antragsstatus einschließlich pending_approval, Planhash und geplante Jobs; nach Genehmigung zusätzlich Ausführungsaggregation, Zähler und paginierte Jobs |
GET /api/v1/tenants/{tenant_id}/jobs/{job_id} |
jobs.get mit job_id |
Einzelzustand, Versuch, Nachprüfungen, begrenzte Ausgaben |
POST /api/v1/tenants/{tenant_id}/jobs/{job_id}/cancel |
jobs.cancel |
Abbruchgrund → tatsächlicher Zustand und cancel_requested |
POST /api/v1/tenants/{tenant_id}/sessions |
sessions.request |
Asset, Stufe, Dauer, Zweck → Entscheidung/Sitzungsreferenz |
POST /api/v1/tenants/{tenant_id}/operation-plans/{plan_id}/authorizations |
Kein MCP-Werkzeug | Nur interaktiver menschlicher WebUI-Kontext; Antrag/Planhash, Entscheidung genehmigen/ablehnen; bei Genehmigung atomar Nachweis, Ausführung, feste Jobs und Outbox |
POST /api/v1/tenants/{tenant_id}/artifacts |
Kein allgemeiner Secret-/Dateiupload durch das Modell | Berechtigter Artefaktimport mit Limits, Hash und Herkunft |
Für jobs.get ist genau eine der beiden IDs zulässig. Der Kunde muss im Request explizit gewählt und im Authentisierungskontext erlaubt sein. Der Name „Kunde X“ wird zuerst eindeutig aufgelöst; gleiche Anzeigenamen dürfen keinen zufälligen Treffer für Änderungen auswählen.
Der Endpunkt für menschliche Freigaben akzeptiert ausschließlich einen dafür vorgesehenen authentisierten interaktiven WebUI-Benutzerkontext mit Freigaberecht. MCP- und Automatisierungszugangsdaten werden unabhängig von der Rollenmitgliedschaft abgewiesen. Der interaktive Kontext wird technisch getrennt, etwa durch separate Audience und geschützte Websitzung mit CSRF-Schutz. Das bloße Weglassen eines MCP-Werkzeugs ist keine Zugriffssperre. Es gibt keine automatische Policyfreigabe; der Policyservice begrenzt oder verweigert nur.
logs.query nutzt erlaubte Quellkennungen wie Event-Log-Kanal oder Journald-Unit, keine unbeschränkte vom Modell behauptete Datei. Gespeicherte Logs sind innerhalb der Leserechte ohne Einzelgenehmigung lesbar. Eine Live-Erhebung ist ein begrenzter Diagnosejob mit passenden Leserechten UND expliziter menschlicher WebUI-Genehmigung; der Aufruf beantragt ihn lediglich. Zurückgelieferte Logs bleiben nicht vertrauenswürdige Daten.
23.4 Beispiel: Hello World auf Windows und Linux
Die folgenden JSON-Blöcke zeigen die normativen fachlichen Felder mit fiktiven IDs und Beispielzeitpunkten. Für tatsächliche Tests werden neue IDs und passende zukünftige Fristen erzeugt. Die Beispiele sind keine bereits ausgeführten Aufträge. Die endgültigen Schemas müssen zusätzliche Integritätsfelder und serverseitig ermittelte Zuordnungen entsprechend den vorherigen Abschnitten enthalten.
Anfrage an operations.plan:
{
"tenant_id": "11111111-1111-4111-8111-111111111111",
"action": "run_script",
"targets": {
"asset_ids": [
"22222222-2222-4222-8222-222222222222",
"33333333-3333-4333-8333-333333333333"
]
},
"parameters": {
"variants": [
{
"os_family": "windows",
"interpreter": "powershell",
"encoding": "utf-8",
"script_utf8": "Write-Output 'Hello World'\n"
},
{
"os_family": "linux",
"interpreter": "posix_sh",
"encoding": "utf-8",
"script_utf8": "printf '%s\\n' 'Hello World'\n"
}
],
"execution_identity": "agent_service",
"timeout_seconds": 60,
"max_output_bytes": 65536
},
"schedule": {
"not_before": "2026-11-12T12:00:00Z",
"start_before": "2026-11-13T12:00:00Z",
"offline_policy": "wait_until_deadline"
},
"rollout": {
"max_parallel": 5,
"halt_after_failures": 1
},
"reason": "Hello-World-Abnahme auf zwei Testgeräten"
}
Der Server speichert die Skripte als unveränderliche Artefakte, wählt je Ziel die passende Variante und liefert unter anderem plan_id, plan_hash, resolved_targets, excluded_targets, authorization_status und expires_at. Nicht unterstützte Ziele werden mit Gründen sichtbar. Standardmäßig ist der Plan nicht einreichbar, solange ein angefordertes Ziel nicht abgedeckt ist; ein bewusst reduzierter Plan ist eine neue feste Zielmenge.
Einreichen des Genehmigungsantrags mit operations.submit (noch keine Ausführung, auch nicht bei passender Policy):
{
"tenant_id": "11111111-1111-4111-8111-111111111111",
"plan_id": "44444444-4444-4444-8444-444444444444",
"idempotency_key": "hello-world-abnahme-001"
}
Antwort von operations.submit:
{
"operation_id": "55555555-5555-4555-8555-555555555555",
"plan_id": "44444444-4444-4444-8444-444444444444",
"planned_job_count": 2,
"job_count": 0,
"approval_state": "pending_approval",
"execution_state": null
}
Ein berechtigter Mensch öffnet anschließend den Antrag in der WebUI. Er sieht beide Zielgeräte, Zielanzahl 2, Interpreter, exakte Skriptinhalte und Skript-/Jobpayload-/Planhashes, Fristen und Auswirkungen und genehmigt explizit dieses feste Paket. Erst diese Aktion erzeugt atomar Genehmigung, Ausführung, zwei Jobs und Outbox. jobs.get(operation_id) zeigt dann approval_state=approved, job_count=2 und execution_state=queued; zuvor zeigt es approval_state=pending_approval, execution_state=null und keine Jobs. MCP kann diese Entscheidung nur abfragen, nicht treffen.
Die Ausführungsaggregation unterscheidet queued, running, succeeded, partially_succeeded, failed, cancelled und needs_attention; sie ist getrennt vom Antragsstatus. Sie liefert Zähler pro Jobzustand. unknown erzeugt needs_attention; „alle erfolgreich“ gilt nur bei bestätigten Erfolgen. Gemischte endgültige Ergebnisse mit mindestens einem Erfolg ergeben partially_succeeded. Übersprungene/abgelaufene Jobs zählen nicht als Erfolg. Wiederholtes Submit liefert dieselbe operation_id und den aktuellen Antrags-/Ausführungsstatus, niemals neue Jobs.
24 Aktions-, RustDesk- und Providerverträge
24.1 Typisierte Aktionen
| Aktion | Wesentliche Parameter | Erfolgsnachweis |
|---|---|---|
refresh_inventory |
Scope, gewünschte Quellen, Zeitlimit | Neue Beobachtung mit Erhebungszeit; bei Teilfehlern vollständige Qualitätsangabe |
ensure_package |
Unveränderliche Rezeptversion, Paketversion, Architektur, Installationskontext | Produkt/Version unabhängig vom Installerexitcode festgestellt |
ensure_rustdesk (nur später optional, keine MVP-Pflicht) |
Unveränderliche Profilversion, dazugehörige Paketrezepte, erlaubte Reparaturschritte | Bei späterer Integration Paket, wirksame Konfiguration, Dienst und ID getrennt nachgewiesen |
set_service_state |
Eindeutige Dienstkennung, gewünschter Zustand, Timeout | OS-Dienststatus und gegebenenfalls definierter Funktionscheck |
reboot |
Grund, frühester Zeitpunkt, Abhängigkeitsgruppe, Wiederanmeldefrist | Authentisierte Wiederanmeldung, neue Boot-ID, Nachprüfung |
run_script |
Exakte Artefakte, Interpreter, Argumente, Identität, Laufzeit, Outputlimit | Ausführungsergebnis plus ausdrücklich definierte Nachbedingungen |
apply_updates |
Unterstützter Provider, Auswahl, Regeln zu Reboot und Wartungsfenster | Aktualisierte Inventur, Ergebnis je Update, Scan-/Neustartzustand |
query_logs |
Erlaubte Quelle, Zeitfenster, Cursor, Filter und Limits | Quelle, Zeit, Ergebnisgrenzen und neuer bestätigter Cursor |
Ein Shell-Exitcode 0 belegt den erfolgreichen Prozessabschluss, aber nicht automatisch eine beliebige fachliche Wirkung. Für das Hello-World-Beispiel genügen Exitcode 0 und die erwartete Ausgabe. Für Installationen, Dienstaktionen und Reboots gelten die getrennten Nachbedingungen.
Freie Skripte laufen als temporäre, zugriffsgeschützte Dateien mit festgelegtem Interpreter und strukturiert übergebenen Argumenten. Standardaktionen werden nicht in einen frei zusammengesetzten Shellstring umgewandelt. Nicht vorhandenes Bash wird nicht mit einer vermeintlich kompatiblen Shell ersetzt. Windows-PowerShell und PowerShell 7 sind unterscheidbare Fähigkeiten. Konfiguration und Policy bestimmen den erlaubten Interpreter; lokale Ausführungsbeschränkungen werden nicht stillschweigend abgeschaltet.
Für diese Spezifikation bezeichnet die Kennung powershell Windows PowerShell 5.1, pwsh PowerShell 7 und posix_sh /bin/sh. Fehlende Interpreter erzeugen UNSUPPORTED_CAPABILITY. Der Adapter dokumentiert Encoding und Ausgabeverhalten für den konkreten Interpreter und prüft sie nativ; eine notwendige Encodingtransformation geschieht vor Hashbildung und Planfreigabe. Die Rohbytes der Ausgabe bleiben erhalten. Ein fachlicher Textvergleich darf dokumentiert CRLF und LF normalisieren, verändert aber weder gespeicherte Skriptbytes noch deren Hash.
24.2 RustDeskConfigProfile
Historischer Architekturvertrag für eine spätere optionale Integration. Gemäß Useroverride in 0.1 vollständig aus dieser Umsetzung/MVP ausgeschlossen: keine Profile/Provisionierung, Installation oder externe Desktopabnahme. Die folgenden Anforderungen gelten erst bei gesonderter späterer Beauftragung, nicht als offenes MVP-Gate.
Ein Profil enthält mindestens profile_id, tenant_id, version, desired_package_version, je Plattform die geprüfte Rezept-/Artefaktreferenz, id_server, optional relay_server und api_server, server_public_key, Installationskontext, erlaubte Zugriffseinstellungen, Secret-Versionreferenzen und zulässige Reparaturschritte. Ein öffentlicher Serverschlüssel ist kein privater Zugangsschlüssel.
ensure_rustdesk führt folgende Schritte aus:
- Betriebssystem, Architektur, Desktopfähigkeit, bestehende Installation und Profilberechtigung prüfen.
- Freigegebenes Paket beziehen und Herkunft/Hash prüfen; keine frei vom LLM gelieferte Download-URL als privilegierten Installer starten.
- Paket im definierten Kontext installieren beziehungsweise Sollversion herstellen.
- Bei Bedarf den Dienst einrichten; Serverkonfiguration, Einstellungen für unbeaufsichtigten Zugriff und Secret-Anwendung als getrennte Schritte durchführen.
--configwird nicht pauschal als vollständige Einrichtung aller Zugriffsregeln behandelt. - Effektive Konfiguration in den tatsächlich genutzten Dienst-/Benutzerkontexten prüfen.
- Ergebnis mit Einzelprüfungen und Fehlern zurückmelden; Zugangsdaten nie als normales stdout oder MCP-Ergebnis ausgeben.
Das Ergebnis enthält package_installed, observed_version, config_applied, profile_id, profile_version, service_running, rustdesk_id, reboot_required und connection_test_status. Letzteres verwendet not_tested, passed, failed oder not_applicable samt Zeitpunkt und Prüfer. Ein Dienststart allein darf keinen bestandenen externen Verbindungstest erzeugen.
Ein wiederholter Auftrag darf keine neue RustDesk-Identität erzwingen und kein Passwort unbeabsichtigt rotieren. Gewollte Rotation ist ein eigener profilgebundener Schritt. Fehlt eine passende RustDesk-Plattformunterstützung, lautet das Ergebnis UNSUPPORTED_CAPABILITY; der RMM-Agent kann auf demselben Gerät dennoch weiter funktionieren.
Die End-to-End-Abnahme verwendet einen tatsächlichen RustDesk-Client außerhalb des Zielgeräts und die vorgesehene Server-/Relaykonfiguration. Sie wird nach einem autorisierten Geräte-Reboot wiederholt. Ein WSS-/443-only-Profil darf erst nach Prüfung der eingesetzten Edition und Version als unterstützt erscheinen.
24.3 Proxmox- und PBS-Verträge
Dieses gesamte Kapitel und seine erste Connectorabnahme gelten erst nach dem MVP, einschließlich Backup- und Clusterprüfungen. Kein hier genannter Client ist für Windows-/Linux-Gastagenten erforderlich.
Jeder Discoverylauf führt scope, started_at, completed_at, completeness, erfolgreiche Teilabfragen und Fehler. 403, Timeout oder Rechtefilter dürfen vorher bekannte Gäste nicht löschen. Fehlende Ressourcen werden erst aus einem erfolgreichen vollständigen Abgleich des betreffenden Bereichs als missing gekennzeichnet; Historie bleibt erhalten.
Provideridentitäten sind mindestens:
- PVE-Gast: Provider-/Clusterinstanz, Gasttyp, VMID und eigener Ressourcenlebenszyklus.
- PVE-Task: Provider-/Clusterinstanz, Knoten und UPID.
- PBS-Snapshot: PBS-Instanz, Datastore, Namespace, Backup-Typ, Backup-ID und Backupzeitpunkt.
Gast-Agent-Zuordnung und Backupzuordnung führen Herkunft, Vertrauens-/Prüfstatus und Gültigkeitszeitraum. Ein gleicher Name oder eine gleiche VMID in einem anderen Cluster ist kein Match. Innerhalb eines Clusters verändert Migration die Hostbeziehung, nicht automatisch die Assetidentität.
Lokale PVE-/PBS-TLS-Verifikation nutzt einen zum Zertifikat passenden Servernamen und eine konfigurierte vertrauenswürdige CA oder einen kontrolliert provisionierten Pin. Ein Zugriff über localhost darf Namensfehler nicht durch accept_invalid_certs umgehen. Token sind Secrets; Rechte und benötigte Endpunkte stehen je getesteter Version in der Supportmatrix.
Backupzustände werden getrennt in schedule_evaluation, attempt_result, coverage, snapshot_presence, verification_result und restore_test_result geführt. Jeder Teil kann unknown oder not_applicable sein und trägt Quelle und Zeit. Ein erfolgreiches Gesamtbackup wird nicht automatisch auf alle Gäste übertragen; nicht interpretierbare Taskdaten erzeugen keinen erfundenen Einzelerfolg.
Für die erste Abnahme genügt eine ausdrücklich konfigurierte maximale Backupalter-Regel mit zuverlässigem historischem Abdeckungsfenster. Automatischer Import aller Proxmox-Zeitplanvarianten ist ein separater, versionsgeprüfter Provider. Eine fehlende konfigurierte PBS-Verbindung beeinträchtigt den optionalen PBS-Status, macht aber den PVE-Connector nicht insgesamt defekt.
25 Implementierungsreihenfolge und Abnahmekriterien
25.1 Arbeitspakete
Jedes Arbeitspaket wird als vollständige, lauffähige Erweiterung abgeschlossen. Sicherheits- und Autorisierungsgrundlagen werden vor dem ersten schreibenden Pfad umgesetzt. Ein späteres UI oder MCP darf keine neue Ausführungsabkürzung schaffen.
| Paket | Lieferung | Verbindliche Abnahme |
|---|---|---|
| M0 Repository und lokale Umgebung | Workspace, gepinnte Toolchain, Fehler-/Konfigurationsmodell, Migrationen, PostgreSQL, Dev-Identitäten, CI-Grundlagen | Frischer Checkout lässt sich nach README starten; zwei Testkunden; keine Secrets im Repository; Dev-Auth in Produktionsprofil verweigert |
| M1 Ausgehende Agentstrecke | Zuerst echter Linux-x86-64-Dienst auf tatsächlicher Test-VM, Enrollment, Zertifikate, WSS, Heartbeat und Basisinventar | Reale Linux-VM meldet OS, Hostname und freien Speicher; unbekannter Host ohne PVE-Zugang zulässig; Rotation/Widerruf; keine eingehende RMM-Firewallfreigabe; Windows-Dienstabnahme erst in späterer Windows-Phase |
| M2 Dauerhafte, menschlich autorisierte Jobs | Plan, begrenzende Policy, persistenter Antrag, minimale interaktive WebUI-Genehmigung, Outbox, Journal, Startgrant, Zustände, Ressourcenlocks und Hello World | Vor Genehmigung keine Ausführungsjobs/Outbox/JobOffers/Startgrants; erster Hello-World-Job erst nach menschlicher Genehmigung; Redelivery ohne zweite Wirkung; ACK, Abbruch und Wiederanlauf geprüft |
| M3 API, MCP Lesen und Verwaltungsoberfläche | Gemeinsame DTOs, Kundenauswahl, Geräteansicht, Datenalter, Jobs, lesende MCP-Werkzeuge | Derselbe Bestand über UI, HTTP und MCP; fremde Kundenbestände unzugänglich; Bereitstellung der Plattform-/Capability-Matrix |
| M4 Paketverwaltung ohne RustDesk | Zuerst Linux-Rezeptkatalog/APT, ensure_package, Paketversions-/Nachprüfung; MSI/EXE erst in Windows-Phase | Allgemeine Paketstrecke auf tatsächlicher Linux-Test-VM mit festem UI-genehmigtem Plan, unabhängiger Versionsprüfung und sicherer Wiederholung nachgewiesen; keine RustDesk-Installation, Profile/Provisionierung oder externe Desktopabnahme |
| M5 MCP und Sammelaktionen (Linux-MVP-Abschluss) | operations.plan/submit als Antragsstrecke, Linux-Skripte, Reboot, Rolloutlimits, Teilergebnisse; ohne RustDesk | Linux-Varianten der drei Referenzabläufe 0.3 Nr. 1–3 mit echtem MCP-Client und WebUI-Genehmigung gemäß 0.1; alle Features real auf Linux-VM nachgewiesen; MCP genehmigt niemals; Diagnose/Retry/Folgejob ebenso geschützt; Offlinegerät wartet nur bis Frist; RustDesk-Referenz Nr. 4 ausgeschlossen |
| W Windows nach Linux-MVP | Erst nach Linux-MVP-Abnahme Windows-x86-64-Dienst, Adapter, MSI/EXE und PowerShell sowie M0–M5-Funktionen | Native Windows- und Mischplattformabnahmen, einschließlich AT-15; kein vorgezogener Windows-Abnahmezwang im Linux-MVP |
| M6a Monitoring und ARM64 (nach MVP) | Erwartete Dienste, Alarme, produktiver Metrikpfad, native ARM64-Abnahmen | Keine erfundenen Patchwerte; ARM64 nur auf tatsächlich nativ getesteten Zielsystemen freigegeben |
| M6b Proxmox, Cluster und Backups (nach MVP) | PVE-Modul/-Client auf demselben Linux-Agenten, Discovery, Cluster und Backups; optional PBS | Migration, VMID-Wiederverwendung, Clusterrechte, fehlende Backups, Abdeckung und ACL-Verlust korrekt; keine Abhängigkeit eigenständiger Gastagenten |
| M7 Terminal und produktionsfähiger Betrieb | Relay, begrenzte Shells, Agentupdate, Restoreabgleich, Betriebsdokumentation und Lasttest | Rechteentzug beendet Sitzung; Updatefehler/Restore erzeugen keine Doppelwirkung; dokumentierte Recovery und gemessene Kapazität |
| M8 Optionale Erweiterungen | Geschäftsleistungen, zusätzliche Distributions-/Paketprovider, weitere Integrationen | Eigene Anforderungen und Plattformabnahmen; keine Änderung der Mandantengrenzen |
MVP-Grenze und Reihenfolge: Erst Linux-MVP M0–M5 x86-64 ohne RustDesk, mit WebUI, MCP und autorisierten dauerhaften Jobs; jedes Feature zuerst tatsächlich auf Linux-Test-VM nachweisen. WebUI-Bedienungsausnahme ausschließlich gemäß 0.1. Erst nach dokumentierter Abnahme beginnt W (Windows x86-64); danach folgen M6a/M6b, M7 und M8. PVE-/PBS-/Backup-/Clusterabnahmen sind noch später und blockieren Linux-MVP nicht; keine vorgezogene PVE-Implementierung. Windows-/Mischplattformbeispiele bleiben Zielverträge der Windows-Phase, keine Linux-MVP-Pflicht. RustDesk bleibt spätere optionale Integration und ist weder hier noch automatisch in W Pflicht. Ausgelassene RustDesk-Nachweise sind keine bestandenen Tests und keine offenen MVP-Gates.
25.2 Erste vertikale Strecke
Für den ersten vollständigen Durchlauf werden zwei Testkunden und die tatsächliche Linux-x86-64-Test-VM genutzt; ein Hypervisor muss weder bekannt noch erreichbar sein. Server lokal in Docker auf dem PC und VM-Anbindung gemäß docs/development.md. Die Strecke lautet: Enrollment → ausgehende Verbindung → passives Inventar → feste Zielauswahl → Hello-World-Plan → begrenzende Policyprüfung → operations.submit mit persistentem pending_approval → berechtigter Mensch prüft und genehmigt in minimaler WebUI feste Linux-Jobs samt Skriptbytes/Hashes → atomar Genehmigung, Ausführung, Jobs und Outbox erzeugen → Job zustellen → Agentjournal → JobAccepted → aktuellen Startgrant beziehen und Verbrauch journalisieren → Ausführung auf tatsächlicher VM → gebundene Nachprüfung → Ergebnis. Vor Genehmigung nachweisen, dass kein ausführbarer Job, JobOffer oder Startgrant existiert. Keine erlaubende Testpolicy oder Linux-Dev-Abkürzung; auch Testjobs benötigen menschliche Genehmigung. Passives Standardinventar benötigt keine Jobfreigabe. Windows ergänzt diese Strecke erst nach Linux-MVP-Abnahme.
Die erste Lieferung muss diese Strecke wirklich ausführen. Danach dieselbe Strecke mit HTTPS Long Polling und einem neu menschlich genehmigten Plan prüfen. Die minimale interaktive Genehmigungs-WebUI ist bereits in M2 Pflicht; die umfassende Oberfläche folgt in M3. Ein Simulator ergänzt reale Tests, ersetzt aber keine native Dienst- oder Installerabnahme.
25.3 Fehler- und Sicherheitsabnahmen
Alle Ausführungsjobs dieser Tests benötigen explizite menschliche WebUI-Genehmigung, außer wenn gezielt deren Fehlen geprüft wird (dann darf kein Job starten). Keine impliziten Reboots, Updates oder destruktiven Zieltests; Testumfang gesondert ausdrücklich abstimmen. Linux-MVP prüft zunächst Linux-Varianten auf tatsächlicher VM; AT-15 und Windows-Anteile folgen in W nach Linux-MVP-Abnahme. AT-03 gilt im Linux-MVP nur für Gerätezertifikate; der PVE-Anteil, AT-16 und AT-19–AT-23 gehören ausschließlich zu M6b nach der Windows-Phase. AT-25/AT-26 sind Betriebsreifeabnahmen in M7; übrige Fälle werden mit der jeweils gelieferten Capability geprüft, nicht durch spätere Module zum MVP-Blocker.
| ID | Test | Erwartete Reaktion |
|---|---|---|
| AT-01 | Agent hinter NAT; eingehende Verbindungen blockiert | Inventar und Jobausführung funktionieren ausschließlich über ausgehende Verbindungen |
| AT-02 | WSS blockiert, HTTPS erlaubt | Long-Poll-Strecke funktioniert; Terminalverfügbarkeit wird getrennt angezeigt |
| AT-03 | Geräte- oder PVE-Zertifikat ungültig | Verständlicher Verbindungsfehler, keine automatische Abschaltung der Prüfung |
| AT-04 | Kunde B fragt Asset, Job, Log oder Artefakt von A an | Kein Datenzugriff über HTTP, MCP, Worker- oder Objektpfad |
| AT-05 | Tenant-Kontext fehlt oder Poolverbindung wird wiederverwendet | Zugriff wird verweigert; keine Übernahme des vorherigen Tenant-Kontexts |
| AT-06 | Agent verliert Verbindung nach Annahme, vor Start | Kein neuer Jobstart offline, auch keine Diagnose; nach Kontakt Genehmigung und aktuelle Rechte erneut prüfen |
| AT-07 | Ergebnis-ACK verloren | Derselbe Ergebnisnachweis erneut übertragen; keine erneute Wirkung |
| AT-08 | Agentabsturz direkt nach möglicher Wirkung | unknown und Abgleich; freies Skript nicht blind wiederholen |
| AT-09 | Startfrist abgelaufen oder Kunde entzieht Rechte | Vor Beginn keine Wirkung; laufender Paketmanager nur sicher abbrechen |
| AT-10 | Identitätsklon oder Snapshot-Restore | Keine stille Zusammenführung oder historische Wiederholung; erneuter Abgleich |
| AT-11 | Agent meldet alte gepufferte Heartbeats/Messwerte | Keine falsche aktuelle Online-/Grünanzeige |
| AT-12 | Manipulierte Anweisung in Logtext | Daten bleiben Daten; nächster Toolaufruf benötigt unveränderte Autorisierung |
| AT-13 | Gleicher Idempotenzschlüssel mit geändertem Skript | IDEMPOTENCY_CONFLICT; keine Ausführung |
| AT-14 | Plan nach Freigabe verändert beziehungsweise Zielmenge erweitert | Hashbindung schlägt fehl oder neuer Plan nötig |
| AT-15 | Windows/Linux-Sammelskript, ein Ziel offline | Passende Interpreter; Ergebnis je Gerät; Offlineziel wartet nur bis zur Frist |
| AT-16 | Reboot von Gast und Hypervisor gleichzeitig angefragt | Abhängigkeiten und unterschiedliche Berechtigungsbereiche werden sichtbar und beachtet |
| AT-17 (später optional, nicht MVP) | RustDesk erneut installieren/konfigurieren | Nur bei späterer Integration: Sollzustand erhalten; keine unbeabsichtigte neue ID/Secretrotation; gesonderter Verbindungstest |
| AT-18 (später optional, nicht MVP) | Headless-/nicht unterstütztes RustDesk-Ziel | Nur bei späterer Integration: ehrliche Capabilitymeldung; keine automatische Desktopinstallation |
| AT-19 | PVE-Token verliert Rechte oder Discovery ist unvollständig | Bekannte Gäste bleiben bestehen; Datenqualität sinkt sichtbar |
| AT-20 | PVE-Collectorwechsel mit verspätetem Taskereignis | Ein historischer Nachweis; aktuelle Sicht nicht durch alte Generation überschrieben |
| AT-21 | VM migriert oder VMID wird neu vergeben | Migration erhält Ressource, Wiederverwendung erhält neuen Lebenszyklus |
| AT-22 | Fälliges Backup startet nie; ein Gast im Sammelbackup scheitert | Fehlende Sicherung und Einzelfehler unabhängig vom Gesamtjob erkennbar |
| AT-23 | Disk vom Backup ausgeschlossen oder LXC-Bind-Mount vorhanden | Abdeckung eingeschränkt/unklar statt uneingeschränkt grün |
| AT-24 | Gateway-/Serverausfall und anschließender Wiederanlauf | Reconnect mit Jitter; dauerhafte Jobs bleiben; keine automatische Doppelwirkung |
| AT-25 | Zentrale aus älterem Backup wiederhergestellt | Änderungen zunächst gesperrt; Journal-/Generationsabgleich vor Freigabe |
| AT-26 | Manipuliertes beziehungsweise unzulässig altes Agentupdate | Update verweigert; funktionsfähige erlaubte Version bleibt erhalten |
| AT-27 | Telemetrie-/Logflut eines Kunden | Quoten und Backpressure greifen; Jobjournal und andere Kunden bleiben geschützt |
| AT-28 | Ein Agent läuft, aber erwarteter Webdienst ist defekt | Verbindung online, fachliche Gesundheit kritisch; Zustände nicht vermischen |
| AT-29 | UI, MCP oder Automatik reicht ohne menschliche Genehmigung ein, auch Diagnose/Hello World | Nur Antrag pending_approval, in jobs.get sichtbar; keine ausführbaren Jobs, Outbox, JobOffers, Startgrants oder Wirkung |
| AT-30 | MCP-/Automatisierungstoken mit Approver-Rolle ruft Freigabeendpunkt auf; Policy behauptet Erlaubnis | Token abgewiesen; keine Policyfreigabe; ausschließlich explizite menschliche interaktive WebUI-Genehmigung |
| AT-31 | Transparentes Sammelpaket genehmigen, danach Ziel/Bytes/Frist verändern oder Wildcard verlangen | Alle festen Jobs vor Genehmigung sichtbar; unveränderliche Bindung; jede Änderung neuer genehmigungspflichtiger Plan; keine Dauerfreigabe |
| AT-32 | Retry/neuer Versuch oder Reboot-/Diagnosefolgejob nach Fehler | Neuer fester genehmigter Plan, sofern Folgejob nicht bereits einzeln im genehmigten Paket gebunden; keine implizite Folge-/Retryerlaubnis |
| AT-33 | Derselbe genehmigte Versuch erneut zugestellt; nicht gestartetes technisches Ticket abgelaufen | Keine neue Genehmigung für Redelivery; kein zweiter Start; Ticketersatz nur bei belegtem Nichtstart und weiterhin gültiger Genehmigung |
| AT-34 | Windows-/Linux-VM mit unbekanntem Host und ohne PVE-Agent/-Zugang | Enrollment, Inventar, UI/MCP und genehmigte Jobs vollständig nutzbar; kein PVE-/Hypervisorzwang |
25.4 Definition of Done je Lieferung
- Tatsächliche Funktionen sind lauffähig; fehlende Fähigkeiten werden ausdrücklich als fehlend ausgewiesen.
cargo fmt --check, sinnvolle Clippy-Prüfungen und die betroffenen Unit-/Integrationstests bestehen auf den passenden Plattformen.- Datenbankmigrationen und eine Wiederherstellung auf einem frischen Entwicklungsbestand wurden für die betroffene Änderung geprüft.
- Authentisierung, Tenant-Grenzen und relevant veränderte Fehlerpfade sind getestet; eine bestandene Normalfall-Demo allein genügt nicht.
- Protokoll-/API-Änderungen besitzen Schemas, Kompatibilitätsregeln und angepasste Fixtures.
- Bei Windows-/Linux-Systemfunktionen liegt eine native Abnahme vor; Cross-Builds werden nicht als Laufzeittest ausgegeben.
- README und
docs/implementation-status.mdnennen Startbefehle, Konfiguration, implementierte Arbeitspakete und verbleibende Grenzen. - Keine echten Secrets, Kundenlogs oder privaten Schlüssel im Repository und keine Defaultpasswörter im Produktionsprofil.
- Testergebnisse beschreiben, was tatsächlich geprüft wurde. Nicht ausgeführte Tests werden nicht als bestanden dargestellt.
- Jedes Feature ist zuerst auf tatsächlicher Linux-Test-VM ausgeführt und nachgewiesen; fehlender Realnachweis bleibt offen. Geplante Befehle als geplant, nicht getestet markieren. Keine impliziten Reboots, Updates oder destruktiven Zieltests aus einer Toolinstallationsfreigabe ableiten.
Die Coding-KI implementiert und testet in dafür vorgesehenen Entwicklungsumgebungen; Installation benötigter Entwicklungs-/Testtools ist ausdrücklich erlaubt. Dies ist keine implizite Genehmigung von Kundensystemänderungen. Enrollment echter Kundengeräte, produktive Neustarts und Bereitstellung auf realer Infrastruktur bleiben gesonderte Betriebsaktionen. Jeder über die Plattform eingestellte Test- oder Kundenjob benötigt weiterhin menschliche WebUI-Genehmigung.
26 Direkt verwendbarer Startauftrag für eine Coding-KI
Der folgende Text kann zusammen mit dieser Markdown-Datei an eine implementierende KI gegeben werden:
Implementiere die in Rust_RMM_Implementierungsspezifikation.md beschriebene
Plattform. Lies die gesamte Spezifikation, bevor du technische Entscheidungen
triffst. Behandle die Anforderungen REQ-01 bis REQ-15 und die normativen
Verträge als verbindlich.
Prüfe zuerst das vorhandene Repository und seine lokalen Anweisungen. Falls
noch kein Projekt existiert, lege den Cargo-Workspace und die lokale
Entwicklungsumgebung gemäß Kapitel 19 an. Verwende die Startentscheidungen
aus Kapitel 18 und dokumentiere verbleibende Betriebsparameter als
Konfiguration. Erfinde keine Kundenzugangsdaten oder erfolgreichen Tests.
Beginne mit M0, M1 und M2 als erster vertikaler Strecke: zwei Testmandanten,
ein Linux-Agent auf tatsächlicher Linux-Test-VM, ausgehende TLS-Verbindung, Inventar und
ein erst nach expliziter menschlicher WebUI-Genehmigung ausgeführter
Hello-World-Job mit lokalem Journal und überprüftem Ergebnis. operations.submit
speichert nur pending_approval; keine Ausführungsqueue vor Genehmigung.
Policies begrenzen/verweigern nur; MCP darf niemals genehmigen. Diagnosejobs,
Reboot-Folgejobs und neue Versuche benötigen ebenfalls menschliche Genehmigung.
Gastagenten funktionieren ohne bekannten Host und ohne Hypervisorzugang.
Alle Features zuerst real auf Linux-Test-VM nachweisen. Erstes Phasenziel:
Linux-MVP M0–M5 x86-64. Windows beginnt erst nach dessen dokumentierter Abnahme;
ARM64, PVE/Cluster/Backups und Betriebsreife folgen noch später. Kein vorgezogenes PVE.
Lies AGENTS.md und docs/development.md: Server lokal in Docker auf dem PC,
Ports nur Loopback, PC initiiert SSH-Reverse-Forward zur VM, TLS E2E mit
DNS SAN rmm-dev.internal und expliziter VM-Auflösung, keine ungültigen Certs.
SSH nur Dev/bootstrap, kein RMM-Sicherheitsersatz. Auch Linux-Dev-Jobs bleiben
pending_approval bis tatsächlicher menschlicher WebUI-Genehmigung.
VM-Daten credentials/linux-vm.conf, gitignore, Modi 700/600, keine Secrets
loggen/committen, kein source/eval. Keine impliziten Ziel-Reboots, Updates
oder destruktiven Tests. Geplante Commands als geplant markieren,
keinen Erfolg ohne realen Nachweis behaupten.
Installiere erforderliche Entwicklungstools; dies genehmigt keine Änderungen
auf Kundensystemen. Implementiere die weiteren Arbeitspakete in
der Reihenfolge von Kapitel 25. Nutze gemeinsame Fachservices für HTTP, MCP
und automatische Regeln.
Erzeuge konkrete Änderungen, führe sie soweit die vorhandene Umgebung es
ermöglicht aus und prüfe die relevanten Abnahmekriterien. Dokumentiere
fehlende native Testmöglichkeiten und fahre mit unabhängigen Aufgaben fort.
Berichte pro abgeschlossener Strecke: implementierte Funktionen, genaue
Start-/Testbefehle, tatsächliche Testergebnisse und nächste Arbeitspakete.
Halte docs/implementation-status.md aktuell, damit die Arbeit fortgesetzt
werden kann.
Baue keine eigene grafische Fernsteuerung. Lasse RustDesk in dieser Umsetzung
aus: keine Installation, Profile/Provisionierung oder externe Desktopabnahme.
Die verbliebenen RustDesk-Verträge sind ausschließlich später optional.
Erhalte die Vorgabe ausschließlich vom Agenten initiierter Verbindungen.
Gib unklare Ausführungsergebnisse als unknown aus und führe sie nicht blind
erneut aus. Behalte die Mandantentrennung auf jedem Zugriffspfad bei.
Quellen und Referenzen
Alle Quellen sind Primärquellen der jeweiligen Projekte oder Hersteller. Abrufstand ist der 12. November 2026. Architekturentscheidungen, Intervalle, Betriebsziele und Lastszenarien in diesem Dokument sind Empfehlungen; sie sind keine vom Hersteller zugesicherten Eigenschaften der entworfenen Plattform.
-
Rust Projekt. Rust Programming Language. https://rust-lang.org/ ↩︎
-
Model Context Protocol. Official Rust SDK. https://github.com/modelcontextprotocol/rust-sdk ↩︎
-
Tokio Projekt. Tokio und Axum. https://tokio.rs/ und https://github.com/tokio-rs/axum ↩︎
-
Rust Projekt. Platform Support. https://doc.rust-lang.org/stable/rustc/platform-support.html ↩︎
-
Proxmox. Hardware Requirements. https://www.proxmox.com/en/products/proxmox-virtual-environment/requirements ↩︎
-
Microsoft. Initializing the COM Library. https://learn.microsoft.com/en-us/windows/win32/learnwin32/initializing-the-com-library ↩︎
-
Microsoft. Working with software installations. https://learn.microsoft.com/en-us/powershell/scripting/samples/working-with-software-installations ↩︎
-
Microsoft. Troubleshooting Windows Package Manager. https://learn.microsoft.com/en-us/windows/package-manager/winget/troubleshooting ↩︎
-
Proxmox. QEMU/KVM Virtual Machines. https://github.com/proxmox/pve-docs/blob/master/qm.adoc ↩︎
-
Proxmox. API Proxy Daemon. https://github.com/proxmox/pve-docs/blob/master/pveproxy.adoc ↩︎
-
Proxmox. User Management und Tasks API. https://github.com/proxmox/pve-docs/blob/master/pveum.adoc und https://github.com/proxmox/pve-manager/blob/master/PVE/API2/Tasks.pm ↩︎
-
Proxmox. Backup and Restore. https://github.com/proxmox/pve-docs/blob/master/vzdump.adoc ↩︎
-
Proxmox Backup Server. User Management. https://pbs.proxmox.com/docs/user-management.html ↩︎
-
Proxmox Backup Server. Maintenance Tasks. https://pbs.proxmox.com/docs/maintenance.html ↩︎
-
PostgreSQL. SELECT und SKIP LOCKED. https://www.postgresql.org/docs/current/sql-select.html ↩︎
-
Amazon Web Services. Making retries safe with idempotent APIs. https://aws.amazon.com/builders-library/making-retries-safe-with-idempotent-APIs/ ↩︎
-
RustDesk. Client Deployment und Client Configuration. https://rustdesk.com/docs/en/self-host/client-deployment/ und https://rustdesk.com/docs/en/self-host/client-configuration/ ↩︎
-
RustDesk. Self Host und erforderliche Verbindungen. https://rustdesk.com/docs/en/self-host/ ↩︎
-
Model Context Protocol. Streamable HTTP 2026-07-28. https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/streamable-http ↩︎
-
Model Context Protocol. Authorization Security Considerations. https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization/security-considerations ↩︎
-
OWASP. MCP Security Cheat Sheet. https://cheatsheetseries.owasp.org/cheatsheets/MCP_Security_Cheat_Sheet.html ↩︎
-
PostgreSQL. Row Security Policies. https://www.postgresql.org/docs/current/ddl-rowsecurity.html ↩︎
-
VictoriaMetrics. Single Node Documentation und Multitenancy. https://docs.victoriametrics.com/victoriametrics/ ↩︎
-
The Update Framework. Security. https://theupdateframework.io/docs/security/ ↩︎