btrbk/doc/btrbk.1

.TH "btrbk" "1" "2016-06-07" "btrbk v0.23.2" ""
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.SH NAME
btrbk \- backup tool for btrfs volumes
.SH SYNOPSIS
.nf
\fBbtrbk\fR [\-h|\-\-help] [\-\-version] [\-c|\-\-config <file>]
      [\-n|\-\-dry\-run] [\-p|\-\-preserve] [\-r|\-\-resume\-only]
      [\-v|\-\-verbose] [\-q|\-\-quiet] [\-l|\-\-loglevel <level>]
      [\-t|\-\-table] [\-\-format <output\-format>]
      [\-\-progress] [\-\-print\-schedule]
      <command> [<args>]
.fi
.SH DESCRIPTION
\fBbtrbk\fR 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.
.PP
Snapshots as well as backup subvolume names are created in form:
.PP
.RS 4
<snapshot\-name>.<timestamp>[_N]
.RE
.PP
Where <snapshot\-name> is identical to the source subvolume name,
unless the configuration option \fIsnapshot_name\fR is set. The
<timestamp> is either "YYYYMMDD" or "YYYYMMDDThhmm" (dependent of the
\fItimestamp_format\fR 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.
.SH OPTIONS
.PP
\-h, \-\-help
.RS 4
Prints the synopsis and a list of the commands.
.RE
.PP
\-\-version
.RS 4
Prints the btrbk version.
.RE
.PP
\-n, \-\-dry\-run
.RS 4
Don't run anything that would alter the filesystem, just show the
snapshots and backup subvolumes that would be created/deleted by the
\fBrun\fR and \fBclean\fR commands. Use in conjunction with \fI\-l
debug\fR to see the btrfs commands that would be executed.
.RE
.PP
\-c, \-\-config <file>
.RS 4
Read the configuration from <file>.
.RE
.PP
\-p, \-\-preserve
.RS 4
Preserve all snapshots and backups. Skips deletion of any snapshots
and backups, even if specified in the configuration file.
.RE
.PP
\-r, \-\-resume-only
.RS 4
Resume only. Skips snapshot creation, only resumes missing backups to
satisfy the target retention policy.
.RE
.PP
\-v, \-\-verbose
.RS 4
Verbose output (shortcut for "\-\-loglevel=info").
.RE
.PP
\-q, \-\-quiet
.RS 4
Quiet operation. If set, btrbk does not print the summary after
executing the "run" command.
.RE
.PP
\-l, \-\-loglevel <level>
.RS 4
Set the level of verbosity. Accepted levels are warn, info, debug,
and trace.
.RE
.PP
\-t, \-\-table
.RS 4
Print output in table format (shortcut for "\-\-format=table").
.RE
.PP
\-\-format table|long|raw
.RS 4
Print output in specified format. If set to "raw", prints
space-separated key="value" pairs (machine readable). Affects output
format for \fBrun\fR, \fBdryrun\fR and \fBlist\fR commands. Useful for
further exporting/scripting.
.RE
.PP
\-\-progress
.RS 4
Show progress bar on send-receive operation.
.RE
.PP
\-\-print\-schedule
.RS 4
Print detailed scheduler information on \fBrun\fR and \fBdryrun\fR
commands. Use the \fI\-\-format\fR command line option to switch
between different output formats.
.RE
.PP
\-\-override <config_option>=<value>
.RS 4
Override a configuration option <config_option> with <value>.
Globally, for ALL contexts. Use with care!
.RE
.PP
\-\-lockfile <file>
.RS 4
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 (\fI\-n\fR, \fI\-\-dry\-run\fR).
.RE
.SH COMMANDS
.PP
.B run
[filter...]
.RS 4
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 \fIFILTER STATEMENT\fR (see below).
.PP
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.
.PP
If the checks succeed, btrbk creates snapshots for the source
subvolumes specified in the configuration file, according to the
\fIsnapshot_create\fR option.
.PP
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
\fIincremental\fR option is set to \[lq]no\[rq]), a full
(non-incremental) backup is created.
.PP
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.
.PP
See section RETENTION POLICY in
.BR btrbk.conf (5)
for information on configuring the retention policy.
.PP
Use the \fI\-\-format\fR command line option to switch between
different output formats.
.RE
.PP
.B dryrun
[filter...]
.RS 4
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 \fBrun\fR command. Use in conjunction with \fI\-l debug\fR to
see the btrfs commands that would be executed.
.RE
.PP
.B archive
<source> <target>
.I *experimental*
.RS 4
Recursively copy all subvolumes created by btrbk from <source> to
<target> directory, optionally rescheduled using
\fIarchive_preserve_*\fR 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.
.PP
Note that this feature needs a \fBlinux kernel >=4.4\fR 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.
.PP
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.
.RE
.PP
.B stats
[filter...]
.RS 4
Print statistics of snapshot and backup subvolumes. Optionally
filtered by [filter...] arguments (see \fIFILTER STATEMENTS\fR below).
.RE
.PP
.B list
<subcommand> [filter...]
.RS 4
Print information defined by <subcommand> in a tabular form. Optionally
filtered by [filter...] arguments (see \fIFILTER STATEMENTS\fR
below).
.PP
Available subcommands:
.TP 11
.B snapshots
All snapshots (and corresponding backups).
.PD 0
.TP 11
.B backups
All backups (and corresponding snapshots).
.TP 11
.B latest
Most recent common snapshot/backup pair, or most recent snapshot if no
common found.
.TP 11
.B config
Configured source/snapshot/target relations.
.TP 11
.B source
Configured source/snapshot relations.
.TP 11
.B volume
Configured volume sections.
.TP 11
.B target
Configured targets.
.PD
.PP
Use the \fI\-\-format\fR command line option to switch between
different output formats.
.RE
.PP
.B clean
[filter...]
.RS 4
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.
.RE
.PP
.B usage
[filter...]
.RS 4
Print filesystem usage information for all source/target
volumes. Optionally filtered by [filter...] arguments (see \fIFILTER
STATEMENTS\fR below).
.RE
.PP
.B origin
<subvolume>
.RS 4
Print the subvolume origin tree: Shows the parent-child relationships
as well as the received-from information. Use the \fI\-\-format\fR
command line option to switch between different output formats.
.RE
.PP
.B diff
<from> <to>
.RS 4
Print new files since subvolume <from> for subvolume <to>.
.RE
.PP
.B config
print|print\-all
.RS 4
Prints the parsed configuration file. Use the \fI\-\-format\fR command
line option to switch between different output formats.
.RE
.SH FILTER STATEMENTS
Filter arguments are accepted in form:
.PP
[hostname:]<volume\-directory>
.RS 4
Matches all subvolumes and targets of a \fIvolume\fR configuration
section.
.RE
.PP
[hostname:]<volume\-directory>/<subvolume\-name>
.RS 4
Matches the specified subvolume and all targets of a \fIsubvolume\fR
configuration section.
.RE
.PP
[hostname:]<target\-directory>
.RS 4
Matches all targets of a \fItarget\fR configuration section.
.RE
.PP
[hostname:]<target\-directory>/<snapshot\-name>
.RS 4
Matches a single target of a \fItarget\fR section within a
\fIsubvolume\fR section with given <snapshot\-name>.
.RE
.PP
<group\-name>
.RS 4
Matches the \fIgroup\fR configuration option of a \fIvolume\fR,
\fIsubvolume\fR or \fItarget\fR section.
.RE
.PP
For convenience, [hostname:] can be specified as either "hostname:" or
"ssh://hostname/".
.SH FILES
.PP
/etc/btrbk.conf
.br
/etc/btrbk/btrbk.conf
.RS 4
Default configuration file. The file format and configuration options
are described in
.BR btrbk.conf (5).
.RE
.PD
.SH EXIT STATUS
\fBbtrbk\fR returns the following error codes:
.IP "0" 4
No problems occurred.
.IP "1" 4
Generic error code.
.IP "2" 4
Parse error: when parsing command-line options or configuration file.
.IP "3" 4
Lockfile error: if lockfile is present on startup.
.IP "10" 4
Backup abort: At least one backup task aborted.
.IP "255" 4
Script error.
.SH AVAILABILITY
Please refer to the btrbk project page \fBhttp://digint.ch/btrbk/\fR
for further details.
.SH SEE ALSO
.BR btrbk.conf (5),
.BR btrfs (1)
.PP
For more information about btrfs and incremental backups, see the web
site at https://btrfs.wiki.kernel.org/index.php/Incremental_Backup
.SH AUTHOR
Axel Burri <axel@tty0.ch>