Ubuntu Manpage: btrbk - backup tool for btrfs volumes

name
synopsis
description
options
commands
filter statements
files
exit status
availability
see also
author

NAME

       btrbk - backup tool for btrfs volumes

SYNOPSIS

       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]
             <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 target volumes. It is able to perform backups from
       one source to multiple destinations.

       Snapshots as well as backup subvolume names are created in form:

           <snapshot_name>.<timestamp>[_N]

       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 backup,
       starting at 1.

OPTIONS

-h, --help
Prints the synopsis and a list of the commands.

--version
Prints the btrbk version.

-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 and clean commands. Use in conjunction with -l debug to see
the btrfs commands that would be executed.

-c, --config <file>
Read the configuration from <file>.

-p, --preserve
Preserve all backups. Skips deletion of old backups, even if specified in the configuration file.

-r, --resume-only
Resume only. Skips snapshot creation, only resumes missing backups. This only makes sense if the
resume_missing option is set to “yes” in the configuration file.

-v, --verbose
Verbose output. Sets "-l info", and prints detailed scheduler information on "run" and "dryrun"
commands.

-q, --quiet
Quiet operation. If set, btrbk does not print the summary after executing the "run" command.

-l, --loglevel <level>
Set the level of verbosity. Accepted levels are warn, info, debug, and trace.

-t, --table
Print output in table format (shortcut for "--format=table").

--format table|long|raw
Print output in specified format. If set to "raw", prints space-separated key="value" pairs (machine-
readable). Affects output format for run, dryrun, list and tree commands. Useful for further
exporting/scripting.

--progress
Show progress bar on send-receive operation.

COMMANDS

       run [filter...]
           Perform backup operations as specified in the configuration file. If the optional [filter...]
           arguments are present, backups are only performed for the subvolumes/targets matching a FILTER
           STATEMENT (see below).

           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 all the source subvolumes specified in the
           configuration file.

           Then, for each specified target, btrbk creates the backups as follows: If the resume_missing option
           is set (the default), btrbk transfers all missing snapshots needed to satisfy the configured
           target_preserve_{daily,weekly,monthly} retention policy, always incrementally from the latest common
           parent subvolume found. If no common parent subvolume is found, a full backup is created for the
           first transfer. Note that the latest snapshot (the one created in the first step) is always
           transferred, regardless of the retention policy.

           As a last step, unless the -p (preserve backups) option is set, snapshots and backup subvolumes that
           are not preserved by their configured retention policy will be deleted. Note that the latest snapshot
           as well as the latest backup is always preserved, regardless of the retention policy.

           Use the --format command line option to switch between different output formats.

       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.

       stats [filter...]
           Print statistics of snapshot and backup subvolumes. Optionally filtered by [filter...] arguments (see
           FILTER STATEMENTS below).

       list <subcommand> [filter...]
           Print information defined by <subcommand> in a tabular form. Optionally filtered by [filter...]
           arguments (see FILTER STATEMENTS below).

           Available subcommands:

           snapshots  All snapshots (and corresponding backups).
           backups    All backups (and corresponding snapshots).
           latest     Most recent snapshots and backups.
           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...]
           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.

       usage [filter...]
           Print filesystem usage information for all source/target volumes. Optionally filtered by [filter...]
           arguments (see FILTER STATEMENTS below).

       origin <subvolume>
           Print origin information for the given backup subvolume, showing the parent-child relationship as
           well as the received-from information.

       diff <from> <to>
           Print new files since subvolume <from> for subvolume <to>.

       config print|print-all
           Prints the parsed configuration file. Use the --format command line option to switch between
           different output formats.

FILTER STATEMENTS

       Filter arguments are accepted in form:

       [hostname:]<volume-directory>
           Matches all subvolumes and targets of a volume configuration section.

       [hostname:]<volume-directory>/<subvolume-name>
           Matches the specified subvolume and all targets of a subvolume configuration section.

       [hostname:]<target-directory>
           Matches all targets of a target configuration section.

       [hostname:]<target-directory>/<snapshot-name>
           Matches a single target of a target section within a subvolume section with given <snapshot-name>.

       <group-name>
           Matches the group configuration option of a volume, subvolume or target section.

       For convenience, [hostname:] can be specified as either "hostname:" or "ssh://hostname/".

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:

       0   No problems occurred.

       1   Generic error code.

       2   Parse error: when parsing command-line options or configuration file.

       10  Backup abort: At least one backup task aborted.

       255 Script error.

AVAILABILITY

       Please refer to the btrbk project page http://www.digint.ch/btrbk/ for further details.

AUTHOR

       Axel Burri <axel@tty0.ch>