Skip to content
Knowledge base

Monitor Borg and borgmatic backups with a heartbeat

Borg finishes with warnings more often than people notice, and a cron line that stops running says nothing at all. A heartbeat after borg create or borgmatic alerts on both.

1. Create the heartbeat

Add a monitor with Check type Heartbeat (cron), set the interval to the backup schedule and the grace to how long a backup can take, and copy the ping URL into the job's environment as PING_URL. Heartbeats are on every plan, Free included.

2. Plain Borg: decide what a warning is

Borg's documented return codes are 0 for success, 1 for a warning (the run finished but something needs a look, such as a file that changed while it was read), 2 for an error, and 128 plus N when stopped by signal N. To treat warnings as failures: borg create ::'{now}' /data && curl -fsS -m 10 "$PING_URL" || curl -fsS -m 10 --data-raw "borg exit $?" "$PING_URL/fail". To let warnings through, run borg create, save rc=$?, then ping "$PING_URL" when rc is 0 or 1 and "$PING_URL/fail" otherwise.

3. borgmatic: wrap the command

borgmatic exits non-zero when any configured action fails, so the same wrapper works on the whole run: borgmatic && curl -fsS -m 10 "$PING_URL" || curl -fsS -m 10 --data-raw "borgmatic exit $?" "$PING_URL/fail". Put it in the cron entry or systemd service that runs borgmatic today, in place of the bare borgmatic command.

4. What it catches

A repository that is full or locked, an SSH key that stopped working, a mount that was not there, a schedule that was disabled, and a host that was off all end the same way: no success ping before interval plus grace, or a fail ping, and an alert through your usual channels.

Go deeper

The full reference lives in the docs: Heartbeat monitors documentation. Error codes named above are each explained in the error-code reference.