BTRFS-BACKUP-NG-CONFIG(1)

💖 btrfs-backup-ng-config(1) — the config-management era 💖

okay bestie, pull up a chair, because this is the btrfs-backup-ng config family of commands — the ones that handle all your configuration files. Think of it as the group chat where your backups make Plans. ✨

It lives in the btrfs-backup-ng User Commands corner of the manual, and it's gonna help you create, validate, detect subvolumes, migrate from btrbk, and manage systemd integration. Iconic behavior, no notes.

---

✨ NAME ✨

btrfs-backup-ng-config — configuration management commands. that's it, that's the vibe 💅

---

🎀 SYNOPSIS 🎀

btrfs-backup-ng config validate
btrfs-backup-ng config init [-i|--interactive] [-o FILE]
btrfs-backup-ng config import [-o FILE] BTRBK_CONF
btrfs-backup-ng config detect [--json] [-w|--wizard]
btrfs-backup-ng config migrate-systemd [--dry-run]

---

🌸 DESCRIPTION 🌸

Manage btrfs-backup-ng configuration files. These commands help you create, validate, detect subvolumes, migrate from btrbk, and manage systemd integration. literally your config's whole life cycle, and it's serving 🫶

---

👑 SUBCOMMANDS 👑

💖 validate

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

btrfs-backup-ng config validate

It also checks, on this machine and without root, that each enabled volume's source can actually be backed up: it can be read from this account, it exists, and it's a directory on btrfs. A native source must also be a subvolume root, since btrfs subvolume snapshot refuses anything else — a directory that's just chilling inside a subvolume gets reported with the subvolume that holds it. A snapper source (that's source = "snapper") is not required to be one, because snapper takes its snapshots itself. Remote targets are not probed; doctor does that. iykyk 💅

Exit status, because this is the part you actually need:

• 0 — The file is valid and its volumes are usable here. slay ✅
• 1 — No config file was found, or the file itself is invalid and must be edited. 😭 go fix it
• 2 — The file is valid, but this machine cannot back up these volumes: a source is missing, cannot be read from this account, is not a directory, is not on btrfs, or (for native sources) is not a subvolume root. 💀

---

🧚 init

Generate an example configuration file with comments explaining all the options. Can be run in interactive mode for a guided setup wizard. it's giving ✨starter pack✨

btrfs-backup-ng config init [-i|--interactive] [-o FILE]

• -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. no judgment 🫶

Saved over an existing configuration, the wizard keeps every option it does not ask about: volumes are matched by path and targets by path within their volume, and options such as a target's ssh_key, ssh_host_key_policy or optional are carried into the new file. Answers to the wizard's own questions win, including an option answered by leaving it out. Before asking whether to overwrite, it lists what it kept and what it will remove (a volume or target the new configuration no longer has). Comments in the old file are not kept. 💔

• -o, --output FILE — Write output to FILE instead of stdout.

Example, bestie:

# 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

Import a btrbk configuration file and convert it to TOML format. This helps you migrate from btrbk to btrfs-backup-ng. glow-up arc, fr fr ✨

btrfs-backup-ng config import [-o FILE] BTRBK_CONF

• BTRBK_CONF — Path to the btrbk.conf file to import.
• -o, --output FILE — Write output to FILE instead of stdout.

The importer is out here doing the most:

• 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, so you know exactly what you're getting:

• 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

• --force — Overwrite the output file if it already exists. do it, no fear 🔥

---

🔥 detect

Scan the system for btrfs subvolumes and suggest backup configurations. This command helps you discover what subvolumes exist on your system and categorizes them for backup purposes. detective mode: activated 🕵️‍♀️

btrfs-backup-ng config detect [--json] [-w|--wizard]

• --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. main character energy 👑
• Optional — System data (/opt, /var/log) that may or may not need backup. your call honestly
• Excluded — Existing snapshots and system-internal subvolumes. not invited 🚫

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

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. out with the old, in with the slay 💅

btrfs-backup-ng config migrate-systemd [--dry-run]

• --dry-run — Show what would be done without making any changes. Use this to preview the migration before applying it. always preview first, bestie, we don't do impulsive 🙈

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

---

💜 CONFIGURATION FORMAT 💜

Configuration uses TOML format. Key sections, coming right up:

✨ [global]

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

✨ [global.retention]

Default retention policy.

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

✨ [[volumes]]

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

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. living outside the btrfs-box, love that for them ✨

# 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). keep that secret secret 🤫

🌸 [notifications]

Optional notification settings. only if you want the drama 💌

[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"

---

🎀 FILES 🎀

• ~/.config/btrfs-backup-ng/config.toml — User configuration file. your personal config, your personal era 💖
• /etc/btrfs-backup-ng/config.toml — System-wide configuration file. the communal one 👑

---

⭐ SEE ALSO ⭐

btrfs-backup-ng(1), toml(5)

go read them, bestie, they're worth it 🫶

---

that's a wrap!! 💅 this page is from btrfs-backup-ng, dated January 2026 — and yes, that's the whole BTRFS-BACKUP-NG-CONFIG(1) moment. no cap, you understood all of it. periodt. ✨🎀🦋