glenda.party
term% ls -F
term% cat index.txt
FOSSIL(4)                  Kernel Interfaces Manual                  FOSSIL(4)



NAME
       fossil, flchk, flfmt - archival file server

SYNOPSIS
       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

DESCRIPTION
       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‐
       chive/2002/1215/.

       The  attach name used in mount (see bind(1), bind(2) and attach(5)) se‐
       lects a file system to be served and optionally a subtree, in the  for‐
       mat fs[/dir].  An empty attach name selects main/active.

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

       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
       (sources.cs.bell-labs.com) 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 fossilcons(8).

       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 fossilcons(8) 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  fossil‐
       cons(8)).  Flchk prints fossil console commands that may be executed to
       take care of bad pointers (clrp), bad entries (clre), bad directory en‐
       tries  (clri), unreachable blocks (bfree).  Console commands are inter‐
       spersed 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
              made.

       -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 vac(1), so that the appropriate snapshot metadata
              is present.

       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.

EXAMPLES
       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
              EOF
              fossil/fossil -f /dev/sdC0/fossil
              mount /srv/fossil /n/fossil

       See the discussion of the users and uname commands in fossilcons(8) 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.

SOURCE
       /sys/src/cmd/fossil

SEE ALSO
       yesterday(1),   fs(3),  fs(4),  srv(4),  fossilcons(8),  loadfossil(8),
       venti(8)

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

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



                                                                     FOSSIL(4)