fossil.4 (10027B)
1 .TH FOSSIL 4 2 .SH NAME 3 fossil, flchk, flfmt \- archival file server 4 .SH SYNOPSIS 5 .B fossil/fossil 6 [ 7 .B -Dt 8 ] 9 [ 10 .B -c 11 .I cmd 12 ]... 13 [ 14 .B -f 15 .I file 16 ] 17 [ 18 .B -m 19 .I free-memory-percent 20 ] 21 .PP 22 .B fossil/flchk 23 [ 24 .B -f 25 ] 26 [ 27 .B -c 28 .I ncache 29 ] 30 [ 31 .B -h 32 .I host 33 ] 34 .I file 35 .PP 36 .B fossil/flfmt 37 [ 38 .B -y 39 ] 40 [ 41 .B -b 42 .I blocksize 43 ] 44 [ 45 .B -h 46 .I host 47 ] 48 [ 49 .B -l 50 .I label 51 ] 52 [ 53 .B -v 54 .I score 55 ] 56 .I file 57 .PP 58 .B fossil/conf 59 [ 60 .B -w 61 ] 62 .I file 63 [ 64 .I config 65 ] 66 .PP 67 .B fossil/last 68 .I file 69 .SH DESCRIPTION 70 .I Fossil 71 is the main file system for Plan 9. 72 Unlike the Plan 9 file servers of old, 73 .I fossil 74 is a collection of user-space programs that run on a standard Plan 9 kernel. 75 The name of the main fossil file server at Murray Hill is 76 .BR pie . 77 The Plan 9 distribution file server, 78 .BR sources , 79 is also a fossil server. 80 .PP 81 .I Fossil 82 is structured as a magnetic disk write buffer 83 optionally backed by a Venti server for archival storage. 84 It serves the Plan 9 protocol via TCP. 85 A 86 .I fossil 87 file server conventionally presents 88 three trees in the root directory of each file system: 89 .BR active , 90 .BR archive , 91 and 92 .BR snapshot . 93 .B /active 94 is the root of a conventional file system 95 whose blocks are stored in a disk file. 96 In a typical configuration, the file server periodically 97 marks the entire file system copy-on-write, effectively 98 taking a snapshot of the file system at that moment. 99 This snapshot is made available in a name 100 created from the date and time of the snapshot: 101 .BI /snapshot/ yyyy / mmdd / hhmm \fR, 102 where 103 .I yyyy 104 is the full year, 105 .I mm 106 is the month number, 107 .I dd 108 is the day number, 109 .I hh 110 is the hour, 111 and 112 .I mm 113 is the minute. 114 The snapshots in 115 .B /snapshot 116 are ephemeral: eventually they are deleted 117 to reclaim the disk space they occupy. 118 Long-lasting snapshots stored on a Venti server 119 are kept in 120 .B /archive 121 and also named from the date (though not the time) of the snapshot: 122 .BI /archive/ yyyy / mmdds \fR, 123 where 124 .IR yyyy , 125 .IR mm , 126 and 127 .I dd 128 are year, month, and day as before, 129 and 130 .I s 131 is a sequence number if more than one 132 archival snapshot is done in a day. 133 For the first snapshot, 134 .I s 135 is null. 136 For the subsequent snapshots, 137 .I s 138 is 139 .BR .1 , 140 .BR .2 , 141 .BR .3 , 142 etc. 143 The root of the main file system that is frozen 144 for the first archival snapshot of December 15, 2002 145 will be named 146 .BR /archive/2002/1215/ . 147 .PP 148 The attach name used in 149 .I mount 150 (see 151 .MR bind (1) , 152 .MR bind (2) 153 and 154 .MR attach (5) ) 155 selects a file system to be served 156 and optionally a subtree, 157 in the format 158 .IB fs \fR[\fB/ dir \fR]. 159 An empty attach name selects 160 .BR main/active . 161 .PP 162 .I Fossil 163 normally requires all users except 164 .L none 165 to provide authentication tickets on each 166 .MR attach (5) . 167 To keep just anyone from connecting, 168 .L none 169 is only allowed to attach after another user 170 has successfully attached on the same 171 connection. 172 The other user effectively acts as a chaperone 173 for 174 .LR none . 175 Authentication can be disabled using the 176 .B -A 177 flag to 178 .B open 179 or 180 .B srv 181 (see 182 .MR fossilcons (8) ). 183 .PP 184 The groups called 185 .B noworld 186 and 187 .B write 188 are special on the file server. 189 Any user belonging to 190 .B noworld 191 has attenuated access privileges. 192 Specifically, when checking such a user's access to files, 193 the file's permission bits are first ANDed 194 with 0770 for normal files and 0771 for directories. 195 The effect is to deny world access permissions to 196 .B noworld 197 users, except when walking into directories. 198 If the 199 .B write 200 group exists, then the file system appears read-only 201 to users not in the group. 202 This is used to make the Plan 9 distribution file server 203 .RI ( sources.cs.bell-labs.com ) 204 readable by the world but writable only to the developers. 205 .PP 206 .I Fossil 207 starts a new instance of the fossil file server. 208 It is configured mainly through console commands, 209 documented in 210 .MR fossilcons (8) . 211 .PP 212 The options are: 213 .TF "-c\fI cmd 214 .PD 215 .TP 216 .B -D 217 Toggle the debugging flag, which is initially off. 218 When the flag is set, information about authentication 219 and all protocol messages are written to standard error. 220 .TP 221 .B -t 222 Start a file server console on 223 .BR /dev/cons . 224 If this option is given, 225 .I fossil 226 does not fork itself into the background. 227 .TP 228 .BI -c " cmd 229 Execute the console command 230 .IR cmd . 231 This option may be repeated to give multiple 232 commands. 233 Typically the only commands given on the 234 command line are 235 .RB `` ".\fI file" ,'' 236 which executes a file containing commands, 237 and 238 .RB `` "srv -p" \fIcons \fR,'' 239 which starts a file server console on 240 .BI /srv/ cons \fR. 241 See 242 .MR fossilcons (8) 243 for more information. 244 .TP 245 .BI -f " file 246 Read and execute console commands stored in the Fossil disk 247 .IR file . 248 .I Conf 249 .RI ( q.v. ) 250 reads and writes the command set stored in the disk. 251 .TP 252 .B -m 253 Allocate 254 .I free-memory-percent 255 percent of the available free RAM for buffers. 256 This overrides all other memory sizing parameters, 257 notably the 258 .B -c 259 option to 260 .BR open . 261 30% is a reasonable choice. 262 .PD 263 .PP 264 .I Flchk 265 checks the fossil file system stored in 266 .I file 267 for inconsistencies. 268 .I Flchk 269 is deprecated in favor of the console 270 .B check 271 command (see 272 .MR fossilcons (8) ). 273 .I Flchk 274 prints 275 .I fossil 276 console commands that may be 277 executed to take care of 278 bad pointers 279 .RB ( clrp ), 280 bad entries 281 .RB ( clre ), 282 bad directory entries 283 .RB ( clri ), 284 unreachable blocks 285 .RB ( bfree ). 286 Console commands are interspersed with 287 more detailed commentary on the file system. 288 The commands are distinguished by being prefixed with 289 sharp signs. 290 Note that all proposed fixes are rather drastic: offending 291 pieces of file system are simply chopped off. 292 .PP 293 .I Flchk 294 does 295 .I not 296 modify the file system, so it is safe to 297 run concurrently with 298 .IR fossil , 299 though in this case 300 the list of unreachable 301 blocks and any inconsistencies involving the active file system 302 should be taken with a grain of salt. 303 .PP 304 The options are: 305 .TF "-h\fI host 306 .PD 307 .TP 308 .B -f 309 Fast mode. 310 By default, 311 .I flchk 312 checks the entire file system image for consistency, 313 which includes all the archives to Venti 314 and can take a very long time. 315 In fast mode, 316 .I flchk 317 avoids walking in Venti blocks 318 whenever possible. 319 .TP 320 .BI -c " ncache 321 Keep a cache of 322 .I ncache 323 (by default, 1000) 324 file system blocks in memory during the check. 325 .TP 326 .BI -h " host 327 Use 328 .I host 329 as the Venti server. 330 .PD 331 .PP 332 .I Flfmt 333 prepares 334 .I file 335 as a new fossil file system. 336 The file system is initialized with three empty directories 337 .BR active , 338 .BR archive , 339 and 340 .BR snapshot , 341 as described above. 342 The options are: 343 .TF "-b\fI blocksize 344 .PD 345 .TP 346 .B -y 347 Yes mode. 348 By default, 349 .I flfmt 350 will prompt for confirmation before formatting 351 a file that already contains a fossil file system, 352 and before formatting a file that is not served 353 directly by a kernel device. 354 If the 355 .B -y 356 flag is given, no such checks are made. 357 .TP 358 .BI -b " blocksize 359 Set the file system block size (by default, 8192). 360 .TP 361 .BI -h " host 362 Use 363 .I host 364 as the Venti server. 365 .TP 366 .BI -l " label 367 Set the textual label on the file system to 368 .IR label . 369 The label is only a comment. 370 .TP 371 .BI -v " score 372 Initialize the file system using the vac file 373 system stored on Venti at 374 .IR score . 375 The score should have been generated by 376 .I fossil 377 rather than by 378 .MR vac (1) , 379 so that the appropriate snapshot metadata is present. 380 .PD 381 .PP 382 .I Conf 383 reads or writes the configuration branded on the Fossil disk 384 .IR file . 385 By default, it reads the configuration from the disk and prints it to 386 standard output. 387 If the 388 .B -w 389 flag is given, 390 .I conf 391 reads a new configuration from 392 .I config 393 (or else from standard input) 394 and writes it to the disk. 395 Inside the configuration file, the argument 396 .L * 397 may be used to stand in for the name of the disk holding the configuration. 398 The Plan 9 kernel boot process runs 399 .RB `` fossil 400 .B -f 401 .IR disk '' 402 to start a Fossil file server. 403 The disk is just a convenient place to store configuration 404 information. 405 .PP 406 .I Last 407 prints the vac score that resulted after the most recent archival snapshot 408 of the fossil in 409 .I file. 410 .SH EXAMPLES 411 .PP 412 Place the root of the archive file system on 413 .B /n/dump 414 and show the modified times of the MIPS C compiler 415 over all dumps in December 2002: 416 .IP 417 .EX 418 9fs dump 419 ls -l /n/dump/2002/12*/mips/bin/vc 420 .EE 421 .PP 422 To get only one line of output for each version of the compiler: 423 .IP 424 .EX 425 ls -lp /n/dump/2002/12*/mips/bin/vc | uniq 426 .EE 427 .ne 14 428 .PP 429 Initialize a new file system, start the server with permission 430 checking turned off, create a users file, and mount the server: 431 .IP 432 .EX 433 fossil/flfmt /dev/sdC0/fossil 434 fossil/conf -w /dev/sdC0/fossil <<EOF 435 fsys main config 436 fsys main open -AWP 437 fsys main 438 create /active/adm adm sys d775 439 create /active/adm/users adm sys 664 440 users -w 441 srv -p fscons 442 srv fossil 443 EOF 444 fossil/fossil -f /dev/sdC0/fossil 445 mount /srv/fossil /n/fossil 446 .EE 447 .LP 448 See the discussion of the 449 .B users 450 and 451 .B uname 452 commands in 453 .MR fossilcons (8) 454 for more about the user table. 455 .ne 3 456 .PP 457 Perhaps because the disk has been corrupted or replaced, 458 format a new file system using the last archive score printed 459 on the console: 460 .IP 461 .EX 462 fossil/flfmt -v b9b3...5559 /dev/sdC0/fossil 463 .EE 464 .LP 465 Note that while 466 .B /snapshot 467 will be lost, 468 .B /active 469 and 470 .B /archive 471 will be restored to their contents at the time of the 472 last archival snapshot. 473 .ne 3 474 .PP 475 Blindly accept the changes prescribed by 476 .I flchk 477 (not recommended): 478 .IP 479 .EX 480 fossil/flchk /dev/sdC0/fossil | sed -n 's/^# //p' >>/srv/fscons 481 .EE 482 .LP 483 A better strategy is to vet the output, 484 filter out any suggestions you're not comfortable with, 485 and then use the 486 .I sed 487 command to prepare the script. 488 .SH SOURCE 489 .B \*9/src/cmd/fossil 490 .SH SEE ALSO 491 .MR yesterday (1) , 492 .MR fs (3) , 493 .MR fs (4) , 494 .MR srv (4) , 495 .MR fossilcons (8) , 496 .MR loadfossil (8) , 497 .MR venti (8) 498 .SH BUGS 499 It is possible that the disk format (but not the Venti format) 500 will change in the future, to make the disk a full cache 501 rather than just a write buffer. 502 Changing to the new format will require reformatting 503 the disk as in the example above, 504 but note that this will preserve most of the file system 505 (all but 506 .BR /snapshot ) 507 with little effort. 508 .PP 509 The 510 .B -m 511 option currently assumes a block size of 8K bytes, 512 and a single file system per 513 .I fossil 514 instance.