blob: 12ad6c7f4e50a8e33d395b3993341715b25db960 [file] [log] [blame]
David Howells0795e7c02007-04-26 15:57:43 -07001 ====================
Linus Torvalds1da177e2005-04-16 15:20:36 -07002 kAFS: AFS FILESYSTEM
3 ====================
4
David Howells0795e7c02007-04-26 15:57:43 -07005Contents:
6
7 - Overview.
8 - Usage.
9 - Mountpoints.
10 - Proc filesystem.
11 - The cell database.
12 - Security.
13 - Examples.
14
15
16========
17OVERVIEW
18========
19
20This filesystem provides a fairly simple secure AFS filesystem driver. It is
21under development and does not yet provide the full feature set. The features
22it does support include:
23
24 (*) Security (currently only AFS kaserver and KerberosIV tickets).
25
26 (*) File reading.
27
28 (*) Automounting.
29
30It does not yet support the following AFS features:
31
32 (*) Write support.
33
34 (*) Local caching.
35
36 (*) pioctl() system call.
37
38
39===========
40COMPILATION
41===========
42
43The filesystem should be enabled by turning on the kernel configuration
44options:
45
46 CONFIG_AF_RXRPC - The RxRPC protocol transport
47 CONFIG_RXKAD - The RxRPC Kerberos security handler
48 CONFIG_AFS - The AFS filesystem
49
50Additionally, the following can be turned on to aid debugging:
51
52 CONFIG_AF_RXRPC_DEBUG - Permit AF_RXRPC debugging to be enabled
53 CONFIG_AFS_DEBUG - Permit AFS debugging to be enabled
54
55They permit the debugging messages to be turned on dynamically by manipulating
56the masks in the following files:
57
58 /sys/module/af_rxrpc/parameters/debug
59 /sys/module/afs/parameters/debug
60
61
Linus Torvalds1da177e2005-04-16 15:20:36 -070062=====
Linus Torvalds1da177e2005-04-16 15:20:36 -070063USAGE
64=====
65
66When inserting the driver modules the root cell must be specified along with a
67list of volume location server IP addresses:
68
David Howells0795e7c02007-04-26 15:57:43 -070069 insmod af_rxrpc.o
70 insmod rxkad.o
Linus Torvalds1da177e2005-04-16 15:20:36 -070071 insmod kafs.o rootcell=cambridge.redhat.com:172.16.18.73:172.16.18.91
72
David Howells0795e7c02007-04-26 15:57:43 -070073The first module is the AF_RXRPC network protocol driver. This provides the
74RxRPC remote operation protocol and may also be accessed from userspace. See:
75
76 Documentation/networking/rxrpc.txt
77
78The second module is the kerberos RxRPC security driver, and the third module
79is the actual filesystem driver for the AFS filesystem.
Linus Torvalds1da177e2005-04-16 15:20:36 -070080
81Once the module has been loaded, more modules can be added by the following
82procedure:
83
84 echo add grand.central.org 18.7.14.88:128.2.191.224 >/proc/fs/afs/cells
85
86Where the parameters to the "add" command are the name of a cell and a list of
David Howells0795e7c02007-04-26 15:57:43 -070087volume location servers within that cell, with the latter separated by colons.
Linus Torvalds1da177e2005-04-16 15:20:36 -070088
89Filesystems can be mounted anywhere by commands similar to the following:
90
91 mount -t afs "%cambridge.redhat.com:root.afs." /afs
92 mount -t afs "#cambridge.redhat.com:root.cell." /afs/cambridge
93 mount -t afs "#root.afs." /afs
94 mount -t afs "#root.cell." /afs/cambridge
95
Linus Torvalds1da177e2005-04-16 15:20:36 -070096Where the initial character is either a hash or a percent symbol depending on
97whether you definitely want a R/W volume (hash) or whether you'd prefer a R/O
98volume, but are willing to use a R/W volume instead (percent).
99
100The name of the volume can be suffixes with ".backup" or ".readonly" to
101specify connection to only volumes of those types.
102
103The name of the cell is optional, and if not given during a mount, then the
104named volume will be looked up in the cell specified during insmod.
105
106Additional cells can be added through /proc (see later section).
107
108
David Howells0795e7c02007-04-26 15:57:43 -0700109===========
Linus Torvalds1da177e2005-04-16 15:20:36 -0700110MOUNTPOINTS
111===========
112
David Howells0795e7c02007-04-26 15:57:43 -0700113AFS has a concept of mountpoints. In AFS terms, these are specially formatted
114symbolic links (of the same form as the "device name" passed to mount). kAFS
115presents these to the user as directories that have a follow-link capability
116(ie: symbolic link semantics). If anyone attempts to access them, they will
117automatically cause the target volume to be mounted (if possible) on that site.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700118
David Howells0795e7c02007-04-26 15:57:43 -0700119Automatically mounted filesystems will be automatically unmounted approximately
120twenty minutes after they were last used. Alternatively they can be unmounted
121directly with the umount() system call.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700122
David Howells0795e7c02007-04-26 15:57:43 -0700123Manually unmounting an AFS volume will cause any idle submounts upon it to be
124culled first. If all are culled, then the requested volume will also be
125unmounted, otherwise error EBUSY will be returned.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700126
David Howells0795e7c02007-04-26 15:57:43 -0700127This can be used by the administrator to attempt to unmount the whole AFS tree
128mounted on /afs in one go by doing:
Linus Torvalds1da177e2005-04-16 15:20:36 -0700129
David Howells0795e7c02007-04-26 15:57:43 -0700130 umount /afs
Linus Torvalds1da177e2005-04-16 15:20:36 -0700131
132
David Howells0795e7c02007-04-26 15:57:43 -0700133===============
Linus Torvalds1da177e2005-04-16 15:20:36 -0700134PROC FILESYSTEM
135===============
136
Linus Torvalds1da177e2005-04-16 15:20:36 -0700137The AFS modules creates a "/proc/fs/afs/" directory and populates it:
138
David Howells0795e7c02007-04-26 15:57:43 -0700139 (*) A "cells" file that lists cells currently known to the afs module and
140 their usage counts:
141
142 [root@andromeda ~]# cat /proc/fs/afs/cells
143 USE NAME
144 3 cambridge.redhat.com
Linus Torvalds1da177e2005-04-16 15:20:36 -0700145
146 (*) A directory per cell that contains files that list volume location
147 servers, volumes, and active servers known within that cell.
148
David Howells0795e7c02007-04-26 15:57:43 -0700149 [root@andromeda ~]# cat /proc/fs/afs/cambridge.redhat.com/servers
150 USE ADDR STATE
151 4 172.16.18.91 0
152 [root@andromeda ~]# cat /proc/fs/afs/cambridge.redhat.com/vlservers
153 ADDRESS
154 172.16.18.91
155 [root@andromeda ~]# cat /proc/fs/afs/cambridge.redhat.com/volumes
156 USE STT VLID[0] VLID[1] VLID[2] NAME
157 1 Val 20000000 20000001 20000002 root.afs
Linus Torvalds1da177e2005-04-16 15:20:36 -0700158
David Howells0795e7c02007-04-26 15:57:43 -0700159
160=================
Linus Torvalds1da177e2005-04-16 15:20:36 -0700161THE CELL DATABASE
162=================
163
David Howells0795e7c02007-04-26 15:57:43 -0700164The filesystem maintains an internal database of all the cells it knows and the
165IP addresses of the volume location servers for those cells. The cell to which
166the system belongs is added to the database when insmod is performed by the
167"rootcell=" argument or, if compiled in, using a "kafs.rootcell=" argument on
168the kernel command line.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700169
170Further cells can be added by commands similar to the following:
171
172 echo add CELLNAME VLADDR[:VLADDR][:VLADDR]... >/proc/fs/afs/cells
173 echo add grand.central.org 18.7.14.88:128.2.191.224 >/proc/fs/afs/cells
174
175No other cell database operations are available at this time.
176
177
David Howells0795e7c02007-04-26 15:57:43 -0700178========
179SECURITY
180========
181
182Secure operations are initiated by acquiring a key using the klog program. A
183very primitive klog program is available at:
184
185 http://people.redhat.com/~dhowells/rxrpc/klog.c
186
187This should be compiled by:
188
189 make klog LDLIBS="-lcrypto -lcrypt -lkrb4 -lkeyutils"
190
191And then run as:
192
193 ./klog
194
195Assuming it's successful, this adds a key of type RxRPC, named for the service
196and cell, eg: "afs@<cellname>". This can be viewed with the keyctl program or
197by cat'ing /proc/keys:
198
199 [root@andromeda ~]# keyctl show
200 Session Keyring
201 -3 --alswrv 0 0 keyring: _ses.3268
202 2 --alswrv 0 0 \_ keyring: _uid.0
203 111416553 --als--v 0 0 \_ rxrpc: afs@CAMBRIDGE.REDHAT.COM
204
205Currently the username, realm, password and proposed ticket lifetime are
206compiled in to the program.
207
208It is not required to acquire a key before using AFS facilities, but if one is
209not acquired then all operations will be governed by the anonymous user parts
210of the ACLs.
211
212If a key is acquired, then all AFS operations, including mounts and automounts,
213made by a possessor of that key will be secured with that key.
214
215If a file is opened with a particular key and then the file descriptor is
216passed to a process that doesn't have that key (perhaps over an AF_UNIX
217socket), then the operations on the file will be made with key that was used to
218open the file.
219
220
221========
Linus Torvalds1da177e2005-04-16 15:20:36 -0700222EXAMPLES
223========
224
David Howells0795e7c02007-04-26 15:57:43 -0700225Here's what I use to test this. Some of the names and IP addresses are local
226to my internal DNS. My "root.afs" partition has a mount point within it for
Linus Torvalds1da177e2005-04-16 15:20:36 -0700227some public volumes volumes.
228
David Howells0795e7c02007-04-26 15:57:43 -0700229insmod /tmp/rxrpc.o
230insmod /tmp/rxkad.o
231insmod /tmp/kafs.o rootcell=cambridge.redhat.com:172.16.18.91
Linus Torvalds1da177e2005-04-16 15:20:36 -0700232
233mount -t afs \%root.afs. /afs
234mount -t afs \%cambridge.redhat.com:root.cell. /afs/cambridge.redhat.com/
235
David Howells0795e7c02007-04-26 15:57:43 -0700236echo add grand.central.org 18.7.14.88:128.2.191.224 > /proc/fs/afs/cells
Linus Torvalds1da177e2005-04-16 15:20:36 -0700237mount -t afs "#grand.central.org:root.cell." /afs/grand.central.org/
238mount -t afs "#grand.central.org:root.archive." /afs/grand.central.org/archive
239mount -t afs "#grand.central.org:root.contrib." /afs/grand.central.org/contrib
240mount -t afs "#grand.central.org:root.doc." /afs/grand.central.org/doc
241mount -t afs "#grand.central.org:root.project." /afs/grand.central.org/project
242mount -t afs "#grand.central.org:root.service." /afs/grand.central.org/service
243mount -t afs "#grand.central.org:root.software." /afs/grand.central.org/software
244mount -t afs "#grand.central.org:root.user." /afs/grand.central.org/user
245
Linus Torvalds1da177e2005-04-16 15:20:36 -0700246umount /afs
247rmmod kafs
David Howells0795e7c02007-04-26 15:57:43 -0700248rmmod rxkad
Linus Torvalds1da177e2005-04-16 15:20:36 -0700249rmmod rxrpc