hdup.conf - the hdup configuration file

NAME

       hdup.conf - the hdup configuration file

DESCRIPTION

The configuration file syntax of hdup 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 all 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:

#
# 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

[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’.

[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 archive dir must be specified in the configuration file,
dir is only needed when performing backups. When restoring it is not
needed.

Keywords
The following keywords are supported: algorithm, allow remote, always
backup, archive dir, chunk size, compression,compression level, date
spec dir, exclude, force, free, group, gpg, include, inherit, key, log,
mcrypt, no history, ,nobackup, one filesystem, overwrite, postrun,
prerun, proto, proto option, remote hdup, remote hdup option, skip,
sparse, tar, tar option and user,

The only mandatory options are archive dir and dir. They must be
present for every host.

algorithm
Optional. What algorithm should hdup use when encrypting an
archive. If this is not specified the archive will not be
encrypted. Both ’algorithm’ and
’key’ must be present. For gpg encryption use gpg here.

allow remote
Optional, binary option. If ’on’ remote archives are allowed to
be uploaded from this host, otherwise they are denied.

always backup
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 hdup discovers no monthly incfile when doing a weekly
it performs a monthly dump.

archive dir
Mandatory. Specify what directory hdup should use to store the
archives and the (incremental) dump information.

chunk size
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, chunk size = 640m could be used.

compression
Optional. Specify the compression hdup should use. This can be
bzip, gzip, lzop or none. Defaults to gzip. Some explanation on
the difference might be appropiate here. bzip (which uses bzip2)
is slow but compresses the best, gzip is faster but offers less
compression. lzop is the fastest of them all while offering very
good compression. none is of course the fastest.

compression level
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.

date spec
Optional. The following formats are supported:
default format will be ’DD-MM-YYYY’
iso format will be ’YYYY-MM-DD’
american format will be ’MM-DD-YYYYY’

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

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

exclude
Optional. Specify a list with a regular expressions that should
be used to determine which files should not be backed up. See
regex(7) for more information about regular expressions. Also
see the section PATTERNS.

force Optional, binary option. When ’on’ a restore to / will be
allowed.

free Optional. With free you can specify how much free space must be
available on a partition. If this free space requirement is not
met, hdup will not perform the backup. Takes an optional size
modifier: ’k’, ’m’ or ’G’.

gpg Optional. The path to gpg. Defaults to the value of the
configure script.

group Optional. Specify the group under which the archives must be
stored. Defaults to whatever group ’user’ belongs to.

include
Optional. Specify a list with a regular expressions that should
be used to determine which files should be backed up. See
regex(7) for more information about regular expressions. Also
see the section PATTERNS. Included files take precedence on
exclude files.

inherit
Optional. Specify a list of hosts 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.

key Optional. Which file should be used as the encryption key. Both
’algorithm’ and ’key’ must be present. In the case where
algorithm is gpg the user ID of the key must be specified here.

log Optional, binary option. When ’on’ hdup 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:
FAILURE, <hostname>, <error condition>

Succes is reported as:
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".

mcrypt Optional. The path to mcrypt. Defaults to the value of the
configure script.

no history
Optional, binary option. When ’on’ hdup 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 NOT 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.

nobackup
Optional. The argument is a filename. When specified hdup looks
for this file in the directories it backs up. If this file is
found the current directory and all sub-directories are excluded
from the backup.

one filesystem
Optional, binary option. When ’on’ hdup will stay in the local
file system for each directory specified (with ’dir’) when
creating a backup.

overwrite
Optional, binary option. When ’on’ old archives are overwritten.

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

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

prerun Optional. Specify a command or script that should run before
hdup begins with the actual backup. The following variables can
be used as arguments:
%h expands to the current host.
%a expands to the full path of the archivename of the current
backup.
%s expands to the current scheme.
%u expands to the username under which the archives are stored.
%e expands to ’yes’ when encryption is used, ’no’ otherwise.
%c expands to ’yes’ when chunksize is used, ’no’ otherwise.
%g 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.

proto Optional. Specify the path of the program to use when
transferring an archive to a remote host. Known to work is ssh.
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 hdup 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.

proto option
Optional. Specify options that are given to the proto command in
hdup. E.g. proto option = -i /home/user/.ssh/identity
-oProtocol=2.

remote hdup
Optional. If the @user@remotehost syntax is used this keyword
specifies the location of the remote hdup.

remote hdup option
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 hdup.

skip Optional, binary option. Depricated, it is always ’on’. When
’on’ the backup directory is automaticly put in the exclude list
and thus not backed up.

sparse Optional, binary option. Depricated, it is always ’on’. When
’on’ hdup will use tar’s --sparse feature when backing up files.

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

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

user Optional. Specify the user under which the archives must be
stored. Defaults to operator.

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 case sensitive.

   Examples
       To  match  all files ending with .txt use the pattern .*.txt.  To match
       everything file under opt, use ^/opt. To match a specific directory  in
       /opt,  use  ^/opt/bla/,  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

AUTHOR

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

REPORTING BUGS

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

COPYRIGHT