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:
# Service-Status pruefen
systemctl status datazone-agent
# Logs anzeigen
journalctl -u datazone-agent -n 50 --no-pager
# Konfiguration pruefen
cat /etc/datazone/agent.jsonHaeufige Ursachen:
- Ungueltige JSON-Konfiguration (fehlende Kommas, falsche Anfuehrungszeichen)
- Falscher
server_url-Wert - Binary nicht ausfuehrbar (
chmod +xvergessen)
Windows
Symptom: Der Dienst "DATAZONE Control Agent" startet nicht.
Diagnose:
# 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:
Agent laeuft?
bash# Linux systemctl is-active datazone-agent # Windows Get-Service datazone-agent | Select StatusWebSocket-Verbindung?
bash# Linux: Pruefen ob Verbindung besteht ss -tnp | grep datazone # Agent-Log auf Verbindungsfehler pruefen journalctl -u datazone-agent | grep -i "error\|connect"Token gueltig?
- Pruefen Sie, ob das Token in der Konfiguration korrekt ist
- Generieren Sie bei Bedarf ein neues Token
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_urlin 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
# 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# 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-agentLogs
Wichtige Log-Dateien
| Plattform | Log-Pfad |
|---|---|
| Linux | journalctl -u datazone-agent |
| Windows | C:\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):
{
"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-upgradeabgebrochen 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.jsonwird beim Speichern auf 0600 gesetzt; ein Proxy ohne Port nutzt 80/443.- OPNsense: der Report vor dem Reboot wird nicht mehr durch
shutdownblockiert, 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, PVEpveversionund PBSproxmox-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.