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:
# Check service status
systemctl status datazone-agent
# View logs
journalctl -u datazone-agent -n 50 --no-pager
# Check configuration
cat /etc/datazone/agent.jsonCommon Causes:
- Invalid JSON configuration (missing commas, incorrect quotes)
- Incorrect
server_urlvalue - Binary not executable (forgot
chmod +x)
Windows
Symptom: The "DATAZONE Control Agent" service does not start.
Diagnosis:
# 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:
Is the agent running?
bash# Linux systemctl is-active datazone-agent # Windows Get-Service datazone-agent | Select StatusWebSocket 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"Is the token valid?
- Verify that the token in the configuration is correct
- Generate a new token if necessary
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_urlin 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
# 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# 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-agentLogs
Important Log Files
| Platform | Log Path |
|---|---|
| Linux | journalctl -u datazone-agent |
| Windows | C:\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):
{
"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-upgradecould 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.jsonis 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, PVEpveversionand PBSproxmox-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.