mirror of https://github.com/digint/btrbk
documentation: add pre-generated man pages: from groff to asciidoc and back again
This reduces build-time dependencies to zero, helping package maintainers and providing reproducible builds. NOTE: generated man pages will only be updated on releases. In order to make sure the docs are correctly rebuilt, run "make clean man". We apologize for the inconvenience. From Groff to Asciidoc and Back Again [1] ========================================= | Comparison | Links | | -------------------------------------------------------------------------| -------------------------------------------------------------------------------------------------------------- | | **Plain ROFF** | | | +++ Best result for `man` (our main goal!) | | | - Not supported by github | [btrbk(1) v0.25.1 in plain groff](https://github.com/digint/btrbk/blob/v0.25.1/doc/btrbk.1) | | - No decent converters: e.g. `groff -Txhtml -mandoc` | [btrbk(1) v0.25.1 at digint.ch (official site)](https://digint.ch/btrbk/doc/archive/btrbk-0.25.1/btrbk.1.html) | | | | | **asciidoc** | | | + Decent (scriptable!) html | [btrbk(1) v0.26.1 at digint.ch (official site)](https://digint.ch/btrbk/doc/archive/btrbk-0.26.1/btrbk.1.html) | | + Supported by github (helps contributors writing decent documentation) | [btrbk.1.asciidoc v0.26.1 at github](https://github.com/digint/btrbk/blob/master/doc/btrbk.1.asciidoc) | | | | | **asciidoc (`xmlto`, `atx`)** | http://asciidoc.org/ | | + Good result for `man` | | | - EOL (why care that much? it works fine!) | [asciidoc EOL notice at github](https://github.com/asciidoc/asciidoc/releases/tag/8.6.10) | | | | | **asciidoc (`asciidoctor`)** | https://asciidoctor.org | | - Pulls in tons of ruby (build depends) | https://bugs.gentoo.org/681056 | | -- Implies to commit a pre-converted `doc/btrbk.1` | | | + Seems more evolved than `xmlto`, still actively maintained | | | | | | **rst (`xrst2man.py` from docutils)** | | | - Worse result for `man` | | | ++ Good html converters (after having a quick look at it) | | | - Not so well supported by github | [btrbk.1.rst v0.26.1 at github](https://github.com/digint/btrbk/blob/rst2man/doc/btrbk.1.rst) | [1] https://github.com/digint/btrbk/pull/219 (edited)pull/286/head v0.28.0
Axel Burri
parent
fc485565ce
commit
a6dbd60e5a
|
|
@ -1,2 +1 @@
|
|||
*.[1-8]
|
||||
*.[1-8].gz
|
||||
|
|
|
|||
|
|
@ -0,0 +1,561 @@
|
|||
'\" 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" "" ">"
|
||||
|
|
@ -0,0 +1,744 @@
|
|||
'\" 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" "" ">"
|
||||
|
|
@ -0,0 +1,208 @@
|
|||
'\" 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