1BTRBK.CONF(5) Btrbk Manual BTRBK.CONF(5)
2
6 btrbk.conf - btrbk configuration file
7
9 /etc/btrbk.conf
10 /etc/btrbk/btrbk.conf
11
13 The btrbk configuration file specifies which btrfs subvolumes on the
14 filesystem are to be processed, what target subvolumes should be used
15 to create the backups, and where the snapshots should be generated. The
16 retention policy, as well as most other options can be defined either
17 globally or within a section.
18 The options specified always apply to the last section encountered,
20 superseding the values set in upper-level sections. This means that
21 global options must be set before any sections are defined.
22 Blank lines are ignored. A hash character (#) starts a comment
24 extending until end of line.
25
27 volume <volume-directory>|<url>
28 Directory of a btrfs volume containing the source subvolume(s) to
29 be backed up. <volume-directory> must be an absolute path and
30 point to a btrfs volume (or subvolume). Usually the mount point of
31 a btrfs filesystem mounted with the subvolid=5 option.
32 subvolume <subvolume-name>
34 Subvolume to be backed up, relative to the <volume-directory>
35 specified in the volume section. Multiple subvolume sections are
36 allowed within volume sections. Accepts wildcard character "*".
37 If set to ".", the subvolume at <volume-directory> is used as
39 backup source, and the snapshots will be created within the source
40 subvolume itself (see snapshot_dir option below), which is not
41 recommended. Note that if this subvolume is btrfs root (id=5), it
42 needs to have a valid UUID, which is not the case for file systems
43 created with btrfs-progs < 4.16.
44 target <type> <target-directory>|<url>
46 Target type and directory where the backup subvolumes are to be
47 created. See the TARGET TYPES section for supported <type>.
48 Multiple target sections are allowed within subvolume sections. A
49 target section defined in the global context or in a volume section
50 is propagated (multiplied) to all underlying subvolume sections,
51 unless a target with the same declaration already exists (hint: run
52 "btrbk config print" to see the resulting configuration).
53 <target-directory>
55 Run actions locally.
56 Note that whitespace or unicode characters are NOT allowed for file
58 names. Allowed characters are:
59 [0-9] [a-z] [A-Z] and "._+-@"
61 This is for sanity/safety/security reasons, we apologize for the
63 inconvenience.
64 <url>
66 Run actions remotely via ssh. Either:
67 ssh://<hostname>/<directory>
69 <hostname>:<directory>
70 If a <url> is specified, btrbk actions for <hostname> (shell
72 commands) are executed via ssh, using the "ssh_" options described
73 below.
74 Note that btrbk keeps mountpoint and btrfs-tree information per
76 hostname: specifying different ssh_port for the same host, e.g. for
77 several virtual machines listening on same address, will NOT work.
78 If you need this, define alias host names for each vm.
79
81 The options described here can be specified in global context as well
82 as volume, subvolume and target sections, unless stated otherwise.
83 Basic Options
85 timestamp_format short|long|long-iso
86 Timestamp format used as postfix for new snapshot subvolume names.
87 Defaults to “short”.
88 short
90 YYYYMMDD[_N] (e.g. "20150825", "20150825_1")
91 long
93 YYYYMMDD<T>hhmm[_N] (e.g. "20150825T1531")
94 long-iso
96 YYYYMMDD<T>hhmmss±hhmm[_N] (e.g. "20150825T153123+0200")
97 Note that a postfix "_N" is appended to the timestamp if a snapshot
99 or backup already exists with the timestamp of current date/time.
100 Use “long-iso” if you want to make sure that btrbk never creates
102 ambiguous time stamps (which can happen if multiple snapshots are
103 created during a daylight saving time clock change).
104 Note that using “long-iso” has implications on the scheduling, see
106 RETENTION POLICY (caveats) below.
107 snapshot_dir <directory>
109 Directory in which the btrfs snapshots are created, relative to
110 <volume-directory> of the volume section. Note that btrbk does not
111 autmatically create this directory, and the snapshot creation will
112 fail if it is not present.
113 snapshot_name <basename>
115 Base name of the created snapshot (and backup). This option is only
116 valid in the subvolume section. Defaults to <subvolume-name>.
117 snapshot_create always|onchange|ondemand|no
119 If set to “always”, snapshots are always created. If set to
120 “onchange”, snapshots are only created if the source subvolume has
121 changed since the last snapshot (more precisely: if the btrfs
122 generation has been increased since the last snapshot). If set to
123 “ondemand”, snapshots are only created if at least one target
124 subvolume is reachable (useful if you are tight on disk space and
125 you only need btrbk for backups to an external disk which is not
126 always connected). If set to “no”, the snapshots are never created
127 (useful if another instance of btrbk is taking care of snapshot
128 creation). Defaults to “always”.
129 incremental yes|no|strict
131 If set, incremental backups are created. If set to “strict”,
132 non-incremental (initial) backups are never created. Defaults to
133 “yes”.
134 Grouping Options
136 group <group-name>[,<group-name>]...
137 Add the current section (volume, subvolume or target) to a
138 user-defined group, which can be used as filter for most btrbk
139 commands. This option can be set multiple times within the same
140 context.
141 Retention Policy Options
143 preserve_day_of_week monday|tuesday|...|sunday
144 Defines on what day a snapshot/backup is considered to be a
145 "weekly" backup. Weekly, monthly and yearly backups are preserved
146 on this day of week (see RETENTION POLICY below). Defaults to
147 “sunday”.
148 preserve_hour_of_day [0..23]
150 Defines after what time (in full hours since midnight) a
151 snapshot/backup is considered to be a "daily" backup. Daily,
152 weekly, monthly and yearly backups are preserved on this hour (see
153 RETENTION POLICY below). If you set this option, make sure to also
154 set timestamp_format to “long” or “long-iso” (backups and snapshots
155 having no time information will ignore this option). Defaults to
156 “0”.
157 snapshot_preserve no|<retention_policy>
159 Set retention policy for snapshots (see RETENTION POLICY below). If
160 set to “no”, preserve snapshots according to snapshot_preserve_min
161 only. Defaults to “no”.
162 snapshot_preserve_min all|latest|<number>{h,d,w,m,y}
164 Preserve all snapshots for a minimum amount of hours (h), days (d),
165 weeks (w), months (m) or years (y), regardless of how many there
166 are. If set to “all”, preserve all snapshots forever. If set to
167 “latest”, preserve latest snapshot. Defaults to “all”.
168 target_preserve no|<retention_policy>
170 Set retention policy for backups (see RETENTION POLICY below). If
171 set to “no”, preserve backups according to target_preserve_min
172 only. Defaults to “no”.
173 target_preserve_min all|latest|no|<number>{h,d,w,m,y}
175 Preserve all backups for a minimum amount of hours (h), days (d),
176 weeks (w), months (m) or years (y), regardless of how many there
177 are. If set to “all”, preserve all backups forever. If set to
178 “latest”, always preserve the latest backup (useful in conjunction
179 with "target_preserve no", if you want to keep the latest backup
180 only). If set to “no”, only the backups following the
181 target_preserve policy are created. Defaults to “all”.
182 archive_preserve no|<retention_policy>
184 Set retention policy for archives ("btrbk archive" command), with
185 same semantics as target_preserve.
186 archive_preserve_min all|latest|no|<number>{h,d,w,m,y}
188 Set retention policy for archives ("btrbk archive" command), with
189 same semantics as target_preserve_min.
190 archive_exclude <pattern> *experimental*
192 Exclude subvolumes matching <pattern> from archiving. The pattern
193 accepts wildcard character "*", and is matched against the end of
194 the pathname.
195 SSH Options
197 ssh_identity <file>
198 Absolute path to a ssh identity file (private key). Note that if
199 the private key is password protected, btrbk will prompt for user
200 input, which is usually not desired.
201 ssh_user <username>
203 Remote username for ssh. Defaults to “root”. Make sure the remote
204 user is able to run "btrfs" with root privileges (see option
205 backend for details).
206 ssh_port <port>|default
208 Port to connect to on the remote host. Defaults to “default” (the
209 port specified in ssh_config, which defaults to 22).
210 Note that btrbk keeps mountpoint and btrfs-tree information per
212 hostname: specifying different ssh_port for the same host, e.g. for
213 several virtual machines listening on same address, will NOT work.
214 If you need this, define alias host names for each vm.
215 ssh_compression yes|no
217 Enables or disables the compression of ssh connections. Defaults to
218 “no”.
219 ssh_cipher_spec <cipher_spec>
221 Selects the cipher specification for encrypting the session
222 (comma-separated list of ciphers in order of preference). See the
223 "-c cipher_spec" option in ssh(1) for more information. Defaults to
224 “default” (the ciphers specified in ssh_config).
225 Data Stream Options
227 stream_compress <compress_command>|no
228 Compress the btrfs send stream before transferring it from/to
229 remote locations. Defaults to “no”. If enabled, make sure that
230 <compress_command> is available on the source and target hosts.
231 Supported <compress_command>: gzip, pigz, bzip2, pbzip2, xz, lzo,
232 lz4.
233 stream_compress_level default|<number>
235 Compression level for the specified <compress_command>. Refer to
236 the related man-page for details (usually [1..9], where 1 means
237 fastest compression). Defaults to “default” (the default
238 compression level of <compress_command>).
239 stream_compress_threads default|<number>
241 Number of threads to use for <compress_command>. Only supported for
242 "pigz", "pbzip2" and recent versions of "xz".
243 stream_buffer <size>|no
245 Add a buffer to the btrfs send stream (in front of "btrfs
246 receive"), with a maximum size of <size>. This can give a speed
247 improvement (measured up to 20%) on both local or remote
248 operations, but also increases system load. A suffix of "k", "m",
249 "g", or "%" can be added to <size> to denote kilobytes (*1024),
250 megabytes, gigabytes, or a percentage of total physical memory.
251 Defaults to “no”. If enabled, make sure that the "mbuffer" command
252 is available on the target host.
253 rate_limit <rate>|no
255 Limit the transfer to a maximum of <rate> bytes per second. A
256 suffix of "k", "m", "g", or "t" can be added to denote kilobytes
257 (*1024), megabytes, and so on. Defaults to “no”. If enabled for
258 remote sources, make sure that the "pv" command is available on the
259 source host.
260 System Options
262 transaction_log <file>|no
263 If set, all transactions (snapshot create, subvolume send-receive,
264 subvolume delete) as well as abort messages are logged to <file>,
265 in a space-separated table format: "localtime type status
266 target_url source_url parent_url message".
267 transaction_syslog <facility>|no
269 If set, all transactions (as described in transaction_log above)
270 are logged to syslog. The program name used in the messages is
271 "btrbk". Accepted parameters for <facility>: user, mail, daemon,
272 auth, lpr, news, cron, authpriv, local0..local7.
273 lockfile <file>|no
275 Create lockfile <file> on startup; checks lockfile before running
276 any btrfs commands (using perl "flock"), and exits if the lock is
277 held by another btrbk instance. Ignored on dryrun (-n, --dry-run).
278 See also --lockfile command-line option.
279 backend btrfs-progs|btrfs-progs-btrbk|btrfs-progs-sudo
281 Backend filesystem utilities to be used for btrfs specific
282 operations. Defaults to “btrfs-progs”.
283 btrfs-progs
285 Default backend, btrfs commands are called as specified in
286 btrfs(8) (e.g. "btrfs subvolume show").
287 btrfs-progs-btrbk
289 btrfs commands are separated by a dash instead of a whitespace
290 (e.g. "btrfs-subvolume-show" instead of "btrfs subvolume
291 show"). Useful for setting suid or file capabilities (setcap)
292 on specific btrfs commands, as implemented in
293 https://github.com/digint/btrfs-progs-btrbk.
294 btrfs-progs-sudo
296 btrfs commands are prefixed with "sudo -n" (e.g. "sudo -n btrfs
297 subvolume show" instead of "btrfs subvolume show"). Make sure
298 to have appropriate (root) permissions for "btrfs" command
299 groups in /etc/sudoers.
300 For convenience, it is also possible to set backend_local or
302 backend_remote options, which will override the backend only for
303 local or remote sources/targets (e.g. "backend_remote
304 btrfs-progs-btrbk").
305 Btrfs Specific Options
307 btrfs_commit_delete after|each|no
308 If set, make sure the deletion of snapshot and backup subvolumes
309 are committed to disk when btrbk terminates. Defaults to “no”.
310 snapshot_qgroup_destroy yes|no *experimental*
312 target_qgroup_destroy yes|no *experimental*
314 archive_qgroup_destroy yes|no *experimental*
316 Whenever a subvolume is deleted, also destroy corresponding default
317 qgroup "0/<subvol-id>". Only useful if you have enabled btrfs quota
318 support. See also:
319 https://bugzilla.kernel.org/show_bug.cgi?id=91751
320
322 btrbk uses separate retention policies for snapshots and backups, which
323 are defined by the snapshot_preserve_min, snapshot_preserve,
324 target_preserve_min, target_preserve, preserve_day_of_week and
325 preserve_hour_of_day configuration options.
326 Within this section, any statement about "backups" is always valid for
328 backups as well as snapshots, referring to target_preserve or
329 snapshot_preserve respectively.
330 The format for <retention_policy> is:
332 [<hourly>h] [<daily>d] [<weekly>w] [<monthly>m] [<yearly>y]
334 With the following semantics:
336 hourly
338 Defines how many hours back hourly backups should be preserved. The
339 first backup of an hour is considered an hourly backup. Note that
340 if you use <hourly> scheduling, make sure to also set
341 timestamp_format to “long” or “long-iso”, or the scheduler will
342 interpret the time as "00:00" (midnight).
343 daily
345 Defines how many days back daily backups should be preserved. The
346 first backup of a day (starting at preserve_hour_of_day) is
347 considered a daily backup.
348 weekly
350 Defines how many weeks back weekly backups should be preserved. The
351 first daily backup created at preserve_day_of_week (or the first
352 backup in this week if none was made on the exact day) is
353 considered as a weekly backup.
354 monthly
356 Defines how many months back monthly backups should be preserved.
357 Every first weekly backup in a month is considered a monthly
358 backup.
359 yearly
361 Defines for how many years back yearly backups should be preserved.
362 Every first monthly backup in a year is considered a yearly backup.
363 Use an asterisk for “all” (e.g. "target_preserve 60d *m" states:
365 "preserve daily backups for 60 days back, and all monthly backups").
366 The reference time (which defines the beginning of a day, week, month
368 or year) for all date/time calculations is the local time of the host
369 running btrbk.
370 Hint: Run btrbk with the -S, --print-schedule option to get a
372 comprehensive output of the scheduler results.
373 Caveats:
375 · If you run a setup with several btrbk instances (e.g. one
377 snapshot-only instance per remote client, and a separate fetch-only
378 instance on the backup server), it makes perfectly sense to run
379 btrbk with different local time on the clients, in order to make
380 sure the backups from all the remote hosts are preserved for
381 "midnight", and not at "00:00 UTC" (which would be "14:00" in
382 Honolulu). If you want this behaviour, do NOT use "timestamp_format
383 long-iso".
384 · If "timestamp_format long-iso" is set, running btrbk from different
386 time zones leads to different interpretation of "first in day,
387 week, month, or year". Make sure to run btrbk with the same time
388 zone on every host, e.g. by setting the TZ environment variable
389 (see tzset(3)).
390
392 send-receive
393 Backup to a btrfs filesystem, using "btrfs send/receive". This is
394 the recommended (standard) target type. The <target-directory> must
395 be an absolute path and point to a btrfs volume (or subvolume), or
396 to a directory within a subvolume. See btrfs-send(8),
397 btrfs-receive(8).
398 raw *experimental*
400 Backup to a raw (filesystem independent) file from the output of
401 btrfs-send(8), with optional compression and encryption.
402 Note that the target preserve mechanism is currently disabled for
404 incremental raw backups (btrbk does not delete any incremental raw
405 files)!
406 Raw backups consist of two files: the main data file containing the
408 btrfs send stream, and a sidecar file ".info" containing metadata:
409 <snapshot-name>.<timestamp>[_N].btrfs[.gz|.bz2|.xz][.gpg]
411 <snapshot-name>.<timestamp>[_N].btrfs[.gz|.bz2|.xz][.gpg].info
412 For incremental backups ("incremental yes"), please note that:
414 · As soon as a single incremental backup file is lost or
416 corrupted, all later incremental backups become invalid, as
417 there is no common parent for the subsequent incremental images
418 anymore. This might be a good compromise for a vacation backup
419 plan, but for the long term make sure that a non-incremental
420 backup is triggered from time to time.
421 · There is currently no support for rotation of incremental
423 backups: if incremental is set, a full backup must be triggered
424 manually from time to time in order to be able to delete old
425 backups.
426 Additional options for raw targets:
428 raw_target_compress <compress_command>|no
430 Compression algorithm to use for raw backup target. Supported
431 <compress_command>: gzip, pigz, bzip2, pbzip2, xz, lzo, lz4.
432 raw_target_compress_level default|<number>
434 Compression level for the specified <compress_command>.
435 raw_target_compress_threads default|<number>
437 Number of threads to use for <compress_command>.
438 raw_target_split <size>|no
440 Split the raw backup file into pieces of size <size>.
441 raw_target_block_size <number>
443 Block size to use for writing the raw backup file. Defaults to
444 “128K”.
445 raw_target_encrypt gpg|openssl_enc|no
447 If enabled, encrypt the target raw file using gpg or
448 openssl_enc.
449 Additional options for "raw_target_encrypt gpg":
451 gpg_keyring <file>
453 Keyring to use for gpg, e.g. "/etc/btrbk/gpg/pubring.kbx".
454 gpg_recipient <name>
456 Encrypt for user id <name> (email address).
457 Additional options for "raw_target_encrypt openssl_enc" (very
459 experimental):
460 openssl_ciphername <name>
462 Defaults to “aes-256-cbc”.
463 openssl_iv_size <size-in-bytes>|no
465 Depends on selected cipher.
466 openssl_keyfile <file>|no
468 Point to a key file in hex (absolute path). Example key file
469 creation (256bit key):
470 # dd if=/dev/urandom bs=1 count=32 \
472 | od -x -A n \
473 | tr -d "[:space:]" > /path/to/keyfile
474 kdf_backend <file>|no
476 KDF backend to be executed, e.g.
477 "/usr/share/btrbk/scripts/kdf_pbkdf2.py".
478 kdf_keysize <size-in-bytes>
480 Defaults to “32”.
481 kdf_keygen once|each
483 Defaults to “once”.
484
486 Please refer to the btrbk project page https://digint.ch/btrbk/ for
487 further details.
488
490 btrbk(1)
491
493 Axel Burri <axel@tty0.ch>
494Btrbk 0.27.0 2018-10-16 BTRBK.CONF(5)