.\" @(#)hdup.conf.1 1.6.7 18-Mar-2003 OF; 
.TH hdup.conf 5 "18 Mar 2003"
.SH NAME
hdup.conf \- the hdup configuration file
.SH DESCRIPTION
The configuration file syntax of \fBhdup\fR is borrowed from SaMBa (which 
is more commonly known as an ini-style config file).
A '#' as the first character on a line is the start of a comment. Blank lines
are skipped. 

Multiple entries on a line must separated by commas: ",".

Some options can be turned on and off. These are binary options. All binary option
default to 'off'.  They are turned on by 'yes','on' or 'true' 
and are turned off with 'no', 'off' or 'false'. 

The [global] section is required to be the first section in the configuration
files. Options specified under [global] are also used in [host] sections. They
can overridden when they are also specified under that [host] statement. This
works for \fIall\fR options. Further to this, one [host] statement can inherit
from another [host] statement.

Config entries may be given multiple times, in that case the latest one is taken
as the final choice.

It is further best described by an example:

.TS
tab (@);
l l.
#
# backup config for hdup
#
[global]
archive dir = /tmp/storage/
compression = gzip
user = operator
proto = /usr/bin/ssh
proto option = -q -oProtocol=2
overwrite = yes

[host-name-a-conf]
dir = /var/www, /etc/cron.d

[host-name-a-root]
dir = /root/.cpan/Bundle

[host-name-a]
inherit = host-name-a-conf, host-name-a-root
allow remote = yes
.TE

.PP
.SS [global]
The [global] section is required. The keywords specified under it are
used for each host (globally). 

All keywords specified under [global] are inherited by the other hosts. Ie. if
you specify 'compression = gzip' under global, all hosts who do not 
redefine 'compression' will use 'gzip'.

.SS [host-name]
This is a host statement. For every host you want to back up there should be a
host statement. This is also true when you are restoring an archive. 

Host statements can inherit from other host statements. Any keywords 
initialised for the original host, will append to, or overwrite, the 
current keywords.

There is a maximum of 255 different hosts in 1 hdup configuration file.

Be aware that \fIarchive dir\fR \fBmust\fR be specified in the configuration
file, \fIdir\fR is only needed when performing backups. When restoring it is
not needed.

.SS Keywords
The following keywords are supported: 
\fIalgorithm\fR, \fIallow remote\fR, \fIalways backup\fR, \fIarchive dir\fR, \fIchunk size\fR,
\fIcompression\fR,\fIcompression level\fI, \fIdate spec\fR \fIdir\fR, \fIexclude\fR, 
\fIforce\fR, \fIfree\fR, \fIgroup\fR, \fIgpg\fR, \fIinclude\fR, \fIinherit\fR, \fIkey\fR, \fIlog\fR,
\fImcrypt\fR, \fIno history\fR, ,\fInobackup\fR, \fIone filesystem\fR, \fIoverwrite\fR,
\fIpostrun\fR, \fIprerun\fR, \fIproto\fR, \fIproto\fR,
\fIremote hdup\fR, \fIremote hdup option\fR \fIskip\fR, \fIsparse\fR,
\fItar\fR, \fItar option\fR and \fIuser\fR,

The only mandatory options are \fBarchive dir\fR and \fBdir\fR. They must
be present for every host.

.TP
\fBalgorithm\fR
Optional. What algorithm should \fBhdup\fR use when encrypting an archive. If
this is not specified the archive will not be encrypted. Both 'algorithm' and
 'key' must be present. For \fBgpg\fR encryption use \fBgpg\fR here.

.TP
\fBallow remote\fR
Optional, binary option. If 'on' remote archives are allowed to be uploaded from
this host, otherwise they are denied.

.TP
\fBalways backup\fR
Optional, binary option. When 'on' hdup will always perform a backup. Normally
when an incfile is not found the backup is aborted. What this option does is that
if the backup scheme is daily and no weekly incfile is found, hdup performs a
weekly backup. If \fBhdup\fR discovers no monthly incfile when doing a
weekly it performs a monthly dump.

.TP
\fBarchive dir\fR
Mandatory. Specify what directory \fBhdup\fR should use to store the archives
and the (incremental) dump information.

.TP
\fBchunk size\fR
Optional. Give the size of the chunks hdup should create when splitting up an
archive. Size can be given with the suffix 'k', 'K' or 'm', 'M'. Chunks of the
archive get the suffix '__split__XX', where XX is a two letter sequence starting
by 'aa' and ending at 'zz'.  To split up archive in CD sized chunks, \fBchunk
size = 640m\fR could be used.

.TP
\fBcompression\fR
Optional. Specify the compression \fBhdup\fR should use. This can
be \fIbzip\fR, \fIgzip\fR, \fIlzop\fR or \fInone\fI. Defaults to \fIgzip\fR.
Some explanation on the difference might be appropiate here. \fIbzip\fR (which
uses bzip2) is slow but compresses the best, \fIgzip\fR is faster but offers
less compression. \fIlzop\fR is the fastest of them all while offering very
good compression. \fInone\fR is of course the fastest.

.TP
\fBcompression level\fR
Optional. Specify the compression level, it's an integer between 1 and 9
(inclusive), where 1 equals, fast operation, lousy compression and 9 means
best compression, but slow. When omitted it defaults to 6.

Defaults to 6, which for all compression algorithms is the standard
default. 

.TP
\fBdate spec\fR
Optional. The following formats are supported:
.br
\fIdefault\fR  format will be 'DD-MM-YYYY'
.br
\fIiso\fR  format will be 'YYYY-MM-DD'
.br
\fIamerican\fR  format will be 'MM-DD-YYYYY'

.TP
\fBdir\fR 
Mandatory. Specify which directories or files should be backed up. You can also specify
a single file, like \fI/usr/src/linux/.config\fR.

There can be up to 20 different directories specified. There can only be 1 dir statement 
per host.

.TP
\fBexclude\fR 
Optional. Specify a list with a \fIregular\fR expressions that should be used to
determine which files should \fBnot\fR be backed up. See \fIregex(7)\fR for
more information about regular expressions. Also see the section
\fBPATTERNS\fR.

.TP
\fBforce\fR
Optional, binary option. When 'on' a restore to / will be allowed.

.TP
\fBfree\fR
Optional. With \fBfree\fR you can specify how much free space \fImust\fR be
available on a partition. If this free space requirement is not met, \fBhdup\fR
will not perform the backup. Takes an optional size modifier: 'k', 'm' or 'G'.

.TP
\fBgpg\fR
Optional. The path to \fBgpg\fR. Defaults to the value of the configure script.

.TP
\fBgroup\fR
Optional. Specify the group under which the archives must be stored. Defaults
to whatever group 'user' belongs to.

.TP 
\fBinclude\fR 
Optional. Specify a list with a \fIregular\fR expressions that should be used to
determine which files should be backed up. See \fIregex(7)\fR for
more information about regular expressions. Also see the section
\fBPATTERNS\fR. Included files take precedence on exclude files. 

.TP 
\fBinherit\fR 
Optional. Specify a list of \fIhosts\fR to inherit from. All keywords specified
will either overwrite (for single items) or append (for lists) keywords for the
current host. This allows creating specific host configurations out of common
parts.

.TP
\fBkey\fR
Optional. Which file should be used as the encryption key.  Both 'algorithm' and 'key' 
must be present. In the case where \fBalgorithm\fR is \fBgpg\fR the user ID
of the key must be specified here.

.TP
\fBlog\fR
Optional, binary option. When 'on' \fBhdup\fR will also log to syslog. All
message will be logged under LOG_DAEMON with priority LOG_NOTICE. All errors
are logged in the following format:
.br
FAILURE, <hostname>, <error condition>

Succes is reported as:
.br
SUCCESS, <hostname>, <archive size>, <archive time>

If the backup is send to a remote system, <archive size> equals "remote".
If the operation is restore, then <archive size> equals "restore".

.TP
\fBmcrypt\fR
Optional. The path to \fBmcrypt\fR. Defaults to the value of the configure script.

.TP
\fBno history\fR
Optional, binary option. When 'on' \fBhdup\fR will store each archive in a
directory called 'static' thereby not keeping any history of the archives.
WARNING: this option is dangerous to use. When a backup fails and you did not
copy the archives to some safe place you are left with no backups at all!
A postrun script is provided in the examples directory of the hdup source, which
copies the archives to a safe place.
It is best to \fINOT\fR use this option unless you know what you are doing.

Restoring such an archive can be accomplished by using the word 'static' as the
restore date.

.TP
\fBnobackup\fR
Optional. The argument is a filename. When specified \fBhdup\fR looks for
this file in the directories it backs up. If this file is found the current
directory and \fIall\fR sub-directories are \fIexcluded\fR from the backup.

.TP
\fBone filesystem\fR
Optional, binary option. When 'on' \fBhdup\fR will stay in the local file system
for each directory specified (with 'dir') when creating a backup.

.TP
\fBoverwrite\fR
Optional, binary option. When 'on' old archives are overwritten.

.TP
\fBpostrun\fR
Optional. Specify a command or script that be should run \fIafter\fR \fBhdup\fR is
finished with the backup. The following variables can be used as arguments:
.br
\fI%h\fR expands to the current host.
.br
\fI%a\fR expands to the full path of the archivename of the current backup.
.br
\fI%s\fR expands to the current scheme.
.br
\fI%u\fR expands to the username under which the archives are stored.
.br
\fI%e\fR expands to 'yes' when encryption is used, 'no' otherwise.
.br
\fI%c\fR expands to 'yes' when chunksize is used, 'no' otherwise.
.br
\fI%g\fR expands to the groupname under which the archives are stored.

Note: If the postrun script executes with errors the backup is \fInot\fR aborted.
Note2: Any arguments not defined will be expanded to '-empty', without the
quotes.

.TP
\fBprerun\fR
Optional. Specify a command or script that should run \fIbefore\fR \fBhdup\fR begins
with the actual backup. The following variables can be used as arguments:
.br
\fI%h\fR expands to the current host.
.br
\fI%a\fR expands to the full path of the archivename of the current backup.
.br
\fI%s\fR expands to the current scheme.
.br
\fI%u\fR expands to the username under which the archives are stored.
.br
\fI%e\fR expands to 'yes' when encryption is used, 'no' otherwise.
.br
\fI%c\fR expands to 'yes' when chunksize is used, 'no' otherwise.
.br
\fI%g\fR expands to the groupname under which the archives are stored.

Note: If the prerun script executes with errors the backup IS aborted.
Note2: Any arguments not defined will be expanded to '-empty', without the
quotes.

.TP
\fBproto\fR
Optional. Specify the path of the program to use when transferring an archive to a
remote host. Known to work is \fBssh\fR. Defaults to the value of the configure script.

These programs must be able to be used as a filter and support the user@remotehost syntax.

Note: Be aware that this value must also be defined in the remote \fBhdup\fR
which is receiving the backup, although it is not used there. If you don't want
to set it to 'ssh' you can use '/dev/null' or any other path.

.TP
\fBproto option\fR 
Optional. Specify options that are given to the \fBproto\fR command in \fBhdup\fR.
E.g. \fIproto option = -i /home/user/.ssh/identity -oProtocol=2\fR.

.TP
\fBremote hdup\fR
Optional. If the @user@remotehost syntax is used this keyword specifies the
location of the remote \fBhdup\fR.

.TP
\fBremote hdup option\fR
Optional. If the @user@remotehost syntax is used this keyword specifies the
options (like the location of the config file) that should be used by the remote
\fBhdup\fR.

.TP
\fBskip\fR
Optional, binary option. When 'on' the backup directory is automaticly put in
the exclude list and thus not backed up.

.TP
\fBsparse\fR
Optional, binary option. When 'on' hdup will use \fBtar\fR's --sparse feature
when backing up files.

.TP
\fBtar\fR
Optional. The path to \fBtar\fR. Defaults to the value of the configure script.
This \fBtar\fR must support the command line syntax of GNU tar.

.TP
\fBtar option\fR
Optional. Specify some extra options to the \fBtar\fR executed by
\fBhdup\fR. These options are given the tar and untar commands. No extra
checking is done by \fBhdup\fR on these options.

.TP
\fBuser\fR 
Optional. Specify the user under which the archives must be stored. Defaults to
\fIoperator\fR.

.SH PATTERNS
The include and exclude keywords take regular expression as there input.
There is one extra rule. If an expression ends with a slash '/' it is 
only applied to directories. A '/' in a different place is not handled
special.

The whole pathname of a file or directory is used in the pattern matching.
The pattern matching is \fIcase sensitive\fR.

.SS Examples
To match all files ending with .txt use the pattern \fI.*\.txt\fR.
To match everything file under opt, use \fI^/opt\fR. To match a specific
directory in /opt, use \fI^/opt/bla/\fR, note that this excludes all
directories which start with this string.

If you want to match a single directory you must supply the full pathname
and a leading, and closing '/'.

WHAT COMES FIRST include or exclude

.SH AUTHOR
Written by Miek Gieben. Wouter van Gils helped a lot with testing pre-release
versions. User feedback is appreciated.

.SH REPORTING BUGS
Report bugs to <hdup-user@miek.n> or via the bugzilla at the homepage.

.SH COPYRIGHT
Copyright (C) 2001-2005 Miek Gieben. This is free software. There is NO
warrenty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
PURPOSE.

.SH SEE ALSO
\fBhdup\fR(1), \fBregex\fR(7).