Ubuntu Manpage: rsbackup - rsync-based backup utility

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 only means deleting the records of 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 suppress 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 the records of them. Records corresponding to backups
on unavailable devices are not removed.

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 SCHEMA below), 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 suppress this check with the --force
option.

--prune, -p
Prune old backups of selected volumes. See PRUNING below.

--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 output.

--text PATH, -T PATH
Write a plain text report to PATH. The report covers all volumes, not just
selected ones. PATH can be - to write to standard output.

--email ADDRESS, -e ADDRESS
Email a report to ADDRESS. The contents is equivalent to the output of --text and
--html.

--dump-config
Writes the parsed configuration file to standard output. Must not be combined with
any other action option.

With --verbose, the configuration file is annotated with descriptive comments.

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 running.

--database, -D PATH
Override the path to the backup database.

--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 succeeded.

errors Includes all error logfiles.

recent Includes only the most recent error logfile.

latest Includes only the latest logfile, even if the backup succeeded.

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. (Warnings will always be
included in the report, this refers to runtime error output.)

--warn-store
Display warnings for unsuitable store directories and unavailable 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 selectors 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 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.

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.

Comments are introduced by an initial "#".

Command arguments may be quoted, using "double quotes". Quotes and backslashes within
quoted strings are escaped with backslashes.

Global Directives
Global directives control some general aspect of the program.

colors GOOD BAD
The colors used to represent good states (a recent backup) and bad states (no
sufficiently recent backup).

GOOD and BAD are integer values representing RGB triples. It is most convenient to
write them in hex, e.g. as 0xRRGGBB. For example, black is 0x000000, red is
0xFF0000, and so on.

device DEVICE
Names a device. This can be used multiple times. The store must have a file
called STORE/device-id which contains a known device name. Backups will only be
made to known devices.

When a device is lost or destroyed, remove its device entry and use the
--prune-unknown option to delete records of backups on it.

Device names may contain letters, digits, dots and underscores.

include PATH
Include another file as part of the configuration. If PATH is a directory then the
files within it are included (excluding dotfiles, backup and recovery files).

keep-prune-logs DAYS
The number of days to keep records of pruned backups for. The default is 31.

lock PATH
Enable locking. If this directive is present then PATH will be used as a lockfile
for operations that change anything (--backup, --prune, etc).

The lock is made by opening PATH and calling flock(2) on it with LOCK_EX.

logs PATH
The directory to store logfiles and backup records. The default is
/var/log/backup.

post-access-hook COMMAND...
A command to execute after all backup and prune operations. This is executed only
once per invocation of rsbackup. A backup is still considered to have succeeded
even if the post-access hook fails (i.e. exits nonzero). See HOOKS below.

pre-access-hook COMMAND...
A command to execute before anything that accesses any backup devices (i.e. backup
and prune operations). This is executed only once per invocation of rsbackup and
if it fails (i.e. exits nonzero) then rsbackup terminates immediately. See HOOKS
below.

public true|false
If true, backups are public. Normally backups must only be accessible by the
calling user. This option suppresses the check.

report-prune-logs DAYS
The number of days of pruning logs to put in hte report. The default is 3.

sendmail PATH
The path to the executable to use for sending email. The default is platform-
dependent but typically /usr/sbin/sendmail. The executable should support the -t,
-oee, -oi and -odb options.

store PATH
A path at which a backup device may be mounted. This can be used multiple times.

store-pattern PATTERN
A glob(7) pattern matching paths at which a backup device may be mounted. This can
be used multiple times.

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.

Inheritable Directives
Inheritable directives control an aspect of one or more backups. They can be specified at
the global level or in a host or volume stanza (see below). If one appears in multiple
places then volume settings override host settings and host settings override global
settings.

hook-timeout SECONDS
How long to wait before concluding a hook has hung, in seconds. The default is 0,
which means to wait indefinitely.

max-age DAYS
The maximum age of the most recent backup before you feel uncomfortable. The
default is 3, meaning that if a volume hasn't been backed up in the last 3 days it
will have red ink in the HTML report.

min-backups COUNT
The minimum number of backups for each volume to keep on each store, when pruning.
The default is 1.

(This is an alias for prune-parameter min-backups and will be removed in a future
version.)

post-backup-hook COMMAND...
A command to execute after finishing a backup, or after it failed. A backup is
still considered to have succeeded even if the post-backup hook fails (exits
nonzero). See HOOKS below.

pre-backup-hook COMMAND...
A command to execute before starting a backup. If this hook fails (i.e. exits
nonzero) then the backup is not made and the post-backup hook will not be run. See
HOOKS below.

This hook can override the source path for the backup by writing a new source path
to standard output.

prune-age DAYS
The age at which a backup may be pruned. The default is 366, meaning a backup will
never be pruned until it is at least a whole year old.

(This is an alias for prune-parameter prune-age and will be removed in a future
version.)

prune-parameter NAME VALUE
Set a parameter for the pruning policy. See PRUNING below.

prune-parameter --remove NAME
Remove a parameter for pruning policy.

prune-policy NAME
The pruning policy to use. See PRUNING below.

rsync-timeout SECONDS
How long to wait before concluding rsync has hung, in seconds. The default is 0,
which means to wait indefinitely.

ssh-timeout SECONDS
How long to wait before concluding a host is down, in seconds. The default is 60.

Host Directives
A host stanza is started by a host directive.

host HOST
Introduce a host stanza. The name is used for the backup directory for this host.

The following directives, and volume stanzas (see below), can appear in a host stanza:

always-up true|false
If true, the host is expected to always be available. If it is not then a warning
will be issued when making a backup if it is not. Failed attempts to make a backup
will also be recorded as failures for always-up hosts (normally hosts that cannot
be reached are silently skipped).

devices PATTERN
A glob(3) pattern restricting the devices that this host will be backed up to.

Note that only backup creation honors this restriction. Pruning and retiring do
not.

hostname HOSTNAME
The SSH hostname for this host. The default is the name from the host stanza.

The hostname localhost is treated specially: it is assumed to always be identical
to the local system, so files will be read from the local filesystem.

priority INTEGER
The priority of this host. Hosts are backed up in descending priority order. The
default priority is 0.

user USERNAME
The SSH username for this host. The default is not to supply a username.

In addition, inheritable directives can appear in a host stanza, and override any
appearance of them at the global level.

Conventionally the contents of a host stanza are indented.

Remote hosts are accessed by SSH. The user rsbackup runs as must be able to connect to
the remote host (and without a password being entered if it is to be run from a cron job
or similar).

Volume Directives
A volume stanza is started by a volume directive.

volume VOLUME PATH
Introduce a volume stanza. The name is used for the backup directory for this
volume. The path is the absolute path on the host.

The following directives can appear in a volume stanza:

check-file PATH
Checks that PATH exists before backing up the volume. PATH may be either an
absolute path or a relative path (to the root of the volume). It need not be
inside the volume though the usual use would be to check for a file which is always
present there.

This check is done before executing the pre-backup-hook, so it applies to the real
path to the volume, not the rewritten path.

check-mounted true|false
If true, checks that the volume's path is a mount point before backing up the
volume.

This check is done before executing the pre-backup-hook, so it applies to the real
path to the volume, not the rewritten path.

Note that if multiple check- options are used, all checks must pass for the volume
to be backed up.

exclude PATTERN
An exclusion for this volume. The pattern is passed to the rsync --exclude option.
This directive may appear multiple times per volume.

See the rsync man page for full details.

traverse true|false
If true, traverse mount points. This suppresses the rsync --one-file-system
option.

In addition, inheritable directives can appear in a volume stanza, and override any
appearance of them at the host or global level.

Conventionally the contents of a volume stanza are indented.

PRUNING

This is process of removing old backups (using the --prune option). The pruning policy
used to determine which backups to remove is set with the inheritable prune-policy
directive, and parameters to the policy set via the prune-parameter directive.

The available policies are listed below. The default policy is age.

age
This policy deletes backups older than a minimum age, provided a minimum number of backups
on a device remain available. The following pruning parameters are supported:

min-backups
The minimum number of backups of the volume to maintain on the device. Pruning
will never cause the number of backups to fall below this value. The default (and
minimum) is 1.

prune-age
The age after backups become eligible for pruning, in days. Only backups more than
this many days old will be pruned. The default is 366 and the minimum is 1.

For backwards compatibility, these values can also be set using the directives of the same
name. This will be disabled in a future version.

decay
This policy thins out backups older than a minimum age, using a configurable decay pattern
that arranges to keep a declining number of backups with age. The following pruning
parameters are supported:

decay-start
The age after backups become eligible for pruning, in days. Only backups more than
this many days old will be pruned. The default is 1 and the minimum is 1.

decay-limit
The age after which backups are always pruned, in days. Backups older than this
will always be pruned unless this would leave no backups at all. The default is
366 and the minimum is 1.

decay-scale
The scale at which the decay window is expanded. The default is 2 and the minimum
is 2.

decay-window
The size of the decay window. The default is 1 and the minimum is 1.

exec
This policy executes a subprogram with parameters and additional information supplied in
the environment.

The following parameters are supported:

path The path to the subprogram to execute.

Any additional parameters are supplied to the subprogram via environment variables,
prefixed with PRUNE_. Additionally the following environment variables are set:

PRUNE_DEVICE
The name of the device containing the backup.

PRUNE_HOST
The name of the host.

PRUNE_ONDEVICE
The list of backups on the device, by age in days. This list excludes any that
have already been scheduled for pruning, and includes the backup under
consideration (i.e. the value of BACKUP_AGE will appear in this list).

PRUNE_TOTAL
The total number of backups of this volume on any device. Note that it does not
include backups on other devices that have just been selected for pruning by
another call to the subprogram.

PRUNE_VOLUME
The name of the volume.

These environment variables all override any parameters with clashing names.

The output should be a list of backups to prune, one per line (in any order). Each line
should contain the age in days of the backup to prune (i.e. the same value as appeared in
PRUNE_ONDEVICE), followed by a colon, followed by the reason that this backup is to be
pruned.

As a convenience, if the argument to prune-policy starts with / then the exec policy is
chosen with the policy name as the path parameter.

never
This policy never deletes any backups.

HOOKS

A hook is a command executed by rsbackup just before or just after some action. The
command is passed directly to execvp(3); to use a shell command, therefore, either wrap it
in a script or invoke the shell with the -c option.

All hooks are run in --dry-run mode. Hook scripts must honor RSBACKUP_ACT which will be
set to false in this mode and true otherwise.

Access Hooks
Access hooks are executed (once) before doing anything that will access backup devices
(even just to read them).

The following environment variables are set when an access hook is executed:

RSBACKUP_ACT
Set to false in --dry-run mode and true otherwise.

RSBACKUP_DEVICES
A space-separated list of known device names.

RSBACKUP_HOOK
The name of the hook (i.e. pre-access-hook, etc). This allows a single hook script
to serve as the implementation for multiple hooks.

Backup Hooks
Backup hooks are executed just before or just after a backup is made.

The following environment variables are set when a backup hook is executed:

RSBACKUP_ACT
Set to false in --dry-run mode and true otherwise.

RSBACKUP_DEVICE
The target device name for the backup.

Note that this may be removed in a future version.

RSBACKUP_HOOK
The name of the hook (i.e. pre-backup-hook, etc). This allows a single hook script
to serve as the implementation for multiple hooks.

RSBACKUP_HOST
The name of the host.

RSBACKUP_SSH_HOSTNAME
The SSH hostname of the host.

Recall that rsbackup treats the hostname localhost specially. If the hook also
needs to do so then it must duplicate this logic.

RSBACKUP_SSH_TARGET
The SSH hostname and username combined for passing to ssh(1).

This will be username@hostname or just hostname depending on whether a SSH username
was set.

RSBACKUP_SSH_USERNAME
The SSH username of the host. If no SSH username was set, this variable will not
be set.

RSBACKUP_STATUS
(Only for post-backup-hook). Either ok or failed.

RSBACKUP_STORE
The path to the store directory where the device is mounted.

RSBACKUP_VOLUME
The name of the volume.

RSBACKUP_VOLUME_PATH
The path to the volume.

The error output from backup hooks is stored in the same backup record as the output from
rsync.

NOTE: The current behavior is that the pre/post backup hooks are run separately for each
backup. In a future version, they may be run only once for all backups of a given volume,
in which case RSBACKUP_DEVICE will no longer be set.

See rsbackup-snapshot-hook(1) for a hook program that can be used to back up from Linux
LVM snapshots.

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 contents of the
subsiduary filesystems, then be sure to include the traverse 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 configuration 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 complete 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 records 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  corresponding  .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  directory  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 warnings 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 taking place.

       fatally broken
              The store cannot be used for a backup.  The program will be terminated.

       The states are recognized using the following tests (in this order):

       •      If the store path does not exist, the store is bad.

       •      If  the store does not have a device-id file then it is unavailable.  If it has one
              but reading it raises an error then it is bad.

       •      If the store's device-id file contains an unknown device name then it is bad.

       •      If the store's device-id file names the same device as some other store then it  is
              fatally broken.

       •      If  the  store  is  not owned by root then it is bad.  This check can be overridden
              with the public directive.

       •      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/backups.db
              The backup records.  See SCHEMA below.

       STORE/HOST/VOLUME/YYYY-MM-DD
              One backup for a volume.

       STORE/HOST/VOLUME/YYYY-MM-DD.incomplete
              Flag file for an incomplete backup.

SCHEMA

backups.db is a SQLite database. It contains a single table with the following
definition:

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)
)

Each row represents a completed backup. The meanings of the fields are as follows:

host The name of the host the backup was taken from.

volume The name of the volume the backup was taken from.

device The name of the device the backup was written to.

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.

time The time that the backup was started, as a time_t.

pruned The time that backup pruning started (if it is underway) or finished (if it is
complete), as a time_t.

rc The exit status of the backup process. 0 means success.

status Status of this backup. See below.

log The log output of rsync(1) and hooks. If the backup status is pruning or pruned
(see below) then this contains the reason for the pruning.

Possible status values are:

0 Unknown status. Not normally seen.

1 Internally this means the backup is underway. If seen externally after rsbackup
terminates it means the backup is incomplete.

2 Backup is complete.

3 Backup has failed.

4 Pruning has started.

5 Pruning has completed.

rsbackup 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.

HISTORICAL BEHAVIOR

       Older  versions  of  rsbackup stored the logs for each backup in a separate file.  If such
       files are encountered then rsbackup will automatically populate backups.db from  them  and
       then delete them.

       Older  versions  of rsbackup 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.

AUTHOR

       Richard Kettlewell <rjk@greenend.org.uk>

                                                                                      rsbackup(1)