Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
FOSSIL(4)		   Kernel Interfaces Manual		     FOSSIL(4)

       fossil, flchk, flfmt - archival file server

       fossil/fossil  [	-Dt ] [	-c cmd ]...  [ -f file ] [ -m free-memory-per-
       cent ]

       fossil/flchk [ -f ] [ -c	ncache ] [ -h host ] file

       fossil/flfmt [ -y ] [ -b	blocksize ] [ -h host ]	[  -l  label  ]	 [  -v
       score ] file

       fossil/conf [ -w	] file [ config	]

       fossil/last file

       Fossil  is  the	main  file  system for Plan 9.	Unlike the Plan	9 file
       servers of old, 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 pie.  The Plan	9 distribution file  server,  sources,
       is also a fossil	server.

       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 fossil file server	conventionally presents	three trees in
       the root	directory of each file system: active, archive,	and  snapshot.
       /active	is  the	 root  of  a conventional file system whose blocks are
       stored in a disk	file.  In a typical configuration, the file server pe-
       riodically marks	the entire file	system copy-on-write, effectively tak-
       ing 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 snap-
       shot: /snapshot/yyyy/mmdd/hhmm, where yyyy is the full year, mm is  the
       month  number,  dd  is  the  day	 number, hh is the hour, and mm	is the
       minute.	The snapshots in /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 /archive and also named  from  the
       date  (though not the time) of the snapshot: /archive/yyyy/mmdds, where
       yyyy, mm, and dd	are year, month, and day as before, and	 s  is	a  se-
       quence number if	more than one archival snapshot	is done	in a day.  For
       the first snapshot, s is	null.  For the subsequent snapshots, s is  .1,
       .2,  .3,	 etc.  The root	of the main file system	that is	frozen for the
       first archival snapshot	of  December  15,  2002	 will  be  named  /ar-

       The  attach  name  used	in  mount (see and selects a file system to be
       served and optionally a subtree,	in the format fs[/dir].	 An empty  at-
       tach name selects main/active.

       Fossil  normally	 requires  all	users except to	provide	authentication
       tickets on each To keep just anyone from	connecting, is only allowed to
       attach after another user has successfully attached on the same connec-
       tion.  The other	user effectively acts as a chaperone  for  Authentica-
       tion can	be disabled using the -A flag to open or srv (see

       The  groups  called  noworld  and write are special on the file server.
       Any  user  belonging  to	 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 noworld
       users, except when walking into directories.  If	the  write  group  ex-
       ists, then the file system appears read-only to users not in the	group.
       This  is	 used  to  make	 the   Plan   9	  distribution	 file	server
       (  readable  by	the world but writable only to
       the developers.

       Fossil starts a new instance of the fossil file server.	It is  config-
       ured mainly through console commands, documented	in

       The options are:

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

       -t     Start  a	file  server  console on /dev/cons.  If	this option is
	      given, fossil does not fork itself into the background.

       -c cmd Execute the console command cmd.	This option may	be repeated to
	      give  multiple  commands.	  Typically the	only commands given on
	      the command line are ``. file,'' which executes a	file  contain-
	      ing  commands,  and  ``srv  -pcons,'' which starts a file	server
	      console on /srv/cons.  See for more information.

       -f file
	      Read and execute console commands	 stored	 in  the  Fossil  disk
	      file.   Conf  (q.v.)  reads and writes the command set stored in
	      the disk.

       -m     Allocate free-memory-percent percent of the available  free  RAM
	      for buffers.  This overrides all other memory sizing parameters,
	      notably the -c option to open.  30% is a reasonable choice.

       Flchk checks the	fossil file system stored in file for inconsistencies.
       Flchk  is  deprecated  in favor of the console check command (see Flchk
       prints fossil console commands that may be executed to take care	of bad
       pointers	 (clrp), bad entries (clre), bad directory entries (clri), un-
       reachable blocks	(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.

       Flchk  does  not	 modify	 the file system, so it	is safe	to run concur-
       rently with 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.

       The options are:

       -f     Fast mode.  By default, flchk checks the entire file system  im-
	      age  for	consistency,  which includes all the archives to Venti
	      and can take a very long time.  In fast mode, flchk avoids walk-
	      ing in Venti blocks whenever possible.

       -c ncache
	      Keep  a cache of ncache (by default, 1000) file system blocks in
	      memory during the	check.

       -h host
	      Use host as the Venti server.

       Flfmt prepares file as a	new fossil file	system.	 The  file  system  is
       initialized with	three empty directories	active,	archive, and snapshot,
       as described above.  The	options	are:

       -y     Yes mode.	 By default, 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	 -y  flag is given, no such checks are

       -b blocksize
	      Set the file system block	size (by default, 8192).

       -h host
	      Use host as the Venti server.

       -l label
	      Set the textual label on the file	system to label.  The label is
	      only a comment.

       -v score
	      Initialize  the  file system using the vac file system stored on
	      Venti at score.  The score should	have been generated by	fossil
	      rather  than  by	so  that  the appropriate snapshot metadata is

       Conf reads or writes the	configuration branded on the Fossil disk file.
       By  default,  it	reads the configuration	from the disk and prints it to
       standard	output.	 If the	-w flag	is given, conf reads a new  configura-
       tion  from  config  (or	else from standard input) and writes it	to the
       disk.  Inside the configuration file, the argument may be used to stand
       in for the name of the disk holding the configuration.  The Plan	9 ker-
       nel boot	process	runs ``fossil -f disk''	to start a Fossil file server.
       The disk	is just	a convenient place to store configuration information.

       Last  prints the	vac score that resulted	after the most recent archival
       snapshot	of the fossil in file.

       Place the root of the archive file system on /n/dump and	show the modi-
       fied times of the MIPS C	compiler over all dumps	in December 2002:

	      9fs dump
	      ls -l /n/dump/2002/12*/mips/bin/vc

       To get only one line of output for each version of the compiler:

	      ls -lp /n/dump/2002/12*/mips/bin/vc | uniq

       Initialize a new	file system, start the server with permission checking
       turned off, create a users file,	and mount the server:

	      fossil/flfmt /dev/sdC0/fossil
	      fossil/conf -w /dev/sdC0/fossil <<EOF
	      fsys main	config
	      fsys main	open -AWP
	      fsys main
	      create /active/adm adm sys d775
	      create /active/adm/users adm sys 664
	      users -w
	      srv -p fscons
	      srv fossil
	      fossil/fossil -f /dev/sdC0/fossil
	      mount /srv/fossil	/n/fossil

       See the discussion of the users and uname commands in  for  more	 about
       the user	table.

       Perhaps	because	 the disk has been corrupted or	replaced, format a new
       file system using the last archive score	printed	on the console:

	      fossil/flfmt -v b9b3...5559 /dev/sdC0/fossil

       Note that while /snapshot will be lost, /active and  /archive  will  be
       restored	to their contents at the time of the last archival snapshot.

       Blindly accept the changes prescribed by	flchk (not recommended):

	      fossil/flchk /dev/sdC0/fossil | sed -n 's/^# //p'	>>/srv/fscons

       A  better  strategy  is	to  vet	the output, filter out any suggestions
       you're not comfortable with, and	then use the sed  command  to  prepare
       the script.


       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	/snapshot) with	little effort.

       The  -m option currently	assumes	a block	size of	8K bytes, and a	single
       file system per fossil instance.



Want to link to this manual page? Use this URL:

home | help