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

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

CONFIGURATION FILE
       The  configuration file contains global directives and a series of host
       stanzas.  Each host stanze in turn contains host directives and  volume
       stanzas.   Although  it  is  not enforced it is suggested that host and
       volume stanzas are indented.

       Comments are introduced by an initial "#".

       Command arguments may be quoted, using  "double  quotes".   Quotes  and
       backslashes within quoted strings are escaped with backslashes.

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  dot-
              files, 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 PATH
              A path at which a backup device may be  mounted.   This  can  be
              used multiple times.

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

   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  vol-
                     ume.

              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 VARI-
                     ABLE, 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  ele-
              ments.  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 compo-
              nent specifications of the form PART:COLUMN,ROW[:HV], where:

              PART   The name of this component.  The following parts are rec-
                     ognized:

                     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 com-
                     ponent.  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  conve-
              nient  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)  repre-
              sents  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 bright-
              ness of the color.

              See  https://en.wikipedia.org/wiki/HSL_and_HSV for a fuller dis-
              cussion 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 over-
       ride 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.

       max-age DAYS
              The maximum age of the most recent backup before you feel uncom-
              fortable.  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.

       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 direc-
              tory 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).

       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.

       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 pol-
       icy 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  mini-
       mum  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 ver-
       sion.

   decay
       This policy thins out backups older than a minimum age, using a config-
       urable  decay pattern that arranges to keep a declining number of back-
       ups 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 infor-
       mation 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 environ-
       ment variables, prefixed with PRUNE_.  Additionally the following envi-
       ronment 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,  and
              includes  the  backup  under  consideration  (i.e.  the value of
              BACKUP_AGE will appear in this list).

       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 other-
       wise.

   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 exe-
       cuted:

       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.

       The following environment variables are set when a backup hook is  exe-
       cuted:

       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.

       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.

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>