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  in-
       dented) 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.

   Time Intervals
       A time interval, denoted INTERVAL below, can be either a  raw  integer,
       or  an  integer  with the suffix "s", "m", "h" or "d" for seconds, min-
       utes, hours or days respectively.

       If there is no suffix then the interpretation is contextual.  This  be-
       havior is deprecated; suffixes will become mandatory in future.

GLOBAL DIRECTIVES
       Global directives control some general aspect of the program.

       database PATH
              The  path to the backup database.  By default this is LOGS/back-
              ups.db where LOGS is controlled by the logs directive below.

       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 INTERVAL
              The  time period to keep records of pruned backups for.  The de-
              fault is 31 days.

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

       prune-timeout INTERVAL
              The maximum amount of time to spend pruning, in a single invoca-
              tion.  0 means that there is no limit (which is the default).

              Note that, if this is directive is used, prune operations timing
              out are considered to be normal behavior, and  the  exit  status
              will  be  0.   Most  of the diagnostics relating to timeouts are
              suppressed unless the -v option is used.

       public true|false
              If true, backups are public.  Normally backups must only be  ac-
              cessible  by  the  calling  user.  This directive 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 op-
              tions.

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

       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}"

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

       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  rs-
       backup-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 in-
              terpretation 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  ex-
                            pected to be in the same row as content.

                     volume-labels
                            The volume name labels for the graph.  This is ex-
                            pected 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  de-
              pend  on  the fonts installed locally but Pango recognizes mono-
              space, sans and and serif as generic family names.

              To get a list of Pango fonts:

                  rsbackup-graph --fonts

       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.

       backup-parameter NAME VALUE
              Set a parameter for the backup policy.  See BACKUP POLICIES  be-
              low.

       backup-parameter --remove NAME
              Remove  a  parameter for the backup policy.  See BACKUP POLICIES
              below.

       backup-policy NAME
              The backup policy to use.  See BACKUP POLICIES below.

       backup-time EARLIEST-LATEST
              Set the time window within a day during  which  backups  may  be
              initiated.   EARLIEST  and  LATEST  take the form HOUR:MINUTE or
              HOUR:MINUTE:SECOND.

              This directive only affects backup creation, and only applies if
              no host/volume selectors appear on the command line.

       group GROUP
              The concurrency group for this host or group.  The default for a
              host is the name from the host stanza.  See CONCURRENCY below.

       hook-timeout INTERVAL
              How long to wait before concluding a hook has hung.  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 INTERVAL
              The maximum age of the most recent backup before you feel uncom-
              fortable.  The default is 3  days,  meaning  that  if  a  volume
              hasn't been backed up in the last 3 days it will have red ink in
              the HTML report.

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

              The hook can be suppressed with an empty COMMAND  (e.g.  if  you
              have a global hook and wish to suppress it for a single volume).

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

              The  hook  can  be suppressed with an empty COMMAND (e.g. if you
              have a global hook and wish to suppress it for a single volume).

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

       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.

       backup-job-timeout INTERVAL
              How long to wait before concluding rsync has hung.  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 --stats --no-human-readable.

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

              See  PLATFORMS for how to use this directive when backing up ma-
              cOS or Windows platforms.

       rsync-io-timeout INTERVAL
              The I/O timeout (passed as --timeout) to rsync.  The default  is
              0, meaning no timeout.

       rsync-link-dest true|false
              If  true,  use rsync's --link-dest option to save space in back-
              ups.  The default is true.

       rsync-remote COMMAND
              If nonempty, passed to rsync as the --rsync-path option.

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

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:

       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.

       The contents of a host stanza must be indented consistently relative to
       the host directive that introduces it.

       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  en-
       tered 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  di-
              rectory  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-volume-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-volume-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.

       The  contents of a volume stanza must be indented consistently relative
       to the volume directive that introduces it.

BACKUP POLICIES
       Backup policies determine when a backup is made.  The  available  poli-
       cies are listed below.  The default policy is daily.

   always
       This policy creates a backup at every opportunity.

   daily
       This  policy creates at most one backup per calendar day, as understood
       in local time.

   interval
       This policy enforces a minimum interval between backups.  The following
       backup parameters are supported:

       min-interval INTERVAL
              The minimum interval between backups.

       The --force option can be used to override backup policies, forcing all
       selected volumes to be backed up unconditionally.

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 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 INTERVAL
              The age after backups become eligible for pruning.  Only backups
              more than this many days old will be pruned.  The default is 366
              days and the minimum is 1 day.

       For backwards compatibility, these values can also be set using the di-
       rectives 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 config-
       urable decay pattern that arranges to keep a declining number of  back-
       ups with age.

       The  idea  is  that backup history is partitioned into a series of win-
       dows.  Each window is a fixed multiple of the size of the previous one.
       The pruning policy arranges that only one backup (per device)  is  pre-
       served within each window.

       For  example, with the default configuration, the first window is 1 day
       long and will contain one backup.  The second window is two  days  long
       and  again,  only  contains  one backup.  The third window is four days
       long, and so on.

       The effect is that the density of backups  over  time  decays  exponen-
       tially.

       See ]8;;https://www.greenend.org.uk/rjk/rsbackup/decay.pdf\decay.pdf]8;;\ for more information.

       The following pruning parameters are supported:

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

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

       decay-scale SCALE
              The scale at which the decay window is expanded.  The default is
              2 and the (exclusive) minimum is 1.

       decay-window INTERVAL
              The size of the decay window.  The default is 1 day and the min-
              imum is 1 day.

   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 timestamp.  This list  ex-
              cludes 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 timestamp 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  RS-
       BACKUP_ACT which will be set to false in this mode and true otherwise.

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

       The  following environment variables are set when a device 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-device-hook, etc).  This allows a
              single hook script to serve as the implementation  for  multiple
              hooks.

       Device hooks used to be called access hooks.

   Volume Hooks
       Pre-volume  hooks  are executed before all the backups of a volume, and
       post-volume hooks after all backups of the volume.  Possible  uses  for
       volume hooks include snapshotting volumes or mounting volumes.

       When a volume hook is executed, the environment variables listed in EN-
       VIRONMENT below are set, along with the following:

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

       The exit status of the pre-volume-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.

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

       Volume hooks used to be called backup hooks.

ENVIRONMENT
       When  a hook or rsync are executed, the following environment variables
       are set:

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

       RSBACKUP_HOST
              The name of the host.

       RSBACKUP_GROUP
              The name of the concurrency group.  See the group directive.

       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_VOLUME
              The name of the volume.

       RSBACKUP_VOLUME_PATH
              The path to the volume.

CONCURRENCY
       Any given device only gets used for one thing at a time; it will  never
       happen that two backups, or two prunes, access the same device.

       No  concurrency  group will ever have more than one backup made from it
       any a time.  By default a concurrency group is just a single host,  but
       this can be changed in two ways:

       +o      At  the  host  level the group directive can put the host into a
              different concurrency group.  For example, this  might  be  used
              for  a  collection  of hosts that shared the same physical hard-
              ware.

       +o      At the volume level the group directive can put the volume  into
              a  different  concurrency group.  For example this might be used
              to group volumes in line with their underlying physical storage,
              with one concurrency group per physical disk.

       No two hooks will be executed concurrently, even if they apply to  dif-
       ferent  concurrency  groups and different devices.  However, a hook may
       execute while a backup (for a different concurrency group and a differ-
       ent device) is executing.

NOTES
   Resource Control
       Large backup jobs can  have  unreasonable  impacts  on  kernel  memory,
       evicting  applications  and cache data by the gigabyte just for single-
       use copies of backup data.

       On Linux this problem can be addressed with with the memory cgroup con-
       troller.

       First, a slice is created on each host (both the back server and client
       machines):

           [Unit]
           Description=Memory-bound slice for rsbackup
           Before=slices.target

           [Slice]
           MemoryAccounting=true
           MemoryHigh=128M
           MemoryMax=256M

       Second, rsbackup is run with a memory use limit:

           systemd-run --quiet --pipe --slice membound rsbackup --backup

       If you are using the Debian cron job then this  can  be  configured  in
       /etc/rsbackup/defaults:

           nicely="systemd-run --quiet --pipe --slice membound"

       Finally,  to control resource use on client machines, add the following
       to their host sections:

           rsync-remote "systemd-run --quiet --pipe --slice membound rsync"

       See also: systemd-run(1), systemctl(1),  systemd.slice(5),  systemd.re-
       source-control(5), rsbackup.cron(1).

   macOS
       Apple's  rsync  does not have the --open-noatime option, and has a non-
       standard option to enable backup of extended attributes.

       For local backups you can configure rsbackup to backup extended attrib-
       utes 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 --open-noatime

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>