2016-03-23 11:58:23 +01:00
|
|
|
.TH "btrbk.conf" "5" "2016-03-23" "btrbk v0.23.0-dev" ""
|
2015-09-03 18:02:19 +02:00
|
|
|
.\" disable hyphenation
|
|
|
|
.nh
|
|
|
|
.\" disable justification (adjust text to left margin only)
|
|
|
|
.ad l
|
2015-02-08 13:43:29 +01:00
|
|
|
.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
|
2015-05-25 17:13:36 +02:00
|
|
|
generated. The retention policy, as well as most other options can be
|
|
|
|
defined either globally or within a section.
|
2015-02-08 13:43:29 +01:00
|
|
|
.PP
|
|
|
|
The options specified always apply to the last section encountered,
|
2015-04-18 20:18:11 +02:00
|
|
|
superseding the values set in upper-level sections. This means that
|
2015-02-08 13:43:29 +01:00
|
|
|
global options must be set before any sections are defined.
|
2015-09-29 15:59:15 +02:00
|
|
|
.SH SECTIONS
|
2015-09-03 18:02:19 +02:00
|
|
|
.PP
|
2015-02-08 13:43:29 +01:00
|
|
|
\fBvolume\fR <volume-directory>|<url>
|
2015-09-03 18:02:19 +02:00
|
|
|
.RS 4
|
2015-04-28 19:08:20 +02:00
|
|
|
Directory of a btrfs volume containing the source subvolume(s) to be
|
2015-05-25 17:13:36 +02:00
|
|
|
backed up. \fI<volume-directory>\fR must be an absolute path and point
|
2015-04-28 19:08:20 +02:00
|
|
|
to a btrfs volume (or subvolume). Usually the mount point of a btrfs
|
|
|
|
filesystem mounted with the \fIsubvolid=0\fR option.
|
2015-09-03 18:02:19 +02:00
|
|
|
.RE
|
|
|
|
.PP
|
2015-02-08 13:43:29 +01:00
|
|
|
\fBsubvolume\fR <subvolume-name>
|
2015-09-03 18:02:19 +02:00
|
|
|
.RS 4
|
2015-05-25 17:13:36 +02:00
|
|
|
Subvolume to be backed up, relative to the \fI<volume-directory>\fR
|
2015-09-29 15:59:15 +02:00
|
|
|
specified in the \fIvolume\fR section. Multiple \fIsubvolume\fR
|
|
|
|
sections are allowed within \fIvolume\fR sections.
|
2015-09-03 18:02:19 +02:00
|
|
|
.RE
|
|
|
|
.PP
|
2015-09-29 15:59:15 +02:00
|
|
|
\fBtarget\fR <type> <target-directory>|<url>
|
2015-09-03 18:02:19 +02:00
|
|
|
.RS 4
|
2015-02-08 13:43:29 +01:00
|
|
|
Target type and directory where the backup subvolumes are to be
|
2015-09-29 15:59:15 +02:00
|
|
|
created. See the TARGET TYPES section for supported
|
|
|
|
\fI<type>\fR. Multiple \fItarget\fR sections are allowed within
|
|
|
|
\fIsubvolume\fR sections.
|
|
|
|
.RE
|
2015-02-08 13:43:29 +01:00
|
|
|
.PP
|
2015-09-29 15:59:15 +02:00
|
|
|
For the \fIvolume\fR and \fItarget\fR sections, you can specify a
|
2015-02-08 13:43:29 +01:00
|
|
|
ssh-url instead of a local directory. The syntax for \fI<url>\fR is:
|
2015-09-03 18:02:19 +02:00
|
|
|
.PP
|
|
|
|
.RS 4
|
|
|
|
.nf
|
2015-02-08 13:43:29 +01:00
|
|
|
ssh://host.xz/path/to/volume
|
2015-09-03 18:02:19 +02:00
|
|
|
.fi
|
|
|
|
.RE
|
2015-02-08 13:43:29 +01:00
|
|
|
.PP
|
2015-04-13 23:42:15 +02:00
|
|
|
Note that btrfs is very picky on file names (mainly for security
|
2015-04-28 20:17:47 +02:00
|
|
|
reasons), only the characters [0-9] [a-z] [A-Z] and "._+-@" are
|
2015-04-13 23:42:15 +02:00
|
|
|
allowed.
|
2015-09-03 18:02:19 +02:00
|
|
|
.RE
|
2015-09-29 15:59:15 +02:00
|
|
|
.SH OPTIONS
|
|
|
|
.PP
|
2015-10-22 17:45:27 +02:00
|
|
|
\fBtransaction_log\fR <file>
|
|
|
|
.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.
|
|
|
|
.RE
|
|
|
|
.PP
|
2015-09-29 15:59:15 +02:00
|
|
|
\fBtimestamp_format\fR short|long
|
|
|
|
.RS 4
|
|
|
|
Timestamp format used as postfix for new snapshot subvolume names.
|
2015-11-02 20:09:19 +01:00
|
|
|
Defaults to \[lq]short\[rq].
|
|
|
|
.PP
|
|
|
|
.IP \fBshort\fR
|
|
|
|
YYYYMMDD[_N] (e.g. "20150825", "20150825_1")
|
|
|
|
.IP \fBlong\fR
|
|
|
|
YYYYMMDD<T>hhmm[_N] (e.g. "20150825T1531")
|
2015-09-29 15:59:15 +02:00
|
|
|
.PP
|
|
|
|
Note that a postfix "_N" is only appended to the timestamp if a
|
|
|
|
snapshot/backup already exists with the timestamp of current
|
|
|
|
date/time.
|
|
|
|
.RE
|
2015-09-03 18:02:19 +02:00
|
|
|
.PP
|
2015-02-08 13:43:29 +01:00
|
|
|
\fBsnapshot_dir\fR <directory>
|
2015-09-03 18:02:19 +02:00
|
|
|
.RS 4
|
2015-04-18 20:18:11 +02:00
|
|
|
Directory in which the btrfs snapshots are created, relative to
|
2015-02-08 13:43:29 +01:00
|
|
|
\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.
|
2015-09-03 18:02:19 +02:00
|
|
|
.RE
|
|
|
|
.PP
|
|
|
|
\fBsnapshot_name\fR <basename>
|
|
|
|
.RS 4
|
|
|
|
Base name of the created snapshot (and backup). This option is only
|
2015-09-24 14:56:22 +02:00
|
|
|
valid in the \fIsubvolume\fR section. Defaults to
|
|
|
|
\fI<subvolume-name>\fR.
|
2015-09-03 18:02:19 +02:00
|
|
|
.RE
|
|
|
|
.PP
|
2015-05-25 14:38:32 +02:00
|
|
|
\fBsnapshot_create\fR always|ondemand|onchange|no
|
2015-09-03 18:02:19 +02:00
|
|
|
.RS 4
|
2015-05-25 14:38:32 +02:00
|
|
|
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]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]always\[rq], snapshots are always
|
|
|
|
created. If set to \[lq]no\[rq], the snapshots are never created
|
|
|
|
(useful in conjunction with the \fIresume_missing\fR option if another
|
|
|
|
instance of btrbk is taking care of snapshot creation). Defaults to
|
|
|
|
\[lq]always\[rq].
|
2015-09-03 18:02:19 +02:00
|
|
|
.RE
|
|
|
|
.PP
|
2015-04-18 20:18:11 +02:00
|
|
|
\fBincremental\fR yes|no|strict
|
2015-09-03 18:02:19 +02:00
|
|
|
.RS 4
|
2015-05-25 17:13:36 +02:00
|
|
|
If set, incremental backups are created. If set to \[lq]strict\[rq],
|
|
|
|
non-incremental (initial) backups are never created. Defaults to
|
|
|
|
\[lq]yes\[rq].
|
2015-09-03 18:02:19 +02:00
|
|
|
.RE
|
|
|
|
.PP
|
2015-04-01 14:21:50 +02:00
|
|
|
\fBresume_missing\fR yes|no
|
2015-09-03 18:02:19 +02:00
|
|
|
.RS 4
|
2015-04-01 14:21:50 +02:00
|
|
|
If set, the backups in the target directory are compared to the source
|
|
|
|
snapshots, and missing backups are created if needed (complying to the
|
2015-05-20 13:50:18 +02:00
|
|
|
target preserve matrix). Defaults to \[lq]yes\[rq].
|
2015-09-03 18:02:19 +02:00
|
|
|
.RE
|
|
|
|
.PP
|
2016-02-29 23:19:55 +01:00
|
|
|
\fBtarget_preserve\fR [<daily>d] [<weekly>w] [<monthly>m] [<yearly>y]
|
|
|
|
.RS 4
|
|
|
|
Shortcut to set \fItarget_preserve_daily\fR,
|
|
|
|
\fItarget_preserve_weekly\fR, \fItarget_preserve_monthly\fR and
|
|
|
|
\fItarget_preserve_yearly\fR options (see below) on a single line. Use
|
|
|
|
an asterisk for \[lq]all\[rq] (e.g. "target_preserve 60d *m" expands
|
|
|
|
to "target_preserve_daily 60" and "target_preserve_monthly all").
|
|
|
|
.RE
|
|
|
|
.PP
|
2015-02-08 13:43:29 +01:00
|
|
|
\fBtarget_preserve_daily\fR all|<number>
|
2015-09-03 18:02:19 +02:00
|
|
|
.RS 4
|
2015-05-20 13:50:18 +02:00
|
|
|
How many days of backups should be preserved. Defaults to \[lq]all\[rq].
|
2015-09-03 18:02:19 +02:00
|
|
|
.RE
|
|
|
|
.PP
|
2015-02-08 13:43:29 +01:00
|
|
|
\fBtarget_preserve_weekly\fR all|<number>
|
2015-09-03 18:02:19 +02:00
|
|
|
.RS 4
|
2015-02-08 13:43:29 +01:00
|
|
|
Defines for how many weeks back weekly backups should be
|
|
|
|
preserved. Every backup created at \fIpreserve_day_of_week\fR (or
|
|
|
|
the next backup in this week if none was made on the exact day) is
|
2015-05-20 13:50:18 +02:00
|
|
|
considered as a weekly backup. Defaults to \[lq]0\[rq].
|
2015-09-03 18:02:19 +02:00
|
|
|
.RE
|
|
|
|
.PP
|
2015-02-08 13:43:29 +01:00
|
|
|
\fBtarget_preserve_monthly\fR all|<number>
|
2015-09-03 18:02:19 +02:00
|
|
|
.RS 4
|
2015-02-08 13:43:29 +01:00
|
|
|
Defines for how many months back monthly backups should be
|
|
|
|
preserved. Every last weekly backup in a month is considered a
|
2015-05-20 13:50:18 +02:00
|
|
|
monthly backup. Defaults to \[lq]all\[rq].
|
2015-09-03 18:02:19 +02:00
|
|
|
.RE
|
|
|
|
.PP
|
2016-02-29 20:12:55 +01:00
|
|
|
\fBtarget_preserve_yearly\fR all|<number>
|
|
|
|
.RS 4
|
|
|
|
Defines for how many years back yearly backups should be
|
|
|
|
preserved. Every last monthly backup in a year is considered a yearly
|
|
|
|
backup. Defaults to \[lq]0\[rq].
|
|
|
|
.RE
|
|
|
|
.PP
|
2016-02-29 23:19:55 +01:00
|
|
|
\fBsnapshot_preserve\fR
|
2015-02-08 13:43:29 +01:00
|
|
|
.PD 0
|
2015-09-03 18:02:19 +02:00
|
|
|
.PP
|
2016-02-29 23:19:55 +01:00
|
|
|
\fBsnapshot_preserve_daily\fR
|
|
|
|
.PP
|
2015-02-08 13:43:29 +01:00
|
|
|
\fBsnapshot_preserve_weekly\fR
|
2015-09-03 18:02:19 +02:00
|
|
|
.PP
|
2015-02-08 13:43:29 +01:00
|
|
|
\fBsnapshot_preserve_monthly\fR
|
2016-02-29 20:12:55 +01:00
|
|
|
.PP
|
|
|
|
\fBsnapshot_preserve_yearly\fR
|
2015-09-03 18:02:19 +02:00
|
|
|
.RS 4
|
2015-05-25 17:13:36 +02:00
|
|
|
Defines retention policy for the snapshots, with same semantics as the
|
2015-02-08 13:43:29 +01:00
|
|
|
\fItarget_preserve_*\fR options.
|
2015-09-03 18:02:19 +02:00
|
|
|
.RE
|
2015-02-08 13:43:29 +01:00
|
|
|
.PD
|
2015-09-03 18:02:19 +02:00
|
|
|
.PP
|
2015-02-08 13:43:29 +01:00
|
|
|
\fBpreserve_day_of_week\fR monday|tuesday|...|sunday
|
2015-09-03 18:02:19 +02:00
|
|
|
.RS 4
|
2015-02-08 13:43:29 +01:00
|
|
|
Defines on what day a backup/snapshot is considered as a weekly
|
2015-05-20 13:50:18 +02:00
|
|
|
backup. Defaults to \[lq]sunday\[rq].
|
2015-09-03 18:02:19 +02:00
|
|
|
.RE
|
|
|
|
.PP
|
2015-09-20 17:47:46 +02:00
|
|
|
\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
|
2015-02-08 13:43:29 +01:00
|
|
|
\fBssh_identity\fR <file>
|
2015-09-03 18:02:19 +02:00
|
|
|
.RS 4
|
2015-02-08 13:43:29 +01:00
|
|
|
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.
|
2015-09-03 18:02:19 +02:00
|
|
|
.RE
|
|
|
|
.PP
|
2015-02-08 13:43:29 +01:00
|
|
|
\fBssh_user\fR <username>
|
2015-09-03 18:02:19 +02:00
|
|
|
.RS 4
|
2015-05-20 13:50:18 +02:00
|
|
|
Remote username for ssh. Defaults to \[lq]root\[rq]. Note that you will
|
2015-02-08 13:43:29 +01:00
|
|
|
have to make sure that the remote user is able to run /sbin/btrfs
|
|
|
|
(which needs root privileges).
|
2015-09-03 18:02:19 +02:00
|
|
|
.RE
|
|
|
|
.PP
|
2015-08-13 21:39:07 +02:00
|
|
|
\fBssh_port\fR <port>
|
2015-09-03 18:02:19 +02:00
|
|
|
.RS 4
|
2015-08-13 21:39:07 +02:00
|
|
|
Port to connect to on the remote host. Defaults to \[lq]default\[rq]
|
|
|
|
(the port specified in \fIssh_config\fR, which defaults to 22).
|
2015-09-03 18:02:19 +02:00
|
|
|
.RE
|
|
|
|
.PP
|
2015-09-01 00:43:14 +02:00
|
|
|
\fBssh_compression\fR yes|no
|
2015-09-03 18:02:19 +02:00
|
|
|
.RS 4
|
2015-09-01 00:43:14 +02:00
|
|
|
Enables or disables the compression of ssh connections. Defaults to
|
|
|
|
\[lq]no\[rq].
|
2015-09-03 18:02:19 +02:00
|
|
|
.RE
|
|
|
|
.PP
|
2015-09-20 18:32:19 +02:00
|
|
|
\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
|
2016-03-23 11:58:23 +01:00
|
|
|
\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].
|
|
|
|
.RE
|
|
|
|
.PP
|
2015-02-08 13:43:29 +01:00
|
|
|
\fBbtrfs_commit_delete\fR after|each|no
|
2015-09-03 18:02:19 +02:00
|
|
|
.RS 4
|
2015-02-08 13:43:29 +01:00
|
|
|
If set, make sure the deletion of snapshot and backup subvolumes are
|
2015-05-20 13:50:18 +02:00
|
|
|
committed to disk when btrbk terminates. Defaults to \[lq]no\[rq].
|
2015-09-03 18:02:19 +02:00
|
|
|
.RE
|
|
|
|
.PP
|
2015-03-24 13:13:00 +01:00
|
|
|
\fBbtrfs_progs_compat\fR yes|no \fI*experimental*\fR
|
2015-09-03 18:02:19 +02:00
|
|
|
.RS 4
|
2015-03-24 13:13:00 +01:00
|
|
|
Enable compatibility mode for btrfs-progs < 3.17 (\fIbtrfs
|
|
|
|
--version\fR). This option can be set either globally or within a
|
|
|
|
\fItarget\fR section. If enabled, the latest common snapshots are
|
|
|
|
determined by subvolume names instead of \fIreceived_uuid\fR, which
|
|
|
|
can lead to false guesses if the snapshot or target subvolumes are
|
|
|
|
manipulated by hand (moved, deleted).
|
2015-09-03 18:02:19 +02:00
|
|
|
.RE
|
2015-02-08 13:43:29 +01:00
|
|
|
.PP
|
|
|
|
Lines that contain a hash character (#) in the first column are
|
|
|
|
treated as comments.
|
2015-10-23 19:26:35 +02:00
|
|
|
.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). 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 raw
|
|
|
|
backups (btrbk does not delete any raw files)!
|
|
|
|
.PP
|
|
|
|
Additional options for raw targets:
|
|
|
|
.PP
|
|
|
|
.RS 4
|
|
|
|
raw_target_compress gzip|bzip2|xz|no
|
|
|
|
.PD 0
|
|
|
|
.PP
|
2016-01-14 18:02:53 +01:00
|
|
|
raw_target_compress_level default|<number>
|
|
|
|
.PP
|
|
|
|
raw_target_compress_threads default|<number>
|
|
|
|
.PP
|
2015-10-23 19:26:35 +02:00
|
|
|
raw_target_encrypt gpg|no
|
|
|
|
.PP
|
|
|
|
gpg_keyring <file>
|
|
|
|
.PP
|
|
|
|
gpg_recipient <name>
|
|
|
|
.RE
|
|
|
|
.PD
|
|
|
|
.PP
|
|
|
|
Target file name syntax:
|
|
|
|
.PP
|
|
|
|
.RS 4
|
|
|
|
<snapshot-name>--<received_uuid>[@<parent_uuid>].btrfs[.gz|.bz2|.xz][.gpg]
|
|
|
|
.RE
|
|
|
|
.PP
|
|
|
|
The <parent_uuid> is only set on \fIincremental\fR backups, and points
|
|
|
|
to the <received_uuid> of the previous backup in a incremental backup
|
2015-11-02 20:09:19 +01:00
|
|
|
chain.
|
|
|
|
.PP
|
|
|
|
For \fIincremental\fR backups ("incremental yes"), please note that:
|
|
|
|
.IP 1. 4
|
2015-10-23 19:26:35 +02:00
|
|
|
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.
|
2015-11-02 20:09:19 +01:00
|
|
|
.IP 2. 4
|
2015-10-23 19:26:35 +02:00
|
|
|
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
|
2015-02-08 13:43:29 +01:00
|
|
|
.SH AVAILABILITY
|
2016-03-16 17:45:32 +01:00
|
|
|
Please refer to the btrbk project page \fBhttp://digint.ch/btrbk/\fR
|
|
|
|
for further details.
|
2015-02-08 13:43:29 +01:00
|
|
|
.SH SEE ALSO
|
|
|
|
.BR btrbk (1)
|
|
|
|
.SH AUTHOR
|
|
|
|
Axel Burri <axel@tty0.ch>
|