btrfs-backup-ng-config - Man Page

Validate the current configuration file. Checks for syntax errors, missing required fields, and invalid values.

Exit status is 0 if valid, non-zero if errors are found.

Generate an example configuration file with comments explaining all options. Can be run in interactive mode for a guided setup wizard.

-i,  --interactive

Run the interactive configuration wizard. This guides you through setting up:

• Global settings (snapshot directory, timestamp format)
• Parallelism settings
• Retention policies (hourly, daily, weekly, monthly, yearly)
• Email and webhook notifications
• Volumes to backup and their targets

Requires a terminal (TTY). Press Ctrl+C to cancel at any time.

-o,  --output FILE

Write output to FILE instead of stdout.

Example:

# Generate example config to stdout
btrfs-backup-ng config init > ~/.config/btrfs-backup-ng/config.toml

# Generate example config to file
btrfs-backup-ng config init -o /etc/btrfs-backup-ng/config.toml

# Run interactive wizard
btrfs-backup-ng config init --interactive

# Run interactive wizard and save to file
btrfs-backup-ng config init -i -o config.toml

Import a btrbk configuration file and convert it to TOML format. This helps migrate from btrbk to btrfs-backup-ng.

BTRBK_CONF

Path to the btrbk.conf file to import.

-o, --output FILE

Write output to FILE instead of stdout.

The importer:

• Parses btrbk's custom syntax
• Resolves inheritance (options cascade down)
• Converts retention policies
• Maps timestamp formats (short, long, long-iso to strftime patterns)
• Converts SSH sudo settings (backend btrfs-progs-sudo to ssh_sudo)
• Converts raw_target_compress and raw_target_encrypt settings
• Warns about common btrbk pitfalls
• Outputs valid TOML

Timestamp format mapping:

• short → %Y%m%d (e.g., 20260109)
• long → %Y%m%dT%H%M (e.g., 20260109T1430)
• long-iso → %Y%m%dT%H%M%S%z (e.g., 20260109T143052+0000)

Example:

btrfs-backup-ng config import /etc/btrbk/btrbk.conf
btrfs-backup-ng config import /etc/btrbk/btrbk.conf -o config.toml

Scan the system for btrfs subvolumes and suggest backup configurations. This command helps discover what subvolumes exist on your system and categorizes them for backup purposes.

--json

Output results in JSON format for scripting and automation.

-w,  --wizard

Launch the interactive configuration wizard with detected volumes pre-populated. Requires a terminal (TTY).

The detect command:

• Scans all mounted btrfs filesystems
• Lists all subvolumes found
• Categorizes subvolumes as recommended, optional, or excluded
• Suggests snapshot prefixes based on mount paths
• Identifies existing snapshots and system-internal subvolumes

Subvolume categories:

• Recommended: User data directories like /home that should be backed up
• Optional: System data (/opt, /var/log) that may or may not need backup
• Excluded: Existing snapshots and system-internal subvolumes

Example:

# Scan for subvolumes (requires root for full access)
sudo btrfs-backup-ng config detect

# Output in JSON format
sudo btrfs-backup-ng config detect --json

# Launch wizard with detected volumes
sudo btrfs-backup-ng config detect --wizard

Migrate systemd integration from btrbk to btrfs-backup-ng. This command stops and disables btrbk's systemd timer and enables btrfs-backup-ng's timer.

--dry-run

Show what would be done without making any changes. Use this to preview the migration before applying it.

The migrate-systemd command:

• Detects active btrbk systemd units (btrbk.timer, btrbk.service)
• Stops running btrbk timers
• Disables btrbk.timer
• Enables btrfs-backup-ng.timer (if installed)
• Prevents both tools from running simultaneously

Example:

# Preview migration (recommended first step)
btrfs-backup-ng config migrate-systemd --dry-run

# Apply migration
sudo btrfs-backup-ng config migrate-systemd

# If btrfs-backup-ng timer not installed, install it first
sudo btrfs-backup-ng install --timer=hourly
sudo btrfs-backup-ng config migrate-systemd

Global settings applied to all volumes unless overridden.

[global]
snapshot_dir = ".snapshots"
timestamp_format = "%Y%m%d-%H%M%S"
incremental = true
log_file = "/var/log/btrfs-backup-ng.log"
parallel_volumes = 2
parallel_targets = 2

Default retention policy.

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

Volume definitions. Each volume specifies a source path and targets.

[[volumes]]
path = "/home"
snapshot_prefix = "home-"
snapshot_dir = ".snapshots"  # optional override

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

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

[volumes.retention]  # optional override
daily = 14

Raw targets write btrfs send streams to files instead of using btrfs receive. This enables backups to non-btrfs filesystems with optional compression and encryption.

# Raw target to local path with compression and GPG encryption
[[volumes.targets]]
path = "raw:///mnt/nas/backups/home"
compress = "zstd"
encrypt = "gpg"
gpg_recipient = "backup@example.com"

# Raw target over SSH
[[volumes.targets]]
path = "raw+ssh://backup@server/backups/home"
compress = "zstd"

# Raw target with OpenSSL encryption (btrbk compatible)
[[volumes.targets]]
path = "raw:///mnt/backup"
compress = "gzip"
encrypt = "openssl_enc"
openssl_cipher = "aes-256-cbc"

Configuration options for raw targets:

compress

Compression method: gzip, pigz, zstd, lz4, xz, lzo, bzip2, pbzip2.

encrypt

Encryption method: gpg or openssl_enc.

gpg_recipient

GPG key recipient (required for gpg encryption).

gpg_keyring

Optional path to GPG keyring file.

openssl_cipher

OpenSSL cipher (default: aes-256-cbc).

For OpenSSL encryption, set the passphrase via environment variable BTRFS_BACKUP_PASSPHRASE or BTRBK_PASSPHRASE (for btrbk compatibility).

Optional notification settings.

[notifications]
on_success = false
on_failure = true

[notifications.email]
smtp_host = "smtp.example.com"
smtp_port = 587
from_addr = "backup@example.com"
to_addrs = ["admin@example.com"]
use_tls = true
username = "backup@example.com"
password = "secret"

[notifications.webhook]
url = "https://hooks.example.com/backup"