Documentation/filesystems/afs.txt

   1                              ====================
   2                              kAFS: AFS FILESYSTEM
   3                              ====================
   4
   5 Contents:
   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 ========
  18 OVERVIEW
  19 ========
  20
  21 This filesystem provides a fairly simple secure AFS filesystem driver. It is
  22 under development and does not yet provide the full feature set.  The features
  23 it 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
  33 It does not yet support the following AFS features:
  34
  35  (*) pioctl() system call.
  36
  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              - 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 =====
  62 USAGE
  63 =====
  64
  65 When inserting the driver modules the root cell must be specified along with a
  66 list 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
  71 The first module is the AF_RXRPC network protocol driver.  This provides the
  72 RxRPC remote operation protocol and may also be accessed from userspace.  See:
  73
  74         Documentation/networking/rxrpc.txt
  75
  76 The second module is the kerberos RxRPC security driver, and the third module
  77 is the actual filesystem driver for the AFS filesystem.
  78
  79 Once the module has been loaded, more modules can be added by the following
  80 procedure:
  81
  82         echo add grand.central.org 18.9.48.14:128.2.203.61:130.237.48.87 >/proc/fs/afs/cells
  83
  84 Where the parameters to the "add" command are the name of a cell and a list of
  85 volume location servers within that cell, with the latter separated by colons.
  86
  87 Filesystems 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
  94 Where the initial character is either a hash or a percent symbol depending on
  95 whether you definitely want a R/W volume (percent) or whether you'd prefer a
  96 R/O volume, but are willing to use a R/W volume instead (hash).
  97
  98 The name of the volume can be suffixes with ".backup" or ".readonly" to
  99 specify connection to only volumes of those types.
 100
 101 The name of the cell is optional, and if not given during a mount, then the
 102 named volume will be looked up in the cell specified during modprobe.
 103
 104 Additional cells can be added through /proc (see later section).
 105
 106
 107 ===========
 108 MOUNTPOINTS
 109 ===========
 110
 111 AFS has a concept of mountpoints. In AFS terms, these are specially formatted
 112 symbolic links (of the same form as the "device name" passed to mount).  kAFS
 113 presents 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
 115 automatically cause the target volume to be mounted (if possible) on that site.
 116
 117 Automatically mounted filesystems will be automatically unmounted approximately
 118 twenty minutes after they were last used.  Alternatively they can be unmounted
 119 directly with the umount() system call.
 120
 121 Manually unmounting an AFS volume will cause any idle submounts upon it to be
 122 culled first.  If all are culled, then the requested volume will also be
 123 unmounted, otherwise error EBUSY will be returned.
 124
 125 This can be used by the administrator to attempt to unmount the whole AFS tree
 126 mounted on /afs in one go by doing:
 127
 128         umount /afs
 129
 130
 131 ============
 132 DYNAMIC ROOT
 133 ============
 134
 135 A mount option is available to create a serverless mount that is only usable
 136 for dynamic lookup.  Creating such a mount can be done by, for example:
 137
 138         mount -t afs none /afs -o dyn
 139
 140 This creates a mount that just has an empty directory at the root.  Attempting
 141 to look up a name in this directory will cause a mountpoint to be created that
 142 looks up a cell of the same name, for example:
 143
 144         ls /afs/grand.central.org/
 145
 146
 147 ===============
 148 PROC FILESYSTEM
 149 ===============
 150
 151 The 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 =================
 175 THE CELL DATABASE
 176 =================
 177
 178 The filesystem maintains an internal database of all the cells it knows and the
 179 IP addresses of the volume location servers for those cells.  The cell to which
 180 the 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
 182 the kernel command line.
 183
 184 Further 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
 189 No other cell database operations are available at this time.
 190
 191
 192 ========
 193 SECURITY
 194 ========
 195
 196 Secure operations are initiated by acquiring a key using the klog program.  A
 197 very primitive klog program is available at:
 198
 199         http://people.redhat.com/~dhowells/rxrpc/klog.c
 200
 201 This should be compiled by:
 202
 203         make klog LDLIBS="-lcrypto -lcrypt -lkrb4 -lkeyutils"
 204
 205 And then run as:
 206
 207         ./klog
 208
 209 Assuming it's successful, this adds a key of type RxRPC, named for the service
 210 and cell, eg: "afs@<cellname>".  This can be viewed with the keyctl program or
 211 by 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
 219 Currently the username, realm, password and proposed ticket lifetime are
 220 compiled in to the program.
 221
 222 It is not required to acquire a key before using AFS facilities, but if one is
 223 not acquired then all operations will be governed by the anonymous user parts
 224 of the ACLs.
 225
 226 If a key is acquired, then all AFS operations, including mounts and automounts,
 227 made by a possessor of that key will be secured with that key.
 228
 229 If a file is opened with a particular key and then the file descriptor is
 230 passed to a process that doesn't have that key (perhaps over an AF_UNIX
 231 socket), then the operations on the file will be made with key that was used to
 232 open the file.
 233
 234
 235 =====================
 236 THE @SYS SUBSTITUTION
 237 =====================
 238
 239 The list of up to 16 @sys substitutions for the current network namespace can
 240 be configured by writing a list to /proc/fs/afs/sysname:
 241
 242         [root@andromeda ~]# echo foo amd64_linux_26 >/proc/fs/afs/sysname
 243
 244 or cleared entirely by writing an empty list:
 245
 246         [root@andromeda ~]# echo >/proc/fs/afs/sysname
 247
 248 The 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
 254 When @sys is being substituted for, each element of the list is tried in the
 255 order given.
 256
 257 By default, the list will contain one item that conforms to the pattern
 258 "<arch>_linux_26", amd64 being the name for x86_64.