1BTRBK(1) Btrbk Manual BTRBK(1)
2
6 btrbk - backup tool for btrfs subvolumes
7
9 btrbk [-h|--help] [--version]
10 [-c|--config <file>] [-n|--dry-run] [--exclude <filter>]
11 [-p|--preserve] [--preserve-snapshots] [--preserve-backups]
12 [-v|--verbose] [-q|--quiet] [-l|--loglevel <level>]
13 [-t|--table] [-L|--long] [-1|--single-column]
14 [--format <output-format>] [--pretty]
15 [-S|--print-schedule] [--progress]
16 [--lockfile <file>]
17 [--override <config_option>=<value>]
18 <command> [[--] <filter>...]
19
21 btrbk is a backup tool for btrfs subvolumes, taking advantage of btrfs
22 specific capabilities to create atomic snapshots and transfer them
23 incrementally to a target btrfs filesystem. It is able to perform
24 backups from one source to multiple destinations.
25 For most operations, btrbk requires root privileges to run correctly.
27 Alternatively, consider using "btrfs-progs-sudo" or "btrfs-progs-btrbk"
28 backends, both of which allows you to run btrbk as a regular user.
29 Refer to configuration option backend in btrbk.conf(5) for more
30 details.
31 Snapshots and Backups
33 Snapshots as well as backup subvolumes are created in form:
34 <snapshot-name>.<timestamp>[_N]
36 Where <snapshot-name> is identical to the source subvolume name, unless
38 the configuration option snapshot_name is set. The <timestamp> is
39 either "YYYYMMDD" or "YYYYMMDDThhmm" (dependent of the timestamp_format
40 configuration option), where "YYYY" is the year, "MM" is the month,
41 "DD" is the day, "hh" is the hour and "mm" is the minute of the
42 creation time (local time of the host running btrbk). If multiple
43 snapshots/backups are created on the same date/time, N will be
44 incremented on each snapshot, starting at 1.
45 If a snapshot or backup does not match the naming scheme above (i.e. if
47 it has been renamed manually), btrbk will leave it untouched.
48 Note that snapshot is a btrfs terminology for a “read-only subvolume”
50 (showing a parent-uuid, see btrfs-subvolume(8)); backup is a btrbk
51 terminology for a “read-only subvolume created with send/receive”
52 (showing a received-uuid).
53
55 -h, --help
56 Prints the synopsis and a list of the commands.
57 --version
59 Prints the btrbk version.
60 -c, --config <file>
62 Read the configuration from <file>.
63 -n, --dry-run
65 Don’t run anything that would alter the filesystem, just show the
66 snapshots and backup subvolumes that would be created/deleted by
67 the run, snapshot, resume, prune, archive and clean commands. Use
68 in conjunction with -l debug to see the btrfs commands that would
69 be executed.
70 --exclude <filter>
72 Exclude configured sections matching <filter>. See FILTER
73 STATEMENTS below.
74 -p, --preserve
76 Preserve all snapshots and backups. Skips deletion of any snapshots
77 and backups, even if specified in the configuration file (shortcut
78 for "--preserve-snapshots --preserve-backups").
79 --preserve-snapshots
81 Preserve all snapshots. Skips deletion of any snapshots, even if
82 specified in the configuration file.
83 --preserve-backups
85 Preserve all backups. Skips deletion of any backups, even if
86 specified in the configuration file.
87 --wipe
89 Ignore configured snapshot retention policy, delete all but latest
90 snapshots instead. All snapshots needed for incremental backup
91 (latest common) are also preserved. Useful if you are getting low
92 on disk space (ENOSPC).
93 -v, --verbose
95 Increase the logging level, see "--loglevel".
96 -q, --quiet
98 Quiet operation. If set, btrbk does not print the summary after
99 executing the run, snapshot, resume, prune, or archive commands.
100 -l, --loglevel <level>
102 Set the level of verbosity for the stderr logging. Accepted levels
103 are: error, warn, info, debug, and trace. Default is info.
104 -t, --table
106 Print output in table format (shortcut for "--format=table").
107 -L, --long
109 Print output in long table format (shortcut for "--format=long").
110 -1, --single-column
112 Print output as single column (not available for all commands).
113 --format table|long|raw|col:[h:]<columns>
115 Print output in specified format. If set to "raw", prints
116 space-separated, quoted key=value pairs (machine readable).
117 If set to "col:", prints only the <columns> specified
119 (comma-separated list). Header lines are ommitted if the "h:"
120 modifier is present. Columns prefixed with "-" are collapsed if
121 empty. Columns postfixed with ":RALIGN" are right-aligned.
122 --pretty
124 Print table output with lowercase, underlined column headings
125 (instead of single-line uppercase headings).
126 -S, --print-schedule
128 Print detailed scheduler information on run, snapshot, resume,
129 prune and archive commands. Use the --format command line option to
130 switch between different output formats.
131 --progress
133 Show progress bar on send-receive operation. Requires "mbuffer"
134 command (version >= 20180505) installed on the host running btrbk.
135 --lockfile <file>
137 Create lockfile <file> on startup; checks lockfile before running
138 any btrfs commands (using perl "flock"), and exits if the lock is
139 held by another btrbk instance. Overrides configuration option
140 "lockfile". Ignored on dryrun (-n, --dry-run).
141 --override <config_option>=<value>
143 Override a configuration option <config_option> with <value>.
144 Globally, for ALL contexts. Use with care!
145
147 Actions
148 The following commands are used to create snapshots and/or backups. All
149 actions can operate in dry-run mode (-n, --dry-run). Use the --format
150 command line option to switch between different output formats.
151 See section RETENTION POLICY in btrbk.conf(5) for information on
153 configuring the retention policy.
154 run [filter...]
156 Perform snapshot and backup operations as specified in the
157 configuration file. If the optional [filter...] arguments are
158 present, snapshots and backups are only performed for the
159 subvolumes/targets matching a filter statement (see FILTER
160 STATEMENTS below).
161 Step 0: Read Data
163 Read information from the source and target btrfs filesystems
164 in order to perform sanity checks and identify parent/child and
165 received-from relationships.
166 Step 1: Create Snapshots
168 If the checks succeed, btrbk creates snapshots for the source
169 subvolumes specified in the configuration file, according to
170 the snapshot_create option.
171 Step 2: Create Backups
173 For each specified target, btrbk creates the backups as
174 follows: After comparing the backups to the source snapshots,
175 btrbk transfers all missing snapshots needed to satisfy the
176 configured target retention policy, incrementally from the
177 latest common parent subvolume found. If no common parent
178 subvolume is found (or if the incremental option is set to
179 “no”), a full (non-incremental) backup is created.
180 Step 3: Delete Backups
182 Unless the -p, --preserve or --preserve-backups option is set,
183 backup subvolumes that are not preserved by their configured
184 retention policy will be deleted. Note that the latest
185 snapshot/backup pair are always preserved, regardless of the
186 retention policy.
187 Step 4: Delete Snapshots
189 Unless the -p, --preserve or --preserve-snapshots option is
190 set, snapshots that are not preserved by their configured
191 retention policy will be deleted. Note that the latest snapshot
192 (the one created in step 1) as well as the latest
193 snapshot/backup pair are always preserved, regardless of the
194 retention policy. If any target is unreachable or has errors,
195 all snapshots are preserved in order not to break the
196 incremental chain.
197 dryrun [filter...]
199 Don’t run any btrfs commands that would alter the filesystem, just
200 show the snapshots and backup subvolumes that would be
201 created/deleted by the run command. Use in conjunction with -l
202 debug to see the btrfs commands that would be executed.
203 snapshot [filter...]
205 Snapshot only: skips backup creation and deletion (steps 2 and 3).
206 Use in conjunction with -p, --preserve (or --preserve-snapshots) if
207 you also want to skip snapshot deletion (step 4).
208 Note that snapshot deletion is skipped if the target is not
210 accessible, as it is still required in order to determine the
211 latest snapshot/backup pair (which is always preserved, regardless
212 of the retention policy).
213 resume [filter...]
215 Resume backups: skips snapshot creation (step 1), transfers and
216 deletes snapshots/backups in order to satisfy their configured
217 retention policy. Use in conjunction with -p, --preserve,
218 --preserve-backups, --preserve-snapshots if you want to skip backup
219 and/or snapshot deletion (steps 3, 4).
220 prune [filter...]
222 Prune snapshots and backups: skips snapshot and backup creation
223 (steps 1, 2), only deletes snapshots and backups in order to
224 satisfy their configured retention policy. Useful for cleaning the
225 disk after changing the retention policy. Use in conjunction with
226 --preserve-backups, --preserve-snapshots if you want to skip backup
227 or snapshot deletion (steps 3, 4).
228 Note that deletion is skipped if source or target is not
230 accessible, as it is still required in order to determine the
231 latest snapshot/backup pair (which is always preserved, regardless
232 of the retention policy).
233 archive <source> <target> [--raw]
235 Recursively copy all subvolumes created by btrbk from <source> to
236 <target> directory, optionally rescheduled using archive_preserve_*
237 configuration options. Also creates directory tree on <target>.
238 Useful for creating extra archive copies (clones) from your backup
239 disks. Note that you can continue using btrbk after swapping your
240 backup disk with the archive disk.
241 If you want to use nested subvolumes on the target filesystem, you
243 need to create them by hand (e.g. by running "btrfs subvolume
244 create <target>/dir"). Check the output of --dry-run if unsure.
245 Note that this feature needs a linux kernel >=4.4 to work
247 correctly!
248 If --raw option is set, creates raw targets (experimental, see
250 btrbk.conf(5), TARGET TYPES).
251 clean [filter...]
253 Delete incomplete (garbled) backups. Incomplete backups can be left
254 behind on network errors or kill signals while a send/receive
255 operation is ongoing, and are identified by the "received_uuid"
256 flag not being set on a target (backup) subvolume.
257 The following table gives a quick overview of the action commands and
259 resulting snapshot creation (S+), backup creation (B+), snapshot
260 deletion (S-), and backup deletion (B-):
261 Command Option S+ B+ S- B-
263 --------------------------------------------
264 run x x x x
265 run --preserve x x
266 run --preserve-snapshots x x x
267 run --preserve-backups x x x
268 snapshot x x
269 snapshot --preserve x
270 resume x x x
271 resume --preserve x
272 resume --preserve-snapshots x x
273 resume --preserve-backups x x
274 prune x x
275 prune --preserve-snapshots x
276 prune --preserve-backups x
277 Informative Commands
279 The following commands are informative only, and will not alter the
280 file system.
281 stats [filter...]
283 Print statistics of snapshot and backup subvolumes. Optionally
284 filtered by [filter...] arguments (see FILTER STATEMENTS below).
285 list <subcommand> [filter...]
287 Print information defined by <subcommand> in a tabular form.
288 Optionally filtered by [filter...] arguments (see FILTER STATEMENTS
289 below).
290 Available subcommands (default “all”):
292 all
294 List all snapshots and backups created by btrbk.
295 snapshots
297 List all snapshots created by btrbk.
298 backups
300 List all backups (and correlated snapshots) created by btrbk.
301 latest
303 List most recent common snapshot/backup pair, or most recent
304 snapshot if no common found.
305 config
307 List configured source/snapshot/target relations.
308 source
310 List configured source/snapshot relations.
311 volume
313 List configured volume sections.
314 target
316 List configured targets.
317 Use the --format command line option to switch between different
319 output formats.
320 usage [filter...]
322 Print filesystem usage information for all source/target volumes,
323 optionally filtered by [filter...] arguments (see FILTER STATEMENTS
324 below). Note that the "free" value is an estimate of the amount of
325 data that can still be written to the file system.
326 origin <subvolume>
328 Print the subvolume origin tree: Shows the parent-child
329 relationships as well as the received-from information. Use the
330 --format command line option to switch between different output
331 formats.
332 diff <from> <to>
334 List the modified files since generation (transid) of subvolume
335 <from> in subvolume <to>. Columns:
336 SIZE file was modified for a total of SIZE bytes
338 COUNT file was modified in COUNT generations
339 FLAGS "+" file accessed at offset 0 (at least once)
340 "c" COMPRESS flag is set (at least once)
341 "i" INLINE flag is set (at least once)
342 extents [diff] <subvolume>... [exclusive <subvolume>...]
344 Print accurate disk space usage and diff based on extent data
345 (FIEMAP ioctl, slow!).
346 Subvolumes following the exclusive keyword are added to a separate
348 set, and additional set-exclusive data is printed at the end of the
349 list. This gives a hint of how much data will be freed if deleting
350 all subvolumes in the set. Example:
351 btrbk extents diff /backup/data.* exclusive /backup/data.2010*
353 The EXCLUSIVE column shows the set-exclusive data of all other
355 listed (!) subvolumes (relative complement of block regions).
356 Provided that all related subvolumes (holding references to
357 extents) are also listed, this amount of disk space would be freed
358 when deleting the subvolume.
359 The DIFF column shows the data added to the previous subvolume
361 (relative complement of block regions).
362 If called with the --related option, btrbk also lists all related
364 subvolumes. This is not recommended for backups, as parent-uuid
365 relations break for received subvolumes as soon as an intermediate
366 subvolume is deleted.
367 Note that reading all extents is a disk-intensive task, expect long
369 execution times and high ram usage. Consider setting cache_dir.
370 ls <path>|<url>...
372 List all btrfs subvolumes below <path>. Use the --format command
373 line option to switch between different output formats. See
374 lsbtr(1).
375 config print|print-all
377 Prints the parsed configuration file. Use the --format command line
378 option to switch between different output formats.
379
381 Filter arguments are accepted in form:
382 <group-name>
384 Matches the group configuration option of volume, subvolume or
385 target sections.
386 <hostname>[:<port>]
388 Matches the hostname portion from <url> of volume or target
389 sections.
390 <directory>|<url>
392 Matches volume, subvolume or target sections by either relative or
393 absolute path (if starting with "/" or "ssh://" or "<hostname>:/"),
394 accepting wildcard character "*". Relative paths are matched
395 against the end of the pathname. Either:
396 <volume-directory>
398 Matches volume sections.
399 <volume-directory>/<subvolume-name>
401 Matches subvolume sections.
402 <volume-directory>/<snapshot-dir>/<snapshot-name>
404 Matches subvolume sections defining snapshots with the
405 configured snapshot_dir and snapshot_name.
406 <target-directory>
408 Matches target sections.
409 <target-directory>/<snapshot-name>
411 Matches target sections within subvolume sections defining
412 snapshots with the configured snapshot_name.
413 Accepted formats for <url> are:
415 ssh://<hostname>[:<port>]/<directory>
417 <hostname>:<directory>
418 Note that for run and snapshot commands, a filter matching a target
420 configuration section also enables snapshot creation of the surrounding
421 subvolume section. If this is not desired, consider running snapshot
422 and resume commands separately.
423
425 /etc/btrbk.conf, /etc/btrbk/btrbk.conf
426 Default configuration file. The file format and configuration
427 options are described in btrbk.conf(5).
428
430 btrbk returns the following error codes:
431 0
433 No problems occurred.
434 1
436 Generic error code.
437 2
439 Parse error: when parsing command-line options or configuration
440 file.
441 3
443 Lockfile error: if lockfile is present on startup.
444 10
446 Backup abort: At least one backup task aborted.
447 255
449 Script error.
450
452 Please refer to the btrbk project page https://digint.ch/btrbk/ for
453 further details.
454
456 btrbk.conf(5), btrfs(8)
457 For more information about btrfs and incremental backups, see the web
459 site at https://btrfs.wiki.kernel.org/index.php/Incremental_Backup
460
462 Axel Burri axel@tty0.ch
463Btrbk 0.32.1 2022-02-26 BTRBK(1)