BTRBK(1)

📦
version 0.32.7 · 6 versions
, in arch rolling, fedora 43, fedora 44, nixos 26.05, nixpkgs unstable

💖 NAME 💖

okay so this is btrbk(1) — the Btrbk Manual, bestie — and btrbk is literally a backup tool for btrfs subvolumes 🦋

✨ SYNOPSIS ✨

btrbk [-h|--help] [--version]
      [-c|--config <file>] [-n|--dry-run] [--exclude <filter>]
      [-p|--preserve] [--preserve-snapshots] [--preserve-backups]
      [-v|--verbose] [-q|--quiet] [-l|--loglevel <level>]
      [-t|--table] [-L|--long] [-1|--single-column]
      [--format <output-format>] [--pretty]
      [-S|--print-schedule] [--progress]
      [--lockfile <file>]
      [--override <config_option>=<value>]
      <command> [[--] <filter>...]

🌸 DESCRIPTION 🌸

so btrbk is a backup tool for btrfs subvolumes, and the whole serve is that it uses btrfs-specific capabilities to make atomic snapshots and then transfer them incrementally to a target btrfs filesystem ✨ like, it's giving one source to multiple destinations, no big deal 💅

For most operations, btrbk needs root privileges to run correctly, which is honestly so real of it. OR — hear me out — you could use the btrfs-progs-sudo or btrfs-progs-btrbk backends, both of which let you run btrbk as a regular user 👑 Check the configuration option backend in btrbk.conf(5) for the deets.

🎀 Snapshots and Backups 🎀

Snapshots and backup subvolumes get created in this exact form, bestie, write it down:

<snapshot-name>.<timestamp>[_N]

Where <snapshot-name> is identical to the source subvolume name — unless the configuration option snapshot_name is set, then it's whatever you told it to be. <timestamp> is a timestamp describing the creation time (local time of the host running btrbk) of the snapshot/backup. You can configure the format with the timestamp_format option, go read btrbk.conf(5) for details 📖

And if multiple snapshots/backups get created on the same date/time, then N gets incremented on each snapshot, starting at 1 🔢

If a snapshot or backup does not match the naming scheme above (say, because someone renamed it manually 😭), btrbk will leave it untouched. It's not gonna touch your stuff, it's respectful like that.

Also quick vocab check because the terminology here is lowkey a trap 🪤 — in btrfs terminology, a snapshot is a "subvolume with a given initial content of the original subvolume" (it shows a parent-uuid, see btrfs-subvolume(8)), and they can be read-write (default) or read-only. But in btrbk terminology, snapshot means "read-only btrfs snapshot", and backup means "read-only subvolume created with send/receive" (it shows a received-uuid). Two different languages, same friend group, iykyk 💀

💅 OPTIONS 💅

  • -h, --help — prints the synopsis and a list of the commands 🫶
  • --version — prints the btrbk version ⭐
  • -c, --config <file> — read the configuration from <file> 📄
  • -n, --dry-run — don't run anything that would alter the filesystem, just show the snapshots and backup subvolumes that would be created/deleted by the run, snapshot, resume, prune, archive and clean commands 👀 use it together with -l debug to see the actual btrfs commands that would be executed 🔍
  • --exclude <filter> — exclude configured sections matching <filter>. See FILTER STATEMENTS below ✂️
  • -p, --preserve — preserve all snapshots and backups. Skips deletion of any snapshots and backups, even if it's specified in the configuration file (this is a shortcut for "--preserve-snapshots --preserve-backups") 🙅♀️
  • --preserve-snapshots — preserve all snapshots. Skips deletion of any snapshots, even if specified in the configuration file 💖
  • --preserve-backups — preserve all backups. Skips deletion of any backups, even if specified in the configuration file 💖
  • --wipe — ignore the configured snapshot retention policy and just delete all but the latest snapshots instead. All snapshots needed for incremental backup (latest common) are also preserved. Super useful if you're getting low on disk space (ENOSPC) 😭
  • -v, --verbose — increase the logging level, see "--loglevel" 📢
  • -q, --quiet — quiet operation. If set, btrbk does not print the summary after executing the run, snapshot, resume, prune, or archive commands 🤫
  • -l, --loglevel <level> — set the level of verbosity for the stderr logging. Accepted levels are: error, warn, info, debug, and trace. Default is info 📊
  • -t, --table — print output in table format (shortcut for "--format=table") 🗂️
  • -L, --long — print output in long table format (shortcut for "--format=long") 📋
  • -1, --single-column — print output as single column (heads up: not available for all commands) 1️⃣
  • --format table|long|raw|col:[h:]<columns> — print output in the specified format. If it's set to "raw", it prints space-separated, quoted key=value pairs (machine readable 🤖).

If it's set to col:, it prints only the <columns> you specified (comma-separated list). Header lines are omitted if the "h:" modifier is present. Columns prefixed with "-" are collapsed if empty. Columns postfixed with ":RALIGN" are right-aligned ➡️

  • --pretty — print table output with lowercase, underlined column headings (instead of single-line uppercase headings) 🎀 so aesthetic
  • -S, --print-schedule — print detailed scheduler information on the run, snapshot, resume, prune and archive commands. Use the --format command line option to switch between different output formats 🗓️
  • --progress — show a progress bar on the send-receive operation. Requires the "mbuffer" command (version >= 20180505) installed on the host running btrbk 📈
  • --lockfile <file> — place an exclusive lock on <file> during program execution, using flock(2). If the lock is held by another process, exit before running any actions. Overrides the configuration option "lockfile". Ignored on dryrun (-n, --dry-run) 🔒
not me emphasizing this one but --override is powerful and you should be careful, fr fr:
  • --override <config_option>=<value> — override a configuration option <config_option> with <value>. Globally, for ALL contexts. Use with care! ⚠️🔥

🎀 COMMANDS 🎀

✨ Actions ✨

okay so these are the commands that actually do stuff — they make snapshots and/or backups, and yes bestie, they can all run in dry-run mode with -n, --dry-run. if you wanna switch up the output format, hit it with the --format command line option. it's giving customizable ✨

also, go read section RETENTION POLICY in btrbk.conf(5) for the tea on configuring your retention policy. iykyk 💅

🏃‍♀️ run [filter...]

perform snapshot and backup operations as specified in the configuration file. if the optional [filter...] arguments are present, snapshots and backups are only performed for the subvolumes/targets matching a filter statement (see FILTER STATEMENTS below). no cap.

  • Step 0: Read Data — read information from the source and target btrfs filesystems so it can do sanity checks and identify parent/child and received-from relationships. slay.
  • Step 1: Create Snapshots — if the checks succeed, btrbk creates snapshots for the source subvolumes specified in the configuration file, according to the snapshot_create option.
  • Step 2: Create Backups — for each specified target, btrbk creates the backups as follows: after comparing the backups to the source snapshots, btrbk transfers all missing snapshots needed to satisfy the configured target retention policy, incrementally from the latest common parent subvolume found. if no common parent subvolume is found (or if the incremental option is set to “no”), a full (non-incremental) backup is created. periodt.
  • Step 3: Delete Backups — unless the -p, --preserve or --preserve-backups option is set, backup subvolumes that are not preserved by their configured retention policy will be deleted. note that the latest snapshot/backup pair are always preserved, regardless of the retention policy.
  • Step 4: Delete Snapshots — unless the -p, --preserve or --preserve-snapshots option is set, snapshots that are not preserved by their configured retention policy will be deleted. note that the latest snapshot (the one created in step 1) as well as the latest snapshot/backup pair are always preserved, regardless of the retention policy. if any target is unreachable or has errors, all snapshots are preserved in order not to break the incremental chain. 💀

dryrun [filter...]

don’t run any btrfs commands that would alter the filesystem — just show the snapshots and backup subvolumes that would be created/deleted by the run command. use in conjunction with -l debug to see the btrfs commands that would be executed. bestie, it’s a vibe check for your backups 🫶

snapshot [filter...]

snapshot only: skips backup creation and deletion (steps 2 and 3). use in conjunction with -p, --preserve (or --preserve-snapshots) if you also want to skip snapshot deletion (step 4).

note that snapshot deletion is skipped if the target is not accessible, as it is still required in order to determine the latest snapshot/backup pair (which is always preserved, regardless of the retention policy). don’t touch that pair, okay? 💅

resume [filter...]

resume backups: skips snapshot creation (step 1), transfers and deletes snapshots/backups in order to satisfy their configured retention policy. use in conjunction with -p, --preserve, --preserve-backups, --preserve-snapshots if you want to skip backup and/or snapshot deletion (steps 3, 4). it’s giving pick-up-where-you-left-off energy ✨

prune [filter...]

prune snapshots and backups: skips snapshot and backup creation (steps 1, 2), only deletes snapshots and backups in order to satisfy their configured retention policy. useful for cleaning the disk after changing the retention policy. use in conjunction with --preserve-backups, --preserve-snapshots if you want to skip backup or snapshot deletion (steps 3, 4).

note that deletion is skipped if source or target is not accessible, as it is still required in order to determine the latest snapshot/backup pair (which is always preserved, regardless of the retention policy). 🌸

archive <source> <target> [--raw]

recursively copy all subvolumes created by btrbk from <source> to <target> directory, optionally rescheduled using archive_preserve_* configuration options. also creates directory tree on <target>. useful for creating extra archive copies (clones) from your backup disks. note that you can continue using btrbk after swapping your backup disk with the archive disk. iconic behavior 👑

if you want to use nested subvolumes on the target filesystem, you need to create them by hand (e.g. by running btrfs subvolume create <target>/dir). check the output of --dry-run if unsure.

note that this feature needs a linux kernel >=4.4 to work correctly! ⚠️

if --raw option is set, creates raw targets (experimental, see btrbk.conf(5), TARGET TYPES). 👀

clean [filter...]

delete incomplete (garbled) backups. incomplete backups can be left behind on network errors or kill signals while a send/receive operation is ongoing, and are identified by the "received_uuid" flag not being set on a target (backup) subvolume. not me cleaning up garbled backups 💀

the following table gives a quick overview of the action commands and resulting snapshot creation (S+), backup creation (B+), snapshot deletion (S-), and backup deletion (B-):

           Command   Option                 S+ B+ S- B-
           --------------------------------------------
           run                              x  x  x  x
           run       --preserve             x  x
           run       --preserve-snapshots   x  x     x
           run       --preserve-backups     x  x  x
           snapshot                         x     x
           snapshot  --preserve             x
           resume                              x  x  x
           resume    --preserve                x
           resume    --preserve-snapshots      x     x
           resume    --preserve-backups        x  x
           prune                                  x  x
           prune     --preserve-snapshots            x
           prune     --preserve-backups           x

💖 Informative Commands 💖

these commands are informative only, and will not alter the file system. they’re just here to spill the tea ☕ no changes, just facts.

stats [filter...]

print statistics of snapshot and backup subvolumes. optionally filtered by [filter...] arguments (see FILTER STATEMENTS below).

list <subcommand> [filter...]

print information defined by <subcommand> in a tabular form. optionally filtered by [filter...] arguments (see FILTER STATEMENTS below).

available subcommands (default “all”):

  • all — list all snapshots and backups created by btrbk.
  • snapshots — list all snapshots created by btrbk.
  • backups — list all backups (and correlated snapshots) created by btrbk.
  • latest — list most recent common snapshot/backup pair, or most recent snapshot if no common found.
  • config — list configured source/snapshot/target relations.
  • source — list configured source/snapshot relations.
  • volume — list configured volume sections.
  • target — list configured targets.

use the --format command line option to switch between different output formats. 🌈

usage [filter...]

print filesystem usage information for all source/target volumes, optionally filtered by [filter...] arguments (see FILTER STATEMENTS below). note that the "free" value is an estimate of the amount of data that can still be written to the file system. it’s giving disk space forecast 🔮

origin <subvolume>

print the subvolume origin tree: shows the parent-child relationships as well as the received-from information. use the --format command line option to switch between different output formats. family tree but for subvolumes 🧚

diff <from> <to>

list the modified files since generation (transid) of subvolume <from> in subvolume <to>. columns:

  • SIZE — file was modified for a total of SIZE bytes
  • COUNT — file was modified in COUNT generations
  • FLAGS — "+" file accessed at offset 0 (at least once); "c" COMPRESS flag is set (at least once); "i" INLINE flag is set (at least once)

extents [diff] <subvolume>... [exclusive <subvolume>...]

print accurate disk space usage and diff based on extent data (FIEMAP ioctl, slow!). 🐌

subvolumes following the exclusive keyword are added to a separate set, and additional set-exclusive data is printed at the end of the list. this gives a hint of how much data will be freed if deleting all subvolumes in the set. example:

btrbk extents diff /backup/data.* exclusive /backup/data.2010*

the EXCLUSIVE column shows the set-exclusive data of all other listed (!) subvolumes (relative complement of block regions). provided that all related subvolumes (holding references to extents) are also listed, this amount of disk space would be freed when deleting the subvolume.

the DIFF column shows the data added to the previous subvolume (relative complement of block regions).

if called with the --related option, btrbk also lists all related subvolumes. this is not recommended for backups, as parent-uuid relations break for received subvolumes as soon as an intermediate subvolume is deleted. 💀

note that reading all extents is a disk-intensive task, expect long execution times and high ram usage. consider setting cache_dir. 🔥

ls <path>|<url>...

list all btrfs subvolumes below <path>. use the --format command line option to switch between different output formats. see lsbtr(1). ✨

config print|print-all

prints the parsed configuration file. 💅

🔍 FILTER STATEMENTS

okay bestie so filter args come in these forms, and they're lowkey the ✨spice✨ of btrbk:

  • <group-name> — matches the group config option of your volume, subvolume or target sections. group chat but make it btrfs 💅
  • <hostname>[:<port>] — matches the hostname portion that lives inside <url> of volume or target sections. (yes the :port part is optional, she's flexible 🦋)
  • <directory>|<url> — matches volume, subvolume or target sections by either a relative or absolute path. "Absolute" here means it starts with / or ssh:// or <hostname>:/ — and yes, the wildcard character * is accepted, she's inclusive like that 🌈

Relative paths are matched against the end of the pathname. So it's giving "last few characters of the vibe", not "start of the vibe". Either:

  • <volume-directory> — matches volume sections 📁
  • <volume-directory>/<subvolume-name> — matches subvolume sections 🌸
  • <volume-directory>/<snapshot-dir>/<snapshot-name> — matches subvolume sections that define snapshots with the configured snapshot_dir and snapshot_name ✨
  • <target-directory> — matches target sections 🎯
  • <target-directory>/<snapshot-name> — matches target sections within subvolume sections that define snapshots with the configured snapshot_name 💖

Accepted formats for <url> are literally just these two:

ssh://<hostname>[:<port>]/<directory>
<hostname>:<directory>
⚠️ heads up bestie, this one matters: for the run and snapshot commands, a filter matching a target configuration section also enables snapshot creation of the surrounding subvolume section. Like, surprise! It came with a friend 🙈 If that is not the desired behaviour, consider running the snapshot and resume commands separately instead.

Also, filter statements can match multiple times (e.g. on group as well as on host name). In such a case, all matches are processed. Not me getting three hits on one filter 😭 she's popular!

📂 FILES

  • /etc/btrbk.conf, /etc/btrbk/btrbk.conf — the default configuration file 🎀 The file format and all the configuration options are described in btrbk.conf(5). go read her, she's the blueprint 💜

🚦 EXIT STATUS

btrbk returns the following error codes, and ngl you should memorise these, they're the group chat receipts:

  • 0 — No problems occurred. slay ✨ we love a clean exit 👑
  • 1 — Generic error code. the "something happened and we're not elaborating" one 💀
  • 2 — Parse error: when parsing command-line options or configuration file. she couldn't read your handwriting bestie 😭
  • 3 — Lockfile error: if lockfile is present on startup. she's already busy, she's booked and blessed, come back later 🎀
  • 10 — Backup abort: At least one backup task aborted. not the backup catching a case of the aborts 🙈
  • 255 — Script error. the big dramatic finale 💅

🌐 AVAILABILITY

Please refer to the btrbk project page https://digint.ch/btrbk/ for further details. she's got a whole website, she's an icon fr fr ⭐

👀 SEE ALSO

For more information about btrfs and incremental backups, see the web site at https://btrfs.wiki.kernel.org/index.php/Incremental_Backup — the lore goes deep bestie, iykyk 📚🦋

👑 AUTHOR

Axel Burri axel@tty0.ch — thank you for the gift, king 🫶✨

and that's a wrap on this whole page 🎀 huge thanks to the btrbk crew — this is Btrbk 0.32.7, dated 2026-07-19, and that's the BTRBK(1) manual page, done and dusted. go make some snapshots bestie, you've got this 💖🌸✨

📦 where this page comes from