ahltorp / arlanohist Goto Github PK

README for arla-0.36 ($Name: HEAD $)
$Id: README,v 1.89 2004/12/22 19:22:28 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.36.tar.gz
(aka /afs/stacken.kth.se/ftp/pub/arla/arla-0.36.tar.gz).

3. What is AFS?

AFS is a world-wide distributed file system.  See
<http://grand.central.org/twiki/bin/view/AFSLore/GeneralFAQ>
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, 5.1 and later
- OpenBSD 3.1 - 3.2 (u)
- NetBSD 1.5 (u) and 1.6
- Linux 2.4.x, 2.6.x (e)
- Mac OS X 10.0, 10.2 and Darwin
- Windows 2000 (e)
- Solaris 2.6, 7, and 8 (u)
- AIX 4.x (u)
- IRIX 6.x (u)

(e): Experimental
(u): Untested

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 (depending on OS)
  Arlad caches ranges of files, from the first byte to the last requested.
- Authentication (tested with kerberos v5 heimdal 0.6.1)
- 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.
- Statistics gathering code for performance monitoring
- 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 (kernel panics have happened, but are not the
rule).

The user-level programs should work and build on almost any unix
dialect.

If you want to use authentication, you will also need a Kerberos v5
implementation.  We use and recommend the one at
<http://www.pdc.kth.se/heimdal/>.

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 <[email protected]> and Alexandra
Ellwood <[email protected]> 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
<[email protected]>.

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
<[email protected]>.

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.

FreeBSD 5.2 has sendfile(2) which is not supported. The use of this 
syscall might give you the contents of uninitialized RAM instead
of the requested file.

12. How can I help?

With code.  Send us bug-reports and/or patches.

13. Are there any mailing lists for arla?

[email protected]	general discussion
[email protected]	only announcements

Send mail to <LIST>[email protected] 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 <[email protected]> and Jim Doyle <[email protected]> for making
them available.

The rxkad implementation was written by Björn Grönvall <[email protected]>
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.

<[email protected]>

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