milko/README

   1  Milko ($Id$)
   2 =====
   3
   4 Note:
   5   milko is still highly experimental, and is neither stable nor
   6   full-featured.
   7
   8 * Parts
   9
  10   fs            - FileServer
  11   vldb          - Volume Location DataBase-server
  12   pts           - ProTection-Server
  13   appl/sked     - maintaining volumes the hard way
  14
  15   lib/dpart     - partition parsing and handling
  16   lib/mdir      - directory handling (unused ?)
  17   lib/svol      -
  18   lib/vld       - volume,voldb<->afs interfrace.
  19                   This would also be the place where to
  20                   add caching of ``vnodes'', manybe fbuf's too.
  21                   contains the simple (stupid) volume
  22                   and ro-volume.
  23   lib/voldb     - file and directory vnode db.
  24                   There is today one backend of voldb: vdb_flat
  25                   vdb_flat is a flat-db to store inodes. Not very
  26                   smart, but should be efficent enough.
  27   lib/vstatus   - the volume-node
  28
  29 * Installation
  30
  31  1. Create a /vicepa in whatever way
  32
  33  2. CellServDB and ThisCell
  34
  35     Add your cell to $PREFIX/etc/CellServDB and make it the default
  36     cell by adding to to $PREFIX/etc/ThisCell.
  37
  38  3. If you have Kerberos (you really should have, because it is not
  39     tested without).
  40
  41     This text assumes kth-krb.
  42     [If you want support for another kerberos, modify/add apropriate text]
  43
  44     Get a srvtab for afs@YOUR.REALM, or if you want to use a "subcell"
  45     use afs.your.subcell@YOUR.REALM, where your.subcell is the instance.
  46     I you don't already have one, ksrvutil will create a principal
  47     afs@YOUR.REALM for you. Put the srvtab i $PREFIX/etc/srvtab
  48     (really $sysconfdir). Note the empty string '' when you input the
  49     Kerberos instance below.
  50
  51     datan:~$ /usr/athena/sbin/ksrvutil -p lha.admin -f /usr/arla/etc/srvtab get
  52     Name [rcmd]: afs
  53     Instance [datan]: ''
  54     Realm [MY.REALM]:
  55     Is this correct? (y,n) [y]:
  56     Add more keys (y,n) [n]:
  57     Password for lha.admin@MY.REALM:
  58     Added afs@MY.REALM
  59     Old keyfile in /usr/arla/etc/srvtab.old.
  60
  61     Verify that you got you principal right
  62
  63     datan:~$ ksrvutil -f /usr/arla/etc/srvtab  list
  64     Version    Principal
  65        2     afs@MY.REALM
  66
  67     Add your "afs admin instance" to the $PREFIX/etc/superuserlist
  68     file. This can be whatever you like, but has been in most cases
  69     .admin (or .root depending on local religion).
  70
  71     Get your "afs admin instance".
  72
  73     datan:~$ kauth lha.root
  74     lha.root@MY.REALM's Password:
  75
  76     Verify that you get an afs token
  77
  78     datan:~$ afslog -c my.cell
  79     datan:~$ klist -v
  80     Ticket file:    /tmp/tkt0
  81     Principal:      lha@MY.REALM
  82
  83       Issued           Expires          Principal (kvno)
  84     May 25 03:07:02  May 25 13:07:02  krbtgt.MY.REALM@MY.REALM (1)
  85     May 25 03:06:49  May 25 13:06:49  afs@MY.REALM (2)
  86
  87     Note that the ``afs'' key also can be named ``afs.my.cell''.
  88     Its imperative that the key versions (kvno) match up.
  89
  90  4. Start vldb-server.
  91
  92     It will NOT create a databasefile (vl_database) if missing.
  93     The first time you have to run the vldbserver with -create
  94     as an argument.
  95
  96     datan:~/obj/arla/milko/vldb# gdb -q vldbserver
  97     (gdb) r
  98     Starting program: /home/lha/obj/milko/vldb/vldbserver
  99     Milko vldbserver 0.26 started
 100
 101     The vldbserver can be used with -noauth for testing purposes.
 102
 103  5. Add root.afs to vldb
 104
 105     You have to use arla's vos.
 106
 107     datan:~$ vos createentry -id root.afs -host myhost \
 108     -fsserver myhost -part /vicepa -rw 3
 109
 110     If you use afs.my.cell@MY.REALM (not afs@MY.REALM), you
 111     have to add ``-cell my.cell'' to the above command line.
 112
 113  6. Create volume root.afs on disk
 114
 115     datan:~obj/milko/appl/sked# ./sked volcreate /vicepa 3 root.afs
 116     volume 3 created successfully
 117
 118  7. Start ptserver
 119
 120     datan:~obj/milko/fs# gdb -q ptserver
 121     (gdb) r
 122     Starting program: /home/lha/obj/milko/pts/ptserver
 123
 124     If you need to initialize the pts database, use ptserver -create.
 125
 126  8. Start fileserver
 127
 128     datan:~obj/milko/fs# gdb -q fileserver
 129     (gdb) r
 130     Starting program: /home/lha/obj/milko/fs/fileserver
 131     fileserver booting
 132     fileserver started, serving data
 133
 134     Handy args which can be given to fileserver (check with
 135     fileserver --help):
 136         --noauth (for testing)
 137         --log=file (instead of logging to syslog)
 138         --debug=all|errors|warnings|voldb|vld|salvage|fs
 139         --cell=cellname
 140
 141  9. bosserver
 142
 143     After running make install you can use $PREFIX/libexec/bosserver
 144     to start both the vlserver, ptserver and fileserver.
 145
 146  10. run-tests
 147
 148     Run run-tests in tests/,   WORKDIR=/afs ./run-tests -milko -all
 149
 150  11. Now what ?
 151
 152     Find bugs, and report them to <arla-drinkers@stacken.kth.se>.
 153
 154 * Profiling
 155
 156   If you want profiling information, add -pg (gcc) to CFLAGS, LDFLAGS and
 157   recompile.
 158
 159   When you feel you're done, send the fileserver a USR1 and look for the
 160   gprof.out in /vicepa.
 161
 162 * Advice
 163
 164   Documentation how things works is included in the sourcecode.
 165
 166   There should be a notice in the top (after the copyright blub)
 167   that will give you a general idea what the module (should) do.
 168
 169   Each function should be documented in the comment above the function,
 170   where each argument is described. Any simple/complex/no-trivial
 171   locking event should be documented.
 172
 173   If you see any assert()s in the top of the function (just after
 174   the local variables) they are PART OF the documentation. See
 175   example [1] below. This makes it easier to find interface
 176   changes and other brainlossage.
 177
 178   If you find something that is undocumented, write documentation!
 179   If you find documentation that is invalid, rewrite!
 180
 181   I'm told the documentation in c-code isn't enough. Guess there
 182   should be a greater plan.
 183
 184 [1]
 185    Here is an example that the function foo() requires that bar
 186    is set. It isn't written in the comment field, instead
 187    its checked runtime.
 188
 189         int
 190         foo (int *bar)
 191         {
 192                 int baz;
 193
 194                 assert (bar);
 195                 return 0;
 196         }