btrbk/doc/btrbk.conf.5

.TH "btrbk.conf" "5" "2016-04-12" "btrbk v0.23.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.
.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.
.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 (mulitplied) 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
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>
.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
\fBtimestamp_format\fR  short|long
.RS 4
Timestamp format used as postfix for new snapshot subvolume
names. 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")
.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
.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|ondemand|onchange|no
.RS 4
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].
.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
\fBresume_missing\fR  yes|no
.RS 4
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].
.RE
.PP
\fBsnapshot_preserve\fR  <retention_policy>
.RS 4
Set retention policy for snapshots (see RETENTION POLICY below).
.RE
.PP
\fBsnapshot_preserve_all\fR  forever|no|<number>{h,d,w,m,y}
.RS 4
Preserve all snapshots for the given amount of hours (h), days (d),
weeks (w), months (m) or years (y), regardless of how many there
are. Defaults to \[lq]12h\[rq].
.RE
.PP
\fBtarget_preserve\fR  <retention_policy>
.RS 4
Set retention policy for backups (see RETENTION POLICY below).
.RE
.PP
\fBtarget_preserve_all\fR  forever|no|<number>{h,d,w,m,y}
.RS 4
Preserve all backups for the given amount of hours (h), days (d),
weeks (w), months (m) or years (y), regardless of how many there
are. Defaults to \[lq]no\[rq].
.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
\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
\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
\fBbtrfs_progs_compat\fR  yes|no \fI*experimental*\fR
.RS 4
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).
.RE
.PP
Lines that contain a hash character (#) in the first column are
treated as comments.
.SH RETENTION POLICY
btrbk uses separate retention policy for snapshots and backups, which
are defined by the \fIsnapshot_preserve_all\fR,
\fIsnapshot_preserve\fR, \fItarget_preserve_all\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 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").
.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 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
raw_target_compress_level  default|<number>
.PP
raw_target_compress_threads  default|<number>
.PP
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
chain.
.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>