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

# 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?

   # Linux
   systemctl is-active datazone-agent
   
   # Windows
   Get-Service datazone-agent | Select Status

2. WebSocket-Verbindung?

   # 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?

   # 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:

  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:

  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-agent

Logs

Wichtige Log-Dateien

Plattform	Log-Pfad
Linux	journalctl -u datazone-agent
Windows	C:\ProgramData\DATAZONE\logs\agent.log
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.