Based on kernel version 2.6.26. Page generated on 2008-07-16 21:12 EST.
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[AT]andromeda ~]# cat /proc/fs/afs/cambridge.redhat[DOT]com/servers 150 USE ADDR STATE 151 4 172.16.18.91 0 152 [root[AT]andromeda ~]# cat /proc/fs/afs/cambridge.redhat[DOT]com/vlservers 153 ADDRESS 154 172.16.18.91 155 [root[AT]andromeda ~]# cat /proc/fs/afs/cambridge.redhat[DOT]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[AT]<cellname>"[DOT] 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[AT]CAMBRIDGE.REDHAT[DOT]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