linux/Documentation/filesystems/afs.txt
<<
>>
Prefs
   1                             ====================
   2                             kAFS: AFS FILESYSTEM
   3                             ====================
   4
   5Contents:
   6
   7 - Overview.
   8 - Usage.
   9 - Mountpoints.
  10 - Proc filesystem.
  11 - The cell database.
  12 - Security.
  13 - Examples.
  14
  15
  16========
  17OVERVIEW
  18========
  19
  20This filesystem provides a fairly simple secure AFS filesystem driver. It is
  21under development and does not yet provide the full feature set.  The features
  22it does support include:
  23
  24 (*) Security (currently only AFS kaserver and KerberosIV tickets).
  25
  26 (*) File reading and writing.
  27
  28 (*) Automounting.
  29
  30 (*) Local caching (via fscache).
  31
  32It does not yet support the following AFS features:
  33
  34 (*) pioctl() system call.
  35
  36
  37===========
  38COMPILATION
  39===========
  40
  41The filesystem should be enabled by turning on the kernel configuration
  42options:
  43
  44        CONFIG_AF_RXRPC         - The RxRPC protocol transport
  45        CONFIG_RXKAD            - The RxRPC Kerberos security handler
  46        CONFIG_AFS              - The AFS filesystem
  47
  48Additionally, the following can be turned on to aid debugging:
  49
  50        CONFIG_AF_RXRPC_DEBUG   - Permit AF_RXRPC debugging to be enabled
  51        CONFIG_AFS_DEBUG        - Permit AFS debugging to be enabled
  52
  53They permit the debugging messages to be turned on dynamically by manipulating
  54the masks in the following files:
  55
  56        /sys/module/af_rxrpc/parameters/debug
  57        /sys/module/kafs/parameters/debug
  58
  59
  60=====
  61USAGE
  62=====
  63
  64When inserting the driver modules the root cell must be specified along with a
  65list of volume location server IP addresses:
  66
  67        modprobe af_rxrpc
  68        modprobe rxkad
  69        modprobe kafs rootcell=cambridge.redhat.com:172.16.18.73:172.16.18.91
  70
  71The first module is the AF_RXRPC network protocol driver.  This provides the
  72RxRPC remote operation protocol and may also be accessed from userspace.  See:
  73
  74        Documentation/networking/rxrpc.txt
  75
  76The second module is the kerberos RxRPC security driver, and the third module
  77is the actual filesystem driver for the AFS filesystem.
  78
  79Once the module has been loaded, more modules can be added by the following
  80procedure:
  81
  82        echo add grand.central.org 18.9.48.14:128.2.203.61:130.237.48.87 >/proc/fs/afs/cells
  83
  84Where the parameters to the "add" command are the name of a cell and a list of
  85volume location servers within that cell, with the latter separated by colons.
  86
  87Filesystems can be mounted anywhere by commands similar to the following:
  88
  89        mount -t afs "%cambridge.redhat.com:root.afs." /afs
  90        mount -t afs "#cambridge.redhat.com:root.cell." /afs/cambridge
  91        mount -t afs "#root.afs." /afs
  92        mount -t afs "#root.cell." /afs/cambridge
  93
  94Where the initial character is either a hash or a percent symbol depending on
  95whether you definitely want a R/W volume (hash) or whether you'd prefer a R/O
  96volume, but are willing to use a R/W volume instead (percent).
  97
  98The name of the volume can be suffixes with ".backup" or ".readonly" to
  99specify connection to only volumes of those types.
 100
 101The name of the cell is optional, and if not given during a mount, then the
 102named volume will be looked up in the cell specified during modprobe.
 103
 104Additional cells can be added through /proc (see later section).
 105
 106
 107===========
 108MOUNTPOINTS
 109===========
 110
 111AFS has a concept of mountpoints. In AFS terms, these are specially formatted
 112symbolic links (of the same form as the "device name" passed to mount).  kAFS
 113presents these to the user as directories that have a follow-link capability
 114(ie: symbolic link semantics).  If anyone attempts to access them, they will
 115automatically cause the target volume to be mounted (if possible) on that site.
 116
 117Automatically mounted filesystems will be automatically unmounted approximately
 118twenty minutes after they were last used.  Alternatively they can be unmounted
 119directly with the umount() system call.
 120
 121Manually unmounting an AFS volume will cause any idle submounts upon it to be
 122culled first.  If all are culled, then the requested volume will also be
 123unmounted, otherwise error EBUSY will be returned.
 124
 125This can be used by the administrator to attempt to unmount the whole AFS tree
 126mounted on /afs in one go by doing:
 127
 128        umount /afs
 129
 130
 131===============
 132PROC FILESYSTEM
 133===============
 134
 135The AFS modules creates a "/proc/fs/afs/" directory and populates it:
 136
 137  (*) A "cells" file that lists cells currently known to the afs module and
 138      their usage counts:
 139
 140        [root@andromeda ~]# cat /proc/fs/afs/cells
 141        USE NAME
 142          3 cambridge.redhat.com
 143
 144  (*) A directory per cell that contains files that list volume location
 145      servers, volumes, and active servers known within that cell.
 146
 147        [root@andromeda ~]# cat /proc/fs/afs/cambridge.redhat.com/servers
 148        USE ADDR            STATE
 149          4 172.16.18.91        0
 150        [root@andromeda ~]# cat /proc/fs/afs/cambridge.redhat.com/vlservers
 151        ADDRESS
 152        172.16.18.91
 153        [root@andromeda ~]# cat /proc/fs/afs/cambridge.redhat.com/volumes
 154        USE STT VLID[0]  VLID[1]  VLID[2]  NAME
 155          1 Val 20000000 20000001 20000002 root.afs
 156
 157
 158=================
 159THE CELL DATABASE
 160=================
 161
 162The filesystem maintains an internal database of all the cells it knows and the
 163IP addresses of the volume location servers for those cells.  The cell to which
 164the system belongs is added to the database when modprobe is performed by the
 165"rootcell=" argument or, if compiled in, using a "kafs.rootcell=" argument on
 166the kernel command line.
 167
 168Further cells can be added by commands similar to the following:
 169
 170        echo add CELLNAME VLADDR[:VLADDR][:VLADDR]... >/proc/fs/afs/cells
 171        echo add grand.central.org 18.9.48.14:128.2.203.61:130.237.48.87 >/proc/fs/afs/cells
 172
 173No other cell database operations are available at this time.
 174
 175
 176========
 177SECURITY
 178========
 179
 180Secure operations are initiated by acquiring a key using the klog program.  A
 181very primitive klog program is available at:
 182
 183        http://people.redhat.com/~dhowells/rxrpc/klog.c
 184
 185This should be compiled by:
 186
 187        make klog LDLIBS="-lcrypto -lcrypt -lkrb4 -lkeyutils"
 188
 189And then run as:
 190
 191        ./klog
 192
 193Assuming it's successful, this adds a key of type RxRPC, named for the service
 194and cell, eg: "afs@<cellname>".  This can be viewed with the keyctl program or
 195by cat'ing /proc/keys:
 196
 197        [root@andromeda ~]# keyctl show
 198        Session Keyring
 199               -3 --alswrv      0     0  keyring: _ses.3268
 200                2 --alswrv      0     0   \_ keyring: _uid.0
 201        111416553 --als--v      0     0   \_ rxrpc: afs@CAMBRIDGE.REDHAT.COM
 202
 203Currently the username, realm, password and proposed ticket lifetime are
 204compiled in to the program.
 205
 206It is not required to acquire a key before using AFS facilities, but if one is
 207not acquired then all operations will be governed by the anonymous user parts
 208of the ACLs.
 209
 210If a key is acquired, then all AFS operations, including mounts and automounts,
 211made by a possessor of that key will be secured with that key.
 212
 213If a file is opened with a particular key and then the file descriptor is
 214passed to a process that doesn't have that key (perhaps over an AF_UNIX
 215socket), then the operations on the file will be made with key that was used to
 216open the file.
 217
 218
 219========
 220EXAMPLES
 221========
 222
 223Here's what I use to test this.  Some of the names and IP addresses are local
 224to my internal DNS.  My "root.afs" partition has a mount point within it for
 225some public volumes volumes.
 226
 227insmod /tmp/rxrpc.o
 228insmod /tmp/rxkad.o
 229insmod /tmp/kafs.o rootcell=cambridge.redhat.com:172.16.18.91
 230
 231mount -t afs \%root.afs. /afs
 232mount -t afs \%cambridge.redhat.com:root.cell. /afs/cambridge.redhat.com/
 233
 234echo add grand.central.org 18.9.48.14:128.2.203.61:130.237.48.87 > /proc/fs/afs/cells
 235mount -t afs "#grand.central.org:root.cell." /afs/grand.central.org/
 236mount -t afs "#grand.central.org:root.archive." /afs/grand.central.org/archive
 237mount -t afs "#grand.central.org:root.contrib." /afs/grand.central.org/contrib
 238mount -t afs "#grand.central.org:root.doc." /afs/grand.central.org/doc
 239mount -t afs "#grand.central.org:root.project." /afs/grand.central.org/project
 240mount -t afs "#grand.central.org:root.service." /afs/grand.central.org/service
 241mount -t afs "#grand.central.org:root.software." /afs/grand.central.org/software
 242mount -t afs "#grand.central.org:root.user." /afs/grand.central.org/user
 243
 244umount /afs
 245rmmod kafs
 246rmmod rxkad
 247rmmod rxrpc
 248
lxr.linux.no kindly hosted by Redpill Linpro AS, provider of Linux consulting and operations services since 1995.