File: dirvish.8

package info (click to toggle)
dirvish 1.2.1-2
  • links: PTS
  • area: main
  • in suites: bullseye, buster, sid
  • size: 480 kB
  • sloc: perl: 4,494; sh: 211; makefile: 49
file content (343 lines) | stat: -rw-r--r-- 8,140 bytes parent folder | download | duplicates (6)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
.\"       $Id: dirvish.8,v 12.0 2004/02/25 02:42:14 jw Exp $  $Name: Dirvish-1_2 $
.ds d \-\^\-
.ds o \fR[\fP
.ds c \fR]\fP
.ds | \fR|\fP
.de D
\\.B \*d\\$1
..
.de DI
\\.BI \*d\\$1 \\$2
..
.de DR
\\.BR \*d\\$1 \\$2
..
.de Di
\\.BI \*d\\$1 " \\$2"
..
.de Db
\\.B \*d\\$1 " \\$2"
..
.de Df
\\.B \*d\*ono\*c\\$1
..
.de See
See \fB\\$1\fP for details.
..
.de SeeIn
See \fB\\$1\fP in \fB\\$2\fP for details.
..
.de multiple
Multiple \fB\*d\\$1\fP values will accumulate.
..
.de default
Default value: \fB\\$1\fP
..
.TH DIRVISH 8
.SH NAME
dirvish \- Disk based virtual image network backup system
.SH SYNOPSIS
.B dirvish \-\^\-vault
.I vault
[
.I OPTIONS
]
.SH DESCRIPTION
.P
Create a backup image of a client directory tree.
.P
Each image is a directory containing transfer
.BR log,
.BR summary,
.B tree
and if transfer errors were detected an
.B rsync_error
file.
The transfer
.B 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
.B 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.
.P
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.
.P
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.
.P
The removal of an image will have no effect on other images.
.SH 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.
.P
As configuration files are loaded
they may override options on the command line.
.P
Each option may be unambiguously abbreviated.
.TP
.Di branch \*ovault:\*cbranch_name
Specify a branch to use.

A branch is a sequence of images.

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

If this precedes
.D vault
the
.D vault
option will not
load it's own config file.

If vault has been set and
.I 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
.D vault
use
.B ./
to precede the name.

The master configuration file will be read prior to
processing options.
.TP
.Di expire expire_date
Specify a time for the image to expire.

.See Time::ParseDate(3pm)

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

.I image_name
is passed through
.B POSIX::strftime

.See strftime(3)
.TP
.Di 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)
.TP
.D init
Create an initial image.

Create the image entirely from the source tree
without the use of a reference image.
.TP
.D no\-run
.TP
.D 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.
.TP
.Di 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.
.TP
.Di reset option
Reset the values in an accumulating
.IR option .
.TP
.Db summary short\*|long
Specify summary format.

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

.default short
.TP
.Di vault vault\*o:branch_name\*c
Specify the vault to store the image in.

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

If
.I branch_name
is specified here this will behave exactly like the
.D branch
option and
.I branch_name
or
.IR branch_name .conf
will be attempted instead of
.BR default.conf .
.TP
.D version
Print version string and exit.
.SH EXIT CODES
To facilitate further automation and integration of
.B dirvish
with other tools
.B 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.
.TP
0
success
.TP
1-19
The backup job reported warnings.
.TP
20-39
An error occurred during index generation and cleanup.
.TP
40-49
A post-client or post-server command could not be run.
.TP
50-59
The post-client command reported an error.  
Its exit code modulo 10 is added to 50
.TP
60-69
The post-server command reported an error.  
Its exit code modulo 10 is added to 60
.TP
70-79
A post-client or post-server command could not be run.
.TP
80-89
The pre-server command reported an error.  
Its exit code modulo 10 is added to 80
.TP
90-99
The pre-server command reported an error.  
Its exit code modulo 10 is added to 90
.TP
100-149
Rsync encountered a non-fatal error.
.TP
150-199
Rsync encountered a fatal error.
.TP
200-219
An error was encountered in loading a configuration file.
.TP
220-254
An error was detected in the configuration.
.TP
255
Incorrect usage.
.SH FILES
.TP
.B /etc/dirvish/master.conf
alternate master configuration file.
.TP
.B /etc/dirvish.conf
master configuration file.
.TP
.B /etc/dirvish/\fIclient\fP[.conf]
client configuration file.
.TP
.IB bank/vault/ dirvish/default[.conf]
default vault configuration file.
.TP
.IB bank/vault/\fBdirvish\fP/branch [.conf]
branch configuration file.
.TP
.IB bank/vault/\fBdirvish\fP/branch .hist
branch history file.
.TP
.IB bank/vault/image/ summary
image creation summary.
.TP
.IB bank/vault/image/ log
image creation log.
.TP
.IB bank/vault/image/ tree
actual image of source directory tree.
.TP
.IB bank/vault/image/ rsync_error
Error output from rsync if errors or warnings were detected.
.SH SEE ALSO
.nf
dirvish.conf(5)
dirvish\-runall(8)
dirvish\-expire(8)
dirvish\-locate(8)
ssh(1)
rsync(1)
Time::ParseDate(3pm)
strftime(3)
.SH AUTHOR
Dirvish was created by J.W. Schultz of Pegasystems Technologies.
.SH 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.