Skip to content

Troubleshooting ​

Common issues with the DATAZONE Control Agent and their solutions.

Agent Does Not Start ​

Linux ​

Symptom: The agent service does not start or stops immediately.

Diagnosis:

bash
# Check service status
systemctl status datazone-agent

# View logs
journalctl -u datazone-agent -n 50 --no-pager

# Check configuration
cat /etc/datazone/agent.json

Common Causes:

  • Invalid JSON configuration (missing commas, incorrect quotes)
  • Incorrect server_url value
  • Binary not executable (forgot chmod +x)

Windows ​

Symptom: The "DATAZONE Control Agent" service does not start.

Diagnosis:

powershell
# Check service status
Get-Service datazone-agent

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

# Check configuration
Get-Content "C:\ProgramData\DATAZONE\agent.json"

Common Causes:

  • Agent binary is missing or corrupted
  • Configuration file does not exist
  • Service not properly registered

Host Does Not Appear in the Dashboard ​

Symptom: After agent installation, the host does not appear in the frontend.

Checkpoints:

  1. Is the agent running?

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

    bash
    # Linux: Check if connection exists
    ss -tnp | grep datazone
    
    # Check agent log for connection errors
    journalctl -u datazone-agent | grep -i "error\|connect"
  3. Is the token valid?

    • Verify that the token in the configuration is correct
    • Generate a new token if necessary
  4. Is the network reachable?

    bash
    # Test connection to the backend
    curl -v https://control.yourdomain.com/api/health

Connection Issues ​

WebSocket Connection Fails ​

Symptom: Agent log shows WebSocket connection failed or dial error.

Solutions:

  • Check the server_url in the configuration
  • Ensure the port is reachable
  • For HTTPS: Verify the SSL certificate
  • Check firewall rules (outbound port 443 or 8080)

Agent Keeps Going Offline ​

Symptom: Host constantly switches between online and offline.

Possible Causes:

  • Unstable network connection
  • Firewall terminating long-lived WebSocket connections (timeout)
  • Proxy server with short timeouts

Solutions:

  • Check network stability
  • Increase WebSocket timeout in the reverse proxy:
    nginx
    proxy_read_timeout 86400;
    proxy_send_timeout 86400;

Shell Issues ​

Shell Does Not Respond ​

Symptom: The remote shell shows no output or does not respond.

Solutions:

  • Check the agent connection (is the host online?)
  • Check the browser console for errors
  • Check the WebSocket connection in the browser network tab
  • Restart the agent

Incorrect Character Encoding ​

Symptom: Umlauts or special characters are displayed incorrectly.

Solution:

  • Check the locale settings on the host:
    bash
    locale
  • Set UTF-8 as the default

Tunnel Issues ​

Tunnel Does Not Start ​

Symptom: "Tunnel could not be created" error message.

Checkpoints:

  • Is the agent online?
  • Is the tunnel port range (20000-25000) available on the backend server?
  • Has the maximum number of concurrent tunnels been reached?

Connection via Tunnel Fails ​

Symptom: Tunnel is active, but the connection does not work.

Checkpoints:

  • Is the target service running on the host? (e.g., SSH server, RDP)
  • Is the correct port configured?
  • Is a local firewall on the host blocking access?

Updating the Agent ​

Manual Update ​

bash
# Linux
systemctl stop datazone-agent
wget -O /usr/local/bin/datazone-agent https://control.yourdomain.com/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.yourdomain.com/static/agent/datazone-agent-windows-amd64.exe" -OutFile "C:\Program Files\DATAZONE\Agent\datazone-agent.exe"
Start-Service datazone-agent

Logs ​

Important Log Files ​

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

Increasing the Log Level ​

For more detailed logs, you can enable debug mode (temporarily for troubleshooting):

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

Restart the agent afterward.

Note

Disable debug mode after troubleshooting, as it causes log files to grow rapidly.

Agent behaviour since v3.14.2 ​

  • Duplicate delivery of a task (WebSocket push and poll at the same time) is detected; a task runs once per agent. The backend also claims tasks atomically and puts reboot/agent-update tasks at the end of a batch.
  • Agent update and auto-update wait until no other task is running (before, a running apt full-upgrade could be cut off).
  • Cached results (pending_result.json, mode 0600) are sent on the regular task poll too, not only on a WebSocket reconnect; results finally rejected by the backend (HTTP 4xx) are dropped.
  • Script tasks report the exit code also on failure; temporary script files have random names and mode 0600; a timeout no longer blocks the task when child processes keep running.
  • Shell input is no longer logged (before, keystrokes including passwords ended up in the agent log).
  • Heartbeats no longer overlap; the first heartbeat after registration does not block the connection.
  • agent.json is set to 0600 on save; a proxy without a port uses 80/443.
  • OPNsense: the report before the reboot is no longer blocked by shutdown, the final result is on disk before the reboot, and a non-answering configd counts as unknown maintenance state (see OPNsense HA Updates).

Agent behaviour since v3.75.2 ​

Connectivity comes before data: a hanging command on the machine must no longer silence the agent (trigger: unbound-control hung for 8 hours on an OPNsense, the host was offline and without tunnel/shell all that time).

  • Keepalive: if data collection hangs for more than 45 seconds, the agent sends the last successfully sent state with fresh metrics instead. The host stays online, tunnels, shell and tasks keep working. The agent log shows Heartbeat collection hangs for …s in <collector>, the backend log [HB-STUCK] with host and collector (at most once per hour and host).
  • Timeouts: every command used for data collection has a fixed timeout (mostly 20–30 seconds), including OPNsense configctl, pluginctl, unbound-control, ipsec/swanctl, PVE pveversion and PBS proxmox-backup-client.
  • Without live connection: if the WebSocket cannot be established, the agent sends its heartbeat via HTTP and fetches tasks every 5 minutes.
  • Hanging tasks: if all running tasks have been busy for more than 10 minutes, an extra lane (at most 3) picks up the next tasks, e.g. a reboot or a repair script. Docker, service, VM, snapshot, PBS and software actions have their own timeouts. A task running longer than 4 hours 15 minutes no longer blocks agent updates or auto-update.
  • Agent updates on slow links: the download is only aborted after 2 minutes without data (previously 30 seconds in total).
  • Windows: the first data collection after start delays the connection by at most 60 seconds.

DATAZONE Control Documentation