rsync-backup.{in,8}: Introduce `hook' concept.

[rsync-backup] / rsync-backup.8

diff --git a/rsync-backup.8 b/rsync-backup.8
index 0710158..04a489a 100644 (file)
--- a/rsync-backup.8
+++ b/rsync-backup.8
@@ -141,11 +141,29 @@ The backup is now complete.
 The configuration file is simply a Bash shell fragment: configuration
 commands are shell functions.
 .TP
+.BI "addhook " hook " " command
+Arrange that the named
+.I hook
+runs the given
+.IR command .
+See
+.B runhook
+for more details.
+.TP
 .BI "backup " "fs\fR[:\fIfsarg\fR] ..."
 Back up the named filesystems.  The corresponding
 .IR fsarg s
 may be required by the snapshot type.
 .TP
+.BI "defhook " hook
+Define a new hook named
+.IR hook .
+See
+.B addhook
+and
+.B runhook
+for more information.
+.TP
 .BI "host " host
 Future
 .B backup
@@ -246,6 +264,20 @@ mismatch will be retried up to
 .I count
 times before being declared a failure.
 .TP
+.BI "runhook " hook " " args\fR...
+Invoke the named
+.IR hook .
+The individual commands on the hook are run, in order, as
+.RS
+.IP
+.I command
+.IR args ...
+.PP
+If any command fails (returns nonzero) then no other hooks are run and
+.B runhook
+fails with the same exit code.
+.RE
+.TP
 .BI "snap " type " " \fR[\fIargs\fR...]
 Use the snapshot
 .I type
@@ -352,11 +384,28 @@ 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 Hooks
+The configuration file can modify the behaviour of the backup in two
+main ways: by adding commands to hooks (see the
+.B addhook
+command); and by redefining shell functions.
+.PP
+The following hooks are defined.
 .TP
-.BI "backup_precommit_hook " host " " fs " " date
+.BI "commit " host " " fs " " date
+Called during the commit procedure.  The backup tree and manifest have
+been renamed into their proper places.  Typically one would use this
+hook to rename files created in a corresponding
+.B precommit
+command.
+.TP
+.BI "end " rc
+The backup has completed;
+.B rsync-backup
+will exit with status
+.IR rc .
+.TP
+.BI "precommit " host " " fs " " date
 Called after a backup has been verified complete and about to be
 committed.  The backup tree is in
 .B new
@@ -367,12 +416,26 @@ manifest is in
 A typical action would be to create a digital signature on the
 manifest.
 .TP
+.BI "setup " host " " fs " " date
+Called when a backup of a particular filesystem is about to start.  It
+can return with code 99 to skip the backup.
+.TP
+.B "start"
+Invoked before performing any actual dumps (the first time
+.B host
+is run).
+.PP
+The following shell functions can be redefined by users.
+.TP
 .BI "backup_commit_hook " host " " fs " " date
-Called during the commit procedure.  The backup tree and manifest have
-been renamed into their proper places.  Typically one would use this
-hook to rename files created by the
-.B backup_precommit_hook
-function.
+Called from the
+.B commit
+hook for compatibility.
+.TP
+.BI "backup_precommit_hook " host " " fs " " date
+Called from the
+.B precommit
+hook for compatibility.
 .TP
 .BR "whine " [ \-n ] " " \fItext\fR...
 Called to report `interesting' events when the