.TH "btrbk.conf" "5" "2016-11-16" "btrbk v0.24.0" "" .\" 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 | .RS 4 Directory of a btrfs volume containing the source subvolume(s) to be backed up. \fI\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 .RS 4 Subvolume to be backed up, relative to the \fI\fR specified in the \fIvolume\fR section. Multiple \fIsubvolume\fR sections are allowed within \fIvolume\fR sections. Accepts wildcard character "*". .RE .PP \fBtarget\fR | .RS 4 Target type and directory where the backup subvolumes are to be created. See the TARGET TYPES section for supported \fI\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\fR is: .PP .RS 4 .nf ssh://host.xz/path/to/volume .fi .RE .PP If a \fI\fR is specified, all access to the filesystem is performed via ssh, using the "ssh_" options described below. For convenience, "ssh:///" can also be specified as ":". .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 .RS 4 If set, all transactions (snapshot create, subvolume send\-receive, subvolume delete) as well as abort messages are logged to , in a space-separated table format: "localtime type status duration target_url source_url parent_url message". .RE .PP \fBtransaction_syslog\fR .RS 4 If set, all transactions (as described in \fItransaction_log\fR above) are logged to syslog. The facility parameter accepts a lowercase syslog facility name, like \[lq]daemon\[rq] or \[lq]local7\[rq]. The program name used in the messages is "btrbk". .RE .PP \fBtimestamp_format\fR short|long|long\-iso .RS 4 Timestamp format used as postfix for new snapshot subvolume names. Defaults to \[lq]short\[rq]. .PP .IP \fBshort\fR 10 YYYYMMDD[_N] (e.g. "20150825", "20150825_1") .IP \fBlong\fR 10 YYYYMMDDhhmm[_N] (e.g. "20150825T1531") .IP \fBlong\-iso\fR 10 YYYYMMDDhhmmss\[t+-]hhmm[_N] (e.g. "20150825T153123+0200") .PP Note that a postfix "_N" is appended to the timestamp if a snapshot or backup already exists with the timestamp of current date/time. .PP Use \[lq]long\-iso\[rq] 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). .PP Note that using \[lq]long\-iso\[rq] has implications on the scheduling, see RETENTION POLICY (caveats) below. .RE .PP \fBsnapshot_dir\fR .RS 4 Directory in which the btrfs snapshots are created, relative to \fI\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 .RS 4 Base name of the created snapshot (and backup). This option is only valid in the \fIsubvolume\fR section. Defaults to \fI\fR. .RE .PP \fBsnapshot_create\fR always|onchange|ondemand|no .RS 4 If set to \[lq]always\[rq], snapshots are always created. 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]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]no\[rq], the snapshots are never created (useful 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 \fBsnapshot_preserve\fR no| .RS 4 Set retention policy for snapshots (see RETENTION POLICY below). If set to \[lq]no\[rq], preserve snapshots according to \fIsnapshot_preserve_min\fR only. Defaults to \[lq]no\[rq]. .RE .PP \fBsnapshot_preserve_min\fR all|latest|{h,d,w,m,y} .RS 4 Preserve all snapshots for a minimum amount of hours (h), days (d), weeks (w), months (m) or years (y), regardless of how many there are. If set to \[lq]all\[rq], preserve all snapshots forever. If set to \[lq]latest\[rq], preserve latest snapshot. Defaults to \[lq]all\[rq]. .RE .PP \fBtarget_preserve\fR no| .RS 4 Set retention policy for backups (see RETENTION POLICY below). If set to \[lq]no\[rq], preserve backups according to \fItarget_preserve_min\fR only. Defaults to \[lq]no\[rq]. .RE .PP \fBtarget_preserve_min\fR all|latest|no|{h,d,w,m,y} .RS 4 Preserve all backups for a minimum amount of hours (h), days (d), weeks (w), months (m) or years (y), regardless of how many there are. If set to \[lq]all\[rq], preserve all backups forever. If set to \[lq]latest\[rq], always preserve the latest backup (useful in conjunction with "target_preserve no", if you want to keep the latest backup only). If set to \[lq]no\[rq], only the backups following the \fItarget_preserve\fR policy are created. Defaults to \[lq]all\[rq]. .RE .PP \fBarchive_preserve\fR no| .PD 0 .PP \fBarchive_preserve_min\fR all|latest|no|{h,d,w,m,y} .PD .RS 4 Set retention policy for archives ("btrbk archive" command), with same semantics as \fItarget_preserve\fR, \fItarget_preserve_min\fR. .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 [,]... .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 .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 .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 .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 .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 \fBstream_compress\fR |no .RS 4 Compress the btrfs send stream before transferring it from/to remote locations. Defaults to \[lq]no\[rq]. If enabled, make sure that is available on the source and target hosts. Supported \fI\fR: gzip, pigz, bzip2, pbzip2, xz, lzo, lz4. .RE .PP \fBstream_compress_level\fR default| .RS 4 Compression level for the specified . Refer to the related man-page for details (usually [1..9], where 1 means fastest compression). Defaults to \[lq]default\[rq] (the default compression level of ). .RE .PP \fBstream_compress_threads\fR default| .RS 4 Number of threads to use for . Only supported for "pigz", "pbzip2" and recent versions of "xz". .RE .PP \fBrate_limit\fR |no .RS 4 Limit the transfer to a maximum of \fI\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 \fBlockfile\fR .RS 4 Create lockfile on startup; checks lockfile before running any btrfs commands (using perl "flock"), and exits if the lock is held by another btrbk instance. Ignored on dryrun (\fI\-n\fR, \fI\-\-dry\-run\fR). See also \fI\-\-lockfile\fR command-line option. .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 \fBbackend\fR btrfs-progs|btrfs-progs-btrbk \fI*experimental*\fR .RS 4 Btrfs filesystem utilities to be used for subvolume operations. If set to \[lq]btrfs-progs-btrbk\[rq], specific btrfs(8) commands groups needs to be separated by a dash instead of a whitespace (e.g. "btrfs-subvolume-show" instead of "btrfs subvolume show"). Useful for setting suid or file capabilities (setcap) on specific btrfs commands, as implemented in . For convenience, it is also possible to set \fIbackend_local\fR or \fIbackend_remote\fR, which will override the \fIbackend\fR option for local or remote sources/targets. Defaults to \[lq]btrfs-progs\[rq]. .RE .PP Lines that contain a hash character (#) in the first column are treated as comments. .SH RETENTION POLICY btrbk uses separate retention policies for snapshots and backups, which are defined by the \fIsnapshot_preserve_min\fR, \fIsnapshot_preserve\fR, \fItarget_preserve_min\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\fR is: .PP .RS 4 [h] [d] [w] [m] [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 scheduling, make sure to also set \fItimestamp_format\fR to \[lq]long\[rq] or \[lq]long\-iso\[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"). .PP 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. .PP Caveats: .IP \[bu] 2 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". .IP \[bu] 2 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)). .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\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| .PP raw_target_compress_threads default| .PP raw_target_encrypt gpg|no .PP raw_target_block_size (defaults to 128K) .PP gpg_keyring .PP gpg_recipient .RE .PD .PP Raw targets get an extra file suffix in the format: .RS 4 .PP [@].btrfs[.gz|.bz2|.xz][.gpg] .RE .PP The is only set on \fIincremental\fR backups, and points to the 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