Monitoring Backrest with Vigilmon

Backrest is a modern open-source web UI for BorgBackup management, built in Go and designed for home users and small teams who want BorgBackup's power — deduplication, encryption, incremental backups — without CLI expertise. It provides a clean dashboard for managing repositories, scheduling backup plans, browsing snapshots, and monitoring backup history, all accessible from a browser on port 9898. The challenge: Backrest itself can go down (Docker container restart, OOM kill, resource exhaustion) and backup plans can stall without pushing an alert to anyone. Vigilmon watches the Backrest web UI, its REST API, and every scheduled backup plan through webhook notifications.

What You'll Set Up

• HTTP uptime monitor for the Backrest web UI (port 9898 login page health check)
• REST API availability monitor for /api/v1/config endpoint
• TCP port monitor for Backrest service process health
• Webhook heartbeat integration for Backrest scheduled backup plans
• SSL certificate alerts for HTTPS-proxied Backrest deployments

Prerequisites

• Backrest 0.12+ installed (Docker or binary)
• Backrest accessible on port 9898 (or via HTTPS reverse proxy)
• At least one backup plan configured and scheduled
• A free Vigilmon account

Step 1: HTTP Monitor for the Backrest Web UI

Backrest's web interface is the control plane for all backup operations. If the service goes down, no scheduled plans will run and no snapshots will be available for restore.

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter the Backrest URL: http://your-server:9898 (or your HTTPS proxy URL).
4. Set Check interval to 5 minutes.
5. Set Expected HTTP status to 200.
6. Click Save.

Backrest serves the React login page at / — a 200 response confirms the Go binary is running and the HTTP server is accepting connections. If the container crashes or the port binding is lost, Vigilmon alerts within 5 minutes.

For Docker deployments, verify the port binding is correct:

docker ps | grep backrest
# Should show 0.0.0.0:9898->9898/tcp

Step 2: REST API Monitor for /api/v1/config

Beyond the login page, verify the Backrest API layer is responsive — this is the same endpoint the web UI uses to load your repository configuration. An API failure means the UI may appear to load but all operations will fail.

1. In Vigilmon, click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter: http://your-server:9898/api/v1/config.
4. Set Check interval to 5 minutes.
5. Set Expected HTTP status to 200.
6. Optionally set Expected response body contains to repositories (the JSON key present in a valid config response).
7. Click Save.

The /api/v1/config endpoint returns JSON configuration without requiring authentication for the health check to succeed. A valid response looks like:

{
  "repositories": [...],
  "plans": [...],
  "version": "0.12.0"
}

Monitoring this endpoint verifies that Backrest's configuration database is readable and the API layer is functional, not just that the web server is accepting TCP connections.

Step 3: TCP Port Monitor for Backrest Process Health

A TCP-level check complements the HTTP monitors by detecting network-level failures where the port binding drops even if the process appears running. This catches Docker networking issues and firewall rule changes.

1. In Vigilmon, click Add Monitor.
2. Set Type to TCP Port.
3. Enter your Backrest host: your-server.example.com.
4. Set Port to 9898.
5. Set Check interval to 5 minutes.
6. Click Save.

This monitor is especially useful when Backrest is accessed through an HTTPS reverse proxy — it checks the internal port directly, independently of the proxy, so you can distinguish between proxy failures and Backrest service failures.

Step 4: Webhook Heartbeat for Scheduled Backup Plans

Backrest supports webhook notifications on backup plan completion and failure. This is the primary integration for detecting missed or stalled backup jobs — configure Backrest to POST to a Vigilmon heartbeat URL after each successful backup plan execution.

First, create a Cron Heartbeat in Vigilmon:

1. Click Add Monitor → Cron Heartbeat.
2. Set Expected ping interval to match your backup plan schedule (e.g. 1440 minutes for daily plans).
3. Set Grace period to 120 minutes to allow for large initial backups.
4. Copy the heartbeat URL (e.g. https://vigilmon.online/heartbeat/abc123).

Now configure the webhook in Backrest. In the Backrest web UI:

1. Navigate to Plans and open the backup plan you want to monitor.
2. Scroll to the Hooks section.
3. Add a new hook with Event: CONDITION_SNAPSHOT_SUCCESS.
4. Set Action: ACTION_WEBHOOK.
5. Set URL: https://vigilmon.online/heartbeat/abc123.
6. Set Method: POST.
7. Click Save Plan.

Add a second hook for failure alerting:

1. Add another hook with Event: CONDITION_ANY_ERROR.
2. Set Action: ACTION_WEBHOOK.
3. Set URL: https://vigilmon.online/heartbeat/abc123?status=fail&msg=backrest-plan-failed.
4. Click Save Plan.

With this configuration, Backrest POSTs to Vigilmon after every successful snapshot. If the plan fails, stalls, or Backrest itself goes down, the heartbeat stops and Vigilmon alerts after the grace period.

For multiple backup plans, create a separate Vigilmon heartbeat per plan so failures are isolated by plan name in your alerts.

Step 5: SSL Certificate Alerts for HTTPS-Proxied Backrest

Running Backrest behind an nginx or Caddy HTTPS reverse proxy is the recommended production setup. Add SSL monitoring to catch certificate expiry before it locks users out of the Backrest UI and interrupts webhook delivery.

1. Open the HTTP monitor for your Backrest HTTPS proxy URL (from Step 1 or Step 2, if using HTTPS).
2. Enable Monitor SSL certificate under the SSL section.
3. Set Alert when certificate expires in less than 21 days.
4. Click Save.

A minimal nginx reverse proxy configuration for Backrest:

server {
    listen 443 ssl;
    server_name backrest.example.com;

    ssl_certificate /etc/letsencrypt/live/backrest.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/backrest.example.com/privkey.pem;

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

    # Health endpoint for Vigilmon without proxying to Backrest
    location /nginx-health {
        return 200 "ok";
        add_header Content-Type text/plain;
    }
}

Monitor https://backrest.example.com for the proxied UI and https://backrest.example.com/api/v1/config for the API, both with SSL monitoring enabled.

Step 6: Configure Alert Channels

1. Go to Alert Channels in Vigilmon and add email, Slack, or a webhook to your on-call tool.
2. For the backup plan heartbeat monitors, set consecutive failures before alert to 1 — a missed backup plan always warrants immediate notification.
3. For UI and API monitors, set consecutive failures to 2 to tolerate brief Docker container restarts (typically under 30 seconds).
4. Add a Maintenance window in Vigilmon when upgrading Backrest to avoid alerts during the container restart.

Summary

| Monitor | Target | What It Catches | |---|---|---| | HTTP uptime | http://server:9898/ | Backrest container down, port binding lost | | API health | http://server:9898/api/v1/config | API layer failure, database read error | | TCP port | server:9898 | Network-level port binding failure | | Plan heartbeat | CONDITION_SNAPSHOT_SUCCESS webhook | Missed or stalled backup plan | | SSL certificate | HTTPS proxy domain | TLS certificate expiry |

Backrest makes BorgBackup accessible to users who prefer a dashboard over a CLI — but it adds a new failure layer: the Backrest service itself. With Vigilmon watching the web UI, REST API, TCP port, and webhook-driven backup heartbeats, you get full-stack visibility into both the Backrest application and the BorgBackup jobs it orchestrates.