FOSSIL(4)                                               FOSSIL(4)

     NAME
          fossil, flchk, flfmt - archival file server

     SYNOPSIS
          fossil/fossil [ -Dt ] [ -c cmd ]...  [ -f file ] [ -m free-
          memory-percent ]

          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 option-
          ally 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 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 cre-
          ated from the date and time of the snapshot:
          /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
          sequence number if more than one archival snapshot is done
          in a day.  For the first snapshot, s is null.  For the sub-
          sequent snapshots, s is .1, .2, .3, etc.  The root of the
          main file system that is frozen for the first archival snap-
          shot of December 15, 2002 will be named /archive/2002/1215/.

          The attach name used in mount (see bind(1), bind(2) and

     FOSSIL(4)                                               FOSSIL(4)

          attach(5)) selects a file system to be served and optionally
          a subtree, in the format fs[/dir].  An empty attach name
          selects main/active.

          Fossil normally requires all users except `none' to provide
          authentication tickets on each attach(5). To keep just any-
          one from connecting, `none' 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
          `none'.  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
          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 (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 configured 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 authentica-
                  tion and all protocol messages are written to stan-
                  dard 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 containing commands,
                  and ``srv -pcons,'' which starts a file server con-
                  sole on /srv/cons.  See fossilcons(8) for more
                  information.

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

     FOSSIL(4)                                               FOSSIL(4)

          -m      Allocate free-memory-percent percent of the avail-
                  able 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 con-
          sole check command (see fossilcons(8)). Flchk prints fossil
          console commands that may be executed to take care of bad
          pointers (clrp), bad entries (clre), bad directory entries
          (clri), unreachable blocks (bfree).  Console commands are
          interspersed with more detailed commentary on the file sys-
          tem.  The commands are distinguished by being prefixed with
          sharp signs.  Note that all proposed fixes are rather dras-
          tic: offending pieces of file system are simply chopped off.

          Flchk does not modify the file system, so it is safe to run
          concurrently 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 image for consistency, which includes
                   all the archives to Venti and can take a very long
                   time.  In fast mode, flchk avoids walking in Venti
                   blocks whenever possible.

          -c ncache
                   Keep a cache of ncache (by default, 1000) file sys-
                   tem 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.

     FOSSIL(4)                                               FOSSIL(4)

          -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 snap-
                        shot 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 configuration 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 kernel 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 modified 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 com-
          piler:

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

          Initialize a new file system, start the server with permis-
          sion 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

     FOSSIL(4)                                               FOSSIL(4)

               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 recom-
          mended):

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

          A better strategy is to vet the output, filter out any sug-
          gestions 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 for-
          mat) 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.