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