1DIRVISH(8) System Manager's Manual DIRVISH(8)
2
6 dirvish - Disk based virtual image network backup system
7
9 dirvish --vault vault [ OPTIONS ]
10
12 Create a backup image of a client directory tree.
13 Each image is a directory containing transfer log, summary, tree and if
15 transfer errors were detected an rsync_error file. The transfer log
16 retains the the output of any pre and post processing commands and the
17 rsync log listing all files that were changed or added with some sta‐
18 tistical information. The summary file contains all the information
19 about how the image was created and meta-data for managing the image in
20 config file format. Tree is the copy of the client tree.
21 The client directory tree is compared with an existing image to create
23 a new image. Unchanged files are shared between images. For changed
24 files only those parts that actually change are transfered over the
25 network. Unchanged portions of files are copied from the reference
26 image.
27 The resulting images contain complete copies of the original trees pre‐
29 serving ownership and file permissions. In this way even though the
30 backups are made incrementally, each image can be used independently
31 for restores or to make removable-media off-site copies or archives.
32 The removal of an image will have no effect on other images.
34
36 Each option on the command line may be specified any number of times.
37 Those options that support lists in the config files will accumulate
38 all of their arguments otherwise each specification will override the
39 ones before.
40 As configuration files are loaded they may override options on the com‐
42 mand line.
43 Each option may be unambiguously abbreviated.
45 --branch [vault:]branch_name
47 Specify a branch to use.
48 A branch is a sequence of images.
50 If a vault has been specified either here or with --vault the
52 first time this option is used it will attempt to load the con‐
53 fig file branch_name or branch_name.conf from the vault.
54 --config config-file
56 Load options from the specified file.
57 If this precedes --vault the --vault option will not load it's
59 own config file.
60 If vault has been set and config-file is a bare filename the
62 presence of one in the vault will take precedence over one in
63 the current directory. To specify one in the current directory
64 after --vault use ./ to precede the name.
65 The master configuration file will be read prior to processing
67 options.
68 --expire expire_date
70 Specify a time for the image to expire.
71 See Time::ParseDate(3pm) for details.
73 This does not actually expire anything. What it does do is add
75 an Expire: field to the image summary file containing an abso‐
76 lute time so that a dirvish-expire or another tool outside of
77 dirvish can decide when to remove old images.
78 --image image_name
80 Specify a name for the image.
81 image_name is passed through POSIX::strftime
83 See strftime(3) for details.
85 --image-time parsedate_expression
87 Time to use when creating the image name.
88 If an absolute time without a date is provided it will be forced
90 into the past. If this isn't set the current time will be used.
91 See Time::ParseDate(3pm) for details.
93 --init Create an initial image.
95 Create the image entirely from the source tree without the use
97 of a reference image.
98 --no-run
100 --dry-run
102 Don't actually do anything.
103 Process all configuration files, options and tests then produce
105 a summary/configuration file on standard output and exit.
106 --reference branch_name|image_name
108 Specify an existing image or a branch from which to create the
109 new image.
110 If a branch_name is specified, the last existing image from its
112 history file will be used. A branch will take precedence over
113 an image of the same name.
114 --reset option
116 Reset the values in an accumulating option.
117 --summary short|long
119 Specify summary format.
120 A short summary will only include final used values. A long
122 summary will include all configuration values.
123 Default value: short
125 --vault vault[:branch_name]
127 Specify the vault to store the image in.
128 If not preceeded by --config this will attempt to load the con‐
130 fig file default or default.conf within the vault.
131 If branch_name is specified here this will behave exactly like
133 the --branch option and branch_name or branch_name.conf will be
134 attempted instead of default.conf.
135 --version
137 Print version string and exit.
138
140 To facilitate further automation and integration of dirvish with other
141 tools dirvish provides rationalised exit codes. The exit codes are
142 range based. While the code for a specific error may change from one
143 version to another it will remain within the specified range. So don't
144 test for specific exit codes but instead test for a range of values.
145 To the degree possible higher value ranges indicate more severe errors.
146 0 success
148 1-19 The backup job reported warnings.
150 20-39 An error occurred during index generation and cleanup.
152 40-49 A post-client or post-server command could not be run.
154 50-59 The post-client command reported an error. Its exit code modulo
156 10 is added to 50
157 60-69 The post-server command reported an error. Its exit code modulo
159 10 is added to 60
160 70-79 A post-client or post-server command could not be run.
162 80-89 The pre-server command reported an error. Its exit code modulo
164 10 is added to 80
165 90-99 The pre-server command reported an error. Its exit code modulo
167 10 is added to 90
168 100-149
170 Rsync encountered a non-fatal error.
171 150-199
173 Rsync encountered a fatal error.
174 200-219
176 An error was encountered in loading a configuration file.
177 220-254
179 An error was detected in the configuration.
180 255 Incorrect usage.
182
184 /etc/dirvish/master.conf
185 alternate master configuration file.
186 /etc/dirvish.conf
188 master configuration file.
189 /etc/dirvish/client[.conf]
191 client configuration file.
192 bank/vault/dirvish/default[.conf]
194 default vault configuration file.
195 bank/vault/dirvish/branch[.conf]
197 branch configuration file.
198 bank/vault/dirvish/branch.hist
200 branch history file.
201 bank/vault/image/summary
203 image creation summary.
204 bank/vault/image/log
206 image creation log.
207 bank/vault/image/tree
209 actual image of source directory tree.
210 bank/vault/image/rsync_error
212 Error output from rsync if errors or warnings were detected.
213
215 dirvish.conf(5)
216 dirvish-runall(8)
217 dirvish-expire(8)
218 dirvish-locate(8)
219 ssh(1)
220 rsync(1)
221 Time::ParseDate(3pm)
222 strftime(3)
223
225 Dirvish was created by J.W. Schultz of Pegasystems Technologies.
226
228 Fields set in configuration files will override command line options
229 that have been set before the file is read. This behaviour while con‐
230 sistent may occasionally confuse. For this reason most command line
231 options should be specified after any options that may cause a configu‐
232 ration file to be loaded.
233 In order to preserve permissions it is necessary for dirvish to run as
235 root on the backup server.
236 The root user must have non-interactive ssh access to the client sys‐
238 tems. It is not necessary that this access be as the root user on the
239 client.
240 File ownership is preserved using numeric values so it is not necessary
242 to have user accounts on the backup server. Making the vaults network
243 accessible using protocols that map UIDs based on names instead of num‐
244 ber could allow access controls on files to be violated.
245 Making the vaults writable by users will compromise the integrity of
247 the backups. Therefore any access to the vaults by users should be
248 done through a read-only mount.
249 DIRVISH(8)