Documentation/filesystems/afs.txt

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