NAME
       rsbackup - rsync-based backup utility

SYNOPSIS
       rsbackup [OPTIONS] [--] [SELECTOR...]
       rsbackup --retire [OPTIONS] [--] [SELECTOR...]
       rsbackup --retire-device [OPTIONS] [--] DEVICE...

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

       See rsbackup(5) for details of the configuration file.

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 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 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, also use the --forget-only option
              (see below).

              Since this command deletes backups, you will be prompted to con-
              firm it.  You can suppress this check with the --force option.

       --prune, -p
              Prune old backups of selected volumes.  See rsbackup(5) for  de-
              tails how how pruning is controlled.

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

       --check-unexpected
              List unexpected files on  backup  devices  to  standard  output.
              Must not be combined with any other action option.

              Note that this option does not verify that the backups are good.
              It just detects unexpected files on currently-mounted backup de-
              vices.

       --latest
              Prints  out  the path to the latest complete backup for each se-
              lected volume.

       --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 de-
              scriptive comments.

   Options Affecting Action Options
       --forget-only
              With --retire, suppresses deletion of backups, and instead  just
              drops database records for the hosts and volumes affected.

   General Options
       --config PATH, -c PATH
              The  path  to  the  configuration file.  The default is /etc/rs-
              backup/config.

       --store PATH, -s PATH
              Specify the destination directory to back up to.  Using this op-
              tion (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.

       --unmounted-store PATH
              Equivalent to --store except that the store does not have to  be
              a mount point.

       --verbose, -v
              Enable  verbose mode.  Various messages will be displayed to re-
              port 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, and
              overrides backup policies.

       --null, -0
              For the --check-unexpected option, terminate  filenames  with  a
              null, rather than newline.

       --wait, -w
              Waits  rather than giving up if another copy of rsbackup is run-
              ning.

       --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  in-
              clude 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.

       HOST  and  VOLUME  are both glob(7) patterns, so (for example) * can be
       used to select all hosts.

       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.

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-parameter  prune-age,
       max-age and prune-parameter 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-parameter prune-age,
       max-age and prune-parameter min-backups.

   Adding A New Device
       To add a new device:

       1.  Format and mount it.

       2.  chown it to root.

       3.  chmod it to mode 0700.

       4.  Create a device-id file containing its name in its top-level direc-
           tory.

       5.  Add a device entry for it in the configuration file,

       6.  If you do not use store-pattern, add a store entry in the  configu-
           ration file mentioning its usual mount point.

   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 in-
       terrupted  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  ap-
       proach 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  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 -aSHAXz --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.

LINK TARGETS
       In  order  to minimize storage requirements, when a backup is made, rs-
       backup selects recent backups to use as link targets.  Where  possible,
       rsync will create hardlinks between the new backup and the link target,
       instead of making a new copy of an unchanged file.

       At present up to two backups may be selected as link targets, according
       to the following rules:

       +o      If  the  .nolink  file exists for the volume (see below) then no
              link target is used, overriding the rules below.

       +o      The most recent complete backup, if there is one, is used.

       +o      If the most recent backup is incomplete, that is used.

FILES
       /etc/rsbackup/config
              Configuration file.  See rsbackup(5)

       LOGS/backups.db
              The backup records.  See SCHEMA below.

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

       STORE/HOST/VOLUME.nolink
              If this file exists then no existing backup will  be  considered
              as  a hardlink target until a new backup has succeeded (at which
              point it is deleted).

       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,
             finishTime INTEGER,
             PRIMARY KEY (host,volume,device,id)
           )
       Each  row  represents a backup.  The meanings of the fields are as fol-
       lows:

       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  rea-
                 son for the pruning.

       Possible status values are:

       0      Unknown status.  Not normally seen.

       1      The backup is underway, or rsbackup was interrupted.

       2      Backup is complete.

       3      Backup has failed.

       4      Pruning has started.

       5      Pruning has completed.

       finishTimetime
              The time that the backup finished, as a time_t.

       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.

SEE ALSO
       rsbackup-graph(1),  rsbackup.cron(1), rsbackup-mount(1), rsbackup-snap-
       shot-hook(1), rsync(1), rsbackup(5)

AUTHOR
       Richard Kettlewell <rjk@greenend.org.uk>