252 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3====================4kAFS: AFS FILESYSTEM5====================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 19Overview20========21 22This filesystem provides a fairly simple secure AFS filesystem driver. It is23under development and does not yet provide the full feature set. The features24it 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 34It does not yet support the following AFS features:35 36 (*) pioctl() system call.37 38 39Compilation40===========41 42The filesystem should be enabled by turning on the kernel configuration43options::44 45 CONFIG_AF_RXRPC - The RxRPC protocol transport46 CONFIG_RXKAD - The RxRPC Kerberos security handler47 CONFIG_AFS_FS - The AFS filesystem48 49Additionally, the following can be turned on to aid debugging::50 51 CONFIG_AF_RXRPC_DEBUG - Permit AF_RXRPC debugging to be enabled52 CONFIG_AFS_DEBUG - Permit AFS debugging to be enabled53 54They permit the debugging messages to be turned on dynamically by manipulating55the masks in the following files::56 57 /sys/module/af_rxrpc/parameters/debug58 /sys/module/kafs/parameters/debug59 60 61Usage62=====63 64When inserting the driver modules the root cell must be specified along with a65list of volume location server IP addresses::66 67 modprobe rxrpc68 modprobe kafs rootcell=cambridge.redhat.com:172.16.18.73:172.16.18.9169 70The first module is the AF_RXRPC network protocol driver. This provides the71RxRPC remote operation protocol and may also be accessed from userspace. See:72 73 Documentation/networking/rxrpc.rst74 75The second module is the kerberos RxRPC security driver, and the third module76is the actual filesystem driver for the AFS filesystem.77 78Once the module has been loaded, more modules can be added by the following79procedure::80 81 echo add grand.central.org 18.9.48.14:128.2.203.61:130.237.48.87 >/proc/fs/afs/cells82 83Where the parameters to the "add" command are the name of a cell and a list of84volume location servers within that cell, with the latter separated by colons.85 86Filesystems can be mounted anywhere by commands similar to the following::87 88 mount -t afs "%cambridge.redhat.com:root.afs." /afs89 mount -t afs "#cambridge.redhat.com:root.cell." /afs/cambridge90 mount -t afs "#root.afs." /afs91 mount -t afs "#root.cell." /afs/cambridge92 93Where the initial character is either a hash or a percent symbol depending on94whether you definitely want a R/W volume (percent) or whether you'd prefer a95R/O volume, but are willing to use a R/W volume instead (hash).96 97The name of the volume can be suffixes with ".backup" or ".readonly" to98specify connection to only volumes of those types.99 100The name of the cell is optional, and if not given during a mount, then the101named volume will be looked up in the cell specified during modprobe.102 103Additional cells can be added through /proc (see later section).104 105 106Mountpoints107===========108 109AFS has a concept of mountpoints. In AFS terms, these are specially formatted110symbolic links (of the same form as the "device name" passed to mount). kAFS111presents these to the user as directories that have a follow-link capability112(i.e.: symbolic link semantics). If anyone attempts to access them, they will113automatically cause the target volume to be mounted (if possible) on that site.114 115Automatically mounted filesystems will be automatically unmounted approximately116twenty minutes after they were last used. Alternatively they can be unmounted117directly with the umount() system call.118 119Manually unmounting an AFS volume will cause any idle submounts upon it to be120culled first. If all are culled, then the requested volume will also be121unmounted, otherwise error EBUSY will be returned.122 123This can be used by the administrator to attempt to unmount the whole AFS tree124mounted on /afs in one go by doing::125 126 umount /afs127 128 129Dynamic Root130============131 132A mount option is available to create a serverless mount that is only usable133for dynamic lookup. Creating such a mount can be done by, for example::134 135 mount -t afs none /afs -o dyn136 137This creates a mount that just has an empty directory at the root. Attempting138to look up a name in this directory will cause a mountpoint to be created that139looks up a cell of the same name, for example::140 141 ls /afs/grand.central.org/142 143 144Proc Filesystem145===============146 147The 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 and150 their usage counts::151 152 [root@andromeda ~]# cat /proc/fs/afs/cells153 USE NAME154 3 cambridge.redhat.com155 156 (*) A directory per cell that contains files that list volume location157 servers, volumes, and active servers known within that cell::158 159 [root@andromeda ~]# cat /proc/fs/afs/cambridge.redhat.com/servers160 USE ADDR STATE161 4 172.16.18.91 0162 [root@andromeda ~]# cat /proc/fs/afs/cambridge.redhat.com/vlservers163 ADDRESS164 172.16.18.91165 [root@andromeda ~]# cat /proc/fs/afs/cambridge.redhat.com/volumes166 USE STT VLID[0] VLID[1] VLID[2] NAME167 1 Val 20000000 20000001 20000002 root.afs168 169 170The Cell Database171=================172 173The filesystem maintains an internal database of all the cells it knows and the174IP addresses of the volume location servers for those cells. The cell to which175the system belongs is added to the database when modprobe is performed by the176"rootcell=" argument or, if compiled in, using a "kafs.rootcell=" argument on177the kernel command line.178 179Further cells can be added by commands similar to the following::180 181 echo add CELLNAME VLADDR[:VLADDR][:VLADDR]... >/proc/fs/afs/cells182 echo add grand.central.org 18.9.48.14:128.2.203.61:130.237.48.87 >/proc/fs/afs/cells183 184No other cell database operations are available at this time.185 186 187Security188========189 190Secure operations are initiated by acquiring a key using the klog program. A191very primitive klog program is available at:192 193 https://people.redhat.com/~dhowells/rxrpc/klog.c194 195This should be compiled by::196 197 make klog LDLIBS="-lcrypto -lcrypt -lkrb4 -lkeyutils"198 199And then run as::200 201 ./klog202 203Assuming it's successful, this adds a key of type RxRPC, named for the service204and cell, e.g.: "afs@<cellname>". This can be viewed with the keyctl program or205by cat'ing /proc/keys::206 207 [root@andromeda ~]# keyctl show208 Session Keyring209 -3 --alswrv 0 0 keyring: _ses.3268210 2 --alswrv 0 0 \_ keyring: _uid.0211 111416553 --als--v 0 0 \_ rxrpc: afs@CAMBRIDGE.REDHAT.COM212 213Currently the username, realm, password and proposed ticket lifetime are214compiled into the program.215 216It is not required to acquire a key before using AFS facilities, but if one is217not acquired then all operations will be governed by the anonymous user parts218of the ACLs.219 220If a key is acquired, then all AFS operations, including mounts and automounts,221made by a possessor of that key will be secured with that key.222 223If a file is opened with a particular key and then the file descriptor is224passed to a process that doesn't have that key (perhaps over an AF_UNIX225socket), then the operations on the file will be made with key that was used to226open the file.227 228 229The @sys Substitution230=====================231 232The list of up to 16 @sys substitutions for the current network namespace can233be configured by writing a list to /proc/fs/afs/sysname::234 235 [root@andromeda ~]# echo foo amd64_linux_26 >/proc/fs/afs/sysname236 237or cleared entirely by writing an empty list::238 239 [root@andromeda ~]# echo >/proc/fs/afs/sysname240 241The current list for current network namespace can be retrieved by::242 243 [root@andromeda ~]# cat /proc/fs/afs/sysname244 foo245 amd64_linux_26246 247When @sys is being substituted for, each element of the list is tried in the248order given.249 250By default, the list will contain one item that conforms to the pattern251"<arch>_linux_26", amd64 being the name for x86_64.252