kopia-mon is a off-line monitoring and alerting tool for Kopia backup. It is designed to run on a schedule, review all the backup tasks that completed since its previous run, and send an email report with any detected errors.
Main features:
- Email based reporting and alerting for kopia backup
- Always send the report or only when errors occur
- Alert on snapshot error
- Alert on snapshot inactivity/ missed backups
- Optionally do a basic verification that there were actually changes that required backup when detecting inactivity
- Optionally set a different email header when errors are detected
- Handles multiple repositories in a single email
- Support for SMTP servers that require authentication like gmail
A daily report with no errors:
A daily report with an error in one of the snapshots:
A daily report when no snapshot has been taken for too long:
NOTE: The program has only been tested with gmail, both for sending and receiving the emails. Other SMTP providers that use TLS should work but there are no guarantees. Likewise, if the recipient is not on gmail, the email formatting may not work correctly and the email may look messed up.
The kopia command line must be in the environment path when kopia-mon is started.
Python with minimum version 3.10 is required. It is recommended to use a virtual environment, if you know how to use it and how to get the scheduler to run the script from the correct environment.
Installing dependencies:
pip install -r requirements.txt
Create a new environment for kopia-mon:
conda env create -f environment.yml
Activate the environment before using the script:
conda activate kopia-mon
Since the config file holds a cleartext (=unencrypted) password it is highly recommended that you create a dedicated gmail account just for sending emails from kopia-mon. Once you create the account had over to the "Manage Account" panel and select the "Security" tab. Find the "Signing in to Google" section on that page and select "App passwords". Create a new app password and, copy it, and paste in appropriate place in the config file.
The program doesn't manage scheduling. You should use your OS scheduling service (cron, Windows Task Scheduler, etc.) to run it periodically. Kopia's "After Snapshot" action should also work but it hasn't been tested and unless it's very important to be notified immediately about errors I wouldn't recommend it.
python kopia-mon.py
Optional arguments:
-c <CONFIG_FILE> - Path to config file. Default: "config.yaml"
--no-send-email - Write the report to stdout instead of sending it by email
--set-exit-code - Set the exit code to 0 if no report was generated, 2 if a report was generated and 6 if an error report was generated. An exit code of 1 would indicate a python error, as usual.
kopia-mon requires a YAML configuration file with the following structure:
email:
from: (required) - Email address of sender
to: (required) - A single email address or array of email addresses to send the report to>
subject: (optional) - The subject of the email when there are no errors
subject-error: (optional) - The subject of the email when there are errors
server:
address: (required) - The address of the SMTP server to use for sending the emails
port: (required) - The port of the SMTP server
transport: (optional) - The transport encryption to use. Either SSL (the default) or TLS
user: (required) - The username to authenticate to the SMTP server with
password: (required) - The password to authenticate with
repositories:
- config-file: (required) - The kopia config file for the repository
inactivity_days: (required) - minimum days of inactivity before reporting an error
validate_inactivity: (required) - Boolean value indicating if kopia-mon should try to verify if there were any actual file changes, that were expected to be backup up but didn't, before reporting an inactivity error. This check ignores ignored files so a change in an ignored file will still trigger the alert
errors_only: (required) - Boolean value indicating if kopia-mon should only send an email when errors are detected or every time it runs
Example:
email:
from: [email protected]
to: [email protected]
subject: Kopia Backup Report
subject-error: Kopia Backup Report - HAS ERRORS
server:
address: smtp.gmail.com
port: 465
user: [email protected]
password: my_app_password
repositories:
- config-file: documents.config
inactivity_days: 2
validate_inactivity: false
errors_only: true
- config-file: media.config
inactivity_days: 5
validate_inactivity: true
errors_only: true