1.. SPDX-License-Identifier: GPL-2.0
2
3====================
4kAFS: 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
19Overview
20========
21
22This filesystem provides a fairly simple secure AFS filesystem driver. It is
23under development and does not yet provide the full feature set.  The features
24it 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
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
61Usage
62=====
63
64When inserting the driver modules the root cell must be specified along with a
65list 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
70The first module is the AF_RXRPC network protocol driver.  This provides the
71RxRPC remote operation protocol and may also be accessed from userspace.  See:
72
73	Documentation/networking/rxrpc.rst
74
75The second module is the kerberos RxRPC security driver, and the third module
76is the actual filesystem driver for the AFS filesystem.
77
78Once the module has been loaded, more modules can be added by the following
79procedure::
80
81	echo add grand.central.org 18.9.48.14:128.2.203.61:130.237.48.87 >/proc/fs/afs/cells
82
83Where the parameters to the "add" command are the name of a cell and a list of
84volume 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." /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
93Where the initial character is either a hash or a percent symbol depending on
94whether you definitely want a R/W volume (percent) or whether you'd prefer a
95R/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" to
98specify connection to only volumes of those types.
99
100The name of the cell is optional, and if not given during a mount, then the
101named volume will be looked up in the cell specified during modprobe.
102
103Additional cells can be added through /proc (see later section).
104
105
106Mountpoints
107===========
108
109AFS has a concept of mountpoints. In AFS terms, these are specially formatted
110symbolic links (of the same form as the "device name" passed to mount).  kAFS
111presents 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
113automatically cause the target volume to be mounted (if possible) on that site.
114
115Automatically mounted filesystems will be automatically unmounted approximately
116twenty minutes after they were last used.  Alternatively they can be unmounted
117directly with the umount() system call.
118
119Manually unmounting an AFS volume will cause any idle submounts upon it to be
120culled first.  If all are culled, then the requested volume will also be
121unmounted, otherwise error EBUSY will be returned.
122
123This can be used by the administrator to attempt to unmount the whole AFS tree
124mounted on /afs in one go by doing::
125
126	umount /afs
127
128
129Dynamic Root
130============
131
132A mount option is available to create a serverless mount that is only usable
133for dynamic lookup.  Creating such a mount can be done by, for example::
134
135	mount -t afs none /afs -o dyn
136
137This creates a mount that just has an empty directory at the root.  Attempting
138to look up a name in this directory will cause a mountpoint to be created that
139looks up a cell of the same name, for example::
140
141	ls /afs/grand.central.org/
142
143
144Proc Filesystem
145===============
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 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
170The Cell Database
171=================
172
173The filesystem maintains an internal database of all the cells it knows and the
174IP addresses of the volume location servers for those cells.  The cell to which
175the 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
177the 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/cells
182	echo add grand.central.org 18.9.48.14:128.2.203.61:130.237.48.87 >/proc/fs/afs/cells
183
184No other cell database operations are available at this time.
185
186
187Security
188========
189
190Secure operations are initiated by acquiring a key using the klog program.  A
191very primitive klog program is available at:
192
193	https://people.redhat.com/~dhowells/rxrpc/klog.c
194
195This should be compiled by::
196
197	make klog LDLIBS="-lcrypto -lcrypt -lkrb4 -lkeyutils"
198
199And then run as::
200
201	./klog
202
203Assuming it's successful, this adds a key of type RxRPC, named for the service
204and cell, e.g.: "afs@<cellname>".  This can be viewed with the keyctl program or
205by 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
213Currently the username, realm, password and proposed ticket lifetime are
214compiled into the program.
215
216It is not required to acquire a key before using AFS facilities, but if one is
217not acquired then all operations will be governed by the anonymous user parts
218of 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 is
224passed to a process that doesn't have that key (perhaps over an AF_UNIX
225socket), then the operations on the file will be made with key that was used to
226open the file.
227
228
229The @sys Substitution
230=====================
231
232The list of up to 16 @sys substitutions for the current network namespace can
233be configured by writing a list to /proc/fs/afs/sysname::
234
235	[root@andromeda ~]# echo foo amd64_linux_26 >/proc/fs/afs/sysname
236
237or cleared entirely by writing an empty list::
238
239	[root@andromeda ~]# echo >/proc/fs/afs/sysname
240
241The 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
247When @sys is being substituted for, each element of the list is tried in the
248order given.
249
250By default, the list will contain one item that conforms to the pattern
251"<arch>_linux_26", amd64 being the name for x86_64.
252