table of contents
- stretch 0.24.0-1
- testing 0.27.1-1
- unstable 0.27.1-1
- experimental 0.28.2-1
btrbk.conf(5) | btrbk.conf(5) |
NAME¶
btrbk.conf - btrbk configuration fileSYNOPSIS¶
/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.
SECTIONS¶
volume <volume-directory>|<url>subvolume <subvolume-name>
target <type> <target-directory>|<url>
For the volume and target sections, you can specify a ssh-url instead of a local directory. The syntax for <url> is:
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>transaction_syslog <facility>
timestamp_format short|long|long-iso
- short
- YYYYMMDD[_N] (e.g. "20150825", "20150825_1")
- long
- YYYYMMDD<T>hhmm[_N] (e.g. "20150825T1531")
- long-iso
- YYYYMMDD<T>hhmmss±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 (caveats) below.
snapshot_dir <directory>
snapshot_name <basename>
snapshot_create always|onchange|ondemand|no
incremental yes|no|strict
snapshot_preserve no|<retention_policy>
snapshot_preserve_min all|latest|<number>{h,d,w,m,y}
target_preserve no|<retention_policy>
target_preserve_min all|latest|no|<number>{h,d,w,m,y}
archive_preserve no|<retention_policy>
archive_preserve_min all|latest|no|<number>{h,d,w,m,y}
preserve_day_of_week monday|tuesday|...|sunday
group <group-name>[,<group-name>]...
ssh_identity <file>
ssh_user <username>
ssh_port <port>
ssh_compression yes|no
ssh_cipher_spec <cipher_spec>
stream_compress <compress_command>|no
stream_compress_level default|<number>
stream_compress_threads default|<number>
rate_limit <rate>|no
lockfile <file>
btrfs_commit_delete after|each|no
backend btrfs-progs|btrfs-progs-btrbk *experimental*
Lines that contain a hash character (#) in the first column are treated as comments.
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:
With the following semantics:
hourly
daily
weekly
monthly
yearly
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-receiveraw *experimental*
Note that the target preserve mechanism is currently disabled for raw backups (btrbk does not delete any raw files)!
Additional options for raw targets:
raw_target_compress_level default|<number>
raw_target_compress_threads default|<number>
raw_target_encrypt gpg|no
raw_target_block_size <number> (defaults to 128K)
gpg_keyring <file>
gpg_recipient <name>
Raw targets get an extra file suffix in the format:
<received_uuid>[@<parent_uuid>].btrfs[.gz|.bz2|.xz][.gpg]
The <parent_uuid> is only set on incremental backups, and points to the <received_uuid> of the previous backup in a incremental backup chain.
For incremental backups ("incremental yes"), please note that:
- 1.
- 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.
- 2.
- 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>2016-11-16 | btrbk v0.24.0 |