Provided by: rsbackup_4.0-1ubuntu1_amd64 
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 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 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 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.
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.
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).
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 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, 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 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.
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.
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>
rsbackup(5)