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] [--format <output-format>]
14             [-S|--print-schedule] [--progress]
15             [--lockfile <file>]
16             [--override <config_option>=<value>]
17             <command> [<args>]
18

DESCRIPTION

20       btrbk is a backup tool for btrfs subvolumes, taking advantage of btrfs
21       specific capabilities to create atomic snapshots and transfer them
22       incrementally to a target btrfs filesystem. It is able to perform
23       backups from one source to multiple destinations.
24
25       For most operations, btrbk requires root privileges to run correctly.
26       Alternatively, consider using "btrfs-progs-sudo" or "btrfs-progs-btrbk"
27       backends, both of which allows you to run btrbk as a regular user.
28       Refer to configuration option backend in btrbk.conf(5) for more
29       details.
30
31   Snapshots and Backups
32       Snapshots as well as backup subvolumes are created in form:
33
34           <snapshot-name>.<timestamp>[_N]
35
36       Where <snapshot-name> is identical to the source subvolume name, unless
37       the configuration option snapshot_name is set. The <timestamp> is
38       either "YYYYMMDD" or "YYYYMMDDThhmm" (dependent of the timestamp_format
39       configuration option), where "YYYY" is the year, "MM" is the month,
40       "DD" is the day, "hh" is the hour and "mm" is the minute of the
41       creation time (local time of the host running btrbk). If multiple
42       snapshots/backups are created on the same date/time, N will be
43       incremented on each snapshot, starting at 1.
44
45       Note that snapshot is a btrfs terminology for a “read-only subvolume”
46       (showing a parent-uuid, see btrfs-subvolume(8)); backup is a btrbk
47       terminology for a “read-only subvolume created with send/receive”
48       (showing a received-uuid).
49

OPTIONS

51       -h, --help
52           Prints the synopsis and a list of the commands.
53
54       --version
55           Prints the btrbk version.
56
57       -c, --config <file>
58           Read the configuration from <file>.
59
60       -n, --dry-run
61           Don’t run anything that would alter the filesystem, just show the
62           snapshots and backup subvolumes that would be created/deleted by
63           the run, snapshot, resume, prune, archive and clean commands. Use
64           in conjunction with -l debug to see the btrfs commands that would
65           be executed.
66
67       --exclude <filter>
68           Exclude configured sections matching <filter>. See FILTER
69           STATEMENTS below
70
71       -p, --preserve
72           Preserve all snapshots and backups. Skips deletion of any snapshots
73           and backups, even if specified in the configuration file (shortcut
74           for "--preserve-snapshots --preserve-backups").
75
76       --preserve-snapshots
77           Preserve all snapshots. Skips deletion of any snapshots, even if
78           specified in the configuration file.
79
80       --preserve-backups
81           Preserve all backups. Skips deletion of any backups, even if
82           specified in the configuration file.
83
84       --wipe
85           Ignore configured snapshot retention policy, delete all but latest
86           snapshots instead. All snapshots needed for incremental backup
87           (latest common) are also preserved. Useful if you are getting low
88           on disk space (ENOSPC).
89
90       -v, --verbose
91           Verbose output (shortcut for "--loglevel=info").
92
93       -q, --quiet
94           Quiet operation. If set, btrbk does not print the summary after
95           executing the run, snapshot, resume, prune, or archive commands.
96
97       -l, --loglevel <level>
98           Set the level of verbosity. Accepted levels are warn, info, debug,
99           and trace.
100
101       -t, --table
102           Print output in table format (shortcut for "--format=table").
103
104       --format table|long|raw
105           Print output in specified format. If set to "raw", prints
106           space-separated key="value" pairs (machine readable). Affects
107           output format for run, snapshot, resume, prune, archive and list
108           commands. Useful for further exporting/scripting.
109
110       -S, --print-schedule
111           Print detailed scheduler information on run, snapshot, resume,
112           prune and archive commands. Use the --format command line option to
113           switch between different output formats.
114
115       --progress
116           Show progress bar on send-receive operation.
117
118       --lockfile <file>
119           Create lockfile <file> on startup; checks lockfile before running
120           any btrfs commands (using perl "flock"), and exits if the lock is
121           held by another btrbk instance. Overrides configuration option
122           "lockfile". Ignored on dryrun (-n, --dry-run).
123
124       --override <config_option>=<value>
125           Override a configuration option <config_option> with <value>.
126           Globally, for ALL contexts. Use with care!
127

COMMANDS

129   Actions
130       The following commands are used to create snapshots and/or backups. All
131       actions can operate in dry-run mode (-n, --dry-run). Use the --format
132       command line option to switch between different output formats.
133
134       See section RETENTION POLICY in btrbk.conf(5) for information on
135       configuring the retention policy.
136
137       run [filter...]
138           Perform snapshot and backup operations as specified in the
139           configuration file. If the optional [filter...] arguments are
140           present, snapshots and backups are only performed for the
141           subvolumes/targets matching a filter statement (see FILTER
142           STATEMENTS below).
143
144           Step 0: Read Data
145               Read information from the source and target btrfs filesystems
146               in order to perform sanity checks and identify parent/child and
147               received-from relationships.
148
149           Step 1: Create Snapshots
150               If the checks succeed, btrbk creates snapshots for the source
151               subvolumes specified in the configuration file, according to
152               the snapshot_create option.
153
154           Step 2: Create Backups
155               For each specified target, btrbk creates the backups as
156               follows: After comparing the backups to the source snapshots,
157               btrbk transfers all missing snapshots needed to satisfy the
158               configured target retention policy, incrementally from the
159               latest common parent subvolume found. If no common parent
160               subvolume is found (or if the incremental option is set to
161               “no”), a full (non-incremental) backup is created.
162
163           Step 3: Delete Backups
164               Unless the -p, --preserve or --preserve-backups option is set,
165               backup subvolumes that are not preserved by their configured
166               retention policy will be deleted. Note that the latest
167               snapshot/backup pair are always preserved, regardless of the
168               retention policy.
169
170           Step 4: Delete Snapshots
171               Unless the -p, --preserve or --preserve-snapshots option is
172               set, snapshots that are not preserved by their configured
173               retention policy will be deleted. Note that the latest snapshot
174               (the one created in step 1) as well as the latest
175               snapshot/backup pair are always preserved, regardless of the
176               retention policy.
177
178       dryrun [filter...]
179           Don’t run any btrfs commands that would alter the filesystem, just
180           show the snapshots and backup subvolumes that would be
181           created/deleted by the run command. Use in conjunction with -l
182           debug to see the btrfs commands that would be executed.
183
184       snapshot [filter...]
185           Snapshot only: skips backup creation and deletion (steps 2 and 3).
186           Use in conjunction with -p, --preserve (or --preserve-snapshots) if
187           you also want to skip snapshot deletion (step 4).
188
189           Note that snapshot deletion is skipped if the target is not
190           accessible, as it is still required in order to determine the
191           latest snapshot/backup pair (which is always preserved, regardless
192           of the retention policy).
193
194       resume [filter...]
195           Resume backups: skips snapshot creation (step 1), transfers and
196           deletes snapshots/backups in order to satisfy their configured
197           retention policy. Use in conjunction with -p, --preserve,
198           --preserve-backups, --preserve-snapshots if you want to skip backup
199           and/or snapshot deletion (steps 3, 4).
200
201       prune [filter...]
202           Prune snapshots and backups: skips snapshot and backup creation
203           (steps 1, 2), only deletes snapshots and backups in order to
204           satisfy their configured retention policy. Useful for cleaning the
205           disk after changing the retention policy. Use in conjunction with
206           --preserve-backups, --preserve-snapshots if you want to skip backup
207           or snapshot deletion (steps 3, 4).
208
209           Note that deletion is skipped if source or 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
214       archive <source> <target>
215           Recursively copy all subvolumes created by btrbk from <source> to
216           <target> directory, optionally rescheduled using archive_preserve_*
217           configuration options. Also creates directory tree on <target>.
218           Useful for creating extra archive copies (clones) from your backup
219           disks. Note that you can continue using btrbk after swapping your
220           backup disk with the archive disk.
221
222           If you want to use nested subvolumes on the target filesystem, you
223           need to create them by hand (e.g. by running "btrfs subvolume
224           create <target>/dir"). Check the output of --dry-run if unsure.
225
226           Note that this feature needs a linux kernel >=4.4 to work
227           correctly!
228
229       clean [filter...]
230           Delete incomplete (garbled) backups. Incomplete backups can be left
231           behind on network errors or kill signals while a send/receive
232           operation is ongoing, and are identified by the "received_uuid"
233           flag not being set on a target (backup) subvolume.
234
235       The following table gives a quick overview of the action commands and
236       resulting snapshot creation (S+), backup creation (B+), snapshot
237       deletion (S-), and backup deletion (B-):
238
239           Command   Option                 S+ B+ S- B-
240           --------------------------------------------
241           run                              x  x  x  x
242           run       --preserve             x  x
243           run       --preserve-snapshots   x  x     x
244           run       --preserve-backups     x  x  x
245           snapshot                         x     x
246           snapshot  --preserve             x
247           resume                              x  x  x
248           resume    --preserve                x
249           resume    --preserve-snapshots      x     x
250           resume    --preserve-backups        x  x
251           prune                                  x  x
252           prune     --preserve-snapshots            x
253           prune     --preserve-backups           x
254
255   Informative Commands
256       The following commands are informative only, and will not alter the
257       file system.
258
259       stats [filter...]
260           Print statistics of snapshot and backup subvolumes. Optionally
261           filtered by [filter...] arguments (see FILTER STATEMENTS below).
262
263       list <subcommand> [filter...]
264           Print information defined by <subcommand> in a tabular form.
265           Optionally filtered by [filter...] arguments (see FILTER STATEMENTS
266           below).
267
268           Available subcommands:
269
270           snapshots
271               List all snapshots (and corresponding backups). Note that all
272               snapshots related to configured subvolumes are listed, not only
273               the ones created by btrbk.
274
275           backups
276               List all backups (and corresponding snapshots).
277
278           latest
279               List most recent common snapshot/backup pair, or most recent
280               snapshot if no common found.
281
282           config
283               List configured source/snapshot/target relations.
284
285           source
286               List configured source/snapshot relations.
287
288           volume
289               List configured volume sections.
290
291           target
292               List configured targets.
293
294           Use the --format command line option to switch between different
295           output formats.
296
297       usage [filter...]
298           Print filesystem usage information for all source/target volumes,
299           optionally filtered by [filter...] arguments (see FILTER STATEMENTS
300           below). Note that the "free" value is an estimate of the amount of
301           data that can still be written to the file system.
302
303       origin <subvolume>
304           Print the subvolume origin tree: Shows the parent-child
305           relationships as well as the received-from information. Use the
306           --format command line option to switch between different output
307           formats.
308
309       diff <from> <to>
310           Print new files since subvolume <from> for subvolume <to>.
311
312       config print|print-all
313           Prints the parsed configuration file. Use the --format command line
314           option to switch between different output formats.
315

FILTER STATEMENTS

317       Filter arguments are accepted in form:
318
319       <group-name>
320           Matches the group configuration option of volume, subvolume or
321           target sections.
322
323       <hostname>[:<port>]
324           Matches the hostname portion from <url> of volume or target
325           sections.
326
327       <directory>|<url>
328           Matches volume, subvolume or target sections by either relative or
329           absolute path (if starting with "/" or "ssh://" or "<hostname>:/"),
330           accepting wildcard character "*". Relative paths are matched
331           against the end of the pathname. Either:
332
333           <volume-directory>
334               Matches volume sections.
335
336           <volume-directory>/<subvolume-name>
337               Matches subvolume sections.
338
339           <volume-directory>/<snapshot-dir>/<snapshot-name>
340               Matches subvolume sections defining snapshots with the
341               configured snapshot_dir and snapshot_name.
342
343           <target-directory>
344               Matches target sections.
345
346           <target-directory>/<snapshot-name>
347               Matches target sections within subvolume sections defining
348               snapshots with the configured snapshot_name.
349
350           Accepted formats for <url> are:
351
352               ssh://<hostname>[:<port>]/<directory>
353               <hostname>:<directory>
354
355       Note that for run and snapshot commands, a filter matching a target
356       configuration section also enables snapshot creation of the surrounding
357       subvolume section. If this is not desired, consider running snapshot
358       and resume commands separately.
359

FILES

361       /etc/btrbk.conf, /etc/btrbk/btrbk.conf
362           Default configuration file. The file format and configuration
363           options are described in btrbk.conf(5).
364

EXIT STATUS

366       btrbk returns the following error codes:
367
368       0
369           No problems occurred.
370
371       1
372           Generic error code.
373
374       2
375           Parse error: when parsing command-line options or configuration
376           file.
377
378       3
379           Lockfile error: if lockfile is present on startup.
380
381       10
382           Backup abort: At least one backup task aborted.
383
384       255
385           Script error.
386

AVAILABILITY

388       Please  refer  to the btrbk project page <https://digint.ch/btrbk/> for
389       further details.
390

SEE ALSO

392       btrbk.conf(5), btrfs(8)
393
394       For more information about btrfs and incremental backups, see  the  web
395       site at <https://btrfs.wiki.kernel.org/index.php/Incremental_Backup>
396

AUTHOR

398       Axel Burri <axel@tty0.ch <axel@tty0.ch>>
399
400
401
402Btrbk 0.28.3                      2019-07-28                          BTRBK(1)
Impressum