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
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).
.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
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.
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
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
.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
.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),