 Milko ($Id: README,v 1.27 2000/07/02 15:30:44 tol Exp $)
=====

Note: 
  milko is still highly experimental, and is neither stable nor
  full-featured.

* Parts

  fs		- FileServer
  vldb		- Volume Location DataBase-server
  pts		- ProTection-Server
  appl/sked	- maintaining volumes the hard way

  lib/dpart     - partition parsing and handling
  lib/mdir	- directory handling (unused ?)
  lib/svol	- 
  lib/vld	- volume,voldb<->afs interfrace.
		  This would also be the place where to
		  add caching of ``vnodes'', manybe fbuf's too.
		  contains the simple (stupid) volume
		  and ro-volume.
  lib/voldb	- file and directory vnode db.
		  There is today one backend of voldb: vdb_flat
		  vdb_flat is a flat-db to store inodes. Not very
		  smart, but should be efficent enough.
  lib/vstatus	- the volume-node

* Installation

 1. Create a /vicepa in whatever way

 2. CellServDB and ThisCell

    Add your cell to $PREFIX/etc/CellServDB and make it the default
    cell by adding to to $PREFIX/etc/ThisCell.

 3. If you have Kerberos (you really should have, because it is not
    tested without).

    This text assumes kth-krb.
    [If you want support for another kerberos, modify/add apropriate text]
    
    Get a srvtab for afs@YOUR.REALM, or if you want to use a "subcell"
    use afs.your.subcell@YOUR.REALM, where your.subcell is the instance.
    I you don't already have one, ksrvutil will create a principal
    afs@YOUR.REALM for you. Put the srvtab i $PREFIX/etc/srvtab
    (really $sysconfdir). Note the empty string '' when you input the
    Kerberos instance below.

    datan:~$ /usr/athena/sbin/ksrvutil -p lha.admin -f /usr/arla/etc/srvtab get
    Name [rcmd]: afs
    Instance [datan]: ''
    Realm [MY.REALM]: 
    Is this correct? (y,n) [y]:
    Add more keys (y,n) [n]:
    Password for lha.admin@MY.REALM:
    Added afs@MY.REALM
    Old keyfile in /usr/arla/etc/srvtab.old.

    Verify that you got you principal right

    datan:~$ ksrvutil -f /usr/arla/etc/srvtab  list
    Version    Principal
       2     afs@MY.REALM

    Add your "afs admin instance" to the $PREFIX/etc/superuserlist
    file. This can be whatever you like, but has been in most cases
    .admin (or .root depending on local religion).

    Get your "afs admin instance".

    datan:~$ kauth lha.root
    lha.root@MY.REALM's Password:

    Verify that you get an afs token

    datan:~$ afslog -c my.cell
    datan:~$ klist -v
    Ticket file:    /tmp/tkt0
    Principal:      lha@MY.REALM

      Issued           Expires          Principal (kvno)
    May 25 03:07:02  May 25 13:07:02  krbtgt.MY.REALM@MY.REALM (1)
    May 25 03:06:49  May 25 13:06:49  afs@MY.REALM (2)
    
    Note that the ``afs'' key also can be named ``afs.my.cell''.
    Its imperative that the key versions (kvno) match up.

 4. Start vldb-server.

    It will NOT create a databasefile (vl_database) if missing.
    The first time you have to run the vldbserver with -create
    as an argument.
    
    datan:~/obj/arla/milko/vldb# gdb -q vldbserver
    (gdb) r
    Starting program: /home/lha/obj/milko/vldb/vldbserver
    Milko vldbserver 0.26 started

    The vldbserver can be used with -noauth for testing purposes.

 5. Add root.afs to vldb

    You have to use arla's vos.

    datan:~$ vos createentry -id root.afs -host localhost \
    -fsserver localhost -part /vicepa -rw 3

    If you use afs.my.cell@MY.REALM (not afs@MY.REALM), you
    have to add ``-cell my.cell'' to the above command line.

 6. Create volume root.afs on disk

    datan:~obj/milko/appl/sked# ./sked volcreate /vicepa 3 root.afs
    volume 3 created successfully

 7. Start ptserver

    datan:~obj/milko/fs# gdb -q ptserver
    (gdb) r
    Starting program: /home/lha/obj/milko/pts/ptserver

    If you need to initialize the pts database, use ptserver -create.

 8. Start fileserver

    datan:~obj/milko/fs# gdb -q fileserver
    (gdb) r
    Starting program: /home/lha/obj/milko/fs/fileserver
    fileserver booting
    fileserver started, serving data

    Handy args which can be given to fileserver (check with 
    fileserver --help):
	--noauth (for testing)
	--log=file (instead of logging to syslog)
	--debug=all|errors|warnings|voldb|vld|salvage|fs
	--cell=cellname

 9. bosserver

    After running make install you can use $PREFIX/libexec/bosserver
    to start both the vlserver, ptserver and fileserver.

 10. run-tests

    Run run-tests in tests/,   WORKDIR=/afs ./run-tests -milko -all

 11. Now what ?

    Find bugs, and report them to <arla-drinkers@stacken.kth.se>.

* Profiling

  If you want profiling information, add -pg (gcc) to CFLAGS, LDFLAGS and
  recompile.

  When you feel you're done, send the fileserver a USR1 and look for the
  gprof.out in /vicepa.

* Advice

  Documentation how things works is included in the sourcecode.

  There should be a notice in the top (after the copyright blub)
  that will give you a general idea what the module (should) do.

  Each function should documented in the comment above the function.
  Where each argument is described. Any simple/complex/no-trivial
  locking event should be documented.

  If you see any assert()s in the top of the function (just after
  the local variables) they are PART OF the documentation. See
  example [1] below. This makes it easier to find interface
  changes and other brainlossage.

  If you find something that is undocumented, write documentation!
  If you find documentation that is invalid, rewrite!

  I'm told the documentation in c-code isn't enough. Guess there
  should be a greater plan.

[1]
   Here is an example that the function foo() requires that bar
   is set. It isn't written in the comment field, instead
   its checked runtime.

	int
	foo (int *bar)
	{
		int baz;
	
		assert (bar);
		return 0;
	}
