X-Git-Url: https://git.distorted.org.uk/~mdw/rsync-backup/blobdiff_plain/1c9c923af8ab55f91a9875d135e7189395302334..c4098e64396d324603341045ca54f8c19caa993b:/rsync-backup.8?ds=inline

diff --git a/rsync-backup.8 b/rsync-backup.8
index 714b63f..5ff20bc 100644
--- 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
@@ -158,7 +176,9 @@ will avoid inefficient and pointless messing about
 in this case.
 This command clears the
 .B like
-list, and resets the retention policy to its default (i.e., the to
+list, the remote
+.B user
+name, and resets the retention policy to its default (i.e., the to
 policy defined prior to the first
 .B host
 command).
@@ -244,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
@@ -251,6 +285,15 @@ for subsequent backups.  Some snapshot types require additional
 arguments, which may be supplied here.  This command clears the
 .B retry
 counter.
+.TP
+.BI "user " name
+Specify the user name on the remote host.  Without this, calls to
+.BR ssh (1)
+and
+.BR rsync (1)
+won't specify any user name, so the default (probably from the
+.BR ssh_config (5)
+file) will apply.
 .SS Configuration variables
 The following shell variables may be overridden by the configuration
 file.
@@ -341,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
@@ -356,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
@@ -465,7 +539,8 @@ 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.
+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
@@ -476,6 +551,7 @@ There is also a symbolic link
 .B last
 referring to the most recent backup of the filesystem.
 .SH SEE ALSO
+.BR check-bkp-status (8),
 .BR fshash (1),
 .BR lvm (8),
 .BR rfreezefs (8),