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.
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 which to suppress it for a single vol-
ume).
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 which to suppress it for a single vol-
ume).
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.
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
macOS 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.
group GROUP
The concurrency group for this host. The default is the name
from the host stanza. See CONCURRENCY below.
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 enfores 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 decay.pdf <https://www.greenend.org.uk/rjk/rsbackup/decay.pdf> 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. Normally a concurrency group is just a single host, but
the group directive can be used to add multiple hosts to a single group
(for instance, if they share physical hardware).
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 at-
tributes 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>