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

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

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

2. WebSocket connection?

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

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

  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:

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

Logs

Important Log Files

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