mirror of https://github.com/digint/btrbk
137 lines
5.2 KiB
Groff
137 lines
5.2 KiB
Groff
.TH "btrbk.conf" "5" "2015-04-30" "btrbk v0.17.0" ""
|
|
.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 other options can be
|
|
defined for each backup.
|
|
.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
|
|
backuped. \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 backuped, 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 \(lqsend\-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). Defaults to
|
|
\fI<subvolume-name>\fR. This option is only valid in the \fItarget\fR
|
|
section.
|
|
.TP
|
|
\fBsnapshot_create_always\fR yes|no
|
|
If set, the snapshots are always created, even if the backup subvolume
|
|
cannot be created (e.g. if the target subvolume cannot be
|
|
reached). Use in conjunction with the \fIresume_missing\fR option to
|
|
make sure that the backups are created as soon as the target subvolume
|
|
is reachable again. Useful for laptop filesystems in order to make
|
|
sure the snapshots are created even if you are on the road. Defaults
|
|
to \(lqno\(rq.
|
|
.TP
|
|
\fBincremental\fR yes|no|strict
|
|
Perform incremental backups. Defaults to \(lqyes\(rq. If set to
|
|
\(lqstrict\(rq, non-incremental (initial) backups are never created.
|
|
.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 \(lqyes\(rq.
|
|
.TP
|
|
\fBtarget_preserve_daily\fR all|<number>
|
|
How many days of backups should be preserved. Defaults to \(lqall\(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 \(lq0\(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 \(lqall\(rq.
|
|
.TP
|
|
\fBsnapshot_preserve_daily\fR
|
|
.PD 0
|
|
.TP
|
|
\fBsnapshot_preserve_weekly\fR
|
|
.TP
|
|
\fBsnapshot_preserve_monthly\fR
|
|
Define 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 \(lqsunday\(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 \(lqroot\(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 \(lqno\(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>
|