vbackup.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.)