btrfs-backup-ng - Man Page

automated btrfs backup management with incremental transfers

Synopsis

btrfs-backup-ng [OPTIONS] COMMAND [COMMAND_OPTIONS]

btrfs-backup-ng is a modern, feature-rich tool for automated BTRFS snapshot backup management. It supports TOML configuration files, time-based retention policies, parallel execution, stream compression, space-aware operations with quota support, automatic subvolume detection, and robust SSH transfer support.

The tool can operate in two modes:

Config-driven mode: Uses a TOML configuration file to define volumes, targets, and retention policies. Accessed via subcommands like run, snapshot, transfer.
Legacy mode: Direct command-line specification of source and destination paths, compatible with the original btrfs-backup tool.

Global Options

-h, --help: Show help message and exit.
-v, --verbose: Enable verbose output.
-q, --quiet: Suppress non-essential output.
--debug: Enable debug output with detailed logging.
-V, --version: Show version and exit.
-c, --config FILE: Path to configuration file. Defaults to ~/.config/btrfs-backup-ng/config.toml or /etc/btrfs-backup-ng/config.toml.

Commands

run: Execute all configured backup jobs (snapshot + transfer + prune). See btrfs-backup-ng-run(1).
snapshot: Create snapshots only, without transferring to targets. See btrfs-backup-ng-snapshot(1).
transfer: Transfer existing snapshots to targets without creating new ones. See btrfs-backup-ng-transfer(1).
prune: Apply retention policies to clean up old snapshots and backups. See btrfs-backup-ng-prune(1).
list: Show snapshots and backups across all configured volumes. See btrfs-backup-ng-list(1).
status: Show job status, last run times, and statistics. See btrfs-backup-ng-status(1).
config: Configuration management (validate, init, import, detect). See btrfs-backup-ng-config(1).
install: Install systemd timer/service for automated backups. See btrfs-backup-ng-install(1).
uninstall: Remove installed systemd timer/service.
restore: Restore snapshots from backup location back to local system. See btrfs-backup-ng-restore(1).
verify: Verify backup integrity at local or remote locations. See btrfs-backup-ng-verify(1).
estimate: Estimate backup transfer sizes before execution. See btrfs-backup-ng-estimate(1).

Configuration

Configuration files use TOML format and are searched in this order:

CLI specified: --config /path/to/config.toml
User config: ~/.config/btrfs-backup-ng/config.toml
System config: /etc/btrfs-backup-ng/config.toml

Example configuration:

[global]
snapshot_dir = ".snapshots"
incremental = true

[global.retention]
min = "1d"
hourly = 24
daily = 7
weekly = 4
monthly = 12

[[volumes]]
path = "/home"
snapshot_prefix = "home-"

[[volumes.targets]]
path = "/mnt/backup/home"

[[volumes.targets]]
path = "ssh://backup@server:/backups/home"
ssh_sudo = true
compress = "zstd"

Retention Policies

Time-based retention uses these settings:

min: Minimum retention period (e.g., "1d", "12h"). Nothing is deleted before this age.
hourly: Number of hourly snapshots to keep.
daily: Number of daily snapshots to keep.
weekly: Number of weekly snapshots to keep.
monthly: Number of monthly snapshots to keep.
yearly: Number of yearly snapshots to keep.

Compression

Supported compression methods for transfers:

none: No compression (default).
zstd: Zstandard compression (recommended, fast with good ratio).
gzip: Standard gzip compression.
lz4: Very fast compression with lower ratio.
pigz: Parallel gzip (multi-threaded).
lzop: Fast compression, low CPU usage.

SSH Targets

Remote targets use SSH URLs:

ssh://user@host:/path/to/backup

Options for SSH targets:

ssh_sudo: Use sudo for btrfs commands on remote host.
ssh_key: Path to SSH private key file.

Raw Targets

Raw targets write btrfs send streams directly to files instead of using btrfs receive. This enables backups to non-btrfs filesystems (NFS, SMB, cloud storage) with optional compression and encryption.

URL schemes:

raw:///path: Local raw target.
raw+ssh://user@host/path: Remote raw target via SSH.

Configuration options:

compress: Compression method: gzip, pigz, zstd, lz4, xz, lzo, bzip2, pbzip2.
encrypt: Encryption method: gpg, openssl_enc.
gpg_recipient: GPG key recipient (required for gpg encryption).
gpg_keyring: Optional GPG keyring path.
openssl_cipher: OpenSSL cipher (default: aes-256-cbc).

Example raw target configuration:

[[volumes.targets]]
path = "raw:///mnt/nas/backups/home"
compress = "zstd"
encrypt = "gpg"
gpg_recipient = "backup@example.com"

For OpenSSL encryption, set the passphrase via environment variable:

export BTRFS_BACKUP_PASSPHRASE="your_passphrase"
# or (btrbk compatible)
export BTRBK_PASSPHRASE="your_passphrase"

File naming convention:

snapshot-name.btrfs                    # No compression/encryption
snapshot-name.btrfs.zst                # Compressed with zstd
snapshot-name.btrfs.gpg                # GPG encrypted
snapshot-name.btrfs.zst.gpg            # Compressed + GPG encrypted
snapshot-name.btrfs.enc                # OpenSSL encrypted
snapshot-name.btrfs.zst.enc            # Compressed + OpenSSL encrypted

Examples

Run all backup jobs:: btrfs-backup-ng run
Create snapshots only:: btrfs-backup-ng snapshot
Run with compression and rate limiting:: btrfs-backup-ng run --compress zstd --rate-limit 50M
List all snapshots:: btrfs-backup-ng list
Validate configuration:: btrfs-backup-ng config validate
Install hourly timer:: sudo btrfs-backup-ng install --timer hourly
Restore from backup:: btrfs-backup-ng restore ssh://server:/backups/home /mnt/restore
Estimate backup sizes:: btrfs-backup-ng estimate --volume /home
Estimate with space check:: btrfs-backup-ng estimate --volume /home --check-space
Detect btrfs subvolumes:: sudo btrfs-backup-ng config detect