README for arla-0.35 ($arla: $) $arla: README,v 1.87 2003/07/15 16:22:58 lha Exp $ 1. What is arla? Arla is a free AFS cache-manager implementation. 2. Where do I find this file? This file is contained inside ftp://ftp.stacken.kth.se/pub/arla/arla-0.35.tar.gz (aka /afs/stacken.kth.se/ftp/pub/arla/arla-0.35.tar.gz). 3. What is AFS? AFS is a world-wide distributed file system. See <http://www.transarc.com/afs/transarc.com/public/www/Product/AFS/FAQ/faq.html> for more information. 4. What's included in arla? There is kernel support (with different level of functionality) for the following operating systems: - FreeBSD 4.5 (and later), and 5.1 and later - OpenBSD 3.1 - 3.2 - NetBSD 1.5 and 1.6 - Linux 2.2.x, 2.4.x - SunOS 4 - Solaris 2.6, 7, and 8 - AIX 4.x - IRIX 6.x - Digital Unix 4.0, Compaq Tru64 5.0 (OSF/1) - Mac OS X 10.0 and 10.2 (and Darwin) A cache manager (arlad) that works both in user-level mode and with the kernel module. The user-level mode is quite portable and has even been working under Windows NT (with the cygwin32 libraries). Some simple programs (amon, bos, fs, pts, tokens, vos, and udebug). An experimental AFS server called milko. 5. What's the status of arla? - Working stable client (currently cacheing whole files) Arlad caches ranges of files, from the first byte to the last requested. - Authentication (using kth-krb4 or any other krb4 implantation) - Used in production systems with OpenBSD, FreeBSD, NetBSD, Linux, and Mac OS X - Some administration programs (bos, fs, vos, pts and bos) - An experimental AFS server (milko) - Graphical program, amon, for monitoring the state of the cache. - A graphical interface for managing ACLs (for MacOS X only) - A configuration utility for Mac OS X 6. What do I need to run arla? If you have one of the systems listed above you will be able to mount afs as a file system (and probably to panic your kernel as well). The user-level programs should work and build on almost any other unix dialect. If you want to use authentication, you will also need a Kerberos v4 implementation. We use and recommend the one at <http://www.pdc.kth.se/kth-krb/>. OpenBSD 2.3 and above already ships with kth-krb. On OpenBSD 2.3 only, you'll have to add the line 'AFS=yes' to /etc/mk.conf and rebuild libkafs and afslog. (can be found in /usr/src/kerberosIV/{kafs,afslog}) (versions since 2.3 have AFS=yes on by default, except for m88k). If you are using MIT-Kerberos or CNS Kerberos you can find a replacement for libkafs in http://web.mit.edu/openafs/krbafs/. Then you need to use the --with-krbafs=dir option when running configure. Thanks to Derrick J Brashear <shadow@dementia.org> and Alexandra Ellwood <lxs@mit.edu> for making this available for the MIT kerberos users. If you don't have Kerberos, you should still be able to test that it works, but there's not much point in running unauthenticated, and it's not very tested. 7. How do I compile/install/start arla? See the file INSTALL 8. What do I do when I find a bug? Report it with as much detail as possible (including patches) to <arla-drinkers@stacken.kth.se>. If you find a bug, and do not have a clue what is wrong, please run arlad with `arlad -n -z --debug=almost-all' and append the output the the mail. You can also turn on debug on an already running arlad with `fs arladebug <debug-level>'. To enable debugging in the nnpfs kernel module, use `fs nnpfsdebug <debug-level>'. The output will end up in your syslog (like /var/log/messages or /var/adm/messages). If arlad crashes, at least run gdb on the core dump and do a `bt'. Print out variables around where it crashes if they seem useful. If you don't get a core dump, try starting arlad under gdb (the `-n' option is useful here) and then do the same thing when it crashes. If the kernel crashes, try to obtain a crash dump by whatever means your OS has for this and then run the debugger on it. The documentation on your OS should have more information on how to perform this task. Without this info we are probably as lost as you are. 9. How do I adjust the amount of debug information? Both arlad and the nnpfs (the kernel module) have variables for controlling what type of debug messages should be printed. They are controlled by the `--debug' option to arlad and then by running `fs arladebug' and `fs nnpfsdebug'. 10. How hard is it to port arla to a new operating system? It's not hard. The user-level code is quite portable and is not much different between different operating systems. The kernel module is system-specific but not that large and you can probably start with the one in `nnpfs/SYSTEM' that's most similar to your system. If you're interested in doing the port or even run Arla on an OS not mentioned above, send mail to <arla-drinkers@stacken.kth.se>. 11. Known problems. OpenBSD on some architectures have serious problems with mmap. If arlad doesn't seem to work om your system run configure with `--disable-mmap'. This problem has only been noticed on sun4m platforms. The same problem exists on Mac OS X 10.1 (Darwin 1.4). Use the --disable-mmap option. If you have problems with stale data cached or arlad is misbehaving a lot try zapping the entire cache directory (`/usr/arla/cache' per default) and restarting arlad. 12. How can I help? With code. Send us bug-reports and/or patches. 13. Are there any mailing lists for arla? arla-drinkers@stacken.kth.se general discussion arla-announce@stacken.kth.se only announcements Send mail to <LIST>-request@stacken.kth.se to subscribe. 14. Is there a web page? Yes, http://www.stacken.kth.se/project/arla/ 15. Are there any copyrights on parts of arla? lwp and rx are copyrighted by IBM. We're grateful to Derrick J Brashear <shadow@dementia.org> and Jim Doyle <jrd@bu.edu> for making them available. The rxkad implementation was written by Björn Grönvall <bg@sics.se> and is also part of the kth-krb distribution. editline was written by Simmule Turner and Rich Salz. The code for disconnected operation was written by Wuwei Shen. The code for gluing these together were written by ourselves. <arla-drinkers@stacken.kth.se> 16. What has changed since *? See NEWS and ChangeLog. 17. What does `arla' mean? - Arla in Swedish means `early'. Most of the code has been written early in the morning. - Arla is also the name of the largest producer of dairy products in Sweden. They produce, among others, a milk product called `fil' (filmjölk = sour milk) which also happens to be the swedish word for `file'.