+.ie t .ds o \(bu
+.el .ds o o
+.de hP
+.IP
+\h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
+..
.TH rsync-backup 8 "7 October 2012" rsync-backup
.SH SYNOPSIS
.B rsync-backup
-.RB [ \-v ]
+.RB [ \-nv ]
.RB [ \-c
.IR config-file ]
.SH DESCRIPTION
responsible for the integrity of the backup data. A dishonest backup
server can easily compromise a client which is being restored from
corrupt backup data.)
+.SS Command-line options
+Most of the behaviour of
+.B rsync-backup
+is controlled by a configuration file, described starting with the
+section named
+.B Configuration commands
+below.
+But a few features are controlled by command-line options.
+.TP
+.B \-h
+Show a brief help message for the program, and exit successfully.
+.TP
+.B \-V
+Show
+.BR rsync-backup 's
+version number and some choice pieces of build-time configuration, and
+exit successfully.
+.TP
+.BI "\-c " conf
+Read
+.I conf
+instead of the default configuration file (shown as
+.B conf
+in the
+.B \-V
+output).
+.TP
+.B \-n
+Don't actually take a backup, or write proper logs: instead, write a
+description of what would be done to standard error.
+.TP
+.B \-v
+Produce verbose progress information on standard output while the backup
+is running. This keeps one amused while running a backup
+interactively. In any event,
+.B rsync-backup
+will report failures to standard error, and otherwise run silently, so
+it doesn't annoy unnecessarily if run by
+.BR cron (8).
+.SS Backup process
+Backing up a filesystem works as follows.
+.hP \*o
+Make a snapshot of the filesystem on the client, and ensure that the
+snapshot is mounted. There are some `trivial' snapshot types which use
+the existing mounted filesystem, and either prevent processes writing to
+it during the backup, or just hope for the best. Other snapshot types
+require the snapshot to be mounted somewhere distinct from the main
+filesystem, so that the latter can continue being used.
+.hP \*o
+Run
+.B rsync
+to copy the snapshot to the backup volume \(en specifically, to
+.IB host / fs / new \fR.
+If this directory already exists, then it's presumed to be debris from a
+previous attempt to dump this filesystem:
+.B rsync
+will update it appropriately, by adding, deleting or modifying the
+files. This means that retrying a failed dump \(en after fixing whatever
+caused it to go wrong, obviously! \(en is usually fairly quick.
+.hP \*o
+Run
+.B fshash
+on the client to generate a `digest' describing the contents of the
+filesystem, and send this to the server as
+.IB host / fs / new .fshash \fR.
+.hP \*o
+Release the snapshot: we don't need it any more.
+.hP \*o
+Run
+.B fshash
+over the new backup; specifically, to
+.BI tmp/fshash. host . fs . date \fR.
+This gives us a digest for what the backup volume actually stored.
+.hP \*o
+Compare the two
+.B fshash
+digests. If they differ then dump the differences to the log file and
+report a backup failure. (Backups aren't any good if they don't
+actually back up the right thing. And you stand a better chance of
+fixing them if you know that they're going wrong.)
+.hP \*o
+Commit the backup, by renaming the dump directory to
+.IB host / fs / date
+and the
+.B fshash
+digest file to
+.IB host / fs / date .fshash \fR.
.PP
-The
-
-
+The backup is now complete.
.SS Configuration commands
The configuration file is simply a Bash shell fragment: configuration
commands are shell functions.
.B backup
commands will back up filesystems on the named
.IR host .
-This clears the
+To back up filesystems on the backup server itself, use its hostname:
+.B rsync-backup
+will avoid inefficient and pointless messing about
+.BR ssh (1)
+in this case.
+This command clears the
.B like
-list.
+list, and resets the retention policy to its default (i.e., the to
+policy defined prior to the first
+.B host
+command).
.TP
.BI "like " "host\fR ..."
Declare that subsequent filesystems are `similar' to like-named
.BR weekly ,
.BR monthly ,
or
-.B annually
+.B annually
(or
.BR yearly ,
which means the same); the
Expiry considers each existing dump against the policy lines in order:
the last applicable line determines the dump's fate \(en so you should
probably write the lines in decreasing order of duration.
+.RS
+.PP
+Groups of
+.B retain
+commands between
+.B host
+and/or
+.B backup
+commands collectively define a retention policy. Once a policy is
+defined, subsequent
+.B backup
+operations use the policy. The first
+.B retain
+command after a
+.B host
+or
+.B backup
+command clears the policy and starts defining a new one. The policy
+defined before the first
+.B host
+is the
+.I default
+policy: at the start of each
+.B host
+stanza, the policy is reset to the default.
+.RE
+.TP
+.BI "retry " count
+The
+.B live
+snapshot type (see below) doesn't prevent a filesystem from being
+modified while it's being backed up. If this happens, the
+.B fshash
+pass will detect the difference and fail. If the filesystem in question
+is relatively quiescent, then maybe retrying the backup will result in a
+successful consistent copy. Following this command, a backup which
+results in an
+.B fshash
+mismatch will be retried up to
+.I count
+times before being declared a failure.
.TP
.BI "snap " type " " \fR[\fIargs\fR...]
Use the snapshot
.I type
for subsequent backups. Some snapshot types require additional
-arguments, which may be supplied here.
+arguments, which may be supplied here. This command clears the
+.B retry
+counter.
.SS Configuration variables
The following shell variables may be overridden by the configuration
file.
Command-line options to pass to
.BR rsync (1)
in addition to the basic set:
-.B \-\-archive \-\-hard-links \-\-numeric-ids \-\-del \-\-sparse
-.B \-\-compress \-\-one-file-system \-\-partial
-.B \-\-filter="dir-merge .rsync-backup"
+.B \-\-archive
+.B \-\-hard-links
+.B \-\-numeric-ids
+.B \-\-del
+.B \-\-sparse
+.B \-\-compress
+.B \-\-one-file-system
+.B \-\-partial
+.BR "\-\-filter=""dir-merge .rsync-backup""" .
The default is
.BR \-\-verbose .
.TP
author interesting snapshot handlers for inclusion in the main
distribution.
.SS Archive structure
+Backup trees are stored in a fairly straightforward directory tree.
+.PP
+At the top level is one directory for each client host. There are also
+some special entries:
+.TP
+.B \&.rsync-backup-store
+This file must be present in order to indicate that a backup volume is
+present (and not just an empty mount point).
+.TP
+.B fshash.cache
+The cache database used for improving performance of local file
+hashing. There may be other
+.B fshash.cache-*
+files used by SQLite for its own purposes.
+.TP
+.B lost+found
+Part of the filesystem used on the backup volume. You don't want to
+mess with this.
+.TP
+.B tmp
+Used to store temporary files during the backup process. (Some of them
+want to be on the same filesystem as the rest of the backup.) When
+things go wrong, files are left behind in the hope that they might help
+someone debug the mess. It's always safe to delete the files in here
+when no backup is running.
+.PP
+So don't use those names for your hosts.
+.PP
+The next layer down contains a directory for each filesystem on the given host.
+.PP
+The bottom layer contains a directory for each dump of that filesystem,
+named with the date at which the dump was started (in ISO8601
+.IB yyyy \(en mm \(en dd
+format), together with associated files named
+.IB date .* \fR.
+.SH SEE ALSO
+.BR fshash (1),
+.BR lvm (8),
+.BR rfreezefs (8),
+.BR rsync (1),
+.BR ssh (1).
+.SH AUTHOR
+Mark Wooding, <mdw@distorted.org.uk>
~mdw / rsync-backup / blobdiff