Troubleshooting & Installing Beszel Agent (Synology NAS)

Target Systems: Synology DS1522+ (and other DSM 7.x+ models)
Method: DSM Task Scheduler (Root execution)
Primary Port: 45876

1. Overview

On Synology DSM, the Beszel Agent runs as a background binary. Unlike standard Linux distributions, DSM does not use systemd. Troubleshooting requires manually clearing orphaned processes and ensuring the Task Scheduler correctly detaches the binary from the shell using nohup.

2. Phase 1: The "Order 66" (Process Cleanup)

If the agent appears "Offline" in the Hub but logs show the SSH server started, a previous instance is likely "ghosting" in the background and hogging the port. You must kill it before a new configuration or key can take effect.

• Create a new "User-defined script" in Task Scheduler.
• Set the user to root.
• Use the following command to clear the port:

  killall -9 beszel-agent

• Run the task once, then delete it.

3. Phase 2: Key Verification

When migrating the Hub to a new server, the Public Key will change. You must use the exact string provided by your Beszel Hub UI. Using an incorrect or placeholder key will result in a "failed to parse key" error. Ensure the key is valid base64 data to avoid "illegal base64 data" initialization failures[cite: 5].

4. Phase 3: The "Pave" (Clean Reinstall)

Update your primary BeszelAgent task with the following script. It uses export for clean variable handling and nohup to prevent DSM from killing the process when the task finishes.

# 1. Set environment variables
export PORT=45876
export KEY="<YOUR_HUB_PUBLIC_KEY_HERE>"

# 2. Start agent with nohup to ensure it stays alive
# Note: Use '>' to wipe the log for testing, '>>' to append for long-term use
nohup /volume1/homes/admin/beszel-agent >> /volume1/homes/admin/beszel.log 2>&1 &

5. Phase 4: Security & Firewall

• SSH Status: Synology's native SSH (Port 22) does not need to be enabled. Beszel manages its own internal SSH server.
• Firewall: If the DSM Firewall is active, create an Allow rule for TCP Port 45876.

6. Troubleshooting via Logs

View the log file at /volume1/homes/admin/beszel.log to diagnose issues:

• Data Directory: The agent default data path is /var/lib/beszel-agent[cite: 1].
• "illegal base64 data": The Public Key is malformed or contains placeholder text[cite: 5].
• "ssh: no key found": The KEY variable was not set correctly or used placeholder text.
• "HUB_URL environment variable not set": This is a normal warning when using the SSH "Pull" method instead of the "Push" method[cite: 3].
• "Docker outdated": A common informational warning on Synology due to DSM's slower update cycle for the Container Manager[cite: 2].
• "Unknown method 'ListUnitsByPatterns'": This error can be ignored; it occurs because Synology does not use systemd.

Note: To preserve NVMe SSD longevity on micro PCs, the log output is redirected to the main volume to minimize unnecessary write cycles on the system partition.