Man Linux: Main Page and Category List

NAME

       dirvish - Disk based virtual image network backup system

SYNOPSIS

       dirvish --vault vault [ OPTIONS ]

DESCRIPTION

       Create a backup image of a client directory tree.

       Each image is a directory containing transfer log, summary, tree and if
       transfer errors were detected an rsync_error file.   The  transfer  log
       retains  the the output of any pre and post processing commands and the
       rsync log listing all files  that  were  changed  or  added  with  some
       statistical information.  The summary file contains all the information
       about how the image was created and meta-data for managing the image in
       config file format.  Tree is the copy of the client tree.

       The  client directory tree is compared with an existing image to create
       a new image.  Unchanged files are shared between images.   For  changed
       files  only  those  parts  that actually change are transfered over the
       network.  Unchanged portions of files are  copied  from  the  reference
       image.

       The  resulting  images  contain  complete  copies of the original trees
       preserving ownership and file permissions.  In this way even though the
       backups  are  made  incrementally, each image can be used independently
       for restores or to make removable-media off-site copies or archives.

       The removal of an image will have no effect on other images.

OPTIONS

       Each option on the command line may be specified any number  of  times.
       Those  options  that  support lists in the config files will accumulate
       all of their arguments otherwise each specification will  override  the
       ones before.

       As  configuration  files  are  loaded  they may override options on the
       command line.

       Each option may be unambiguously abbreviated.

       --branch [vault:]branch_name
              Specify a branch to use.

              A branch is a sequence of images.

              If a vault has been specified either here or  with  --vault  the
              first  time  this  option  is  used  it will attempt to load the
              config file branch_name or branch_name.conf from the vault.

       --config config-file
              Load options from the specified file.

              If this precedes --vault the --vault option will not  load  it’s
              own config file.

              If  vault  has  been  set and config-file is a bare filename the
              presence of one in the vault will take precedence  over  one  in
              the  current directory.  To specify one in the current directory
              after --vault use ./ to precede the name.

              The master configuration file will be read prior  to  processing
              options.

       --expire expire_date
              Specify a time for the image to expire.

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

              This  does not actually expire anything.  What it does do is add
              an Expire:  field  to  the  image  summary  file  containing  an
              absolute  time  so that a dirvish-expire or another tool outside
              of dirvish can decide when to remove old images.

       --image image_name
              Specify a name for the image.

              image_name is passed through POSIX::strftime

              See strftime(3) for details.

       --image-time parsedate_expression
              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 details.

       --init Create an initial image.

              Create the image entirely from the source tree without  the  use
              of a reference image.

       --no-run

       --dry-run
              Don’t actually do anything.

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

       --reference branch_name|image_name
              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.

       --reset option
              Reset the values in an accumulating option.

       --summary  short|long
              Specify summary format.

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

              Default value: short

       --vault vault[:branch_name]
              Specify the vault to store the image in.

              If not preceeded by --config  this  will  attempt  to  load  the
              config file default or default.conf within the vault.

              If  branch_name  is specified here this will behave exactly like
              the --branch option and branch_name or branch_name.conf will  be
              attempted instead of default.conf.

       --version
              Print version string and exit.

EXIT CODES

       To  facilitate further automation and integration of dirvish with other
       tools dirvish provides rationalised exit codes.   The  exit  codes  are
       range  based.   While the code for a specific error may change from one
       version to another it will remain within the specified range.  So don’t
       test  for  specific  exit codes but instead test for a range of values.
       To the degree possible higher value ranges indicate more severe errors.

       0      success

       1-19   The backup job reported warnings.

       20-39  An error occurred during index generation and cleanup.

       40-49  A post-client or post-server command could not be run.

       50-59  The post-client command reported an error.  Its exit code modulo
              10 is added to 50

       60-69  The post-server command reported an error.  Its exit code modulo
              10 is added to 60

       70-79  A post-client or post-server command could not be run.

       80-89  The  pre-server command reported an error.  Its exit code modulo
              10 is added to 80

       90-99  The pre-server command reported an error.  Its exit code  modulo
              10 is added to 90

       100-149
              Rsync encountered a non-fatal error.

       150-199
              Rsync encountered a fatal error.

       200-219
              An error was encountered in loading a configuration file.

       220-254
              An error was detected in the configuration.

       255    Incorrect usage.

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.conf(5)
       dirvish-runall(8)
       dirvish-expire(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 AND ISSUES

       Fields  set  in  configuration files will override command line options
       that have been set before the  file  is  read.   This  behaviour  while
       consistent may occasionally confuse.  For this reason most command line
       options should  be  specified  after  any  options  that  may  cause  a
       configuration file to be loaded.

       In  order to preserve permissions it is necessary for dirvish to run as
       root on the backup server.

       The root user must  have  non-interactive  ssh  access  to  the  client
       systems.   It  is not necessary that this access be as the root user on
       the client.

       File ownership is preserved using numeric values so it is not necessary
       to  have user accounts on the backup server.  Making the vaults network
       accessible using protocols that map UIDs  based  on  names  instead  of
       number could allow access controls on files to be violated.

       Making  the  vaults  writable by users will compromise the integrity of
       the backups.  Therefore any access to the vaults  by  users  should  be
       done through a read-only mount.