NAME
rsbackup - rsync-based backup utility
SYNOPSIS
rsbackup [OPTIONS] [--] [SELECTOR...]
rsbackup --retire [OPTIONS] [--] [SELECTOR...]
rsbackup --retire-device [OPTIONS] [--] DEVICE...
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.
Incremental backups are achieved by hard-linking identical files within
successive backups of the same files.
OPTIONS
Action Options
At least one of these options must be specified. When multiple actions
are specified, they are executed in the order shown below.
--backup, -b
Make a backup of the selected volumes. At most one backup of a
given volume will be made per day.
--retire-device
Retire the named devices. Retiring a device means deleting the
logfiles for it. Files on the device itself are not touched.
If the device is still listed in the configuration file then you
will be asked whether you really want to retire it; you can sup-
press this check with the --force option.
--retire
Retire the named hosts and volumes. Retiring a volume means
deleting any available backups for the volume and their corre-
sponding logfiles. Logfiles on backups for unavailable devices
are not removed.
If you just want to remove logfiles for retired volumes but want
to keep the backups, you should either manually remove the log-
files, or rename it within the volume.
If the volume is still listed in the configuration file then you
will be asked whether you really want to retire it; you can sup-
press this check with the --force option.
--prune, -p
Prune old backups of selected volumes. Any backups that are
older than the prune-age listed for them in the current configu-
ration will be deleted provided that does not reduce the number
of backups below the volume's min-backups setting.
--prune-incomplete,-P
Prune incomplete backups of selected volumes. Any backups that
failed before completion will be removed.
--html PATH, -H PATH
Write an HTML report to PATH. The report covers all volumes,
not just selected ones. PATH can be - to write to standard out-
put.
--text PATH, -T PATH
Write a plain text report to PATH. The report covers all vol-
umes, not just selected ones. PATH can be - to write to stan-
dard output.
--email ADDRESS, -e ADDRESS
Email a report to ADDRESS. The contents is equivalent to the
output of --text and --html.
General Options
--config PATH, -c PATH
The path to the configuration file. The default is
/etc/rsbackup/config.
--store PATH, -s PATH
Specify the destination directory to back up to. Using this
option (possibly more than once) is equivalent to removing the
store directives from the configuration file and replacing them
with the paths give in --store options.
This option implicitly enables the --warn-store option.
--verbose, -v
Enable verbose mode. Various messages will be displayed to
report progress and the rsync --quiet option is suppressed.
--dry-run, -n
Enable dry-run mode. Commands will be displayed but nothing
will actually be done.
--force, -f
Suppress checks made when retiring devices and volumes.
--wait, -w
Waits rather than giving up if another copy of rsbackup is run-
ning.
--help, -h
Display a usage message.
--version, -V
Display the version number.
Report Verbosity
--logs VERBOSITY
Controls which logfiles for a given volume/device pair to
include in the report. The possible values of VERBOSITY are:
all Includes all nonempty logfiles, even if the backup suc-
ceeded.
errors Includes all error logfiles.
recent Includes only the most recent error logfile.
latest Includes only the latest logfile, even if the backup suc-
ceeded.
failed Includes only the most recent logfile but only if that
attempt failed. This is the default.
Warning Options
--warn-unknown
Display warnings for unknown devices, hosts and volumes. (Warn-
ings will always be included in the report, this refers to run-
time error output.)
--warn-store
Display warnings for unsuitable store directories and unavail-
able devices.
--warn-unreachable
Display warnings for unreachable hosts.
--no-warn-partial
Suppress warnings for rsync "partial transfer" diagnostics
(which are on by default).
--warn-all, -W
Enable all --warn- options.
--no-errors
Suppress display of errors from rsync.
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 selec-
tors are possible:
HOST Select all volumes for the host.
HOST:VOLUME Select the volume.
-HOST Deselect all volumes for the host.
-HOST:VOLUME Deselect the volume.
* Select all volumes.
If no hosts or volumes are specified on the command line then all vol-
umes are selected for backing up or pruning. For retiring, you must
explicitly select hosts or volumes to retire and only positive selec-
tions are possible.
CONFIGURATION FILE
The config file contains global directives and a series of host stan-
zas. 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
store PATH
A path at which a backup device may be mounted. This can be
used multiple times.
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 logs of backups on it.
Device names may contain letters, digits, dots and underscores.
public Backups are public. Normally backups must only be accessible by
the calling user. This option suppresses the check.
logs PATH
The directory to store logfiles. The default is
/var/log/backup.
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).
ssh-timeout SECONDS
How long to wait before concluding a host is down. The default
is 3.
max-age DAYS
The maximum age of the most recent backup before you feel uncom-
fortable. 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.
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.
keep-prune-logs DAYS
The number of days to keep prune logs for. The default is 31.
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 and backup files).
pre-access-hook COMMAND...
A command to execute before anything that accesses any backup
devices (i.e. backup and prune operations). This is execute
only once per invocation of rsbackup and if it fails (i.e. exits
nonzero) then rsbackup terminates immediately. See HOOKS below.
post-access-hook COMMAND...
A command to execute after all backup and prune operations.
This is execute 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-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.
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.
rsync-timeout SECONDS
How long to wait before concluding rsync has hung. The default
is 0, which means to wait indefinitely.
hook-timeout SECONDS
How long to wait before concluding a hook has hung. The default
is 0, which means to wait indefinitely.
Host Directives
A host stanza is started by a host directive. It contains other host
directives, and one or more volume stanzas.
host HOST
Introduce a host stanza. The name is used for the backup direc-
tory for this host.
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.
user USERNAME
The SSH username for this host. The default is not to supply a
username.
always-up
Indicates that 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.
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.
In addition, the following directives can be used within a host stanza,
and apply to just that host:
prune-age
max-age
min-backups
pre-backup-hook
post-backup-hook
rsync-timeout
hook-timeout
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. It contains one or
more volume directives.
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.
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
Traverse mount points. This suppresses the rsync
--one-file-system option.
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.
In addition, the following directives can be used within a volume
stanza, and apply to just that volume:
prune-age
max-age
min-backups
pre-backup-hook
post-backup-hook
rsync-timeout
hook-timeout
devices
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.
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 a backup hook is exe-
cuted:
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.
RSBACKUP_ACT
Set to false in --dry-run mode and true otherwise.
Access hooks are executed in --dry-run mode.
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 exe-
cuted:
RSBACKUP_DEVICE
The target device name for the backup.
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 written to the same logfile as
the output from rsync.
Backup hooks are currently not executed in --dry-run mode but note that
this may be changed in the future and an RSBACKUP_ACT variable intro-
duced, as for access hooks.
BACKUP LIFECYCLE
Adding A New Host
To add a new host create a host entry for it in the configuration file.
To back up the local host, specify hostname localhost. Otherwise you
can usually omit hostname.
You may want to set host-wide values for prune-age, max-age and
min-backups.
A host with no volumes has no effect.
Adding A New Volume
To add a new volume create a volume entry for it in the relevant host
section of the configuration file.
Add exclude options to skip files you don't want to back up. This
might include temporary files and the contents of "trash" directories.
If the volume contains mount points, and you want to back up the con-
tents of the subsiduary filesystems, then be sure to include the tra-
verse option.
You may want to set per-volume values for prune-age, max-age and
min-backups.
Adding A New Device
To add a new device, format and mount it and create a device-id file in
its top-level directory. Add a device entry for it in the configura-
tion file and a store entry mentioning its usual mount point.
Under normal circumstances you should make sure that the backup
filesystem is owned by root and mode 0700.
Making Backups
To backup up all available volumes to all available devices:
rsbackup --backup
You will probably want to automate this. To only back up a limited set
of volumes specify selection arguments on the command line.
Pruning Backups
To prune old backups:
rsbackup --prune --prune-incomplete
You will probably want to automate this.
An "incomplete backup" occurs when a backup of a volume fails or is
interrupted before completion. They are not immediately deleted
because rsync may be able to use the files already transferred to save
effort on subsequent backups on the same day, or (if there are no com-
plete backups to use for this purpose) later days.
Retiring A Host
Retiring a host means removing all backups for it. The suggested
approach is to remove configuration for it and then use rsbackup
--retire HOST 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.
If any of the backups for the host are on a retired device you should
retire that device first.
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 rsbackup --retire
HOST:VOLUME.
You can retire multiple hosts and volumes in a single command.
Retiring A Device
Retiring a device just means removing the logs for it. Use rsbackup
--retire-device DEVICE to do this. The contents of the device are not
modified; if you want that you must do it manually.
You can retire multiple devices in a single command.
RESTORING
Restore costs extra l-)
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.
Be careful to get file ownership right. The backup is stored with the
same numeric user and group ID as the original system used.
Until a backup is completed, or while one is being pruned, a corre-
sponding .incomplete file will exist. Check for such a file before
restoring any given backup.
Restoring With rsync
Supposing that host chymax has a volume called users in which user home
directories are backed up, and user rjk wants their entire home direc-
tory to be restored, an example restore command might be:
rsync -aSHz --numeric-ids /store/chymax/users/2010-04-01/rjk/. chymax:~rjk/.
You could add the --delete option if you wanted to restore to exactly
the status quo ante, or at the opposite extreme --existing if you only
wanted to restore files that had been deleted.
You might prefer to rsync back into a staging area and then pick files
out manually.
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 --numeric-owner option to tar.
STORE VALIDITY
A store may be in the following states:
available
The store can be used for a backup.
unavailable
The store cannot be used for a backup. Normally this does not
generate an error but --warn-store can be used to report warn-
ings for all unavailable stores, and if no store is available
then the problems with the unavailable stores are described.
bad The store cannot be used for a backup. This always generates an
error message, but does not prevent backups to other stores tak-
ing place.
fatally broken
The store cannot be used for a backup. The program will be ter-
minated.
The states are recognized using the following tests (in this order):
+o If the store path does not exist, the store is bad.
+o If the store does not have a device-id file then it is unavail-
able. If it has one but reading it raises an error then it is
bad.
+o If the store's device-id file contains an unknown device name
then it is bad.
+o If the store's device-id file names the same device as some
other store then it is fatally broken.
+o If the store is not owned by root then it is bad. This check
can be overridden with the public directive.
+o If the store can be read or written by group or world then it is
bad. This check can be overridden with the public directive.
FILES
/etc/rsbackup/config
Configuration file.
LOGS/YYYY-MM-DD-DEVICE-HOST-VOLUME.log
Log file for one attempt to back up a volume.
LOGS/prune-YYYY-MM-DD.log
Log of recently pruning actions.
STORE/HOST/VOLUME/YYYY-MM-DD
One backup for a volume.
STORE/HOST/VOLUME/YYYY-MM-DD.incomplete
Flag file for an incomplete backup.
SEE ALSO
rsbackup.cron(1), rsbackup-mount(1), rsync(1)
AUTHOR
Richard Kettlewell <rjk@greenend.org.uk>