.TH rsbackup 1
.\" Copyright (c) 2011, 2012, 2014, 2015 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
rsbackup \- rsync-based backup utility
.SH SYNOPSIS
\fBrsbackup\fR [\fIOPTIONS\fR] [\fB\-\-\fR] [\fISELECTOR\fR...]
.br
\fBrsbackup \-\-retire [\fIOPTIONS\fR] [\fB\-\-\fR] [\fISELECTOR\fR...]
.br
\fBrsbackup \-\-retire\-device [\fIOPTIONS\fR] [\fB\-\-\fR] \fIDEVICE\fR...
.SH DESCRIPTION
Backs up files from one or more (remote) destinations to a single
backup storage directory, preserving their contents, layout,
ownership, permissions, timestamps and hardlink structure.
.PP
Incremental backups are achieved by hard-linking identical files
within successive backups of the same files.
.SH OPTIONS
.SS "Action Options"
At least one of these options must be specified.
When multiple actions are specified, they are executed in the order
shown below.
.TP
.B \-\-backup\fR, \fB-b
Make a backup of the selected volumes.
At most one backup of a given volume will be made per day.
.TP
.B \-\-retire\-device
Retire the named devices.
Retiring a device only means deleting the records of it.
Files on the device itself are not touched.
.IP
If the device is still listed in the configuration file then you will
be asked whether you really want to retire it; you can suppress this
check with the \fB\-\-force\fR option.
.TP
.B \-\-retire
Retire the named hosts and volumes.
Retiring a volume means deleting any available backups for the volume
and the records of them.
Records corresponding to backups on unavailable devices are not removed.
.IP
If you just want to remove backup records for retired volumes but want
to keep the backups, you should either manually remove the records
(see \fBSCHEMA\fR below),
or
rename it within the volume.
.IP
If the volume is still listed in the configuration file then you will
be asked whether you really want to retire it; you can suppress this
check with the \fB\-\-force\fR option.
.TP
.B \-\-prune\fR, \fB\-p
Prune old backups of selected volumes.
See \fBPRUNING\fR below.
.TP
.BR \-\-prune\-incomplete, \fB\-P
Prune incomplete backups of selected volumes.
Any backups that failed before completion will be removed.
.TP
.B \-\-html \fIPATH\fR, \fB\-H \fIPATH
Write an HTML report to \fIPATH\fR.
The report covers all volumes, not just selected ones.
\fIPATH\fR can be \fB\-\fR to write to standard output.
.TP
.B \-\-text \fIPATH\fR, \fB\-T \fIPATH
Write a plain text report to \fIPATH\fR.
The report covers all volumes, not just selected ones.
\fIPATH\fR can be \fB\-\fR to write to standard output.
.TP
.B \-\-email \fIADDRESS\fR, \fB\-e \fIADDRESS
Email a report to \fIADDRESS\fR.
The contents is equivalent to the output of \fB\-\-text\fR and
\fB\-\-html\fR.
.TP
.B \-\-dump\-config
Writes the parsed configuration file to standard output.
Must not be combined with any other action option.
.IP
With \fB\-\-verbose\fR, the configuration file is annotated with
descriptive comments.
.SS "General Options"
.TP
.B \-\-config \fIPATH\fR, \fB\-c \fIPATH
The path to the configuration file.
The default is
.IR /etc/rsbackup/config .
.TP
.B \-\-store \fIPATH\fR, \fB\-s \fIPATH
Specify the destination directory to back up to.
Using this option (possibly more than once) is equivalent to removing
the \fBstore\fR directives from the configuration file and replacing
them with the paths give in \fB\-\-store\fR options.
.IP
This option implicitly enables the \fB\-\-warn\-store\fR option.
.TP
.B \-\-verbose\fR, \fB\-v
Enable verbose mode.
Various messages will be displayed to report progress and the rsync
\fB\-\-quiet\fR option is suppressed.
.TP
.B \-\-dry\-run\fR, \fB\-n
Enable dry-run mode.
Commands will be displayed but nothing will actually be done.
.TP
.B \-\-force\fR, \fB\-f
Suppress checks made when retiring devices and volumes.
.TP
.B \-\-wait\fR, \fB\-w
Waits rather than giving up if another copy of \fBrsbackup\fR is running.
.TP
.B \-\-database\fR, \fB-D \fIPATH
Override the path to the backup database.
.TP
.B \-\-help\fR, \fB\-h
Display a usage message.
.TP
.B \-\-version\fR, \fB\-V
Display the version number.
.SS "Report Verbosity"
.TP
.B \-\-logs \fIVERBOSITY\fR
Controls which logfiles for a given volume/device pair to include in
the report.
The possible values of \fIVERBOSITY\fR are:
.RS
.TP
.B all
Includes all nonempty logfiles, even if the backup succeeded.
.TP
.B errors
Includes all error logfiles.
.TP
.B recent
Includes only the most recent error logfile.
.TP
.B latest
Includes only the latest logfile, even if the backup succeeded.
.TP
.B failed
Includes only the most recent logfile but only if that attempt failed.
This is the default.
.RE
.SS "Warning Options"
.TP
.B \-\-warn\-unknown
Display warnings for unknown devices, hosts and volumes.
(Warnings will always be included in the report, this refers to
runtime error output.)
.TP
.B \-\-warn\-store
Display warnings for unsuitable store directories and unavailable devices.
.TP
.B \-\-warn\-unreachable
Display warnings for unreachable hosts.
.TP
.B \-\-no\-warn\-partial
Suppress warnings for rsync "partial transfer" diagnostics
(which are on by default).
.TP
.B \-\-warn\-all\fR, \fB\-W
Enable all \fB\-\-warn\-\fR options.
.TP
.B \-\-no\-errors
Suppress display of errors from rsync.
.SS "Volume Selection"
The list of selectors on the command line determines what subset of
the known volumes are backed up, pruned or retired.
The following selectors are possible:
.TP 16
.I HOST
Select all volumes for the host.
.TP
.IR HOST : VOLUME
Select the volume.
.TP
.BI - HOST
Deselect all volumes for the host.
.TP
.BI - HOST : VOLUME
Deselect the volume.
.TP
.B *
Select all volumes.
.PP
If no hosts or volumes are specified on the command line then all volumes are
selected for backing up or pruning.
For retiring, you must explicitly select hosts or volumes to retire
and only positive selections are possible.
.SH "CONFIGURATION FILE"
The config 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.
.PP
Comments are introduced by an initial "#".
.PP
Command arguments may be quoted, using "double quotes".
Quotes and backslashes within quoted strings are escaped with
backslashes.
.SS "Global Directives"
Global directives control some general aspect of the program.
.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.
.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 report\-prune\-logs \fIDAYS\fR
The number of days of pruning logs to put in hte report.
The default is 3.
.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 store \fIPATH\fR
A path at which a backup device may be mounted.
This can be used multiple times.
.TP
.B store-pattern \fIPATTERN\fR
A \fBglob\fR(7) pattern matching paths at which a backup device may be
mounted.
This can be used multiple times.
.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 "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 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 is an alias for \fBprune\-parameter min\-backups\fR and will be
removed in a future version.)
.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 is an alias for \fBprune\-parameter prune\-age\fR and will be
removed in a future version.)
.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 ssh\-timeout \fISECONDS\fR
How long to wait before concluding a host is down, in seconds.
The default is 60.
.SS "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).
.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).
.SS "Volume Directives"
A volume stanza is started by a \fBvolume\fR directive.
.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,
and includes the backup under consideration (i.e. the value of
\fBBACKUP_AGE\fR will appear in this list).
.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.
.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
.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 "BACKUP LIFECYCLE"
.SS "Adding A New Host"
To add a new host create a \fBhost\fR entry for it in the configuration file.
.PP
To back up the local host, specify \fBhostname localhost\fR.
Otherwise you can usually omit \fBhostname\fR.
.PP
You may want to set host-wide values for \fBprune\-age\fR,
\fBmax\-age\fR and \fBmin\-backups\fR.
.PP
A host with no volumes has no effect.
.SS "Adding A New Volume"
To add a new volume create a \fBvolume\fR entry for it in the relevant
\fBhost\fR section of the configuration file.
.PP
Add \fBexclude\fR options to skip files you don't want to back up.
This might include temporary files and the contents of "trash"
directories.
.PP
If the volume contains mount points, and you want to back up the
contents of the subsiduary filesystems, then be sure to include the
\fBtraverse\fR option.
.PP
You may want to set per-volume values for \fBprune\-age\fR,
\fBmax\-age\fR and \fBmin\-backups\fR.
.SS "Adding A New Device"
To add a new device, format and mount it and create a
\fIdevice\-id\fR file in its top-level directory.
Add a \fBdevice\fR entry for it in the configuration file and a
\fBstore\fR entry mentioning its usual mount point.
.PP
Under normal circumstances you should make sure that the backup
filesystem is owned by root and mode 0700.
.SS "Making Backups"
To backup up all available volumes to all available devices:
.in +4n
.nf

rsbackup \-\-backup

.fi
.in
You will probably want to automate this.
To only back up a limited set of volumes specify selection arguments
on the command line.
.SS "Pruning Backups"
To prune old backups:
.in +4n
.nf

rsbackup \-\-prune \-\-prune\-incomplete

.fi
.in
You will probably want to automate this.
.PP
An "incomplete backup" occurs when a backup of a volume fails or is
interrupted before completion.
They are not immediately deleted because \fBrsync\fR may be able to
use the files already transferred to save effort on subsequent backups
on the same day, or (if there are no complete backups to use for this
purpose) later days.
.SS "Retiring A Host"
Retiring a host means removing all backups for it.
The suggested approach is to remove configuration for it and then use
\fBrsbackup \-\-retire \fIHOST\fR to remove its backups too.
You can do this the other way around but you will be prompted to check
you really meant to remove backups for a host still listed in the
configuration file.
.PP
If any of the backups for the host are on a retired device you should
retire that device first.
.SS "Retiring A Volume"
Retiring a volume means removing all backups for it.
It is almost the same as retiring a whole host but the command is
\fBrsbackup \-\-retire \fIHOST\fB:\fIVOLUME\fR.
.PP
You can retire multiple hosts and volumes in a single command.
.SS "Retiring A Device"
Retiring a device just means removing the records for it.
Use \fBrsbackup \-\-retire\-device \fIDEVICE\fR to do this.
The contents of the device are not modified; if you want that you must
do it manually.
.PP
You can retire multiple devices in a single command.
.SH RESTORING
Restore costs extra l-)
.SS "Manual Restore"
The backup has the same layout, permissions etc as the original
system, so it's perfectly possible to simply copy files from a backup
directory to their proper location.
.PP
Be careful to get file ownership right.
The backup is stored with the same numeric user and group ID as the
original system used.
.PP
Until a backup is completed, or while one is being pruned,
a corresponding \fB.incomplete\fR file
will exist.
Check for such a file before restoring any given backup.
.SS "Restoring With rsync"
Supposing that host \fBchymax\fR has a volume called \fBusers\fR in
which user home directories are backed up, and user \fBrjk\fR wants
their entire home directory to be restored, an example restore
command might be:
.in +4n
.nf

rsync \-aSHz \-\-numeric\-ids /store/chymax/users/2010-04-01/rjk/. chymax:~rjk/.

.fi
.in
.PP
You could add the \fB\-\-delete\fR option if you wanted to restore to
exactly the status quo ante, or at the opposite extreme
\fB\-\-existing\fR if you only wanted to restore files that had been
deleted.
.PP
You might prefer to rsync back into a staging area and then pick files
out manually.
.SS "Restoring with tar"
You could tar up a backup directory (or a subset of it) and then untar
it on the target.
Remember to use the \fB\-\-numeric\-owner\fR option to tar.
.SH "STORE VALIDITY"
A store may be in the following states:
.IP \fBavailable
The store can be used for a backup.
.IP \fBunavailable
The store cannot be used for a backup.
Normally this does not generate an error but \fB\-\-warn\-store\fR can
be used to report warnings for all unavailable stores, and if no store
is available then the problems with the unavailable stores are described.
.IP \fBbad
The store cannot be used for a backup.
This always generates an error message, but does not prevent backups
to other stores taking place.
.IP "\fBfatally broken"
The store cannot be used for a backup.
The program will be terminated.
.PP
The states are recognized using the following tests (in this order):
.IP \(bu
If the store path does not exist, the store is bad.
.IP \(bu
If the store does not have a \fBdevice\-id\fR file then it is
unavailable.
If it has one but reading it raises an error then it is bad.
.IP \(bu
If the store's \fBdevice\-id\fR file contains an unknown device name
then it is bad.
.IP \(bu
If the store's \fBdevice\-id\fR file names the same device as some
other store then it is fatally broken.
.IP \(bu
If the store is not owned by \fBroot\fR then it is bad.
This check can be overridden with the \fBpublic\fR directive.
.IP \(bu
If the store can be read or written by group or world then it is bad.
This check can be overridden with the \fBpublic\fR directive.
.SH FILES
.TP
.I /etc/rsbackup/config
Configuration file.
.TP
.I LOGS/backups.db
The backup records.
See \fBSCHEMA\fR below.
.TP
.I STORE/HOST/VOLUME/YYYY\-MM\-DD
One backup for a volume.
.TP
.I STORE/HOST/VOLUME/YYYY\-MM\-DD.incomplete
Flag file for an incomplete backup.
.SH SCHEMA
.I backups.db
is a SQLite database.
It contains a single table with the following definition:
.nf

CREATE TABLE backup (
  host TEXT,
  volume TEXT,
  device TEXT,
  id TEXT,
  time INTEGER,
  pruned INTEGER,
  rc INTEGER,
  status INTEGER,
  log BLOB,
  PRIMARY KEY (host,volume,device,id)
)

.fi
Each row represents a completed backup.
The meanings of the fields are as follows:
.TP 10
.B host
The name of the host the backup was taken from.
.TP
.B volume
The name of the volume the backup was taken from.
.TP
.B device
The name of the device the backup was written to.
.TP
.B id
The unique identifier for the backup.
Currently this is the date the backup was made, in the format YYYY-MM-DD
but this may be changed in the future.
.TP
.B time
The time that the backup was started, as a \fBtime_t\fR.
.TP
.B pruned
The time that backup pruning started (if it is underway) or finished
(if it is complete), as a \fBtime_t\fR.
.TP
.B rc
The exit status of the backup process.
0 means success.
.TP
.B status
Status of this backup.
See below.
.TP
.B log
The log output of \fBrsync\fR(1) and hooks.
If the backup status is pruning or pruned (see below) then this
contains the reason for the pruning.
.PP
Possible status values are:
.TP
.B 0
Unknown status.
Not normally seen.
.TP
.B 1
Internally this means the backup is underway.
If seen externally after \fBrsbackup\fR terminates it means the backup
is incomplete.
.TP
.B 2
Backup is complete.
.TP
.B 3
Backup has failed.
.TP
.B 4
Pruning has started.
.TP
.B 5
Pruning has completed.
.PP
\fBrsbackup\fR is not designed with concurrent access to this table in
mind.
Therefore it is recommended that you only modify its contents when the
program is not running.
.SH "HISTORICAL BEHAVIOR"
Older versions of \fBrsbackup\fR stored the logs for each backup in a
separate file.
If such files are encountered then \fBrsbackup\fR will automatically
populate \fIbackups.db\fR from them and then delete them.
.PP
Older versions of \fBrsbackup\fR logged pruning information to a
pruning logfile.
These files will be deleted at the same rate as records of pruned
backups in the database.
They are not included in the report.
.SH "SEE ALSO"
\fBrsbackup.cron\fR(1), \fBrsbackup\-mount\fR(1),
\fBrsbackup-snapshot-hook\fR(1),
\fBrsync\fR(1)
.SH AUTHOR
Richard Kettlewell <rjk@greenend.org.uk>