Provided by: dirvish_1.2.1-1.1_all bug

NAME

       dirvish.conf - dirvish configuration file.

DESCRIPTION

       The  dirvish.conf  file  provides configuration information and default
       values for dirvish.

       The file format is  fairly  simple.   Each  option  requires  either  a
       single-value or a list of values and unless otherwise indicated must be
       specified according to its expected type.   Single  value  options  are
       specified  by  lines of the form option: value.  Options expecting list
       must be specified in a multi-line format as shown here where the  lines
       specifying  values  are indented by any kind of whitespace even if only
       one value is being specified.

            option:
                 value1
                 value2
                 .
                 .
                 .
                 valueN
        Each value must be provided on its own line.  Any leading and trailing
       whitespace  is  discarded.  Options whose names with an initial capital
       (ex: Foo) are discarded by dirvish itself but may be  used  by  support
       utilities.  Blank lines are ignored.

       While  this  simplistic  format  may  allow for configuration errors it
       allows arbitrary options to be declared  that  custom  support  scripts
       could use.

       A # introduces a comment to the end of the line.

       On  startup the dirvish utilities will first load a master dirvish.conf
       file.  /etc/dirvish.conf  will  be  tried  first  but  if  not  present
       /etc/dirvish/master.conf will be tried.

       During installation dirvish may have been configured expect the system-
       wide configuration files in some location other than /etc/dirvish.

       Multiple configuration files will be loaded by the --vault and --branch
       command-line  options  as well as the config: and client: configuration
       parameters.  To prevent looping each configuration  file  can  only  be
       loaded once.

DIRVISH OPTIONS

       Like the command line each option may be specified any number of times.
       Those options that expect lists will accumulate all of their  arguments
       and  for single value options each specification will override the ones
       before.

       Boolean values need to specified as 1 or 0 or may  be  specified  using
       SET  or  UNSET.   Some  Boolean  values  are set by default and must be
       explicitly unset if unwanted.

       Each option is marked here with one of  (B)  for  Boolean,  (S)  single
       value, (L) list or (0) other.

       SET option option ... (O)

       UNSET option option ... (O)
              Set or unset one or more boolean options.

              NOTE: The SET and UNSET directives do not use colons <:>.

       RESET option (O)
              Reset a list option so that it contains no values.

              This may be used to start specification of the option.

              NOTE: The RESET directive does not use a colon <:>.

       bank: (L)
              Specify paths to directories containing vaults.

              A bank is a directory containing one or more vaults.  The system
              supports multiple banks so that filesystem mount-points  can  be
              managed more effectively.

              When  a  vault  is  specified the banks will be searched in list
              order until the vault is found.  This way vaults  can  be  moved
              between banks or added without having to update a master index.

              Multiple bank: values will accumulate.

       branch: branch_name (S)
              Specify a branch to use.

              A branch is a sequence of images.

              This also specifies a default value for reference:.

              Setting  this in a config file may cause the command line option
              to be overridden.  Use branch-default: instead.

       branch-default: branch_name (S)
              Specify a default branch to use.

       client: [username@]client_name (S)
              specify a client to back up.

              Setting this to the same value as hostname will cause dirvish to
              do  a  local  copy and stay off the network.  This automatically
              invokes whole-file.

              The first time this parameter is set /etc/dirvish/client_name or
              /etc/dirvish/client_name.conf will be loaded.

       checksum: (B)
              Force  the  checksum  comparison  of file contents even when the
              inode fails to indicate a change has occurred.

              Default value: 0

       config: filename (S)
              Load configuration file.

              Similar to #include, filename or filename.conf  will  be  loaded
              immediately.

              If  filename  is  a  relative  path it will be looked for in the
              vault and then the system-wide configuration directories.

       devices: (B)
              If this is unset device special  files  will  be  excluded  from
              backups.

              This may need to be unset when doing backups of where the client
              OS uses device numbers or types unsupported by the server OSs or
              where  the  presence  of  device  nodes  in  the vault present a
              security issue.

       exclude: (L)
              Specify a filename patterns to exclude.

              Patterns are based on shell glob with some enhancements.

              See rsync(1) for more details.

              Multiple exclude: values will accumulate.

       file-exclude: filename (S)
              Load a set of patterns from a file.

              If filename is a relative path it will  be  looked  for  in  the
              vault and then the system-wide configuration directories.

       expire: expire_date (S)
              Specify a time for the image to expire.

              This  does not actually expire anything.  What it does do is add
              an Expire: option to the image summary file  with  the  absolute
              time  appended  so  that  dirvish-expire  can automate old image
              removal.

              Setting this in a config file may cause the command line  option
              to be overridden.  Use expire-rule: and expire-default: instead.

              See Time::ParseDate(3pm) for more details.

       expire-default: expire_date (S)
              Specify a default expiration time.

              This  value  will  only  be  used  if  expire  is  not  set  and
              expire-rule doesn't have a match.

       expire-rule: (L)
              specify rules for expiration.

              Rules are specified similar to crontab or in Time::Periodformat.

              See EXPIRE RULES for more details.

              Multiple expire-rule: values will accumulate.

       image: image_name (S)
              Specify a name for the image.

              image_name is passed through POSIX::strftime

              Setting this in a config file may cause the command line  option
              to be overridden.  Use image-default: instead.

              See strftime(3) for more details.

       image-default: image_name (S)
              Set the default image_name.

              This value will only be used if image: is not set.

       image-perm: octal_mode (S)
              Set the permissions for the image.

              While the image is being created the image directory permissions
              will be 0700.  After completion it will be changed to octal_mode
              or 0755.

              See chmod(1) and umask(2) for more details.

       image-time: parsedate_expression (S)
              Time to use when creating the image name.

              If an absolute time without a date is provided it will be forced
              into the past.

              If this isn't set the current time will be used.

              See Time::ParseDate(3pm) for more details.

       image-temp: dirname (S)
              Temporary directory name to use for new image.  This allows  you
              to  have images created with the same directory name each run so
              that automatic processes can access them.

              The next time an image is made on the branch  this  option  will
              cause the directory to be renamed to its official name.

       index: none|text|gzip|bzip2 (S)
              Create an index file listing all files in the image.

              The  index  file will be created using find -ls so the list will
              be in the same format as ls-dils with paths converted to reflect
              the source location.

              If index is set to bzip2 or gzip or a path to one the index file
              will be compressed accordingly.

              This index will be used by dirvish-locate to locate versions  of
              files.  See dirvish-locate(8) for more details.

       init: (B)
              Create an initial image.

              Turning this on will prevent backups from being incremental.

       log: text|gzip|bzip2 (S)
              Specify format for the image log file.

              If  log  is  set  to bzip2 or gzip or a path to one the log file
              will be compressed accordingly.

       meta-perm: octal-mode (S)
              Set the permissions for the image meta-data files.

              If this value is set the permissions of the meta-data  files  in
              the image will be changed after the image is created.  Otherwise
              the active umask will prevail.

              SECURITY NOTE: The log, index, and error files contain lists  of
              files.   It  may be possible that filenames themselves may be or
              contain confidential  information  so  uncontrolled  access  may
              constitute a security weakness.

              See chmod(1) and umask(2) for more details.

       numeric-ids: (B)
              Use  numeric  uid/gid  values  instead  of looking up user/group
              names for setting permissions.

              See rsync(1) for more details.

              Default value: 1

       password-file: filepath (S)
              Specify file containing password  for  connection  to  an  rsync
              daemon on backup client.

              This is not useful for remote shell passwords.

              See --password-file in rsync(1) for more details.

       permissions: (B)
              Preserve  file  permissions.   If this is unset permissions will
              not be checked or preserved.

              With rsync version 2.5.6 not preserving permissions  will  break
              the linking.  Only unset this if you are running a later version
              of rsync.

              See rsync(1) for more details.

              Default value: 1

       pre-server: shell_command (S)

       pre-client: shell_command (S)

       post-client: shell_command (S)

       post-server: shell_command (S)
              Execute shell_command on client or server before or after making
              backup.

              The  client  commands  are  run  on  the client system using the
              remote shell command (see the rsh: parameter).

              The  order  of  execution  is  pre-server,  pre-client,   rsync,
              post-client,  post-server.   The  shell_command  will  be passed
              through strftime(3) to allow date strings to be expanded.

              Each  pre  or  post  shell_commands  will  be  run  with   these
              environment     variables     DIRVISH_SERVER,    DIRVISH_CLIENT,
              DIRVISH_SRC, DIRVISH_DEST and DIRVISH_IMAGE  set.   The  current
              directory  will be DIRVISH_SRC on the client and DIRVISH_DEST on
              the server.  If there  are  any  exclude  patterns  defined  the
              pre-server  shell command will also have the exclude file's path
              in DIRVISH_EXCLUDE so it may read or modify the exlude list.

              STDOUT from each shell_command will be written to the image  log
              file.

              The exit status of each script will be checked.  Non-zero values
              will be recognised  as  failure  and  logged.   Failure  of  the
              pre-server command will halt all further action.  Failure of the
              pre-client command will prevent the rsync from running  and  the
              post-server command, if any, will be run.

              Post   shell_commands  will  also  have  DIRVISH_STATUS  set  to
              success, warning, error, or fatal error.

              This is useful for multiple things.  The  client  shell_commands
              can  be  used  to  stop and start services so their files can be
              backed up  safely.   You  might  use  post-server:  to  schedule
              replication  or  a  tape  backup  of  the  new  image.  Use your
              imagination.

       reference: branch_name|image_name (S)
              Specify an existing image or a branch from which to  create  the
              new image.

              If  a branch_name is specified, the last existing image from its
              history file will be used.  A branch will take  precedence  over
              an image of the same name.

              If  this  isn't  specified  the  branch  name  will be used as a
              default value.

       rsh: command (S)
              Remote shell utility.

              This can be used to specify the location of ssh or rsh and/or to
              provide  addition  options  for said utility such as -p port for
              ssh to use an alternate port number.

              If not specified ssh will be used.

              This remote shell command will be used not only as  the  default
              rsync  transport  but  also  for  any pre-client and post-client
              commands.

       rsync: command (S)
              Path to rsync executable on the server.

       rsync-client: command (S)
              Path to rsync executable on the client.

       rsync-option: (L)
              Specify additional options for the rsync command.

              Only one option per list item is supported.

              This allows you to use rsync  features  that  are  not  directly
              supported  by  dirvish.   Where  dirvish  does  support an rsync
              feature it is probably better to use the  the  dirvish  supplied
              mechanism for setting it.

              Multiple rsync-option: values will accumulate.

       sparse: (B)
              Try  to  handle  sparse  files  efficiently so they take up less
              space in the vault.

              NOTE: Some filesystem types may have problems seeking over  null
              regions.

       speed-limit: Mbps (S)
              Specify a maximum transfer rate.

              This  allows  you  to limit the network bandwidth consumed.  The
              value is specified in approximate  Mega-bits  per  second  which
              correlates  to  network  transport  specifications.  An adaptive
              algorithm is used so the actual bandwidth usage may exceed  Mbps
              occasionally.

              See --bwlimit in rsync(1) for more details.

       stats: (B)
              Have rsync report transfer statistics.

              See rsync(1) for more details.

              Default value: 1

       summary: short|long (S)
              Specify summary format.

              A  short  summary  will  only include final used values.  A long
              summary will include all configuration values.

              With long format you custom options in the  configuration  files
              will appear in the summary.

              The default is short.

       tree: path [alias] (S)
              Specify a directory path on the client to backup.

              If  path is prefixed with a colon the transfer will be done from
              an rsync daemon on the client otherwise  the  transfer  will  be
              done through a remote shell process.

              The  optional alias specifies the path that should appear in the
              index  so  dirvish-locate  will  report  paths  consistant  with
              common  usage.  This can help reduce confusion when dealing with
              users unfamiliar with the physical  topology  of  their  network
              provided files.

       no-run: (B)
              Don't actually do anything.

              Process  all configuration files, options and tests then produce
              a summary/configuration file on standard output and exit.

              I can't think why you would do this in a configuration file  but
              if you want to shoot yourself in the foot, be my guest.

       vault: vault (S)
              Specify the vault to store the image in.

              Although  multiple  vaults  may share a filesystem a given vault
              cannot span filesystems.  For filesystem purposes the  vault  is
              the level of atomicity.

              This will seldom be specified in a configuration file.

       whole-file: (B)
              Transfer  whole  files  instead  of  just  the  parts  that have
              changed.

              This may be slightly faster for files  that  have  more  changed
              than  left  the  same such as compressed or encrypted files.  In
              most cases this  will  be  slower  when  transferring  over  the
              network but will use less CPU resources.  This will be faster if
              the transfers are not over the network or when  the  network  is
              faster than the destination disk subsystem.

       xdev: (B)
              Do  not  cross  mount-points  when  traversing  the  tree on the
              client.

       zxfer: (B)
              Enable compression on data-transfer.

SCHEDULING OPTIONS

       Dirvish: path (S)
              Location of dirvish executable.

              If not set defaults to dirvish.

       Runall: (L)
              Specify branches to be scheduled for  automated  backups.   Each
              value is specified in the form
                   vault:branch [image_time]

              If image_time is set here it will be used.

              This option can only be set in the master configuration file and
              multiple values will accumulate.

EXPIRE RULES

       Expire rules is a list of rules used to determine  an  expiration  time
       for an image.

       The  last  rule  that  matches will apply so list order is significant.
       This allows rules to be set in client, vault and  branch  configuration
       files  to  override  rules set in the master configuration file without
       having  to  use  RESET.   In  most  cases  it  is  better  to   use   a
       expire-default:  value  than to define a rule that matches all possible
       times.

       Each rule has an pattern expression against which the current  time  is
       compared  followed  by a date specifier in Time::ParseDate format.  See
       Time::ParseDate(3pm) for more details.

       A matching rule with an  empty/missing  date  specifier  or  specifying
       never will result in no expiration.

       The time pattern expression may be in either crontab or in Time::Period
       format.  See crontab(5) and Time::Period(3pm) for more details.

       The crontab formated patterns are converted to Time::Period  format  so
       the  limitations  and extensions for the specification of option values
       of Time::Period apply to the crontab format as well.  Most  notable  is
       that  the  days  of the week are numbered 1-7 for sun-sat so 0 is not a
       valid wday but sat
        is.

       Here are two equivalent examples of an expire-rule list.

            expire-default: +5 weeks
            expire-rule:

            #MIN  HR    DOM   MON         DOW   EXPIRE
            *     *     *     *           1     +3 months
            *     *     1-7   *           su    +1 year
            *     *     1-7   1,4,7,10    1     never
            *     10-20 *     *           *     +10 days
       or:
            wd { sun }                          +3 months
            wd { sun } md { 1-7 }               +1 year
            wd { 1 } md { 1-7 } mo { 1,4,7,10 } never
            hr { 10-20 }                        +10 days

       This describes is an aggressive retention  schedule.   If  the  nightly
       backup  is  made  dated  the  1st  Sunday of each quarter it is is kept
       forever, the 1st Sunday of any other month is  kept  for  1  year,  all
       other  Sunday's are kept for 3 months, the remaining nightlies are kept
       for 5 weeks.  In addition, if the backup is made between 10AM  and  8PM
       it  will  expire  after 10 days.  This would be appropriate for someone
       with a huge backup server who is so paranoid he makes two  backups  per
       day.   The  other  possibility  for  the  hour spec would be for ad-hoc
       special backups to have a default that differs from the normal dailies.

       It should be noted that all  expiration  rules  will  do  is  to  cause
       dirvish   to   put   an  Expire:  option  in  the  summary  file.   The
       dirvish-expire utility will have to  be  run  to  actually  delete  any
       expired images.

FILES

       /etc/dirvish/master.conf
              alternate master configuration file.

       /etc/dirvish.conf
              master configuration file.

       /etc/dirvish/client[.conf]
              client configuration file.

       bank/vault/dirvish/default[.conf]
              default vault configuration file.

       bank/vault/dirvish/branch[.conf]
              branch configuration file.

       bank/vault/dirvish/branch.hist
              branch history file.

       bank/vault/image/summary
              image creation summary.

       bank/vault/image/log
              image creation log.

       bank/vault/image/tree
              actual image of source directory tree.

       bank/vault/image/rsync_error
              Error output from rsync if errors or warnings were detected.

SEE ALSO

       dirvish(8)
       dirvish-expire(8)
       dirvish-runall(8)
       dirvish-locate(8)
       ssh(1),
       rsync(1)
       Time::ParseDate(3pm)
       strftime(3)

AUTHOR

       Dirvish was created by J.W. Schultz of Pegasystems Technologies.

BUGS

       Rsync  version  2.5.6 has a bug so that unsetting the perms option will
       not disable testing for permissions.  Disabling perms will break  image
       linking.

       Options  set  in configuration files will override command line options
       that have been set before the  file  is  read.   This  behaviour  while
       consistent may confuse users.  For this reason the more frequently used
       command line options have options paired with a default option  so  the
       order  of specification will be more forgiving.  It is recommended that
       where such default options exist in configuration files they should  be
       preferred over the primary option.

       It  is  possible to specify almost any command line option as a option.
       Some of them just don't make sense to use here.

                                                               DIRVISH.CONF(5)