Monitoring BorgBackup with Vigilmon

BorgBackup (Borg) is the go-to open-source deduplicating backup tool for Linux servers, databases, and home directories. Its client-side deduplication, AES-CTR encryption, and SSH-native remote repositories make it a favourite among sysadmins — but Borg has no built-in alerting. A failed cron job, an unreachable remote repository, or a corrupt archive can go undetected until the moment you actually need a restore. Vigilmon closes that gap with heartbeat monitoring for cron jobs, TCP health checks for SSH servers, and SSL alerts for HTTPS-proxied repository interfaces.

What You'll Set Up

• Cron heartbeat monitor for scheduled BorgBackup jobs (the primary integration — detect missed or failed backups before data loss)
• TCP port monitor for the remote Borg repository SSH server (port 22)
• HTTP uptime monitor for the Borg server process when using borg serve behind an HTTPS proxy
• SSL certificate alerts for HTTPS-proxied Borg repository servers (BorgBase, rsync.net, custom frontends)

Prerequisites

• BorgBackup 1.2+ installed and at least one repository initialised
• A cron job or systemd timer running regular borg create backups
• A remote Borg repository accessible over SSH (or HTTPS proxy)
• A free Vigilmon account

Step 1: Heartbeat Monitoring for BorgBackup Cron Jobs

The most important Borg monitoring integration is the heartbeat: your backup cron job POSTs to a Vigilmon URL on success. If the job crashes, never runs, or takes too long, Vigilmon alerts you — before you discover the gap during a restore.

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to Cron Heartbeat.
3. Set Expected ping interval to match your backup schedule (e.g. 1440 minutes for daily backups).
4. Set Grace period to 60 minutes to allow for variable backup duration.
5. Copy the heartbeat URL (e.g. https://vigilmon.online/heartbeat/abc123).

Now update your backup script to ping Vigilmon on success:

#!/bin/bash
set -euo pipefail

REPO="user@backup-server:/backups/myserver"
PASSPHRASE="your-passphrase"
VIGILMON_URL="https://vigilmon.online/heartbeat/abc123"

export BORG_PASSPHRASE="$PASSPHRASE"

# Run the backup
borg create \
  --stats \
  --compression lz4 \
  "$REPO::$(hostname)-$(date +%Y-%m-%d)" \
  /home /etc /var/lib

# Prune old archives
borg prune \
  --keep-daily 7 \
  --keep-weekly 4 \
  --keep-monthly 6 \
  "$REPO"

# Signal success to Vigilmon — only reached if all above commands succeeded
curl -fsS --retry 3 "$VIGILMON_URL" > /dev/null

If any command in the script exits with a non-zero status, set -euo pipefail aborts execution and the curl ping is never sent. Vigilmon detects the silence and alerts after the grace period.

For systemd-timer-based backups, add the curl call at the end of your ExecStart command or in an ExecStartPost directive that only fires on success:

[Service]
ExecStart=/usr/local/bin/borg-backup.sh
ExecStartPost=/usr/bin/curl -fsS https://vigilmon.online/heartbeat/abc123

Step 2: Verify the Borg Repository with a Lightweight Check

Beyond the backup cron job, add a separate Vigilmon heartbeat that confirms the Borg repository itself is accessible and readable — useful for catching repository corruption or SSH key problems between backup runs.

Create a second heartbeat monitor in Vigilmon (interval: 60 minutes) and add this check script to a separate cron job:

#!/bin/bash
# Lightweight repository health check — runs borg list with a timeout
REPO="user@backup-server:/backups/myserver"
VIGILMON_REPO_URL="https://vigilmon.online/heartbeat/def456"

export BORG_PASSPHRASE="your-passphrase"

# 'borg list' verifies SSH connectivity, passphrase, and repository integrity
if timeout 60 borg list "$REPO" > /dev/null 2>&1; then
  curl -fsS "$VIGILMON_REPO_URL" > /dev/null
fi

Add to crontab:

*/60 * * * * /usr/local/bin/borg-check.sh

This catches scenarios where the repository becomes unreachable or the SSH key is revoked between backup runs — before the next scheduled backup fails silently.

Step 3: TCP Port Monitor for the Remote Borg SSH Server

Borg backups over SSH fail immediately if the remote server is down or port 22 is blocked. Add a TCP check so Vigilmon alerts you as soon as the SSH server becomes unreachable — giving you time to investigate before the next backup window.

1. In Vigilmon, click Add Monitor.
2. Set Type to TCP Port.
3. Enter the backup server hostname: backup-server.example.com.
4. Set Port to 22.
5. Set Check interval to 5 minutes.
6. Click Save.

If your hosting provider uses a non-standard SSH port, enter that port number instead. This monitor covers BorgBase, rsync.net, and any self-hosted SSH backup server.

Step 4: HTTP Monitor for HTTPS-Proxied Borg Servers

Some Borg setups expose a management interface or API over HTTPS — BorgBase provides a web UI, and custom deployments may place borg serve behind an nginx HTTPS proxy with a REST status endpoint. Add an HTTP monitor to check availability:

1. In Vigilmon, click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter the management URL, e.g. https://borgbase.example.com/health or your custom proxy endpoint.
4. Set Check interval to 5 minutes.
5. Set Expected HTTP status to 200.
6. Click Save.

For a simple nginx proxy health check without a dedicated endpoint, monitor the proxy root:

# In your nginx server block — add a lightweight health endpoint
location /health {
    return 200 "ok";
    add_header Content-Type text/plain;
}

Step 5: SSL Certificate Alerts for Repository HTTPS Interfaces

HTTPS-proxied Borg interfaces — BorgBase, rsync.net HTTPS API, or custom frontends — rely on valid TLS certificates. An expired certificate blocks all HTTPS-based repository access and management tools.

1. Open the HTTP monitor you created in Step 4.
2. Enable Monitor SSL certificate under the SSL section.
3. Set Alert when certificate expires in less than 21 days.
4. Click Save.

A 21-day window gives you enough lead time to investigate Let's Encrypt renewal failures and renew manually before the certificate expires and breaks repository access.

Step 6: Configure Alert Channels

1. Go to Alert Channels in Vigilmon and add email, Slack, or a webhook.
2. For the heartbeat monitors (Steps 1 and 2), set consecutive failures before alert to 1 — a missed backup ping always warrants immediate attention.
3. For the TCP and HTTP monitors (Steps 3 and 4), set consecutive failures to 2 to avoid alerts during brief SSH server restarts.
4. Use Maintenance windows in Vigilmon during planned server maintenance to suppress expected downtime alerts.

Summary

| Monitor | Target | What It Catches | |---|---|---| | Cron heartbeat | Backup job URL | Failed backup, missed schedule, script crash | | Repo health heartbeat | Repo check URL | Repository unreachable between backups | | TCP port | backup-server:22 | SSH server down, port blocked | | HTTP uptime | HTTPS proxy URL | Management interface down | | SSL certificate | HTTPS proxy domain | TLS certificate expiry |

BorgBackup's deduplication and encryption make it one of the best backup solutions available — but silent failures are its Achilles heel. With Vigilmon heartbeats watching every cron job and TCP checks confirming SSH server availability, you get immediate notification when a backup fails or the repository becomes unreachable, long before you discover the gap during an actual restore.