Provided by: rsbackup_5.1-1_amd64 bug

NAME

       /etc/rsbackup/config - configuration for rsync-based backup utility

DESCRIPTION

       This describes the configuration file syntax for for rsbackup(1).

SYNTAX

   Line Splitting
       Line  are  split  into space-separated words.  To include spaces in a word, quote it using
       "double  quotes".   Quotes  and  backslashes  within  quoted  strings  are  escaped   with
       backslashes (and cannot appear in an unquoted word).

   Comments and Blank Lines
       Anything after the first (unquoted) "#" to appear on a line is ignored.

       Lines with no words on (whether they are completely empty, or contain just spaces, or have
       a "#" before any non-space characters)  are  ignored  (and  do  not  have  to  follow  the
       indentation rules below).

   Directives and Stanzas
       The  first  word  of  a  line  is called a directive.  The remaining words if any form its
       arguments.

       A stanza consists of  a  directive  introducing  the  stanza  followed  by  zero  or  more
       directives  within  the  stanza.   These  must  be indented, consistently, relative to the
       directive that introduced the stanza.

       A configuration file contains global directives (which must not be indented)  and  one  or
       more host stanzas.  Each host stanza contains one or more volume stanzas.

       Global directives may appear after host stanzas (and host directives after volume stanzas)
       provided they are indented correctly.

GLOBAL DIRECTIVES

       Global directives control some general aspect of the program.

       device DEVICE
              Names a device.  This can be used multiple times.   The  store  must  have  a  file
              called  STORE/device-id  which  contains a known device name.  Backups will only be
              made to known devices.

              When a  device  is  lost  or  destroyed,  remove  its  device  entry  and  use  the
              --prune-unknown option to delete records of backups on it.

              Device names may contain letters, digits, dots and underscores.

       include PATH
              Include another file as part of the configuration.  If PATH is a directory then the
              files within it are included (excluding dotfiles, backup and recovery files).

       keep-prune-logs DAYS
              The number of days to keep records of pruned backups for.  The default is 31.

       lock PATH
              Enable locking.  If this directive is present then PATH will be used as a  lockfile
              for operations that change anything (--backup, --prune, etc).

              The lock is made by opening PATH and calling flock(2) on it with LOCK_EX.

       logs PATH
              The   directory   to   store   logfiles   and   backup  records.   The  default  is
              /var/log/backup.

       post-access-hook COMMAND...
              A command to execute after all backup and prune operations.  This is executed  only
              once  per  invocation  of rsbackup.  A backup is still considered to have succeeded
              even if the post-access hook fails (i.e. exits nonzero).  See HOOKS below.

       pre-access-hook COMMAND...
              A command to execute before anything that accesses any backup devices (i.e.  backup
              and  prune  operations).  This is executed only once per invocation of rsbackup and
              if it fails (i.e. exits nonzero) then rsbackup terminates immediately.   See  HOOKS
              below.

       public true|false
              If  true,  backups  are  public.   Normally  backups must only be accessible by the
              calling user.  This option suppresses the check.

       store [--mounted|--no-mounted] PATH
              A path at which a backup device may be mounted.  This can be used multiple times.

              With the --mounted option (which is the default), PATH must be a mount point.  With
              --no-mounted it need not be a mount point.

       store-pattern [-mounted|-nomounted] PATTERN
              A glob(7) pattern matching paths at which a backup device may be mounted.  This can
              be used multiple times.

              See the description of store above for the meanings of the options.

   Report Directives
       These are global directives that affect only the HTML report.

       colors GOOD BAD
              The colors used to represent good states (a  recent  backup)  and  bad  states  (no
              sufficiently recent backup).

              GOOD and BAD are integer values representing RGB triples.  It is most convenient to
              write them in hex, e.g. as 0xRRGGBB.   For  example,  black  is  0x000000,  red  is
              0xFF0000, and so on.

              This directive is deprecated.  Use color-bad and color-good instead.

       color-bad COLOR
              The  color  used  to  represent  bad  states (no sufficiently recent backup) in the
              report.  See below for the interpretation of COLOR.

       color-good COLOR
              The color used to represent good states (a recent backup) in the report.

       report [+] [KEY][:VALUE][?CONDITION] ...
              Defines the report contents.  The arguments to this directive  are  a  sequence  of
              keys, optionally parameterized by a value and/or a condition.

              If  the  first  argument  is  a  +  then  the  arguments  are  added to the current
              configuration; otherwise they replace it.

              The possible keys, with values where appropriate, are:

              generated
                     A timestamp stating when the report was generated.

              history-graph
                     A graphic showing the backups available for each volume.  This only works if
                     rsbackup-graph(1) is installed.

              h1:HEADING

              h2:HEADING

              h3:HEADING
                     Headings at levels 1, 2 and 3.

              logs   A list of logs of failed backups.

              p:PARAGRAPH
                     A paragraph of text.

              prune-logs[:DAYS]
                     A list of logs of pruned backups.

                     DAYS  is  the  number  of  days  of  pruning logs to put in the report.  The
                     default is 3.

              summary
                     A table summarizing the backups available for each volume.

              title:TITLE
                     The document title.

              warnings
                     A list of warning messages.

              If a condition is specified then the key is only used if  the  condition  is  true.
              The possible conditions are:

              warnings
                     True  if  there  are  any  warnings  to display (i.e. if the warnings key is
                     nonempty).

              Within a VALUE the following sequences undergo substitution:

              \CHAR  Replaced with the single character CHAR.

              ${VARIABLE}
                     Replaced with the value of the environment variable VARIABLE, if it is set.

              The following environment variables are set:

              RSBACKUP_CTIME
                     The local date and time in ctime(3) format.

              RSBACKUP_DATE
                     The local date in YYYY-MM-DD format.

              The default is equivalent to:

                     report "title:Backup report (${RSBACKUP_DATE})"
                     report "h1:Backup report (${RSBACKUP_DATE})"
                     report + h2:Warnings?warnings warnings
                     report + "h2:Summary" summary
                     report + history-graph
                     report + h2:Logfiles logs
                     report + "h3:Pruning logs" prune-logs
                     report + "p:Generated ${RSBACKUP_CTIME}"

       report-prune-logs DAYS
              Overrides the number of days of pruning logs to put in the report.

              This directive is deprecated.  Use report instead.

       sendmail PATH
              The path to the executable to use for sending  email.   The  default  is  platform-
              dependent  but typically /usr/sbin/sendmail.  The executable should support the -t,
              -oee, -oi and -odb options.

       stylesheet PATH
              The path to the stylesheet to use in the HTML report.  If this  is  absent  then  a
              built-in default stylesheet is used.

   Graph Directives
       These are global directives that affect the output of rsbackup-graph(1).

       color-graph-background COLOR
              The background color.  See below for the interpretation of COLOR.

       color-graph-foreground COLOR
              The foreground color, i.e. for text.

       color-month-guide COLOR
              The color for the vertical month guides.

       color-host-guide COLOR
              The color for the horizontal guides between hosts.

       color-volume-guide COLOR
              The color for the horizontal guides between volumes.

       device-color-strategy STRATEGY
              The strategy to use for picking device colors.

              A strategy is a name and a sequence of parameters, all of which are optional.

              The possible strategies are:

              equidistant-value HUE SATURATION MINVALUE MAXVALUE
                     Colors are picked with chosen hue and saturation, with values equally spaced
                     within a range.

                     The default hue is 0 and the default saturation is  1.   The  default  value
                     range is from 0 to 1.

              equidistant-hue HUE SATURATION VALUE
                     Colors  are picked with chosen saturation and value and equally spaced hues,
                     starting from HUE.

                     The default starting hue is 0 and the default saturation and value are 1.

              The default strategy is equivalent to:

                     device-color-strategy equidistant-value 120 0.75

       horizontal-padding PIXELS
              The number pixels to place between horizontally adjacent elements.  The default  is
              8.

       vertical-padding PIXELS
              The number pixels to place between vertically adjacent elements.  The default is 2.

       host-name-font FONT
              The  font  description  used  for  host names.  See below for the interpretation of
              FONT.

       volume-name-font FONT
              The font description used for volume names.

       device-name-font FONT
              The font description used for device names.

       time-label-font FONT
              The font description used for time labels.

       graph-layout [+] PART:COLUMN,ROW[:HV] ...
              Defines the graph layout.

              The arguments to this directive are a sequence of graph component specifications of
              the form PART:COLUMN,ROW[:HV], where:

              PART   The name of this component.  The following parts are recognized:

                     host-labels
                            The  host  name  labels for the graph.  This is expected to be in the
                            same row as content.

                     volume-labels
                            The volume name labels for the graph.  This is expected to be in  the
                            same row as content.

                     content
                            The graph content.

                     time-labels
                            The  time  labels  for the graph.  This is expected to be in the same
                            column as content.

                     device-key
                            The key mapping device names to colors.

              COLUMN The column number for this component.  0 is the leftmost column.

              ROW    The row number for this component.  0 is the top row.

              HV     The (optional) justification specification for this component.  H may be one
                     of the following:

                     L      Left justification.

                     C      Centre justification.

                     R      Right justification.

                     V may be one of the following:

                     T      Top justification.

                     C      Centre justification.

                     B      Bottom justification.

              Parts may be repeated or omitted.

              The default layout is equivalent to:

                     graph-layout host-labels:0,0
                     graph-layout + volume-labels:1,0
                     graph-layout + content:2,0
                     graph-layout + time-labels:2,1
                     graph-layout + device-key:2,3:RC

   Colors
       COLOR may be one of the following:

       DECIMAL or 0xRRGGBB
              An  integer  value  representing  an  RGB  triple.   It  is  most convenient to use
              hexadecimal.  For example, black is 0x000000, red is 0xFF0000, and so on.

       rgb RED GREEN BLUE
              Three numbers in the range 0 to 1 representing red, green and blue components.

       hsv HUE SATURATION VALUE
              HUE chooses between different primary colors and mixtures of  them.   0  represents
              red,  120  represents  green and 240 represents blue; intermediate values represent
              mixed hues.

              Normally it would be in the range 0 <= HUE < 360, but values outside this range are
              mapped into it.

              SATURATION  is  a  number in the range 0 to 1 and (roughly) represents how colorful
              the color is.  0 is a shade of grey and 1 is maximally colorful.

              VALUE is a number in the range 0 to 1 and represents the brightness of the color.

              See https://en.wikipedia.org/wiki/HSL_and_HSV for  a  fuller  discussion  of  these
              terms.

   Fonts
       FONT  is  a  Pango font description.  The syntax is "[FAMILY-LIST] [STYLE-OPTIONS] [SIZE]"
       where:

       FAMILY-LIST
              A comma-separate list of font families.  These  necessarily  depend  on  the  fonts
              installed  locally  but  Pango  recognizes monospace, sans and and serif as generic
              family names.

              If you have texttopng(1) then texttopng -l will generate a list of fonts recognized
              by  your  Pango  install.   See   http://www.greenend.org.uk/rjk/sw/texttools/  for
              download.

       STYLE-OPTIONS
              A whitespace-separated list of style, variant, weight, stretch and gravity options.

              The possible style options are roman (the default), oblique and italic.

              The possible variant options are small-caps.

              The possible weight options are thin, ultra-light, light, semi-light, book, regular
              (the default), medium, semi-bold, bold, ultra-bold, heavy and ultra-heavy.

              The  possible  stretch  options  are  ultra-condensed,  condensed,  semi-condensed,
              semi-expanded, expanded and ultra-expanded.

              The possible gravity options are south (the default), north, east and west.

       SIZE   The font size in points, or PIXELSpx for a font size in pixels.

       The details of the syntax are entirely under the control of the Pango  library;  for  full
       details you must consult its documentation or source code.

INHERITABLE DIRECTIVES

       Inheritable directives control an aspect of one or more backups.  They can be specified at
       the global level or in a host or volume stanza (see below).  If one  appears  in  multiple
       places  then  volume  settings  override  host  settings and host settings override global
       settings.

       hook-timeout SECONDS
              How long to wait before concluding a hook has hung, in seconds.  The default is  0,
              which means to wait indefinitely.

       host-check always-up
              Assume that the host is always up.

       host-check ssh
              Check whether the host is up using SSH.  This is the default host check behavior.

       host-check command COMMAND...
              Check  whether the host is up by executing a command.  The name of the host will be
              appended to the command line.  If it exits with status 0 the host is assumed to  be
              up.  If it exits with nonzero status the host is assumed to be down.

       max-age DAYS
              The  maximum  age  of  the  most  recent backup before you feel uncomfortable.  The
              default is 3, meaning that if a volume hasn't been backed up in the last 3 days  it
              will have red ink in the HTML report.

       min-backups COUNT
              The  minimum number of backups for each volume to keep on each store, when pruning.
              The default is 1.

              This directive is deprecated.  Use prune-parameter min-backups instead.

       post-backup-hook COMMAND...
              A command to execute after finishing a backup, or after it  failed.   A  backup  is
              still  considered  to  have  succeeded  even  if  the post-backup hook fails (exits
              nonzero).  See HOOKS below.

       pre-backup-hook COMMAND...
              A command to execute before starting a backup.  If  this  hook  fails  (i.e.  exits
              nonzero) then the backup is not made and the post-backup hook will not be run.  See
              HOOKS below.

              This hook can override the source path for the backup by writing a new source  path
              to standard output.

       prune-age DAYS
              The age at which a backup may be pruned.  The default is 366, meaning a backup will
              never be pruned until it is at least a whole year old.

              This directive is deprecated.  Use prune-parameter prune-age instead.

       prune-parameter NAME VALUE
              Set a parameter for the pruning policy.  See PRUNING below.

       prune-parameter --remove NAME
              Remove a parameter for pruning policy.

       prune-policy NAME
              The pruning policy to use.  See PRUNING below.

       rsync-timeout SECONDS
              How long to wait before concluding rsync has hung, in seconds.  The default  is  0,
              which means to wait indefinitely.

       rsync-command COMMAND
              The command to execute to make a backup.  The default is rsync.

       rsync-base-options OPTIONS ...
              The  options  to  supply  to  the rsync command.  The default is --archive --sparse
              --numeric-ids --compress --fuzzy --hard-links --delete.

       rsync-extra-options OPTIONS ...
              Additional options to supply to the rsync command.  The default is --xattrs --acls.

              See PLATFORMS for how  to  set  this  option  when  backing  up  macOS  or  Windows
              platforms.

       ssh-timeout SECONDS
              How long to wait before concluding a host is down, in seconds.  The default is 60.

HOST DIRECTIVES

       A host stanza is started by a host directive.

       host HOST
              Introduce a host stanza.  The name is used for the backup directory for this host.

       The following directives, and volume stanzas (see below), can appear in a host stanza:

       always-up true|false
              If  true, the host is expected to always be available.  If it is not then a warning
              will be issued when making a backup if it is not.  Failed attempts to make a backup
              will  also  be recorded as failures for always-up hosts (normally hosts that cannot
              be reached are silently skipped).

              This directive is deprecated.  Use host-check always-up instead.

       devices PATTERN
              A glob(3) pattern restricting the devices that this host will be backed up to.

              Note that only backup creation honors this restriction.  Pruning  and  retiring  do
              not.

       hostname HOSTNAME
              The SSH hostname for this host.  The default is the name from the host stanza.

              The  hostname  localhost is treated specially: it is assumed to always be identical
              to the local system, so files will be read from the local filesystem.

       priority INTEGER
              The priority of this host.  Hosts are backed up in descending priority order.   The
              default priority is 0.

       user USERNAME
              The SSH username for this host.  The default is not to supply a username.

       In  addition,  inheritable  directives  can  appear  in  a  host  stanza, and override any
       appearance of them at the global level.

       Conventionally the contents of a host stanza are indented.

       Remote hosts are accessed by SSH.  The user rsbackup runs as must be able  to  connect  to
       the  remote  host (and without a password being entered if it is to be run from a cron job
       or similar).

VOLUME DIRECTIVES

       A volume stanza is started by a volume directive.   It  can  only  appear  within  a  host
       stanza.

       volume VOLUME PATH
              Introduce  a  volume  stanza.   The  name is used for the backup directory for this
              volume.  The path is the absolute path on the host.

       The following directives can appear in a volume stanza:

       check-file PATH
              Checks that PATH exists before backing up  the  volume.   PATH  may  be  either  an
              absolute  path  or  a  relative  path  (to the root of the volume).  It need not be
              inside the volume though the usual use would be to check for a file which is always
              present there.

              This  check is done before executing the pre-backup-hook, so it applies to the real
              path to the volume, not the rewritten path.

       check-mounted true|false
              If true, checks that the volume's path is a  mount  point  before  backing  up  the
              volume.

              This  check is done before executing the pre-backup-hook, so it applies to the real
              path to the volume, not the rewritten path.

              Note that if multiple check- options are used, all checks must pass for the  volume
              to be backed up.

       exclude PATTERN
              An exclusion for this volume.  The pattern is passed to the rsync --exclude option.
              This directive may appear multiple times per volume.

              See the rsync man page for full details.

       traverse true|false
              If true, traverse  mount  points.   This  suppresses  the  rsync  --one-file-system
              option.

       In  addition,  inheritable  directives  can  appear  in  a volume stanza, and override any
       appearance of them at the host or global level.

       Conventionally the contents of a volume stanza are indented.

PRUNING

       This is process of removing old backups (using the --prune option).   The  pruning  policy
       used  to  determine  which  backups  to  remove  is  set with the inheritable prune-policy
       directive, and parameters to the policy set via the prune-parameter directive.

       The available policies are listed below.  The default policy is age.

   age
       This policy deletes backups older than a minimum age, provided a minimum number of backups
       on a device remain available.  The following pruning parameters are supported:

       min-backups
              The  minimum  number  of  backups of the volume to maintain on the device.  Pruning
              will never cause the number of backups to fall below this value.  The default  (and
              minimum) is 1.

       prune-age
              The age after backups become eligible for pruning, in days.  Only backups more than
              this many days old will be pruned.  The default is 366 and the minimum is 1.

       For backwards compatibility, these values can also be set using the directives of the same
       name.  This will be disabled in a future version.

   decay
       This policy thins out backups older than a minimum age, using a configurable decay pattern
       that arranges to keep a declining number of  backups  with  age.   The  following  pruning
       parameters are supported:

       decay-start
              The age after backups become eligible for pruning, in days.  Only backups more than
              this many days old will be pruned.  The default is 1 and the minimum is 1.

       decay-limit
              The age after which backups are always pruned, in days.  Backups  older  than  this
              will  always  be  pruned unless this would leave no backups at all.  The default is
              366 and the minimum is 1.

       decay-scale
              The scale at which the decay window is expanded.  The default is 2 and the  minimum
              is 2.

       decay-window
              The size of the decay window.  The default is 1 and the minimum is 1.

   exec
       This  policy  executes a subprogram with parameters and additional information supplied in
       the environment.

       The following parameters are supported:

       path   The path to the subprogram to execute.

       Any additional parameters are  supplied  to  the  subprogram  via  environment  variables,
       prefixed with PRUNE_.  Additionally the following environment variables are set:

       PRUNE_DEVICE
              The name of the device containing the backup.

       PRUNE_HOST
              The name of the host.

       PRUNE_ONDEVICE
              The  list  of  backups  on the device, by age in days.  This list excludes any that
              have already been scheduled for pruning.

       PRUNE_TOTAL
              The total number of backups of this volume on any device.  Note that  it  does  not
              include  backups  on  other  devices  that  have  just been selected for pruning by
              another call to the subprogram.

       PRUNE_VOLUME
              The name of the volume.

       These environment variables all override any parameters with clashing names.

       The output should be a list of backups to prune, one per line (in any order).   Each  line
       should  contain the age in days of the backup to prune (i.e. the same value as appeared in
       PRUNE_ONDEVICE), followed by a colon, followed by the reason that this  backup  is  to  be
       pruned.

       As  a  convenience,  if the argument to prune-policy starts with / then the exec policy is
       chosen with the policy name as the path parameter.

   never
       This policy never deletes any backups.

HOOKS

       A hook is a command executed by rsbackup just before  or  just  after  some  action.   The
       command is passed directly to execvp(3); to use a shell command, therefore, either wrap it
       in a script or invoke the shell with the -c option.

       All hooks are run in --dry-run mode.  Hook scripts must honor RSBACKUP_ACT which  will  be
       set to false in this mode and true otherwise.

   Access Hooks
       Access  hooks  are  executed  (once) before doing anything that will access backup devices
       (even just to read them).

       The following environment variables are set when an access hook is executed:

       RSBACKUP_ACT
              Set to false in --dry-run mode and true otherwise.

       RSBACKUP_DEVICES
              A space-separated list of known device names.

       RSBACKUP_HOOK
              The name of the hook (i.e. pre-access-hook, etc).  This allows a single hook script
              to serve as the implementation for multiple hooks.

   Backup Hooks
       Backup  hooks  are executed just before or just after a backup is made.  Possible uses for
       backup hooks include snapshotting volumes or mounting volumes.

       The following environment variables are set when a backup hook is executed:

       RSBACKUP_ACT
              Set to false in --dry-run mode and true otherwise.

       RSBACKUP_DEVICE
              The target device name for the backup.

              Note that this may be removed in a future version.

       RSBACKUP_HOOK
              The name of the hook (i.e. pre-backup-hook, etc).  This allows a single hook script
              to serve as the implementation for multiple hooks.

       RSBACKUP_HOST
              The name of the host.

       RSBACKUP_SSH_HOSTNAME
              The SSH hostname of the host.

              Recall  that  rsbackup  treats  the hostname localhost specially.  If the hook also
              needs to do so then it must duplicate this logic.

       RSBACKUP_SSH_TARGET
              The SSH hostname and username combined for passing to ssh(1).

              This will be username@hostname or just hostname depending on whether a SSH username
              was set.

       RSBACKUP_SSH_USERNAME
              The  SSH  username of the host.  If no SSH username was set, this variable will not
              be set.

       RSBACKUP_STATUS
              (Only for post-backup-hook).  Either ok or failed.

       RSBACKUP_STORE
              The path to the store directory where the device is mounted.

       RSBACKUP_VOLUME
              The name of the volume.

       RSBACKUP_VOLUME_PATH
              The path to the volume.

       The error output from backup hooks is stored in the same backup record as the output  from
       rsync.

       The exit status of the pre-backup-hook is interpreted as follows:

       0      The hook succeeded.  The backup will be attempted.

       75     The  volume  is  temporarily  unavailable.  The backup will not be attempted, as if
              check-file or check-mounted had failed.

       anything else
              Something went wrong.  The backup will be treated as failed,  as  if  it  had  been
              attempted and rsync had failed.

       NOTE:  The  current behavior is that the pre/post backup hooks are run separately for each
       backup.  In a future version, they may be run only once for all backups of a given volume,
       in which case RSBACKUP_DEVICE will no longer be set.

       See  rsbackup-snapshot-hook(1)  for  a hook program that can be used to back up from Linux
       LVM snapshots.

PLATFORMS

   macOS
       Apple's rsync has a nonstandard option to enable backup of extended attributes.  For local
       backups you can configure rsbackup to use it with a host-level directive:

       rsync-extra-options --extended-attributes

       If  backing  up  a  macOS  host  from  a host with a modern rsync, or vice versa, however,
       extended attributes and ACLs cannot be backed up at all.  In that case the affected  hosts
       must disable backup attribute and ACL backup as follows:

       rsync-extra-options

       If an up-to-date rsync is used on macOS hosts, it can be left at the default.

   Windows
       rsbackup does not run on Windows.  However, it may be used to back up Windows filesystems.
       In this case it can happen that the attributes in the Windows filesystem do not fit in the
       backup filesystem; if this happens you may see errors like this:

       rsync: rsync_xal_set: lsetxattr(""/backup7/host/volume/2018-02-04/path/to/file"","attrname") failed: No space left on device (28)
       rsync error: some files/attrs were not transferred (see previous errors) (code 23) at main.c(1668) [generator=3.1.2]

       In that case the affected volumes must disable attribute backup and ACL backup as follows:

       rsync-extra-options

SEE ALSO

       rsbackup(1),         rsbackup-graph(1),        rsbackup.cron(1),        rsbackup-mount(1),
       rsbackup-snapshot-hook(1), rsync(1), rsbackup(5)

AUTHOR

       Richard Kettlewell <rjk@greenend.org.uk>

                                                                                      rsbackup(5)