X-Git-Url: https://git.distorted.org.uk/~mdw/rsync-backup/blobdiff_plain/6037bdb376603e4572a2ec57c5335eed7496731d..1c9c923af8ab55f91a9875d135e7189395302334:/rsync-backup.8

diff --git a/rsync-backup.8 b/rsync-backup.8
index a265352..714b63f 100644
--- a/rsync-backup.8
+++ b/rsync-backup.8
@@ -5,9 +5,11 @@
 \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
@@ -73,6 +75,10 @@ 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
@@ -152,7 +158,10 @@ will avoid inefficient and pointless messing about
 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
@@ -193,21 +202,95 @@ 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.
+.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.
 .TP
+.B HASH
+The hash function to use for verifying archive integrity.  This is
+passed to the
+.B \-H
+option of
+.BR fshash ,
+so it must name one of the hash functions supported by your Python's
+.B hashlib
+module.
+The default is
+.BR sha256 .
+.TP
+.B INDEXDB
+The name of a SQLite database initialized by
+.BR update-bkp-index (8)
+in which an index is maintained of which dumps are on which backup
+volumes.  If the file doesn't exist, then no index is maintained.  The
+default is
+.IB localstatedir /lib/bkp/index.db
+where
+.I localstatedir
+is the state directory configured at build time.
+.TP
 .B MAXLOG
 The number of log files to be kept for each filesystem.  Old logfiles
 are deleted to keep the total number below this bound.  The default
 value is 14.
 .TP
+.B METADIR
+The metadata directory for the currently mounted backup volume.
+The default is
+.IB mntbkpdir /meta
+where
+.I mntbkpdir
+is the backup mount directory configured at build time.
+.TP
 .B RSYNCOPTS
 Command-line options to pass to
 .BR rsync (1)
@@ -253,16 +336,11 @@ where
 .I mntbkpdir
 is the backup mount directory configured at build time.
 .TP
-.B HASH
-The hash function to use for verifying archive integrity.  This is
-passed to the
-.B \-H
-option of
-.BR fshash ,
-so it must name one of the hash functions supported by your Python's
-.B hashlib
-module.  The default is
-.BR sha256 .
+.B VOLUME
+The name of the current volume.  If this is left unset, the volume name
+is read from the file
+.IB METADIR /volume
+once at the start of the backup run.
 .SS Hook functions
 The configuration file may define shell functions to perform custom
 actions at various points in the backup process.
@@ -394,11 +472,15 @@ 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.
+There is also a symbolic link
+.B last
+referring to the most recent backup of the filesystem.
 .SH SEE ALSO
 .BR fshash (1),
 .BR lvm (8),
 .BR rfreezefs (8),
 .BR rsync (1),
-.BR ssh (1).
+.BR ssh (1),
+.BR update-bkp-index (8).
 .SH AUTHOR
 Mark Wooding, <mdw@distorted.org.uk>