====================
  			     kAFS: AFS FILESYSTEM
  			     ====================
  
  Contents:
  
   - Overview.
   - Usage.
   - Mountpoints.
   - Proc filesystem.
   - The cell database.
   - Security.
   - Examples.
  
  
  ========
  OVERVIEW
  ========
  
  This filesystem provides a fairly simple secure AFS filesystem driver. It is
  under development and does not yet provide the full feature set.  The features
  it does support include:
  
   (*) Security (currently only AFS kaserver and KerberosIV tickets).
  
   (*) File reading and writing.
  
   (*) Automounting.
  
   (*) Local caching (via fscache).
  
  It does not yet support the following AFS features:
  
   (*) pioctl() system call.
  
  
  ===========
  COMPILATION
  ===========
  
  The filesystem should be enabled by turning on the kernel configuration
  options:
  
  	CONFIG_AF_RXRPC		- The RxRPC protocol transport
  	CONFIG_RXKAD		- The RxRPC Kerberos security handler
  	CONFIG_AFS		- The AFS filesystem
  
  Additionally, the following can be turned on to aid debugging:
  
  	CONFIG_AF_RXRPC_DEBUG	- Permit AF_RXRPC debugging to be enabled
  	CONFIG_AFS_DEBUG	- Permit AFS debugging to be enabled
  
  They permit the debugging messages to be turned on dynamically by manipulating
  the masks in the following files:
  
  	/sys/module/af_rxrpc/parameters/debug
  	/sys/module/kafs/parameters/debug
  
  
  =====
  USAGE
  =====
  
  When inserting the driver modules the root cell must be specified along with a
  list of volume location server IP addresses:
  
  	modprobe af_rxrpc
  	modprobe rxkad
  	modprobe kafs rootcell=cambridge.redhat.com:172.16.18.73:172.16.18.91
  
  The first module is the AF_RXRPC network protocol driver.  This provides the
  RxRPC remote operation protocol and may also be accessed from userspace.  See:
  
  	Documentation/networking/rxrpc.txt
  
  The second module is the kerberos RxRPC security driver, and the third module
  is the actual filesystem driver for the AFS filesystem.
  
  Once the module has been loaded, more modules can be added by the following
  procedure:
  
  	echo add grand.central.org 18.9.48.14:128.2.203.61:130.237.48.87 >/proc/fs/afs/cells
  
  Where the parameters to the "add" command are the name of a cell and a list of
  volume location servers within that cell, with the latter separated by colons.
  
  Filesystems can be mounted anywhere by commands similar to the following:
  
  	mount -t afs "%cambridge.redhat.com:root.afs." /afs
  	mount -t afs "#cambridge.redhat.com:root.cell." /afs/cambridge
  	mount -t afs "#root.afs." /afs
  	mount -t afs "#root.cell." /afs/cambridge
  
  Where the initial character is either a hash or a percent symbol depending on
  whether you definitely want a R/W volume (hash) or whether you'd prefer a R/O
  volume, but are willing to use a R/W volume instead (percent).
  
  The name of the volume can be suffixes with ".backup" or ".readonly" to
  specify connection to only volumes of those types.
  
  The name of the cell is optional, and if not given during a mount, then the
  named volume will be looked up in the cell specified during modprobe.
  
  Additional cells can be added through /proc (see later section).
  
  
  ===========
  MOUNTPOINTS
  ===========
  
  AFS has a concept of mountpoints. In AFS terms, these are specially formatted
  symbolic links (of the same form as the "device name" passed to mount).  kAFS
  presents these to the user as directories that have a follow-link capability
  (ie: symbolic link semantics).  If anyone attempts to access them, they will
  automatically cause the target volume to be mounted (if possible) on that site.
  
  Automatically mounted filesystems will be automatically unmounted approximately
  twenty minutes after they were last used.  Alternatively they can be unmounted
  directly with the umount() system call.
  
  Manually unmounting an AFS volume will cause any idle submounts upon it to be
  culled first.  If all are culled, then the requested volume will also be
  unmounted, otherwise error EBUSY will be returned.
  
  This can be used by the administrator to attempt to unmount the whole AFS tree
  mounted on /afs in one go by doing:
  
  	umount /afs
  
  
  ===============
  PROC FILESYSTEM
  ===============
  
  The AFS modules creates a "/proc/fs/afs/" directory and populates it:
  
    (*) A "cells" file that lists cells currently known to the afs module and
        their usage counts:
  
  	[root@andromeda ~]# cat /proc/fs/afs/cells
  	USE NAME
  	  3 cambridge.redhat.com
  
    (*) A directory per cell that contains files that list volume location
        servers, volumes, and active servers known within that cell.
  
  	[root@andromeda ~]# cat /proc/fs/afs/cambridge.redhat.com/servers
  	USE ADDR            STATE
  	  4 172.16.18.91        0
  	[root@andromeda ~]# cat /proc/fs/afs/cambridge.redhat.com/vlservers
  	ADDRESS
  	172.16.18.91
  	[root@andromeda ~]# cat /proc/fs/afs/cambridge.redhat.com/volumes
  	USE STT VLID[0]  VLID[1]  VLID[2]  NAME
  	  1 Val 20000000 20000001 20000002 root.afs
  
  
  =================
  THE CELL DATABASE
  =================
  
  The filesystem maintains an internal database of all the cells it knows and the
  IP addresses of the volume location servers for those cells.  The cell to which
  the system belongs is added to the database when modprobe is performed by the
  "rootcell=" argument or, if compiled in, using a "kafs.rootcell=" argument on
  the kernel command line.
  
  Further cells can be added by commands similar to the following:
  
  	echo add CELLNAME VLADDR[:VLADDR][:VLADDR]... >/proc/fs/afs/cells
  	echo add grand.central.org 18.9.48.14:128.2.203.61:130.237.48.87 >/proc/fs/afs/cells
  
  No other cell database operations are available at this time.
  
  
  ========
  SECURITY
  ========
  
  Secure operations are initiated by acquiring a key using the klog program.  A
  very primitive klog program is available at:
  
  	http://people.redhat.com/~dhowells/rxrpc/klog.c
  
  This should be compiled by:
  
  	make klog LDLIBS="-lcrypto -lcrypt -lkrb4 -lkeyutils"
  
  And then run as:
  
  	./klog
  
  Assuming it's successful, this adds a key of type RxRPC, named for the service
  and cell, eg: "afs@<cellname>".  This can be viewed with the keyctl program or
  by cat'ing /proc/keys:
  
  	[root@andromeda ~]# keyctl show
  	Session Keyring
  	       -3 --alswrv      0     0  keyring: _ses.3268
  		2 --alswrv      0     0   \_ keyring: _uid.0
  	111416553 --als--v      0     0   \_ rxrpc: afs@CAMBRIDGE.REDHAT.COM
  
  Currently the username, realm, password and proposed ticket lifetime are
  compiled in to the program.
  
  It is not required to acquire a key before using AFS facilities, but if one is
  not acquired then all operations will be governed by the anonymous user parts
  of the ACLs.
  
  If a key is acquired, then all AFS operations, including mounts and automounts,
  made by a possessor of that key will be secured with that key.
  
  If a file is opened with a particular key and then the file descriptor is
  passed to a process that doesn't have that key (perhaps over an AF_UNIX
  socket), then the operations on the file will be made with key that was used to
  open the file.
  
  
  ========
  EXAMPLES
  ========
  
  Here's what I use to test this.  Some of the names and IP addresses are local
  to my internal DNS.  My "root.afs" partition has a mount point within it for
  some public volumes volumes.
  
  insmod /tmp/rxrpc.o
  insmod /tmp/rxkad.o
  insmod /tmp/kafs.o rootcell=cambridge.redhat.com:172.16.18.91
  
  mount -t afs \%root.afs. /afs
  mount -t afs \%cambridge.redhat.com:root.cell. /afs/cambridge.redhat.com/
  
  echo add grand.central.org 18.9.48.14:128.2.203.61:130.237.48.87 > /proc/fs/afs/cells
  mount -t afs "#grand.central.org:root.cell." /afs/grand.central.org/
  mount -t afs "#grand.central.org:root.archive." /afs/grand.central.org/archive
  mount -t afs "#grand.central.org:root.contrib." /afs/grand.central.org/contrib
  mount -t afs "#grand.central.org:root.doc." /afs/grand.central.org/doc
  mount -t afs "#grand.central.org:root.project." /afs/grand.central.org/project
  mount -t afs "#grand.central.org:root.service." /afs/grand.central.org/service
  mount -t afs "#grand.central.org:root.software." /afs/grand.central.org/software
  mount -t afs "#grand.central.org:root.user." /afs/grand.central.org/user
  
  umount /afs
  rmmod kafs
  rmmod rxkad
  rmmod rxrpc