ambiser
/
btrbk
mirror of https://github.com/digint/btrbk
9
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
btrbk/doc/btrbk.1.asciidoc

534 lines
19 KiB
Plaintext
Raw Blame History

btrbk(1)
========
:date: 2023-03-25
:release-version: 0.32.6
:man manual: Btrbk Manual
:man source: Btrbk {release-version}
NAME
----
btrbk - backup tool for btrfs subvolumes
SYNOPSIS
--------
[verse]
btrbk [-h|--help] [--version]
[-c|--config <file>] [-n|--dry-run] [--exclude <filter>]
[-p|--preserve] [--preserve-snapshots] [--preserve-backups]
[-v|--verbose] [-q|--quiet] [-l|--loglevel <level>]
[-t|--table] [-L|--long] [-1|--single-column]
[--format <output-format>] [--pretty]
[-S|--print-schedule] [--progress]
[--lockfile <file>]
[--override <config_option>=<value>]
<command> [[--] <filter>...]
DESCRIPTION
-----------
*btrbk* is a backup tool for btrfs subvolumes, taking advantage of
btrfs specific capabilities to create atomic snapshots and transfer
them incrementally to a target btrfs filesystem. It is able to perform
backups from one source to multiple destinations.
For most operations, *btrbk* requires 'root privileges' to run
correctly. Alternatively, consider using "btrfs-progs-sudo" or
"btrfs-progs-btrbk" backends, both of which allows you to run btrbk as
a regular user. Refer to configuration option 'backend' in
btrbk.conf(5) for more details.
=== Snapshots and Backups
Snapshots as well as backup subvolumes are created in the form:
<snapshot-name>.<timestamp>[_N]
Where '<snapshot-name>' is identical to the source subvolume name,
unless the configuration option 'snapshot_name' is set. '<timestamp>'
is a timestamp describing the creation time (local time of the host
running btrbk) of the snapshot/backup. The format can be configured
using the 'timestamp_format' option, refer to btrbk.conf(5) for
details. If multiple snapshots/backups are created on the same
date/time, 'N' will be incremented on each snapshot, starting at 1.
If a snapshot or backup does not match the naming scheme above
(e.g. if it has been renamed manually), btrbk will leave it untouched.
Note that in btrfs terminology, a 'snapshot' is a ``subvolume with
a given initial content of the original subvolume'' (showing a
parent-uuid, see btrfs-subvolume(8)), and they can be read-write
(default) or read-only. In btrbk terminology, 'snapshot' means
``read-only btrfs snapshot'', and 'backup' means ``read-only subvolume
created with send/receive'' (showing a received-uuid).
OPTIONS
-------
-h, --help::
Prints the synopsis and a list of the commands.
--version::
Prints the btrbk version.
-c, --config <file>::
Read the configuration from <file>.
-n, --dry-run::
Don't run anything that would alter the filesystem, just show the
snapshots and backup subvolumes that would be created/deleted by
the *run*, *snapshot*, *resume*, *prune*, *archive* and *clean*
commands. Use in conjunction with '-l debug' to see the btrfs
commands that would be executed.
--exclude <filter>::
Exclude configured sections matching '<filter>' (see
<<_filter_statements,FILTER STATEMENTS>> below), or any specific
snapshot from being backuped or deleted, or any specific backup
from being deleted.
+
Note that excluding specific snapshots from being backuped has impact
on scheduling: e.g. if the "first snapshot of the day" is excluded,
the "second snapshot of the day" shifts to "first", creating a backup
as "first backup of the day".
-p, --preserve::
Preserve all snapshots and backups. Skips deletion of any
snapshots and backups, even if specified in the configuration file
(shortcut for "--preserve-snapshots --preserve-backups").
--preserve-snapshots::
Preserve all snapshots. Skips deletion of any snapshots, even if
specified in the configuration file.
--preserve-backups::
Preserve all backups. Skips deletion of any backups, even if
specified in the configuration file.
--wipe::
Ignore configured snapshot retention policy, delete all but the latest
snapshots instead. All snapshots needed for incremental backup
(latest common) are also preserved. Useful if you are getting low
on disk space (ENOSPC).
-v, --verbose::
Increase the logging level, see "--loglevel".
-q, --quiet::
Quiet operation. If set, btrbk does not print the summary after
executing the *run*, *snapshot*, *resume*, *prune*, or *archive*
commands.
-l, --loglevel <level>::
Set the level of verbosity for the stderr logging. Accepted levels
are: error, warn, info, debug, and trace. Default is info.
-t, --table::
Print output in table format (shortcut for "--format=table").
-L, --long::
Print output in long table format (shortcut for "--format=long").
-1, --single-column::
Print output as single column (not available for all commands).
--format table|long|raw|col:[h:]<columns>::
Print output in specified format. If set to "raw", prints
space-separated, quoted key=value pairs (machine readable).
+
If set to "col:", prints only the <columns> specified (comma-separated
list). Header lines are ommitted if the "h:" modifier is present.
Columns prefixed with "-" are collapsed if empty. Columns postfixed
with ":RALIGN" are right-aligned.
--pretty::
Print table output with lowercase, underlined column headings
(instead of single-line uppercase headings).
-S, --print-schedule::
Print detailed scheduler information on *run*, *snapshot*,
*resume*, *prune* and *archive* commands. Use the '--format'
command line option to switch between different output formats.
--progress::
Show progress bar on send-receive operation. Requires "mbuffer"
command (version >= 20180505) installed on the host running btrbk.
--lockfile <file>::
Place an exclusive lock on <file> during program execution, using
flock(2). If the lock is held by another process, exit before
running any actions. Overrides configuration option
"lockfile". Ignored on dryrun ('-n', '--dry-run').
--override <config_option>=<value>::
Override a configuration option <config_option> with
<value>. Globally, for ALL contexts. Use with care!
COMMANDS
--------
=== Actions
The following commands are used to create snapshots and/or
backups. All actions can operate in dry-run mode ('-n', '--dry-run').
Use the '--format' command line option to switch between different
output formats.
See section RETENTION POLICY in *btrbk.conf*(5) for information on
configuring the retention policy.
*run* [filter...]::
Perform snapshot and backup operations as specified in the
configuration file. If the optional [filter...] arguments are
present, snapshots and backups are only performed for the
subvolumes/targets matching a filter statement (see
<<_filter_statements,FILTER STATEMENTS>> below).
+
*Step 0: Read Data*;;
Read information from the source and target btrfs filesystems in
order to perform sanity checks and identify parent/child and
received-from relationships.
+
*Step 1: Create Snapshots*;;
If the checks succeed, btrbk creates snapshots for the source
subvolumes specified in the configuration file, according to the
'snapshot_create' option.
+
*Step 2: Create Backups*;;
For each specified target, btrbk creates the backups as follows:
After comparing the backups to the source snapshots, btrbk
transfers all missing snapshots needed to satisfy the configured
target retention policy, incrementally from the latest common
parent subvolume found. If no common parent subvolume is found (or
if the 'incremental' option is set to ``no''), a full
(non-incremental) backup is created.
+
*Step 3: Delete Backups*;;
Unless the -p, --preserve or --preserve-backups option is set,
backup subvolumes that are not preserved by their configured
retention policy will be deleted. Note that the latest
snapshot/backup pair are always preserved, regardless of the
retention policy.
+
*Step 4: Delete Snapshots*;;
Unless the -p, --preserve or --preserve-snapshots option is set,
snapshots that are not preserved by their configured retention
policy will be deleted. Note that the latest snapshot (the one
created in step 1) as well as the latest snapshot/backup pair are
always preserved, regardless of the retention policy. If any
target is unreachable or has errors, all snapshots are preserved
in order not to break the incremental chain.
*dryrun* [filter...]::
Don't run any btrfs commands that would alter the filesystem, just
show the snapshots and backup subvolumes that would be
created/deleted by the *run* command. Use in conjunction with '-l
debug' to see the btrfs commands that would be executed.
*snapshot* [filter...]::
Snapshot only: skips backup creation and deletion (steps 2 and
3). Use in conjunction with -p, --preserve (or
--preserve-snapshots) if you also want to skip snapshot deletion
(step 4).
+
Note that snapshot deletion is skipped if the target is not
accessible, as it is still required in order to determine the latest
snapshot/backup pair (which is always preserved, regardless of the
retention policy).
*resume* [filter...]::
Resume backups: skips snapshot creation (step 1), transfers and
deletes snapshots/backups in order to satisfy their configured
retention policy. Use in conjunction with -p, --preserve,
--preserve-backups, --preserve-snapshots if you want to skip
backup and/or snapshot deletion (steps 3, 4).
*prune* [filter...]::
Prune snapshots and backups: skips snapshot and backup creation
(steps 1, 2), only deletes snapshots and backups in order to
satisfy their configured retention policy. Useful for cleaning the
disk after changing the retention policy. Use in conjunction with
--preserve-backups, --preserve-snapshots if you want to skip
backup or snapshot deletion (steps 3, 4).
+
Note that deletion is skipped if source or target is not accessible,
as it is still required in order to determine the latest
snapshot/backup pair (which is always preserved, regardless of the
retention policy).
*archive* <source> <target> [--raw]::
Recursively copy all subvolumes created by btrbk from <source> to
<target> directory, optionally rescheduled using
'archive_preserve_*' configuration options. Also creates directory
tree on <target>. Useful for creating extra archive copies
(clones) from your backup disks. Note that you can continue using
btrbk after swapping your backup disk with the archive disk.
+
If you want to use nested subvolumes on the target filesystem, you
need to create them by hand (e.g. by running "btrfs subvolume create
<target>/dir"). Check the output of --dry-run if unsure.
+
Note that this feature needs a *linux kernel >=4.4* to work correctly!
+
If '--raw' option is set, creates raw targets (experimental, see
btrbk.conf(5), TARGET TYPES).
*clean* [filter...]::
Delete incomplete (garbled) backups. Incomplete backups can be
left behind on network errors or kill signals while a send/receive
operation is ongoing, and are identified by the "received_uuid"
flag not being set on a target (backup) subvolume.
The following table gives a quick overview of the action commands and
resulting snapshot creation (S+), backup creation (B+), snapshot
deletion (S-), and backup deletion (B-):
ifdef::backend-docbook,backend-manpage[]
....
Command Option S+ B+ S- B-
--------------------------------------------
run x x x x
run --preserve x x
run --preserve-snapshots x x x
run --preserve-backups x x x
snapshot x x
snapshot --preserve x
resume x x x
resume --preserve x
resume --preserve-snapshots x x
resume --preserve-backups x x
prune x x
prune --preserve-snapshots x
prune --preserve-backups x
....
endif::backend-docbook,backend-manpage[]
ifndef::backend-docbook,backend-manpage[]
[cols="2*<m,4*^", options="header,autowidth,compact", style="monospaced"]
|=======
|Command |Option |S+ |B+ |S- |B-
|run | | x | x | x | x
|run |--preserve | x | x | |
|run |--preserve-snapshots | x | x | | x
|run |--preserve-backups | x | x | x |
|snapshot | | x | | x |
|snapshot |--preserve | x | | |
|resume | | | x | x | x
|resume |--preserve | | x | |
|resume |--preserve-snapshots | | x | | x
|resume |--preserve-backups | | x | x |
|prune | | | | x | x
|prune |--preserve-snapshots | | | | x
|prune |--preserve-backups | | | x |
|=======
endif::backend-docbook,backend-manpage[]
=== Informative Commands
The following commands are informative only, and will not alter the
file system.
*stats* [filter...]::
Print statistics of snapshot and backup subvolumes. Optionally
filtered by [filter...] arguments (see <<_filter_statements,FILTER
STATEMENTS>> below).
*list* <subcommand> [filter...]::
Print information defined by <subcommand> in a tabular
form. Optionally filtered by [filter...] arguments (see
<<_filter_statements,FILTER STATEMENTS>> below).
+
Available subcommands (default ``all''):
+
--
ifndef::backend-docbook,backend-manpage[]
[horizontal]
endif::backend-docbook,backend-manpage[]
*all*;; List all snapshots and backups created by btrbk.
*snapshots*;; List all snapshots created by btrbk.
*backups*;; List all backups (and correlated snapshots) created by
btrbk.
*latest*;; List most recent common snapshot/backup pair, or most
recent snapshot if no common found.
*config*;; List configured source/snapshot/target relations.
*source*;; List configured source/snapshot relations.
*volume*;; List configured volume sections.
*target*;; List configured targets.
--
+
Use the '--format' command line option to switch between different
output formats.
*usage* [filter...]::
Print filesystem usage information for all source/target volumes,
optionally filtered by [filter...] arguments (see
<<_filter_statements,FILTER STATEMENTS>> below). Note that the
"free" value is an estimate of the amount of data that can still
be written to the file system.
*origin* <subvolume>::
Print the subvolume origin tree: Shows the parent-child
relationships as well as the received-from information. Use the
'--format' command line option to switch between different output
formats.
*diff* <from> <to>::
List the modified files since generation (transid) of subvolume
<from> in subvolume <to>. Columns:
+
------------
SIZE file was modified for a total of SIZE bytes
COUNT file was modified in COUNT generations
FLAGS "+" file accessed at offset 0 (at least once)
"c" COMPRESS flag is set (at least once)
"i" INLINE flag is set (at least once)
------------
*extents* [diff] <subvolume>... [exclusive <subvolume>...]::
Print accurate disk space usage and diff based on extent data
(FIEMAP ioctl, slow!).
+
--
Subvolumes following the 'exclusive' keyword are added to a separate
set, and additional set-exclusive data is printed at the end of the
list. This gives a hint of how much data will be freed if deleting all
subvolumes in the set. Example:
btrbk extents diff /backup/data.* exclusive /backup/data.2010*
The EXCLUSIVE column shows the set-exclusive data of all other listed
(!) subvolumes (relative complement of block regions). Provided that
all related subvolumes (holding references to extents) are also
listed, this amount of disk space would be freed when deleting the
subvolume.
The DIFF column shows the data added to the previous subvolume
(relative complement of block regions).
If called with the '--related' option, btrbk also lists all related
subvolumes. This is not recommended for backups, as parent-uuid
relations break for received subvolumes as soon as an intermediate
subvolume is deleted.
Note that reading all extents is a disk-intensive task, expect long
execution times and high ram usage. Consider setting 'cache_dir'.
--
*ls* <path>|<url>...::
List all btrfs subvolumes below <path>. Use the '--format' command
line option to switch between different output formats. See
lsbtr(1).
*config* print|print-all::
Prints the parsed configuration file.
FILTER STATEMENTS
-----------------
Filter arguments are accepted in form:
<group-name>::
Matches the 'group' configuration option of 'volume', 'subvolume'
or 'target' sections.
<hostname>[:<port>]::
Matches the 'hostname' portion from '<url>' of 'volume' or
'target' sections.
<directory>|<url>::
Matches 'volume', 'subvolume' or 'target' sections by either
relative or absolute path (if starting with "/" or "ssh://" or
"<hostname>:/"), accepting wildcard character "*". Relative paths
are matched against the end of the pathname. Either:
+
--
<volume-directory>::
Matches 'volume' sections.
<volume-directory>/<subvolume-name>::
Matches 'subvolume' sections.
<volume-directory>/<snapshot-dir>/<snapshot-name>::
Matches 'subvolume' sections defining snapshots with the
configured 'snapshot_dir' and 'snapshot_name'.
<target-directory>::
Matches 'target' sections.
<target-directory>/<snapshot-name>::
Matches 'target' sections within 'subvolume' sections defining
snapshots with the configured 'snapshot_name'.
Accepted formats for '<url>' are:
ssh://<hostname>[:<port>]/<directory>
<hostname>:<directory>
--
Note that for *run* and *snapshot* commands, a filter matching a
'target' configuration section also enables snapshot creation of the
surrounding 'subvolume' section. If this is not desired, consider
running *snapshot* and *resume* commands separately.
Filter statements can match multiple times (e.g. on group as well as
host name). In such a case, all matches are processed.
FILES
-----
+/etc/btrbk.conf+::
+/etc/btrbk/btrbk.conf+::
Default configuration file. The file format and configuration
options are described in *btrbk.conf*(5).
EXIT STATUS
-----------
*btrbk* returns the following error codes:
ifndef::backend-docbook,backend-manpage[]
[horizontal]
endif::backend-docbook,backend-manpage[]
0:: No problems occurred.
1:: Generic error code.
2:: Parse error: when parsing command-line options or configuration
file.
3:: Lockfile error: if lockfile is present on startup.
10:: Backup abort: At least one backup task aborted.
255:: Script error.
AVAILABILITY
------------
Please refer to the btrbk project page *<https://digint.ch/btrbk/>*
for further details.
SEE ALSO
--------
*btrbk.conf*(5),
*btrfs*(8)
For more information about btrfs and incremental backups, see the web
site at https://btrfs.wiki.kernel.org/index.php/Incremental_Backup
AUTHOR
------
Axel Burri <axel@tty0.ch>
Reference in New Issue View Git Blame Copy Permalink