Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
DIRVISH(8)		    System Manager's Manual		    DIRVISH(8)

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  sta-
       tistical	 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 im-
       age.

       The resulting images contain complete copies of the original trees pre-
       serving 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 com-
       mand 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 con-
	      fig 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	 abso-
	      lute  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 con-
	      fig 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  con-
       sistent	may  occasionally  confuse.  For this reason most command line
       options should be specified after any options that may cause a configu-
       ration 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  sys-
       tems.   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 num-
       ber 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.

								    DIRVISH(8)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | EXIT CODES | FILES | SEE ALSO | AUTHOR | BUGS AND ISSUES

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=dirvish&sektion=8&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help