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.