X-Git-Url: https://git.distorted.org.uk/~mdw/rsync-backup/blobdiff_plain/2aea457319d4aadc52805c52255a5198d8039db4..c4098e64396d324603341045ca54f8c19caa993b:/rsync-backup.8 diff --git a/rsync-backup.8 b/rsync-backup.8 index 1311403..5ff20bc 100644 --- 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 +.SH NAME +rsync-backup \- back up files using rsync .SH SYNOPSIS .B rsync-backup .RB [ \-nv ] @@ -139,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 @@ -156,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). @@ -242,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 @@ -249,15 +285,55 @@ 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. .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 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) @@ -303,21 +379,33 @@ where .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 . -.SS Hook functions -The configuration file may define shell functions to perform custom -actions at various points in the backup process. +.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 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 @@ -328,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 @@ -437,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 @@ -448,10 +551,12 @@ 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), .BR rsync (1), -.BR ssh (1). +.BR ssh (1), +.BR update-bkp-index (8). .SH AUTHOR Mark Wooding,