1BTRBK(1)                         Btrbk Manual                         BTRBK(1)
2
3
4

NAME

6       btrbk - backup tool for btrfs subvolumes
7

SYNOPSIS

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

DESCRIPTION

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
26       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
32   Snapshots and Backups
33       Snapshots as well as backup subvolumes are created in the form:
34
35           <snapshot-name>.<timestamp>[_N]
36
37       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
45       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
48       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

OPTIONS

56       -h, --help
57           Prints the synopsis and a list of the commands.
58
59       --version
60           Prints the btrbk version.
61
62       -c, --config <file>
63           Read the configuration from <file>.
64
65       -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
72       --exclude <filter>
73           Exclude configured sections matching <filter>. See FILTER
74           STATEMENTS below.
75
76       -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
81       --preserve-snapshots
82           Preserve all snapshots. Skips deletion of any snapshots, even if
83           specified in the configuration file.
84
85       --preserve-backups
86           Preserve all backups. Skips deletion of any backups, even if
87           specified in the configuration file.
88
89       --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
95       -v, --verbose
96           Increase the logging level, see "--loglevel".
97
98       -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
102       -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
106       -t, --table
107           Print output in table format (shortcut for "--format=table").
108
109       -L, --long
110           Print output in long table format (shortcut for "--format=long").
111
112       -1, --single-column
113           Print output as single column (not available for all commands).
114
115       --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
119           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
124       --pretty
125           Print table output with lowercase, underlined column headings
126           (instead of single-line uppercase headings).
127
128       -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
133       --progress
134           Show progress bar on send-receive operation. Requires "mbuffer"
135           command (version >= 20180505) installed on the host running btrbk.
136
137       --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
143       --override <config_option>=<value>
144           Override a configuration option <config_option> with <value>.
145           Globally, for ALL contexts. Use with care!
146

COMMANDS

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
153       See section RETENTION POLICY in btrbk.conf(5) for information on
154       configuring the retention policy.
155
156       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
163           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
168           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
173           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
182           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
189           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
199       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
205       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
210           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
215       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
222       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
230           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
235       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
243           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
247           Note that this feature needs a linux kernel >=4.4 to work
248           correctly!
249
250           If --raw option is set, creates raw targets (experimental, see
251           btrbk.conf(5), TARGET TYPES).
252
253       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
259       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
263           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
279   Informative Commands
280       The following commands are informative only, and will not alter the
281       file system.
282
283       stats [filter...]
284           Print statistics of snapshot and backup subvolumes. Optionally
285           filtered by [filter...] arguments (see FILTER STATEMENTS below).
286
287       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
292           Available subcommands (default “all”):
293
294           all
295               List all snapshots and backups created by btrbk.
296
297           snapshots
298               List all snapshots created by btrbk.
299
300           backups
301               List all backups (and correlated snapshots) created by btrbk.
302
303           latest
304               List most recent common snapshot/backup pair, or most recent
305               snapshot if no common found.
306
307           config
308               List configured source/snapshot/target relations.
309
310           source
311               List configured source/snapshot relations.
312
313           volume
314               List configured volume sections.
315
316           target
317               List configured targets.
318
319           Use the --format command line option to switch between different
320           output formats.
321
322       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
328       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
334       diff <from> <to>
335           List the modified files since generation (transid) of subvolume
336           <from> in subvolume <to>. Columns:
337
338               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
344       extents [diff] <subvolume>... [exclusive <subvolume>...]
345           Print accurate disk space usage and diff based on extent data
346           (FIEMAP ioctl, slow!).
347
348           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
353               btrbk extents diff /backup/data.* exclusive /backup/data.2010*
354
355           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
361           The DIFF column shows the data added to the previous subvolume
362           (relative complement of block regions).
363
364           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
369           Note that reading all extents is a disk-intensive task, expect long
370           execution times and high ram usage. Consider setting cache_dir.
371
372       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
377       config print|print-all
378           Prints the parsed configuration file.
379

FILTER STATEMENTS

381       Filter arguments are accepted in form:
382
383       <group-name>
384           Matches the group configuration option of volume, subvolume or
385           target sections.
386
387       <hostname>[:<port>]
388           Matches the hostname portion from <url> of volume or target
389           sections.
390
391       <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
397           <volume-directory>
398               Matches volume sections.
399
400           <volume-directory>/<subvolume-name>
401               Matches subvolume sections.
402
403           <volume-directory>/<snapshot-dir>/<snapshot-name>
404               Matches subvolume sections defining snapshots with the
405               configured snapshot_dir and snapshot_name.
406
407           <target-directory>
408               Matches target sections.
409
410           <target-directory>/<snapshot-name>
411               Matches target sections within subvolume sections defining
412               snapshots with the configured snapshot_name.
413
414           Accepted formats for <url> are:
415
416               ssh://<hostname>[:<port>]/<directory>
417               <hostname>:<directory>
418
419       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
424       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

FILES

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

EXIT STATUS

433       btrbk returns the following error codes:
434
435       0
436           No problems occurred.
437
438       1
439           Generic error code.
440
441       2
442           Parse error: when parsing command-line options or configuration
443           file.
444
445       3
446           Lockfile error: if lockfile is present on startup.
447
448       10
449           Backup abort: At least one backup task aborted.
450
451       255
452           Script error.
453

AVAILABILITY

455       Please refer to the btrbk project page https://digint.ch/btrbk/ for
456       further details.
457

SEE ALSO

459       btrbk.conf(5), btrfs(8)
460
461       For more information about btrfs and incremental backups, see the web
462       site at https://btrfs.wiki.kernel.org/index.php/Incremental_Backup
463

AUTHOR

465       Axel Burri axel@tty0.ch
466
467
468
469Btrbk 0.32.6                      2023-03-25                          BTRBK(1)
Impressum