.TH rsbackup 5
.\" Copyright (c) 2011, 2012, 2014-18 Richard Kettlewell
.\"
.\" This program is free software: you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation, either version 3 of the License, or
.\" (at your option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with this program.  If not, see <http://www.gnu.org/licenses/>.
.SH NAME
/etc/rsbackup/config \- configuration for rsync-based backup utility
.SH DESCRIPTION
This describes the configuration file syntax for for \fBrsbackup\fR(1).
.SH "SYNTAX"
.SS "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).
.SS "Comments and Blank Lines"
Anything after the first (unquoted) "#" to appear on a line is
ignored.
.PP
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).
.SS "Directives and Stanzas"
The first word of a line is called a directive.
The remaining words if any form its arguments.
.PP
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.
.PP
A configuration file contains global directives (which must not be
indented) and one or more host stanzas.
Each host stanza contains one or more volume stanzas.
.PP
Global directives may appear after host stanzas (and host directives
after volume stanzas) provided they are indented correctly.
.SH "GLOBAL DIRECTIVES"
Global directives control some general aspect of the program.
.TP
.B device \fIDEVICE\fR
Names a device.
This can be used multiple times.
The store must have a file called \fISTORE\fB/device\-id\fR which
contains a known device name.
Backups will only be
made to known devices.
.IP
When a device is lost or destroyed, remove its device entry and use the
\-\-prune\-unknown option to delete records of backups on it.
.IP
Device names may contain letters, digits, dots and underscores.
.TP
.B include \fIPATH\fR
Include another file as part of the configuration.
If \fIPATH\fR is a directory then the files within it are included
(excluding dotfiles, backup and recovery files).
.TP
.B keep\-prune\-logs \fIDAYS\fR
The number of days to keep records of pruned backups for.
The default is 31.
.TP
.B lock \fIPATH\fR
Enable locking.
If this directive is present then \fIPATH\fR will be used as a lockfile
for operations that change anything (\-\-backup, \-\-prune, etc).
.IP
The lock is made by opening \fIPATH\fR and calling \fBflock\fR(2) on
it with \fBLOCK_EX\fR.
.TP
.B logs \fIPATH\fR
The directory to store logfiles and backup records.
The default is \fI/var/log/backup\fR.
.TP
.B post\-access\-hook \fICOMMAND\fR...
A command to execute after all backup and prune operations.
This is executed only once per invocation of \fBrsbackup\fR.
A backup is still considered to have succeeded even if the post-access
hook fails (i.e. exits nonzero).
See \fBHOOKS\fR below.
.TP
.B pre\-access\-hook \fICOMMAND\fR...
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 \fBrsbackup\fR and if it
fails (i.e. exits nonzero) then \fBrsbackup\fR terminates immediately.
See \fBHOOKS\fR below.
.TP
.B public true\fR|\fBfalse
If true, backups are public.
Normally backups must only be accessible by the calling user.
This option suppresses the check.
.TP
.B store \fR[\fB--mounted|--no-mounted\fR] \fIPATH\fR
A path at which a backup device may be mounted.
This can be used multiple times.
.IP
With the \fB--mounted\fR option (which is the default),
\fIPATH\fR must be a mount point.
With \fB--no-mounted\fR it need not be a mount point.
.TP
.B store\-pattern \fR[\fB-mounted|-nomounted\fR] \fIPATTERN\fR
A \fBglob\fR(7) pattern matching paths at which a backup device may be
mounted.
This can be used multiple times.
.IP
See the description of \fBstore\fR above for the meanings of the options.
.SS "Report Directives"
These are global directives that affect only the HTML report.
.TP
.B colors \fIGOOD \fIBAD
The colors used to represent good states (a recent backup) and bad
states (no sufficiently recent backup).
.IP
\fIGOOD\fR and \fIBAD\fR are integer values representing RGB triples.
It is most convenient to write them in hex, e.g. as \fB0x\fIRRGGBB\fR.
For example, black is \fB0x000000\fR, red is \fB0xFF0000\fR, and so
on.
.IP
This directive is deprecated.
Use \fBcolor\-bad\fR and \fBcolor\-good\fR instead.
.TP
.B color\-bad \fICOLOR
The color used to represent bad states (no sufficiently recent backup)
in the report.
See below for the interpretation of \fICOLOR\fR.
.TP
.B color\-good \fICOLOR
The color used to represent good states (a recent backup) in the report.
.TP
.B report \fR[\fB+\fR] \fR[\fIKEY\fR][\fB:\fIVALUE\fR][\fB?\fICONDITION\fR] ...
Defines the report contents.
The arguments to this directive are a sequence of keys, optionally parameterized by a value and/or a condition.
.IP
If the first argument is a \fB+\fR then the arguments are added to the current configuration; otherwise they replace it.
.IP
The possible keys, with values where appropriate, are:
.RS
.TP
.B generated
A timestamp stating when the report was generated.
.TP
.B history\-graph
A graphic showing the backups available for each volume.
This only works if \fBrsbackup\-graph\fR(1) is installed.
.TP
.B h1:\fIHEADING
.TP
.B h2:\fIHEADING
.TP
.B h3:\fIHEADING
Headings at levels 1, 2 and 3.
.TP
.B logs
A list of logs of failed backups.
.TP
.B p:\fIPARAGRAPH
A paragraph of text.
.TP
.B prune\-logs\fR[\fB:\fIDAYS\fR]
A list of logs of pruned backups.
.IP
\fIDAYS\fR is the number of days of pruning logs to put in the report.
The default is 3.
.TP
.B summary
A table summarizing the backups available for each volume.
.TP
.B title:\fITITLE
The document title.
.TP
.B warnings
A list of warning messages.
.PP
If a condition is specified then the key is only used if the condition is true.
The possible conditions are:
.TP
.B warnings
True if there are any warnings to display (i.e. if the \fBwarnings\fR
key is nonempty).
.PP
Within a \fIVALUE\fR the following sequences undergo substitution:
.TP
.B \e\fICHAR
Replaced with the single character \fICHAR\fR.
.TP
.B ${\fIVARIABLE\fB}
Replaced with the value of the environment variable \fIVARIABLE\fR, if
it is set.
.PP
The following environment variables are set:
.TP
.B RSBACKUP_CTIME
The local date and time in \fBctime\fR(3) format.
.TP
.B RSBACKUP_DATE
The local date in YYYY\-MM\-DD format.
.PP
The default is equivalent to:
.PP
.RS
.nf
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}"
.fi
.RE
.RE
.TP
.B report\-prune\-logs \fIDAYS\fR
Overrides the number of days of pruning logs to put in the report.
.IP
This directive is deprecated.
Use \fBreport\fR instead.
.TP
.B sendmail \fIPATH\fR
The path to the executable to use for sending email.
The default is platform-dependent but typically \fI/usr/sbin/sendmail\fR.
The executable should support the \fB\-t\fR, \fB\-oee\fR, \fB\-oi\fR and
\fB\-odb\fR options.
.TP
.B stylesheet \fIPATH
The path to the stylesheet to use in the HTML report.
If this is absent then a built-in default stylesheet is used.
.SS "Graph Directives"
These are global directives that affect the output of \fBrsbackup\-graph\fR(1).
.TP
.B color\-graph\-background \fICOLOR
The background color.
See below for the interpretation of \fICOLOR\fR.
.TP
.B color\-graph\-foreground \fICOLOR
The foreground color, i.e. for text.
.TP
.B color\-month\-guide \fICOLOR
The color for the vertical month guides.
.TP
.B color\-host\-guide \fICOLOR
The color for the horizontal guides between hosts.
.TP
.B color\-volume\-guide \fICOLOR
The color for the horizontal guides between volumes.
.TP
.B device\-color\-strategy \fISTRATEGY
The strategy to use for picking device colors.
.IP
A strategy is a name and a sequence of parameters, all of which are optional.
.IP
The possible strategies are:
.RS
.TP
.B equidistant\-value \fIHUE SATURATION MINVALUE MAXVALUE
Colors are picked with chosen hue and saturation, with values equally spaced within a range.
.IP
The default hue is 0 and the default saturation is 1.
The default value range is from 0 to 1.
.TP
.B equidistant\-hue \fIHUE SATURATION VALUE
Colors are picked with chosen saturation and value and equally spaced hues,
starting from \fIHUE\fR.
.IP
The default starting hue is 0 and the default saturation and value are 1.
.PP
The default strategy is equivalent to:
.RS
.nf

device\-color\-strategy equidistant\-value 120 0.75
.fi
.RE
.RE
.TP
.B horizontal\-padding \fIPIXELS
The number pixels to place between horizontally adjacent elements.
The default is 8.
.TP
.B vertical\-padding \fIPIXELS
The number pixels to place between vertically adjacent elements.
The default is 2.
.TP
.B host\-name\-font \fIFONT
The font description used for host names.
See below for the interpretation of \fIFONT\fR.
.TP
.B volume\-name\-font \fIFONT
The font description used for volume names.
.TP
.B device\-name\-font \fIFONT
The font description used for device names.
.TP
.B time\-label\-font \fIFONT
The font description used for time labels.
.TP
.B graph\-layout \fR[\fB+\fR] \fR\fIPART\fR\fB:\fICOLUMN\fB,\fIROW\fR[\fB:\fIHV\fR] ...
.RS
Defines the graph layout.
.PP
The arguments to this directive are a sequence of graph component
specifications of the form
\fIPART\fR\fB:\fICOLUMN\fB,\fIROW\fR[\fB:\fIHV\fR], where:
.TP
.I PART
The name of this component.
The following parts are recognized:
.RS
.TP
.B host\-labels
The host name labels for the graph.
This is expected to be in the same row as \fBcontent\fR.
.TP
.B volume\-labels
The volume name labels for the graph.
This is expected to be in the same row as \fBcontent\fR.
.TP
.B content
The graph content.
.TP
.B time\-labels
The time labels for the graph.
This is expected to be in the same column as \fBcontent\fR.
.TP
.B device\-key
The key mapping device names to colors.
.RE
.TP
.I COLUMN
The column number for this component.
0 is the leftmost column.
.TP
.I ROW
The row number for this component.
0 is the top row.
.TP
.I HV
The (optional) justification specification for this component.
.I H
may be one of the following:
.RS
.TP
.B L
Left justification.
.TP
.B C
Centre justification.
.TP
.B R
Right justification.
.PP
.I V
may be one of the following:
.TP
.B T
Top justification.
.TP
.B C
Centre justification.
.TP
.B B
Bottom justification.
.RE
.PP
Parts may be repeated or omitted.
.PP
The default layout is equivalent to:
.PP
.RS
.nf
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
.fi
.RE
.RE
.SS Colors
\fICOLOR\fR may be one of the following:
.TP
.I DECIMAL\fR or \fB0x\fIRRGGBB
An integer value representing an RGB triple.
It is most convenient to use hexadecimal.
For example, black is \fB0x000000\fR, red is \fB0xFF0000\fR, and so
on.
.TP
.B rgb \fIRED GREEN BLUE
Three numbers in the range 0 to 1 representing red, green and blue components.
.TP
.B hsv \fIHUE SATURATION VALUE
\fIHUE\fR chooses between different primary colors and mixtures of them.
0 represents red, 120 represents green and 240 represents blue;
intermediate values represent mixed hues.
.IP
Normally it would be in the range 0 <= \fIHUE\fR < 360, but values outside this
range are mapped into it.
.IP
\fISATURATION\fR 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.
.IP
\fIVALUE\fR is a number in the range 0 to 1 and
represents the brightness of the color.
.IP
See https://en.wikipedia.org/wiki/HSL_and_HSV for a fuller discussion
of these terms.
.SS Fonts
\fIFONT\fR is a Pango font description.
The syntax is "[\fIFAMILY-LIST\fR] [\fISTYLE-OPTIONS\fR] [\fISIZE\fR]" where:
.TP
.I FAMILY-LIST
A comma-separate list of font families.
These necessarily depend on the fonts installed locally but Pango
recognizes \fBmonospace\fR, \fBsans\fR and and \fBserif\fR as generic
family names.
.IP
If you have \fBtexttopng\fR(1) then \fBtexttopng \-l\fR will generate a
list of fonts recognized by your Pango install.
See  http://www.greenend.org.uk/rjk/sw/texttools/ for download.
.TP
.I STYLE-OPTIONS
A whitespace-separated list of style, variant, weight, stretch and
gravity options.
.IP
The possible style options are \fBroman\fR (the default),
\fBoblique\fR and \fBitalic\fB.
.IP
The possible variant options are \fBsmall\-caps\fR.
.IP
The possible weight options are \fBthin\fB, \fBultra\-light\fR,
\fBlight\fR, \fBsemi\-light\fB, \fBbook\fR, \fBregular\fR (the
default), \fBmedium\fR, \fBsemi\-bold\fR, \fBbold\fR, \fBultra\-bold\fR,
\fBheavy\fR and \fBultra\-heavy\fR.
.IP
The possible stretch options are \fBultra\-condensed\fR,
\fBcondensed\fR, \fBsemi\-condensed\fR, \fBsemi\-expanded\fR,
\fBexpanded\fR and \fBultra\-expanded\fR.
.IP
The possible gravity options are \fBsouth\fR (the default),
\fBnorth\fR, \fBeast\fR and \fBwest\fR.
.TP
.I SIZE
The font size in points, or \fIPIXELS\fR\fBpx\fR for a font size in pixels.
.PP
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.
.SH "INHERITABLE DIRECTIVES"
Inheritable directives control an aspect of one or more backups.
They can be specified at the global level or in a \fBhost\fR or
\fBvolume\fR stanza (see below).
If one appears in multiple places then volume settings override host
settings and host settings override global settings.
.TP
.B hook\-timeout \fISECONDS
How long to wait before concluding a hook has hung, in seconds.
The default is 0, which means to wait indefinitely.
.TP
.B host\-check always-up
Assume that the host is always up.
.TP
.B host\-check ssh
Check whether the host is up using SSH.
This is the default host check behavior.
.TP
.B host\-check command \fICOMMAND\fR...
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.
.TP
.B max\-age \fIDAYS\fR
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.
.TP
.B min\-backups \fICOUNT\fR
The minimum number of backups for each volume to keep on each store,
when pruning.
The default is 1.
.IP
This directive is deprecated.
Use \fBprune\-parameter min\-backups\fR instead.
.TP
.B post\-backup\-hook \fICOMMAND\fR...
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 \fBHOOKS\fR below.
.TP
.B pre\-backup\-hook \fICOMMAND\fR...
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 \fBHOOKS\fR below.
.IP
This hook can override the source path for the backup by writing a new
source path to standard output.
.TP
.B prune\-age \fIDAYS\fR
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.
.IP
This directive is deprecated.
Use \fBprune\-parameter prune\-age\fR instead.
.TP
.B prune\-parameter \fINAME\fR \fIVALUE\fR
Set a parameter for the pruning policy.
See \fBPRUNING\fR below.
.TP
.B prune\-parameter \-\-remove \fINAME\fR
Remove a parameter for pruning policy.
.TP
.B prune\-policy \fINAME\fR
The pruning policy to use.
See \fBPRUNING\fR below.
.TP
.B rsync\-timeout \fISECONDS
How long to wait before concluding rsync has hung, in seconds.
The default is 0, which means to wait indefinitely.
.TP
.B rsync\-command \fICOMMAND
The command to execute to make a backup.
The default is \fBrsync\fR.
.TP
.B rsync\-base\-options \fIOPTIONS \fR...
The options to supply to the rsync command.
The default is \fB--archive --sparse --numeric-ids --compress --fuzzy --hard-links --delete\fR.
.TP
.B rsync\-extra\-options \fIOPTIONS \fR...
Additional options to supply to the rsync command.
The default is \fB--xattrs --acls\fR.
.IP
See \fBPLATFORMS\fR for how to set this option when backing up macOS
or Windows platforms.
.TP
.B ssh\-timeout \fISECONDS\fR
How long to wait before concluding a host is down, in seconds.
The default is 60.
.SH "HOST DIRECTIVES"
A host stanza is started by a \fBhost\fR directive.
.TP
.B host \fIHOST\fR
Introduce a host stanza.
The name is used for the backup directory for this host.
.PP
The following directives, and \fBvolume\fR stanzas (see below), can
appear in a host stanza:
.TP
.B always\-up true\fR|\fBfalse
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).
.IP
This directive is deprecated.
Use \fBhost\-check always\-up\fR instead.
.TP
.B devices \fIPATTERN\fR
A \fBglob\fR(3) pattern restricting the devices that this host will be
backed up to.
.IP
Note that only backup creation honors this restriction.
Pruning and retiring do not.
.TP
.B hostname \fIHOSTNAME\fR
The SSH hostname for this host.
The default is the name from the host stanza.
.IP
The hostname \fBlocalhost\fR is treated specially: it is assumed to always be
identical to the local system, so files will be read from the local filesystem.
.TP
.B priority \fIINTEGER\fR
The priority of this host.
Hosts are backed up in descending priority order.
The default priority is 0.
.TP
.B user \fIUSERNAME\fR
The SSH username for this host.
The default is not to supply a username.
.PP
In addition, inheritable directives can appear in a host stanza, and
override any appearance of them at the global level.
.PP
Conventionally the contents of a host stanza are indented.
.PP
Remote hosts are accessed by SSH.
The user \fBrsbackup\fR 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).
.SH "VOLUME DIRECTIVES"
A volume stanza is started by a \fBvolume\fR directive.
It can only appear within a host stanza.
.TP
.B volume \fIVOLUME PATH\fR
Introduce a volume stanza.
The name is used for the backup directory for this volume.
The path is the absolute path on the host.
.PP
The following directives can appear in a volume stanza:
.TP
.B check\-file \fIPATH\fR
Checks that \fIPATH\fR exists before backing up the volume.
\fIPATH\fR 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.
.IP
This check is done before executing the \fBpre\-backup\-hook\fR, so it
applies to the real path to the volume, not the rewritten path.
.TP
.B check\-mounted true\fR|\fBfalse
If true, checks that the volume's path is a mount point before backing up the
volume.
.IP
This check is done before executing the \fBpre\-backup\-hook\fR, so it
applies to the real path to the volume, not the rewritten path.
.IP
Note that if multiple \fBcheck\-\fR options are used, all checks must
pass for the volume to be backed up.
.TP
.B exclude \fIPATTERN\fR
An exclusion for this volume.
The pattern is passed to the rsync \fB\-\-exclude\fR option.
This directive may appear multiple times per volume.
.IP
See the rsync man page for full details.
.TP
.B traverse true\fR|\fBfalse
If true, traverse mount points.
This suppresses the rsync \fB\-\-one\-file\-system\fR option.
.PP
In addition, inheritable directives can appear in a volume stanza, and
override any appearance of them at the host or global level.
.PP
Conventionally the contents of a volume stanza are indented.
.SH PRUNING
This is process of removing old backups (using the \fB\-\-prune\fR option).
The pruning policy used to determine which backups to remove is set
with the inheritable \fBprune\-policy\fR directive, and parameters to
the policy set via the \fBprune\-parameter\fR directive.
.PP
The available policies are listed below.
The default policy is \fBage\fR.
.SS 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:
.TP
.B 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.
.TP
.B 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.
.PP
For backwards compatibility, these values can also be set using
the directives of the same name.
This will be disabled in a future version.
.SS 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:
.TP
.B 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.
.TP
.B 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.
.TP
.B decay\-scale
The scale at which the decay window is expanded.
The default is 2 and the minimum is 2.
.TP
.B decay\-window
The size of the decay window.
The default is 1 and the minimum is 1.
.SS exec
This policy executes a subprogram with parameters and additional
information supplied in the environment.
.PP
The following parameters are supported:
.TP
.B path
The path to the subprogram to execute.
.PP
Any additional parameters are supplied to the subprogram via
environment variables, prefixed with \fBPRUNE_\fR.
Additionally the following environment variables are set:
.TP
.B PRUNE_DEVICE
The name of the device containing the backup.
.TP
.B PRUNE_HOST
The name of the host.
.TP
.B PRUNE_ONDEVICE
The list of backups on the device, by age in days.
This list excludes any that have already been scheduled for pruning.
.TP
.B 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.
.TP
.B PRUNE_VOLUME
The name of the volume.
.PP
These environment variables all override any parameters with clashing
names.
.PP
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 \fBPRUNE_ONDEVICE\fR), followed by
a colon, followed by the reason that this backup is to be pruned.
.PP
As a convenience, if the argument to \fBprune\-policy\fR starts with
\fB/\fR then the \fBexec\fR policy is chosen with the policy name as
the \fBpath\fR parameter.
.SS never
This policy never deletes any backups.
.SH HOOKS
A hook is a command executed by \fBrsbackup\fR just before or just
after some action.
The command is passed directly to \fBexecvp\fR(3); to use a shell
command, therefore, either wrap it in a script or invoke the shell
with the \fB\-c\fR option.
.PP
All hooks are run in \fB\-\-dry\-run\fR mode.
Hook scripts must honor \fBRSBACKUP_ACT\fR which will be set to
\fBfalse\fR in this mode and \fBtrue\fR otherwise.
.SS "Access Hooks"
Access hooks are executed (once) before doing anything that will
access backup devices (even just to read them).
.PP
The following environment variables are set when an access hook is executed:
.TP
.B RSBACKUP_ACT
Set to \fBfalse\fR in \fB\-\-dry\-run\fR mode and \fBtrue\fR
otherwise.
.TP
.B RSBACKUP_DEVICES
A space-separated list of known device names.
.TP
.B RSBACKUP_HOOK
The name of the hook (i.e. \fBpre\-access\-hook\fR, etc).
This allows a single hook script to serve as the implementation for
multiple hooks.
.SS "Backup Hooks"
Backup hooks are executed just before or just after a backup is
made.
Possible uses for backup hooks include snapshotting volumes or mounting volumes.
.PP
The following environment variables are set when a backup hook is executed:
.TP
.B RSBACKUP_ACT
Set to \fBfalse\fR in \fB\-\-dry\-run\fR mode and \fBtrue\fR
otherwise.
.TP
.B RSBACKUP_DEVICE
The target device name for the backup.
.IP
Note that this may be removed in a future version.
.TP
.B RSBACKUP_HOOK
The name of the hook (i.e. \fBpre\-backup\-hook\fR, etc).
This allows a single hook script to serve as the implementation for
multiple hooks.
.TP
.B RSBACKUP_HOST
The name of the host.
.TP
.B RSBACKUP_SSH_HOSTNAME
The SSH hostname of the host.
.IP
Recall that \fBrsbackup\fR treats the hostname \fBlocalhost\fR specially.
If the hook also needs to do so then it must duplicate this logic.
.TP
.B RSBACKUP_SSH_TARGET
The SSH hostname and username combined for passing to \fBssh\fR(1).
.IP
This will be \fIusername\fB@\fIhostname\fR or just \fIhostname\fR
depending on whether a SSH username was set.
.TP
.B RSBACKUP_SSH_USERNAME
The SSH username of the host.
If no SSH username was set, this variable will not be set.
.TP
.B RSBACKUP_STATUS
(Only for \fBpost\-backup\-hook\fR).
Either \fBok\fR or \fBfailed\fR.
.TP
.B RSBACKUP_STORE
The path to the store directory where the device is mounted.
.TP
.B RSBACKUP_VOLUME
The name of the volume.
.TP
.B RSBACKUP_VOLUME_PATH
The path to the volume.
.PP
The error output from backup hooks is stored in the same backup record
as the output
from \fBrsync\fR.
.PP
The exit status of the \fBpre\-backup\-hook\fR is interpreted as follows:
.TP
.B 0
The hook succeeded.
The backup will be attempted.
.TP
.B 75
The volume is temporarily unavailable.
The backup will not be attempted, as if \fBcheck\-file\fR or \fBcheck-mounted\fR had failed.
.TP
.I anything else
Something went wrong.
The backup will be treated as failed, as if it had been attempted and \fBrsync\fR had failed.
.PP
.BR 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 \fBRSBACKUP_DEVICE\fR will no longer be
set.
.PP
See \fBrsbackup\-snapshot\-hook\fR(1) for a hook program that can be
used to back up from Linux LVM snapshots.
.SH PLATFORMS
.SS macOS
Apple's \fBrsync\fR has a nonstandard option to enable backup of
extended attributes.
For local backups you can configure \fBrsbackup\fR to use it with a host-level directive:
.PP
.nf
rsync-extra-options --extended-attributes
.fi
.PP
If backing up a macOS host from a host with a modern \fBrsync\fR, 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:
.PP
.nf
rsync-extra-options
.fi
.PP
If an up-to-date \fBrsync\fR is used on macOS hosts, it can be left at
the default.
.SS Windows
\fBrsbackup\fR 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:
.PP
.nf
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]
.fi
.PP
In that case the affected volumes must disable attribute backup and ACL
backup as follows:
.PP
.nf
rsync-extra-options
.fi
.SH "SEE ALSO"
\fBrsbackup\fR(1),
\fBrsbackup\-graph\fR(1),
\fBrsbackup.cron\fR(1),
\fBrsbackup\-mount\fR(1),
\fBrsbackup\-snapshot\-hook\fR(1),
\fBrsync\fR(1),
\fBrsbackup\fR(5)
.SH AUTHOR
Richard Kettlewell <rjk@greenend.org.uk>