tvbackup.8 - plan9port - [fork] Plan 9 from user space
(HTM) git clone git://src.adamsgaard.dk/plan9port
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) README
(DIR) LICENSE
---
tvbackup.8 (7920B)
---
1 .TH VBACKUP 8
2 .SH NAME
3 vbackup, vcat, vftp, vmount, vnfs \-
4 back up Unix file systems to Venti
5 .SH SYNOPSIS
6 .B vbackup
7 [
8 .B -DVinv
9 ]
10 [
11 .B -M
12 .I mtpt
13 ]
14 [
15 .B -m
16 .I host
17 ]
18 [
19 .B -s
20 .I secs
21 ]
22 [
23 .B -w
24 .I n
25 ]
26 .I disk
27 [
28 .I score
29 ]
30 .PP
31 .B vcat
32 [
33 .B -z
34 ]
35 .I disk
36 |
37 .I score
38 .B >
39 .I disk
40 .PP
41 .B vftp
42 .I score
43 |
44 .I disk
45 .PP
46 .B vmount
47 [
48 .B -v
49 ]
50 .I addr
51 .I mtpt
52 .PP
53 .B vnfs
54 [
55 .B -ELLRVir
56 ]
57 [
58 .B -a
59 .I addr
60 ]
61 [
62 .B -b
63 .I blocksize
64 ]
65 [
66 .B -c
67 .I cachesize
68 ]
69 .I config
70 .SH DESCRIPTION
71 These programs back up and restore standard
72 Unix file system images stored in
73 .MR venti (8) .
74 Images stored in
75 .I venti
76 are named by
77 .IR scores ,
78 which consist of a file system type followed
79 by a colon and forty hexadecimal digits, as in:
80 .IP
81 .EX
82 ffs:0123456789abcdef0123456789abcdef01234567
83 .EE
84 .PP
85 (The hexadecimal data is the SHA1 hash of the Venti
86 root block representing the file system image.)
87 .PP
88 These programs expect the environment variable
89 .B $venti
90 to be set to the network address of the Venti server to use
91 (for example,
92 .B yourhost
93 or
94 .BR tcp!yourhost!venti ).
95 .PP
96 .I Vbackup
97 copies the file system stored on
98 .I disk
99 to the Venti server and prints the
100 score for the newly-stored image.
101 The argument
102 .I disk
103 should be a disk or disk partition device
104 that would be appropriate to pass to
105 .MR mount (8) .
106 .PP
107 The optional argument
108 .I score
109 is the score of a previous backup of the disk image.
110 If
111 .I score
112 is given,
113 .I vbackup
114 will not write to Venti any blocks that have not changed
115 since the previous backup.
116 This is only a speed optimization: since the blocks are already
117 stored on Venti they need not be sent to the Venti server again.
118 .PP
119 The options to
120 .I vbackup
121 are:
122 .TP
123 .B -D
124 Turn on debugging output.
125 .TP
126 .B -V
127 Trace interactions with Venti server.
128 .TP
129 .B -m \fIhost
130 .B -M \fImtpt
131 Set names used to construct the path in the
132 .B mount command.
133 The default
134 .I host
135 is the name returned by
136 .I sysname
137 (see
138 .MR getuser (3) ).
139 The default
140 .I mtpt
141 is the place where
142 .I disk
143 is currently mounted.
144 .TP
145 Set backup mount point:
146 this name is also used in the printed
147 .B mount
148 command.
149 The default is the name returned by
150 .I sysname
151 (see
152 .MR getuser (3) ).
153 .TP
154 .B -n
155 No-op mode: do not write any blocks to the server
156 .TP
157 .B -i
158 Read scores incrementally from the previous backup as needed,
159 rather than prefetching them.
160 .TP
161 .B -v
162 Print verbose output.
163 .TP
164 .B -w \fIn
165 Write parallelism: keep
166 .I n
167 writes to the server in progress at a time.
168 .TP
169 .B -s \fIsecs
170 Status interval: every
171 .I secs
172 seconds, print a line tracking progress of the backup.
173 .PD
174 .PP
175 When
176 .I vbackup
177 finishes, it prints a single line of the form
178 .IP
179 .EX
180 mount /\fIhost\fL/\fIyyyy\fL/\fImmdd\fL/\fImtpt\fL \fIscore\fL \fIyyyy\fL/\fImmdd\fL/\fIhhmm
181 .EE
182 .LP
183 This line is a valid configuration line for
184 .I vnfs
185 .RI ( q.v. ).
186 .I Mntpath
187 is the path on which
188 .I disk
189 is currently mounted.
190 .PP
191 .I Vcat
192 writes the named disk image to standard output.
193 Unused file system blocks are printed zeroed regardless
194 of their actual content.
195 .PP
196 By default,
197 .I vcat
198 will assume that its standard output is seekable
199 .RI ( i.e.,
200 it has been redirected to a file or disk)
201 and seek over unused blocks instead of writing to them.
202 The
203 .B -z
204 option causes
205 .I vcat
206 to zero unused blocks instead.
207 .PP
208 .I Vftp
209 presents an
210 .MR ftp (1) -like
211 interface to a physical or backed-up disk image.
212 It is used mainly for debugging.
213 Type
214 .B help
215 at the
216 .B vftp>
217 prompt for a list of commands.
218 .PP
219 .I Vmount
220 mounts the NFS service at the network connection
221 .I address
222 onto
223 .IR mountpoint .
224 On most operating systems,
225 .I vmount
226 must be run by the user
227 .BR root .
228 Because
229 .I address
230 is passed to the host OS kernel rather than interpreted by
231 .MR dial (3) ,
232 it must be only an IP address, not a full dial address.
233 .PP
234 .I Vnfs
235 serves, using the
236 NFS version 3 protocol,
237 one or more disk images in a synthetic tree defined
238 by the configuration file
239 .IR config .
240 .I Vnfs
241 serves both NFS mount protocol
242 and NFS protocol
243 RPCs at
244 .IR addr
245 (default
246 .BR udp!*!nfs ).
247 The options are:
248 .TP
249 .B -E
250 Disable `encrypted' handles.
251 By default handles are encrypted with a random key to avoid
252 leaking information about the backed-up file systems.
253 If encryption is disabled, the NFS handles exposed to the client
254 may leak information about the root scores of the disks as well
255 as inode numbers.
256 .TP
257 .B -L
258 Local service only: serve only requests from the loopback interface (127.0.0.1).
259 .TP
260 .B -LL
261 Local service only, with paranoia: serve only requests from loopback,
262 and only from the first source port that sends a request.
263 This option is intended to be used to make sure that once the local
264 host has mounted the service, no other local users can access it.
265 .TP
266 .B -R
267 Print all NFS and NFS mount RPCs to standard error.
268 .TP
269 .B -V
270 Print all Venti transactions to standard error.
271 .TP
272 .BI -a " addr
273 Serve requests on
274 .IR addr
275 (see above).
276 .TP
277 .BI -b " blocksize
278 Set block size used by the in-memory venti block cache.
279 Must be as large as the maximum block size in any
280 file system mentioned in the configuration.
281 .TP
282 .BI -c " cachesize
283 Set the number of blocks stored by the in-memory venti cache.
284 .TP
285 .B -i
286 Run in ``insecure'' mode, allowing remote root users to
287 use uid and gid 0 and read any file.
288 (Normally, remote root is mapped to uid and gid \-1
289 and has no special permissions.)
290 .TP
291 .B -r
292 Respond to all requests with a Sun RPC rejection.
293 This is useful during debugging.
294 .PD
295 .PP
296 .I Config
297 is a text file describing the
298 backup hierarchy for
299 .I vnfs
300 to serve.
301 Lines beginning with a sharp
302 .RB ( # )
303 are ignored.
304 The rest of the file is a sequence of commands, one per line.
305 The commands are:
306 .TP
307 .BI mount " mtpt score time
308 Add the file system with the given
309 .I score
310 to the tree at the mount point
311 .IR mtpt .
312 The path to the mount point will be created
313 if necessary.
314 If
315 .B /dev/null
316 is given as the score, an empty file system is mounted at
317 .IR mtpt ,
318 excluding
319 .IR mtpt 's
320 contents from view.
321 .I Time
322 is the modification time to return for the directory
323 .IR mtpt ,
324 either a decimal number of seconds since the epoch
325 or a string of the form
326 .IB yyyy / mmdd / hhmm
327 giving the year, month, day, hour, and minute.
328 .RI ( Vnfs
329 does not use the modification time of the root in order
330 to avoid accessing every mounted file system on common
331 actions like
332 .B ls
333 .B -l
334 .BR /dump/sys/2005 .)
335 .TP
336 .BI allow " ip\fR[\fL/\fImask\fR]
337 .TP
338 .BI deny " ip\fR[\fL/\fImask\fR]
339 These two commands define access permissions based on IP address.
340 The optional
341 .I mask
342 can be a decimal number (24) or an equivalent IP mask (255.255.255.0).
343 Each request is filtered through the rules listed in the configuration file.
344 The first rule that matches is used.
345 If any
346 .B allow
347 or
348 .B deny
349 rules are given, the default action is to reject the request.
350 In the absence of any rules, the default action is to accept all requests.
351 .PD
352 .PP
353 Reading the special file
354 .B /dump/+refreshconfig
355 causes
356 .I vnfs
357 to reload
358 .IR config .
359 The read returns either the string
360 .B ok
361 or an error message.
362 .SH EXAMPLES
363 .PP
364 Running on the server
365 .IR bob ,
366 back up the file system stored on
367 .BR /dev/da0s1a ,
368 which is mounted on
369 .BR /home :
370 .IP
371 .EX
372 % vbackup /dev/da0s1a
373 mount /bob/2005/0510/home ffs:0123456789abcdef\fI...\fP 2005/0510/0831
374 %
375 .EE
376 .PP
377 Serve that backup and a few others in a tree reminiscent
378 of Plan 9's dump file system, but hide each day's contents of
379 .B /tmp :
380 .IP
381 .EX
382 % cat config
383 mount /bob/2005/0510 ffs:0123456789abcdef\fI...\fP 2005/0510/0829
384 mount /bob/2005/0510/home ffs:0123456789abcdef\fI...\fP 2005/0510/0831
385 mount /bob/2005/0510/tmp /dev/null 1
386 mount /bob/2005/0511 ffs:0123456789abcdef\fI...\fP 2005/0511/0827
387 mount /bob/2005/0511/home ffs:0123456789abcdef\fI...\fP 2005/0511/0828
388 mount /bob/2005/0511/tmp /dev/null 1
389 % vnfs -b 16k -c 1k config
390 %
391 .EE
392 .PP
393 Mount the backups on a client machine using
394 .IR vmount :
395 .IP
396 .EX
397 # vmount yourserver /dump
398 # ls /dump/bob/2005
399 0510
400 0511
401 #
402 .EE
403 .PP
404 (Users of fancy shells may need to quote the address argument.)