Skip to content

Fehlerbehebung ​

Haeufige Probleme mit dem DATAZONE Control Agent und deren Loesungen.

Agent startet nicht ​

Linux ​

Symptom: Der Agent-Service startet nicht oder stoppt sofort.

Diagnose:

bash
# Service-Status pruefen
systemctl status datazone-agent

# Logs anzeigen
journalctl -u datazone-agent -n 50 --no-pager

# Konfiguration pruefen
cat /etc/datazone/agent.json

Haeufige Ursachen:

  • Ungueltige JSON-Konfiguration (fehlende Kommas, falsche Anfuehrungszeichen)
  • Falscher server_url-Wert
  • Binary nicht ausfuehrbar (chmod +x vergessen)

Windows ​

Symptom: Der Dienst "DATAZONE Control Agent" startet nicht.

Diagnose:

powershell
# Service-Status pruefen
Get-Service datazone-agent

# Logs anzeigen
Get-Content "C:\ProgramData\DATAZONE\logs\agent.log" -Tail 50

# Konfiguration pruefen
Get-Content "C:\ProgramData\DATAZONE\agent.json"

Haeufige Ursachen:

  • Agent-Binary fehlt oder ist beschaedigt
  • Konfigurationsdatei nicht vorhanden
  • Dienst nicht korrekt registriert

Host erscheint nicht im Dashboard ​

Symptom: Nach der Agent-Installation erscheint der Host nicht im Frontend.

Pruefpunkte:

  1. Agent laeuft?

    bash
    # Linux
    systemctl is-active datazone-agent
    
    # Windows
    Get-Service datazone-agent | Select Status
  2. WebSocket-Verbindung?

    bash
    # Linux: Pruefen ob Verbindung besteht
    ss -tnp | grep datazone
    
    # Agent-Log auf Verbindungsfehler pruefen
    journalctl -u datazone-agent | grep -i "error\|connect"
  3. Token gueltig?

    • Pruefen Sie, ob das Token in der Konfiguration korrekt ist
    • Generieren Sie bei Bedarf ein neues Token
  4. Netzwerk erreichbar?

    bash
    # Verbindung zum Backend testen
    curl -v https://control.ihredomain.de/api/health

Verbindungsprobleme ​

WebSocket-Verbindung schlaegt fehl ​

Symptom: Agent-Log zeigt WebSocket connection failed oder dial error.

Loesungen:

  • Pruefen Sie die server_url in der Konfiguration
  • Stellen Sie sicher, dass der Port erreichbar ist
  • Bei HTTPS: SSL-Zertifikat pruefen
  • Firewall-Regeln pruefen (ausgehend Port 443 oder 8080)

Agent geht immer wieder offline ​

Symptom: Host wechselt staendig zwischen Online und Offline.

Moegliche Ursachen:

  • Instabile Netzwerkverbindung
  • Firewall unterbricht langlebige WebSocket-Verbindungen (Timeout)
  • Proxy-Server mit kurzen Timeouts

Loesungen:

  • Netzwerkstabilitaet pruefen
  • WebSocket-Timeout im Reverse Proxy erhoehen:
    nginx
    proxy_read_timeout 86400;
    proxy_send_timeout 86400;

Shell-Probleme ​

Shell reagiert nicht ​

Symptom: Die Remote-Shell zeigt keine Ausgabe oder reagiert nicht.

Loesungen:

  • Agent-Verbindung pruefen (ist der Host online?)
  • Browser-Konsole auf Fehler pruefen
  • WebSocket-Verbindung im Browser-Netzwerk-Tab pruefen
  • Agent neustarten

Zeichencodierung fehlerhaft ​

Symptom: Umlaute oder Sonderzeichen werden falsch dargestellt.

Loesung:

  • Pruefen Sie die Locale-Einstellungen auf dem Host:
    bash
    locale
  • Setzen Sie UTF-8 als Standard

Tunnel-Probleme ​

Tunnel startet nicht ​

Symptom: "Tunnel konnte nicht erstellt werden" Fehlermeldung.

Pruefpunkte:

  • Agent online?
  • Tunnel-Port-Bereich (20000-25000) auf dem Backend-Server verfuegbar?
  • Maximale Anzahl gleichzeitiger Tunnel erreicht?

Verbindung ueber Tunnel schlaegt fehl ​

Symptom: Tunnel ist aktiv, aber Verbindung funktioniert nicht.

Pruefpunkte:

  • Zieldienst laeuft auf dem Host? (z.B. SSH-Server, RDP)
  • Richtiger Port konfiguriert?
  • Lokale Firewall auf dem Host blockiert den Zugriff?

Agent aktualisieren ​

Manuelles Update ​

bash
# Linux
systemctl stop datazone-agent
wget -O /usr/local/bin/datazone-agent https://control.ihredomain.de/static/agent/datazone-agent-linux-amd64
chmod +x /usr/local/bin/datazone-agent
systemctl start datazone-agent
powershell
# Windows
Stop-Service datazone-agent
Invoke-WebRequest -Uri "https://control.ihredomain.de/static/agent/datazone-agent-windows-amd64.exe" -OutFile "C:\Program Files\DATAZONE\Agent\datazone-agent.exe"
Start-Service datazone-agent

Logs ​

Wichtige Log-Dateien ​

PlattformLog-Pfad
Linuxjournalctl -u datazone-agent
WindowsC:\ProgramData\DATAZONE\logs\agent.log
macOS/Library/Logs/DATAZONE/agent.log (Neustart: sudo launchctl kickstart -k system/de.datazone.agent)
OPNsense/var/log/datazone-agent.log

Log-Level erhoehen ​

Fuer detailliertere Logs koennen Sie den Debug-Modus aktivieren (temporaer fuer Fehlersuche):

json
{
  "server_url": "wss://...",
  "token": "...",
  "debug": true
}

Starten Sie den Agent danach neu.

Hinweis

Deaktivieren Sie den Debug-Modus nach der Fehlersuche, da er die Log-Dateien schnell vergroessert.

Verhalten des Agents seit v3.14.2 ​

  • Doppelte Zustellung eines Tasks (WebSocket-Push und Abruf gleichzeitig) wird erkannt; ein Task laeuft pro Agent nur einmal. Das Backend vergibt Tasks ausserdem atomar und reiht Neustart-/Agent- Update-Tasks ans Ende eines Stapels.
  • Agent-Update und Auto-Update warten, bis keine andere Aufgabe mehr laeuft (vorher konnte ein laufendes apt full-upgrade abgebrochen werden).
  • Zwischengespeicherte Ergebnisse (pending_result.json, Rechte 0600) werden auch beim regulaeren Task-Abruf gesendet, nicht nur beim WebSocket-Reconnect; vom Backend endgueltig abgelehnte Ergebnisse (HTTP 4xx) werden verworfen.
  • Script-Tasks melden den Exit-Code auch bei Fehlschlag; temporaere Script-Dateien haben zufaellige Namen und Rechte 0600; ein Timeout blockiert den Task nicht mehr, wenn Kindprozesse weiterlaufen.
  • Shell-Eingaben werden nicht mehr protokolliert (vorher standen Tastendruecke inklusive Passwoertern im Agent-Log).
  • Heartbeats ueberlappen sich nicht mehr; der erste Heartbeat nach der Registrierung blockiert die Verbindung nicht.
  • agent.json wird beim Speichern auf 0600 gesetzt; ein Proxy ohne Port nutzt 80/443.
  • OPNsense: der Report vor dem Reboot wird nicht mehr durch shutdown blockiert, das Endergebnis liegt vor dem Reboot auf der Platte, und ein nicht antwortender configd gilt als unbekannter Maintenance-Zustand (siehe OPNsense HA-Updates).

Verhalten des Agents seit v3.75.2 ​

Erreichbarkeit geht vor Daten: Ein hängender Befehl auf dem Rechner darf den Agent nicht mehr verstummen lassen (Anlass: unbound-control hing auf einer OPNsense 8 Stunden, der Host war so lange offline und ohne Tunnel/Shell).

  • Lebenszeichen: Hängt die Datensammlung länger als 45 Sekunden, schickt der Agent statt des Heartbeats den zuletzt erfolgreich gesendeten Stand mit frischen Messwerten. Der Host bleibt online, Tunnel, Shell und Tasks funktionieren. Im Agent-Log steht Heartbeat collection hangs for …s in <Sammler>, im Backend-Log [HB-STUCK] mit Host und Sammler (höchstens einmal je Stunde und Host).
  • Zeitlimits: Alle Befehle der Datensammlung haben feste Zeitlimits (meist 20–30 Sekunden), auch OPNsense configctl, pluginctl, unbound-control, ipsec/swanctl, PVE pveversion und PBS proxmox-backup-client.
  • Ohne Live-Verbindung: Kommt der WebSocket nicht zustande, sendet der Agent seinen Heartbeat per HTTP und holt alle 5 Minuten Aufgaben ab.
  • Hängende Aufgaben: Laufen alle aktiven Aufgaben länger als 10 Minuten, startet eine zusätzliche Spur (höchstens 3) für die nächsten Aufgaben, z. B. Neustart oder ein Reparatur-Script. Docker-, Dienst-, VM-, Snapshot-, PBS- und Software-Aktionen haben eigene Zeitlimits. Eine Aufgabe, die länger als 4 Stunden 15 Minuten läuft, hält Agent-Update und Auto-Update nicht mehr auf.
  • Agent-Updates auf langsamen Leitungen: Der Download bricht nur noch ab, wenn 2 Minuten lang nichts ankommt (vorher 30 Sekunden Gesamtzeit).
  • Windows: Die erste Datensammlung nach dem Start verzögert die Verbindung höchstens 60 Sekunden.

DATAZONE Control Documentation