bionic (5) hdup.conf.5.gz

Provided by: hdup_2.0.14-4ubuntu2_amd64 bug

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 (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).

                                                   18 Mar 2003                                      hdup.conf(5)