config.toml

# btrfs-backup-ng Configuration Example
#
# This file demonstrates all available configuration options.
# Copy to ~/.config/btrfs-backup-ng/config.toml or /etc/btrfs-backup-ng/config.toml

# =============================================================================
# Global Settings
# =============================================================================
# These apply to all volumes unless overridden at the volume level.

[global]
# Directory for storing snapshots (relative to volume path or absolute)
snapshot_dir = ".snapshots"

# Timestamp format for snapshot names (strftime format)
timestamp_format = "%Y%m%d-%H%M%S"

# Use incremental transfers when possible (recommended)
incremental = true

# Optional log file path (comment out to disable file logging)
# log_file = "/var/log/btrfs-backup-ng.log"

# Parallel execution settings
parallel_volumes = 2    # Max concurrent volume backups
parallel_targets = 3    # Max concurrent target transfers per volume

# Output verbosity
quiet = false           # Suppress non-essential output
verbose = false         # Enable verbose output

# Transfer limits. A transfer that is moving data is succeeding, so there is NO
# wall-clock limit by default; faults are caught by measuring bytes instead. A
# fixed deadline is a guess about link speed times dataset size, and the old
# fixed hour ended first syncs that were working perfectly.
transfer_timeout = 0            # Seconds per transfer; 0 = unlimited (default)
transfer_stall_timeout = 900    # Give up when no data has moved for this long; 0 disables

# -----------------------------------------------------------------------------
# Default Retention Policy
# -----------------------------------------------------------------------------
# Time-based retention with intuitive bucket system.
# Duration format: 30m (minutes), 2h (hours), 1d (days), 1w (weeks)

[global.retention]
min = "1d"       # Keep ALL snapshots for at least 1 day ("all" = keep every snapshot for ever)
hourly = 24      # Then keep 24 hourly (one per hour)
daily = 7        # Then keep 7 daily (one per day)
weekly = 4       # Then keep 4 weekly (one per week)
monthly = 12     # Then keep 12 monthly (one per month)
yearly = 0       # Don't keep yearly snapshots (0 = disabled)


# =============================================================================
# Volume Configurations
# =============================================================================
# Define each BTRFS subvolume you want to back up.

# -----------------------------------------------------------------------------
# Example 1: Home directory backup to local and remote targets
# -----------------------------------------------------------------------------
[[volumes]]
path = "/home"
snapshot_prefix = "home-"
enabled = true

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

# Remote backup target with compression
[[volumes.targets]]
path = "ssh://backup@nas.local:/backups/home"
ssh_sudo = true
ssh_password_auth = true
compress = "zstd"    # compressed over the wire, decompressed on the
                     # remote before btrfs receive
rate_limit = "50M"


# -----------------------------------------------------------------------------
# Example 2: Root filesystem with custom retention
# -----------------------------------------------------------------------------
[[volumes]]
path = "/"
snapshot_prefix = "root-"
snapshot_dir = "/.snapshots"    # Absolute path for root

# Override global retention for root (keep fewer snapshots)
[volumes.retention]
min = "6h"
hourly = 12
daily = 7
weekly = 2
monthly = 3

[[volumes.targets]]
path = "ssh://backup@nas.local:/backups/root"
ssh_sudo = true
compress = "lz4"    # compressed over the wire, decompressed on the
                    # remote before btrfs receive


# -----------------------------------------------------------------------------
# Example 3: Database volume with frequent snapshots, no remote
# -----------------------------------------------------------------------------
[[volumes]]
path = "/var/lib/postgresql"
snapshot_prefix = "postgres-"

# More aggressive retention for databases
[volumes.retention]
min = "2h"
hourly = 48
daily = 14
weekly = 4
monthly = 6

# Local backup only (no remote targets)
[[volumes.targets]]
path = "/mnt/backup/postgres"


# -----------------------------------------------------------------------------
# Example 4: Disabled volume (for reference/later use)
# -----------------------------------------------------------------------------
[[volumes]]
path = "/srv/data"
snapshot_prefix = "data-"
enabled = false    # Skip this volume during backups

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


# -----------------------------------------------------------------------------
# Example 5: External drive backup with mount verification
# -----------------------------------------------------------------------------
[[volumes]]
path = "/home"
snapshot_prefix = "home-"

[[volumes.targets]]
path = "/mnt/usb-backup/home"
# The target is a SUBDIRECTORY of the mount point, so name the mount point.
# require_mount = true would require /mnt/usb-backup/home itself to be a mount
# point, and would abort even with the drive connected.
require_mount = "/mnt/usb-backup"    # Fail if the drive is not mounted
# optional = true                    # Allowed to be absent: skip it instead of
                                     # failing the run, and let the source prune


# =============================================================================
# SSH Target Options Reference
# =============================================================================
# All available options for SSH targets:
#
# [[volumes.targets]]
# path = "ssh://user@host:/path"    # Required: SSH URL
# ssh_sudo = false                   # Use sudo on remote host
# ssh_port = 22                      # SSH port number
# ssh_key = "~/.ssh/id_rsa"         # Path to SSH private key
# ssh_auth_sock = "/path/to/agent.sock"  # Explicit ssh-agent socket (see note below)
# ssh_password_auth = true           # Allow password authentication fallback
# ssh_host_key_policy = "accept-new" # accept-new (trust first contact, reject a changed
#                                    # key) | strict (known_hosts only)
# skip_remote_lock = false           # Proceed even when a lock cannot be RECORDED on this
#                                    # target. Default false: an operation stops rather than
#                                    # run unprotected, because a prune elsewhere would not
#                                    # see the snapshot as in use. Set true only for a
#                                    # destination you can read but not write
# compress = "none"                  # Compression: none|gzip|pigz|zstd|lz4|
#                                    # xz|lzo|bzip2|pbzip2 -- the same set on
#                                    # every kind of target
# rate_limit = "10M"                 # Bandwidth limit: number with K|M|G suffix
# require_mount = false              # true, or "/mnt/point" the target lives under (local only)
#
# SSH agent under sudo:
# Backups run as root (btrfs send/receive need it), and sudo strips SSH_AUTH_SOCK.
# If your SSH key is passphrase-protected, its usable key lives in your ssh-agent, so
# btrfs-backup-ng auto-discovers your agent socket (common locations incl. ~/.ssh/agent/,
# /run/user/<uid>/...) and uses it. If your agent lives somewhere unusual, pin it with
# ssh_auth_sock above, export BTRFS_BACKUP_SSH_AUTH_SOCK, or run with
# `sudo --preserve-env=SSH_AUTH_SOCK` (or `sudo -E`). Alternatively use a passphrase-less
# key. On the CLI (restore/verify/estimate/snapper) the same override is --ssh-auth-sock.


# =============================================================================
# Filesystem Check Options
# =============================================================================
# Controls how btrfs-backup-ng validates source and destination paths.
# These can be set via command line: --fs-checks=auto|strict|skip
#
# Modes:
#   auto   - (Default) Warn about issues but continue operation
#   strict - Error out on any filesystem check failure
#   skip   - Bypass all filesystem verification checks
#
# The default "auto" mode is user-friendly: it warns about potential issues
# (like a source not being a btrfs subvolume) but continues anyway.
#
# Use "strict" for production/automated backups where you want failures
# to stop execution.
#
# Use "skip" when working with backup directories (which are regular
# directories, not subvolumes) or non-standard setups.


# =============================================================================
# Space Checking (Estimate Command)
# =============================================================================
# Before running large backups, you can check if there's enough space:
#
#   btrfs-backup-ng estimate --volume /home --check-space
#
# This checks both filesystem free space AND btrfs quota limits (if enabled),
# using the more restrictive value. A safety margin (default 10%) is applied.
#
# Options:
#   --check-space              Enable destination space verification
#   --safety-margin PERCENT    Safety margin percentage (default: 10%)
#
# Example with custom safety margin:
#   btrfs-backup-ng estimate --volume /home --check-space --safety-margin 20


# =============================================================================
# Subvolume Detection
# =============================================================================
# To discover btrfs subvolumes on your system:
#
#   sudo btrfs-backup-ng config detect
#
# This scans all btrfs filesystems and categorizes subvolumes as:
#   - Recommended: User data like /home that should be backed up
#   - Optional: System data that may or may not need backup
#   - Excluded: Existing snapshots and system internals
#
# To launch an interactive wizard with detected volumes:
#   sudo btrfs-backup-ng config detect --wizard
#
# For scripting, use JSON output:
#   sudo btrfs-backup-ng config detect --json