Agent - Uebersicht
Der DATAZONE Control Agent ist ein leichtgewichtiger Dienst, der auf jedem verwalteten Host installiert wird. Er sammelt Systemdaten, fuehrt Befehle aus und stellt die Verbindung zum Backend her.
Funktionen
| Funktion | Beschreibung |
|---|---|
| Heartbeat | Regelmaessiges Senden von Systemmetriken (CPU, RAM, Disk, Uptime) |
| System-Informationen | Sammlung von Hardware-, Software- und Netzwerkdaten |
| Script-Ausfuehrung | Empfangen und Ausfuehren von Scripts vom Backend |
| Remote Shell | WebSocket-basierte Terminal-Session |
| Tunnel | Port-Forwarding ueber WebSocket-Verbindung |
| SSH-Server | Eingebetteter SSH-Server fuer Agent-SSH-Tunnel |
| Auto-Update | Selbst-Update des Agents auf neue Versionen |
| Task-Verarbeitung | Empfang und Ausfuehrung von Backend-Tasks |
Architektur
┌─────────────────────────────────────┐
│ DATAZONE Agent │
├─────────────────────────────────────┤
│ WebSocket Client │
│ ├── Heartbeat Sender (30s) │
│ ├── Task Receiver (30s) │
│ ├── Ping/Pong (25s) │
│ ├── Shell Handler │
│ └── Tunnel Handler │
├─────────────────────────────────────┤
│ System Collector │
│ ├── Hardware Cache (einmalig) │
│ ├── Metrics (pro Heartbeat) │
│ ├── Update Cache (stuendlich) │
│ └── Windows Cache (Hintergrund) │
├─────────────────────────────────────┤
│ Embedded SSH Server │
├─────────────────────────────────────┤
│ Auto-Updater (5 min) │
├─────────────────────────────────────┤
│ Konfiguration (agent.json) │
└─────────────────────────────────────┘Kommunikation
Der Agent kommuniziert ausschliesslich ueber WebSocket mit dem Backend:
- Der Agent baut eine ausgehende WebSocket-Verbindung zum Backend auf
- Ueber diese Verbindung werden bidirektional Nachrichten ausgetauscht
- Kein eingehender Port muss auf dem Host geoeffnet werden
Firewall-freundlich
Da der Agent nur eine ausgehende Verbindung aufbaut, funktioniert er auch hinter NAT und Firewalls ohne Port-Freigaben auf dem Host.
Reconnect-Verhalten
Bei Verbindungsabbruch versucht der Agent automatisch eine Neuverbindung:
- Startverzoegerung: 1 Sekunde
- Maximale Verzoegerung: 30 Sekunden
- Algorithmus: Exponentielles Backoff (Verzoegerung verdoppelt sich bei jedem Fehlversuch)
- Reset: Nach erfolgreicher Verbindung wird die Verzoegerung auf 1 Sekunde zurueckgesetzt
- Verteilung (ab 3.67.3): Bricht eine laufende Verbindung ab (z. B. beim Neustart von Control), wartet der Agent zufaellig 1-15 Sekunden, bevor er neu verbindet, und schickt den ersten (vollen) Heartbeat danach zufaellig verteilt innerhalb von 20 Sekunden. So melden sich nach einem Neustart nicht alle Agents in derselben Sekunde.
- Drosselung (ab 3.67.3): Ist Control ueberlastet, kann es einen Heartbeat mit HTTP 429 zurueckstellen. Der Agent laesst dann die naechsten Heartbeats fuer die angegebene Zeit (5-60 Sekunden) aus und weicht nicht auf den WebSocket aus. Im Agent-Log steht
Heartbeat deferred by server. - Schnellpfad im Server (ab 3.67.3): Aendern sich nur Messwerte, schreibt Control sie gesammelt alle 5 Sekunden statt bei jedem Heartbeat; spaetestens alle 5 Minuten wird jeder Heartbeat komplett verarbeitet. Notschalter unter Einstellungen > Parameter:
heartbeat_fastpath= 0 schaltet den Schnellpfad ab,heartbeat_throttle= 0 die Drosselung (wirkt nach spaetestens 45 Sekunden, ohne Neustart).
Heartbeat-Intervalle und Datensammlung
Timing-Uebersicht
| Operation | Intervall | Beschreibung |
|---|---|---|
| Heartbeat | 30 Sekunden | Sendet Metriken und Systemdaten an das Backend |
| Task-Polling | 30 Sekunden | Prueft auf neue Aufgaben vom Backend |
| WebSocket-Ping | 25 Sekunden | Erkennt abgebrochene Verbindungen (10s Timeout) |
| Auto-Update-Check | 5 Minuten | Prueft auf neue Agent-Versionen |
Heartbeat-Daten (alle Plattformen)
Jeder Heartbeat enthaelt folgende Basisdaten:
| Feld | Beschreibung | Erfassung |
|---|---|---|
cpu | CPU-Auslastung in Prozent | Echtzeit (500ms Messung) |
memory | RAM-Auslastung in Prozent | Echtzeit |
memory_total | Gesamter Arbeitsspeicher | Echtzeit |
disk | Festplattenauslastung in Prozent | Echtzeit |
uptime | Betriebszeit in Sekunden | Echtzeit |
hostname | Hostname des Systems | Echtzeit |
agent_version | Agent-Version | Fest |
Nur Aenderungen uebertragen (Heartbeat-Delta)
Die grossen Inventarlisten (Windows-Updates, installierte Software, Dienste, geplante Aufgaben, VMs, Backups, OPNsense-Regeln und -Aliase, Pakete, Prozesse an Ports usw.) schickt der Agent nur, wenn sie sich seit dem letzten erfolgreich gesendeten Heartbeat geaendert haben. Messwerte wie CPU, RAM, Disk, Uptime, Load, Gateways und Zaehler gehen immer mit. Control behaelt bei einem fehlenden Feld den letzten Stand; wird eine Liste leer, wird sie als leere Liste gesendet.
Komplett gesendet wird in jedem Fall: beim ersten Heartbeat nach dem Verbinden, beim Wechsel zwischen HTTP und WebSocket-Fallback, nach einem fehlgeschlagenen Senden und spaetestens alle 60 Minuten. Im Agent-Log steht hinter jedem Heartbeat [full ...] oder [delta ...] mit der gesendeten Groesse.
Plattform-spezifische Daten
Linux / PVE / PBS
| Datentyp | Erfassungsintervall | Details |
|---|---|---|
| Hardware-Info | Einmalig beim Start | CPU, RAM, Mainboard, BIOS, Seriennummern |
| Ausstehende Updates | Stuendlich (1h Cache) | apt list --upgradable bzw. dnf check-update |
| Docker-Container | Pro Heartbeat (30s) | Name, Image, Status, Ports |
| SSH-Sessions | Pro Heartbeat (30s) | Benutzer, Quell-IP, Login-Zeit |
| Cron-Jobs | Pro Heartbeat (30s) | System- und Benutzer-Crontabs |
| Load Average | Pro Heartbeat (30s) | 1/5/15 Minuten Durchschnitt |
| Services | Pro Heartbeat (30s) | Systemd-Dienste mit Status |
| Disks | Pro Heartbeat (30s) | Partitionen, Mountpoints, Belegung |
| Netzwerk-Interfaces | Pro Heartbeat (30s) | IPs, MAC, Bytes in/out |
| Offene Ports | Pro Heartbeat (30s) | Listening TCP/UDP mit Prozess |
PVE-spezifisch:
| Datentyp | Erfassungsintervall | Details |
|---|---|---|
| VMs und Container | Pro Heartbeat (30s) | VMID, Name, Status, Ressourcen |
| Storages | Pro Heartbeat (30s) | Storage-Pools und Belegung |
| Backup-Jobs | 30 Minuten (Cache) | Backup-Job-Konfigurationen |
| Backup-History | 30 Minuten (Cache) | Backup-Ausfuehrungshistorie |
PBS-spezifisch:
| Datentyp | Erfassungsintervall | Details |
|---|---|---|
| Datastores | Pro Heartbeat (30s) | Datastores und Belegung |
| Backups | Pro Heartbeat (30s) | Backup-Liste und -Counts |
| Sync-Jobs | Pro Heartbeat (30s) | Synchronisierungsstatus |
OPNsense
| Datentyp | Erfassungsintervall | Details |
|---|---|---|
| Hardware-Info | Einmalig beim Start | CPU, RAM, BIOS |
| Interfaces | Pro Heartbeat (30s) | Interface-Status, IPs, Durchsatz |
| Gateways | Pro Heartbeat (30s) | Gateway-Status, Latenz, Paketverlust |
| VPN-Tunnel | Pro Heartbeat (30s) | OpenVPN, IPsec, WireGuard mit Status |
| Routen | Pro Heartbeat (30s) | Routing-Tabelle (seit v1.3.0) |
| Zertifikate | 6 Stunden (Cache) | ACME- und SSL-Zertifikate mit Ablaufdatum (seit v1.3.0) |
| Unbound DNS Stats | Pro Heartbeat (30s) | DNS-Abfragen, Cache-Hits, Top-Domains (seit v1.3.0) |
| Nginx Virtual Hosts | 1 Stunde (Cache) | Nginx-Konfigurationen und Server (seit v1.3.0) |
| Services | Pro Heartbeat (30s) | OPNsense-Dienste mit Status |
| Config-Aenderung | Pro Heartbeat (30s) | Letzte config.xml-Aenderung |
| Externe IP | Pro Heartbeat (30s) | WAN-IP-Adresse. Ermittelt Control aus der Verbindung des Agents (ab 3.57.1, kein externer Dienst). Bei einer Control-Instanz im selben LAN bleibt das Feld leer. |
| Update-Status | Pro Heartbeat (30s) | Verfuegbare Firmware-Updates |
Windows
Windows-Daten werden im Hintergrund in verschiedenen Intervallen gesammelt, um die Systembelastung zu minimieren:
| Datentyp | Erfassungsintervall | Details |
|---|---|---|
| Hardware-Info | 24 Stunden (Cache) | CPU, RAM, Hersteller, Modell |
| OS-Version/Domain | 1 Stunde (Cache) | Build, Edition, AD-Domain, DC-Status |
| Windows-Dienste | 2 Minuten (Cache) | Name, Status, Starttyp |
| Netzwerk-Interfaces | 2 Minuten (Cache) | Adapter, IPs, DNS |
| Installierte Software | 5 Minuten (Cache) | Via Winget, Name und Version |
| Geplante Aufgaben | 5 Minuten (Cache) | Scheduled Tasks |
| Disk-Informationen | 5 Minuten (Cache) | Laufwerke, Groesse, frei |
| Windows Updates | 10 Minuten (Cache) | Verfuegbare Updates |
| Angemeldete Benutzer | Pro Heartbeat (30s) | Aktive Sessions |
| RustDesk-ID/Version | Pro Heartbeat (30s) | RustDesk-Remote-ID und Version (falls installiert) |
| Domain/DC-Status | 1 Stunde (Cache) | AD-Domain, Domain-Controller-Status |
| Produkt-Typ | 1 Stunde (Cache) | Server / Domain Controller / Workstation |
Warum unterschiedliche Intervalle?
Windows-Daten werden gestaffelt erfasst, um PowerShell- und WMI-Abfragen nicht zu haeufen. Schnell aenderbare Daten (Benutzer, Services) werden oefter aktualisiert als selten aenderbare (Hardware, Software).
Reaktionszeiten
| Ereignis | Reaktionszeit |
|---|---|
| Host geht offline | Max. 60 Sekunden (2x Heartbeat-Intervall) |
| Neuer Task | Max. 30 Sekunden (naechster Task-Poll) |
| Agent-Update verfuegbar | Max. 5 Minuten (naechster Auto-Update-Check) |
| Verbindungsabbruch erkannt | Max. 35 Sekunden (25s Ping + 10s Timeout) |
| Reconnect nach Ausfall | 1-30 Sekunden (exponentielles Backoff) |
| Script-Ausfuehrung | Sofort (ueber WebSocket-Nachricht) |
| Shell-Verbindung | Sofort (ueber WebSocket-Nachricht) |
Plattformen
| Plattform | Binary | Besonderheiten |
|---|---|---|
| Linux (amd64) | datazone-agent-linux-amd64 | Systemd-Service |
| Linux (arm64) | datazone-agent-linux-arm64 | Fuer ARM-Server (Raspberry Pi, etc.) |
| Windows (amd64) | datazone-agent-windows-amd64.exe | Windows-Dienst |
| macOS (Apple Silicon / Intel) | datazone-agent-darwin-arm64 / -amd64 | launchd-Dienst de.datazone.agent, signiert + notarisiert |
| FreeBSD (amd64) | datazone-agent-freebsd-amd64 | OPNsense-kompatibel |
Ressourcenverbrauch
| Ressource | Typischer Wert |
|---|---|
| RAM | 10-20 MB |
| CPU | < 1% (im Leerlauf) |
| Netzwerk | ~1 KB/s (Heartbeat) |
| Speicher | < 20 MB |
Konfiguration
Die Agent-Konfiguration wird in einer JSON-Datei gespeichert:
Linux / FreeBSD
/etc/datazone/agent.jsonWindows
C:\ProgramData\DATAZONE\agent.jsonKonfigurationsparameter
{
"server_url": "wss://control.ihredomain.de",
"token": "onboarding-token-hier",
"host_type": "linux",
"hostname": "web01"
}| Parameter | Beschreibung |
|---|---|
server_url | WebSocket-URL des Backends |
token | Onboarding-Token fuer die Registrierung |
host_type | Systemtyp (linux, windows, pve, pbs, opnsense) |
hostname | Anzeigename (optional, wird automatisch ermittelt) |
Task-Ausfuehrung
Der Agent empfaengt Tasks vom Backend und fuehrt diese aus:
| Task-Typ | Timeout | Beschreibung |
|---|---|---|
| Script | 5 Minuten (Standard) | Konfigurierbarer Timeout pro Script |
| Update | 30 Minuten | System-Update (apt/dnf/pkg/Windows Update) |
| Reboot | - | Sofortiger Neustart mit 2s Verzoegerung |
| Agent-Update | - | Selbst-Aktualisierung des Agent-Binaries |
Bei fehlgeschlagener Task-Ergebnis-Uebermittlung wird bis zu 3x mit exponentiellem Backoff (2s, 4s) wiederholt.
Naechste Schritte
- Agent-Installation - Schritt-fuer-Schritt-Anleitung
- Fehlerbehebung - Haeufige Probleme loesen