# DSM

# 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 &amp; 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.*