Skip to content

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 ​

FunktionBeschreibung
HeartbeatRegelmaessiges Senden von Systemmetriken (CPU, RAM, Disk, Uptime)
System-InformationenSammlung von Hardware-, Software- und Netzwerkdaten
Script-AusfuehrungEmpfangen und Ausfuehren von Scripts vom Backend
Remote ShellWebSocket-basierte Terminal-Session
TunnelPort-Forwarding ueber WebSocket-Verbindung
SSH-ServerEingebetteter SSH-Server fuer Agent-SSH-Tunnel
Auto-UpdateSelbst-Update des Agents auf neue Versionen
Task-VerarbeitungEmpfang 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:

  1. Der Agent baut eine ausgehende WebSocket-Verbindung zum Backend auf
  2. Ueber diese Verbindung werden bidirektional Nachrichten ausgetauscht
  3. 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 ​

OperationIntervallBeschreibung
Heartbeat30 SekundenSendet Metriken und Systemdaten an das Backend
Task-Polling30 SekundenPrueft auf neue Aufgaben vom Backend
WebSocket-Ping25 SekundenErkennt abgebrochene Verbindungen (10s Timeout)
Auto-Update-Check5 MinutenPrueft auf neue Agent-Versionen

Heartbeat-Daten (alle Plattformen) ​

Jeder Heartbeat enthaelt folgende Basisdaten:

FeldBeschreibungErfassung
cpuCPU-Auslastung in ProzentEchtzeit (500ms Messung)
memoryRAM-Auslastung in ProzentEchtzeit
memory_totalGesamter ArbeitsspeicherEchtzeit
diskFestplattenauslastung in ProzentEchtzeit
uptimeBetriebszeit in SekundenEchtzeit
hostnameHostname des SystemsEchtzeit
agent_versionAgent-VersionFest

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 ​

DatentypErfassungsintervallDetails
Hardware-InfoEinmalig beim StartCPU, RAM, Mainboard, BIOS, Seriennummern
Ausstehende UpdatesStuendlich (1h Cache)apt list --upgradable bzw. dnf check-update
Docker-ContainerPro Heartbeat (30s)Name, Image, Status, Ports
SSH-SessionsPro Heartbeat (30s)Benutzer, Quell-IP, Login-Zeit
Cron-JobsPro Heartbeat (30s)System- und Benutzer-Crontabs
Load AveragePro Heartbeat (30s)1/5/15 Minuten Durchschnitt
ServicesPro Heartbeat (30s)Systemd-Dienste mit Status
DisksPro Heartbeat (30s)Partitionen, Mountpoints, Belegung
Netzwerk-InterfacesPro Heartbeat (30s)IPs, MAC, Bytes in/out
Offene PortsPro Heartbeat (30s)Listening TCP/UDP mit Prozess

PVE-spezifisch:

DatentypErfassungsintervallDetails
VMs und ContainerPro Heartbeat (30s)VMID, Name, Status, Ressourcen
StoragesPro Heartbeat (30s)Storage-Pools und Belegung
Backup-Jobs30 Minuten (Cache)Backup-Job-Konfigurationen
Backup-History30 Minuten (Cache)Backup-Ausfuehrungshistorie

PBS-spezifisch:

DatentypErfassungsintervallDetails
DatastoresPro Heartbeat (30s)Datastores und Belegung
BackupsPro Heartbeat (30s)Backup-Liste und -Counts
Sync-JobsPro Heartbeat (30s)Synchronisierungsstatus

OPNsense ​

DatentypErfassungsintervallDetails
Hardware-InfoEinmalig beim StartCPU, RAM, BIOS
InterfacesPro Heartbeat (30s)Interface-Status, IPs, Durchsatz
GatewaysPro Heartbeat (30s)Gateway-Status, Latenz, Paketverlust
VPN-TunnelPro Heartbeat (30s)OpenVPN, IPsec, WireGuard mit Status
RoutenPro Heartbeat (30s)Routing-Tabelle (seit v1.3.0)
Zertifikate6 Stunden (Cache)ACME- und SSL-Zertifikate mit Ablaufdatum (seit v1.3.0)
Unbound DNS StatsPro Heartbeat (30s)DNS-Abfragen, Cache-Hits, Top-Domains (seit v1.3.0)
Nginx Virtual Hosts1 Stunde (Cache)Nginx-Konfigurationen und Server (seit v1.3.0)
ServicesPro Heartbeat (30s)OPNsense-Dienste mit Status
Config-AenderungPro Heartbeat (30s)Letzte config.xml-Aenderung
Externe IPPro 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-StatusPro Heartbeat (30s)Verfuegbare Firmware-Updates

Windows ​

Windows-Daten werden im Hintergrund in verschiedenen Intervallen gesammelt, um die Systembelastung zu minimieren:

DatentypErfassungsintervallDetails
Hardware-Info24 Stunden (Cache)CPU, RAM, Hersteller, Modell
OS-Version/Domain1 Stunde (Cache)Build, Edition, AD-Domain, DC-Status
Windows-Dienste2 Minuten (Cache)Name, Status, Starttyp
Netzwerk-Interfaces2 Minuten (Cache)Adapter, IPs, DNS
Installierte Software5 Minuten (Cache)Via Winget, Name und Version
Geplante Aufgaben5 Minuten (Cache)Scheduled Tasks
Disk-Informationen5 Minuten (Cache)Laufwerke, Groesse, frei
Windows Updates10 Minuten (Cache)Verfuegbare Updates
Angemeldete BenutzerPro Heartbeat (30s)Aktive Sessions
RustDesk-ID/VersionPro Heartbeat (30s)RustDesk-Remote-ID und Version (falls installiert)
Domain/DC-Status1 Stunde (Cache)AD-Domain, Domain-Controller-Status
Produkt-Typ1 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 ​

EreignisReaktionszeit
Host geht offlineMax. 60 Sekunden (2x Heartbeat-Intervall)
Neuer TaskMax. 30 Sekunden (naechster Task-Poll)
Agent-Update verfuegbarMax. 5 Minuten (naechster Auto-Update-Check)
Verbindungsabbruch erkanntMax. 35 Sekunden (25s Ping + 10s Timeout)
Reconnect nach Ausfall1-30 Sekunden (exponentielles Backoff)
Script-AusfuehrungSofort (ueber WebSocket-Nachricht)
Shell-VerbindungSofort (ueber WebSocket-Nachricht)

Plattformen ​

PlattformBinaryBesonderheiten
Linux (amd64)datazone-agent-linux-amd64Systemd-Service
Linux (arm64)datazone-agent-linux-arm64Fuer ARM-Server (Raspberry Pi, etc.)
Windows (amd64)datazone-agent-windows-amd64.exeWindows-Dienst
macOS (Apple Silicon / Intel)datazone-agent-darwin-arm64 / -amd64launchd-Dienst de.datazone.agent, signiert + notarisiert
FreeBSD (amd64)datazone-agent-freebsd-amd64OPNsense-kompatibel

Ressourcenverbrauch ​

RessourceTypischer Wert
RAM10-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.json

Windows ​

C:\ProgramData\DATAZONE\agent.json

Konfigurationsparameter ​

json
{
  "server_url": "wss://control.ihredomain.de",
  "token": "onboarding-token-hier",
  "host_type": "linux",
  "hostname": "web01"
}
ParameterBeschreibung
server_urlWebSocket-URL des Backends
tokenOnboarding-Token fuer die Registrierung
host_typeSystemtyp (linux, windows, pve, pbs, opnsense)
hostnameAnzeigename (optional, wird automatisch ermittelt)

Task-Ausfuehrung ​

Der Agent empfaengt Tasks vom Backend und fuehrt diese aus:

Task-TypTimeoutBeschreibung
Script5 Minuten (Standard)Konfigurierbarer Timeout pro Script
Update30 MinutenSystem-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 ​

DATAZONE Control Documentation