Merge branch 'staging'

[rsync-backup] / rsync-backup.8

diff --git a/rsync-backup.8 b/rsync-backup.8
index 20682ea..714b63f 100644 (file)
--- a/rsync-backup.8
+++ b/rsync-backup.8
@@ -5,6 +5,8 @@
 \h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
 ..
 .TH rsync-backup 8 "7 October 2012" rsync-backup
 \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 [ \-nv ]
 .SH SYNOPSIS
 .B rsync-backup
 .RB [ \-nv ]


@@ -156,7 +158,10 @@ will avoid inefficient and pointless messing about
 in this case.
 This command clears the
 .B like
 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
 .TP
 .BI "like " "host\fR ..."
 Declare that subsequent filesystems are `similar' to like-named


@@ -197,6 +202,32 @@ 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.
 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
 .TP
 .BI "retry " count
 The


@@ -224,11 +255,42 @@ counter.
 The following shell variables may be overridden by the configuration
 file.
 .TP
 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 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)
 .B RSYNCOPTS
 Command-line options to pass to
 .BR rsync (1)


@@ -274,16 +336,11 @@ where
 .I mntbkpdir
 is the backup mount directory configured at build time.
 .TP
 .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.
 .SS Hook functions
 The configuration file may define shell functions to perform custom
 actions at various points in the backup process.


@@ -415,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.
 .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),
 .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>
 .SH AUTHOR
 Mark Wooding, <mdw@distorted.org.uk>