X-Git-Url: https://git.distorted.org.uk/~mdw/rsync-backup/blobdiff_plain/f6b4ffdc7265b79b945e2350efbd9d2a94df4450..977d0da99bb1ccfdbdcbccbb0fd059662c30737b:/rsync-backup.8?ds=sidebyside diff --git a/rsync-backup.8 b/rsync-backup.8 index 3d2cffc..e8276e4 100644 --- a/rsync-backup.8 +++ b/rsync-backup.8 @@ -1,7 +1,15 @@ +.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 NAME +rsync-backup \- back up files using rsync .SH SYNOPSIS .B rsync-backup -.RB [ \-v ] +.RB [ \-nv ] .RB [ \-c .IR config-file ] .SH DESCRIPTION @@ -40,10 +48,95 @@ security disaster. Remember that the backup server is, in the end, 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. @@ -58,9 +151,17 @@ Future .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 @@ -87,7 +188,7 @@ can be .BR weekly , .BR monthly , or -.B annually +.B annually (or .BR yearly , which means the same); the @@ -101,12 +202,53 @@ or 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. +.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. +.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. @@ -120,9 +262,15 @@ value is 14. 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 @@ -261,3 +409,46 @@ type handlers: please see the script for details. Please send the 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,