Provided by: btrbk_0.22.2-1_all bug

NAME

       btrbk.conf - btrbk configuration file

SYNOPSIS

       /etc/btrbk.conf
       /etc/btrbk/btrbk.conf

DESCRIPTION

       The btrbk configuration file specifies which btrfs subvolumes on the filesystem are to be
       processed, what target subvolumes should be used to create the backups, and where the
       snapshots should be generated. The retention policy, as well as most other options can be
       defined either globally or within a section.

       The options specified always apply to the last section encountered, superseding the values
       set in upper-level sections. This means that global options must be set before any
       sections are defined.

SECTIONS

       volume  <volume-directory>|<url>
           Directory of a btrfs volume containing the source subvolume(s) to be backed up.
           <volume-directory> must be an absolute path and point to a btrfs volume (or
           subvolume). Usually the mount point of a btrfs filesystem mounted with the subvolid=0
           option.

       subvolume  <subvolume-name>
           Subvolume to be backed up, relative to the <volume-directory> specified in the volume
           section. Multiple subvolume sections are allowed within volume sections.

       target  <type> <target-directory>|<url>
           Target type and directory where the backup subvolumes are to be created. See the
           TARGET TYPES section for supported <type>. Multiple target sections are allowed within
           subvolume sections.

       For the volume and target sections, you can specify a ssh-url instead of a local
       directory. The syntax for <url> is:

           ssh://host.xz/path/to/volume

       Note that btrfs is very picky on file names (mainly for security reasons), only the
       characters [0-9] [a-z] [A-Z] and "._+-@" are allowed.

OPTIONS

       transaction_log  <file>
           If set, all transactions (snapshot create, subvolume send-receive, subvolume delete)
           as well as abort messages are logged to <file>, in a space-separated table format.

       timestamp_format  short|long
           Timestamp format used as postfix for new snapshot subvolume names.  Defaults to
           “short”.

           short  YYYYMMDD[_N]  (e.g. "20150825", "20150825_1")

           long   YYYYMMDD<T>hhmm[_N]  (e.g. "20150825T1531")

           Note that a postfix "_N" is only appended to the timestamp if a snapshot/backup
           already exists with the timestamp of current date/time.

       snapshot_dir  <directory>
           Directory in which the btrfs snapshots are created, relative to <volume-directory> of
           the volume section. Note that btrbk does not autmatically create this directory, and
           the snapshot creation will fail if it is not present.

       snapshot_name <basename>
           Base name of the created snapshot (and backup). This option is only valid in the
           subvolume section. Defaults to <subvolume-name>.

       snapshot_create  always|ondemand|onchange|no
           If set to “ondemand”, snapshots are only created if the target subvolume is reachable
           (useful if you are tight on disk space and you only need btrbk for backups to an
           external disk which is not always connected).  If set to “onchange”, snapshots are
           only created if the source subvolume has changed since the last snapshot (more
           precisely: if the btrfs generation has been increased since the last snapshot). If set
           to “always”, snapshots are always created. If set to “no”, the snapshots are never
           created (useful in conjunction with the resume_missing option if another instance of
           btrbk is taking care of snapshot creation). Defaults to “always”.

       incremental  yes|no|strict
           If set, incremental backups are created. If set to “strict”, non-incremental (initial)
           backups are never created. Defaults to “yes”.

       resume_missing  yes|no
           If set, the backups in the target directory are compared to the source snapshots, and
           missing backups are created if needed (complying to the target preserve matrix).
           Defaults to “yes”.

       target_preserve_daily  all|<number>
           How many days of backups should be preserved. Defaults to “all”.

       target_preserve_weekly  all|<number>
           Defines for how many weeks back weekly backups should be preserved. Every backup
           created at preserve_day_of_week (or the next backup in this week if none was made on
           the exact day) is considered as a weekly backup. Defaults to “0”.

       target_preserve_monthly  all|<number>
           Defines for how many months back monthly backups should be preserved. Every last
           weekly backup in a month is considered a monthly backup. Defaults to “all”.

       snapshot_preserve_daily
       snapshot_preserve_weekly
       snapshot_preserve_monthly
           Defines retention policy for the snapshots, with same semantics as the
           target_preserve_* options.

       preserve_day_of_week  monday|tuesday|...|sunday
           Defines on what day a backup/snapshot is considered as a weekly backup. Defaults to
           “sunday”.

       group  <group-name>[,<group-name>]...
           Add the current section (volume, subvolume or target) to a user-defined group, which
           can be used as filter for several btrbk commands.

       ssh_identity  <file>
           Absolute path to a ssh identity file (private key). Note that if the private key is
           password protected, btrbk will prompt for user input, which is usually not desired.

       ssh_user  <username>
           Remote username for ssh. Defaults to “root”. Note that you will have to make sure that
           the remote user is able to run /sbin/btrfs (which needs root privileges).

       ssh_port  <port>
           Port to connect to on the remote host. Defaults to “default” (the port specified in
           ssh_config, which defaults to 22).

       ssh_compression  yes|no
           Enables or disables the compression of ssh connections. Defaults to “no”.

       ssh_cipher_spec  <cipher_spec>
           Selects the cipher specification for encrypting the session (comma-separated list of
           ciphers in order of preference). See the "-c cipher_spec" option in ssh(1) for more
           information. Defaults to “default” (the ciphers specified in ssh_config).

       btrfs_commit_delete  after|each|no
           If set, make sure the deletion of snapshot and backup subvolumes are committed to disk
           when btrbk terminates. Defaults to “no”.

       btrfs_progs_compat  yes|no *experimental*
           Enable compatibility mode for btrfs-progs < 3.17 (btrfs --version). This option can be
           set either globally or within a target section.  If enabled, the latest common
           snapshots are determined by subvolume names instead of received_uuid, which can lead
           to false guesses if the snapshot or target subvolumes are manipulated by hand (moved,
           deleted).

       Lines that contain a hash character (#) in the first column are treated as comments.

TARGET TYPES

       send-receive
           Backup to a btrfs filesystem, using "btrfs send/receive". This is the recommended
           (standard) target type. The <target-directory> must be an absolute path and point to a
           btrfs volume (or subvolume). See btrfs-send(8), btrfs-receive(8).

       raw  *experimental*
           Backup to a raw (filesystem independent) file from the output of btrfs-send(8), with
           optional compression and encryption.

           Note that the target preserve mechanism is currently disabled for raw backups (btrbk
           does not delete any raw files)!

           Additional options for raw targets:

               raw_target_compress  gzip|bzip2|xz|no
               raw_target_compress_level  default|<number>
               raw_target_compress_threads  default|<number>
               raw_target_encrypt  gpg|no
               gpg_keyring  <file>
               gpg_recipient  <name>

           Target file name syntax:

               <snapshot-name>--<received_uuid>[@<parent_uuid>].btrfs[.gz|.bz2|.xz][.gpg]

           The <parent_uuid> is only set on incremental backups, and points to the
           <received_uuid> of the previous backup in a incremental backup chain.

           For incremental backups ("incremental yes"), please note that:

           1.  As soon as a single incremental backup file is lost or corrupted, all later
               incremental backups become invalid, as there is no common parent for the
               subsequent incremental images anymore. This might be a good compromise for a
               vacation backup plan, but for the long term make sure that a non-incremental
               backup is triggered from time to time.

           2.  There is currently no support for rotation of incremental backups: if incremental
               is set, a full backup must be triggered manually from time to time in order to be
               able to delete old backups.

AVAILABILITY

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

SEE ALSO

       btrbk(1)

AUTHOR

       Axel Burri <axel@tty0.ch>