tutorial

Monitoring NZBGet with Vigilmon

NZBGet is the C++ Usenet downloader built for low-resource environments — here's how to monitor its web UI, JSON-RPC API, download queue, and completion health with Vigilmon for NAS, Raspberry Pi, and ARM homelab setups.

NZBGet is the Usenet downloader of choice for resource-constrained homelab environments — a C++ binary that downloads NZBs with a fraction of the memory footprint of Python-based alternatives. When you're running NZBGet on a Raspberry Pi, a low-RAM NAS, or an ARM server alongside Sonarr and Radarr, a silent failure has real consequences: the download queue stalls, automated media acquisition stops, and there's no obvious error message to find. Vigilmon gives you web UI uptime checks, JSON-RPC API health probes, and a download queue heartbeat to catch NZBGet failures in your most constrained environments.

What You'll Set Up

  • HTTP monitor for the NZBGet web UI (port 6789)
  • JSON-RPC API health check via the status method
  • Download queue and completion status monitoring
  • SSL certificate expiry alerts for reverse-proxied HTTPS deployments
  • Heartbeat monitor for NZBGet download queue and completion health

Prerequisites

  • NZBGet installed and accessible on port 6789 (or your configured port)
  • NZBGet web UI credentials (set in Settings → Security → ControlUsername / ControlPassword)
  • At least one Usenet news server configured in Settings → News-Servers
  • A free Vigilmon account

Step 1: Monitor the NZBGet Web UI

NZBGet serves its web interface from a built-in C++ HTTP server on port 6789. A GET / returning HTTP 200 confirms the NZBGet process is running and the web interface is reachable.

  1. Log in to vigilmon.online and click Add Monitor.
  2. Set Type to HTTP / HTTPS.
  3. Enter your NZBGet URL: http://your-server:6789/
  4. Set Check interval to 1 minute.
  5. Set Expected HTTP status to 200.
  6. Under Keyword check, enter NZBGet to confirm you're receiving the NZBGet interface, not a default page from another service.
  7. Click Save.

On ARM devices and NAS units, NZBGet can be killed by the OS OOM killer during heavy par2 repair operations. This HTTP check catches those crashes immediately.

Step 2: Monitor the NZBGet JSON-RPC API

NZBGet exposes a JSON-RPC API at /jsonrpc. The status method is the primary health check — it returns current download speed, queue size, server pause state, and article cache statistics, all in a single call. It requires HTTP Basic Auth with your NZBGet credentials:

POST http://your-server:6789/jsonrpc
Authorization: Basic base64(username:password)
Content-Type: application/json

{"version": "1.1", "method": "status", "id": 1}

Expected response excerpt:

{
  "result": {
    "downloadSpeed": 15728640,
    "remainingSize": 2048,
    "serverPaused": false,
    "articleCache": 104857600,
    "downloadLimit": 0
  }
}

Add this monitor in Vigilmon:

  1. Click Add Monitor → HTTP / HTTPS.

  2. URL: http://your-server:6789/jsonrpc

  3. Method: POST

  4. Request body: {"version": "1.1", "method": "status", "id": 1}

  5. Request headers:

    • Content-Type: application/json
    • Authorization: Basic YOUR_BASE64_CREDENTIALS

    Generate the Base64 credential string:

    echo -n "username:password" | base64

  6. Expected status: 200.

  7. Keyword check: downloadSpeed — confirms the status response is complete and the download engine is running.

  8. Check interval: 2 minutes.

  9. Click Save.

A failure here — while the web UI is still reachable — indicates the download engine thread has stalled, which happens occasionally on NAS devices with slow storage.

Step 3: Monitor Usenet Server Connectivity via Status

The status JSON-RPC response includes a serverStats array with per-server download statistics. Non-zero bytesSum values confirm that at least one Usenet server is actively transferring articles. If all servers show zero bytes downloaded over an extended period during expected activity, it indicates a connectivity failure.

For a simpler connectivity check, monitor the serverPaused field from the same status endpoint. NZBGet auto-pauses downloads when it encounters repeated Usenet server errors (authentication failures, connection resets, or DNS failures) — a serverPaused: true response during expected download hours warrants investigation.

Add a dedicated connectivity check:

  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: http://your-server:6789/jsonrpc
  3. Method: POST
  4. Request body: {"version": "1.1", "method": "status", "id": 2}
  5. Same auth headers as above.
  6. Expected status: 200.
  7. Keyword check: serverStats — confirms the server statistics array is present in the response.
  8. Check interval: 5 minutes.
  9. Click Save.

Step 4: SSL Certificate Alerts for HTTPS NZBGet Deployments

NZBGet does not support HTTPS natively — production homelab deployments run it behind a reverse proxy. Monitor the SSL certificate on your proxy domain so a Let's Encrypt renewal failure doesn't silently break remote access.

Enable SSL monitoring:

  1. Open the HTTPS monitor for https://nzbget.yourdomain.com/.
  2. Enable Monitor SSL certificate.
  3. Set Alert when certificate expires in less than 21 days.
  4. Click Save.

A sample Caddy configuration for NZBGet (Caddy auto-manages Let's Encrypt renewal):

nzbget.yourdomain.com {
    reverse_proxy localhost:6789
    basicauth /* {
        # Optional: add an extra auth layer in front of NZBGet
    }
}

For nginx:

server {
    listen 443 ssl;
    server_name nzbget.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/nzbget.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/nzbget.yourdomain.com/privkey.pem;

    location / {
        proxy_pass http://localhost:6789;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Step 5: Heartbeat Monitoring for Download Queue Health

A scheduled heartbeat that calls both listgroups (active queue) and history (recent completions) gives you a complete picture of whether NZBGet is actively processing downloads and whether completions are succeeding.

  1. In Vigilmon, click Add Monitor → Cron Heartbeat.
  2. Set Expected ping interval to 30 minutes.
  3. Copy the heartbeat URL (e.g. https://vigilmon.online/heartbeat/abc123).
  4. Add a cron job on your NZBGet server:
crontab -e

*/30 * * * * AUTH="$(echo -n 'username:password' | base64)" && \
  HISTORY=$(curl -s -X POST http://localhost:6789/jsonrpc \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $AUTH" \
  -d '{"version":"1.1","method":"history","id":1}') && \
  FAILED=$(echo "$HISTORY" | python3 -c \
  "import sys,json; h=json.load(sys.stdin)['result']; \
   recent=h[:5]; print(sum(1 for s in recent if s.get('Status','').startswith('FAILURE')))") && \
  [ "$FAILED" -lt 3 ] && \
  STATUS=$(curl -s -X POST http://localhost:6789/jsonrpc \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $AUTH" \
  -d '{"version":"1.1","method":"status","id":2}') && \
  echo "$STATUS" | grep -q '"serverPaused": *false' && \
  curl -s https://vigilmon.online/heartbeat/abc123

This script:

  1. Fetches the last 5 completed NZB items from the history API
  2. Counts items with a FAILURE status (covers FAILURE/PAR_FAILURE, FAILURE/UNPACK_FAILURE, FAILURE/MOVE_FAILURE)
  3. Checks that NZBGet is not paused due to server errors
  4. Only pings the Vigilmon heartbeat if both conditions pass

If the NZBGet process is killed by the OOM killer (common on 512 MB RAM NAS devices during par2), the API call fails and the heartbeat stops. If post-processing is consistently failing, the failure count exceeds the threshold.

To inspect history manually and check recent statuses:

curl -s -u username:password \
  -X POST http://localhost:6789/jsonrpc \
  -H "Content-Type: application/json" \
  -d '{"version":"1.1","method":"history","id":1}' | \
  python3 -c "import sys,json; [print(s['NZBName'], s['Status']) for s in json.load(sys.stdin)['result'][:10]]"

Step 6: Configure Alert Channels

  1. Go to Alert Channels in Vigilmon and add email, Slack, or a webhook.
  2. Set Consecutive failures before alert to 2 on the web UI HTTP monitor — a momentary spike during par2 repair on slow storage can cause a single timeout.
  3. Set Consecutive failures to 1 on the JSON-RPC status monitor — if the download engine is stalled, Sonarr and Radarr completions stop arriving immediately.

Summary

| Monitor | URL / Check | What It Catches | |---|---|---| | Web UI | http://your-server:6789/ | NZBGet OOM kill, process crash | | JSON-RPC status | POST /jsonrpc (status) | Download engine stall, API failure | | Server stats | POST /jsonrpc (status.serverStats) | Usenet server connectivity loss | | SSL certificate | Your reverse-proxy domain | Let's Encrypt renewal failure | | Cron heartbeat | history + status methods | Par2 failures, unrar errors, server auto-pause |

NZBGet's lightweight C++ design makes it ideal for resource-constrained homelab hardware — but that same hardware is the most likely to OOM-kill the process during heavy operations or lose connectivity silently. With Vigilmon monitoring the web UI, JSON-RPC API, server statistics, SSL certificate, and download completion health, you have full observability into your NZBGet deployment without adding any measurable overhead to the host.

Monitor your app with Vigilmon

Free plan — 5 monitors, no credit card required. Up and running in 60 seconds.

Start free →
← Back to all articles