mirror of https://github.com/digint/btrbk
documentation: remove pre-generated man pages
Package maintainers like to build everything from scratch, removing
overhead. Again, we apologize for the inconvenience.
Note that reproducible builds are still guaranteed by setting
SOURCE_DATE_EPOCH in doc/Makefile.
Reverts: a6dbd60e5a documentation: add pre-generated man pages: from groff to asciidoc and back again
pull/286/head
Axel Burri
parent
f54853dd18
commit
ef69f1ffee
|
|
@ -1 +1,2 @@
|
|||
*.[1-8]
|
||||
*.[1-8].gz
|
||||
|
|
|
|||
561
doc/btrbk.1
561
doc/btrbk.1
|
|
@ -1,561 +0,0 @@
|
|||
'\" t
|
||||
.\" Title: btrbk
|
||||
.\" Author: [see the "AUTHOR(S)" section]
|
||||
.\" Generator: Asciidoctor 1.5.7.1
|
||||
.\" Date: 2019-04-24
|
||||
.\" Manual: Btrbk Manual
|
||||
.\" Source: Btrbk 0.28.0
|
||||
.\" Language: English
|
||||
.\"
|
||||
.TH "BTRBK" "1" "2019-04-24" "Btrbk 0.28.0" "Btrbk Manual"
|
||||
.ie \n(.g .ds Aq \(aq
|
||||
.el .ds Aq '
|
||||
.ss \n[.ss] 0
|
||||
.nh
|
||||
.ad l
|
||||
.de URL
|
||||
\fI\\$2\fP <\\$1>\\$3
|
||||
..
|
||||
.als MTO URL
|
||||
.if \n[.g] \{\
|
||||
. mso www.tmac
|
||||
. am URL
|
||||
. ad l
|
||||
. .
|
||||
. am MTO
|
||||
. ad l
|
||||
. .
|
||||
. LINKSTYLE blue R < >
|
||||
.\}
|
||||
.SH "NAME"
|
||||
btrbk \- backup tool for btrfs subvolumes
|
||||
.SH "SYNOPSIS"
|
||||
.sp
|
||||
.nf
|
||||
btrbk [\-h|\-\-help] [\-\-version]
|
||||
[\-c|\-\-config <file>] [\-n|\-\-dry\-run] [\-\-exclude <filter>]
|
||||
[\-p|\-\-preserve] [\-\-preserve\-snapshots] [\-\-preserve\-backups]
|
||||
[\-v|\-\-verbose] [\-q|\-\-quiet] [\-l|\-\-loglevel <level>]
|
||||
[\-t|\-\-table] [\-\-format <output\-format>]
|
||||
[\-S|\-\-print\-schedule] [\-\-progress]
|
||||
[\-\-lockfile <file>]
|
||||
[\-\-override <config_option>=<value>]
|
||||
<command> [<args>]
|
||||
.fi
|
||||
.br
|
||||
.SH "DESCRIPTION"
|
||||
.sp
|
||||
\fBbtrbk\fP 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.
|
||||
.sp
|
||||
For most operations, \fBbtrbk\fP requires \fIroot privileges\fP to run
|
||||
correctly. Alternatively, consider using "btrfs\-progs\-sudo" or
|
||||
"btrfs\-progs\-btrbk" backends, both of which allows you to run btrbk as
|
||||
a regular user. Refer to configuration option \fIbackend\fP in
|
||||
btrbk.conf(5) for more details.
|
||||
.SS "Snapshots and Backups"
|
||||
.sp
|
||||
Snapshots as well as backup subvolumes are created in form:
|
||||
.sp
|
||||
.if n .RS 4
|
||||
.nf
|
||||
<snapshot\-name>.<timestamp>[_N]
|
||||
.fi
|
||||
.if n .RE
|
||||
.sp
|
||||
Where \fI<snapshot\-name>\fP is identical to the source subvolume name,
|
||||
unless the configuration option \fIsnapshot_name\fP is set. The
|
||||
<timestamp> is either "YYYYMMDD" or "YYYYMMDDThhmm" (dependent of the
|
||||
\fItimestamp_format\fP 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.
|
||||
.sp
|
||||
Note that \fIsnapshot\fP is a btrfs terminology for a \(lqread\-only
|
||||
subvolume\(rq (showing a parent\-uuid, see btrfs\-subvolume(8)); \fIbackup\fP
|
||||
is a btrbk terminology for a \(lqread\-only subvolume created with
|
||||
send/receive\(rq (showing a received\-uuid).
|
||||
.SH "OPTIONS"
|
||||
.sp
|
||||
\-h, \-\-help
|
||||
.RS 4
|
||||
Prints the synopsis and a list of the commands.
|
||||
.RE
|
||||
.sp
|
||||
\-\-version
|
||||
.RS 4
|
||||
Prints the btrbk version.
|
||||
.RE
|
||||
.sp
|
||||
\-c, \-\-config <file>
|
||||
.RS 4
|
||||
Read the configuration from <file>.
|
||||
.RE
|
||||
.sp
|
||||
\-n, \-\-dry\-run
|
||||
.RS 4
|
||||
Don\(cqt run anything that would alter the filesystem, just show the
|
||||
snapshots and backup subvolumes that would be created/deleted by
|
||||
the \fBrun\fP, \fBsnapshot\fP, \fBresume\fP, \fBprune\fP, \fBarchive\fP and \fBclean\fP
|
||||
commands. Use in conjunction with \fI\-l debug\fP to see the btrfs
|
||||
commands that would be executed.
|
||||
.RE
|
||||
.sp
|
||||
\-\-exclude <filter>
|
||||
.RS 4
|
||||
Exclude configured sections matching \fI<filter>\fP. See
|
||||
FILTER STATEMENTS below
|
||||
.RE
|
||||
.sp
|
||||
\-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
|
||||
.sp
|
||||
\-\-preserve\-snapshots
|
||||
.RS 4
|
||||
Preserve all snapshots. Skips deletion of any snapshots, even if
|
||||
specified in the configuration file.
|
||||
.RE
|
||||
.sp
|
||||
\-\-preserve\-backups
|
||||
.RS 4
|
||||
Preserve all backups. Skips deletion of any backups, even if
|
||||
specified in the configuration file.
|
||||
.RE
|
||||
.sp
|
||||
\-\-wipe
|
||||
.RS 4
|
||||
Ignore configured snapshot retention policy, delete all but latest
|
||||
snapshots instead. All snapshots needed for incremental backup
|
||||
(latest common) are also preserved. Useful if you are getting low
|
||||
on disk space (ENOSPC).
|
||||
.RE
|
||||
.sp
|
||||
\-v, \-\-verbose
|
||||
.RS 4
|
||||
Verbose output (shortcut for "\-\-loglevel=info").
|
||||
.RE
|
||||
.sp
|
||||
\-q, \-\-quiet
|
||||
.RS 4
|
||||
Quiet operation. If set, btrbk does not print the summary after
|
||||
executing the \fBrun\fP, \fBsnapshot\fP, \fBresume\fP, \fBprune\fP, or \fBarchive\fP
|
||||
commands.
|
||||
.RE
|
||||
.sp
|
||||
\-l, \-\-loglevel <level>
|
||||
.RS 4
|
||||
Set the level of verbosity. Accepted levels are warn, info, debug,
|
||||
and trace.
|
||||
.RE
|
||||
.sp
|
||||
\-t, \-\-table
|
||||
.RS 4
|
||||
Print output in table format (shortcut for "\-\-format=table").
|
||||
.RE
|
||||
.sp
|
||||
\-\-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\fP, \fBsnapshot\fP, \fBresume\fP, \fBprune\fP, \fBarchive\fP
|
||||
and \fBlist\fP commands. Useful for further exporting/scripting.
|
||||
.RE
|
||||
.sp
|
||||
\-S, \-\-print\-schedule
|
||||
.RS 4
|
||||
Print detailed scheduler information on \fBrun\fP, \fBsnapshot\fP,
|
||||
\fBresume\fP, \fBprune\fP and \fBarchive\fP commands. Use the \fI\-\-format\fP
|
||||
command line option to switch between different output formats.
|
||||
.RE
|
||||
.sp
|
||||
\-\-progress
|
||||
.RS 4
|
||||
Show progress bar on send\-receive operation.
|
||||
.RE
|
||||
.sp
|
||||
\-\-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\fP, \fI\-\-dry\-run\fP).
|
||||
.RE
|
||||
.sp
|
||||
\-\-override <config_option>=<value>
|
||||
.RS 4
|
||||
Override a configuration option <config_option> with
|
||||
<value>. Globally, for ALL contexts. Use with care!
|
||||
.RE
|
||||
.SH "COMMANDS"
|
||||
.SS "Actions"
|
||||
.sp
|
||||
The following commands are used to create snapshots and/or
|
||||
backups. All actions can operate in dry\-run mode (\fI\-n\fP, \fI\-\-dry\-run\fP).
|
||||
Use the \fI\-\-format\fP command line option to switch between different
|
||||
output formats.
|
||||
.sp
|
||||
See section RETENTION POLICY in \fBbtrbk.conf\fP(5) for information on
|
||||
configuring the retention policy.
|
||||
.sp
|
||||
\fBrun\fP [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 filter statement (see
|
||||
FILTER STATEMENTS below).
|
||||
.sp
|
||||
\fBStep 0: Read Data\fP
|
||||
.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
|
||||
.sp
|
||||
\fBStep 1: Create Snapshots\fP
|
||||
.RS 4
|
||||
If the checks succeed, btrbk creates snapshots for the source
|
||||
subvolumes specified in the configuration file, according to the
|
||||
\fIsnapshot_create\fP option.
|
||||
.RE
|
||||
.sp
|
||||
\fBStep 2: Create Backups\fP
|
||||
.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\fP option is set to \(lqno\(rq), a full
|
||||
(non\-incremental) backup is created.
|
||||
.RE
|
||||
.sp
|
||||
\fBStep 3: Delete Backups\fP
|
||||
.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
|
||||
.sp
|
||||
\fBStep 4: Delete Snapshots\fP
|
||||
.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
|
||||
.RE
|
||||
.sp
|
||||
\fBdryrun\fP [filter...]
|
||||
.RS 4
|
||||
Don\(cqt run any btrfs commands that would alter the filesystem, just
|
||||
show the snapshots and backup subvolumes that would be
|
||||
created/deleted by the \fBrun\fP command. Use in conjunction with \fI\-l
|
||||
debug\fP to see the btrfs commands that would be executed.
|
||||
.RE
|
||||
.sp
|
||||
\fBsnapshot\fP [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).
|
||||
.sp
|
||||
Note that snapshot deletion is skipped if the target is not
|
||||
accessible, as it is still required in order to determine the latest
|
||||
snapshot/backup pair (which is always preserved, regardless of the
|
||||
retention policy).
|
||||
.RE
|
||||
.sp
|
||||
\fBresume\fP [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
|
||||
.sp
|
||||
\fBprune\fP [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).
|
||||
.sp
|
||||
Note that deletion is skipped if source or target is not accessible,
|
||||
as it is still required in order to determine the latest
|
||||
snapshot/backup pair (which is always preserved, regardless of the
|
||||
retention policy).
|
||||
.RE
|
||||
.sp
|
||||
\fBarchive\fP <source> <target>
|
||||
.RS 4
|
||||
Recursively copy all subvolumes created by btrbk from <source> to
|
||||
<target> directory, optionally rescheduled using
|
||||
\fIarchive_preserve_*\fP configuration options. Also creates directory
|
||||
tree on <target>. 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.
|
||||
.sp
|
||||
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.
|
||||
.sp
|
||||
Note that this feature needs a \fBlinux kernel >=4.4\fP to work correctly!
|
||||
.RE
|
||||
.sp
|
||||
\fBclean\fP [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
|
||||
.sp
|
||||
The following table gives a quick overview of the action commands and
|
||||
resulting snapshot creation (S+), backup creation (B+), snapshot
|
||||
deletion (S\-), and backup deletion (B\-):
|
||||
.sp
|
||||
.if n .RS 4
|
||||
.nf
|
||||
Command Option S+ B+ S\- B\-
|
||||
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
||||
run x x x x
|
||||
run \-\-preserve x x
|
||||
run \-\-preserve\-snapshots x x x
|
||||
run \-\-preserve\-backups x x x
|
||||
snapshot x x
|
||||
snapshot \-\-preserve x
|
||||
resume x x x
|
||||
resume \-\-preserve x
|
||||
resume \-\-preserve\-snapshots x x
|
||||
resume \-\-preserve\-backups x x
|
||||
prune x x
|
||||
prune \-\-preserve\-snapshots x
|
||||
prune \-\-preserve\-backups x
|
||||
.fi
|
||||
.if n .RE
|
||||
.SS "Informative Commands"
|
||||
.sp
|
||||
The following commands are informative only, and will not alter the
|
||||
file system.
|
||||
.sp
|
||||
\fBstats\fP [filter...]
|
||||
.RS 4
|
||||
Print statistics of snapshot and backup subvolumes. Optionally
|
||||
filtered by [filter...] arguments (see FILTER
|
||||
STATEMENTS below).
|
||||
.RE
|
||||
.sp
|
||||
\fBlist\fP <subcommand> [filter...]
|
||||
.RS 4
|
||||
Print information defined by <subcommand> in a tabular
|
||||
form. Optionally filtered by [filter...] arguments (see
|
||||
FILTER STATEMENTS below).
|
||||
.sp
|
||||
Available subcommands:
|
||||
.sp
|
||||
\fBsnapshots\fP
|
||||
.RS 4
|
||||
List all snapshots (and corresponding backups). Note
|
||||
that all snapshots related to configured subvolumes are
|
||||
listed, not only the ones created by btrbk.
|
||||
.RE
|
||||
.sp
|
||||
\fBbackups\fP
|
||||
.RS 4
|
||||
List all backups (and corresponding snapshots).
|
||||
.RE
|
||||
.sp
|
||||
\fBlatest\fP
|
||||
.RS 4
|
||||
List most recent common snapshot/backup pair, or most
|
||||
recent snapshot if no common found.
|
||||
.RE
|
||||
.sp
|
||||
\fBconfig\fP
|
||||
.RS 4
|
||||
List configured source/snapshot/target relations.
|
||||
.RE
|
||||
.sp
|
||||
\fBsource\fP
|
||||
.RS 4
|
||||
List configured source/snapshot relations.
|
||||
.RE
|
||||
.sp
|
||||
\fBvolume\fP
|
||||
.RS 4
|
||||
List configured volume sections.
|
||||
.RE
|
||||
.sp
|
||||
\fBtarget\fP
|
||||
.RS 4
|
||||
List configured targets.
|
||||
.RE
|
||||
.sp
|
||||
Use the \fI\-\-format\fP command line option to switch between
|
||||
different output formats.
|
||||
.RE
|
||||
.sp
|
||||
\fBusage\fP [filter...]
|
||||
.RS 4
|
||||
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.
|
||||
.RE
|
||||
.sp
|
||||
\fBorigin\fP <subvolume>
|
||||
.RS 4
|
||||
Print the subvolume origin tree: Shows the parent\-child
|
||||
relationships as well as the received\-from information. Use the
|
||||
\fI\-\-format\fP command line option to switch between different output
|
||||
formats.
|
||||
.RE
|
||||
.sp
|
||||
\fBdiff\fP <from> <to>
|
||||
.RS 4
|
||||
Print new files since subvolume <from> for subvolume <to>.
|
||||
.RE
|
||||
.sp
|
||||
\fBconfig\fP print|print\-all
|
||||
.RS 4
|
||||
Prints the parsed configuration file. Use the \fI\-\-format\fP command
|
||||
line option to switch between different output formats.
|
||||
.RE
|
||||
.SH "FILTER STATEMENTS"
|
||||
.sp
|
||||
Filter arguments are accepted in form:
|
||||
.sp
|
||||
<group\-name>
|
||||
.RS 4
|
||||
Matches the \fIgroup\fP configuration option of \fIvolume\fP, \fIsubvolume\fP
|
||||
or \fItarget\fP sections.
|
||||
.RE
|
||||
.sp
|
||||
<hostname>[:<port>]
|
||||
.RS 4
|
||||
Matches the \fIhostname\fP portion from \fI<url>\fP of \fIvolume\fP or
|
||||
\fItarget\fP sections.
|
||||
.RE
|
||||
.sp
|
||||
<directory>|<url>
|
||||
.RS 4
|
||||
Matches \fIvolume\fP, \fIsubvolume\fP or \fItarget\fP sections by either
|
||||
relative or absolute path (if starting with "/" or "ssh://" or
|
||||
"<hostname>:/"), accepting wildcard character "*". Relative paths
|
||||
are matched against the end of the pathname. Either:
|
||||
.sp
|
||||
<volume\-directory>
|
||||
.RS 4
|
||||
Matches \fIvolume\fP sections.
|
||||
.RE
|
||||
.sp
|
||||
<volume\-directory>/<subvolume\-name>
|
||||
.RS 4
|
||||
Matches \fIsubvolume\fP sections.
|
||||
.RE
|
||||
.sp
|
||||
<volume\-directory>/<snapshot\-dir>/<snapshot\-name>
|
||||
.RS 4
|
||||
Matches \fIsubvolume\fP sections defining snapshots with the
|
||||
configured \fIsnapshot_dir\fP and \fIsnapshot_name\fP.
|
||||
.RE
|
||||
.sp
|
||||
<target\-directory>
|
||||
.RS 4
|
||||
Matches \fItarget\fP sections.
|
||||
.RE
|
||||
.sp
|
||||
<target\-directory>/<snapshot\-name>
|
||||
.RS 4
|
||||
Matches \fItarget\fP sections within \fIsubvolume\fP sections defining
|
||||
snapshots with the configured \fIsnapshot_name\fP.
|
||||
.RE
|
||||
.sp
|
||||
Accepted formats for \fI<url>\fP are:
|
||||
.sp
|
||||
.if n .RS 4
|
||||
.nf
|
||||
ssh://<hostname>[:<port>]/<directory>
|
||||
<hostname>:<directory>
|
||||
.fi
|
||||
.if n .RE
|
||||
.RE
|
||||
.sp
|
||||
Note that for \fBrun\fP and \fBsnapshot\fP commands, a filter matching a
|
||||
\fItarget\fP configuration section also enables snapshot creation of the
|
||||
surrounding \fIsubvolume\fP section. If this is not desired, consider
|
||||
running \fBsnapshot\fP and \fBresume\fP commands separately.
|
||||
.SH "FILES"
|
||||
.sp
|
||||
\f(CR/etc/btrbk.conf\fP, \f(CR/etc/btrbk/btrbk.conf\fP
|
||||
.RS 4
|
||||
Default configuration file. The file format and configuration
|
||||
options are described in \fBbtrbk.conf\fP(5).
|
||||
.RE
|
||||
.SH "EXIT STATUS"
|
||||
.sp
|
||||
\fBbtrbk\fP returns the following error codes:
|
||||
.sp
|
||||
0
|
||||
.RS 4
|
||||
No problems occurred.
|
||||
.RE
|
||||
.sp
|
||||
1
|
||||
.RS 4
|
||||
Generic error code.
|
||||
.RE
|
||||
.sp
|
||||
2
|
||||
.RS 4
|
||||
Parse error: when parsing command\-line options or configuration
|
||||
file.
|
||||
.RE
|
||||
.sp
|
||||
3
|
||||
.RS 4
|
||||
Lockfile error: if lockfile is present on startup.
|
||||
.RE
|
||||
.sp
|
||||
10
|
||||
.RS 4
|
||||
Backup abort: At least one backup task aborted.
|
||||
.RE
|
||||
.sp
|
||||
255
|
||||
.RS 4
|
||||
Script error.
|
||||
.RE
|
||||
.SH "AVAILABILITY"
|
||||
.sp
|
||||
Please refer to the btrbk project page \fB\c
|
||||
.URL "https://digint.ch/btrbk/" "" "\fP"
|
||||
for further details.
|
||||
.SH "SEE ALSO"
|
||||
.sp
|
||||
\fBbtrbk.conf\fP(5),
|
||||
\fBbtrfs\fP(8)
|
||||
.sp
|
||||
For more information about btrfs and incremental backups, see the web
|
||||
site at \c
|
||||
.URL "https://btrfs.wiki.kernel.org/index.php/Incremental_Backup" "" ""
|
||||
.SH "AUTHOR"
|
||||
.sp
|
||||
Axel Burri <\c
|
||||
.MTO "axel\(attty0.ch" "" ">"
|
||||
744
doc/btrbk.conf.5
744
doc/btrbk.conf.5
|
|
@ -1,744 +0,0 @@
|
|||
'\" t
|
||||
.\" Title: btrbk.conf
|
||||
.\" Author: [see the "AUTHOR(S)" section]
|
||||
.\" Generator: Asciidoctor 1.5.7.1
|
||||
.\" Date: 2019-04-24
|
||||
.\" Manual: Btrbk Manual
|
||||
.\" Source: Btrbk 0.28.0
|
||||
.\" Language: English
|
||||
.\"
|
||||
.TH "BTRBK.CONF" "5" "2019-04-24" "Btrbk 0.28.0" "Btrbk Manual"
|
||||
.ie \n(.g .ds Aq \(aq
|
||||
.el .ds Aq '
|
||||
.ss \n[.ss] 0
|
||||
.nh
|
||||
.ad l
|
||||
.de URL
|
||||
\fI\\$2\fP <\\$1>\\$3
|
||||
..
|
||||
.als MTO URL
|
||||
.if \n[.g] \{\
|
||||
. mso www.tmac
|
||||
. am URL
|
||||
. ad l
|
||||
. .
|
||||
. am MTO
|
||||
. ad l
|
||||
. .
|
||||
. LINKSTYLE blue R < >
|
||||
.\}
|
||||
.SH "NAME"
|
||||
btrbk.conf \- btrbk configuration file
|
||||
.SH "SYNOPSIS"
|
||||
.sp
|
||||
.nf
|
||||
/etc/btrbk.conf
|
||||
/etc/btrbk/btrbk.conf
|
||||
.fi
|
||||
.br
|
||||
.SH "DESCRIPTION"
|
||||
.sp
|
||||
The btrbk configuration file specifies which btrfs subvolumes on the
|
||||
filesystem are to be processed, what target subvolumes should be used
|
||||
to create the backups, and where the snapshots should be
|
||||
generated. The retention policy, as well as most other options can be
|
||||
defined either globally or within a section.
|
||||
.sp
|
||||
The options specified always apply to the last section encountered,
|
||||
superseding the values set in upper\-level sections. This means that
|
||||
global options must be set before any sections are defined.
|
||||
.sp
|
||||
Blank lines are ignored. A hash character (#) starts a comment
|
||||
extending until end of line.
|
||||
.sp
|
||||
Whitespace or unicode characters are not allowed for file
|
||||
names. Allowed characters are:
|
||||
.sp
|
||||
.if n .RS 4
|
||||
.nf
|
||||
[0\-9] [a\-z] [A\-Z] and "._+\-@"
|
||||
.fi
|
||||
.if n .RE
|
||||
.sp
|
||||
This is for sanity/safety/security reasons, we apologize for the
|
||||
inconvenience.
|
||||
.SH "SECTIONS"
|
||||
.sp
|
||||
\fBvolume\fP <volume\-directory>|<url>
|
||||
.RS 4
|
||||
Directory of a btrfs volume containing the source subvolume(s) to
|
||||
be backed up. \fI<volume\-directory>\fP must be an absolute path and
|
||||
point to a btrfs volume (or subvolume). Usually the mount point of
|
||||
a btrfs filesystem mounted with the \fIsubvolid=5\fP option.
|
||||
.RE
|
||||
.sp
|
||||
\fBsubvolume\fP <subvolume\-name>
|
||||
.RS 4
|
||||
Subvolume to be backed up, relative to the \fI<volume\-directory>\fP
|
||||
specified in the \fIvolume\fP section. Multiple \fIsubvolume\fP sections
|
||||
are allowed within \fIvolume\fP sections. Accepts wildcard character
|
||||
"*".
|
||||
.sp
|
||||
If set to ".", the subvolume at \fI<volume\-directory>\fP is used as backup
|
||||
source, and the snapshots will be created within the source subvolume
|
||||
itself (see \fIsnapshot_dir\fP option below), which is not recommended.
|
||||
Note that if this subvolume is btrfs root (id=5), it needs to have a
|
||||
valid UUID, which is not the case for file systems created with
|
||||
btrfs\-progs < 4.16.
|
||||
.RE
|
||||
.sp
|
||||
\fBtarget\fP [send\-receive|raw] <target\-directory>|<url>
|
||||
.RS 4
|
||||
Target directory where the backup subvolumes are to be
|
||||
created. The optional target type defaults to \(lqsend\-receive\(rq,
|
||||
see TARGET TYPES below for details.
|
||||
.sp
|
||||
Multiple \fItarget\fP sections are allowed, in any context: a \fItarget\fP
|
||||
defined in \fIvolume\fP or global context will be used for all underlying
|
||||
\fIsubvolume\fP sections (hint: run "btrbk list" or "btrbk config print"
|
||||
to see the resulting configuration).
|
||||
.RE
|
||||
.sp
|
||||
If a \fI<url>\fP is specified, btrbk actions (shell commands) are executed
|
||||
remotely via ssh, using the SSH Options described
|
||||
below. Accepted formats are:
|
||||
.sp
|
||||
.if n .RS 4
|
||||
.nf
|
||||
ssh://<hostname>[:<port>]/<directory>
|
||||
<hostname>:<directory>
|
||||
.fi
|
||||
.if n .RE
|
||||
.sp
|
||||
If you are connecting to virtual machines, consider configuring
|
||||
several \fIvolume\fP sections for a \fI<hostname>\fP, with distinct \fI<port>\fP
|
||||
numbers for each machine.
|
||||
.SH "OPTIONS"
|
||||
.sp
|
||||
The options described here can be specified in \fIglobal context\fP as
|
||||
well as \fIvolume\fP, \fIsubvolume\fP and \fItarget\fP sections, unless stated
|
||||
otherwise.
|
||||
.SS "Basic Options"
|
||||
.sp
|
||||
\fBtimestamp_format\fP short|long|long\-iso
|
||||
.RS 4
|
||||
Timestamp format used as postfix for new snapshot subvolume
|
||||
names. Defaults to \(lqshort\(rq.
|
||||
.sp
|
||||
\fBshort\fP
|
||||
.RS 4
|
||||
\f(CRYYYYMMDD[_N]\fP (e.g. "20150825", "20150825_1")
|
||||
.RE
|
||||
.sp
|
||||
\fBlong\fP
|
||||
.RS 4
|
||||
\f(CRYYYYMMDD<T>hhmm[_N]\fP (e.g. "20150825T1531")
|
||||
.RE
|
||||
.sp
|
||||
\fBlong\-iso\fP
|
||||
.RS 4
|
||||
\f(CRYYYYMMDD<T>hhmmss±hhmm[_N]\fP (e.g. "20150825T153123+0200")
|
||||
.RE
|
||||
.sp
|
||||
Note that a postfix "_N" is appended to the timestamp if a snapshot or
|
||||
backup already exists with the timestamp of current date/time.
|
||||
.sp
|
||||
Use \(lqlong\-iso\(rq if you want to make sure that btrbk never
|
||||
creates ambiguous time stamps (which can happen if multiple
|
||||
snapshots are created during a daylight saving time clock
|
||||
change).
|
||||
.sp
|
||||
Note that using \(lqlong\-iso\(rq has implications on the scheduling, see
|
||||
RETENTION POLICY (caveats) below.
|
||||
.RE
|
||||
.sp
|
||||
\fBsnapshot_dir\fP <directory>
|
||||
.RS 4
|
||||
Directory in which the btrfs snapshots are created, relative to
|
||||
\fI<volume\-directory>\fP of the \fIvolume\fP section. Note that btrbk does
|
||||
not autmatically create this directory, and the snapshot creation
|
||||
will fail if it is not present.
|
||||
.RE
|
||||
.sp
|
||||
\fBsnapshot_name\fP <basename>
|
||||
.RS 4
|
||||
Base name of the created snapshot (and backup). This option is
|
||||
only valid in the \fIsubvolume\fP section. Defaults to
|
||||
\fI<subvolume\-name>\fP.
|
||||
.RE
|
||||
.sp
|
||||
\fBsnapshot_create\fP always|onchange|ondemand|no
|
||||
.RS 4
|
||||
If set to \(lqalways\(rq, snapshots are always created. If set to
|
||||
\(lqonchange\(rq, snapshots are only created if the source subvolume
|
||||
has changed since the last snapshot (more precisely: if the btrfs
|
||||
generation has been increased since the last snapshot). If set to
|
||||
\(lqondemand\(rq, snapshots are only created if at least one target
|
||||
subvolume is reachable (useful if you are tight on disk space and
|
||||
you only need btrbk for backups to an external disk which is not
|
||||
always connected). If set to \(lqno\(rq, the snapshots are never
|
||||
created (useful if another instance of btrbk is taking care of
|
||||
snapshot creation). Defaults to \(lqalways\(rq.
|
||||
.RE
|
||||
.sp
|
||||
\fBincremental\fP yes|no|strict
|
||||
.RS 4
|
||||
If set, incremental backups are created. If set to \(lqstrict\(rq,
|
||||
non\-incremental (initial) backups are never created, and
|
||||
incremental backups are restricted to \fIrelated parents\fP (by
|
||||
parent\-uuid relationship). Defaults to \(lqyes\(rq.
|
||||
.sp
|
||||
Note that even if the parent\-uuid chain is broken, snapshots and
|
||||
backups can still share data (which is especially true for backups
|
||||
created with \fIincremental\fP option enabled), and are perfectly suitable
|
||||
as parents for incremental send\-receive operations. But as btrbk can
|
||||
not be certain about this, such operations are disallowed in
|
||||
"incremental strict" mode.
|
||||
.RE
|
||||
.sp
|
||||
\fBnoauto\fP yes|no
|
||||
.RS 4
|
||||
If set, the context is skipped by all btrbk actions unless
|
||||
explicitely enabled by a matching btrbk \fI<filter>\fP command line
|
||||
argument (e.g. "btrbk run myfilter").
|
||||
.RE
|
||||
.SS "Grouping Options"
|
||||
.sp
|
||||
\fBgroup\fP <group\-name> [<group\-name>]...
|
||||
.RS 4
|
||||
Add the current section (volume, subvolume or target) to
|
||||
user\-defined groups, which can be used as filter for most btrbk
|
||||
commands. This option can be set multiple times within the same
|
||||
context.
|
||||
.RE
|
||||
.SS "Retention Policy Options"
|
||||
.sp
|
||||
\fBpreserve_day_of_week\fP monday|tuesday|...|sunday
|
||||
.RS 4
|
||||
Defines on what day a snapshot/backup is considered to be a
|
||||
"weekly" backup. Weekly, monthly and yearly backups are preserved
|
||||
on this day of week (see RETENTION POLICY
|
||||
below). Defaults to \(lqsunday\(rq.
|
||||
.RE
|
||||
.sp
|
||||
\fBpreserve_hour_of_day\fP [0..23]
|
||||
.RS 4
|
||||
Defines after what time (in full hours since midnight) a
|
||||
snapshot/backup is considered to be a "daily" backup. Daily,
|
||||
weekly, monthly and yearly backups are preserved on this hour (see
|
||||
RETENTION POLICY below). If you set this
|
||||
option, make sure to also set \fItimestamp_format\fP to \(lqlong\(rq or
|
||||
\(lqlong\-iso\(rq (backups and snapshots having no time information
|
||||
will ignore this option). Defaults to \(lq0\(rq.
|
||||
.RE
|
||||
.sp
|
||||
\fBsnapshot_preserve\fP no|<retention_policy>
|
||||
.RS 4
|
||||
Set retention policy for snapshots (see
|
||||
RETENTION POLICY below). If set to \(lqno\(rq,
|
||||
preserve snapshots according to \fIsnapshot_preserve_min\fP
|
||||
only. Defaults to \(lqno\(rq.
|
||||
.RE
|
||||
.sp
|
||||
\fBsnapshot_preserve_min\fP all|latest|<number>{h,d,w,m,y}
|
||||
.RS 4
|
||||
Preserve all snapshots for a minimum amount of hours (h), days
|
||||
(d), weeks (w), months (m) or years (y), regardless of how many
|
||||
there are. If set to \(lqall\(rq, preserve all snapshots forever. If
|
||||
set to \(lqlatest\(rq, preserve latest snapshot. Defaults to \(lqall\(rq.
|
||||
.RE
|
||||
.sp
|
||||
\fBtarget_preserve\fP no|<retention_policy>
|
||||
.RS 4
|
||||
Set retention policy for backups (see
|
||||
RETENTION POLICY below). If set to \(lqno\(rq,
|
||||
preserve backups according to \fItarget_preserve_min\fP only. Defaults
|
||||
to \(lqno\(rq.
|
||||
.RE
|
||||
.sp
|
||||
\fBtarget_preserve_min\fP all|latest|no|<number>{h,d,w,m,y}
|
||||
.RS 4
|
||||
Preserve all backups for a minimum amount of hours (h), days (d),
|
||||
weeks (w), months (m) or years (y), regardless of how many there
|
||||
are. If set to \(lqall\(rq, preserve all backups forever. If set to
|
||||
\(lqlatest\(rq, always preserve the latest backup (useful in
|
||||
conjunction with "target_preserve no", if you want to keep the
|
||||
latest backup only). If set to \(lqno\(rq, only the backups following
|
||||
the \fItarget_preserve\fP policy are created. Defaults to \(lqall\(rq.
|
||||
.RE
|
||||
.sp
|
||||
\fBarchive_preserve\fP no|<retention_policy>
|
||||
.RS 4
|
||||
Set retention policy for archives ("btrbk archive" command), with
|
||||
same semantics as \fItarget_preserve\fP.
|
||||
.RE
|
||||
.sp
|
||||
\fBarchive_preserve_min\fP all|latest|no|<number>{h,d,w,m,y}
|
||||
.RS 4
|
||||
Set retention policy for archives ("btrbk archive" command), with
|
||||
same semantics as \fItarget_preserve_min\fP.
|
||||
.RE
|
||||
.sp
|
||||
\fBarchive_exclude\fP <pattern>
|
||||
.RS 4
|
||||
Exclude subvolumes matching <pattern> from archiving. The pattern
|
||||
accepts wildcard character "*", and is matched against the end of
|
||||
the pathname.
|
||||
.RE
|
||||
.SS "SSH Options"
|
||||
.sp
|
||||
\fBssh_identity\fP <file>
|
||||
.RS 4
|
||||
Absolute path to a ssh identity file (private key). Note that if
|
||||
the private key is password protected, btrbk will prompt for user
|
||||
input, which is usually not desired.
|
||||
.RE
|
||||
.sp
|
||||
\fBssh_user\fP <username>
|
||||
.RS 4
|
||||
Remote username for ssh. Defaults to \(lqroot\(rq. Make sure the
|
||||
remote user is able to run "btrfs" with root privileges (see
|
||||
option \fIbackend\fP for details).
|
||||
.RE
|
||||
.sp
|
||||
\fBssh_compression\fP yes|no
|
||||
.RS 4
|
||||
Enables or disables the compression of ssh connections. Defaults
|
||||
to \(lqno\(rq.
|
||||
.RE
|
||||
.sp
|
||||
\fBssh_cipher_spec\fP <cipher_spec>
|
||||
.RS 4
|
||||
Selects the cipher specification for encrypting the session
|
||||
(comma\-separated list of ciphers in order of preference). See the
|
||||
"\-c cipher_spec" option in ssh(1) for more information. Defaults
|
||||
to \(lqdefault\(rq (the ciphers specified in \fIssh_config\fP).
|
||||
.RE
|
||||
.sp
|
||||
Previous versions btrbk allowed you to set a \fBssh_port\fP option, this
|
||||
has been dropped in favor of the \f(CRssh://hostname:port\fP notation in the
|
||||
\fIvolume\fP and \fItarget\fP sections. If you want to set a
|
||||
global port for all SSH connections to remote hosts, set the \(lqPort\(rq
|
||||
option in ssh_config(5).
|
||||
.SS "Data Stream Options"
|
||||
.sp
|
||||
\fBstream_compress\fP <compress_command>|no
|
||||
.RS 4
|
||||
Compress the btrfs send stream before transferring it from/to
|
||||
remote locations. Defaults to \(lqno\(rq. If enabled, make sure that
|
||||
\fI<compress_command>\fP is available on the source and target
|
||||
hosts. Supported \fI<compress_command>\fP: gzip, pigz, bzip2, pbzip2,
|
||||
xz, lzo, lz4.
|
||||
.RE
|
||||
.sp
|
||||
\fBstream_compress_level\fP default|<number>
|
||||
.RS 4
|
||||
Compression level for the specified \fI<compress_command>\fP. Refer to
|
||||
the related man\-page for details (usually [1..9], where 1 means
|
||||
fastest compression). Defaults to \(lqdefault\(rq (the default
|
||||
compression level of \fI<compress_command>\fP).
|
||||
.RE
|
||||
.sp
|
||||
\fBstream_compress_threads\fP default|<number>
|
||||
.RS 4
|
||||
Number of threads to use for <compress_command>. Only supported
|
||||
for "pigz", "pbzip2" and recent versions of "xz".
|
||||
.RE
|
||||
.sp
|
||||
\fBstream_buffer\fP <size>|no
|
||||
.RS 4
|
||||
Add a buffer to the btrfs send stream (in front of "btrfs
|
||||
receive"), with a maximum size of \fI<size>\fP. This can give a speed
|
||||
improvement (measured up to 20%) on both local or remote
|
||||
operations, but also increases system load. A suffix of "k", "m",
|
||||
"g", or "%" can be added to \fI<size>\fP to denote kilobytes (*1024),
|
||||
megabytes, gigabytes, or a percentage of total physical
|
||||
memory. Defaults to \(lqno\(rq.
|
||||
.sp
|
||||
If enabled, make sure that the "mbuffer" command is available on the
|
||||
target host. Note that versions of mbuffer < 20180505 suffered from
|
||||
nasty bugs (infinite loops, hangs); if your main concern is a stable
|
||||
backup process, leave this option disabled.
|
||||
.RE
|
||||
.sp
|
||||
\fBrate_limit\fP <rate>|no
|
||||
.RS 4
|
||||
Limit the transfer to a maximum of \fI<rate>\fP bytes per second. A
|
||||
suffix of "k", "m", "g", or "t" can be added to denote kilobytes
|
||||
(*1024), megabytes, and so on. Defaults to \(lqno\(rq. If enabled for
|
||||
remote sources, make sure that the "pv" command is available on
|
||||
the source host.
|
||||
.RE
|
||||
.SS "System Options"
|
||||
.sp
|
||||
\fBtransaction_log\fP <file>|no
|
||||
.RS 4
|
||||
If set, all transactions (snapshot create, subvolume send\-receive,
|
||||
subvolume delete) as well as abort messages are logged to <file>,
|
||||
in a space\-separated table format: "localtime type status
|
||||
target_url source_url parent_url message".
|
||||
.RE
|
||||
.sp
|
||||
\fBtransaction_syslog\fP <facility>|no
|
||||
.RS 4
|
||||
If set, all transactions (as described in \fItransaction_log\fP above)
|
||||
are logged to syslog. The program name used in the messages is
|
||||
"btrbk". Accepted parameters for \fI<facility>\fP: user, mail,
|
||||
daemon, auth, lpr, news, cron, authpriv, local0..local7.
|
||||
.RE
|
||||
.sp
|
||||
\fBlockfile\fP <file>|no
|
||||
.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. Ignored on dryrun (\fI\-n\fP,
|
||||
\fI\-\-dry\-run\fP). See also \fI\-\-lockfile\fP command\-line option.
|
||||
.RE
|
||||
.sp
|
||||
\fBbackend\fP btrfs\-progs|btrfs\-progs\-btrbk|btrfs\-progs\-sudo
|
||||
.RS 4
|
||||
Backend filesystem utilities to be used for btrfs specific
|
||||
operations. Defaults to \(lqbtrfs\-progs\(rq.
|
||||
.sp
|
||||
btrfs\-progs
|
||||
.RS 4
|
||||
Default backend, btrfs commands are called as specified in
|
||||
btrfs(8) (e.g. "btrfs subvolume show").
|
||||
.RE
|
||||
.sp
|
||||
btrfs\-progs\-btrbk
|
||||
.RS 4
|
||||
btrfs commands are separated by a dash instead of a whitespace
|
||||
(e.g. "btrfs\-subvolume\-show" instead of "btrfs subvolume
|
||||
show"). Useful for setting suid or file capabilities (setcap) on
|
||||
specific btrfs commands, as implemented in
|
||||
.URL "https://github.com/digint/btrfs\-progs\-btrbk" "" "."
|
||||
.RE
|
||||
.sp
|
||||
btrfs\-progs\-sudo
|
||||
.RS 4
|
||||
btrfs commands are prefixed with "sudo \-n" (e.g. "sudo \-n btrfs
|
||||
subvolume show" instead of "btrfs subvolume show"). Make sure to
|
||||
have appropriate (root) permissions for the "btrfs" command groups
|
||||
and the "readlink" command in /etc/sudoers.
|
||||
.RE
|
||||
.sp
|
||||
For convenience, it is also possible to set \fBbackend_local\fP or
|
||||
\fBbackend_remote\fP options, which will override the backend only for
|
||||
local or remote sources/targets (e.g. "backend_remote
|
||||
btrfs\-progs\-btrbk").
|
||||
.RE
|
||||
.SS "Btrfs Specific Options"
|
||||
.sp
|
||||
\fBbtrfs_commit_delete\fP after|each|no
|
||||
.RS 4
|
||||
If set, make sure the deletion of snapshot and backup subvolumes
|
||||
are committed to disk when btrbk terminates. Defaults to \(lqno\(rq.
|
||||
.RE
|
||||
.sp
|
||||
\fBincremental_clones\fP <number>
|
||||
.RS 4
|
||||
Maximum number of clone sources allowed for incremental send. If
|
||||
set, btrbk adds "\-c <clone\-src>" to the btrfs\-send(8) command for
|
||||
all present snapshot/backup pairs (correlated subvolumes matching
|
||||
matching \fIreceived_uuid\fP, printed by "btrbk stats"). Set this to a
|
||||
high number if you want to make sure that no common data is missed
|
||||
on incremental backups, in expense of btrfs\-send
|
||||
performance. Defaults to 0.
|
||||
.RE
|
||||
.sp
|
||||
\fBincremental_resolve\fP mountpoint|directory
|
||||
.RS 4
|
||||
Specifies where to search for the best common parent for
|
||||
incremental backups. If set to \(lqmountpoint\(rq, use parents in the
|
||||
filesystem tree below mount points of source
|
||||
"<volume\-directory>/<snapshot\-dir>" and target
|
||||
"<target\-directory>". If set to \(lqdirectory\(rq, use parents
|
||||
strictly below source/target directories. Set this to
|
||||
\(lqdirectory\(rq if you get access problems (when not running btrbk
|
||||
as root). Defaults to \(lqmountpoint\(rq.
|
||||
.RE
|
||||
.sp
|
||||
\fBsnapshot_qgroup_destroy\fP yes|no \fI*experimental*\fP
|
||||
.RS 4
|
||||
|
||||
.RE
|
||||
.sp
|
||||
\fBtarget_qgroup_destroy\fP yes|no \fI*experimental*\fP
|
||||
.RS 4
|
||||
|
||||
.RE
|
||||
.sp
|
||||
\fBarchive_qgroup_destroy\fP yes|no \fI*experimental*\fP
|
||||
.RS 4
|
||||
Whenever a subvolume is deleted, also destroy corresponding
|
||||
default qgroup "\f(CR0/<subvol\-id>\fP". Only useful if you have enabled
|
||||
btrfs quota support. See also:
|
||||
.URL "https://bugzilla.kernel.org/show_bug.cgi?id=91751" "" ""
|
||||
.RE
|
||||
.SH "RETENTION POLICY"
|
||||
.sp
|
||||
btrbk uses separate retention policies for snapshots and backups,
|
||||
which are defined by the \fIsnapshot_preserve_min\fP, \fIsnapshot_preserve\fP,
|
||||
\fItarget_preserve_min\fP, \fItarget_preserve\fP, \fIpreserve_day_of_week\fP and
|
||||
\fIpreserve_hour_of_day\fP configuration options.
|
||||
.sp
|
||||
Within this section, any statement about "backups" is always valid for
|
||||
backups as well as snapshots, referring to \fItarget_preserve\fP or
|
||||
\fIsnapshot_preserve\fP respectively.
|
||||
.sp
|
||||
The format for \fI<retention_policy>\fP is:
|
||||
.sp
|
||||
.if n .RS 4
|
||||
.nf
|
||||
[<hourly>h] [<daily>d] [<weekly>w] [<monthly>m] [<yearly>y]
|
||||
.fi
|
||||
.if n .RE
|
||||
.sp
|
||||
With the following semantics:
|
||||
.sp
|
||||
\fBhourly\fP
|
||||
.RS 4
|
||||
Defines how many hours back hourly backups should be
|
||||
preserved. The first backup of an hour is considered an hourly
|
||||
backup. Note that if you use <hourly> scheduling, make sure to
|
||||
also set \fItimestamp_format\fP to \(lqlong\(rq or \(lqlong\-iso\(rq, or the
|
||||
scheduler will interpret the time as "00:00" (midnight).
|
||||
.RE
|
||||
.sp
|
||||
\fBdaily\fP
|
||||
.RS 4
|
||||
Defines how many days back daily backups should be preserved. The
|
||||
first backup of a day (starting at \fIpreserve_hour_of_day\fP) is
|
||||
considered a daily backup.
|
||||
.RE
|
||||
.sp
|
||||
\fBweekly\fP
|
||||
.RS 4
|
||||
Defines how many weeks back weekly backups should be
|
||||
preserved. The first daily backup created at
|
||||
\fIpreserve_day_of_week\fP (or the first backup in this week if none
|
||||
was made on the exact day) is considered as a weekly backup.
|
||||
.RE
|
||||
.sp
|
||||
\fBmonthly\fP
|
||||
.RS 4
|
||||
Defines how many months back monthly backups should be
|
||||
preserved. Every first weekly backup in a month is considered a
|
||||
monthly backup.
|
||||
.RE
|
||||
.sp
|
||||
\fByearly\fP
|
||||
.RS 4
|
||||
Defines for how many years back yearly backups should be
|
||||
preserved. Every first monthly backup in a year is considered a
|
||||
yearly backup.
|
||||
.RE
|
||||
.sp
|
||||
Use an asterisk for \(lqall\(rq (e.g. "target_preserve 60d *m"
|
||||
states: "preserve daily backups for 60 days back, and all monthly
|
||||
backups").
|
||||
.sp
|
||||
The reference time (which defines the beginning of a day, week, month
|
||||
or year) for all date/time calculations is the local time of the host
|
||||
running btrbk.
|
||||
.sp
|
||||
Hint: Run btrbk with the \fI\-S\fP, \fI\-\-print\-schedule\fP option to get a
|
||||
comprehensive output of the scheduler results.
|
||||
.sp
|
||||
Caveats:
|
||||
.sp
|
||||
.RS 4
|
||||
.ie n \{\
|
||||
\h'-04'\(bu\h'+03'\c
|
||||
.\}
|
||||
.el \{\
|
||||
. sp -1
|
||||
. IP \(bu 2.3
|
||||
.\}
|
||||
If you run a setup with several btrbk instances (e.g. one
|
||||
snapshot\-only instance per remote client, and a separate fetch\-only
|
||||
instance on the backup server), it makes perfectly sense to run
|
||||
btrbk with different local time on the clients, in order to make
|
||||
sure the backups from all the remote hosts are preserved for
|
||||
"midnight", and not at "00:00 UTC" (which would be "14:00" in
|
||||
Honolulu). If you want this behaviour, do NOT use "timestamp_format
|
||||
long\-iso".
|
||||
.RE
|
||||
.sp
|
||||
.RS 4
|
||||
.ie n \{\
|
||||
\h'-04'\(bu\h'+03'\c
|
||||
.\}
|
||||
.el \{\
|
||||
. sp -1
|
||||
. IP \(bu 2.3
|
||||
.\}
|
||||
If "timestamp_format long\-iso" is set, running btrbk from different
|
||||
time zones leads to different interpretation of "first in day, week,
|
||||
month, or year". Make sure to run btrbk with the same time zone on
|
||||
every host, e.g. by setting the TZ environment variable (see
|
||||
tzset(3)).
|
||||
.RE
|
||||
.SH "TARGET TYPES"
|
||||
.sp
|
||||
\fBsend\-receive\fP
|
||||
.RS 4
|
||||
Backup to a btrfs filesystem, using "btrfs send/receive". This is
|
||||
the recommended (standard) target type. The \fI<target\-directory>\fP
|
||||
must be an absolute path and point to a btrfs volume (or
|
||||
subvolume), or to a directory within a subvolume. See
|
||||
btrfs\-send(8), btrfs\-receive(8).
|
||||
.RE
|
||||
.sp
|
||||
\fBraw\fP \fI*experimental*\fP
|
||||
.RS 4
|
||||
Backup to a raw (filesystem independent) file from the output of
|
||||
btrfs\-send(8), with optional compression and encryption.
|
||||
.sp
|
||||
Note that the target preserve mechanism is currently disabled for
|
||||
incremental raw backups (btrbk does not delete any incremental raw
|
||||
files)!
|
||||
.sp
|
||||
Raw backups consist of two files: the main data file containing the
|
||||
btrfs send stream, and a sidecar file ".info" containing metadata:
|
||||
.sp
|
||||
.if n .RS 4
|
||||
.nf
|
||||
<snapshot\-name>.<timestamp>[_N].btrfs[.gz|.bz2|.xz][.gpg]
|
||||
<snapshot\-name>.<timestamp>[_N].btrfs[.gz|.bz2|.xz][.gpg].info
|
||||
.fi
|
||||
.if n .RE
|
||||
.sp
|
||||
For \fIincremental\fP backups ("incremental yes"), please note that:
|
||||
.sp
|
||||
.RS 4
|
||||
.ie n \{\
|
||||
\h'-04'\(bu\h'+03'\c
|
||||
.\}
|
||||
.el \{\
|
||||
. sp -1
|
||||
. IP \(bu 2.3
|
||||
.\}
|
||||
As soon as a single \fIincremental\fP backup file is lost or corrupted,
|
||||
all later incremental backups become invalid, as there is no common
|
||||
parent for the subsequent incremental images anymore. This might be
|
||||
a good compromise for a vacation backup plan, but for the long term
|
||||
make sure that a non\-incremental backup is triggered from time to
|
||||
time.
|
||||
.RE
|
||||
.sp
|
||||
.RS 4
|
||||
.ie n \{\
|
||||
\h'-04'\(bu\h'+03'\c
|
||||
.\}
|
||||
.el \{\
|
||||
. sp -1
|
||||
. IP \(bu 2.3
|
||||
.\}
|
||||
There is currently no support for rotation of incremental backups:
|
||||
if \fIincremental\fP is set, a full backup must be triggered manually
|
||||
from time to time in order to be able to delete old backups.
|
||||
.RE
|
||||
.sp
|
||||
Additional options for raw targets:
|
||||
.sp
|
||||
\fBraw_target_compress\fP <compress_command>|no
|
||||
.RS 4
|
||||
Compression algorithm to use for raw backup target. Supported
|
||||
\fI<compress_command>\fP: gzip, pigz, bzip2, pbzip2, xz, lzo, lz4.
|
||||
.RE
|
||||
.sp
|
||||
\fBraw_target_compress_level\fP default|<number>
|
||||
.RS 4
|
||||
Compression level for the specified <compress_command>.
|
||||
.RE
|
||||
.sp
|
||||
\fBraw_target_compress_threads\fP default|<number>
|
||||
.RS 4
|
||||
Number of threads to use for <compress_command>.
|
||||
.RE
|
||||
.sp
|
||||
\fBraw_target_split\fP <size>|no
|
||||
.RS 4
|
||||
Split the raw backup file into pieces of size \fI<size>\fP.
|
||||
.RE
|
||||
.sp
|
||||
\fBraw_target_block_size\fP <number>
|
||||
.RS 4
|
||||
Block size to use for writing the raw backup file. Defaults to
|
||||
\(lq128K\(rq.
|
||||
.RE
|
||||
.sp
|
||||
\fBraw_target_encrypt\fP gpg|openssl_enc|no
|
||||
.RS 4
|
||||
If enabled, encrypt the target raw file using gpg or openssl_enc.
|
||||
.RE
|
||||
.sp
|
||||
Additional options for "raw_target_encrypt gpg":
|
||||
.sp
|
||||
\fBgpg_keyring\fP <file>
|
||||
.RS 4
|
||||
Keyring to use for gpg, e.g. "\f(CR/etc/btrbk/gpg/pubring.kbx\fP".
|
||||
.RE
|
||||
.sp
|
||||
\fBgpg_recipient\fP <name>
|
||||
.RS 4
|
||||
Encrypt for user id \fI<name>\fP (email address).
|
||||
.RE
|
||||
.sp
|
||||
Additional options for "raw_target_encrypt openssl_enc" (\fIvery
|
||||
experimental\fP):
|
||||
.sp
|
||||
\fBopenssl_ciphername\fP\~<name>
|
||||
.RS 4
|
||||
Defaults to \(lqaes\-256\-cbc\(rq.
|
||||
.RE
|
||||
.sp
|
||||
\fBopenssl_iv_size\fP <size\-in\-bytes>|no
|
||||
.RS 4
|
||||
Depends on selected cipher.
|
||||
.RE
|
||||
.sp
|
||||
\fBopenssl_keyfile\fP <file>|no
|
||||
.RS 4
|
||||
Point to a key file in hex (absolute path). Example key file
|
||||
creation (256bit key):
|
||||
.sp
|
||||
.if n .RS 4
|
||||
.nf
|
||||
# dd if=/dev/urandom bs=1 count=32 \(rs
|
||||
| od \-x \-A n \(rs
|
||||
| tr \-d "[:space:]" > /path/to/keyfile
|
||||
.fi
|
||||
.if n .RE
|
||||
.RE
|
||||
.sp
|
||||
\fBkdf_backend\fP <file>|no
|
||||
.RS 4
|
||||
KDF backend to be executed,
|
||||
e.g. "\f(CR/usr/share/btrbk/scripts/kdf_pbkdf2.py\fP".
|
||||
.RE
|
||||
.sp
|
||||
\fBkdf_keysize\fP <size\-in\-bytes>
|
||||
.RS 4
|
||||
Defaults to \(lq32\(rq.
|
||||
.RE
|
||||
.sp
|
||||
\fBkdf_keygen\fP once|each
|
||||
.RS 4
|
||||
Defaults to \(lqonce\(rq.
|
||||
.RE
|
||||
.RE
|
||||
.SH "AVAILABILITY"
|
||||
.sp
|
||||
Please refer to the btrbk project page \fB\c
|
||||
.URL "https://digint.ch/btrbk/" "" "\fP"
|
||||
for further details.
|
||||
.SH "SEE ALSO"
|
||||
.sp
|
||||
\fBbtrbk\fP(1)
|
||||
.SH "AUTHOR"
|
||||
.sp
|
||||
Axel Burri <\c
|
||||
.MTO "axel\(attty0.ch" "" ">"
|
||||
|
|
@ -1,208 +0,0 @@
|
|||
'\" t
|
||||
.\" Title: ssh_filter_btrbk
|
||||
.\" Author: [see the "AUTHOR(S)" section]
|
||||
.\" Generator: Asciidoctor 1.5.7.1
|
||||
.\" Date: 2019-04-24
|
||||
.\" Manual: Btrbk Manual
|
||||
.\" Source: Btrbk 0.28.0
|
||||
.\" Language: English
|
||||
.\"
|
||||
.TH "SSH_FILTER_BTRBK" "1" "2019-04-24" "Btrbk 0.28.0" "Btrbk Manual"
|
||||
.ie \n(.g .ds Aq \(aq
|
||||
.el .ds Aq '
|
||||
.ss \n[.ss] 0
|
||||
.nh
|
||||
.ad l
|
||||
.de URL
|
||||
\fI\\$2\fP <\\$1>\\$3
|
||||
..
|
||||
.als MTO URL
|
||||
.if \n[.g] \{\
|
||||
. mso www.tmac
|
||||
. am URL
|
||||
. ad l
|
||||
. .
|
||||
. am MTO
|
||||
. ad l
|
||||
. .
|
||||
. LINKSTYLE blue R < >
|
||||
.\}
|
||||
.SH "NAME"
|
||||
ssh_filter_btrbk \- ssh command filter script for btrbk
|
||||
.SH "SYNOPSIS"
|
||||
.sp
|
||||
.nf
|
||||
ssh_filter_btrbk.sh [\-s|\-\-source] [\-t|\-\-target] [\-d|\-\-delete]
|
||||
[\-i|\-\-info] [\-\-snapshot] [\-\-send] [\-\-receive]
|
||||
[\-p|\-\-restrict\-path <path>] [\-l|\-\-log] [\-\-sudo]
|
||||
.fi
|
||||
.br
|
||||
.SH "DESCRIPTION"
|
||||
.sp
|
||||
\fBssh_filter_btrbk.sh\fP restricts SSH commands to commands used by
|
||||
\fIbtrbk\fP. It examines the SSH_ORIGINAL_COMMAND environment variable
|
||||
(set by sshd) and executes it only if it contains commands used by
|
||||
\fIbtrbk\fP.
|
||||
.sp
|
||||
The accepted commands are specified by the "\-\-source", "\-\-target",
|
||||
"\-\-delete" and "\-\-info" options.
|
||||
.sp
|
||||
The following commands are always allowed:
|
||||
.sp
|
||||
.RS 4
|
||||
.ie n \{\
|
||||
\h'-04'\(bu\h'+03'\c
|
||||
.\}
|
||||
.el \{\
|
||||
. sp -1
|
||||
. IP \(bu 2.3
|
||||
.\}
|
||||
"btrfs subvolume show"
|
||||
.RE
|
||||
.sp
|
||||
.RS 4
|
||||
.ie n \{\
|
||||
\h'-04'\(bu\h'+03'\c
|
||||
.\}
|
||||
.el \{\
|
||||
. sp -1
|
||||
. IP \(bu 2.3
|
||||
.\}
|
||||
"btrfs subvolume list"
|
||||
.RE
|
||||
.sp
|
||||
.RS 4
|
||||
.ie n \{\
|
||||
\h'-04'\(bu\h'+03'\c
|
||||
.\}
|
||||
.el \{\
|
||||
. sp -1
|
||||
. IP \(bu 2.3
|
||||
.\}
|
||||
"readlink"
|
||||
.RE
|
||||
.sp
|
||||
.RS 4
|
||||
.ie n \{\
|
||||
\h'-04'\(bu\h'+03'\c
|
||||
.\}
|
||||
.el \{\
|
||||
. sp -1
|
||||
. IP \(bu 2.3
|
||||
.\}
|
||||
"cat /proc/self/mountinfo"
|
||||
.RE
|
||||
.sp
|
||||
.RS 4
|
||||
.ie n \{\
|
||||
\h'-04'\(bu\h'+03'\c
|
||||
.\}
|
||||
.el \{\
|
||||
. sp -1
|
||||
. IP \(bu 2.3
|
||||
.\}
|
||||
pipes through "gzip", "pigz", "bzip2", "pbzip2", "xz", "lzop",
|
||||
"lz4" (stream_compress)
|
||||
.RE
|
||||
.sp
|
||||
.RS 4
|
||||
.ie n \{\
|
||||
\h'-04'\(bu\h'+03'\c
|
||||
.\}
|
||||
.el \{\
|
||||
. sp -1
|
||||
. IP \(bu 2.3
|
||||
.\}
|
||||
pipes through "mbuffer" (stream_buffer)
|
||||
.RE
|
||||
.sp
|
||||
.RS 4
|
||||
.ie n \{\
|
||||
\h'-04'\(bu\h'+03'\c
|
||||
.\}
|
||||
.el \{\
|
||||
. sp -1
|
||||
. IP \(bu 2.3
|
||||
.\}
|
||||
pipes through "pv \-L" (rate_limit)
|
||||
.RE
|
||||
.sp
|
||||
Example line in /root/.ssh/authorized_keys on a backup target host:
|
||||
.sp
|
||||
.if n .RS 4
|
||||
.nf
|
||||
command="ssh_filter_btrbk.sh \-\-target \-\-delete \-\-restrict\-path /mnt/btr_backup" ssh\-rsa AAAAB3NzaC1...hwumXFRQBL btrbk@mydomain.com
|
||||
.fi
|
||||
.if n .RE
|
||||
.SH "OPTIONS"
|
||||
.sp
|
||||
\-s, \-\-source
|
||||
.RS 4
|
||||
Allow commands for backup source: "btrfs subvolume snapshot",
|
||||
"btrfs send". Equivalent to "\-\-snapshot \-\-send".
|
||||
.RE
|
||||
.sp
|
||||
\-t, \-\-target
|
||||
.RS 4
|
||||
Allow commands for backup target: "btrfs receive".
|
||||
.RE
|
||||
.sp
|
||||
\-d, \-\-delete
|
||||
.RS 4
|
||||
Allow commands for subvolume deletion: "btrfs subvolume
|
||||
delete". This is used for backup source if
|
||||
\fIsnapshot_preserve_daily\fP is not set to \(lqall\(rq, and for backup
|
||||
targets if \fItarget_preserve_daily\fP is not set to \(lqall\(rq.
|
||||
.RE
|
||||
.sp
|
||||
\-i, \-\-info
|
||||
.RS 4
|
||||
Allow informative commands: "btrfs subvolume find\-new", "btrfs
|
||||
filesystem usage". This is used by btrbk \fIinfo\fP and \fIdiff\fP
|
||||
commands.
|
||||
.RE
|
||||
.sp
|
||||
\-\-snapshot
|
||||
.RS 4
|
||||
Allow btrfs snapshot command: "btrfs subvolume snapshot".
|
||||
.RE
|
||||
.sp
|
||||
\-\-send
|
||||
.RS 4
|
||||
Allow btrfs send command: "btrfs send".
|
||||
.RE
|
||||
.sp
|
||||
\-\-receive
|
||||
.RS 4
|
||||
Allow btrfs receive command: "btrfs receive".
|
||||
.RE
|
||||
.sp
|
||||
\-p, \-\-restrict\-path <path>
|
||||
.RS 4
|
||||
Restrict btrfs commands to <path>.
|
||||
.RE
|
||||
.sp
|
||||
\-l, \-\-log
|
||||
.RS 4
|
||||
Log ACCEPT and REJECT messages to the system log.
|
||||
.RE
|
||||
.sp
|
||||
\-\-sudo
|
||||
.RS 4
|
||||
Allow btrfs commands to be called via sudo. Enable this if you
|
||||
have "backend btrfs\-progs\-sudo" in your btrbk configuration file.
|
||||
.RE
|
||||
.SH "AVAILABILITY"
|
||||
.sp
|
||||
Please refer to the btrbk project page \fB\c
|
||||
.URL "https://digint.ch/btrbk/" "" "\fP"
|
||||
for further details.
|
||||
.SH "SEE ALSO"
|
||||
.sp
|
||||
\fBbtrbk\fP(1),
|
||||
\fBbtrbk.conf\fP(5),
|
||||
\fBbtrfs\fP(8)
|
||||
.SH "AUTHOR"
|
||||
.sp
|
||||
Axel Burri <\c
|
||||
.MTO "axel\(attty0.ch" "" ">"
|
||||
Loading…
Reference in New Issue