BTRBK(1)			 Btrbk Manual			      BTRBK(1)

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>

Btrbk 0.32.6			  2023-03-25			      BTRBK(1)