1 ==================== 2 kAFS: AFS FILESYSTEM 3 ==================== 4 5Contents: 6 7 - Overview. 8 - Usage. 9 - Mountpoints. 10 - Dynamic root. 11 - Proc filesystem. 12 - The cell database. 13 - Security. 14 - The @sys substitution. 15 16 17======== 18OVERVIEW 19======== 20 21This filesystem provides a fairly simple secure AFS filesystem driver. It is 22under development and does not yet provide the full feature set. The features 23it does support include: 24 25 (*) Security (currently only AFS kaserver and KerberosIV tickets). 26 27 (*) File reading and writing. 28 29 (*) Automounting. 30 31 (*) Local caching (via fscache). 32 33It does not yet support the following AFS features: 34 35 (*) pioctl() system call. 36 37 38=========== 39COMPILATION 40=========== 41 42The filesystem should be enabled by turning on the kernel configuration 43options: 44 45 CONFIG_AF_RXRPC - The RxRPC protocol transport 46 CONFIG_RXKAD - The RxRPC Kerberos security handler 47 CONFIG_AFS - The AFS filesystem 48 49Additionally, the following can be turned on to aid debugging: 50 51 CONFIG_AF_RXRPC_DEBUG - Permit AF_RXRPC debugging to be enabled 52 CONFIG_AFS_DEBUG - Permit AFS debugging to be enabled 53 54They permit the debugging messages to be turned on dynamically by manipulating 55the masks in the following files: 56 57 /sys/module/af_rxrpc/parameters/debug 58 /sys/module/kafs/parameters/debug 59 60 61===== 62USAGE 63===== 64 65When inserting the driver modules the root cell must be specified along with a 66list of volume location server IP addresses: 67 68 modprobe rxrpc 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 (percent) or whether you'd prefer a 96R/O volume, but are willing to use a R/W volume instead (hash). 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============ 132DYNAMIC ROOT 133============ 134 135A mount option is available to create a serverless mount that is only usable 136for dynamic lookup. Creating such a mount can be done by, for example: 137 138 mount -t afs none /afs -o dyn 139 140This creates a mount that just has an empty directory at the root. Attempting 141to look up a name in this directory will cause a mountpoint to be created that 142looks up a cell of the same name, for example: 143 144 ls /afs/grand.central.org/ 145 146 147=============== 148PROC FILESYSTEM 149=============== 150 151The AFS modules creates a "/proc/fs/afs/" directory and populates it: 152 153 (*) A "cells" file that lists cells currently known to the afs module and 154 their usage counts: 155 156 [root@andromeda ~]# cat /proc/fs/afs/cells 157 USE NAME 158 3 cambridge.redhat.com 159 160 (*) A directory per cell that contains files that list volume location 161 servers, volumes, and active servers known within that cell. 162 163 [root@andromeda ~]# cat /proc/fs/afs/cambridge.redhat.com/servers 164 USE ADDR STATE 165 4 172.16.18.91 0 166 [root@andromeda ~]# cat /proc/fs/afs/cambridge.redhat.com/vlservers 167 ADDRESS 168 172.16.18.91 169 [root@andromeda ~]# cat /proc/fs/afs/cambridge.redhat.com/volumes 170 USE STT VLID[0] VLID[1] VLID[2] NAME 171 1 Val 20000000 20000001 20000002 root.afs 172 173 174================= 175THE CELL DATABASE 176================= 177 178The filesystem maintains an internal database of all the cells it knows and the 179IP addresses of the volume location servers for those cells. The cell to which 180the system belongs is added to the database when modprobe is performed by the 181"rootcell=" argument or, if compiled in, using a "kafs.rootcell=" argument on 182the kernel command line. 183 184Further cells can be added by commands similar to the following: 185 186 echo add CELLNAME VLADDR[:VLADDR][:VLADDR]... >/proc/fs/afs/cells 187 echo add grand.central.org 18.9.48.14:128.2.203.61:130.237.48.87 >/proc/fs/afs/cells 188 189No other cell database operations are available at this time. 190 191 192======== 193SECURITY 194======== 195 196Secure operations are initiated by acquiring a key using the klog program. A 197very primitive klog program is available at: 198 199 http://people.redhat.com/~dhowells/rxrpc/klog.c 200 201This should be compiled by: 202 203 make klog LDLIBS="-lcrypto -lcrypt -lkrb4 -lkeyutils" 204 205And then run as: 206 207 ./klog 208 209Assuming it's successful, this adds a key of type RxRPC, named for the service 210and cell, eg: "afs@<cellname>". This can be viewed with the keyctl program or 211by cat'ing /proc/keys: 212 213 [root@andromeda ~]# keyctl show 214 Session Keyring 215 -3 --alswrv 0 0 keyring: _ses.3268 216 2 --alswrv 0 0 \_ keyring: _uid.0 217 111416553 --als--v 0 0 \_ rxrpc: afs@CAMBRIDGE.REDHAT.COM 218 219Currently the username, realm, password and proposed ticket lifetime are 220compiled in to the program. 221 222It is not required to acquire a key before using AFS facilities, but if one is 223not acquired then all operations will be governed by the anonymous user parts 224of the ACLs. 225 226If a key is acquired, then all AFS operations, including mounts and automounts, 227made by a possessor of that key will be secured with that key. 228 229If a file is opened with a particular key and then the file descriptor is 230passed to a process that doesn't have that key (perhaps over an AF_UNIX 231socket), then the operations on the file will be made with key that was used to 232open the file. 233 234 235===================== 236THE @SYS SUBSTITUTION 237===================== 238 239The list of up to 16 @sys substitutions for the current network namespace can 240be configured by writing a list to /proc/fs/afs/sysname: 241 242 [root@andromeda ~]# echo foo amd64_linux_26 >/proc/fs/afs/sysname 243 244or cleared entirely by writing an empty list: 245 246 [root@andromeda ~]# echo >/proc/fs/afs/sysname 247 248The current list for current network namespace can be retrieved by: 249 250 [root@andromeda ~]# cat /proc/fs/afs/sysname 251 foo 252 amd64_linux_26 253 254When @sys is being substituted for, each element of the list is tried in the 255order given. 256 257By default, the list will contain one item that conforms to the pattern 258"<arch>_linux_26", amd64 being the name for x86_64. 259
