Skip to content
backpulse backpulse docs

Monitor restic and Borg backups

A successful backup process is not proof that a usable backup exists. The command can exit zero while the repository holds no recent snapshot, the output file is empty, or the scheduled job stopped running entirely.

backupctl wraps the command, reports start and completion, and runs a backend-specific verification before reporting success.

restic

Section titled “restic”

The restic adapter runs restic snapshots --json after the wrapped backup and rejects success when the newest snapshot is older than --max-age:

Terminal window
export RESTIC_REPOSITORY='s3:s3.example.com/backups/production'
export RESTIC_PASSWORD_FILE=/root/.config/restic/password
export BACKPULSE_URL=https://backpulse.aniicrite.dev
export BACKPULSE_PING_KEY='<check-key>'


backupctl run --adapter restic --max-age 26h -- \
  restic backup /srv/data --tag daily

A nightly cron entry:

30 3 * * * BACKPULSE_URL=https://backpulse.aniicrite.dev BACKPULSE_PING_KEY=<check-key> /usr/local/bin/backupctl run --adapter restic --max-age 26h -- restic backup /srv/data --tag daily

Borg

Section titled “Borg”
Terminal window
Use the generic artifact checks for an exported archive or manifest. The
command must exit zero, the file must exist, be recent, and exceed the minimum
size:


```sh
backupctl run \
  --path /var/backups/borg/latest-manifest.json \
  --max-age 26h \
  --min-size 128 \
  -- /usr/local/sbin/run-borg-backup

If the Borg script already runs borg check, keep it inside the wrapped command so a failed integrity check reports failure:

Terminal window
backupctl run -- /bin/sh -c \
  'borg create --stats ::daily-{now} /srv/data && borg check --verify-data --last 1'

Failure signals

Section titled “Failure signals”
  • No /start before the expected time: the scheduler or host failed.
  • /start without completion: the process is stuck or the host disappeared.
  • /fail: the command or result verification failed.
  • A late completion: the job exceeded its normal window.
  • Duplicate starts: overlapping schedules or retries running the job twice.

The backup command remains authoritative. A backpulse network failure only warns — it never turns a successful backup into a failed one.