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

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

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

Windows

C:\ProgramData\DATAZONE\agent.json

Konfigurationsparameter

json

{
  "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

Agent - Uebersicht ​

Funktionen ​

Architektur ​

Kommunikation ​

Reconnect-Verhalten ​

Heartbeat-Intervalle und Datensammlung ​

Timing-Uebersicht ​

Heartbeat-Daten (alle Plattformen) ​

Plattform-spezifische Daten ​

Linux / PVE / PBS ​

OPNsense ​

Windows ​

Reaktionszeiten ​

Plattformen ​

Ressourcenverbrauch ​

Konfiguration ​

Linux / FreeBSD ​

Windows ​

Konfigurationsparameter ​

Task-Ausfuehrung ​

Naechste Schritte ​

Agent - Uebersicht

Funktionen

Architektur

Kommunikation

Reconnect-Verhalten

Heartbeat-Intervalle und Datensammlung

Timing-Uebersicht

Heartbeat-Daten (alle Plattformen)

Plattform-spezifische Daten

Linux / PVE / PBS

OPNsense

Windows

Reaktionszeiten

Plattformen

Ressourcenverbrauch

Konfiguration

Linux / FreeBSD

Windows

Konfigurationsparameter

Task-Ausfuehrung

Naechste Schritte