.TH "btrbk.conf" "5" "2015-06-21" "btrbk v0.19.3" ""
.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
The sections are:
.TP
\fBvolume\fR  <volume-directory>|<url>
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.
.TP
\fBsubvolume\fR  <subvolume-name>
Subvolume to be backed up, relative to the \fI<volume-directory>\fR
specified in the \fIvolume\fR section.
.TP
\fBtarget\fR  <type> <volume-directory>|<url>
Target type and directory where the backup subvolumes are to be
created. \fI<volume-directory>\fR must be an absolute path and point
to a btrfs volume (or subvolume). Currently the the only valid
\fI<type>\fR is \[lq]send\-receive\[rq].
.PP
For the \fIvolume\fR and \fItarget\fR sections, you can also specify a
ssh-url instead of a local directory. The syntax for \fI<url>\fR is:
.IP
ssh://host.xz/path/to/volume
.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.
.PP
The configuration options are:
.TP
\fBsnapshot_dir\fR  <directory>
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.
.TP
\fBsnapshot_name\fR <basename> Base name of the created snapshot (and
backup). This option is only valid in the \fItarget\fR
section. Defaults to \fI<subvolume-name>\fR.
.TP
\fBsnapshot_create\fR  always|ondemand|onchange|no
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].
.TP
\fBincremental\fR  yes|no|strict
If set, incremental backups are created. If set to \[lq]strict\[rq],
non-incremental (initial) backups are never created. Defaults to
\[lq]yes\[rq].
.TP
\fBresume_missing\fR  yes|no
If set, the backups in the target directory are compared to the source
snapshots, and missing backups are created if needed (complying to the
target preserve matrix). Defaults to \[lq]yes\[rq].
.TP
\fBtarget_preserve_daily\fR  all|<number>
How many days of backups should be preserved. Defaults to \[lq]all\[rq].
.TP
\fBtarget_preserve_weekly\fR  all|<number>
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
considered as a weekly backup. Defaults to \[lq]0\[rq].
.TP
\fBtarget_preserve_monthly\fR  all|<number>
Defines for how many months back monthly backups should be
preserved. Every last weekly backup in a month is considered a
monthly backup. Defaults to \[lq]all\[rq].
.TP
\fBsnapshot_preserve_daily\fR
.PD 0
.TP
\fBsnapshot_preserve_weekly\fR
.TP
\fBsnapshot_preserve_monthly\fR
Defines retention policy for the snapshots, with same semantics as the
\fItarget_preserve_*\fR options.
.PD
.TP
\fBpreserve_day_of_week\fR  monday|tuesday|...|sunday
Defines on what day a backup/snapshot is considered as a weekly
backup. Defaults to \[lq]sunday\[rq].
.TP
\fBssh_identity\fR  <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.
.TP
\fBssh_user\fR  <username>
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).
.TP
\fBbtrfs_commit_delete\fR  after|each|no
If set, make sure the deletion of snapshot and backup subvolumes are
committed to disk when btrbk terminates. Defaults to \[lq]no\[rq].
.TP
\fBbtrfs_progs_compat\fR  yes|no \fI*experimental*\fR
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).
.PP
Lines that contain a hash character (#) in the first column are
treated as comments.
.SH AVAILABILITY
Please refer to the btrbk project page
\fBhttp://www.digint.ch/btrbk/\fR for further
details.
.SH SEE ALSO
.BR btrbk (1)
.SH AUTHOR
Axel Burri <axel@tty0.ch>