OpenBSD-4.6/usr.sbin/afs/src/README

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'.