Kevin's rsync based backup system readme.
NOTE: This is a work in progress.  Use at your own risk!

Version 0.13

Each backup is defined by a directory named as the name of the backup.
Inside of that directory are settings and tab files instructing the
backup system on what to do when that named backup is run.

There is also a "settings" directory that contains global settings for
all backups.  If a named backup sets the same setting as one in the global
settings file the named backup setting takes priority.

The backup settings go into settings/settings.pl and [backupname]/settings.pl.
The syntax is simply perl variables.  The only setting that must be set is
$BackupRoot.  All others have defaults which are listed and explained below.

The possible settings for those files are:
$BackupRoot="none"; 			# where to backup stuff to
					# backups will be in hostname/_filesystem.date
					# under this path
					# This setting must be set.
$DeletionPool="$BackupRoot/deleteme";	# This is the directory where old
					# backups are moved to when they are
					# ready to be deleted.  This must be
					# on the same filesystem as
					# $BackupRoot so that the move is
					# instant.  Doing this as a move
					# instead of an rm allows the backup
					# system to just do backups instead of
					# having to stop to delete stuff
					# during your backup window.
					# There will be a purge script that
					# will delete everything put into this
					# directory.  It can be either run via
					# cron job at a set time, cron.*
					# whenever that happens, or via l! in
					# the backuptab.
					# This will have no effect if using
					# ZFS snapshots since they can be
					# deleted instantly but it still needs
					# to be defined just because I don't
					# feel like coding more exceptions.
$DefaultNumberOldBackups=30;		# number of backups to keep by default
$HumanReadableOutput="yes";		# Tell rsync to use human readable
					# outputs.
$ItemizeChanges="no";			# Enable --itemize-changes on rsync.
					# Implies verbose mode.
$BackupACLs="no";			# Tells rsync to backup file ACLs (-A)
$BackupXATTRs="no";			# Tells rsync to backup file XATTRs (-X)
$UseNetworkCompression="no";		# want network compression (rsync's -z)?
$UseSSHIdentyFile="none";		# set if you have a non-standard ssh key location
					# or leave on "none" if not.
$ForceChecksum="no";			# set if you want to run rsync with --checksum
					# (slow and rarely needed)
$TransferWholeFiles="no";		# Tell rsync to always transfer whole
					# files instead of using delta xfers.
					# This is faster if doing a local only
					# transfer.
$UpdateFilesInPlace="yes";		# Use --inplace on rsync.  Should not
					# used if files are in use on the
					# backup system (doesn't matter on the
					# backup client).
$BackupIsFAT="no";			# set if your backup device is FAT formatted.
$BackupIsNAS="no";			# set if your backup device is a NAS device.
					# This is not yet implamented but at
					# some time in the future it will
					# provide more optimizations.
$CompensateForFAT="no";			# set if you are backing up a FAT filesystem
					# and want to compensate for the
					# limitations of FAT.
$UseFilterFiles="no";			# set if you use filter files (-F)
$ArchiveMethod="link-dest|cp|zfs";	# what method to use for archiving old backups.
					# Should be global.
					# 
					# link-dest means to use rsync --link-dest (best)
					# 
					# cp is the old cp -al method.  This
					# is very slow and provides no real
					# benefit above link-dest.
					# 
					# zfs is for zfs snapshots.  This is
					# even faster than --link-dest but
					# only works on [Open]Solaris.  Note
					# that this feature has not been
					# written yet as I am hopeful that
					# btrfs in Linux will replace this
					# method in the near future.
$ExtraRsyncParams="";			# Any extra rsync parameters that I
					# didn't think to make options for.
					# Added to the rsync command line as
					# is.  Your responsibility to make
					# sure they work.

Note that ssh specific settings such as user name and port numbers should be
specified in ~/.ssh/config.  Those should not be different between backups and
normal ssh usage so the backups do not have their own settings for them.

In each named backup directory there is a file called backuptab.  This is the list of
what to backup.  It also allows you to run external command to handle things like LVM
snapshots.

The syntaxes for the backuptab file is:
host:/path:n	# does backup with n old copies
		# ("d" means to use the global default, 0 means none)
host:r!command	# runs command on remote end
host:l!command	# runs command on local end (user@host ignored)
host:/*:n	# does a backup of all detected local filesystems
		# (df -lT) except for known unimportant filesystem
		# types (tmpfs iso9660 cd9660 squashfs)
host://:n	# does a backup of the root filesystem without excluding
		# other mount points (no --one-file-system)


The global settings directory and the named backup directories can also contain
files named exclude and include which will be used with rsync's --exclude-from and
--include-from options.

The final file that can be in the named backup directories only is the infotab file.
This file allows information about a backup client to be gathered if that information
is not stored in a file.  This is useful for backing up things like partition tables
or anything else that can be dumped to a text file.

The syntax for the infotab file is:
host:command:file	# ssh host command > file

Incomplete backup handling:
As backups are running they are named backup.incomplete.  If a new backup is
started and backup.incomplete already exists it will be used (completed) with
the backup.current as the link-dest.  Only when the backup is completely
finished with the backup.current symlink be updated and the backup.incomplete
renamed to backup.date.

The default rsync options are:
--archive --one-file-system --hard-links --human-readable --inplace --numeric-ids --delete --delete-excluded --exclude-from=file --link-dest=previousbackup
with --verbose and --progress being added if you run with -v


TODO:
*** optimized offsite replicator!
*** need sparse toggle setting (off by default since it conflicts with --inplace)
*** should have override setting for re-using aborted incompletes
*** need an option to NOT preserve hard links.  This is needed for large Maildir repositories.
*** better error handler