mirror of https://github.com/digint/btrbk
303 lines
8.1 KiB
Groff
303 lines
8.1 KiB
Groff
.TH "btrbk" "1" "2015-10-25" "btrbk v0.21.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>]
|
|
[\-n|\-\-dry\-run] [\-p|\-\-preserve] [\-r|\-\-resume\-only]
|
|
[\-v|\-\-verbose] [\-q|\-\-quiet] [\-l|\-\-loglevel <level>]
|
|
[\-t|\-\-table] [\-\-format <output\-format>]
|
|
[\-\-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
|
|
<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 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
|
|
\-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 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. Sets "\-l info", and prints detailed scheduler
|
|
information on "run" and "dryrun" commands.
|
|
.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, \fBlist\fR and \fBtree\fR
|
|
commands. Useful for further exporting/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
|
|
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 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 snapshots and backups.
|
|
.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 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
|
|
.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 "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://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>
|