This is Info file arla.info, produced by Makeinfo version 1.68 from the
input file arla.texi.

INFO-DIR-SECTION Arla
START-INFO-DIR-ENTRY
* Arla: (arla).           Arla - The Free AFS Clone
END-INFO-DIR-ENTRY


File: arla.info,  Node: Top,  Prev: (dir),  Up: (dir)

Arla
****

Arla is a free AFS clone from KTH.

* Menu:

* Introduction::
* Parts of Arla::
* Debugging::
* Authors::
* Oddities::
* Acknowledgments::


File: arla.info,  Node: Introduction,  Next: Parts of Arla,  Prev: Top,  Up: Top

Introduction
************

     *Caution:* this is alpha quality software. If something doesn't
     work, it's probably because it doesn't. If you don't have backup of
     your data, take backup.

What is Arla?
=============

Arla is a free AFS clone. Some of the goals are:

   * have an implementation that is free and can be used for adding
     stuff like disconnected-mode support to.

   * provide an alternative to Transarc's AFS-client

   * Add support for platfroms that doesn't have AFS support today.

This release is known to work on the following platforms: NetBSD,
OpenBSD, FreeBSD, Linux, SunOS, Solaris, AIX, IRIX, Digital UNIX,
Rhapsody.

Status
======

Arla has the following features (this does not mean any of this works):

   * a rxgen implementation called ydr

   * partly implemented fs, vos, pts commands.

   * a implementaion of rxkad written outside USA without any export
     restrictions

Bug reports
===========

If you find bugs in this software, make sure it is a genuine bug and not
just a part of the code that isn't implemented.

Bug reports should be sent to <arla-drinkers@stacken.kth.se>. Please
include information on what machine and operating system (including
version) you are running, what you are trying to do, what happens, what
you think should have happened, an example for us to repeat, the output
you get when trying the example, and a patch for the problem if you have
one. Please make any patches with `diff -u' or `diff -c'.

Suggestions, comments and other non bug reports are also welcome.

Mailing list
============

There are two mailing lists with talk about Arla.
<arla-announce@stacken.kth.se> is a low-volume announcement list, while
<arla-drinkers@stacken.kth.se> is for general discussion.  Send a
message to <LIST-request@stacken.kth.se> to subscribe.


File: arla.info,  Node: Parts of Arla,  Next: Debugging,  Prev: Introduction,  Up: Top

Top

Parts of Arla
*************

     *Caution:* This text just tries to give a general picture.  For
     real info read the code. If you have any questions, mail
     <arla-drinkers@stacken.kth.se>.

* Menu:

* How arla works::
* Arlad and XFS relation::
* The life of a file::
* Tools and libs::
* The files in arlad/::
* pioctl and kafs::


File: arla.info,  Node: How arla works,  Next: Arlad and XFS relation,  Prev: Parts of Arla,  Up: Parts of Arla

How does arla work
==================

Arla consists of two parts, a userland process (arlad) and the
kernel-module (xfs).

Arlad is written in user-space for simpler debugging (and less
rebooting).  And there is not the same limitations as if it would be
written in the kernel.  To avoid the performance loss xfs does caching.

xfs and arlad communicate with each other via a char-device-driver.
There is a rpc-protocol currenly used specially written for this
(`arlad/message.c')

xfs is written to be as simple as possible. Theoretically, xfs could be
used by other user-space daemons to implement a file system. Some
parts, such as syscalls, are arla-specific. These parts are designed to
be as general as possible.

For example, xfs does not recognize which pioctl the user-level program
calls, it just passes this information on to arlad.


File: arla.info,  Node: Arlad and XFS relation,  Next: The life of a file,  Prev: How arla works,  Up: Parts of Arla

Arlad and XFS relation
======================

     Userland
     
                                  ---------
                 Edit file        | Arlad |  ------> Network
                                  ---------
                ----------------------|[1]----
                 -------           -------
     Kernel      | VFS | <--[2]--> | XFS |
                 -------           -------

[1] A char device (/dev/xfs0)

[2] Xfs provides a filesystem for the vfs-layer in
     the operating system.


File: arla.info,  Node: The life of a file,  Next: Tools and libs,  Prev: Arlad and XFS relation,  Up: Parts of Arla

The life of a file
==================

This a rough description of the life of a file. The names are inspired
of BSD-style VFS-layer but the idea is the same in most operating
systems.

   * The user decides to open a file.

   * The vfslayer sends a VOP_LOOKUP to xfs that is forwarded to arlad
     with a getnode() (seq-num 1).

   * arlad tries to find the requested file and then, if found, sends an
     install_node to xfs by writing to the xfs character device.

   * xfs inserts the node into the cache and returns from the device
     write.

   * arla sends a wakeup rpc message (seq-num 1). If the return value is
     zero xfs tries to find the node in the cache, if not found it
     might have been flushed out of the cache and the whole thing is
     repeated.

   * If a none-zero return value is returned, this value is sent as
     reply to the user. This way arla can decide what error message is
     returned, without xfs having support for each error.

   * xfs now checks if it has the valid attributes. If the attributes
     are invalid, xfs will send a rpc message to arlad to refresh it.

   * Since the user wanted to open the file, a getdata rpc message is
     sent from xfs to arlad. Now arlad fetches the files from the afs
     file server.

   * Arlad stores the file in the file cache. All vnode operations will
     be done on this file. Now arlad sends a installdata to xfs.

   * When xfs recives the installdata it looks up the node in the cache,
     and then it does a VOP_LOOKUP to find a vnode to the cachefile
     (and store it to keep it for future use).

   * The same thing is done when the file is a directory, except that
     the directory is converted from the afs directory format to an
     operating system dependent format and stored in a file. xfs reads
     this file instead.

   * If the directory is modified locally, write operations are done on
     the file obtained from the afs-server, and when done the newly
     changed file is converted and reinstalled.

   * Now the user wants to read a file.

   * A VOP_READ is sent to the from the vfs-layer to xfs.

   * xfs checks if it has valid attributes/and data (and updates if
     needed).  Now VOP_READ is simply performed on the stored vnode of
     the cachefile.


File: arla.info,  Node: Tools and libs,  Next: The files in arlad/,  Prev: The life of a file,  Up: Parts of Arla

Tools and libs
==============

What other tools does the arla suite consists of

`libutil' - a library for most used modules like hashtable,
     double-linked list, logging functions, date-parsing, etc

`rx' - the library for the rx protocol (*Note Rx protocol::).

`lwp' - the library for the lwp thread-package
     (*Note LWP::).

`ydr' - A stub generator that replaces rxgen.

`rxkad' - The rx Kerberos authentication package.

`lib/roken/' - The library that will unbreak things that
     is missing or broken.

`lib/ko' - A library of functions that is arlad-core related
     but is also useful for programs like vos, pts, fs, etc.

`appl/libarlalib.a' - A broken library that does all the hard
     work with connections etc.

`appl/fs' - The fs util, extra feature: getfid

`appl/vos' - The vos util

`appl/pts' - The pts util, extra feature: dump

`appl/udebug' - Debug your ubik server

File: arla.info,  Node: Rx protocol,  Next: LWP,  Up: Tools and libs

Rx protocol
===========

Rx is run over UDP.

rxgen or ydr is used to generate stub-files, ydr is better since it
generates prototypes too.

Current implemetation of rx it not that beautiful.


File: arla.info,  Node: LWP,  Prev: Rx protocol,  Up: Tools and libs

LWP
===

LWP is a pre-epmtive thread package. It does it's context-switching by
creating a private stack for each thread. The heart of the package is
select(2).

The core of the package is `process.S'. Its currenty built with a
bourne-shell file. `Process.s' is preprocessed with `cpp' and then
given to (g)as. The magic how to build this file a portable way is not
fun.

The stack is checked for overruns in context-switches, but that is often
too late. It might be an idea to add a `red zone' at the top of the
stack to be able to detect overruns.


File: arla.info,  Node: The files in arlad/,  Next: pioctl and kafs,  Prev: Tools and libs,  Up: Parts of Arla

The files in arlad/
===================

This is a short describtion of the files to bring new deveplopers up to
speed.

The core of arlad
-----------------

`adir.c' - contain all functions needed to to operations
     on afs-directory file.

`afsdir_check.c' - check if a afs-directory looks sane.

`arla.c' - The startup and the standalone (-t) code.

`arladeb.c' - The logging code specific to arla, like aliases
     for debugging masks.

`cmcb.c' - The callback-server that is contacted by the
     server when a callback expire or a server want to send a
     InitCallBackState.

`conn.c' - The connection cache, responsible for caching connection
     based on pag and security index. It will also create new
     connection when needed.

`cred.c' - Keep track of all credentails that all users have
     inserted. Indexed on pag.

`fbuf.c' - An interface between rx and filedescriptors. It also
     mmap files. `adir.c' uses it.

`fcache.c' - Responsible for keeping track of files in the cache.
     Also fetches files from the afs-server.

`fprio.c' - Tries to give files priority and therefore not
     garbarge-collected that fast they would be otherwise. Think
     disconnected mode.

`inter.c' - A interface to hide all junk in fcache, just give it
     a VenusFid and you have it.

`kernel.c' - The interface between arlad and the char-device.

`messages.c' - The rpc interface between arlad and xfs.

`volcache.c' - Cache for all volumes.
Operatingsystem specific files
------------------------------

These are the files that contain operating specific functions.  Today
it's just conv_dir().

`aix-subr.c' - AIX

`bsd-subr.c' - FreeBSD 2.2.6, OpenBSD 2.2, 2.3, NetBSD 1.3.x

`hpux-subr.c' - HPUX

`irix-subr.c' - Irix

`linux-subr.c' - Linux 2.0.x, 2.1.x, 2.2

`solaris-subr.c' - Solaris 2.5.x, 2.6, 7

`sunos-subr.c' - SunOS

`unknown-subr.c' - Stub used when compiled on a unknown OS.

File: arla.info,  Node: pioctl and kafs,  Prev: The files in arlad/,  Up: Parts of Arla

pioctl and kafs
===============

pioctl is a ioctl but with a path instead of a filedescriptor.  When
you probe if there is a live afsclient you first run `k_hasafs()' that
probe if there is a afsclient around.  It also setup some static
variables in the library. So if you start to do `pioctl()' w/o running
`k_hasafs()', you're up to funny errors.

What `k_hasafs()' does is `AFSCALL_PIOCTL' with opcode `VIOCSETTOK' and
insize == 0, ie you try to set a token (ticket) that is 0 bytes long.
This is cleary invalid and kafs expects to find a `EINVAL' returned
from `syscall(2)'.

The pioctl is used more then just for `AFSCALL_PIOCTL', other uses are
`AFSCALL_SETPAG' (setting pag). It has also been in use for setting xfs
debugginglevels.

When xfs discovers that a path is given in the `pioctl()' it does a
`VOP_LOOKUP' on the path and if the returned a vnode that resides in
afs then it extracts the xfs-handle for that node (that just happens to
be the VenusFid) and passes that on to arlad.

The only ugly thing about the current implentation is that the syscall
code assumes that the arlad on "xfs-fd" is the arlad that should get
this syscall.

An example of `pioctl()'

` int fs_getfilecellname(char *path, char *cell, size_t len) {
struct ViceIoctl a_params;

a_params.in_size=0;     a_params.out_size=len;     a_params.in=NULL;
a_params.out=cell;

if (k_pioctl(path,VIOC_FILE_CELL_NAME,&a_params,1) == -1)
return errno;

return 0; } '


File: arla.info,  Node: Debugging,  Next: Oddities,  Prev: Parts of Arla,  Up: Top

Debugging
=========

Arlad
-----

If arlad is run without any arguments arlad will fork(2) and log to
syslog(3). To stop forking use the -nofork (-n) switch.

To enable more debuggning run arla with the switch
-debug=module1,module2,...  One useful combination is
        --debug=all,-cleaner
The cleaner output is usully not that intresting and can be ignored.

To set the debugging with a running arlad use `fs arladeb' as root.

     datan:~# fs arladeb
     arladebug is: none
     datan:~# fs arladeb almost-all
     datan:~#

When arlad doesn't log to stdout, or a file, it logs to syslog.

xfs
---

XFS debugging does almost look the same on all platforms. They all
share same debugging flags, but not all are enabled on all platforms.

Either you edit the file `xfs/<your-os>/xfs_deb.c' or use fs to set it.

     datan:~# fs xfsdebug
     xfsdebug is: none
     datan:~# fs xfsdebug almost-all
     datan:~#

The logging of xfs ends up in your syslog. Syslog usully logs to
/var/log or /var/adm (look in /etc/syslog.conf).


File: arla.info,  Node: Oddities,  Next: Authors,  Prev: Debugging,  Up: Top

Oddities
========

AFS
---

   * Directories - UnixModeBits are ignored when the vnode is a
     directory.

   * Errnos are sent over the network. Like Solaris ENOTEMPTY(93)
     doesn't  even map to an error on sunos4 where ENOTEMPTY is 66.

Operatingsystems
----------------

   * On irix 6.5 you have to build the dirents depending on what ABI
     of the binary you are currently running.


File: arla.info,  Node: Authors,  Next: Acknowledgments,  Prev: Oddities,  Up: Top

Authors
=======

Currently writing on arla are

Assar Westerlund, Everything

Magnus Ahltorp, Linux xfs

Artur Grabowski, BSD xfs

Love Hornquist-Astrand, Everything

Robert Burgess, fs, Solaris xfs

Johan Danielsson, OSF/1 xfs

Hans Insulander, pts

Mattias Amnefelt, vos

File: arla.info,  Node: Acknowledgments,  Prev: Authors,  Up: Top

Acknowledgments
***************

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.

Some of the files in `libroken' come from Berkeley by the way of
NetBSD/FreeBSD

`editline' was written by Simmule Turner and Rich Salz.

The code for gluing these together were written by ourselves.

Bugfixes, documentation, encouragement, and code has been contributed
by:
Aaron M. Ucko
     <amu@MIT.EDU>

Alec Wolman
     <wolman@cs.washington.edu>

Alexandra Ellwood
     <lxs@MIT.EDU>

Brad Keryan
     <keryan@andrew.cmu.edu>

Constantine Sapuntzakis
     <csapuntz@openbsd.org>

Dan Winship
     <danw@MIT.EDU>

Derrick J Brashear
     <shadow@dementia.org>

Jim Doyle
     <jrd@bu.edu>

John Davison
     <davisoja@clarkson.edu>

John Hawkinson
     <jhawk@MIT.EDU>

Karl Ramm
     <kcr@MIT.EDU>

Mark Eichin
     <eichin@kitten.gen.ma.us>

Per Boussard T/ED
     <Per.Boussard@era-t.ericsson.se>

Dima Ruban
     <dima@best.net>

Max
     <davros@cyclone.Stanford.EDU>

Andrzej Filinski
     <andrzej@daimi.aau.dk>

Chuck Lever
     <chuckl@netscape.com>

WUWEI SHEN
     <wwshen@engin.umich.edu>

Cheng Jin
     <chengjin@eecs.umich.edu>

Paul Callaway
     <pcallawa@umich.edu>

Brandon S. Allbery
     <allbery@ece.cmu.edu>

Ken Raeburn
     <raeburn@raeburn.org>

If you have done something and are not mentioned here, please send mail
to <arla-drinkers@stacken.kth.se>.

If you are mentioned here and have not contributed, that's because we
expect you to.



Tag Table:
Node: Top210
Node: Introduction418
Node: Parts of Arla2323
Node: How arla works2758
Node: Arlad and XFS relation3719
Node: The life of a file4342
Node: Tools and libs6748
Node: Rx protocol7763
Node: LWP8028
Node: The files in arlad/8651
Node: pioctl and kafs10673
Node: Debugging12211
Node: Oddities13330
Node: Authors13805
Node: Acknowledgments14164

End Tag Table
