MAN page from openSUSE Tumbleweed btrbk-0.32.5-8.43.noarch.rpm

BTRBK

Section: Btrbk Manual (1)
Updated: 2022-10-23
Index

NAME

btrbk - backup tool for btrfs subvolumes

SYNOPSIS

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 ofbtrfs specific capabilities to create atomic snapshots and transferthem incrementally to a target btrfs filesystem. It is able to performbackups from one source to multiple destinations.

For most operations, btrbk requires root privileges to runcorrectly. Alternatively, consider using "btrfs-progs-sudo" or"btrfs-progs-btrbk" backends, both of which allows you to run btrbk asa regular user. Refer to configuration option backend inbtrbk.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 hostrunning btrbk) of the snapshot/backup. The format can be configuredusing the timestamp_format option, refer to btrbk.conf(5) fordetails. If multiple snapshots/backups are created on the samedate/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 witha given initial content of the original subvolume" (showing aparent-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 subvolumecreated 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 thesnapshots and backup subvolumes that would be created/deleted bythe run, snapshot, resume, prune, archive and cleancommands. Use in conjunction with -l debug to see the btrfscommands that would be executed.

--exclude <filter>

: Exclude configured sections matching <filter>. SeeFILTER STATEMENTS below.

-p, --preserve

: Preserve all snapshots and backups. Skips deletion of anysnapshots 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 ifspecified in the configuration file.

--preserve-backups

: Preserve all backups. Skips deletion of any backups, even ifspecified in the configuration file.

--wipe

: Ignore configured snapshot retention policy, delete all but the latestsnapshots instead. All snapshots needed for incremental backup(latest common) are also preserved. Useful if you are getting lowon disk space (ENOSPC).

-v, --verbose

: Increase the logging level, see "--loglevel".

-q, --quiet

: Quiet operation. If set, btrbk does not print the summary afterexecuting the run, snapshot, resume, prune, or archivecommands.

-l, --loglevel <level>

: Set the level of verbosity for the stderr logging. Accepted levelsare: 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", printsspace-separated, quoted key=value pairs (machine readable).
If set to "col:", prints only the <columns> specified (comma-separatedlist). Header lines are ommitted if the "h:" modifier is present.Columns prefixed with "-" are collapsed if empty. Columns postfixedwith ":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 --formatcommand 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>

: Create lockfile <file> on startup; checks lockfile before runningany btrfs commands (using perl "flock"), and exits if the lock isheld by another btrbk instance. 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/orbackups. All actions can operate in dry-run mode (-n, --dry-run).Use the --format command line option to switch between differentoutput formats.

See section RETENTION POLICY in btrbk.conf(5) for information onconfiguring the retention policy.

run [filter...]

Perform snapshot and backup operations as specified in theconfiguration file. If the optional [filter...] arguments arepresent, snapshots and backups are only performed for thesubvolumes/targets matching a filter statement (seeFILTER STATEMENTS below).

Step 0: Read Data

: Read information from the source and target btrfs filesystems inorder to perform sanity checks and identify parent/child andreceived-from relationships.

Step 1: Create Snapshots

: If the checks succeed, btrbk creates snapshots for the sourcesubvolumes specified in the configuration file, according to thesnapshot_create option.

Step 2: Create Backups

: For each specified target, btrbk creates the backups as follows:After comparing the backups to the source snapshots, btrbktransfers all missing snapshots needed to satisfy the configuredtarget retention policy, incrementally from the latest commonparent subvolume found. If no common parent subvolume is found (orif 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 configuredretention policy will be deleted. Note that the latestsnapshot/backup pair are always preserved, regardless of theretention policy.

Step 4: Delete Snapshots

: Unless the -p, --preserve or --preserve-snapshots option is set,snapshots that are not preserved by their configured retentionpolicy will be deleted. Note that the latest snapshot (the onecreated in step 1) as well as the latest snapshot/backup pair arealways preserved, regardless of the retention policy. If anytarget is unreachable or has errors, all snapshots are preservedin order not to break the incremental chain.

dryrun [filter...]

: Don't run any btrfs commands that would alter the filesystem, justshow the snapshots and backup subvolumes that would becreated/deleted by the run command. Use in conjunction with -ldebug to see the btrfs commands that would be executed.

snapshot [filter...]

: Snapshot only: skips backup creation and deletion (steps 2 and3). 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 notaccessible, as it is still required in order to determine the latestsnapshot/backup pair (which is always preserved, regardless of theretention policy).

resume [filter...]

: Resume backups: skips snapshot creation (step 1), transfers anddeletes snapshots/backups in order to satisfy their configuredretention policy. Use in conjunction with -p, --preserve,--preserve-backups, --preserve-snapshots if you want to skipbackup 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 tosatisfy their configured retention policy. Useful for cleaning thedisk after changing the retention policy. Use in conjunction with--preserve-backups, --preserve-snapshots if you want to skipbackup 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 latestsnapshot/backup pair (which is always preserved, regardless of theretention policy).

archive <source> <target> [--raw]

Recursively copy all subvolumes created by btrbk from <source> to<target> directory, optionally rescheduled usingarchive_preserve_* configuration options. Also creates directorytree on <target>. Useful for creating extra archive copies(clones) from your backup disks. Note that you can continue usingbtrbk after swapping your backup disk with the archive disk.

If you want to use nested subvolumes on the target filesystem, youneed 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, seebtrbk.conf(5), TARGET TYPES).

clean [filter...]

: Delete incomplete (garbled) backups. Incomplete backups can beleft behind on network errors or kill signals while a send/receiveoperation 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 andresulting snapshot creation (S+), backup creation (B+), snapshotdeletion (S-), and backup deletion (B-):

Command   Option                 S+ B+ S- B---------------------------------------------run                              x  x  x  xrun       --preserve             x  xrun       --preserve-snapshots   x  x     xrun       --preserve-backups     x  x  xsnapshot                         x     xsnapshot  --preserve             xresume                              x  x  xresume    --preserve                xresume    --preserve-snapshots      x     xresume    --preserve-backups        x  xprune                                  x  xprune     --preserve-snapshots            xprune     --preserve-backups           x

Informative Commands

The following commands are informative only, and will not alter thefile system.

stats [filter...]

: Print statistics of snapshot and backup subvolumes. Optionallyfiltered by [filter...] arguments (see FILTERSTATEMENTS below).

list <subcommand> [filter...]

Print information defined by <subcommand> in a tabularform. Optionally filtered by [filter...] arguments (seeFILTER STATEMENTS below).

Available subcommands (default "all"):

all

: List all snapshots and backups created by btrbk.

snapshots

: List all snapshots created by btrbk.

backups

: List all backups (and correlated snapshots) created bybtrbk.

latest

: List most recent common snapshot/backup pair, or mostrecent 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 differentoutput formats.

usage [filter...]

: Print filesystem usage information for all source/target volumes,optionally filtered by [filter...] arguments (seeFILTER STATEMENTS below). Note that the"free" value is an estimate of the amount of data that can stillbe written to the file system.

origin <subvolume>

: Print the subvolume origin tree: Shows the parent-childrelationships as well as the received-from information. Use the--format command line option to switch between different outputformats.

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 bytesCOUNT  file was modified in COUNT generationsFLAGS  "+"  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 separateset, and additional set-exclusive data is printed at the end of thelist. This gives a hint of how much data will be freed if deleting allsubvolumes 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 thatall related subvolumes (holding references to extents) are alsolisted, this amount of disk space would be freed when deleting thesubvolume.

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 relatedsubvolumes. This is not recommended for backups, as parent-uuidrelations break for received subvolumes as soon as an intermediatesubvolume is deleted.

Note that reading all extents is a disk-intensive task, expect longexecution times and high ram usage. Consider setting cache_dir.

ls <path>|<url>...

: List all btrfs subvolumes below <path>. Use the --format commandline option to switch between different output formats. Seelsbtr(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, subvolumeor target sections.

<hostname>[:<port>]

: Matches the hostname portion from <url> of volume ortarget sections.

Matches volume, subvolume or target sections by eitherrelative or absolute path (if starting with "/" or "ssh://" or"<hostname>:/"), accepting wildcard character "*". Relative pathsare 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 theconfigured snapshot_dir and snapshot_name.

<target-directory>

: Matches target sections.

<target-directory>/<snapshot-name>

: Matches target sections within subvolume sections definingsnapshots 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 atarget configuration section also enables snapshot creation of thesurrounding subvolume section. If this is not desired, considerrunning snapshot and resume commands separately.

Filter statements can match multiple times (e.g. on group as well ashost name). In such a case, all matches are processed.