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]
11 [-p|--preserve] [--preserve-snapshots] [--preserve-backups]
12 [-v|--verbose] [-q|--quiet] [-l|--loglevel <level>]
13 [-t|--table] [--format <output-format>]
14 [--progress] [-S|--print-schedule]
15 [--override <config_option>=<value>]
16 [--lockfile <file>]
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 -n, --dry-run
58 Don’t run anything that would alter the filesystem, just show the
59 snapshots and backup subvolumes that would be created/deleted by
60 the run, snapshot, resume, prune, archive and clean commands. Use
61 in conjunction with -l debug to see the btrfs commands that would
62 be executed.
63 -c, --config <file>
65 Read the configuration from <file>.
66 -p, --preserve
68 Preserve all snapshots and backups. Skips deletion of any snapshots
69 and backups, even if specified in the configuration file (shortcut
70 for "--preserve-snapshots --preserve-backups").
71 --preserve-snapshots
73 Preserve all snapshots. Skips deletion of any snapshots, even if
74 specified in the configuration file.
75 --preserve-backups
77 Preserve all backups. Skips deletion of any backups, even if
78 specified in the configuration file.
79 --wipe
81 Ignore configured snapshot retention policy, delete all but latest
82 snapshots instead. All snapshots needed for incremental backup
83 (latest common) are also preserved. Useful if you are getting low
84 on disk space (ENOSPC).
85 -v, --verbose
87 Verbose output (shortcut for "--loglevel=info").
88 -q, --quiet
90 Quiet operation. If set, btrbk does not print the summary after
91 executing the run, snapshot, resume, prune, or archive commands.
92 -l, --loglevel <level>
94 Set the level of verbosity. Accepted levels are warn, info, debug,
95 and trace.
96 -t, --table
98 Print output in table format (shortcut for "--format=table").
99 --format table|long|raw
101 Print output in specified format. If set to "raw", prints
102 space-separated key="value" pairs (machine readable). Affects
103 output format for run, snapshot, resume, prune, archive and list
104 commands. Useful for further exporting/scripting.
105 --progress
107 Show progress bar on send-receive operation.
108 -S, --print-schedule
110 Print detailed scheduler information on run, snapshot, resume,
111 prune and archive commands. Use the --format command line option to
112 switch between different output formats.
113 --lockfile <file>
115 Create lockfile <file> on startup; checks lockfile before running
116 any btrfs commands (using perl "flock"), and exits if the lock is
117 held by another btrbk instance. Overrides configuration option
118 "lockfile". Ignored on dryrun (-n, --dry-run).
119 --override <config_option>=<value>
121 Override a configuration option <config_option> with <value>.
122 Globally, for ALL contexts. Use with care!
123
125 Actions
126 The following commands are used to create snapshots and/or backups. All
127 actions can operate in dry-run mode (-n, --dry-run). Use the --format
128 command line option to switch between different output formats.
129 See section RETENTION POLICY in btrbk.conf(5) for information on
131 configuring the retention policy.
132 run [filter...]
134 Perform snapshot and backup operations as specified in the
135 configuration file. If the optional [filter...] arguments are
136 present, snapshots and backups are only performed for the
137 subvolumes/targets matching a filter statement (see FILTER
138 STATEMENTS below).
139 Step 0: Read Data
141 Read information from the source and target btrfs filesystems
142 in order to perform sanity checks and identify parent/child and
143 received-from relationships.
144 Step 1: Create Snapshots
146 If the checks succeed, btrbk creates snapshots for the source
147 subvolumes specified in the configuration file, according to
148 the snapshot_create option.
149 Step 2: Create Backups
151 For each specified target, btrbk creates the backups as
152 follows: After comparing the backups to the source snapshots,
153 btrbk transfers all missing snapshots needed to satisfy the
154 configured target retention policy, incrementally from the
155 latest common parent subvolume found. If no common parent
156 subvolume is found (or if the incremental option is set to
157 “no”), a full (non-incremental) backup is created.
158 Step 3: Delete Backups
160 Unless the -p, --preserve or --preserve-backups option is set,
161 backup subvolumes that are not preserved by their configured
162 retention policy will be deleted. Note that the latest
163 snapshot/backup pair are always preserved, regardless of the
164 retention policy.
165 Step 4: Delete Snapshots
167 Unless the -p, --preserve or --preserve-snapshots option is
168 set, snapshots that are not preserved by their configured
169 retention policy will be deleted. Note that the latest snapshot
170 (the one created in step 1) as well as the latest
171 snapshot/backup pair are always preserved, regardless of the
172 retention policy.
173 dryrun [filter...]
175 Don’t run any btrfs commands that would alter the filesystem, just
176 show the snapshots and backup subvolumes that would be
177 created/deleted by the run command. Use in conjunction with -l
178 debug to see the btrfs commands that would be executed.
179 snapshot [filter...]
181 Snapshot only: skips backup creation and deletion (steps 2 and 3).
182 Use in conjunction with -p, --preserve (or --preserve-snapshots) if
183 you also want to skip snapshot deletion (step 4).
184 Note that snapshot deletion is skipped if the target is not
186 accessible, as it is still required in order to determine the
187 latest snapshot/backup pair (which is always preserved, regardless
188 of the retention policy).
189 resume [filter...]
191 Resume backups: skips snapshot creation (step 1), transfers and
192 deletes snapshots/backups in order to satisfy their configured
193 retention policy. Use in conjunction with -p, --preserve,
194 --preserve-backups, --preserve-snapshots if you want to skip backup
195 and/or snapshot deletion (steps 3, 4).
196 prune [filter...]
198 Prune snapshots and backups: skips snapshot and backup creation
199 (steps 1, 2), only deletes snapshots and backups in order to
200 satisfy their configured retention policy. Useful for cleaning the
201 disk after changing the retention policy. Use in conjunction with
202 --preserve-backups, --preserve-snapshots if you want to skip backup
203 or snapshot deletion (steps 3, 4).
204 Note that deletion is skipped if source or target is not
206 accessible, as it is still required in order to determine the
207 latest snapshot/backup pair (which is always preserved, regardless
208 of the retention policy).
209 archive <source> <target> *experimental*
211 Recursively copy all subvolumes created by btrbk from <source> to
212 <target> directory, optionally rescheduled using archive_preserve_*
213 configuration options. Also creates directory tree on <target> (see
214 bugs below). Useful for creating extra archive copies (clones) from
215 your backup disks. Note that you can continue using btrbk after
216 swapping your backup disk with the archive disk.
217 If you want to use nested subvolumes on the target filesystem, you
219 need to create them by hand (e.g. by running "btrfs subvolume
220 create <target>/dir"). Check the output of --dry-run if unsure.
221 Note that this feature needs a linux kernel >=4.4 to work
223 correctly!
224 clean [filter...]
226 Delete incomplete (garbled) backups. Incomplete backups can be left
227 behind on network errors or kill signals while a send/receive
228 operation is ongoing, and are identified by the "received_uuid"
229 flag not being set on a target (backup) subvolume.
230 The following table gives a quick overview of the action commands and
232 resulting snapshot creation (S+), backup creation (B+), snapshot
233 deletion (S-), and backup deletion (B-):
234 Command Option S+ B+ S- B-
236 --------------------------------------------
237 run x x x x
238 run --preserve x x
239 run --preserve-snapshots x x x
240 run --preserve-backups x x x
241 snapshot x x
242 snapshot --preserve x
243 resume x x x
244 resume --preserve x
245 resume --preserve-snapshots x x
246 resume --preserve-backups x x
247 prune x x
248 prune --preserve-snapshots x
249 prune --preserve-backups x
250 Informative Commands
252 The following commands are informative only, and will not alter the
253 file system.
254 stats [filter...]
256 Print statistics of snapshot and backup subvolumes. Optionally
257 filtered by [filter...] arguments (see FILTER STATEMENTS below).
258 list <subcommand> [filter...]
260 Print information defined by <subcommand> in a tabular form.
261 Optionally filtered by [filter...] arguments (see FILTER STATEMENTS
262 below).
263 Available subcommands:
265 snapshots
267 List all snapshots (and corresponding backups). Note that all
268 snapshots related to configured subvolumes are listed, not only
269 the ones created by btrbk.
270 backups
272 List all backups (and corresponding snapshots).
273 latest
275 List most recent common snapshot/backup pair, or most recent
276 snapshot if no common found.
277 config
279 List configured source/snapshot/target relations.
280 source
282 List configured source/snapshot relations.
283 volume
285 List configured volume sections.
286 target
288 List configured targets.
289 Use the --format command line option to switch between different
291 output formats.
292 usage [filter...]
294 Print filesystem usage information for all source/target volumes,
295 optionally filtered by [filter...] arguments (see FILTER STATEMENTS
296 below). Note that the "free" value is an estimate of the amount of
297 data that can still be written to the file system.
298 origin <subvolume>
300 Print the subvolume origin tree: Shows the parent-child
301 relationships as well as the received-from information. Use the
302 --format command line option to switch between different output
303 formats.
304 diff <from> <to>
306 Print new files since subvolume <from> for subvolume <to>.
307 config print|print-all
309 Prints the parsed configuration file. Use the --format command line
310 option to switch between different output formats.
311
313 Filter arguments are accepted in form:
314 <group-name>
316 Matches the group configuration option of a volume, subvolume or
317 target section (including all underlying sections).
318 [hostname:]<volume-directory>
320 Matches all subvolumes and targets of a volume configuration
321 section.
322 [hostname:]<volume-directory>/<subvolume-name>
324 Matches the specified subvolume and all targets of a subvolume
325 configuration section.
326 [hostname:]<target-directory>
328 Matches all targets of a target configuration section.
329 [hostname:]<target-directory>/<snapshot-name>
331 Matches a single target of a target section within a subvolume
332 section with given <snapshot-name>.
333 For convenience, [hostname:] can be specified as either "hostname:" or
335 "ssh://hostname/".
336 Note that for run and snapshot commands, a filter matching a target
338 configuration section also enables snapshot creation of the surrounding
339 subvolume section. If this is not desired, consider running snapshot
340 and resume commands separately.
341
343 /etc/btrbk.conf, /etc/btrbk/btrbk.conf
344 Default configuration file. The file format and configuration
345 options are described in btrbk.conf(5).
346
348 btrbk returns the following error codes:
349 0
351 No problems occurred.
352 1
354 Generic error code.
355 2
357 Parse error: when parsing command-line options or configuration
358 file.
359 3
361 Lockfile error: if lockfile is present on startup.
362 10
364 Backup abort: At least one backup task aborted.
365 255
367 Script error.
368
370 Please refer to the btrbk project page https://digint.ch/btrbk/ for
371 further details.
372
374 btrbk.conf(5), btrfs(8)
375 For more information about btrfs and incremental backups, see the web
377 site at https://btrfs.wiki.kernel.org/index.php/Incremental_Backup
378
380 Axel Burri <axel@tty0.ch>
381Btrbk 0.27.0 2018-10-16 BTRBK(1)