ambiser
/
btrbk
mirror of https://github.com/digint/btrbk
9
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

documentation: convert all groff files (man pages) to asciidoc 

- btrbk.conf.5 to btrbk.conf.5.asciidoc
 - btrbk.1 to btrbk.1.asciidoc
 - ssh_filter_btrbk.1 to ssh_filter_btrbk.1.asciidoc
pull/204/head
Axel Burri 2017-10-09 14:52:15 +02:00
parent e3ee674085
commit c4ced9d6e4
7 changed files with 908 additions and 1036 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
ChangeLog
View File

@ -21,6 +21,7 @@ btrbk-current
* Remove "duration" column from transaction_log/transaction_syslog.
* Resolve ancestors (recursive on parent_uuid chain) when searching
for latest common subvolume.
* Generate man pages from asciidoc (remove raw groff sources).
* Bugfix: ssh_filter_btrbk: accept mbuffer command (stream_buffer).
* Bugfix: print correct (end-)time in transaction_log.
* Bugfix: check path when expanding wildcards (close #181).

421
doc/btrbk.1
View File

@ -1,421 +0,0 @@
.TH "btrbk" "1" "2017-08-21" "btrbk v0.26.0-dev" ""
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.SH NAME
btrbk \- backup tool for btrfs volumes
.SH SYNOPSIS
.nf
\fBbtrbk\fR [\-h|\-\-help] [\-\-version] [\-c|\-\-config <file>]
[\-n|\-\-dry\-run] [\-p|\-\-preserve]
[\-\-preserve\-snapshots] [\-\-preserve\-backups]
[\-v|\-\-verbose] [\-q|\-\-quiet] [\-l|\-\-loglevel <level>]
[\-t|\-\-table] [\-\-format <output\-format>]
[\-\-progress] [\-\-print\-schedule]
<command> [<args>]
.fi
.SH DESCRIPTION
\fBbtrbk\fR is a backup tool for btrfs subvolumes, taking advantage of
btrfs specific capabilities to create atomic snapshots and transfer
them incrementally to a target btrfs filesystem. It is able to perform
backups from one source to multiple destinations.
.PP
Snapshots as well as backup subvolume names are created in form:
.PP
.RS 4
<snapshot\-name>.<timestamp>[_N]
.RE
.PP
Where <snapshot\-name> is identical to the source subvolume name,
unless the configuration option \fIsnapshot_name\fR is set. The
<timestamp> is either "YYYYMMDD" or "YYYYMMDDThhmm" (dependent of the
\fItimestamp_format\fR configuration option), where "YYYY" is the
year, "MM" is the month, "DD" is the day, "hh" is the hour and "mm" is
the minute of the creation time (local time of the host running
btrbk). If multiple snapshots/backups are created on the same
date/time, N will be incremented on each snapshot, starting at 1.
.SH OPTIONS
.PP
\-h, \-\-help
.RS 4
Prints the synopsis and a list of the commands.
.RE
.PP
\-\-version
.RS 4
Prints the btrbk version.
.RE
.PP
\-n, \-\-dry\-run
.RS 4
Don't run anything that would alter the filesystem, just show the
snapshots and backup subvolumes that would be created/deleted by the
\fBrun\fR, \fBsnapshot\fR, \fBresume\fR, \fBprune\fR, \fBarchive\fR
and \fBclean\fR commands. Use in conjunction with \fI\-l debug\fR to
see the btrfs commands that would be executed.
.RE
.PP
\-c, \-\-config <file>
.RS 4
Read the configuration from <file>.
.RE
.PP
\-p, \-\-preserve
.RS 4
Preserve all snapshots and backups. Skips deletion of any snapshots
and backups, even if specified in the configuration file (shortcut for
"\-\-preserve\-snapshots \-\-preserve\-backups").
.RE
.PP
\-\-preserve-snapshots
.RS 4
Preserve all snapshots. Skips deletion of any snapshots, even if
specified in the configuration file.
.RE
.PP
\-\-preserve-backups
.RS 4
Preserve all backups. Skips deletion of any backups, even if specified
in the configuration file.
.RE
.PP
\-\-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
.PP
\-v, \-\-verbose
.RS 4
Verbose output (shortcut for "\-\-loglevel=info").
.RE
.PP
\-q, \-\-quiet
.RS 4
Quiet operation. If set, btrbk does not print the summary after
executing the \fBrun\fR, \fBsnapshot\fR, \fBresume\fR, \fBprune\fR, or
\fBarchive\fR commands.
.RE
.PP
\-l, \-\-loglevel <level>
.RS 4
Set the level of verbosity. Accepted levels are warn, info, debug,
and trace.
.RE
.PP
\-t, \-\-table
.RS 4
Print output in table format (shortcut for "\-\-format=table").
.RE
.PP
\-\-format table|long|raw
.RS 4
Print output in specified format. If set to "raw", prints
space-separated key="value" pairs (machine readable). Affects output
format for \fBrun\fR, \fBsnapshot\fR, \fBresume\fR, \fBprune\fR,
\fBarchive\fR and \fBlist\fR commands. Useful for further
exporting/scripting.
.RE
.PP
\-\-progress
.RS 4
Show progress bar on send-receive operation.
.RE
.PP
\-\-print\-schedule
.RS 4
Print detailed scheduler information on \fBrun\fR, \fBsnapshot\fR,
\fBresume\fR, \fBprune\fR and \fBarchive\fR commands. Use the
\fI\-\-format\fR command line option to switch between different
output formats.
.RE
.PP
\-\-override <config_option>=<value>
.RS 4
Override a configuration option <config_option> with
<value>. Globally, for ALL contexts. Use with care!
.RE
.PP
\-\-lockfile <file>
.RS 4
Create lockfile <file> on startup; checks lockfile before running any
btrfs commands (using perl "flock"), and exits if the lock is held by
another btrbk instance. Overrides configuration option
"lockfile". Ignored on dryrun (\fI\-n\fR, \fI\-\-dry\-run\fR).
.RE
.SH COMMANDS
.PP
.B run
[filter...]
.RS 4
Perform snapshot and backup operations as specified in the
configuration file. If the optional [filter...] arguments are present,
snapshots and backups are only performed for the subvolumes/targets
matching a \fIFILTER STATEMENT\fR (see below).
.PP
.B Step 0: Read Data
.RS 4
Read information from the source and target btrfs filesystems in order
to perform sanity checks and identify parent/child and received-from
relationships.
.RE
.PP
.B Step 1: Create Snapshots
.RS 4
If the checks succeed, btrbk creates snapshots for the source
subvolumes specified in the configuration file, according to the
\fIsnapshot_create\fR option.
.RE
.PP
.B Step 2: Create Backups
.RS 4
For each specified target, btrbk creates the backups as follows: After
comparing the backups to the source snapshots, btrbk transfers all
missing snapshots needed to satisfy the configured target retention
policy, incrementally from the latest common parent subvolume
found. If no common parent subvolume is found (or if the
\fIincremental\fR option is set to \[lq]no\[rq]), a full
(non-incremental) backup is created.
.RE
.PP
.B Step 3: Delete Backups
.RS 4
Unless the \-p, \-\-preserve or \-\-preserve\-backups option is set,
backup subvolumes that are not preserved by their configured retention
policy will be deleted. Note that the latest snapshot/backup pair are
always preserved, regardless of the retention policy.
.RE
.PP
.B Step 4: Delete Snapshots
.RS 4
Unless the \-p, \-\-preserve or \-\-preserve-snapshots option is set,
snapshots that are not preserved by their configured retention policy
will be deleted. Note that the latest snapshot (the one created in
step 1) as well as the latest snapshot/backup pair are always
preserved, regardless of the retention policy.
.RE
.PP
See section RETENTION POLICY in
.BR btrbk.conf (5)
for information on configuring the retention policy.
.PP
Use the \fI\-\-format\fR command line option to switch between
different output formats.
.RE
.PP
.B dryrun
[filter...]
.RS 4
Don't run any btrfs commands that would alter the filesystem, just
show the snapshots and backup subvolumes that would be created/deleted
by the \fBrun\fR command. Use in conjunction with \fI\-l debug\fR to
see the btrfs commands that would be executed.
.RE
.PP
.B snapshot
[filter...]
.RS 4
Snapshot only: skips backup creation and deletion (steps 2 and 3). Use
in conjunction with \-p, \-\-preserve (or \-\-preserve\-snapshots) if
you also want to skip snapshot deletion (step 4).
.RE
.PP
.B resume
[filter...]
.RS 4
Resume backups: skips snapshot creation (step 1), transfers and
deletes snapshots/backups in order to satisfy their configured
retention policy. Use in conjunction with \-p, \-\-preserve,
\-\-preserve\-backups, \-\-preserve\-snapshots if you want to skip
backup and/or snapshot deletion (steps 3, 4).
.RE
.PP
.B prune
[filter...]
.RS 4
Prune snapshots and backups: skips snapshot and backup creation (steps
1, 2), only deletes snapshots and backups in order to satisfy their
configured retention policy. Useful for cleaning the disk after
changing the retention policy. Use in conjunction with
\-\-preserve\-backups, \-\-preserve\-snapshots if you want to skip
backup or snapshot deletion (steps 3, 4).
.RE
.PP
.B archive
<source> <target>
.I *experimental*
.RS 4
Recursively copy all subvolumes created by btrbk from <source> to
<target> directory, optionally rescheduled using
\fIarchive_preserve_*\fR configuration options. Also creates directory
tree on <target> (see bugs below). Useful for creating extra archive
copies (clones) from your backup disks. Note that you can continue
using btrbk after swapping your backup disk with the archive disk.
.PP
Note that this feature needs a \fBlinux kernel >=4.4\fR to work
correctly! Kernels >=4.1 and <4.4 have a bug when re-sending
subvolumes (the archived subvolumes will have incorrect received_uuid,
see <http://thread.gmane.org/gmane.comp.file\-systems.btrfs/48798>),
so make sure you run a recent kernel.
.PP
Known bugs: If you want to use nested subvolumes on the target
filesystem, you need to create them by hand (e.g. by running "btrfs
subvolume create <target>/dir"). Check the output of \-\-dry\-run if
unsure.
.RE
.PP
.B stats
[filter...]
.RS 4
Print statistics of snapshot and backup subvolumes. Optionally
filtered by [filter...] arguments (see \fIFILTER STATEMENTS\fR below).
.RE
.PP
.B list
<subcommand> [filter...]
.RS 4
Print information defined by <subcommand> in a tabular form. Optionally
filtered by [filter...] arguments (see \fIFILTER STATEMENTS\fR
below).
.PP
Available subcommands:
.TP 11
.B snapshots
All snapshots (and corresponding backups).
.PD 0
.TP 11
.B backups
All backups (and corresponding snapshots).
.TP 11
.B latest
Most recent common snapshot/backup pair, or most recent snapshot if no
common found.
.TP 11
.B config
Configured source/snapshot/target relations.
.TP 11
.B source
Configured source/snapshot relations.
.TP 11
.B volume
Configured volume sections.
.TP 11
.B target
Configured targets.
.PD
.PP
Use the \fI\-\-format\fR command line option to switch between
different output formats.
.RE
.PP
.B clean
[filter...]
.RS 4
Delete incomplete (garbled) backups. Incomplete backups can be left
behind on network errors or kill signals while a send/receive
operation is ongoing, and are identified by the "received_uuid" flag
not being set on a target (backup) subvolume.
.RE
.PP
.B usage
[filter...]
.RS 4
Print filesystem usage information for all source/target volumes,
optionally filtered by [filter...] arguments (see \fIFILTER
STATEMENTS\fR below). Note that the "free" value is an estimate of the
amount of data that can still be written to the file system.
.RE
.PP
.B origin
<subvolume>
.RS 4
Print the subvolume origin tree: Shows the parent-child relationships
as well as the received-from information. Use the \fI\-\-format\fR
command line option to switch between different output formats.
.RE
.PP
.B diff
<from> <to>
.RS 4
Print new files since subvolume <from> for subvolume <to>.
.RE
.PP
.B config
print|print\-all
.RS 4
Prints the parsed configuration file. Use the \fI\-\-format\fR command
line option to switch between different output formats.
.RE
.SH FILTER STATEMENTS
Filter arguments are accepted in form:
.PP
[hostname:]<volume\-directory>
.RS 4
Matches all subvolumes and targets of a \fIvolume\fR configuration
section.
.RE
.PP
[hostname:]<volume\-directory>/<subvolume\-name>
.RS 4
Matches the specified subvolume and all targets of a \fIsubvolume\fR
configuration section.
.RE
.PP
[hostname:]<target\-directory>
.RS 4
Matches all targets of a \fItarget\fR configuration section.
.RE
.PP
[hostname:]<target\-directory>/<snapshot\-name>
.RS 4
Matches a single target of a \fItarget\fR section within a
\fIsubvolume\fR section with given <snapshot\-name>.
.RE
.PP
<group\-name>
.RS 4
Matches the \fIgroup\fR configuration option of a \fIvolume\fR,
\fIsubvolume\fR or \fItarget\fR section.
.RE
.PP
For convenience, [hostname:] can be specified as either "hostname:" or
"ssh://hostname/".
.SH FILES
.PP
/etc/btrbk.conf
.br
/etc/btrbk/btrbk.conf
.RS 4
Default configuration file. The file format and configuration options
are described in
.BR btrbk.conf (5).
.RE
.PD
.SH EXIT STATUS
\fBbtrbk\fR returns the following error codes:
.IP "0" 4
No problems occurred.
.IP "1" 4
Generic error code.
.IP "2" 4
Parse error: when parsing command-line options or configuration file.
.IP "3" 4
Lockfile error: if lockfile is present on startup.
.IP "10" 4
Backup abort: At least one backup task aborted.
.IP "255" 4
Script error.
.SH AVAILABILITY
Please refer to the btrbk project page \fBhttp://digint.ch/btrbk/\fR
for further details.
.SH SEE ALSO
.BR btrbk.conf (5),
.BR btrfs (1)
.PP
For more information about btrfs and incremental backups, see the web
site at https://btrfs.wiki.kernel.org/index.php/Incremental_Backup
.SH AUTHOR
Axel Burri <axel@tty0.ch>

363
doc/btrbk.1.asciidoc Normal file
View File

@ -0,0 +1,363 @@
btrbk(1)
========
:date: 2017-10-09
:revision: 0.26.0-dev
:man manual: Btrbk Manual
:man source: Btrbk
NAME
----
btrbk - backup tool for btrfs volumes
SYNOPSIS
--------
[literal]
btrbk [-h|--help] [--version] [-c|--config <file>]
[-n|--dry-run] [-p|--preserve]
[--preserve-snapshots] [--preserve-backups]
[-v|--verbose] [-q|--quiet] [-l|--loglevel <level>]
[-t|--table] [--format <output-format>]
[--progress] [--print-schedule]
<command> [<args>]
DESCRIPTION
-----------
*btrbk* 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.
Snapshots as well as backup subvolume names are created in form:
<snapshot-name>.<timestamp>[_N]
Where '<snapshot-name>' is identical to the source subvolume name,
unless the configuration option 'snapshot_name' is set. The
<timestamp> is either "YYYYMMDD" or "YYYYMMDDThhmm" (dependent of the
'timestamp_format' 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.
OPTIONS
-------
-h, --help::
Prints the synopsis and a list of the commands.
--version::
Prints the btrbk version.
-n, --dry-run::
Don't run anything that would alter the filesystem, just show the
snapshots and backup subvolumes that would be created/deleted by
the *run*, *snapshot*, *resume*, *prune*, *archive* and *clean*
commands. Use in conjunction with '-l debug' to see the btrfs
commands that would be executed.
-c, --config <file>::
Read the configuration from <file>.
-p, --preserve::
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").
--preserve-snapshots::
Preserve all snapshots. Skips deletion of any snapshots, even if
specified in the configuration file.
--preserve-backups::
Preserve all backups. Skips deletion of any backups, even if
specified in the configuration file.
--wipe::
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).
-v, --verbose::
Verbose output (shortcut for "--loglevel=info").
-q, --quiet::
Quiet operation. If set, btrbk does not print the summary after
executing the *run*, *snapshot*, *resume*, *prune*, or *archive*
commands.
-l, --loglevel <level>::
Set the level of verbosity. Accepted levels are warn, info, debug,
and trace.
-t, --table::
Print output in table format (shortcut for "--format=table").
--format table|long|raw::
Print output in specified format. If set to "raw", prints
space-separated key="value" pairs (machine readable). Affects
output format for *run*, *snapshot*, *resume*, *prune*, *archive*
and *list* commands. Useful for further exporting/scripting.
--progress::
Show progress bar on send-receive operation.
--print-schedule::
Print detailed scheduler information on *run*, *snapshot*,
*resume*, *prune* and *archive* commands. Use the '--format'
command line option to switch between different output formats.
--override <config_option>=<value>::
Override a configuration option <config_option> with
<value>. Globally, for ALL contexts. Use with care!
--lockfile <file>::
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 ('-n', '--dry-run').
COMMANDS
--------
=== Actions
The following commands are used to create snapshots and/or
backups. All actions can operate in dry-run mode ('-n',
'--dry-run').
*run* [filter...]::
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,FILTER STATEMENTS>> below).
+
*Step 0: Read Data*;;
Read information from the source and target btrfs filesystems in
order to perform sanity checks and identify parent/child and
received-from relationships.
+
*Step 1: Create Snapshots*;;
If the checks succeed, btrbk creates snapshots for the source
subvolumes specified in the configuration file, according to the
'snapshot_create' option.
+
*Step 2: Create Backups*;;
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 'incremental' option is set to ``no''), a full
(non-incremental) backup is created.
+
*Step 3: Delete Backups*;;
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.
+
*Step 4: Delete Snapshots*;;
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.
+
See section RETENTION POLICY in `btrbk.conf`(5)
for information on configuring the retention policy.
Use the '--format' command line option to switch between
different output formats.
*dryrun* [filter...]::
Don't run any btrfs commands that would alter the filesystem, just
show the snapshots and backup subvolumes that would be
created/deleted by the *run* command. Use in conjunction with '-l
debug' to see the btrfs commands that would be executed.
*snapshot* [filter...]::
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).
*resume* [filter...]::
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).
*prune* [filter...]::
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).
*archive* <source> <target> _*experimental*_::
Recursively copy all subvolumes created by btrbk from <source> to
<target> directory, optionally rescheduled using
'archive_preserve_*' configuration options. Also creates directory
tree on <target> (see bugs below). Useful for creating extra
archive copies (clones) from your backup disks. Note that you can
continue using btrbk after swapping your backup disk with the
archive disk.
+
Note that this feature needs a *linux kernel >=4.4* to work correctly!
Kernels >=4.1 and <4.4 have a bug when re-sending subvolumes (the
archived subvolumes will have incorrect received_uuid, see
<http://thread.gmane.org/gmane.comp.file-systems.btrfs/48798>), so
make sure you run a recent kernel.
+
Known bugs: If you want to use nested subvolumes on the target
filesystem, you need to create them by hand (e.g. by running "btrfs
subvolume create <target>/dir"). Check the output of --dry-run if
unsure.
=== Informative Commands
The following commands are informative only, and will not alter the
file system.
*stats* [filter...]::
Print statistics of snapshot and backup subvolumes. Optionally
filtered by [filter...] arguments (see <<_filter_statements,FILTER
STATEMENTS>> below).
*list* <subcommand> [filter...]::
Print information defined by <subcommand> in a tabular
form. Optionally filtered by [filter...] arguments (see
<<_filter_statements,FILTER STATEMENTS>> below).
+
Available subcommands:
+
--
[horizontal]
*snapshots*;; All snapshots (and corresponding backups).
*backups*;; All backups (and corresponding snapshots).
*latest*;; Most recent common snapshot/backup pair, or most recent
snapshot if no common found.
*config*;; Configured source/snapshot/target relations.
*source*;; Configured source/snapshot relations.
*volume*;; Configured volume sections.
*target*;; Configured targets.
--
+
Use the '--format' command line option to switch between
different output formats.
*clean* [filter...]::
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.
*usage* [filter...]::
Print filesystem usage information for all source/target volumes,
optionally filtered by [filter...] arguments (see
<<_filter_statements,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.
*origin* <subvolume>::
Print the subvolume origin tree: Shows the parent-child
relationships as well as the received-from information. Use the
'--format' command line option to switch between different output
formats.
*diff* <from> <to>::
Print new files since subvolume <from> for subvolume <to>.
*config* print|print-all::
Prints the parsed configuration file. Use the '--format' command
line option to switch between different output formats.
FILTER STATEMENTS
-----------------
Filter arguments are accepted in form:
[hostname:]<volume-directory>::
Matches all subvolumes and targets of a 'volume' configuration
section.
[hostname:]<volume-directory>/<subvolume-name>::
Matches the specified subvolume and all targets of a 'subvolume'
configuration section.
[hostname:]<target-directory>::
Matches all targets of a 'target' configuration section.
[hostname:]<target-directory>/<snapshot-name>::
Matches a single target of a 'target' section within a 'subvolume'
section with given <snapshot-name>.
<group-name>::
Matches the 'group' configuration option of a 'volume',
'subvolume' or 'target' section.
For convenience, [hostname:] can be specified as either "hostname:" or
"ssh://hostname/".
FILES
-----
+/etc/btrbk.conf+::
+/etc/btrbk/btrbk.conf+::
Default configuration file. The file format and configuration
options are described in *btrbk.conf*(5).
EXIT STATUS
-----------
*btrbk* returns the following error codes:
[horizontal]
0:: No problems occurred.
1:: Generic error code.
2:: Parse error: when parsing command-line options or configuration
file.
3:: Lockfile error: if lockfile is present on startup.
10:: Backup abort: At least one backup task aborted.
255:: Script error.
AVAILABILITY
------------
Please refer to the btrbk project page *<http://digint.ch/btrbk/>* for
further details.
SEE ALSO
--------
*btrbk.conf*(5),
*btrfs*(8)
For more information about btrfs and incremental backups, see the web
site at https://btrfs.wiki.kernel.org/index.php/Incremental_Backup
AUTHOR
------
Axel Burri <axel@tty0.ch>

508
doc/btrbk.conf.5
View File

@ -1,508 +0,0 @@
.TH "btrbk.conf" "5" "2017-09-28" "btrbk v0.26.0-dev" ""
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.SH NAME
btrbk.conf \- btrbk configuration file
.SH SYNOPSIS
.B /etc/btrbk.conf
.br
.B /etc/btrbk/btrbk.conf
.SH DESCRIPTION
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.
.PP
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.
.PP
Blank lines are ignored. A hash character (#) starts a comment
extending until end of line.
.SH SECTIONS
.PP
\fBvolume\fR <volume\-directory>|<url>
.RS 4
Directory of a btrfs volume containing the source subvolume(s) to be
backed up. \fI<volume\-directory>\fR 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=0\fR option.
.RE
.PP
\fBsubvolume\fR <subvolume\-name>
.RS 4
Subvolume to be backed up, relative to the \fI<volume\-directory>\fR
specified in the \fIvolume\fR section. Multiple \fIsubvolume\fR
sections are allowed within \fIvolume\fR sections. Accepts wildcard
character "*".
.RE
.PP
\fBtarget\fR <type> <target\-directory>|<url>
.RS 4
Target type and directory where the backup subvolumes are to be
created. See the TARGET TYPES section for supported
\fI<type>\fR. Multiple \fItarget\fR sections are allowed within
\fIsubvolume\fR sections. A \fItarget\fR section defined in the global
context or in a \fIvolume\fR section is propagated (multiplied) to all
underlying \fIsubvolume\fR sections, unless a target with the same
declaration already exists (hint: run "btrbk config print" to see the
resulting configuration).
.RE
.PP
For the \fIvolume\fR and \fItarget\fR sections, you can specify a
ssh\-url instead of a local directory. The syntax for \fI<url>\fR is:
.PP
.RS 4
.nf
ssh://host.xz/path/to/volume
.fi
.RE
.PP
If a \fI<url>\fR is specified, all access to the filesystem is
performed via ssh, using the "ssh_" options described below. For
convenience, "ssh://<hostname>/<directory>" can also be specified as
"<hostname>:<directory>".
.PP
Note that btrfs is very picky on file names (mainly for security
reasons), only the characters [0\-9] [a\-z] [A\-Z] and "._+\-@" are
allowed.
.RE
.SH OPTIONS
.PP
\fBtransaction_log\fR <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
.PP
\fBtransaction_syslog\fR <facility>|no
.RS 4
If set, all transactions (as described in \fItransaction_log\fR above)
are logged to syslog. The program name used in the messages is
"btrbk". Accepted parameters for \fI<facility>\fR: user, mail, daemon,
auth, lpr, news, cron, authpriv, local0..local7.
.RE
.PP
\fBtimestamp_format\fR short|long|long\-iso
.RS 4
Timestamp format used as postfix for new snapshot subvolume
names. Defaults to \[lq]short\[rq].
.PP
.IP \fBshort\fR 10
YYYYMMDD[_N] (e.g. "20150825", "20150825_1")
.IP \fBlong\fR 10
YYYYMMDD<T>hhmm[_N] (e.g. "20150825T1531")
.IP \fBlong\-iso\fR 10
YYYYMMDD<T>hhmmss\[t+-]hhmm[_N] (e.g. "20150825T153123+0200")
.PP
Note that a postfix "_N" is appended to the timestamp if a snapshot or
backup already exists with the timestamp of current date/time.
.PP
Use \[lq]long\-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).
.PP
Note that using \[lq]long\-iso\[rq] has implications on the
scheduling, see RETENTION POLICY (caveats) below.
.RE
.PP
\fBsnapshot_dir\fR <directory>
.RS 4
Directory in which the btrfs snapshots are created, relative to
\fI<volume\-directory>\fR of the \fIvolume\fR section. Note that btrbk
does not autmatically create this directory, and the snapshot creation
will fail if it is not present.
.RE
.PP
\fBsnapshot_name\fR <basename>
.RS 4
Base name of the created snapshot (and backup). This option is only
valid in the \fIsubvolume\fR section. Defaults to
\fI<subvolume\-name>\fR.
.RE
.PP
\fBsnapshot_create\fR always|onchange|ondemand|no
.RS 4
If set to \[lq]always\[rq], snapshots are always created. If set to
\[lq]onchange\[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
\[lq]ondemand\[rq], snapshots are only created if the 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 \[lq]no\[rq], the snapshots are never created
(useful if another instance of btrbk is taking care of snapshot
creation). Defaults to \[lq]always\[rq].
.RE
.PP
\fBincremental\fR yes|no|strict
.RS 4
If set, incremental backups are created. If set to \[lq]strict\[rq],
non-incremental (initial) backups are never created. Defaults to
\[lq]yes\[rq].
.RE
.PP
\fBsnapshot_preserve\fR no|<retention_policy>
.RS 4
Set retention policy for snapshots (see RETENTION POLICY below). If
set to \[lq]no\[rq], preserve snapshots according to
\fIsnapshot_preserve_min\fR only. Defaults to \[lq]no\[rq].
.RE
.PP
\fBsnapshot_preserve_min\fR 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 \[lq]all\[rq], preserve all snapshots forever. If set
to \[lq]latest\[rq], preserve latest snapshot. Defaults to
\[lq]all\[rq].
.RE
.PP
\fBtarget_preserve\fR no|<retention_policy>
.RS 4
Set retention policy for backups (see RETENTION POLICY below). If set
to \[lq]no\[rq], preserve backups according to
\fItarget_preserve_min\fR only. Defaults to \[lq]no\[rq].
.RE
.PP
\fBtarget_preserve_min\fR 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 \[lq]all\[rq], preserve all backups forever. If set to
\[lq]latest\[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 \[lq]no\[rq], only the backups following the
\fItarget_preserve\fR policy are created. Defaults to \[lq]all\[rq].
.RE
.PP
\fBarchive_preserve\fR no|<retention_policy>
.PD 0
.PP
\fBarchive_preserve_min\fR all|latest|no|<number>{h,d,w,m,y}
.PD
.RS 4
Set retention policy for archives ("btrbk archive" command), with same
semantics as \fItarget_preserve\fR, \fItarget_preserve_min\fR.
.RE
.PP
\fBpreserve_day_of_week\fR monday|tuesday|...|sunday
.RS 4
Defines on what day a backup/snapshot is considered as a weekly
backup. Defaults to \[lq]sunday\[rq].
.RE
.PP
\fBgroup\fR <group\-name>[,<group\-name>]...
.RS 4
Add the current section (volume, subvolume or target) to a
user-defined group, which can be used as filter for several btrbk
commands.
.RE
.PP
\fBssh_identity\fR <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
.PP
\fBssh_user\fR <username>
.RS 4
Remote username for ssh. Defaults to \[lq]root\[rq]. Note that you
will have to make sure that the remote user is able to run
"/sbin/btrfs" (which needs root privileges).
.RE
.PP
\fBssh_port\fR <port>
.RS 4
Port to connect to on the remote host. Defaults to \[lq]default\[rq]
(the port specified in \fIssh_config\fR, which defaults to 22).
.RE
.PP
\fBssh_compression\fR yes|no
.RS 4
Enables or disables the compression of ssh connections. Defaults to
\[lq]no\[rq].
.RE
.PP
\fBssh_cipher_spec\fR <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
\[lq]default\[rq] (the ciphers specified in \fIssh_config\fR).
.RE
.PP
\fBstream_compress\fR <compress_command>|no
.RS 4
Compress the btrfs send stream before transferring it from/to remote
locations. Defaults to \[lq]no\[rq]. If enabled, make sure that
<compress_command> is available on the source and target
hosts. Supported \fI<compress_command>\fR: gzip, pigz, bzip2, pbzip2,
xz, lzo, lz4.
.RE
.PP
\fBstream_compress_level\fR default|<number>
.RS 4
Compression level for the specified <compress_command>. Refer to the
related man-page for details (usually [1..9], where 1 means fastest
compression). Defaults to \[lq]default\[rq] (the default compression
level of <compress_command>).
.RE
.PP
\fBstream_compress_threads\fR default|<number>
.RS 4
Number of threads to use for <compress_command>. Only supported for
"pigz", "pbzip2" and recent versions of "xz".
.RE
.PP
\fBstream_buffer\fR <size>|no \fI*experimental*\fR
.RS 4
Add a buffer to the btrfs send stream (in front of "btrfs receive"),
with a maximum size of \fI<size>\fR. 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>\fR to denote kilobytes (*1024), megabytes, gigabytes, or
a percentage of total physical memory. Defaults to \[lq]no\[rq]. If
enabled, make sure that the "mbuffer" command is available on the
target host.
.RE
.PP
\fBrate_limit\fR <rate>|no
.RS 4
Limit the transfer to a maximum of \fI<rate>\fR bytes per second. A
suffix of "k", "m", "g", or "t" can be added to denote kilobytes
(*1024), megabytes, and so on. Defaults to \[lq]no\[rq]. If enabled
for remote sources, make sure that the "pv" command is available on
the source host.
.RE
.PP
\fBlockfile\fR <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\fR,
\fI\-\-dry\-run\fR). See also \fI\-\-lockfile\fR command-line option.
.RE
.PP
\fBbtrfs_commit_delete\fR 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 \[lq]no\[rq].
.RE
.PP
\fBbackend\fR btrfs-progs|btrfs-progs-btrbk|btrfs-progs-sudo
.RS 4
Backend filesystem utilities to be used for btrfs specific operations. The
default \[lq]btrfs-progs\[rq] simply executes btrfs(8) commands groups
(e.g. "btrfs subvolume show").
.IP \[bu] 2
If set
to \[lq]btrfs-progs-btrbk\[rq], specific btrfs(8) commands groups
needs to be 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
<https://github.com/digint/btrfs-progs-btrbk>.
.IP \[bu] 2
If set to \[lq]btrfs-progs-sudo\[rq], btrfs commands are prefixed with
"sudo -n" (e.g. "sudo -n btrfs subvolume show" instead of "btrfs
subvolume show"). Make sure to have apropriate (root) permissions for
"btrfs" command groups in /etc/sudoers.
.PP
For convenience, it is also possible to set \fIbackend_local\fR or
\fIbackend_remote\fR options, which will override the backend only for
local or remote sources/targets (e.g. "backend_remote
btrfs-progs-btrbk").
.RE
.PP
\fBsnapshot_qgroup_destroy\fR yes|no \fI*experimental*\fR
.PD 0
.PP
\fBtarget_qgroup_destroy\fR yes|no \fI*experimental*\fR
.PP
\fBarchive_qgroup_destroy\fR yes|no \fI*experimental*\fR
.PD
.RS 4
Whenever a subvolume is deleted, also destroy corresponding default
qgroup "0/<subvol-id>". Only useful if you have enabled btrfs quota
support. See also: <https://bugzilla.kernel.org/show_bug.cgi?id=91751>
.RE
.SH RETENTION POLICY
btrbk uses separate retention policies for snapshots and backups,
which are defined by the \fIsnapshot_preserve_min\fR,
\fIsnapshot_preserve\fR, \fItarget_preserve_min\fR,
\fItarget_preserve\fR, and the \fIpreserve_day_of_week\fR
configuration options.
.PP
Within this section, any statement about "backups" is always valid for
backups as well as snapshots, referring to \fItarget_preserve\fR or
\fIsnapshot_preserve\fR respectively.
.PP
The format for \fI<retention_policy>\fR is:
.PP
.RS 4
[<hourly>h] [<daily>d] [<weekly>w] [<monthly>m] [<yearly>y]
.RE
.PP
With the following semantics:
.PP
.B hourly
.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\fR to \[lq]long\[rq] or \[lq]long\-iso\[rq], or
the scheduler will interpret the time as "00:00" (midnight).
.RE
.PP
.B daily
.RS 4
Defines how many days back daily backups should be preserved. The
first backup of a day is considered a daily backup.
.RE
.PP
.B weekly
.RS 4
Defines how many weeks back weekly backups should be preserved. The
first daily backup created at \fIpreserve_day_of_week\fR (or the first
backup in this week if none was made on the exact day) is considered
as a weekly backup.
.RE
.PP
.B monthly
.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
.PP
.B yearly
.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
.PP
Use an asterisk for \[lq]all\[rq] (e.g. "target_preserve 60d *m"
states: "preserve daily backups for 60 days back, and all monthly
backups").
.PP
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.
.PP
Caveats:
.IP \[bu] 2
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".
.IP \[bu] 2
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)).
.SH TARGET TYPES
.PP
\fBsend\-receive\fR
.RS 4
Backup to a btrfs filesystem, using "btrfs send/receive". This is the
recommended (standard) target type. The \fI<target\-directory>\fR 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
.PP
\fBraw\fR \fI*experimental*\fR
.RS 4
Backup to a raw (filesystem independent) file from the output of
btrfs\-send(8), with optional compression and encryption.
.PP
Note that the target preserve mechanism is currently disabled for
incremental raw backups (btrbk does not delete any incremental raw
files)!
.PP
Additional options for raw targets:
.PP
.RS 4
raw_target_compress gzip|pigz|bzip2|pbzip2|xz|lzo|lz4|no
.PD 0
.PP
raw_target_compress_level default|<number>
.PP
raw_target_compress_threads default|<number>
.PP
raw_target_split <size>|no
.PP
raw_target_block_size <number> (defaults to 128K)
.PP
raw_target_encrypt gpg|openssl_enc|no
.RE
.PD
.PP
Additional options for "raw_target_encrypt gpg":
.PP
.RS 4
gpg_keyring <file>
.PD 0
.PP
gpg_recipient <name>
.RE
.PD
.PP
Additional options for "raw_target_encrypt openssl_enc" (\fIvery
experimental\fR):
.PP
.RS 4
openssl_ciphername <name> (defaults to "aes-256-cbc")
.PD 0
.PP
openssl_iv_size <size-in-bytes>|no (depends on selected cipher)
.PP
openssl_keyfile <file>|no
.PP
kdf_backend <file>|no
.PP
kdf_keysize <size> (defaults to "32")
.PP
kdf_keygen once|each (defaults to "once")
.RE
.PD
.PP
Raw backups consist of two files: the main data file containing the
btrfs send stream, and a sidecar file ".info" containing metadata:
.RS 4
.PP
<snapshot\-name>.<timestamp>[_N].btrfs[.gz|.bz2|.xz][.gpg]
<snapshot\-name>.<timestamp>[_N].btrfs[.gz|.bz2|.xz][.gpg].info
.RE
.PP
For \fIincremental\fR backups ("incremental yes"), please note that:
.IP 1. 4
As soon as a single \fIincremental\fR 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.
.IP 2. 4
There is currently no support for rotation of incremental backups: if
\fIincremental\fR is set, a full backup must be triggered manually
from time to time in order to be able to delete old backups.
.RE
.SH AVAILABILITY
Please refer to the btrbk project page \fBhttp://digint.ch/btrbk/\fR
for further details.
.SH SEE ALSO
.BR btrbk (1)
.SH AUTHOR
Axel Burri <axel@tty0.ch>

436
doc/btrbk.conf.5.asciidoc Normal file
View File

@ -0,0 +1,436 @@
btrbk.conf(5)
=============
:date: 2017-10-09
:revision: 0.26.0-dev
:man manual: Btrbk Manual
:man source: Btrbk
NAME
----
btrbk.conf - btrbk configuration file
SYNOPSIS
--------
[literal]
/etc/btrbk.conf
/etc/btrbk/btrbk.conf
DESCRIPTION
-----------
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.
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.
Blank lines are ignored. A hash character (#) starts a comment
extending until end of line.
SECTIONS
--------
*volume* <volume-directory>|<url>::
Directory of a btrfs volume containing the source subvolume(s)
to be backed up. '<volume-directory>' must be an absolute path
and point to a btrfs volume (or subvolume). Usually the mount
point of a btrfs filesystem mounted with the 'subvolid=0'
option.
*subvolume* <subvolume-name>::
Subvolume to be backed up, relative to the '<volume-directory>'
specified in the 'volume' section. Multiple 'subvolume' sections
are allowed within 'volume' sections. Accepts wildcard character
"*".
*target* <type> <target-directory>|<url>::
Target type and directory where the backup subvolumes are to be
created. See the <<_target_types,TARGET TYPES>> section for
supported '<type>'. Multiple 'target' sections are allowed within
'subvolume' sections. A 'target' section defined in the global
context or in a 'volume' section is propagated (multiplied) to all
underlying 'subvolume' sections, unless a target with the same
declaration already exists (hint: run "btrbk config print" to see
the resulting configuration).
For the 'volume' and 'target' sections, you can specify a ssh-url
instead of a local directory. The syntax for '<url>' is:
ssh://host.xz/path/to/volume
If a '<url>' is specified, all access to the filesystem is performed
via ssh, using the "ssh_" options described below. For convenience,
"+ssh://<hostname>/<directory>+" can also be specified as
"+<hostname>:<directory>+".
Note that btrfs is very picky on file names (mainly for security
reasons), only the characters [0-9] [a-z] [A-Z] and "._+-@" are
allowed.
OPTIONS
-------
*transaction_log* <file>|no::
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".
*transaction_syslog* <facility>|no::
If set, all transactions (as described in 'transaction_log' above)
are logged to syslog. The program name used in the messages is
"btrbk". Accepted parameters for '<facility>': user, mail,
daemon, auth, lpr, news, cron, authpriv, local0..local7.
*timestamp_format* short|long|long-iso::
Timestamp format used as postfix for new snapshot subvolume
names. Defaults to ``short''.
+
--
*short*;; `YYYYMMDD[_N]` (e.g. "20150825", "20150825_1")
*long*;; `YYYYMMDD<T>hhmm[_N]` (e.g. "20150825T1531")
*long-iso*;; `YYYYMMDD<T>hhmmss&plusmn;hhmm[_N]` (e.g. "20150825T153123+0200")
--
+
Note that a postfix "_N" is appended to the timestamp if a snapshot or
backup already exists with the timestamp of current date/time.
+
Use ``long-iso'' 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).
+
Note that using ``long-iso'' has implications on the scheduling, see
<<_retention_policy,RETENTION POLICY>> (caveats) below.
*snapshot_dir* <directory>::
Directory in which the btrfs snapshots are created, relative to
'<volume-directory>' of the 'volume' section. Note that btrbk does
not autmatically create this directory, and the snapshot creation
will fail if it is not present.
*snapshot_name* <basename>::
Base name of the created snapshot (and backup). This option is
only valid in the 'subvolume' section. Defaults to
'<subvolume-name>'.
*snapshot_create* always|onchange|ondemand|no::
If set to ``always'', snapshots are always created. If set to
``onchange'', 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
``ondemand'', snapshots are only created if the 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 ``no'', the snapshots are never created
(useful if another instance of btrbk is taking care of snapshot
creation). Defaults to ``always''.
*incremental* yes|no|strict::
If set, incremental backups are created. If set to ``strict'',
non-incremental (initial) backups are never created. Defaults to
``yes''.
*snapshot_preserve* no|<retention_policy>::
Set retention policy for snapshots (see
<<_retention_policy,RETENTION POLICY>> below). If set to ``no'',
preserve snapshots according to 'snapshot_preserve_min'
only. Defaults to ``no''.
*snapshot_preserve_min* all|latest|<number>{h,d,w,m,y}::
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 ``all'', preserve all snapshots forever. If
set to ``latest'', preserve latest snapshot. Defaults to ``all''.
*target_preserve* no|<retention_policy>::
Set retention policy for backups (see
<<_retention_policy,RETENTION POLICY>> below). If set to ``no'',
preserve backups according to 'target_preserve_min' only. Defaults
to ``no''.
*target_preserve_min* all|latest|no|<number>{h,d,w,m,y}::
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 ``all'', preserve all backups forever. If set to
``latest'', always preserve the latest backup (useful in
conjunction with "target_preserve no", if you want to keep the
latest backup only). If set to ``no'', only the backups following
the 'target_preserve' policy are created. Defaults to ``all''.
*archive_preserve* no|<retention_policy>:: {blank}
*archive_preserve_min* all|latest|no|<number>{h,d,w,m,y}::
Set retention policy for archives ("btrbk archive" command), with
same semantics as 'target_preserve', 'target_preserve_min'.
*preserve_day_of_week* monday|tuesday|...|sunday"::
Defines on what day a backup/snapshot is considered as a weekly
backup. Defaults to ``sunday''.
*group* <group-name>[,<group-name>]...::
Add the current section (volume, subvolume or target) to a
user-defined group, which can be used as filter for several btrbk
commands.
*ssh_identity* <file>::
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.
*ssh_user* <username>::
Remote username for ssh. Defaults to ``root''. Note that you will
have to make sure that the remote user is able to run
"/sbin/btrfs" (which needs root privileges).
*ssh_port* <port>::
Port to connect to on the remote host. Defaults to ``default''
(the port specified in 'ssh_config', which defaults to 22).
*ssh_compression* yes|no::
Enables or disables the compression of ssh connections. Defaults
to ``no''.
*ssh_cipher_spec* <cipher_spec>::
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 ``default'' (the ciphers specified in 'ssh_config').
*stream_compress* <compress_command>|no::
Compress the btrfs send stream before transferring it from/to
remote locations. Defaults to ``no''. If enabled, make sure that
<compress_command> is available on the source and target
hosts. Supported '<compress_command>': gzip, pigz, bzip2, pbzip2,
xz, lzo, lz4.
*stream_compress_level* default|<number>::
Compression level for the specified <compress_command>. Refer to
the related man-page for details (usually [1..9], where 1 means
fastest compression). Defaults to ``default'' (the default
compression level of <compress_command>).
*stream_compress_threads* default|<number>::
Number of threads to use for <compress_command>. Only supported
for "pigz", "pbzip2" and recent versions of "xz".
*stream_buffer* <size>|no _*experimental*_::
Add a buffer to the btrfs send stream (in front of "btrfs
receive"), with a maximum size of '<size>'. 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 '<size>' to denote kilobytes (*1024),
megabytes, gigabytes, or a percentage of total physical
memory. Defaults to ``no''. If enabled, make sure that the
"mbuffer" command is available on the target host.
*rate_limit* <rate>|no::
Limit the transfer to a maximum of '<rate>' bytes per second. A
suffix of "k", "m", "g", or "t" can be added to denote kilobytes
(*1024), megabytes, and so on. Defaults to ``no''. If enabled for
remote sources, make sure that the "pv" command is available on
the source host.
*lockfile* <file>|no::
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 ('-n',
'--dry-run'). See also '--lockfile' command-line option.
*btrfs_commit_delete* after|each|no::
If set, make sure the deletion of snapshot and backup subvolumes
are committed to disk when btrbk terminates. Defaults to ``no''.
*backend* btrfs-progs|btrfs-progs-btrbk|btrfs-progs-sudo::
Backend filesystem utilities to be used for btrfs specific
operations. The default ``btrfs-progs'' simply executes btrfs(8)
commands groups (e.g. "btrfs subvolume show").
+
--
* If set to ``btrfs-progs-btrbk'', specific btrfs(8) commands groups
needs to be 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
<https://github.com/digint/btrfs-progs-btrbk>.
* If set to ``btrfs-progs-sudo'', btrfs commands are prefixed with
"sudo -n" (e.g. "sudo -n btrfs subvolume show" instead of "btrfs
subvolume show"). Make sure to have apropriate (root) permissions
for "btrfs" command groups in /etc/sudoers.
--
+
For convenience, it is also possible to set 'backend_local' or
'backend_remote' options, which will override the backend only for
local or remote sources/targets (e.g. "backend_remote
btrfs-progs-btrbk").
*snapshot_qgroup_destroy* yes|no _*experimental*_:: {blank}
*target_qgroup_destroy* yes|no _*experimental*_:: {blank}
*archive_qgroup_destroy* yes|no _*experimental*_::
Whenever a subvolume is deleted, also destroy corresponding
default qgroup "0/<subvol-id>". Only useful if you have enabled
btrfs quota support. See also:
<https://bugzilla.kernel.org/show_bug.cgi?id=91751>
RETENTION POLICY
----------------
btrbk uses separate retention policies for snapshots and backups,
which are defined by the 'snapshot_preserve_min', 'snapshot_preserve',
'target_preserve_min', 'target_preserve', and the
'preserve_day_of_week' configuration options.
Within this section, any statement about "backups" is always valid for
backups as well as snapshots, referring to 'target_preserve' or
'snapshot_preserve' respectively.
The format for '<retention_policy>' is:
[<hourly>h] [<daily>d] [<weekly>w] [<monthly>m] [<yearly>y]
With the following semantics:
*hourly*::
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 'timestamp_format' to ``long'' or ``long-iso'', or the
scheduler will interpret the time as "00:00" (midnight).
*daily*::
Defines how many days back daily backups should be preserved. The
first backup of a day is considered a daily backup.
*weekly*::
Defines how many weeks back weekly backups should be
preserved. The first daily backup created at
'preserve_day_of_week' (or the first backup in this week if none
was made on the exact day) is considered as a weekly backup.
*monthly*::
Defines how many months back monthly backups should be
preserved. Every first weekly backup in a month is considered a
monthly backup.
*yearly*::
Defines for how many years back yearly backups should be
preserved. Every first monthly backup in a year is considered a
yearly backup.
Use an asterisk for ``all'' (e.g. "target_preserve 60d *m"
states: "preserve daily backups for 60 days back, and all monthly
backups").
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.
Caveats:
* 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".
* 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)).
TARGET TYPES
------------
*send-receive*::
Backup to a btrfs filesystem, using "btrfs send/receive". This is
the recommended (standard) target type. The '<target-directory>'
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).
*raw* _*experimental*_::
Backup to a raw (filesystem independent) file from the output of
btrfs-send(8), with optional compression and encryption.
+
--
Note that the target preserve mechanism is currently disabled for
incremental raw backups (btrbk does not delete any incremental raw
files)!
Additional options for raw targets:
*raw_target_compress* gzip|pigz|bzip2|pbzip2|xz|lzo|lz4|no:: {blank}
*raw_target_compress_level* default|<number>:: {blank}
*raw_target_compress_threads* default|<number>:: {blank}
*raw_target_split* <size>|no:: {blank}
*raw_target_block_size* <number> (defaults to 128K):: {blank}
*raw_target_encrypt* gpg|openssl_enc|no:: {blank}
Additional options for "raw_target_encrypt gpg":
*gpg_keyring* <file>:: {blank}
*gpg_recipient* <name>:: {blank}
Additional options for "raw_target_encrypt openssl_enc" ('very
experimental'):
*openssl_ciphername* <name> (defaults to ``aes-256-cbc''):: {blank}
*openssl_iv_size* <size-in-bytes>|no (depends on selected cipher):: {blank}
*openssl_keyfile* <file>|no:: {blank}
*kdf_backend* <file>|no:: {blank}
*kdf_keysize* <size> (defaults to ``32''):: {blank}
*kdf_keygen* once|each (defaults to ``once''):: {blank}
Raw backups consist of two files: the main data file containing the
btrfs send stream, and a sidecar file ".info" containing metadata:
<snapshot-name>.<timestamp>[_N].btrfs[.gz|.bz2|.xz][.gpg]
<snapshot-name>.<timestamp>[_N].btrfs[.gz|.bz2|.xz][.gpg].info
For 'incremental' backups ("incremental yes"), please note that:
* As soon as a single 'incremental' 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.
* There is currently no support for rotation of incremental backups:
if 'incremental' is set, a full backup must be triggered manually
from time to time in order to be able to delete old backups.
--
AVAILABILITY
------------
Please refer to the btrbk project page *<http://digint.ch/btrbk/>*
for further details.
SEE ALSO
--------
*btrbk*(1)
AUTHOR
------
Axel Burri <axel@tty0.ch>

107
doc/ssh_filter_btrbk.1
View File

@ -1,107 +0,0 @@
.TH "ssh_filter_btrbk" "1" "2017-08-21" "btrbk v0.26.0-dev" ""
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.SH NAME
ssh_filter_btrbk.sh \- ssh command filter script for btrbk
.SH SYNOPSIS
.nf
\fBssh_filter_btrbk.sh\fR [\-s|\-\-source] [\-t|\-\-target] [\-d|\-\-delete] [\-i|\-\-info]
[\-p|\-\-restrict\-path <path>] [\-l|\-\-log] [\-\-sudo]
.fi
.SH DESCRIPTION
\fBssh_filter_btrbk.sh\fR restricts SSH commands to \fIbtrfs\fR
commands used by \fIbtrbk\fR. It examines the SSH_ORIGINAL_COMMAND
environment variable (set by sshd) and executes it only if it matches
commands used by \fIbtrbk\fR. The accepted commands are specified by
the "\-\-source", "\-\-target", "\-\-delete" and "\-\-info" options.
.PP
Note that the following btrfs commands are always allowed: "btrfs
subvolume show", "btrfs subvolume list".
.PP
Note that commands for stream compression (pipes through gzip, pigz,
bzip2, pbzip2, xz, lzop, lz4), rate limiting (pipes through "pv -L"),
and stream buffer (pipes through "mbuffer") are always allowed.
.PP
Example line in /root/.ssh/authorized_keys on a backup target host:
.PP
.RS 4
.nf
command="ssh_filter_btrbk.sh \-\-target \-\-delete \-\-restrict\-path /mnt/btr_backup" ssh\-rsa AAAAB3NzaC1...hwumXFRQBL btrbk@mydomain.com
.fi
.RE
.SH OPTIONS
.PP
\-s, \-\-source
.RS 4
Allow commands for backup source: "btrfs subvolume snapshot", "btrfs
send". Equivalent to "\-\-snapshot \-\-send".
.RE
.PP
\-t, \-\-target
.RS 4
Allow commands for backup target: "btrfs receive", "realpath" and "cat
/proc/self/mounts".
.RE
.PP
\-d, \-\-delete
.RS 4
Allow commands for subvolume deletion: "btrfs subvolume delete". This
is used for backup source if \fIsnapshot_preserve_daily\fR is not set
to \[lq]all\[rq], and for backup targets if
\fItarget_preserve_daily\fR is not set to \[lq]all\[rq].
.RE
.PP
\-c, \-\-compress
.RS 4
Allow commands for stream compression (pipes through gzip, pigz,
bzip2, pbzip2, xz, lzo, lz4). Needed if \fIstream_compress\fR is set.
.RE
.PP
\-i, \-\-info
.RS 4
Allow informative commands: "btrfs subvolume find\-new", "btrfs
filesystem usage". This is used by btrbk \fIinfo\fR and \fIdiff\fR
commands.
.RE
.PP
\-\-snapshot
.RS 4
Allow btrfs snapshot command: "btrfs subvolume snapshot".
.RE
.PP
\-\-send
.RS 4
Allow btrfs send command: "btrfs send".
.RE
.PP
\-\-receive
.RS 4
Allow btrfs receive command: "btrfs receive".
.RE
.PP
\-p, \-\-restrict\-path <path>
.RS 4
Restrict btrfs commands to <path>.
.RE
.PP
\-l, \-\-log
.RS 4
Log ACCEPT and REJECT messages to the system log.
.RE
.PP
\-\-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
Please refer to the btrbk project page \fBhttp://digint.ch/btrbk/\fR
for further details.
.SH SEE ALSO
.BR btrbk (1),
.BR btrbk.conf (5),
.BR btrfs (1)
.SH AUTHOR
Axel Burri <axel@tty0.ch>

108
doc/ssh_filter_btrbk.1.asciidoc Normal file
View File

@ -0,0 +1,108 @@
ssh_filter_btrbk(1)
===================
:date: 2017-10-09
:revision: 0.26.0-dev
:man manual: Btrbk Manual
:man source: Btrbk
NAME
----
ssh_filter_btrbk.sh - ssh command filter script for btrbk
SYNOPSIS
--------
[literal]
ssh_filter_btrbk.sh [-s|--source] [-t|--target] [-d|--delete] [-i|--info]
[-p|--restrict-path <path>] [-l|--log] [--sudo]
DESCRIPTION
-----------
*ssh_filter_btrbk.sh* restricts SSH commands to 'btrfs' commands used
by 'btrbk'. It examines the SSH_ORIGINAL_COMMAND environment variable
(set by sshd) and executes it only if it matches commands used by
'btrbk'. The accepted commands are specified by the "--source",
"--target", "--delete" and "--info" options.
Note that the following btrfs commands are always allowed: "btrfs
subvolume show", "btrfs subvolume list".
Note that commands for stream compression (pipes through gzip, pigz,
bzip2, pbzip2, xz, lzop, lz4), rate limiting (pipes through "pv -L"),
and stream buffer (pipes through "mbuffer") are always allowed.
Example line in /root/.ssh/authorized_keys on a backup target host:
command="ssh_filter_btrbk.sh --target --delete --restrict-path /mnt/btr_backup" ssh-rsa AAAAB3NzaC1...hwumXFRQBL btrbk@mydomain.com
OPTIONS
-------
-s, --source::
Allow commands for backup source: "btrfs subvolume snapshot",
"btrfs send". Equivalent to "--snapshot --send".
-t, --target::
Allow commands for backup target: "btrfs receive", "realpath" and
"cat /proc/self/mounts".
-d, --delete::
Allow commands for subvolume deletion: "btrfs subvolume
delete". This is used for backup source if
'snapshot_preserve_daily' is not set to ``all'', and for backup
targets if 'target_preserve_daily' is not set to ``all''.
-c, --compress::
Allow commands for stream compression (pipes through gzip, pigz,
bzip2, pbzip2, xz, lzo, lz4). Needed if 'stream_compress' is set.
-i, --info::
Allow informative commands: "btrfs subvolume find-new", "btrfs
filesystem usage". This is used by btrbk 'info' and 'diff'
commands.
--snapshot::
Allow btrfs snapshot command: "btrfs subvolume snapshot".
--send::
Allow btrfs send command: "btrfs send".
--receive::
Allow btrfs receive command: "btrfs receive".
-p, --restrict-path <path>::
Restrict btrfs commands to <path>.
-l, --log::
Log ACCEPT and REJECT messages to the system log.
--sudo::
Allow btrfs commands to be called via sudo. Enable this if you
have "backend btrfs-progs-sudo" in your btrbk configuration file.
AVAILABILITY
------------
Please refer to the btrbk project page *<http://digint.ch/btrbk/>* for
further details.
SEE ALSO
--------
*btrbk*(1),
*btrbk.conf*(5),
*btrfs*(8)
AUTHOR
------
Axel Burri <axel@tty0.ch>