Backup scripts

A Python backup orchestration tool. Given a JSON configuration file, it cycles through sources (databases, folders, cloud snapshots), compresses and optionally encrypts each backup, uploads to one or more destinations, and reports via notifications.

Quick start

pip install backups
backups /etc/backups/production.json

See docs/scheduling.md for how to run as a systemd timer or cron job.

Configuration

Configuration is a single JSON file:

{
"sources": [ ... ],
"destinations": [ ... ],
"notifications": [ ... ]
}

Encryption (optional)

Encryption can be specified at the top level (applies to all sources) or per-source. Per-source settings override top-level.

Top-level (applies to all sources):

{
"encryption": {
"passphrase": "YOUR_PASSPHRASE"
},
"sources": [...]
}

Or per-source:

{
"sources": [
{
"name": "mysql-db",
"type": "mysql",
"passphrase": "YOUR_PASSPHRASE"
},
{
"name": "pg-db",
"type": "postgresql",
"recipients": ["ops@example.com"]
}
]
}

Use passphrase for symmetric GPG encryption, or recipients (array) for asymmetric/GPG public key encryption.

Override semantics: if a source defines either passphrase or recipients, the top-level encryption block is ignored entirely for that source.

Note: older configs containing "type": "symmetric" or "type": "asymmetric" fields in the encryption block should be updated — those fields were never implemented and are ignored.

Tracing Configuration

OpenTelemetry OTLP tracing is supported for observability. Tracing is disabled by default (zero performance impact).

Install the optional tracing dependencies:

pip install backups[tracing]

To enable tracing:

• Set OTEL_EXPORTER_OTLP_ENDPOINT to your OTLP collector URL (e.g., http://localhost:4317 for gRPC).
• Optional: Set OTEL_EXPORTER_OTLP_HEADERS for authentication (e.g., authorization=Bearer token).
• Optional: Set OTEL_EXPORTER_OTLP_INSECURE=true to disable TLS (default: TLS enabled).
• Optional: Set OTEL_TRACES_SAMPLER and OTEL_TRACES_SAMPLER_ARG to control sampling (e.g., OTEL_TRACES_SAMPLER=traceidratio and OTEL_TRACES_SAMPLER_ARG=0.1 for 10%).

Example:

export OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317
backups /etc/backups/production.json

Traces include comprehensive spans for:

• Backup run - version, hostname
• Per-source processing - source ID, type, name
• Dump operations - database host/name, file paths, operation timing
• Compression/encryption - operation type, input/output files
• Destination uploads - per-destination spans with upload locations (S3, GDrive, Minio, etc.)
• Retention cleanup - object counts, retained/removed counts
• Notifications - notification type, source ID

All spans include relevant metadata (file paths, database names, bucket names, object counts, timing, errors). The cloudflare-backup-registry notification automatically includes the current trace ID in its metadata for end-to-end correlation.

Sources

Type	Description	Docs
folder	Local directory via tar	docs/sources/folder.md
folder-ssh	Remote directory via SSH + tar	docs/sources/folderssh.md
sftp-folder	Remote directory via SFTP	docs/sources/sftpfolder.md
mysql	MySQL/MariaDB via mysqldump	docs/sources/mysql.md
mysql-ssh	MySQL via SSH tunnel	docs/sources/mysqlssh.md
postgresql	PostgreSQL via pg_dump	docs/sources/postgresql.md
rds	AWS RDS MySQL snapshot	docs/sources/rds.md
rds-pgsql	AWS RDS PostgreSQL snapshot	docs/sources/rdspostgresql.md
snapshot	Azure Managed Disk snapshot	docs/sources/snapshot.md
lvm-ssh	LVM snapshot over SSH	docs/sources/lvm-ssh.md

Destinations

Type	Description	Docs
s3	AWS S3 bucket	docs/destinations/s3.md
gs	Google Cloud Storage	docs/destinations/gs.md
b2	Backblaze B2	docs/destinations/b2.md
minio	Minio / S3-compatible (DO Spaces, Wasabi, etc.)	docs/destinations/minio.md
dropbox	Dropbox	docs/destinations/dropbox.md
gdrive	Google Drive	docs/destinations/gdrive.md
local	Local filesystem path (NFS, USB, etc.)	docs/destinations/local.md
samba	Samba/CIFS share	docs/destinations/samba.md

All destinations support retention_copies and/or retention_days to automatically prune old backups.

Notifications

Type	Description	Docs
smtp	Email via SMTP	docs/notifications/smtp.md
slack	Slack Incoming Webhook	docs/notifications/slack.md
discord	Discord webhook	docs/notifications/discord.md
telegram	Telegram Bot API	docs/notifications/telegram.md
matrix	Matrix room message	docs/notifications/matrix.md
flagfile	Write a flag file for monitoring	docs/notifications/flagfile.md
prometheus	Push metrics to Prometheus Pushgateway	docs/notifications/prometheus.md
elasticsearch	Write stats documents to Elasticsearch	docs/notifications/elasticsearch.md
cloudflare-backup-registry	Backup run reports to Cloudflare Backup Registry	docs/notifications/cloudflare-backup-registry.md

Scheduling

See docs/scheduling.md for setup with:

• systemd timer (recommended) — structured logging, dependency management, easy monitoring
• cron — simple alternative

Development

pip install -r requirements-dev.txt
pytest tests/ -v

Docker

docker pull ghcr.io/rossigee/backups:latest
docker run --rm -v /etc/backups:/etc/backups ghcr.io/rossigee/backups:latest /etc/backups/production.json