NAME

btrbk − backup tool for btrfs volumes

SYNOPSIS

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.

Snapshots as well as backup subvolume names are created in form:

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

Where <snapshot−name> is identical to the source subvolume name, unless the configuration option snapshot_name is set. The <timestamp> is either "YYYYMMDD" or "YYYYMMDDThhmm" (dependent of the timestamp_format configuration option), where "YYYY" is the year, "MM" is the month, "DD" is the day, "hh" is the hour and "mm" is the minute of the creation time (local time of the host running btrbk). If multiple snapshots/backups are created on the same date/time, N will be incremented on each snapshot, starting at 1.

OPTIONS

−h, −−help

Prints the synopsis and a list of the commands.

−−version

Prints the btrbk version.

−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 and clean commands. Use in conjunction with −l debug to see the btrfs commands that would be executed.

−c, −−config <file>

Read the configuration from <file>.

−p, −−preserve

Preserve all snapshots and backups. Skips deletion of any snapshots and backups, even if specified in the configuration file.

−r, −−resume-only

Resume only. Skips snapshot creation, only resumes missing backups to satisfy the target retention policy.

−v, −−verbose

Verbose output (shortcut for "−−loglevel=info").

−q, −−quiet

Quiet operation. If set, btrbk does not print the summary after executing the "run" command.

−l, −−loglevel <level>

Set the level of verbosity. Accepted levels are warn, info, debug, and trace.

−t, −−table

Print output in table format (shortcut for "−−format=table").

−−format table|long|raw

Print output in specified format. If set to "raw", prints space-separated key="value" pairs (machine readable). Affects output format for run, dryrun and list commands. Useful for further exporting/scripting.

−−progress

Show progress bar on send-receive operation.

−−print−schedule

Print detailed scheduler information on run and dryrun commands. Use the −−format command line option to switch between different output formats.

−−override <config_option>=<value>

Override a configuration option <config_option> with <value>. Globally, for ALL contexts. Use with care!

−−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).

COMMANDS

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 below).

First, btrbk reads information from the source and target btrfs filesystems in order to perform sanity checks and identify parent/child and received-from relationships.

If the checks succeed, btrbk creates snapshots for the source subvolumes specified in the configuration file, according to the snapshot_create option.

Then, 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.

As a last step, unless the −p (−−preserve) option is set, snapshots and backup subvolumes that are not preserved by their configured retention policy will be deleted. Note that the latest snapshot (the one created in the first step) as well as the latest snapshot/backup pair are always preserved, regardless of the retention policy.

See section RETENTION POLICY in btrbk.conf(5) for information on configuring the retention policy.

Use the −−format command line option to switch between different output formats.

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.

archive <source> <target> *experimental*

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> (see bugs below). 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.

Note that this feature needs a linux kernel >=4.4 to work correctly! Kernels >=4.1 and <4.4 have a bug when re-sending subvolumes (the archived subvolumes will have incorrect received_uuid, see <http://thread.gmane.org/gmane.comp.file−systems.btrfs/48798>), so make sure you run a recent kernel.

Known bugs: 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.

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:

	snapshots		All snapshots (and corresponding backups).
	backups		All backups (and corresponding snapshots).
	latest		Most recent common snapshot/backup pair, or most recent snapshot if no common found.
	config		Configured source/snapshot/target relations.
	source		Configured source/snapshot relations.
	volume		Configured volume sections.
	target		Configured targets.

Use the −−format command line option to switch between different output formats.

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.

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>

Print new files since subvolume <from> for subvolume <to>.

config print|print−all

Prints the parsed configuration file. Use the −−format command line option to switch between different output formats.

FILTER STATEMENTS

Filter arguments are accepted in form:

[hostname:]<volume−directory>

Matches all subvolumes and targets of a volume configuration section.

[hostname:]<volume−directory>/<subvolume−name>

Matches the specified subvolume and all targets of a subvolume configuration section.

[hostname:]<target−directory>

Matches all targets of a target configuration section.

[hostname:]<target−directory>/<snapshot−name>

Matches a single target of a target section within a subvolume section with given <snapshot−name>.

<group−name>

Matches the group configuration option of a volume, subvolume or target section.

For convenience, [hostname:] can be specified as either "hostname:" or "ssh://hostname/".

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.

AVAILABILITY

Please refer to the btrbk project page http://digint.ch/btrbk/ for further details.

AUTHOR

Axel Burri <axel@tty0.ch>

Document Archive: btrbk-0.25.0

btrbk-0.25.0