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 the 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. <timestamp> is a
39 timestamp describing the creation time (local time of the host running
40 btrbk) of the snapshot/backup. The format can be configured using the
41 timestamp_format option, refer to btrbk.conf(5) for details. If
42 multiple snapshots/backups are created on the same date/time, N will be
43 incremented on each snapshot, starting at 1.
44 If a snapshot or backup does not match the naming scheme above (e.g. if
46 it has been renamed manually), btrbk will leave it untouched.
47 Note that in btrfs terminology, a snapshot is a “subvolume with a given
49 initial content of the original subvolume” (showing a parent-uuid, see
50 btrfs-subvolume(8)), and they can be read-write (default) or read-only.
51 In btrbk terminology, snapshot means “read-only btrfs snapshot”, and
52 backup means “read-only subvolume created with send/receive” (showing a
53 received-uuid).
54
56 -h, --help
57 Prints the synopsis and a list of the commands.
58 --version
60 Prints the btrbk version.
61 -c, --config <file>
63 Read the configuration from <file>.
64 -n, --dry-run
66 Don’t run anything that would alter the filesystem, just show the
67 snapshots and backup subvolumes that would be created/deleted by
68 the run, snapshot, resume, prune, archive and clean commands. Use
69 in conjunction with -l debug to see the btrfs commands that would
70 be executed.
71 --exclude <filter>
73 Exclude configured sections matching <filter>. See FILTER
74 STATEMENTS below.
75 -p, --preserve
77 Preserve all snapshots and backups. Skips deletion of any snapshots
78 and backups, even if specified in the configuration file (shortcut
79 for "--preserve-snapshots --preserve-backups").
80 --preserve-snapshots
82 Preserve all snapshots. Skips deletion of any snapshots, even if
83 specified in the configuration file.
84 --preserve-backups
86 Preserve all backups. Skips deletion of any backups, even if
87 specified in the configuration file.
88 --wipe
90 Ignore configured snapshot retention policy, delete all but the
91 latest snapshots instead. All snapshots needed for incremental
92 backup (latest common) are also preserved. Useful if you are
93 getting low on disk space (ENOSPC).
94 -v, --verbose
96 Increase the logging level, see "--loglevel".
97 -q, --quiet
99 Quiet operation. If set, btrbk does not print the summary after
100 executing the run, snapshot, resume, prune, or archive commands.
101 -l, --loglevel <level>
103 Set the level of verbosity for the stderr logging. Accepted levels
104 are: error, warn, info, debug, and trace. Default is info.
105 -t, --table
107 Print output in table format (shortcut for "--format=table").
108 -L, --long
110 Print output in long table format (shortcut for "--format=long").
111 -1, --single-column
113 Print output as single column (not available for all commands).
114 --format table|long|raw|col:[h:]<columns>
116 Print output in specified format. If set to "raw", prints
117 space-separated, quoted key=value pairs (machine readable).
118 If set to "col:", prints only the <columns> specified
120 (comma-separated list). Header lines are ommitted if the "h:"
121 modifier is present. Columns prefixed with "-" are collapsed if
122 empty. Columns postfixed with ":RALIGN" are right-aligned.
123 --pretty
125 Print table output with lowercase, underlined column headings
126 (instead of single-line uppercase headings).
127 -S, --print-schedule
129 Print detailed scheduler information on run, snapshot, resume,
130 prune and archive commands. Use the --format command line option to
131 switch between different output formats.
132 --progress
134 Show progress bar on send-receive operation. Requires "mbuffer"
135 command (version >= 20180505) installed on the host running btrbk.
136 --lockfile <file>
138 Create lockfile <file> on startup; checks lockfile before running
139 any btrfs commands (using perl "flock"), and exits if the lock is
140 held by another btrbk instance. Overrides configuration option
141 "lockfile". Ignored on dryrun (-n, --dry-run).
142 --override <config_option>=<value>
144 Override a configuration option <config_option> with <value>.
145 Globally, for ALL contexts. Use with care!
146
148 Actions
149 The following commands are used to create snapshots and/or backups. All
150 actions can operate in dry-run mode (-n, --dry-run). Use the --format
151 command line option to switch between different output formats.
152 See section RETENTION POLICY in btrbk.conf(5) for information on
154 configuring the retention policy.
155 run [filter...]
157 Perform snapshot and backup operations as specified in the
158 configuration file. If the optional [filter...] arguments are
159 present, snapshots and backups are only performed for the
160 subvolumes/targets matching a filter statement (see FILTER
161 STATEMENTS below).
162 Step 0: Read Data
164 Read information from the source and target btrfs filesystems
165 in order to perform sanity checks and identify parent/child and
166 received-from relationships.
167 Step 1: Create Snapshots
169 If the checks succeed, btrbk creates snapshots for the source
170 subvolumes specified in the configuration file, according to
171 the snapshot_create option.
172 Step 2: Create Backups
174 For each specified target, btrbk creates the backups as
175 follows: After comparing the backups to the source snapshots,
176 btrbk transfers all missing snapshots needed to satisfy the
177 configured target retention policy, incrementally from the
178 latest common parent subvolume found. If no common parent
179 subvolume is found (or if the incremental option is set to
180 “no”), a full (non-incremental) backup is created.
181 Step 3: Delete Backups
183 Unless the -p, --preserve or --preserve-backups option is set,
184 backup subvolumes that are not preserved by their configured
185 retention policy will be deleted. Note that the latest
186 snapshot/backup pair are always preserved, regardless of the
187 retention policy.
188 Step 4: Delete Snapshots
190 Unless the -p, --preserve or --preserve-snapshots option is
191 set, snapshots that are not preserved by their configured
192 retention policy will be deleted. Note that the latest snapshot
193 (the one created in step 1) as well as the latest
194 snapshot/backup pair are always preserved, regardless of the
195 retention policy. If any target is unreachable or has errors,
196 all snapshots are preserved in order not to break the
197 incremental chain.
198 dryrun [filter...]
200 Don’t run any btrfs commands that would alter the filesystem, just
201 show the snapshots and backup subvolumes that would be
202 created/deleted by the run command. Use in conjunction with -l
203 debug to see the btrfs commands that would be executed.
204 snapshot [filter...]
206 Snapshot only: skips backup creation and deletion (steps 2 and 3).
207 Use in conjunction with -p, --preserve (or --preserve-snapshots) if
208 you also want to skip snapshot deletion (step 4).
209 Note that snapshot deletion is skipped if the target is not
211 accessible, as it is still required in order to determine the
212 latest snapshot/backup pair (which is always preserved, regardless
213 of the retention policy).
214 resume [filter...]
216 Resume backups: skips snapshot creation (step 1), transfers and
217 deletes snapshots/backups in order to satisfy their configured
218 retention policy. Use in conjunction with -p, --preserve,
219 --preserve-backups, --preserve-snapshots if you want to skip backup
220 and/or snapshot deletion (steps 3, 4).
221 prune [filter...]
223 Prune snapshots and backups: skips snapshot and backup creation
224 (steps 1, 2), only deletes snapshots and backups in order to
225 satisfy their configured retention policy. Useful for cleaning the
226 disk after changing the retention policy. Use in conjunction with
227 --preserve-backups, --preserve-snapshots if you want to skip backup
228 or snapshot deletion (steps 3, 4).
229 Note that deletion is skipped if source or target is not
231 accessible, as it is still required in order to determine the
232 latest snapshot/backup pair (which is always preserved, regardless
233 of the retention policy).
234 archive <source> <target> [--raw]
236 Recursively copy all subvolumes created by btrbk from <source> to
237 <target> directory, optionally rescheduled using archive_preserve_*
238 configuration options. Also creates directory tree on <target>.
239 Useful for creating extra archive copies (clones) from your backup
240 disks. Note that you can continue using btrbk after swapping your
241 backup disk with the archive disk.
242 If you want to use nested subvolumes on the target filesystem, you
244 need to create them by hand (e.g. by running "btrfs subvolume
245 create <target>/dir"). Check the output of --dry-run if unsure.
246 Note that this feature needs a linux kernel >=4.4 to work
248 correctly!
249 If --raw option is set, creates raw targets (experimental, see
251 btrbk.conf(5), TARGET TYPES).
252 clean [filter...]
254 Delete incomplete (garbled) backups. Incomplete backups can be left
255 behind on network errors or kill signals while a send/receive
256 operation is ongoing, and are identified by the "received_uuid"
257 flag not being set on a target (backup) subvolume.
258 The following table gives a quick overview of the action commands and
260 resulting snapshot creation (S+), backup creation (B+), snapshot
261 deletion (S-), and backup deletion (B-):
262 Command Option S+ B+ S- B-
264 --------------------------------------------
265 run x x x x
266 run --preserve x x
267 run --preserve-snapshots x x x
268 run --preserve-backups x x x
269 snapshot x x
270 snapshot --preserve x
271 resume x x x
272 resume --preserve x
273 resume --preserve-snapshots x x
274 resume --preserve-backups x x
275 prune x x
276 prune --preserve-snapshots x
277 prune --preserve-backups x
278 Informative Commands
280 The following commands are informative only, and will not alter the
281 file system.
282 stats [filter...]
284 Print statistics of snapshot and backup subvolumes. Optionally
285 filtered by [filter...] arguments (see FILTER STATEMENTS below).
286 list <subcommand> [filter...]
288 Print information defined by <subcommand> in a tabular form.
289 Optionally filtered by [filter...] arguments (see FILTER STATEMENTS
290 below).
291 Available subcommands (default “all”):
293 all
295 List all snapshots and backups created by btrbk.
296 snapshots
298 List all snapshots created by btrbk.
299 backups
301 List all backups (and correlated snapshots) created by btrbk.
302 latest
304 List most recent common snapshot/backup pair, or most recent
305 snapshot if no common found.
306 config
308 List configured source/snapshot/target relations.
309 source
311 List configured source/snapshot relations.
312 volume
314 List configured volume sections.
315 target
317 List configured targets.
318 Use the --format command line option to switch between different
320 output formats.
321 usage [filter...]
323 Print filesystem usage information for all source/target volumes,
324 optionally filtered by [filter...] arguments (see FILTER STATEMENTS
325 below). Note that the "free" value is an estimate of the amount of
326 data that can still be written to the file system.
327 origin <subvolume>
329 Print the subvolume origin tree: Shows the parent-child
330 relationships as well as the received-from information. Use the
331 --format command line option to switch between different output
332 formats.
333 diff <from> <to>
335 List the modified files since generation (transid) of subvolume
336 <from> in subvolume <to>. Columns:
337 SIZE file was modified for a total of SIZE bytes
339 COUNT file was modified in COUNT generations
340 FLAGS "+" file accessed at offset 0 (at least once)
341 "c" COMPRESS flag is set (at least once)
342 "i" INLINE flag is set (at least once)
343 extents [diff] <subvolume>... [exclusive <subvolume>...]
345 Print accurate disk space usage and diff based on extent data
346 (FIEMAP ioctl, slow!).
347 Subvolumes following the exclusive keyword are added to a separate
349 set, and additional set-exclusive data is printed at the end of the
350 list. This gives a hint of how much data will be freed if deleting
351 all subvolumes in the set. Example:
352 btrbk extents diff /backup/data.* exclusive /backup/data.2010*
354 The EXCLUSIVE column shows the set-exclusive data of all other
356 listed (!) subvolumes (relative complement of block regions).
357 Provided that all related subvolumes (holding references to
358 extents) are also listed, this amount of disk space would be freed
359 when deleting the subvolume.
360 The DIFF column shows the data added to the previous subvolume
362 (relative complement of block regions).
363 If called with the --related option, btrbk also lists all related
365 subvolumes. This is not recommended for backups, as parent-uuid
366 relations break for received subvolumes as soon as an intermediate
367 subvolume is deleted.
368 Note that reading all extents is a disk-intensive task, expect long
370 execution times and high ram usage. Consider setting cache_dir.
371 ls <path>|<url>...
373 List all btrfs subvolumes below <path>. Use the --format command
374 line option to switch between different output formats. See
375 lsbtr(1).
376 config print|print-all
378 Prints the parsed configuration file.
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 Filter statements can match multiple times (e.g. on group as well as
425 host name). In such a case, all matches are processed.
426
428 /etc/btrbk.conf, /etc/btrbk/btrbk.conf
429 Default configuration file. The file format and configuration
430 options are described in btrbk.conf(5).
431
433 btrbk returns the following error codes:
434 0
436 No problems occurred.
437 1
439 Generic error code.
440 2
442 Parse error: when parsing command-line options or configuration
443 file.
444 3
446 Lockfile error: if lockfile is present on startup.
447 10
449 Backup abort: At least one backup task aborted.
450 255
452 Script error.
453
455 Please refer to the btrbk project page https://digint.ch/btrbk/ for
456 further details.
457
459 btrbk.conf(5), btrfs(8)
460 For more information about btrfs and incremental backups, see the web
462 site at https://btrfs.wiki.kernel.org/index.php/Incremental_Backup
463
465 Axel Burri axel@tty0.ch
466Btrbk 0.32.6 2023-03-25 BTRBK(1)