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¶
Copyright (C) 2001-2005 Miek Gieben. This is free software. There is NO
warrenty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
SEE ALSO¶
hdup(1),
regex(7).