#ifdef it all out so we compile with heimdal-0.7.2

[arla.git] / doc / partsofarla.texi

@c Copyright (c) 1998 - 2000 Kungliga Tekniska Högskolan
@c (Royal Institute of Technology, Stockholm, Sweden).
@c All rights reserved.

@c $Id$

@node Parts of Arla, Debugging, AFS and the real world, Top
@comment  node-name,  next,  previous,  up
@chapter Parts of Arla

@quotation
@strong{Caution:} This text just tries to give a general picture.
For real info read the code. If you have any questions, mail 
@email{arla-drinkers@@stacken.kth.se}.
@end quotation


@menu
* How arla works::
* The relation between Arlad and NNPFS::
* The life of a file::
* Tools and libs::
* The files in arlad/::
* pioctl and kafs::
@end menu

@comment -----------------------------------------------------
@node How arla works, The relation between Arlad and NNPFS, Parts of Arla, Parts of Arla 
@heading How does arla work

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

Arlad is written in user-space for simpler debugging (and less rebooting).
As a uset space program arlad does not have the same limitations as if it 
would be written in the kernel. To avoid performance loss as much as possible,
nnpfs is caching data.

@c XXX ptr to coda and arla-usenix paper

nnpfs and arlad communicate with each other via a char-device-driver.
There is a rpc-protocol currenly used specially written for this
(@file{arlad/message.c})

nnpfs is written to be as simple as possible. Theoretically, nnpfs 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, nnpfs does not recognize which pioctl the user-level
program calls, it just passes this information on to arlad.

@comment -----------------------------------------------------
@node The relation between Arlad and NNPFS, The life of a file, How arla works, Parts of Arla
@heading The relation between Arlad and NNPFS

@example
Userland

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

@end example

@table @asis
@item [1] A char device (/dev/nnpfs0)
@item [2] NNPFS provides a filesystem for the vfs-layer in
the operating system.
@end table

@comment -----------------------------------------------------
@node The life of a file, Tools and libs, The relation between Arlad and NNPFS, Parts of Arla
@section The life of a file

@comment This a rough description of the life of a file. 

Step by step description of what happens during the creation of a file.
The names are inspired of BSD-style VFS-layer but the idea is the same
in most operating systems.

@itemize @bullet

@item The user decides to open a file.

@item open(2) syscall is issued.

@item The vfslayer sends a VOP_LOOKUP to nnpfs that is forwarded
to arlad with a getnode() (seq-num 1).

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

@item nnpfs inserts the node into the cache and returns from the device write.

@item arlad sends a wakeup rpc message (seq-num 1) to nnpfs.
If the return value is zero nnpfs 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.

@item 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 nnpfs having support for each error.

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

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

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

@item When nnpfs 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). 

@item 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. nnpfs reads this file
instead.

@item 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.

@item Now the user wants to read a file. 

@item read(2) system call is issued.

@item A VOP_READ is sent to the from the vfs-layer to nnpfs.

@item nnpfs 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.

@end itemize

@comment -----------------------------------------------------
@node Tools and libs, The files in arlad/, The life of a file, Parts of Arla
@heading Tools and libs

What other tools does the arla suite consists of

@table @asis

@item libutil: @code{util/libutil.a} - A library for the most often used 
modules like hashtable, double-linked list, logging functions,
date-parsing, etc

@item rx: @code{rx/librx.a} - The library for the rx protocol
 (@pxref{Rx protocol}).

@item lwp: @code{lwp/liblwp.a} - The library for the lwp thread-package
 (@pxref{LWP}).

@item ydr: @code{ydr/ydr} - A stub generator that replaces rxgen.

@item rxkad: @code{rxkad/librxkad.a} - The rx Kerberos authentication package.

@item roken: @code{lib/roken/libroken.a} - The library that will unbreak 
things that are missing or broken.

@item ko: @code{lib/ko/libko.a} - A library of functions that are arlad-core 
related but also are useful for programs like vos, pts, fs, etc.

@item arlalib: @code{appl/lib/libarlalib.a} - A broken library that does all 
the hard work with connections etc.

@item fs: @code{appl/fs/fs} - The fs util, extra feature 
(amongst others): getfid.

@item vos: @code{appl/vos/vos} - The vos util.

@item pts: @code{appl/pts/pts} - The pts util, extra feature: dump.

@item udebug: @code{appl/udebug/udebug} - Debug your ubik server.

@end table

@include tools.texi

@comment -----------------------------------------------------
@node The files in arlad/, pioctl and kafs, Tools and libs, Parts of Arla
@section The files in arlad/

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

@subsection The core of arlad

@table @asis

@item @file{adir.c} - contains all functions needed to to operations
on afs-directory files.

@item @file{afsdir_check.c} - check if an AFS-directory looks sane.

@item @file{arla.c} - The startup and the standalone (-t) code.

@item @file{arladeb.c} - The logging code specific to arla, like aliases
for debugging masks.

@item @file{cmcb.c} - The callback-server that is contacted by the 
server when a callback expires or a server wants to send an InitCallBackState.

@item @file{conn.c} - The connection cache, responsible for caching connection
based on pag and security index. It will also create new connection when
needed.

@item @file{cred.c} - Keep track of all credentials that all users have 
inserted. Indexed on pag.

@item @file{fbuf.c} - An interface between rx and filedescriptors. It is also 
used to mmap files. Used by @file{adir.c}.

@item @file{fcache.c} - Responsible for keeping track of files in the cache.
Also fetches files from the afs-server.

@item @file{fprio.c} - Tries to give files priority. These files are
therefore not garbarge-collected as fast as they would be otherwise. 
If you wonder what this is for, think of the disconnected mode.

@item @file{inter.c} - An interface to hide all junk in fcache, just give 
the items a VenusFid and you can access them this way.

@item @file{kernel.c} - The interface between arlad and the char-device.

@item @file{messages.c} - The rpc interface between arlad and nnpfs.

@item @file{volcache.c} - Cache for all volumes.

@end table

@subsection Operating system specific files

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

@table @asis

@item @file{aix-subr.c} - AIX
@item @file{bsd-subr.c} - FreeBSD 2.2.6, OpenBSD 2.2, 2.3, NetBSD 1.3.x
@item @file{hpux-subr.c} - HPUX
@item @file{irix-subr.c} - Irix
@item @file{linux-subr.c} - Linux 2.0.x, 2.1.x, 2.2
@item @file{solaris-subr.c} - Solaris 2.5.x, 2.6, 7
@item @file{sunos-subr.c} - SunOS
@item @file{unknown-subr.c} - Stub used when compiled on a unknown OS.

@end table
@comment -----------------------------------------------------

@node pioctl and kafs, ,The files in arlad/, Parts of Arla
@heading pioctl and kafs

The pioctl interface is the only part of nnpfs that is afs related.

pioctl is a ioctl but called with a path instead of a filedescriptor.
When you probe if there is a live afsclient you first run
@code{k_hasafs()} that probes if there is an afsclient around.
It also sets up some static variables in the library. So if you
start to do @code{pioctl()} w/o running @code{k_hasafs()}, you're 
up to funny errors, and/or get a corefile.

@code{k_hasafs()} does an @code{AFSCALL_PIOCTL} with opcode 
@code{ARLA_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 an @code{EINVAL} returned from @code{syscall(2)}.

The pioctl is used more then just for @code{AFSCALL_PIOCTL}, an other
use is @code{AFSCALL_SETPAG} (setting pag). It has also been in use for 
setting nnpfs debugging levels.

When nnpfs discovers that a path is given in the @code{pioctl()} it does a
@code{VOP_LOOKUP} on the path and if the returned value is a vnode that
resides in afs then it extracts the nnpfs-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 "nnpfs-fd" is the
arlad that should get this syscall.

An example of using @code{pioctl()}:

@example
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,ARLA_VIOC_FILE_CELL_NAME,&a_params,1) == -1) 
        return errno;

    return 0;
@}

int
main (int argc, char **argv)
@{
    char cell[100];

    if (!k_hasafs())
       errx (1, "there is no afs");

    if (fs_getfilecellname (".", cell, sizeof(cell)))
       errx (1, "fs_getfilecellname failed");

    printf ("cell for `.' is %s", cell);
    return 0;
@}

@end example

@comment -----------------------------------------------------

@c -----------------------------------------------------------
@c  Storybook
@c -----------------------------------------------------------
@c
@c Assar Westerlund tells a story to the rest of the world:
@c 
@c  John Hawkinson <jhawk@MIT.EDU> writes:
@c  > What does sl stand for?
@c  
@c  The short answer is that you should ask Mark.
@c  
@c  The long answer is that it used to be this old library part of MIT
@c  krb4 that was called `ss' (that I believe is short for subsystem, and
@c  that was part of some unknown operating system a long time ago.
@c  (Again, ask Mark.)), for reading and handling command line loops and
@c  parsing.  That wasn't IMHO optimal so we wrote a new library which we
@c  called `sl'.  The reason for SL is that the local transport authority
@c  in Stockholm used to be called SS (Stockholms Sparvagar) but due to
@c  the bad PR this abbreviation got under the second world war and that
@c  they almost have abandoned trolleys (Sparvagnar) today, they renamed 
@c  themselves to SL (Storstockholms Lokaltrafik).
@c
@c 
@c [ lha: Mark is only known to assar ]
@c [ assar: Mark == Mark Eichin ]
@c -----------------------------------------------------------

@c From: Craig_Everhart@transarc.com
@c Subject: Re: [OpenAFS] Silly question, Just interested
@c To: <openafs-info@openafs.org>
@c Date: Fri, 19 Jul 2002 10:00:19 -0400 (EDT)
@c 
@c 
@c The other way around: Vice was the Vast Integrated Computing Environment
@c on the server, and Venus was the client-side component but I don't know
@c if it was an acronym.
@c 
@c              Craig
@c