1 6f4d00ee 2013-09-23 0intro .TH FOSSIL 4
3 6f4d00ee 2013-09-23 0intro fossil, flchk, flfmt \- archival file server
4 6f4d00ee 2013-09-23 0intro .SH SYNOPSIS
5 6f4d00ee 2013-09-23 0intro .B fossil/fossil
19 6f4d00ee 2013-09-23 0intro .I free-memory-percent
22 6f4d00ee 2013-09-23 0intro .B fossil/flchk
36 6f4d00ee 2013-09-23 0intro .B fossil/flfmt
42 6f4d00ee 2013-09-23 0intro .I blocksize
58 6f4d00ee 2013-09-23 0intro .B fossil/conf
67 6f4d00ee 2013-09-23 0intro .B fossil/last
69 6f4d00ee 2013-09-23 0intro .SH DESCRIPTION
71 6f4d00ee 2013-09-23 0intro is the main file system for Plan 9.
72 6f4d00ee 2013-09-23 0intro Unlike the Plan 9 file servers of old,
74 6f4d00ee 2013-09-23 0intro is a collection of user-space programs that run on a standard Plan 9 kernel.
75 6f4d00ee 2013-09-23 0intro The name of the main fossil file server at Murray Hill is
77 6f4d00ee 2013-09-23 0intro The Plan 9 distribution file server,
78 6f4d00ee 2013-09-23 0intro .BR sources ,
79 6f4d00ee 2013-09-23 0intro is also a fossil server.
82 6f4d00ee 2013-09-23 0intro is structured as a magnetic disk write buffer
83 6f4d00ee 2013-09-23 0intro optionally backed by a Venti server for archival storage.
84 6f4d00ee 2013-09-23 0intro It serves the Plan 9 protocol via TCP.
87 6f4d00ee 2013-09-23 0intro file server conventionally presents
88 6f4d00ee 2013-09-23 0intro three trees in the root directory of each file system:
89 6f4d00ee 2013-09-23 0intro .BR active ,
90 6f4d00ee 2013-09-23 0intro .BR archive ,
92 6f4d00ee 2013-09-23 0intro .BR snapshot .
93 6f4d00ee 2013-09-23 0intro .B /active
94 6f4d00ee 2013-09-23 0intro is the root of a conventional file system
95 6f4d00ee 2013-09-23 0intro whose blocks are stored in a disk file.
96 6f4d00ee 2013-09-23 0intro In a typical configuration, the file server periodically
97 6f4d00ee 2013-09-23 0intro marks the entire file system copy-on-write, effectively
98 6f4d00ee 2013-09-23 0intro taking a snapshot of the file system at that moment.
99 6f4d00ee 2013-09-23 0intro This snapshot is made available in a name
100 6f4d00ee 2013-09-23 0intro created from the date and time of the snapshot:
101 6f4d00ee 2013-09-23 0intro .BI /snapshot/ yyyy / mmdd / hhmm \fR,
104 6f4d00ee 2013-09-23 0intro is the full year,
106 6f4d00ee 2013-09-23 0intro is the month number,
108 6f4d00ee 2013-09-23 0intro is the day number,
110 6f4d00ee 2013-09-23 0intro is the hour,
113 6f4d00ee 2013-09-23 0intro is the minute.
114 6f4d00ee 2013-09-23 0intro The snapshots in
115 6f4d00ee 2013-09-23 0intro .B /snapshot
116 6f4d00ee 2013-09-23 0intro are ephemeral: eventually they are deleted
117 6f4d00ee 2013-09-23 0intro to reclaim the disk space they occupy.
118 6f4d00ee 2013-09-23 0intro Long-lasting snapshots stored on a Venti server
119 6f4d00ee 2013-09-23 0intro are kept in
120 6f4d00ee 2013-09-23 0intro .B /archive
121 6f4d00ee 2013-09-23 0intro and also named from the date (though not the time) of the snapshot:
122 6f4d00ee 2013-09-23 0intro .BI /archive/ yyyy / mmdds \fR,
124 6f4d00ee 2013-09-23 0intro .IR yyyy ,
128 6f4d00ee 2013-09-23 0intro are year, month, and day as before,
131 6f4d00ee 2013-09-23 0intro is a sequence number if more than one
132 6f4d00ee 2013-09-23 0intro archival snapshot is done in a day.
133 6f4d00ee 2013-09-23 0intro For the first snapshot,
136 6f4d00ee 2013-09-23 0intro For the subsequent snapshots,
143 6f4d00ee 2013-09-23 0intro The root of the main file system that is frozen
144 6f4d00ee 2013-09-23 0intro for the first archival snapshot of December 15, 2002
145 6f4d00ee 2013-09-23 0intro will be named
146 6f4d00ee 2013-09-23 0intro .BR /archive/2002/1215/ .
148 6f4d00ee 2013-09-23 0intro The attach name used in
151 6f4d00ee 2013-09-23 0intro .IR bind (1),
152 6f4d00ee 2013-09-23 0intro .IR bind (2)
154 6f4d00ee 2013-09-23 0intro .IR attach (5))
155 6f4d00ee 2013-09-23 0intro selects a file system to be served
156 6f4d00ee 2013-09-23 0intro and optionally a subtree,
157 6f4d00ee 2013-09-23 0intro in the format
158 6f4d00ee 2013-09-23 0intro .IB fs \fR[\fB/ dir \fR].
159 6f4d00ee 2013-09-23 0intro An empty attach name selects
160 6f4d00ee 2013-09-23 0intro .BR main/active .
162 6f4d00ee 2013-09-23 0intro .I Fossil
163 6f4d00ee 2013-09-23 0intro normally requires all users except
165 6f4d00ee 2013-09-23 0intro to provide authentication tickets on each
166 6f4d00ee 2013-09-23 0intro .IR attach (5).
167 6f4d00ee 2013-09-23 0intro To keep just anyone from connecting,
169 6f4d00ee 2013-09-23 0intro is only allowed to attach after another user
170 6f4d00ee 2013-09-23 0intro has successfully attached on the same
171 6f4d00ee 2013-09-23 0intro connection.
172 6f4d00ee 2013-09-23 0intro The other user effectively acts as a chaperone
174 6f4d00ee 2013-09-23 0intro .LR none .
175 6f4d00ee 2013-09-23 0intro Authentication can be disabled using the
182 6f4d00ee 2013-09-23 0intro .IR fossilcons (8)).
184 6f4d00ee 2013-09-23 0intro The groups called
185 6f4d00ee 2013-09-23 0intro .B noworld
188 6f4d00ee 2013-09-23 0intro are special on the file server.
189 6f4d00ee 2013-09-23 0intro Any user belonging to
190 6f4d00ee 2013-09-23 0intro .B noworld
191 6f4d00ee 2013-09-23 0intro has attenuated access privileges.
192 6f4d00ee 2013-09-23 0intro Specifically, when checking such a user's access to files,
193 6f4d00ee 2013-09-23 0intro the file's permission bits are first ANDed
194 6f4d00ee 2013-09-23 0intro with 0770 for normal files and 0771 for directories.
195 6f4d00ee 2013-09-23 0intro The effect is to deny world access permissions to
196 6f4d00ee 2013-09-23 0intro .B noworld
197 6f4d00ee 2013-09-23 0intro users, except when walking into directories.
200 6f4d00ee 2013-09-23 0intro group exists, then the file system appears read-only
201 6f4d00ee 2013-09-23 0intro to users not in the group.
202 6f4d00ee 2013-09-23 0intro This is used to make the Plan 9 distribution file server
203 6f4d00ee 2013-09-23 0intro .RI ( sources.cs.bell-labs.com )
204 6f4d00ee 2013-09-23 0intro readable by the world but writable only to the developers.
206 6f4d00ee 2013-09-23 0intro .I Fossil
207 6f4d00ee 2013-09-23 0intro starts a new instance of the fossil file server.
208 6f4d00ee 2013-09-23 0intro It is configured mainly through console commands,
209 6f4d00ee 2013-09-23 0intro documented in
210 6f4d00ee 2013-09-23 0intro .IR fossilcons (8).
212 6f4d00ee 2013-09-23 0intro The options are:
213 6f4d00ee 2013-09-23 0intro .TF "-c\fI cmd
217 6f4d00ee 2013-09-23 0intro Toggle the debugging flag, which is initially off.
218 6f4d00ee 2013-09-23 0intro When the flag is set, information about authentication
219 6f4d00ee 2013-09-23 0intro and all protocol messages are written to standard error.
222 6f4d00ee 2013-09-23 0intro Start a file server console on
223 6f4d00ee 2013-09-23 0intro .BR /dev/cons .
224 6f4d00ee 2013-09-23 0intro If this option is given,
225 6f4d00ee 2013-09-23 0intro .I fossil
226 6f4d00ee 2013-09-23 0intro does not fork itself into the background.
228 6f4d00ee 2013-09-23 0intro .BI -c " cmd
229 6f4d00ee 2013-09-23 0intro Execute the console command
230 6f4d00ee 2013-09-23 0intro .IR cmd .
231 6f4d00ee 2013-09-23 0intro This option may be repeated to give multiple
232 6f4d00ee 2013-09-23 0intro commands.
233 6f4d00ee 2013-09-23 0intro Typically the only commands given on the
234 6f4d00ee 2013-09-23 0intro command line are
235 6f4d00ee 2013-09-23 0intro .RB `` ".\fI file" ,''
236 6f4d00ee 2013-09-23 0intro which executes a file containing commands,
238 6f4d00ee 2013-09-23 0intro .RB `` "srv -p" \fIcons \fR,''
239 6f4d00ee 2013-09-23 0intro which starts a file server console on
240 6f4d00ee 2013-09-23 0intro .BI /srv/ cons \fR.
242 6f4d00ee 2013-09-23 0intro .IR fossilcons (8)
243 6f4d00ee 2013-09-23 0intro for more information.
245 6f4d00ee 2013-09-23 0intro .BI -f " file
246 6f4d00ee 2013-09-23 0intro Read and execute console commands stored in the Fossil disk
247 6f4d00ee 2013-09-23 0intro .IR file .
249 6f4d00ee 2013-09-23 0intro .RI ( q.v. )
250 6f4d00ee 2013-09-23 0intro reads and writes the command set stored in the disk.
254 6f4d00ee 2013-09-23 0intro .I free-memory-percent
255 6f4d00ee 2013-09-23 0intro percent of the available free RAM for buffers.
256 6f4d00ee 2013-09-23 0intro This overrides all other memory sizing parameters,
257 6f4d00ee 2013-09-23 0intro notably the
259 6f4d00ee 2013-09-23 0intro option to
260 6f4d00ee 2013-09-23 0intro .BR open .
261 6f4d00ee 2013-09-23 0intro 30% is a reasonable choice.
265 6f4d00ee 2013-09-23 0intro checks the fossil file system stored in
267 6f4d00ee 2013-09-23 0intro for inconsistencies.
269 6f4d00ee 2013-09-23 0intro is deprecated in favor of the console
271 6f4d00ee 2013-09-23 0intro command (see
272 6f4d00ee 2013-09-23 0intro .IR fossilcons (8)).
275 6f4d00ee 2013-09-23 0intro .I fossil
276 6f4d00ee 2013-09-23 0intro console commands that may be
277 6f4d00ee 2013-09-23 0intro executed to take care of
278 6f4d00ee 2013-09-23 0intro bad pointers
279 6f4d00ee 2013-09-23 0intro .RB ( clrp ),
280 6f4d00ee 2013-09-23 0intro bad entries
281 6f4d00ee 2013-09-23 0intro .RB ( clre ),
282 6f4d00ee 2013-09-23 0intro bad directory entries
283 6f4d00ee 2013-09-23 0intro .RB ( clri ),
284 6f4d00ee 2013-09-23 0intro unreachable blocks
285 6f4d00ee 2013-09-23 0intro .RB ( bfree ).
286 6f4d00ee 2013-09-23 0intro Console commands are interspersed with
287 6f4d00ee 2013-09-23 0intro more detailed commentary on the file system.
288 6f4d00ee 2013-09-23 0intro The commands are distinguished by being prefixed with
289 6f4d00ee 2013-09-23 0intro sharp signs.
290 6f4d00ee 2013-09-23 0intro Note that all proposed fixes are rather drastic: offending
291 6f4d00ee 2013-09-23 0intro pieces of file system are simply chopped off.
296 6f4d00ee 2013-09-23 0intro modify the file system, so it is safe to
297 6f4d00ee 2013-09-23 0intro run concurrently with
298 6f4d00ee 2013-09-23 0intro .IR fossil ,
299 6f4d00ee 2013-09-23 0intro though in this case
300 6f4d00ee 2013-09-23 0intro the list of unreachable
301 6f4d00ee 2013-09-23 0intro blocks and any inconsistencies involving the active file system
302 6f4d00ee 2013-09-23 0intro should be taken with a grain of salt.
304 6f4d00ee 2013-09-23 0intro The options are:
305 6f4d00ee 2013-09-23 0intro .TF "-h\fI host
309 6f4d00ee 2013-09-23 0intro Fast mode.
310 6f4d00ee 2013-09-23 0intro By default,
312 6f4d00ee 2013-09-23 0intro checks the entire file system image for consistency,
313 6f4d00ee 2013-09-23 0intro which includes all the archives to Venti
314 6f4d00ee 2013-09-23 0intro and can take a very long time.
315 6f4d00ee 2013-09-23 0intro In fast mode,
317 6f4d00ee 2013-09-23 0intro avoids walking in Venti blocks
318 6f4d00ee 2013-09-23 0intro whenever possible.
320 6f4d00ee 2013-09-23 0intro .BI -c " ncache
321 6f4d00ee 2013-09-23 0intro Keep a cache of
322 6f4d00ee 2013-09-23 0intro .I ncache
323 6f4d00ee 2013-09-23 0intro (by default, 1000)
324 6f4d00ee 2013-09-23 0intro file system blocks in memory during the check.
326 6f4d00ee 2013-09-23 0intro .BI -h " host
329 6f4d00ee 2013-09-23 0intro as the Venti server.
335 6f4d00ee 2013-09-23 0intro as a new fossil file system.
336 6f4d00ee 2013-09-23 0intro The file system is initialized with three empty directories
337 6f4d00ee 2013-09-23 0intro .BR active ,
338 6f4d00ee 2013-09-23 0intro .BR archive ,
340 6f4d00ee 2013-09-23 0intro .BR snapshot ,
341 6f4d00ee 2013-09-23 0intro as described above.
342 6f4d00ee 2013-09-23 0intro The options are:
343 6f4d00ee 2013-09-23 0intro .TF "-b\fI blocksize
347 6f4d00ee 2013-09-23 0intro Yes mode.
348 6f4d00ee 2013-09-23 0intro By default,
350 6f4d00ee 2013-09-23 0intro will prompt for confirmation before formatting
351 6f4d00ee 2013-09-23 0intro a file that already contains a fossil file system,
352 6f4d00ee 2013-09-23 0intro and before formatting a file that is not served
353 6f4d00ee 2013-09-23 0intro directly by a kernel device.
356 6f4d00ee 2013-09-23 0intro flag is given, no such checks are made.
358 6f4d00ee 2013-09-23 0intro .BI -b " blocksize
359 6f4d00ee 2013-09-23 0intro Set the file system block size (by default, 8192).
361 6f4d00ee 2013-09-23 0intro .BI -h " host
364 6f4d00ee 2013-09-23 0intro as the Venti server.
366 6f4d00ee 2013-09-23 0intro .BI -l " label
367 6f4d00ee 2013-09-23 0intro Set the textual label on the file system to
368 6f4d00ee 2013-09-23 0intro .IR label .
369 6f4d00ee 2013-09-23 0intro The label is only a comment.
371 6f4d00ee 2013-09-23 0intro .BI -v " score
372 6f4d00ee 2013-09-23 0intro Initialize the file system using the vac file
373 6f4d00ee 2013-09-23 0intro system stored on Venti at
374 6f4d00ee 2013-09-23 0intro .IR score .
375 6f4d00ee 2013-09-23 0intro The score should have been generated by
376 6f4d00ee 2013-09-23 0intro .I fossil
377 6f4d00ee 2013-09-23 0intro rather than by
378 6f4d00ee 2013-09-23 0intro .IR vac (1),
379 6f4d00ee 2013-09-23 0intro so that the appropriate snapshot metadata is present.
383 6f4d00ee 2013-09-23 0intro reads or writes the configuration branded on the Fossil disk
384 6f4d00ee 2013-09-23 0intro .IR file .
385 6f4d00ee 2013-09-23 0intro By default, it reads the configuration from the disk and prints it to
386 6f4d00ee 2013-09-23 0intro standard output.
389 6f4d00ee 2013-09-23 0intro flag is given,
391 6f4d00ee 2013-09-23 0intro reads a new configuration from
392 6f4d00ee 2013-09-23 0intro .I config
393 6f4d00ee 2013-09-23 0intro (or else from standard input)
394 6f4d00ee 2013-09-23 0intro and writes it to the disk.
395 6f4d00ee 2013-09-23 0intro Inside the configuration file, the argument
397 6f4d00ee 2013-09-23 0intro may be used to stand in for the name of the disk holding the configuration.
398 6f4d00ee 2013-09-23 0intro The Plan 9 kernel boot process runs
399 6f4d00ee 2013-09-23 0intro .RB `` fossil
401 6f4d00ee 2013-09-23 0intro .IR disk ''
402 6f4d00ee 2013-09-23 0intro to start a Fossil file server.
403 6f4d00ee 2013-09-23 0intro The disk is just a convenient place to store configuration
404 6f4d00ee 2013-09-23 0intro information.
407 6f4d00ee 2013-09-23 0intro prints the vac score that resulted after the most recent archival snapshot
408 6f4d00ee 2013-09-23 0intro of the fossil in
410 6f4d00ee 2013-09-23 0intro .SH EXAMPLES
412 6f4d00ee 2013-09-23 0intro Place the root of the archive file system on
413 6f4d00ee 2013-09-23 0intro .B /n/dump
414 6f4d00ee 2013-09-23 0intro and show the modified times of the MIPS C compiler
415 6f4d00ee 2013-09-23 0intro over all dumps in December 2002:
419 6f4d00ee 2013-09-23 0intro ls -l /n/dump/2002/12*/mips/bin/vc
422 6f4d00ee 2013-09-23 0intro To get only one line of output for each version of the compiler:
425 6f4d00ee 2013-09-23 0intro ls -lp /n/dump/2002/12*/mips/bin/vc | uniq
429 6f4d00ee 2013-09-23 0intro Initialize a new file system, start the server with permission
430 6f4d00ee 2013-09-23 0intro checking turned off, create a users file, and mount the server:
433 6f4d00ee 2013-09-23 0intro fossil/flfmt /dev/sdC0/fossil
434 6f4d00ee 2013-09-23 0intro fossil/conf -w /dev/sdC0/fossil <<EOF
435 6f4d00ee 2013-09-23 0intro fsys main config
436 6f4d00ee 2013-09-23 0intro fsys main open -AWP
437 6f4d00ee 2013-09-23 0intro fsys main
438 6f4d00ee 2013-09-23 0intro create /active/adm adm sys d775
439 6f4d00ee 2013-09-23 0intro create /active/adm/users adm sys 664
441 6f4d00ee 2013-09-23 0intro srv -p fscons
442 6f4d00ee 2013-09-23 0intro srv fossil
444 6f4d00ee 2013-09-23 0intro fossil/fossil -f /dev/sdC0/fossil
445 6f4d00ee 2013-09-23 0intro mount /srv/fossil /n/fossil
448 6f4d00ee 2013-09-23 0intro See the discussion of the
452 6f4d00ee 2013-09-23 0intro commands in
453 6f4d00ee 2013-09-23 0intro .IR fossilcons (8)
454 6f4d00ee 2013-09-23 0intro for more about the user table.
457 6f4d00ee 2013-09-23 0intro Perhaps because the disk has been corrupted or replaced,
458 6f4d00ee 2013-09-23 0intro format a new file system using the last archive score printed
459 6f4d00ee 2013-09-23 0intro on the console:
462 6f4d00ee 2013-09-23 0intro fossil/flfmt -v b9b3...5559 /dev/sdC0/fossil
465 6f4d00ee 2013-09-23 0intro Note that while
466 6f4d00ee 2013-09-23 0intro .B /snapshot
467 6f4d00ee 2013-09-23 0intro will be lost,
468 6f4d00ee 2013-09-23 0intro .B /active
470 6f4d00ee 2013-09-23 0intro .B /archive
471 6f4d00ee 2013-09-23 0intro will be restored to their contents at the time of the
472 6f4d00ee 2013-09-23 0intro last archival snapshot.
475 6f4d00ee 2013-09-23 0intro Blindly accept the changes prescribed by
477 6f4d00ee 2013-09-23 0intro (not recommended):
480 6f4d00ee 2013-09-23 0intro fossil/flchk /dev/sdC0/fossil | sed -n 's/^# //p' >>/srv/fscons
483 6f4d00ee 2013-09-23 0intro A better strategy is to vet the output,
484 6f4d00ee 2013-09-23 0intro filter out any suggestions you're not comfortable with,
485 6f4d00ee 2013-09-23 0intro and then use the
487 6f4d00ee 2013-09-23 0intro command to prepare the script.
488 6f4d00ee 2013-09-23 0intro .SH SOURCE
489 b546bd6e 2017-07-16 rsc .B \*9/src/cmd/fossil
490 6f4d00ee 2013-09-23 0intro .SH SEE ALSO
491 6f4d00ee 2013-09-23 0intro .IR yesterday (1),
492 6f4d00ee 2013-09-23 0intro .IR fs (3),
493 6f4d00ee 2013-09-23 0intro .IR fs (4),
494 6f4d00ee 2013-09-23 0intro .IR srv (4),
495 6f4d00ee 2013-09-23 0intro .IR fossilcons (8),
496 6f4d00ee 2013-09-23 0intro .IR loadfossil (8),
497 6f4d00ee 2013-09-23 0intro .IR venti (8)
499 6f4d00ee 2013-09-23 0intro It is possible that the disk format (but not the Venti format)
500 6f4d00ee 2013-09-23 0intro will change in the future, to make the disk a full cache
501 6f4d00ee 2013-09-23 0intro rather than just a write buffer.
502 6f4d00ee 2013-09-23 0intro Changing to the new format will require reformatting
503 6f4d00ee 2013-09-23 0intro the disk as in the example above,
504 6f4d00ee 2013-09-23 0intro but note that this will preserve most of the file system
506 6f4d00ee 2013-09-23 0intro .BR /snapshot )
507 6f4d00ee 2013-09-23 0intro with little effort.
511 6f4d00ee 2013-09-23 0intro option currently assumes a block size of 8K bytes,
512 6f4d00ee 2013-09-23 0intro and a single file system per
513 6f4d00ee 2013-09-23 0intro .I fossil
514 6f4d00ee 2013-09-23 0intro instance.