Monitoring qBittorrent with Vigilmon

qBittorrent is the go-to open-source BitTorrent client for homelabbers running automated media pipelines alongside Sonarr, Radarr, and Lidarr. Its built-in Web UI lets you manage torrents from any browser — but when the Web UI goes down, your entire download automation stack stalls silently. Vigilmon gives you HTTP uptime checks, API health probes, SSL certificate alerts, and heartbeat monitoring to catch qBittorrent failures before they pile up into a backlog of missed downloads.

What You'll Set Up

• HTTP monitor for the qBittorrent Web UI (port 8080)
• API health check via the unauthenticated version endpoint
• SSL certificate expiry alerts for reverse-proxied HTTPS deployments
• Heartbeat monitor for qBittorrent active torrent and DHT connectivity health

Prerequisites

• qBittorrent installed with the Web UI enabled (Tools → Options → Web UI)
• qBittorrent Web UI accessible on port 8080 (or your configured port)
• Web UI credentials set (default admin / adminadmin — change these)
• A free Vigilmon account

Step 1: Monitor the qBittorrent Web UI

The qBittorrent Web UI is served by the built-in C++ HTTP server on port 8080. A GET / returning HTTP 200 confirms the server process is alive and the Web UI is reachable.

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter your qBittorrent Web UI URL: http://your-server:8080/
4. Set Check interval to 1 minute.
5. Set Expected HTTP status to 200.
6. Under Keyword check, enter qBittorrent to confirm the login page body is present.
7. Click Save.

This catches the qBittorrent process crashing, the port becoming unreachable, or the server running out of file descriptors under heavy torrent load.

Step 2: Monitor the qBittorrent API Health

qBittorrent's REST API lives at /api/v2/. The version endpoint returns the qBittorrent version string without requiring authentication — making it a clean, lightweight liveness probe for the API layer:

GET http://your-server:8080/api/v2/app/version
Header: X-Requested-With: XMLHttpRequest

Expected response:

v5.0.4

The X-Requested-With: XMLHttpRequest header is required — qBittorrent's CSRF protection rejects requests without it.

Add this monitor in Vigilmon:

1. Click Add Monitor → HTTP / HTTPS.
2. URL: http://your-server:8080/api/v2/app/version
3. Custom request header: X-Requested-With: XMLHttpRequest
4. Expected status: 200.
5. Keyword check: v — the response always starts with v followed by the version number.
6. Check interval: 2 minutes.
7. Click Save.

A failure here means the qBittorrent API layer is not responding even though the Web UI process may still be accepting connections — a common state after an out-of-memory kill of the API worker thread.

Step 3: Monitor Transfer Status (Authenticated API)

For deeper health monitoring, the transfer info endpoint returns current download/upload speeds and DHT connectivity:

GET http://your-server:8080/api/v2/transfer/info
Cookie: SID=your-session-id

Expected response fields to watch:

{
  "dl_info_speed": 2457600,
  "up_info_speed": 512000,
  "connection_status": "connected"
}

The connection_status field returns connected, firewalled, or disconnected. A firewalled or disconnected status indicates the qBittorrent listening port is blocked — your torrents will stall waiting for peer connections.

To use this endpoint with Vigilmon, create a session first by logging in via the API:

curl -s -c cookies.txt -X POST \
  http://your-server:8080/api/v2/auth/login \
  -d "username=admin&password=your-password"

Then monitor the transfer info endpoint using the session cookie value as a static header in Vigilmon:

1. Click Add Monitor → HTTP / HTTPS.
2. URL: http://your-server:8080/api/v2/transfer/info
3. Custom request header: Cookie: SID=your-sid-value
4. Expected status: 200.
5. Keyword check: connection_status — confirms valid JSON returned.
6. Check interval: 5 minutes.
7. Click Save.

Step 4: SSL Certificate Alerts for HTTPS qBittorrent Deployments

qBittorrent does not natively support HTTPS — when you expose the Web UI securely you run it behind a reverse proxy (nginx, Caddy, or Traefik) that terminates SSL. Monitor the certificate on your proxy domain so a Let's Encrypt renewal failure doesn't silently break the HTTPS Web UI.

Enable SSL monitoring on each HTTPS monitor you created:

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

If you use Caddy as the reverse proxy, it auto-renews certificates. Verify the Caddy config includes the correct domain:

qbittorrent.yourdomain.com {
    reverse_proxy localhost:8080
}

A 21-day alert window gives Certbot or Caddy three renewal cycles before the certificate actually expires.

Step 5: Heartbeat Monitoring for Active Torrent Health

A running qBittorrent daemon can have a healthy Web UI and API while actually doing nothing — DHT blocked at the firewall, the listening port closed by a system update, or all torrents paused after an unexpected restart. Use a scheduled heartbeat that checks the active torrent list to detect this silent failure mode.

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 qBittorrent server:

crontab -e

*/30 * * * * curl -s -c /tmp/qbt_cookies.txt -X POST \
  http://localhost:8080/api/v2/auth/login \
  -d "username=admin&password=your-password" > /dev/null && \
  curl -s -b /tmp/qbt_cookies.txt \
  "http://localhost:8080/api/v2/torrents/info?filter=active" | \
  grep -q '"hash"' && \
  curl -s https://vigilmon.online/heartbeat/abc123

This script logs in, queries the active torrent list, and only pings the Vigilmon heartbeat if at least one active torrent is found. If qBittorrent is running but DHT is blocked or all torrents have stalled, the heartbeat goes silent and Vigilmon alerts after the interval passes.

During expected idle periods (no active downloads), adjust the cron to probe connection_status from the transfer endpoint instead:

*/30 * * * * curl -s -c /tmp/qbt_cookies.txt -X POST \
  http://localhost:8080/api/v2/auth/login \
  -d "username=admin&password=your-password" > /dev/null && \
  curl -s -b /tmp/qbt_cookies.txt \
  "http://localhost:8080/api/v2/transfer/info" | \
  grep -q '"connected"' && \
  curl -s https://vigilmon.online/heartbeat/abc123

Step 6: Configure Alert Channels

1. Go to Alert Channels in Vigilmon and add email, Slack, Discord, or a webhook.
2. Set Consecutive failures before alert to 2 on the Web UI monitor — a single slow response during a heavy torrent hash-check won't page you unnecessarily.
3. Set Consecutive failures to 1 on the API version monitor — if the API stops responding, the entire automation pipeline (Sonarr/Radarr category management, download completion callbacks) breaks immediately.

Summary

| Monitor | URL / Check | What It Catches | |---|---|---| | Web UI | http://your-server:8080/ | qBittorrent process crash, port unreachable | | API version | /api/v2/app/version | API layer failure, CSRF misconfiguration | | Transfer info | /api/v2/transfer/info | DHT blocked, port firewalled | | SSL certificate | Your reverse-proxy domain | Let's Encrypt renewal failure | | Cron heartbeat | Active torrent list | Silent stall, DHT disconnect, all torrents paused |

qBittorrent running headlessly on a homelab server can fail silently for days without anyone noticing — especially when the Web UI appears reachable but the download engine has stalled. With Vigilmon watching the UI, API, transfer status, SSL certificate, and active download health, you get the observability to keep your media pipeline running without manual babysitting.