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
.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
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
fi
}
+defhook () {
+ hook=$1
+ ## Define a hook called HOOK.
+
+ eval hk_$hook=
+}
+
+addhook () {
+ hook=$1 cmd=$2
+ ## Add command CMD to the hook HOOK.
+
+ eval old=\$hk_$hook; new="$old $cmd"
+ eval hk_$hook=\$new
+}
+
+runhook () {
+ hook=$1; shift 1
+ ## Invoke HOOK, passing it the remaining arguments.
+
+ eval cmds=\$hk_$hook
+ for cmd in $cmds; do
+ if ! $cmd "$@"; then return $?; fi
+ done
+}
+
###--------------------------------------------------------------------------
### Database operations.
done
}
+## Backup hooks.
+defhook setup
+defhook precommit
+defhook postcommit
+
backup_precommit_hook () {
host=$1 fs=$2 date=$3
- ## Override this hook in the configuration file for special effects.
+ ## Compatibility: You can override this hook in the configuration file for
+ ## special effects; but it's better to use `addhook precommit'.
:
}
+addhook precommit backup_precommit_hook
backup_commit_hook () {
host=$1 fs=$2 date=$3
- ## Override this hook in the configuration file for special effects.
+ ## Compatibility: You can override this hook in the configuration file for
+ ## special effects; but it's better to use `addhook commit'.
:
}
+addhook commit backup_commit_hook
do_backup () {
date=$1 fs=$2 fsarg=$3
set -e
attempt=0
+ ## Run a hook beforehand.
+ set +e; runhook setup $host $fs $date; rc=$?; set -e
+ case $? in
+ 0) ;;
+ 99) log "BACKUP of $host:$fs SKIPPED by hook"; return 0 ;;
+ *) log "BACKUP of $host:$fs FAILED (hook returns $?)"; return $? ;;
+ esac
+
## Report the start of this attempt.
log "START BACKUP of $host:$fs"
## Commit this backup.
case $dryrun in
nil)
- backup_precommit_hook $host $fs $date
+ runhook precommit $host $fs $date
mv new $date
mv new.fshash $date.fshash
insert_index $host $fs $date $VOLUME
- backup_commit_hook $host $fs $date
+ runhook commit $host $fs $date
mkdir hack
ln -s $date hack/last
mv hack/last .
###--------------------------------------------------------------------------
### Configuration functions.
+defhook start
+defhook end
+
+done_first_host_p=nil
+
host () {
host=$1
like= userat=
+ case $done_first_host_p in
+ nil) runhook start; done_first_host_p=t ;;
+ esac
case "${expire_policy+t},${default_policy+t}" in
t,) default_policy=$expire_policy ;;
esac
exec 8>&1
. "$conf"
+
+runhook end $bkprc
case "$bkprc" in
0) $verbose "All backups successful" ;;
*) $verbose "Backups FAILED" ;;