borgmatic-checker

NAME

borgmatic-checker - verifies recent borgmatic backup

SYNOPSIS

borgmatic-checker [OPTIONS]

DESCRIPTION

borgmatic-checker checks when your most recent borgmatic backup completed and alerts you if it's older than a specified threshold.

Runs borgmatic commands to retrieve backup information, extracts the timestamp of the last completed backup, and compares it against the current time.

Helps ensure your backup system runs on schedule and can be integrated into monitoring systems or cron jobs.

When run, it normally displays something like:

Last backup completed 2025-10-10 08:30:00+00:00 (2.5 hours ago)

If the time of last backup exceeds the threshold it displays an alert:

ALERT! Last backup completed 2025-10-08 14:00:00+00:00 (43.0 hours ago)

OPTIONS

--older, -o HOURS Alert if backup is older than the specified number of hours. Default: 24

--silent, -s Suppress output unless backup is older than the threshold. Useful for cron jobs and monitoring systems.

--config, -c FILE Path to borgmatic configuration file (overrides borgmatic default).

--borgmatic, -B COMMAND Path to borgmatic command. Default: borgmatic

--hosts, -H FILE Path to YAML file containing a collection of hosts to check.

--debug
Enable debug output.

--time-now "YYYY-MM-DD HH:MM:SS"
Override current time for testing purposes.

--help, -h
Display help message and exit.

Hosts File

The --hosts option can be used to specify a YAML file containing a list of hosts to check. Each entry requires host and config keys.

Example:

hosts:
- host: picard
  config: /etc/borgmatic/config-picard.yaml
- host: data
  config: /etc/borgmatic/config-data.yaml
- host: riker
  config: /etc/borgmatic/config-riker.yaml

EXIT STATUS

0 All checked backups are current within the specified age threshold.

1 One or more backup checks failed. This occurs when:

• A borgmatic command fails to execute.
• A backup is older than the specified threshold.

INSTALLATION

Requirements are:

• Python 3.6+
• borgmatic installed and configured
• Permissions to run borgmatic and access backup repositories

Required Python dependencies can be installed with pip:

pip install -r requirements.txt

TESTING

A comprehensive test suite is provided using pytest. To run the tests:

pip install pytest
pytest test_borgmatic_checker.py -v

AUTHOR

Courtney Rosenthal_
<cr@crosenthal.com>

The latest version is available at: https://codeberg.org/crosenthal/borgmatic-checker

LICENSE

This is free and unencumbered software released into the public domain.

For more information, see the UNLICENSE.