mirror of https://github.com/digint/btrbk
412 lines
12 KiB
Groff
412 lines
12 KiB
Groff
.TH "btrbk" "1" "2017-08-21" "btrbk v0.26.0-dev" ""
|
|
.\" 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]
|
|
[\-\-preserve\-snapshots] [\-\-preserve\-backups]
|
|
[\-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, \fBsnapshot\fR, \fBresume\fR, \fBarchive\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 (shortcut for
|
|
"\-\-preserve\-snapshots \-\-preserve\-backups").
|
|
.RE
|
|
.PP
|
|
\-\-preserve-snapshots
|
|
.RS 4
|
|
Preserve all snapshots. Skips deletion of any snapshots, even if
|
|
specified in the configuration file.
|
|
.RE
|
|
.PP
|
|
\-\-preserve-backups
|
|
.RS 4
|
|
Preserve all backups. Skips deletion of any backups, even if specified
|
|
in the configuration file.
|
|
.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 \fBrun\fR, \fBsnapshot\fR, \fBresume\fR, or
|
|
\fBarchive\fR commands.
|
|
.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, \fBsnapshot\fR, \fBresume\fR, \fBarchive\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, \fBsnapshot\fR,
|
|
\fBresume\fR and \fBarchive\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
|
|
.B Step 0: Read Data
|
|
.RS 4
|
|
Read information from the source and target btrfs filesystems in order
|
|
to perform sanity checks and identify parent/child and received-from
|
|
relationships.
|
|
.RE
|
|
.PP
|
|
.B Step 1: Create Snapshots
|
|
.RS 4
|
|
If the checks succeed, btrbk creates snapshots for the source
|
|
subvolumes specified in the configuration file, according to the
|
|
\fIsnapshot_create\fR option.
|
|
.RE
|
|
.PP
|
|
.B Step 2: Create Backups
|
|
.RS 4
|
|
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.
|
|
.RE
|
|
.PP
|
|
.B Step 3: Delete Backups
|
|
.RS 4
|
|
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.
|
|
.RE
|
|
.PP
|
|
.B Step 4: Delete Snapshots
|
|
.RS 4
|
|
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.
|
|
.RE
|
|
.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 snapshot
|
|
[filter...]
|
|
.RS 4
|
|
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).
|
|
.RE
|
|
.PP
|
|
.B resume
|
|
[filter...]
|
|
.RS 4
|
|
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).
|
|
.RE
|
|
.PP
|
|
.B prune
|
|
[filter...]
|
|
.RS 4
|
|
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).
|
|
.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). Note that the "free" value is an estimate of the
|
|
amount of data that can still be written to the file system.
|
|
.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>
|