From 6f4d00ee45693290fae042b27536b54f77b96acd Mon Sep 17 00:00:00 2001 From: David du Colombier <0intro@gmail.com> Date: Mon, 23 Sep 2013 23:00:39 +0200 Subject: fossil: import from plan 9 R=rsc https://codereview.appspot.com/7988047 --- man/man4/fossil.4 | 514 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 514 insertions(+) create mode 100644 man/man4/fossil.4 (limited to 'man/man4') diff --git a/man/man4/fossil.4 b/man/man4/fossil.4 new file mode 100644 index 00000000..6bb4a392 --- /dev/null +++ b/man/man4/fossil.4 @@ -0,0 +1,514 @@ +.TH FOSSIL 4 +.SH NAME +fossil, flchk, flfmt \- archival file server +.SH SYNOPSIS +.B fossil/fossil +[ +.B -Dt +] +[ +.B -c +.I cmd +]... +[ +.B -f +.I file +] +[ +.B -m +.I free-memory-percent +] +.PP +.B fossil/flchk +[ +.B -f +] +[ +.B -c +.I ncache +] +[ +.B -h +.I host +] +.I file +.PP +.B fossil/flfmt +[ +.B -y +] +[ +.B -b +.I blocksize +] +[ +.B -h +.I host +] +[ +.B -l +.I label +] +[ +.B -v +.I score +] +.I file +.PP +.B fossil/conf +[ +.B -w +] +.I file +[ +.I config +] +.PP +.B fossil/last +.I file +.SH DESCRIPTION +.I Fossil +is the main file system for Plan 9. +Unlike the Plan 9 file servers of old, +.I fossil +is a collection of user-space programs that run on a standard Plan 9 kernel. +The name of the main fossil file server at Murray Hill is +.BR pie . +The Plan 9 distribution file server, +.BR sources , +is also a fossil server. +.PP +.I Fossil +is structured as a magnetic disk write buffer +optionally backed by a Venti server for archival storage. +It serves the Plan 9 protocol via TCP. +A +.I fossil +file server conventionally presents +three trees in the root directory of each file system: +.BR active , +.BR archive , +and +.BR snapshot . +.B /active +is the root of a conventional file system +whose blocks are stored in a disk file. +In a typical configuration, the file server periodically +marks the entire file system copy-on-write, effectively +taking a snapshot of the file system at that moment. +This snapshot is made available in a name +created from the date and time of the snapshot: +.BI /snapshot/ yyyy / mmdd / hhmm \fR, +where +.I yyyy +is the full year, +.I mm +is the month number, +.I dd +is the day number, +.I hh +is the hour, +and +.I mm +is the minute. +The snapshots in +.B /snapshot +are ephemeral: eventually they are deleted +to reclaim the disk space they occupy. +Long-lasting snapshots stored on a Venti server +are kept in +.B /archive +and also named from the date (though not the time) of the snapshot: +.BI /archive/ yyyy / mmdds \fR, +where +.IR yyyy , +.IR mm , +and +.I dd +are year, month, and day as before, +and +.I s +is a sequence number if more than one +archival snapshot is done in a day. +For the first snapshot, +.I s +is null. +For the subsequent snapshots, +.I s +is +.BR .1 , +.BR .2 , +.BR .3 , +etc. +The root of the main file system that is frozen +for the first archival snapshot of December 15, 2002 +will be named +.BR /archive/2002/1215/ . +.PP +The attach name used in +.I mount +(see +.IR bind (1), +.IR bind (2) +and +.IR attach (5)) +selects a file system to be served +and optionally a subtree, +in the format +.IB fs \fR[\fB/ dir \fR]. +An empty attach name selects +.BR main/active . +.PP +.I Fossil +normally requires all users except +.L none +to provide authentication tickets on each +.IR attach (5). +To keep just anyone from connecting, +.L none +is only allowed to attach after another user +has successfully attached on the same +connection. +The other user effectively acts as a chaperone +for +.LR none . +Authentication can be disabled using the +.B -A +flag to +.B open +or +.B srv +(see +.IR fossilcons (8)). +.PP +The groups called +.B noworld +and +.B write +are special on the file server. +Any user belonging to +.B noworld +has attenuated access privileges. +Specifically, when checking such a user's access to files, +the file's permission bits are first ANDed +with 0770 for normal files and 0771 for directories. +The effect is to deny world access permissions to +.B noworld +users, except when walking into directories. +If the +.B write +group exists, then the file system appears read-only +to users not in the group. +This is used to make the Plan 9 distribution file server +.RI ( sources.cs.bell-labs.com ) +readable by the world but writable only to the developers. +.PP +.I Fossil +starts a new instance of the fossil file server. +It is configured mainly through console commands, +documented in +.IR fossilcons (8). +.PP +The options are: +.TF "-c\fI cmd +.PD +.TP +.B -D +Toggle the debugging flag, which is initially off. +When the flag is set, information about authentication +and all protocol messages are written to standard error. +.TP +.B -t +Start a file server console on +.BR /dev/cons . +If this option is given, +.I fossil +does not fork itself into the background. +.TP +.BI -c " cmd +Execute the console command +.IR cmd . +This option may be repeated to give multiple +commands. +Typically the only commands given on the +command line are +.RB `` ".\fI file" ,'' +which executes a file containing commands, +and +.RB `` "srv -p" \fIcons \fR,'' +which starts a file server console on +.BI /srv/ cons \fR. +See +.IR fossilcons (8) +for more information. +.TP +.BI -f " file +Read and execute console commands stored in the Fossil disk +.IR file . +.I Conf +.RI ( q.v. ) +reads and writes the command set stored in the disk. +.TP +.B -m +Allocate +.I free-memory-percent +percent of the available free RAM for buffers. +This overrides all other memory sizing parameters, +notably the +.B -c +option to +.BR open . +30% is a reasonable choice. +.PD +.PP +.I Flchk +checks the fossil file system stored in +.I file +for inconsistencies. +.I Flchk +is deprecated in favor of the console +.B check +command (see +.IR fossilcons (8)). +.I Flchk +prints +.I fossil +console commands that may be +executed to take care of +bad pointers +.RB ( clrp ), +bad entries +.RB ( clre ), +bad directory entries +.RB ( clri ), +unreachable blocks +.RB ( bfree ). +Console commands are interspersed with +more detailed commentary on the file system. +The commands are distinguished by being prefixed with +sharp signs. +Note that all proposed fixes are rather drastic: offending +pieces of file system are simply chopped off. +.PP +.I Flchk +does +.I not +modify the file system, so it is safe to +run concurrently with +.IR fossil , +though in this case +the list of unreachable +blocks and any inconsistencies involving the active file system +should be taken with a grain of salt. +.PP +The options are: +.TF "-h\fI host +.PD +.TP +.B -f +Fast mode. +By default, +.I flchk +checks the entire file system image for consistency, +which includes all the archives to Venti +and can take a very long time. +In fast mode, +.I flchk +avoids walking in Venti blocks +whenever possible. +.TP +.BI -c " ncache +Keep a cache of +.I ncache +(by default, 1000) +file system blocks in memory during the check. +.TP +.BI -h " host +Use +.I host +as the Venti server. +.PD +.PP +.I Flfmt +prepares +.I file +as a new fossil file system. +The file system is initialized with three empty directories +.BR active , +.BR archive , +and +.BR snapshot , +as described above. +The options are: +.TF "-b\fI blocksize +.PD +.TP +.B -y +Yes mode. +By default, +.I flfmt +will prompt for confirmation before formatting +a file that already contains a fossil file system, +and before formatting a file that is not served +directly by a kernel device. +If the +.B -y +flag is given, no such checks are made. +.TP +.BI -b " blocksize +Set the file system block size (by default, 8192). +.TP +.BI -h " host +Use +.I host +as the Venti server. +.TP +.BI -l " label +Set the textual label on the file system to +.IR label . +The label is only a comment. +.TP +.BI -v " score +Initialize the file system using the vac file +system stored on Venti at +.IR score . +The score should have been generated by +.I fossil +rather than by +.IR vac (1), +so that the appropriate snapshot metadata is present. +.PD +.PP +.I Conf +reads or writes the configuration branded on the Fossil disk +.IR file . +By default, it reads the configuration from the disk and prints it to +standard output. +If the +.B -w +flag is given, +.I conf +reads a new configuration from +.I config +(or else from standard input) +and writes it to the disk. +Inside the configuration file, the argument +.L * +may be used to stand in for the name of the disk holding the configuration. +The Plan 9 kernel boot process runs +.RB `` fossil +.B -f +.IR disk '' +to start a Fossil file server. +The disk is just a convenient place to store configuration +information. +.PP +.I Last +prints the vac score that resulted after the most recent archival snapshot +of the fossil in +.I file. +.SH EXAMPLES +.PP +Place the root of the archive file system on +.B /n/dump +and show the modified times of the MIPS C compiler +over all dumps in December 2002: +.IP +.EX +9fs dump +ls -l /n/dump/2002/12*/mips/bin/vc +.EE +.PP +To get only one line of output for each version of the compiler: +.IP +.EX +ls -lp /n/dump/2002/12*/mips/bin/vc | uniq +.EE +.ne 14 +.PP +Initialize a new file system, start the server with permission +checking turned off, create a users file, and mount the server: +.IP +.EX +fossil/flfmt /dev/sdC0/fossil +fossil/conf -w /dev/sdC0/fossil <>/srv/fscons +.EE +.LP +A better strategy is to vet the output, +filter out any suggestions you're not comfortable with, +and then use the +.I sed +command to prepare the script. +.SH SOURCE +.B /sys/src/cmd/fossil +.SH SEE ALSO +.IR yesterday (1), +.IR fs (3), +.IR fs (4), +.IR srv (4), +.IR fossilcons (8), +.IR loadfossil (8), +.IR venti (8) +.SH BUGS +It is possible that the disk format (but not the Venti format) +will change in the future, to make the disk a full cache +rather than just a write buffer. +Changing to the new format will require reformatting +the disk as in the example above, +but note that this will preserve most of the file system +(all but +.BR /snapshot ) +with little effort. +.PP +The +.B -m +option currently assumes a block size of 8K bytes, +and a single file system per +.I fossil +instance. -- cgit v1.2.3