btrbk/doc/btrbk.1

.TH "btrbk" "1" "2015-09-02" "btrbk v0.20.0" ""
.\" 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>]
      [\-p|\-\-preserve] [\-r|\-\-resume\-only]
      [\-v|\-\-verbose] [\-q|\-\-quiet] [\-l|\-\-loglevel <level>] [\-\-progress]
      <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 target volumes. 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
<source_name>.YYYYMMDD[_N]
.RE
.PP
Where YYYY is the year, MM is the month, and DD is the day of
creation, and, if multiple backups are created on the same day, N will
be incremented on each backup, 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
\-c, \-\-config <file>
.RS 4
Read the configuration from <file>.
.RE
.PP
\-p, \-\-preserve
.RS 4
Preserve all backups. Skips deletion of old backups, even if specified
in the configuration file.
.RE
.PP
\-r, \-\-resume-only
.RS 4
Resume only. Skips snapshot creation, only resumes missing
backups. This only makes sense if the \fIresume_missing\fR option is
set to \[lq]yes\[rq] in the configuration file.
.RE
.PP
\-v, \-\-verbose
.RS 4
Verbose output. Identical to: \-l 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
\-\-raw\-output
.RS 4
Print raw (machine-readable) output. Changes output format for
\fBrun\fR, \fBdryrun\fR and \fBtree\fR. Useful for further scripting.
.RE
.PP
\-\-progress
.RS 4
Show progress bar on send-receive operation.
.RE
.SH COMMANDS
.PP
.B run
[filter...]
.RS 4
Perform backup operations as specified in the configuration file. If
the optional [filter...] arguments are present, 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 all the source
subvolumes specified in the configuration file.
.PP
Then, for each specified target, btrbk creates the backups as follows:
If the \fIresume_missing\fR option is set (the default), btrbk
transfers all missing snapshots needed to satisfy the configured
\fItarget_preserve_{daily,weekly,monthly}\fR retention policy, always
incrementally from the latest common parent subvolume found. If no
common parent subvolume is found, a full backup is created for the
first transfer. Note that the latest snapshot (the one created in the
first step) is always transferred, regardless of the retention policy.
.PP
As a last step, unless the -p (preserve backups) option is set,
snapshots and backup subvolumes that are not preserved by their
configured retention policy will be deleted. Note that the latest
snapshot as well as the latest backup is always preserved, regardless
of the retention policy.
.PP
If the \-\-raw\-output command line option is set, print the output in
the following format:
.PP
.RS 4
snapshot <snapshot-url> <src-subvol-url>
...
.RE
.RS 4
receive <target-url> <src-subvol-url> [<parent-subvol-url>]
...
.RE
.RS 4
delete <target-url>
...
.RE
.RS 4
aborted [volume|subvolume|target] <url> -- abort_reason
...
.RE
.RE
.PP
.B dryrun
[filter...]
.RS 4
Don't run btrfs commands, 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 info
[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 tree
[filter...]
.RS 4
Print the snapshots and their corresponding backup subvolumes as a
tree. Optionally filtered by [filter...] arguments (see \fIFILTER
STATEMENTS\fR below).
.PP
If the \-\-raw\-output command line option is set, print the output in
the following format:
.PP
.RS 4
<subvol-url> <snapshot-url> <received-from-url>
...
.RE
.RE
.PP
.B origin
<subvolume>
.RS 4
Print origin information for the given backup subvolume, showing the
parent-child relationship as well as the received-from information.
.RE
.PP
.B diff
<from> <to>
.RS 4
Print new files since subvolume <from> for subvolume <to>.
.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:",
"{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
.sp
\fBbtrbk\fR returns a zero exit status if it succeeds. Non-zero is
returned in case of failure.
.SH AVAILABILITY
Please refer to the btrbk project page
\fBhttp://www.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>