Provided by: dirvish_1.2.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)