.TH MRB 8 "May  9, 2006"
.\" Please adjust this date whenever revising the manpage.
.\"
.\" Some roff macros, for reference:
.\" .nh        disable hyphenation
.\" .hy        enable hyphenation
.\" .ad l      left justify
.\" .ad b      justify to both left and right margins
.\" .nf        disable filling
.\" .fi        enable filling
.\" .br        insert line break
.\" .sp <n>    insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.SH NAME
mrb \- manage incremental snapshots with rsync/make.

.SH SYNOPSIS
.B mrb
.I command

.SH DESCRIPTION
.B mrb
is a simple aid to creating efficient incremental snapshots of a set, or
sets, of directories whenever that may be required.  It may be used as part
of a regular automated backup regime, or for manually checkpointing changes
at convenient points in time.

.SH COMMANDS
The following commands are recognised
(where '\fIMODULE\fP' is the name of one of your snapshot definitions):
.TP
.BI new\- MODULE
Create a skeleton definition for a new snapshot '\fIMODULE\fP'.
.TP
.BI dest\- MODULE
Create the destination dir for '\fIMODULE\fP'.
This directory must exist to create a snapshot.
.TP
.BI snap\- MODULE
Create a snapshot of '\fIMODULE\fP'.
.TP
.B sync
Create snapshots of all defined modules.
If run as root this may be configured to include the modules
of other users too (see MRB_SYNC_USERS in ~/.mrb/defaults).
.TP
.B help
Show mrb's own help text.

.SH CONFIGURATION FILES
.SS Per-user configuration
The following files may be used to specify global and local configuration
options.
.TP
.I /etc/default/mrb
system default configuration.
.TP
.I ~/.mrb/defaults
per-user configuration.

.SS Per-user options
The following options control behaviour for all of a user's modules.
.TP
.B MRB_SNAPSHOT_LOG
An optional file path where transfer details will be recorded.  If unset
these details will not be logged.
.TP
.B MRB_SYNC_USERS
A space separated list of users whose modules should be included in a \fBsync\fP.
This is mostly only useful for root, as mrb will assume the identity of
each user before creating snapshots of their modules.  If unset, only
the invoking user's modules will be sync'ed.
.TP
.B MRB_CONFDIR
An space separated list of the directories to search for module definition
(*.mrc) files.  They will be searched in the order given, with new modules
added by default to the last one listed.  There should be few reasons to
change the default value.

.SS Per-module configuration
The default \fBMRB_CONFDIR\fP value will search for module definitions in:
.TP
.I /etc/mrb/*.mrc
.TP
.I ~/.mrb/*.mrc
Those created by
.BI new\- MODULE
will be placed in this latter location by default.

.SS Per-module options
In each case \fImodule\fP below is the name of the particular module that
the value set should apply to.  These options should be defined in a file
named \fImodule\fP.\fBmrc\fP.
.TP
.B module_SRC
A space separated list of the files and (top level) directories to include
in the snapshots for this module.  These may be remote urls.
.TP
.B module_DEST
The (local) directory root where snapshots of \fImodule\fP should be stored.
.TP
.B module_INCLUDE
An optional list of 
.BR rsync (1)
include patterns.
.TP
.B module_EXCLUDE
An optional list of 
.BR rsync (1)
exclude patterns.
.TP
.B module_FILTER
An optional list of 
.BR rsync (1)
filter patterns.
.TP
.B module_FILTER_FILE
An optional filename for 
.BR rsync (1)
dir-merge filtering support.
.TP
.B module_RSYNC_OPTIONS
Optional additional
.BR rsync (1)
options to pass verbatim when it is invoked.
.TP
.B module_PRECOMMAND
An optional shell command to invoke just prior to creating a new snapshot.
If the command does not return a successful exit status, then the snapshot
creation will be aborted before it begins.  It may be used to mount removable
media or similar.
.TP
.B module_POSTCOMMAND
An optional shell command to execute after making the snapshot.  It will not
be called if the snaphot creation failed at an earlier stage, and its return
status may halt a sync operation if it fails with more modules still to process.
It may be used, for example, to unmount removable media again.
.TP
.B module_USER
An optional user name to check that mrb is running as before performing
a snapshot.  This can be used to ensure you have the correct permisson
to access the files being mirrored before you get too far.

.SH SEE ALSO
.BR rsync (1),
.BR make (1).

.SH AUTHOR
mrb was written by Ron <ron@debian.org>.