blob: ffef91c4e0d690312fc8eb176121c76d1522fa43 [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
Anton Blanchard0dc9aa82009-08-19 16:10:16 +010026 (*) File reading and writing.
David Howells0795e7c02007-04-26 15:57:43 -070027
28 (*) Automounting.
29
Anton Blanchard0dc9aa82009-08-19 16:10:16 +010030 (*) Local caching (via fscache).
31
David Howells0795e7c02007-04-26 15:57:43 -070032It does not yet support the following AFS features:
33
David Howells0795e7c02007-04-26 15:57:43 -070034 (*) pioctl() system call.
35
36
37===========
38COMPILATION
39===========
40
41The filesystem should be enabled by turning on the kernel configuration
42options:
43
44 CONFIG_AF_RXRPC - The RxRPC protocol transport
45 CONFIG_RXKAD - The RxRPC Kerberos security handler
46 CONFIG_AFS - The AFS filesystem
47
48Additionally, the following can be turned on to aid debugging:
49
50 CONFIG_AF_RXRPC_DEBUG - Permit AF_RXRPC debugging to be enabled
51 CONFIG_AFS_DEBUG - Permit AFS debugging to be enabled
52
53They permit the debugging messages to be turned on dynamically by manipulating
54the masks in the following files:
55
56 /sys/module/af_rxrpc/parameters/debug
Anton Blanchard0dc9aa82009-08-19 16:10:16 +010057 /sys/module/kafs/parameters/debug
David Howells0795e7c02007-04-26 15:57:43 -070058
59
Linus Torvalds1da177e2005-04-16 15:20:36 -070060=====
Linus Torvalds1da177e2005-04-16 15:20:36 -070061USAGE
62=====
63
64When inserting the driver modules the root cell must be specified along with a
65list of volume location server IP addresses:
66
Anton Blanchard0dc9aa82009-08-19 16:10:16 +010067 modprobe af_rxrpc
68 modprobe rxkad
69 modprobe kafs rootcell=cambridge.redhat.com:172.16.18.73:172.16.18.91
Linus Torvalds1da177e2005-04-16 15:20:36 -070070
David Howells0795e7c02007-04-26 15:57:43 -070071The first module is the AF_RXRPC network protocol driver. This provides the
72RxRPC remote operation protocol and may also be accessed from userspace. See:
73
74 Documentation/networking/rxrpc.txt
75
76The second module is the kerberos RxRPC security driver, and the third module
77is the actual filesystem driver for the AFS filesystem.
Linus Torvalds1da177e2005-04-16 15:20:36 -070078
79Once the module has been loaded, more modules can be added by the following
80procedure:
81
Anton Blanchard0dc9aa82009-08-19 16:10:16 +010082 echo add grand.central.org 18.9.48.14:128.2.203.61:130.237.48.87 >/proc/fs/afs/cells
Linus Torvalds1da177e2005-04-16 15:20:36 -070083
84Where the parameters to the "add" command are the name of a cell and a list of
David Howells0795e7c02007-04-26 15:57:43 -070085volume location servers within that cell, with the latter separated by colons.
Linus Torvalds1da177e2005-04-16 15:20:36 -070086
87Filesystems 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
Linus Torvalds1da177e2005-04-16 15:20:36 -070094Where the initial character is either a hash or a percent symbol depending on
95whether you definitely want a R/W volume (hash) or whether you'd prefer a R/O
96volume, but are willing to use a R/W volume instead (percent).
97
98The name of the volume can be suffixes with ".backup" or ".readonly" to
99specify connection to only volumes of those types.
100
101The name of the cell is optional, and if not given during a mount, then the
Anton Blanchard0dc9aa82009-08-19 16:10:16 +0100102named volume will be looked up in the cell specified during modprobe.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700103
104Additional cells can be added through /proc (see later section).
105
106
David Howells0795e7c02007-04-26 15:57:43 -0700107===========
Linus Torvalds1da177e2005-04-16 15:20:36 -0700108MOUNTPOINTS
109===========
110
David Howells0795e7c02007-04-26 15:57:43 -0700111AFS has a concept of mountpoints. In AFS terms, these are specially formatted
112symbolic links (of the same form as the "device name" passed to mount). kAFS
113presents 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
115automatically cause the target volume to be mounted (if possible) on that site.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700116
David Howells0795e7c02007-04-26 15:57:43 -0700117Automatically mounted filesystems will be automatically unmounted approximately
118twenty minutes after they were last used. Alternatively they can be unmounted
119directly with the umount() system call.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700120
David Howells0795e7c02007-04-26 15:57:43 -0700121Manually unmounting an AFS volume will cause any idle submounts upon it to be
122culled first. If all are culled, then the requested volume will also be
123unmounted, otherwise error EBUSY will be returned.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700124
David Howells0795e7c02007-04-26 15:57:43 -0700125This can be used by the administrator to attempt to unmount the whole AFS tree
126mounted on /afs in one go by doing:
Linus Torvalds1da177e2005-04-16 15:20:36 -0700127
David Howells0795e7c02007-04-26 15:57:43 -0700128 umount /afs
Linus Torvalds1da177e2005-04-16 15:20:36 -0700129
130
David Howells0795e7c02007-04-26 15:57:43 -0700131===============
Linus Torvalds1da177e2005-04-16 15:20:36 -0700132PROC FILESYSTEM
133===============
134
Linus Torvalds1da177e2005-04-16 15:20:36 -0700135The AFS modules creates a "/proc/fs/afs/" directory and populates it:
136
David Howells0795e7c02007-04-26 15:57:43 -0700137 (*) A "cells" file that lists cells currently known to the afs module and
138 their usage counts:
139
140 [root@andromeda ~]# cat /proc/fs/afs/cells
141 USE NAME
142 3 cambridge.redhat.com
Linus Torvalds1da177e2005-04-16 15:20:36 -0700143
144 (*) A directory per cell that contains files that list volume location
145 servers, volumes, and active servers known within that cell.
146
David Howells0795e7c02007-04-26 15:57:43 -0700147 [root@andromeda ~]# cat /proc/fs/afs/cambridge.redhat.com/servers
148 USE ADDR STATE
149 4 172.16.18.91 0
150 [root@andromeda ~]# cat /proc/fs/afs/cambridge.redhat.com/vlservers
151 ADDRESS
152 172.16.18.91
153 [root@andromeda ~]# cat /proc/fs/afs/cambridge.redhat.com/volumes
154 USE STT VLID[0] VLID[1] VLID[2] NAME
155 1 Val 20000000 20000001 20000002 root.afs
Linus Torvalds1da177e2005-04-16 15:20:36 -0700156
David Howells0795e7c02007-04-26 15:57:43 -0700157
158=================
Linus Torvalds1da177e2005-04-16 15:20:36 -0700159THE CELL DATABASE
160=================
161
David Howells0795e7c02007-04-26 15:57:43 -0700162The filesystem maintains an internal database of all the cells it knows and the
163IP addresses of the volume location servers for those cells. The cell to which
Anton Blanchard0dc9aa82009-08-19 16:10:16 +0100164the system belongs is added to the database when modprobe is performed by the
David Howells0795e7c02007-04-26 15:57:43 -0700165"rootcell=" argument or, if compiled in, using a "kafs.rootcell=" argument on
166the kernel command line.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700167
168Further cells can be added by commands similar to the following:
169
170 echo add CELLNAME VLADDR[:VLADDR][:VLADDR]... >/proc/fs/afs/cells
Anton Blanchard0dc9aa82009-08-19 16:10:16 +0100171 echo add grand.central.org 18.9.48.14:128.2.203.61:130.237.48.87 >/proc/fs/afs/cells
Linus Torvalds1da177e2005-04-16 15:20:36 -0700172
173No other cell database operations are available at this time.
174
175
David Howells0795e7c02007-04-26 15:57:43 -0700176========
177SECURITY
178========
179
180Secure operations are initiated by acquiring a key using the klog program. A
181very primitive klog program is available at:
182
183 http://people.redhat.com/~dhowells/rxrpc/klog.c
184
185This should be compiled by:
186
187 make klog LDLIBS="-lcrypto -lcrypt -lkrb4 -lkeyutils"
188
189And then run as:
190
191 ./klog
192
193Assuming it's successful, this adds a key of type RxRPC, named for the service
194and cell, eg: "afs@<cellname>". This can be viewed with the keyctl program or
195by cat'ing /proc/keys:
196
197 [root@andromeda ~]# keyctl show
198 Session Keyring
199 -3 --alswrv 0 0 keyring: _ses.3268
200 2 --alswrv 0 0 \_ keyring: _uid.0
201 111416553 --als--v 0 0 \_ rxrpc: afs@CAMBRIDGE.REDHAT.COM
202
203Currently the username, realm, password and proposed ticket lifetime are
204compiled in to the program.
205
206It is not required to acquire a key before using AFS facilities, but if one is
207not acquired then all operations will be governed by the anonymous user parts
208of the ACLs.
209
210If a key is acquired, then all AFS operations, including mounts and automounts,
211made by a possessor of that key will be secured with that key.
212
213If a file is opened with a particular key and then the file descriptor is
214passed to a process that doesn't have that key (perhaps over an AF_UNIX
215socket), then the operations on the file will be made with key that was used to
216open the file.
217
218
219========
Linus Torvalds1da177e2005-04-16 15:20:36 -0700220EXAMPLES
221========
222
David Howells0795e7c02007-04-26 15:57:43 -0700223Here's what I use to test this. Some of the names and IP addresses are local
224to my internal DNS. My "root.afs" partition has a mount point within it for
Linus Torvalds1da177e2005-04-16 15:20:36 -0700225some public volumes volumes.
226
David Howells0795e7c02007-04-26 15:57:43 -0700227insmod /tmp/rxrpc.o
228insmod /tmp/rxkad.o
229insmod /tmp/kafs.o rootcell=cambridge.redhat.com:172.16.18.91
Linus Torvalds1da177e2005-04-16 15:20:36 -0700230
231mount -t afs \%root.afs. /afs
232mount -t afs \%cambridge.redhat.com:root.cell. /afs/cambridge.redhat.com/
233
Anton Blanchard0dc9aa82009-08-19 16:10:16 +0100234echo add grand.central.org 18.9.48.14:128.2.203.61:130.237.48.87 > /proc/fs/afs/cells
Linus Torvalds1da177e2005-04-16 15:20:36 -0700235mount -t afs "#grand.central.org:root.cell." /afs/grand.central.org/
236mount -t afs "#grand.central.org:root.archive." /afs/grand.central.org/archive
237mount -t afs "#grand.central.org:root.contrib." /afs/grand.central.org/contrib
238mount -t afs "#grand.central.org:root.doc." /afs/grand.central.org/doc
239mount -t afs "#grand.central.org:root.project." /afs/grand.central.org/project
240mount -t afs "#grand.central.org:root.service." /afs/grand.central.org/service
241mount -t afs "#grand.central.org:root.software." /afs/grand.central.org/software
242mount -t afs "#grand.central.org:root.user." /afs/grand.central.org/user
243
Linus Torvalds1da177e2005-04-16 15:20:36 -0700244umount /afs
245rmmod kafs
David Howells0795e7c02007-04-26 15:57:43 -0700246rmmod rxkad
Linus Torvalds1da177e2005-04-16 15:20:36 -0700247rmmod rxrpc