README

   1 README for arla-0.36 ($Name$)
   2 $Id$
   3
   4 1. What is arla?
   5
   6 Arla is a free AFS cache-manager implementation.
   7
   8 2. Where do I find this file?
   9
  10 This file is contained inside
  11 ftp://ftp.stacken.kth.se/pub/arla/arla-0.36.tar.gz
  12 (aka /afs/stacken.kth.se/ftp/pub/arla/arla-0.36.tar.gz).
  13
  14 3. What is AFS?
  15
  16 AFS is a world-wide distributed file system.  See
  17 <http://grand.central.org/twiki/bin/view/AFSLore/GeneralFAQ>
  18 for more information.
  19
  20 4. What's included in arla?
  21
  22 There is kernel support (with different level of functionality) for
  23 the following operating systems:
  24
  25 - FreeBSD 4.5 and later, 5.1 and later
  26 - OpenBSD 3.1 - 3.2 (u)
  27 - NetBSD 1.5 (u) and 1.6
  28 - Linux 2.4.x, 2.6.x (e)
  29 - Mac OS X 10.0, 10.2 and Darwin
  30 - Windows 2000 (e)
  31 - Solaris 2.6, 7, and 8 (u)
  32 - AIX 4.x (u)
  33 - IRIX 6.x (u)
  34
  35 (e): Experimental
  36 (u): Untested
  37
  38 A cache manager (arlad) that works both in user-level mode and with
  39 the kernel module.  The user-level mode is quite portable and has even
  40 been working under Windows NT (with the cygwin32 libraries).
  41
  42 Some simple programs (amon, bos, fs, pts, tokens, vos, and udebug).
  43
  44 An experimental AFS server called milko.
  45
  46 5. What's the status of arla?
  47
  48 - Working stable client (depending on OS)
  49   Arlad caches ranges of files, from the first byte to the last requested.
  50 - Authentication (tested with kerberos v5 heimdal 0.6.1)
  51 - Used in production systems with OpenBSD, FreeBSD, NetBSD, Linux, and
  52   Mac OS X
  53 - Some administration programs (bos, fs, vos, pts and bos)
  54 - An experimental AFS server (milko)
  55 - Graphical program, amon, for monitoring the state of the cache.
  56 - Statistics gathering code for performance monitoring
  57 - A graphical interface for managing ACLs (for MacOS X only)
  58 - A configuration utility for Mac OS X
  59
  60 6. What do I need to run arla?
  61
  62 If you have one of the systems listed above you will be able to mount
  63 afs as a file system (kernel panics have happened, but are not the
  64 rule).
  65
  66 The user-level programs should work and build on almost any unix
  67 dialect.
  68
  69 If you want to use authentication, you will also need a Kerberos v5
  70 implementation.  We use and recommend the one at
  71 <http://www.pdc.kth.se/heimdal/>.
  72
  73 OpenBSD 2.3 and above already ships with kth-krb.  On OpenBSD 2.3 only, you'll
  74 have to add the line 'AFS=yes' to /etc/mk.conf and rebuild libkafs and
  75 afslog.  (can be found in /usr/src/kerberosIV/{kafs,afslog}) (versions
  76 since 2.3 have AFS=yes on by default, except for m88k).
  77
  78 If you are using MIT-Kerberos or CNS Kerberos you can find a replacement
  79 for libkafs in http://web.mit.edu/openafs/krbafs/. Then you
  80 need to use the --with-krbafs=dir option when running configure.
  81 Thanks to Derrick J Brashear <shadow@dementia.org> and Alexandra
  82 Ellwood <lxs@mit.edu> for making this available for the MIT kerberos
  83 users.
  84
  85 If you don't have Kerberos, you should still be able to test that it
  86 works, but there's not much point in running unauthenticated, and it's
  87 not very tested.
  88
  89 7. How do I compile/install/start arla?
  90
  91 See the file INSTALL
  92
  93 8. What do I do when I find a bug?
  94
  95 Report it with as much detail as possible (including patches) to
  96 <arla-drinkers@stacken.kth.se>.
  97
  98 If you find a bug, and do not have a clue what is wrong, please run
  99 arlad with `arlad -n -z --debug=almost-all' and append the output the
 100 the mail.  You can also turn on debug on an already running arlad with
 101 `fs arladebug <debug-level>'.  To enable debugging in the nnpfs kernel
 102 module, use `fs nnpfsdebug <debug-level>'.  The output will end up in
 103 your syslog (like /var/log/messages or /var/adm/messages).
 104
 105 If arlad crashes, at least run gdb on the core dump and do a `bt'.
 106 Print out variables around where it crashes if they seem useful.  If
 107 you don't get a core dump, try starting arlad under gdb (the `-n'
 108 option is useful here) and then do the same thing when it crashes.
 109
 110 If the kernel crashes, try to obtain a crash dump by whatever means
 111 your OS has for this and then run the debugger on it.  The
 112 documentation on your OS should have more information on how to
 113 perform this task.
 114
 115 Without this info we are probably as lost as you are.
 116
 117 9. How do I adjust the amount of debug information?
 118
 119 Both arlad and the nnpfs (the kernel module) have variables for
 120 controlling what type of debug messages should be printed.
 121
 122 They are controlled by the `--debug' option to arlad and then by
 123 running `fs arladebug' and `fs nnpfsdebug'.
 124
 125 10. How hard is it to port arla to a new operating system?
 126
 127 It's not hard.  The user-level code is quite portable and is not much
 128 different between different operating systems.  The kernel module is
 129 system-specific but not that large and you can probably start with the
 130 one in `nnpfs/SYSTEM' that's most similar to your system.  If you're
 131 interested in doing the port or even run Arla on an OS not mentioned
 132 above, send mail to
 133 <arla-drinkers@stacken.kth.se>.
 134
 135 11. Known problems.
 136
 137 OpenBSD on some architectures have serious problems with mmap.  If arlad
 138 doesn't seem to work om your system run configure with `--disable-mmap'.
 139 This problem has only been noticed on sun4m platforms.
 140
 141 The same problem exists on Mac OS X 10.1 (Darwin 1.4). Use the
 142 --disable-mmap option.
 143
 144 If you have problems with stale data cached or arlad is misbehaving a
 145 lot try zapping the entire cache directory (`/usr/arla/cache' per
 146 default) and restarting arlad.
 147
 148 FreeBSD 5.2 has sendfile(2) which is not supported. The use of this
 149 syscall might give you the contents of uninitialized RAM instead
 150 of the requested file.
 151
 152 12. How can I help?
 153
 154 With code.  Send us bug-reports and/or patches.
 155
 156 13. Are there any mailing lists for arla?
 157
 158 arla-drinkers@stacken.kth.se    general discussion
 159 arla-announce@stacken.kth.se    only announcements
 160
 161 Send mail to <LIST>-request@stacken.kth.se to subscribe.
 162
 163 14. Is there a web page?
 164
 165 Yes, http://www.stacken.kth.se/project/arla/
 166
 167 15. Are there any copyrights on parts of arla?
 168
 169 lwp and rx are copyrighted by IBM.  We're grateful to Derrick J
 170 Brashear <shadow@dementia.org> and Jim Doyle <jrd@bu.edu> for making
 171 them available.
 172
 173 The rxkad implementation was written by Björn Grönvall <bg@sics.se>
 174 and is also part of the kth-krb distribution.
 175
 176 editline was written by Simmule Turner and Rich Salz.
 177
 178 The code for disconnected operation was written by Wuwei Shen.
 179
 180 The code for gluing these together were written by ourselves.
 181
 182 <arla-drinkers@stacken.kth.se>
 183
 184 16. What has changed since *?
 185
 186 See NEWS and ChangeLog.
 187
 188 17. What does `arla' mean?
 189
 190 - Arla in Swedish means `early'.  Most of the code has been written
 191 early in the morning.
 192
 193 - Arla is also the name of the largest producer of dairy products in
 194 Sweden.  They produce, among others, a milk product called `fil'
 195 (filmjölk = sour milk) which also happens to be the swedish word for
 196 `file'.