table of contents
- stretch 0.24.0-1
- testing 0.27.1-1
- unstable 0.27.1-1
- experimental 0.28.2-1
btrbk(1) | btrbk(1) |
NAME¶
btrbk - backup tool for btrfs volumesSYNOPSIS¶
btrbk [-h|--help] [--version] [-c|--config <file>] [-n|--dry-run] [-p|--preserve] [-r|--resume-only] [-v|--verbose] [-q|--quiet] [-l|--loglevel <level>] [-t|--table] [--format <output-format>] [--progress] [--print-schedule] <command> [<args>]
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.Snapshots as well as backup subvolume names are created in form:
Where <snapshot-name> is identical to the source subvolume name, unless the configuration option snapshot_name is set. The <timestamp> is either "YYYYMMDD" or "YYYYMMDDThhmm" (dependent of the timestamp_format configuration option), where "YYYY" is the year, "MM" is the month, "DD" is the day, "hh" is the hour and "mm" is the minute of the creation time (local time of the host running btrbk). If multiple snapshots/backups are created on the same date/time, N will be incremented on each snapshot, starting at 1.
OPTIONS¶
-h, --help--version
-n, --dry-run
-c, --config <file>
-p, --preserve
-r, --resume-only
-v, --verbose
-q, --quiet
-l, --loglevel <level>
-t, --table
--format table|long|raw
--progress
--print-schedule
--override <config_option>=<value>
--lockfile <file>
COMMANDS¶
run [filter...]First, btrbk reads information from the source and target btrfs filesystems in order to perform sanity checks and identify parent/child and received-from relationships.
If the checks succeed, btrbk creates snapshots for the source subvolumes specified in the configuration file, according to the snapshot_create option.
Then, 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.
As a last step, unless the -p (--preserve) option is set, snapshots and backup subvolumes that are not preserved by their configured retention policy will be deleted. Note that the latest snapshot (the one created in the first step) as well as the latest snapshot/backup pair are always preserved, regardless of the retention policy.
See section RETENTION POLICY in btrbk.conf(5) for information on configuring the retention policy.
Use the --format command line option to switch between different output formats.
dryrun [filter...]
archive <source> <target> *experimental*
Note that this feature needs a linux kernel >=4.4 to work correctly! Kernels >=4.1 and <4.4 have a bug when re-sending subvolumes (the archived subvolumes will have incorrect received_uuid, see <http://thread.gmane.org/gmane.comp.file-systems.btrfs/48798>), so make sure you run a recent kernel.
Known bugs: 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.
stats [filter...]
list <subcommand> [filter...]
Available subcommands:
- snapshots
- All snapshots (and corresponding backups).
- backups
- All backups (and corresponding snapshots).
- latest
- Most recent common snapshot/backup pair, or most recent snapshot if no common found.
- config
- Configured source/snapshot/target relations.
- source
- Configured source/snapshot relations.
- volume
- Configured volume sections.
- target
- Configured targets.
Use the --format command line option to switch between different output formats.
clean [filter...]
usage [filter...]
origin <subvolume>
diff <from> <to>
config print|print-all
FILTER STATEMENTS¶
Filter arguments are accepted in form:[hostname:]<volume-directory>
[hostname:]<volume-directory>/<subvolume-name>
[hostname:]<target-directory>
[hostname:]<target-directory>/<snapshot-name>
<group-name>
For convenience, [hostname:] can be specified as either "hostname:" or "ssh://hostname/".
FILES¶
/etc/btrbk.conf/etc/btrbk/btrbk.conf
EXIT STATUS¶
btrbk returns the following error codes:- 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 http://digint.ch/btrbk/ for further details.SEE ALSO¶
btrbk.conf(5), btrfs(1)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>2016-11-16 | btrbk v0.24.0 |