0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ====================
0004 kAFS: AFS FILESYSTEM
0005 ====================
0006
0007 .. Contents:
0008
0009 - Overview.
0010 - Usage.
0011 - Mountpoints.
0012 - Dynamic root.
0013 - Proc filesystem.
0014 - The cell database.
0015 - Security.
0016 - The @sys substitution.
0017
0018
0019 Overview
0020 ========
0021
0022 This filesystem provides a fairly simple secure AFS filesystem driver. It is
0023 under development and does not yet provide the full feature set. The features
0024 it does support include:
0025
0026 (*) Security (currently only AFS kaserver and KerberosIV tickets).
0027
0028 (*) File reading and writing.
0029
0030 (*) Automounting.
0031
0032 (*) Local caching (via fscache).
0033
0034 It does not yet support the following AFS features:
0035
0036 (*) pioctl() system call.
0037
0038
0039 Compilation
0040 ===========
0041
0042 The filesystem should be enabled by turning on the kernel configuration
0043 options::
0044
0045 CONFIG_AF_RXRPC - The RxRPC protocol transport
0046 CONFIG_RXKAD - The RxRPC Kerberos security handler
0047 CONFIG_AFS - The AFS filesystem
0048
0049 Additionally, the following can be turned on to aid debugging::
0050
0051 CONFIG_AF_RXRPC_DEBUG - Permit AF_RXRPC debugging to be enabled
0052 CONFIG_AFS_DEBUG - Permit AFS debugging to be enabled
0053
0054 They permit the debugging messages to be turned on dynamically by manipulating
0055 the masks in the following files::
0056
0057 /sys/module/af_rxrpc/parameters/debug
0058 /sys/module/kafs/parameters/debug
0059
0060
0061 Usage
0062 =====
0063
0064 When inserting the driver modules the root cell must be specified along with a
0065 list of volume location server IP addresses::
0066
0067 modprobe rxrpc
0068 modprobe kafs rootcell=cambridge.redhat.com:172.16.18.73:172.16.18.91
0069
0070 The first module is the AF_RXRPC network protocol driver. This provides the
0071 RxRPC remote operation protocol and may also be accessed from userspace. See:
0072
0073 Documentation/networking/rxrpc.rst
0074
0075 The second module is the kerberos RxRPC security driver, and the third module
0076 is the actual filesystem driver for the AFS filesystem.
0077
0078 Once the module has been loaded, more modules can be added by the following
0079 procedure::
0080
0081 echo add grand.central.org 18.9.48.14:128.2.203.61:130.237.48.87 >/proc/fs/afs/cells
0082
0083 Where the parameters to the "add" command are the name of a cell and a list of
0084 volume location servers within that cell, with the latter separated by colons.
0085
0086 Filesystems can be mounted anywhere by commands similar to the following::
0087
0088 mount -t afs "%cambridge.redhat.com:root.afs." /afs
0089 mount -t afs "#cambridge.redhat.com:root.cell." /afs/cambridge
0090 mount -t afs "#root.afs." /afs
0091 mount -t afs "#root.cell." /afs/cambridge
0092
0093 Where the initial character is either a hash or a percent symbol depending on
0094 whether you definitely want a R/W volume (percent) or whether you'd prefer a
0095 R/O volume, but are willing to use a R/W volume instead (hash).
0096
0097 The name of the volume can be suffixes with ".backup" or ".readonly" to
0098 specify connection to only volumes of those types.
0099
0100 The name of the cell is optional, and if not given during a mount, then the
0101 named volume will be looked up in the cell specified during modprobe.
0102
0103 Additional cells can be added through /proc (see later section).
0104
0105
0106 Mountpoints
0107 ===========
0108
0109 AFS has a concept of mountpoints. In AFS terms, these are specially formatted
0110 symbolic links (of the same form as the "device name" passed to mount). kAFS
0111 presents these to the user as directories that have a follow-link capability
0112 (i.e.: symbolic link semantics). If anyone attempts to access them, they will
0113 automatically cause the target volume to be mounted (if possible) on that site.
0114
0115 Automatically mounted filesystems will be automatically unmounted approximately
0116 twenty minutes after they were last used. Alternatively they can be unmounted
0117 directly with the umount() system call.
0118
0119 Manually unmounting an AFS volume will cause any idle submounts upon it to be
0120 culled first. If all are culled, then the requested volume will also be
0121 unmounted, otherwise error EBUSY will be returned.
0122
0123 This can be used by the administrator to attempt to unmount the whole AFS tree
0124 mounted on /afs in one go by doing::
0125
0126 umount /afs
0127
0128
0129 Dynamic Root
0130 ============
0131
0132 A mount option is available to create a serverless mount that is only usable
0133 for dynamic lookup. Creating such a mount can be done by, for example::
0134
0135 mount -t afs none /afs -o dyn
0136
0137 This creates a mount that just has an empty directory at the root. Attempting
0138 to look up a name in this directory will cause a mountpoint to be created that
0139 looks up a cell of the same name, for example::
0140
0141 ls /afs/grand.central.org/
0142
0143
0144 Proc Filesystem
0145 ===============
0146
0147 The AFS module creates a "/proc/fs/afs/" directory and populates it:
0148
0149 (*) A "cells" file that lists cells currently known to the afs module and
0150 their usage counts::
0151
0152 [root@andromeda ~]# cat /proc/fs/afs/cells
0153 USE NAME
0154 3 cambridge.redhat.com
0155
0156 (*) A directory per cell that contains files that list volume location
0157 servers, volumes, and active servers known within that cell::
0158
0159 [root@andromeda ~]# cat /proc/fs/afs/cambridge.redhat.com/servers
0160 USE ADDR STATE
0161 4 172.16.18.91 0
0162 [root@andromeda ~]# cat /proc/fs/afs/cambridge.redhat.com/vlservers
0163 ADDRESS
0164 172.16.18.91
0165 [root@andromeda ~]# cat /proc/fs/afs/cambridge.redhat.com/volumes
0166 USE STT VLID[0] VLID[1] VLID[2] NAME
0167 1 Val 20000000 20000001 20000002 root.afs
0168
0169
0170 The Cell Database
0171 =================
0172
0173 The filesystem maintains an internal database of all the cells it knows and the
0174 IP addresses of the volume location servers for those cells. The cell to which
0175 the system belongs is added to the database when modprobe is performed by the
0176 "rootcell=" argument or, if compiled in, using a "kafs.rootcell=" argument on
0177 the kernel command line.
0178
0179 Further cells can be added by commands similar to the following::
0180
0181 echo add CELLNAME VLADDR[:VLADDR][:VLADDR]... >/proc/fs/afs/cells
0182 echo add grand.central.org 18.9.48.14:128.2.203.61:130.237.48.87 >/proc/fs/afs/cells
0183
0184 No other cell database operations are available at this time.
0185
0186
0187 Security
0188 ========
0189
0190 Secure operations are initiated by acquiring a key using the klog program. A
0191 very primitive klog program is available at:
0192
0193 https://people.redhat.com/~dhowells/rxrpc/klog.c
0194
0195 This should be compiled by::
0196
0197 make klog LDLIBS="-lcrypto -lcrypt -lkrb4 -lkeyutils"
0198
0199 And then run as::
0200
0201 ./klog
0202
0203 Assuming it's successful, this adds a key of type RxRPC, named for the service
0204 and cell, e.g.: "afs@<cellname>". This can be viewed with the keyctl program or
0205 by cat'ing /proc/keys::
0206
0207 [root@andromeda ~]# keyctl show
0208 Session Keyring
0209 -3 --alswrv 0 0 keyring: _ses.3268
0210 2 --alswrv 0 0 \_ keyring: _uid.0
0211 111416553 --als--v 0 0 \_ rxrpc: afs@CAMBRIDGE.REDHAT.COM
0212
0213 Currently the username, realm, password and proposed ticket lifetime are
0214 compiled into the program.
0215
0216 It is not required to acquire a key before using AFS facilities, but if one is
0217 not acquired then all operations will be governed by the anonymous user parts
0218 of the ACLs.
0219
0220 If a key is acquired, then all AFS operations, including mounts and automounts,
0221 made by a possessor of that key will be secured with that key.
0222
0223 If a file is opened with a particular key and then the file descriptor is
0224 passed to a process that doesn't have that key (perhaps over an AF_UNIX
0225 socket), then the operations on the file will be made with key that was used to
0226 open the file.
0227
0228
0229 The @sys Substitution
0230 =====================
0231
0232 The list of up to 16 @sys substitutions for the current network namespace can
0233 be configured by writing a list to /proc/fs/afs/sysname::
0234
0235 [root@andromeda ~]# echo foo amd64_linux_26 >/proc/fs/afs/sysname
0236
0237 or cleared entirely by writing an empty list::
0238
0239 [root@andromeda ~]# echo >/proc/fs/afs/sysname
0240
0241 The current list for current network namespace can be retrieved by::
0242
0243 [root@andromeda ~]# cat /proc/fs/afs/sysname
0244 foo
0245 amd64_linux_26
0246
0247 When @sys is being substituted for, each element of the list is tried in the
0248 order given.
0249
0250 By default, the list will contain one item that conforms to the pattern
0251 "<arch>_linux_26", amd64 being the name for x86_64.
