Provided by: btrbk_0.32.5-1_all bug

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 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 below.

       -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>
           Create lockfile <file> on startup; checks lockfile before running any btrfs commands
           (using perl "flock"), and exits if the lock is held 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/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 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-):

           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

   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 below).

       list <subcommand> [filter...]
           Print information defined by <subcommand> in a tabular form. Optionally filtered by
           [filter...] arguments (see FILTER 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 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 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:

       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