NAME¶
btrbk - 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¶
btrbk is a backup tool for btrfs subvolumes, taking
advantage of btrfs specific capabilities to create atomic snapshots and
transfer them incrementally to a target btrfs filesystem. It is able to
perform backups from one source to multiple destinations.
For most operations, btrbk requires root privileges
to run correctly. Alternatively, consider using "btrfs-progs-sudo"
or "btrfs-progs-btrbk" backends, both of which allows you to run
btrbk as a regular user. Refer to configuration option backend in
btrbk.conf(5) for more details.
Snapshots and Backups¶
Snapshots as well as backup subvolumes are created in the
form:
<snapshot-name>.<timestamp>[_N]
Where <snapshot-name> is identical to the source
subvolume name, unless the configuration option snapshot_name is set.
<timestamp> is a timestamp describing the creation time (local
time of the host running btrbk) of the snapshot/backup. The format can be
configured using the timestamp_format option, refer to btrbk.conf(5)
for details. If multiple snapshots/backups are created on the same
date/time, N will be incremented on each snapshot, starting at 1.
If a snapshot or backup does not match the naming scheme above
(e.g. if it has been renamed manually), btrbk will leave it untouched.
Note that in btrfs terminology, a snapshot is a
“subvolume with a given initial content of the original
subvolume” (showing a parent-uuid, see btrfs-subvolume(8)), and they
can be read-write (default) or read-only. In btrbk terminology,
snapshot means “read-only btrfs snapshot”, and
backup means “read-only subvolume created with
send/receive” (showing a received-uuid).
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 in conjunction
with -l debug to see the 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 specified in the configuration file (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 configured snapshot retention policy, delete all
but the latest snapshots instead. All snapshots needed for incremental backup
(latest common) are also preserved. Useful if you are 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 (not available for all
commands).
--format table|long|raw|col:[h:]<columns>
Print output in specified format. If set to
"raw", prints space-separated, quoted key=value pairs (machine
readable).
If set to "col:", prints only the <columns>
specified (comma-separated list). Header lines are ommitted 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).
-S, --print-schedule
Print detailed scheduler information on run,
snapshot, resume, prune and archive commands. Use
the --format command line option to switch between different output
formats.
--progress
Show progress bar on send-receive operation. Requires
"mbuffer" command (version >= 20180505) installed on the host
running btrbk.
--lockfile <file>
Create lockfile <file> on startup; checks lockfile
before running any btrfs commands (using perl "flock"), and exits if
the lock is held by another btrbk instance. Overrides configuration option
"lockfile". Ignored on dryrun (-n, --dry-run).
--override <config_option>=<value>
Override a configuration option <config_option>
with <value>. Globally, for ALL contexts. Use with care!
COMMANDS¶
Actions¶
The following commands are used to create snapshots and/or
backups. All actions can operate in dry-run mode (-n,
--dry-run). Use the --format command line option to switch
between different output formats.
See section RETENTION POLICY in btrbk.conf(5) for
information on configuring the retention policy.
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).
Step 0: Read Data
Read information from the source and target btrfs
filesystems in order to perform sanity checks and identify parent/child and
received-from relationships.
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.
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.
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).
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).
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.
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.
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
The following commands are informative only, and will not alter
the file system.
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.
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.
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¶
Filter arguments are accepted in form:
<group-name>
Matches the group configuration option of
volume, subvolume or target sections.
<hostname>[:<port>]
Matches the hostname portion from
<url> of volume or target sections.
<directory>|<url>
Matches
volume,
subvolume or
target
sections by either relative or absolute path (if starting with "/"
or "
ssh://" or "<hostname>:/"), accepting wildcard
character "*". Relative paths are matched against the end of the
pathname. Either:
<volume-directory>
Matches volume sections.
<volume-directory>/<subvolume-name>
Matches subvolume sections.
<volume-directory>/<snapshot-dir>/<snapshot-name>
Matches subvolume sections defining snapshots with
the configured snapshot_dir and snapshot_name.
<target-directory>
Matches target sections.
<target-directory>/<snapshot-name>
Matches target sections within subvolume
sections defining snapshots with the configured snapshot_name.
Accepted formats for <url> are:
ssh://<hostname>[:<port>]/<directory>
<hostname>:<directory>
Note that for run and snapshot commands, a filter
matching a target configuration section also enables snapshot
creation of the surrounding subvolume section. If this is not
desired, consider running snapshot and resume commands
separately.
Filter statements can match multiple times (e.g. on group as well
as host name). In such a case, all matches are processed.
FILES¶
/etc/btrbk.conf,
/etc/btrbk/btrbk.conf
Default configuration file. The file format and
configuration options are described in
btrbk.conf(5).
EXIT STATUS¶
btrbk returns the following error codes:
0
No problems occurred.
1
Generic error code.
2
Parse error: when parsing command-line options or
configuration file.
3
Lockfile error: if lockfile is present on startup.
10
Backup abort: At least one backup task aborted.
255
Script error.
AUTHOR¶
Axel Burri <axel@tty0.ch>
