1 .. SPDX-License-Identifier: GPL-2.0 2 3 ==================== 4 kAFS: AFS FILESYSTEM 5 ==================== 6 7 .. Contents: 8 9 - Overview. 10 - Usage. 11 - Mountpoints. 12 - Dynamic root. 13 - Proc filesystem. 14 - The cell database. 15 - Security. 16 - The @sys substitution. 17 18 19 Overview 20 ======== 21 22 This filesystem provides a fairly simple secure AFS filesystem driver. It is 23 under development and does not yet provide the full feature set. The features 24 it does support include: 25 26 (*) Security (currently only AFS kaserver and KerberosIV tickets). 27 28 (*) File reading and writing. 29 30 (*) Automounting. 31 32 (*) Local caching (via fscache). 33 34 It does not yet support the following AFS features: 35 36 (*) pioctl() system call. 37 38 39 Compilation 40 =========== 41 42 The filesystem should be enabled by turning on the kernel configuration 43 options:: 44 45 CONFIG_AF_RXRPC - The RxRPC protocol transport 46 CONFIG_RXKAD - The RxRPC Kerberos security handler 47 CONFIG_AFS_FS - The AFS filesystem 48 49 Additionally, 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 54 They permit the debugging messages to be turned on dynamically by manipulating 55 the masks in the following files:: 56 57 /sys/module/af_rxrpc/parameters/debug 58 /sys/module/kafs/parameters/debug 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.rst 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 (percent) or whether you'd prefer a 95 R/O volume, but are willing to use a R/W volume instead (hash). 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 Mountpoints 107 =========== 108 109 AFS has a concept of mountpoints. In AFS terms, these are specially formatted 110 symbolic links (of the same form as the "device name" passed to mount). kAFS 111 presents these to the user as directories that have a follow-link capability 112 (i.e.: symbolic link semantics). If anyone attempts to access them, they will 113 automatically cause the target volume to be mounted (if possible) on that site. 114 115 Automatically mounted filesystems will be automatically unmounted approximately 116 twenty minutes after they were last used. Alternatively they can be unmounted 117 directly with the umount() system call. 118 119 Manually unmounting an AFS volume will cause any idle submounts upon it to be 120 culled first. If all are culled, then the requested volume will also be 121 unmounted, otherwise error EBUSY will be returned. 122 123 This can be used by the administrator to attempt to unmount the whole AFS tree 124 mounted on /afs in one go by doing:: 125 126 umount /afs 127 128 129 Dynamic Root 130 ============ 131 132 A mount option is available to create a serverless mount that is only usable 133 for dynamic lookup. Creating such a mount can be done by, for example:: 134 135 mount -t afs none /afs -o dyn 136 137 This creates a mount that just has an empty directory at the root. Attempting 138 to look up a name in this directory will cause a mountpoint to be created that 139 looks up a cell of the same name, for example:: 140 141 ls /afs/grand.central.org/ 142 143 144 Proc Filesystem 145 =============== 146 147 The AFS module creates a "/proc/fs/afs/" directory and populates it: 148 149 (*) A "cells" file that lists cells currently known to the afs module and 150 their usage counts:: 151 152 [root@andromeda ~]# cat /proc/fs/afs/cells 153 USE NAME 154 3 cambridge.redhat.com 155 156 (*) A directory per cell that contains files that list volume location 157 servers, volumes, and active servers known within that cell:: 158 159 [root@andromeda ~]# cat /proc/fs/afs/cambridge.redhat.com/servers 160 USE ADDR STATE 161 4 172.16.18.91 0 162 [root@andromeda ~]# cat /proc/fs/afs/cambridge.redhat.com/vlservers 163 ADDRESS 164 172.16.18.91 165 [root@andromeda ~]# cat /proc/fs/afs/cambridge.redhat.com/volumes 166 USE STT VLID[0] VLID[1] VLID[2] NAME 167 1 Val 20000000 20000001 20000002 root.afs 168 169 170 The Cell Database 171 ================= 172 173 The filesystem maintains an internal database of all the cells it knows and the 174 IP addresses of the volume location servers for those cells. The cell to which 175 the system belongs is added to the database when modprobe is performed by the 176 "rootcell=" argument or, if compiled in, using a "kafs.rootcell=" argument on 177 the kernel command line. 178 179 Further cells can be added by commands similar to the following:: 180 181 echo add CELLNAME VLADDR[:VLADDR][:VLADDR]... >/proc/fs/afs/cells 182 echo add grand.central.org 18.9.48.14:128.2.203.61:130.237.48.87 >/proc/fs/afs/cells 183 184 No other cell database operations are available at this time. 185 186 187 Security 188 ======== 189 190 Secure operations are initiated by acquiring a key using the klog program. A 191 very primitive klog program is available at: 192 193 https://people.redhat.com/~dhowells/rxrpc/klog.c 194 195 This should be compiled by:: 196 197 make klog LDLIBS="-lcrypto -lcrypt -lkrb4 -lkeyutils" 198 199 And then run as:: 200 201 ./klog 202 203 Assuming it's successful, this adds a key of type RxRPC, named for the service 204 and cell, e.g.: "afs@<cellname>". This can be viewed with the keyctl program or 205 by cat'ing /proc/keys:: 206 207 [root@andromeda ~]# keyctl show 208 Session Keyring 209 -3 --alswrv 0 0 keyring: _ses.3268 210 2 --alswrv 0 0 \_ keyring: _uid.0 211 111416553 --als--v 0 0 \_ rxrpc: afs@CAMBRIDGE.REDHAT.COM 212 213 Currently the username, realm, password and proposed ticket lifetime are 214 compiled into the program. 215 216 It is not required to acquire a key before using AFS facilities, but if one is 217 not acquired then all operations will be governed by the anonymous user parts 218 of the ACLs. 219 220 If a key is acquired, then all AFS operations, including mounts and automounts, 221 made by a possessor of that key will be secured with that key. 222 223 If a file is opened with a particular key and then the file descriptor is 224 passed to a process that doesn't have that key (perhaps over an AF_UNIX 225 socket), then the operations on the file will be made with key that was used to 226 open the file. 227 228 229 The @sys Substitution 230 ===================== 231 232 The list of up to 16 @sys substitutions for the current network namespace can 233 be configured by writing a list to /proc/fs/afs/sysname:: 234 235 [root@andromeda ~]# echo foo amd64_linux_26 >/proc/fs/afs/sysname 236 237 or cleared entirely by writing an empty list:: 238 239 [root@andromeda ~]# echo >/proc/fs/afs/sysname 240 241 The current list for current network namespace can be retrieved by:: 242 243 [root@andromeda ~]# cat /proc/fs/afs/sysname 244 foo 245 amd64_linux_26 246 247 When @sys is being substituted for, each element of the list is tried in the 248 order given. 249 250 By default, the list will contain one item that conforms to the pattern 251 "<arch>_linux_26", amd64 being the name for x86_64.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.