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] [--format <output-format>]
14 [-S|--print-schedule] [--progress]
15 [--lockfile <file>]
16 [--override <config_option>=<value>]
17 <command> [<args>]
18
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 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 Snapshots and Backups
32 Snapshots as well as backup subvolumes are created in form:
33 <snapshot-name>.<timestamp>[_N]
35 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 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
51 -h, --help
52 Prints the synopsis and a list of the commands.
53 --version
55 Prints the btrbk version.
56 -c, --config <file>
58 Read the configuration from <file>.
59 -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 --exclude <filter>
68 Exclude configured sections matching <filter>. See FILTER
69 STATEMENTS below
70 -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 --preserve-snapshots
77 Preserve all snapshots. Skips deletion of any snapshots, even if
78 specified in the configuration file.
79 --preserve-backups
81 Preserve all backups. Skips deletion of any backups, even if
82 specified in the configuration file.
83 --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 -v, --verbose
91 Verbose output (shortcut for "--loglevel=info").
92 -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 -l, --loglevel <level>
98 Set the level of verbosity. Accepted levels are warn, info, debug,
99 and trace.
100 -t, --table
102 Print output in table format (shortcut for "--format=table").
103 --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 -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 --progress
116 Show progress bar on send-receive operation.
117 --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 --override <config_option>=<value>
125 Override a configuration option <config_option> with <value>.
126 Globally, for ALL contexts. Use with care!
127
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 See section RETENTION POLICY in btrbk.conf(5) for information on
135 configuring the retention policy.
136 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 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 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 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 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 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 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 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 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 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 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 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 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 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 Note that this feature needs a linux kernel >=4.4 to work
227 correctly!
228 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 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 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 Informative Commands
256 The following commands are informative only, and will not alter the
257 file system.
258 stats [filter...]
260 Print statistics of snapshot and backup subvolumes. Optionally
261 filtered by [filter...] arguments (see FILTER STATEMENTS below).
262 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 Available subcommands:
269 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 backups
276 List all backups (and corresponding snapshots).
277 latest
279 List most recent common snapshot/backup pair, or most recent
280 snapshot if no common found.
281 config
283 List configured source/snapshot/target relations.
284 source
286 List configured source/snapshot relations.
287 volume
289 List configured volume sections.
290 target
292 List configured targets.
293 Use the --format command line option to switch between different
295 output formats.
296 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 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 diff <from> <to>
310 Print new files since subvolume <from> for subvolume <to>.
311 config print|print-all
313 Prints the parsed configuration file. Use the --format command line
314 option to switch between different output formats.
315
317 Filter arguments are accepted in form:
318 <group-name>
320 Matches the group configuration option of volume, subvolume or
321 target sections.
322 <hostname>[:<port>]
324 Matches the hostname portion from <url> of volume or target
325 sections.
326 <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 <volume-directory>
334 Matches volume sections.
335 <volume-directory>/<subvolume-name>
337 Matches subvolume sections.
338 <volume-directory>/<snapshot-dir>/<snapshot-name>
340 Matches subvolume sections defining snapshots with the
341 configured snapshot_dir and snapshot_name.
342 <target-directory>
344 Matches target sections.
345 <target-directory>/<snapshot-name>
347 Matches target sections within subvolume sections defining
348 snapshots with the configured snapshot_name.
349 Accepted formats for <url> are:
351 ssh://<hostname>[:<port>]/<directory>
353 <hostname>:<directory>
354 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
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
366 btrbk returns the following error codes:
367 0
369 No problems occurred.
370 1
372 Generic error code.
373 2
375 Parse error: when parsing command-line options or configuration
376 file.
377 3
379 Lockfile error: if lockfile is present on startup.
380 10
382 Backup abort: At least one backup task aborted.
383 255
385 Script error.
386
388 Please refer to the btrbk project page https://digint.ch/btrbk/ for
389 further details.
390
392 btrbk.conf(5), btrfs(8)
393 For more information about btrfs and incremental backups, see the web
395 site at https://btrfs.wiki.kernel.org/index.php/Incremental_Backup
396
398 Axel Burri axel@tty0.ch
399Btrbk 0.28.3 2019-07-28 BTRBK(1)