Merge branch 'mnt_devname' of git://git.kernel.org/pub/scm/linux/kernel/git/viro...
[linux-2.6.git] / Documentation / filesystems / afs.txt
1                              ====================
2                              kAFS: AFS FILESYSTEM
3                              ====================
4
5 Contents:
6
7  - Overview.
8  - Usage.
9  - Mountpoints.
10  - Proc filesystem.
11  - The cell database.
12  - Security.
13  - Examples.
14
15
16 ========
17 OVERVIEW
18 ========
19
20 This filesystem provides a fairly simple secure AFS filesystem driver. It is
21 under development and does not yet provide the full feature set.  The features
22 it does support include:
23
24  (*) Security (currently only AFS kaserver and KerberosIV tickets).
25
26  (*) File reading and writing.
27
28  (*) Automounting.
29
30  (*) Local caching (via fscache).
31
32 It does not yet support the following AFS features:
33
34  (*) pioctl() system call.
35
36
37 ===========
38 COMPILATION
39 ===========
40
41 The filesystem should be enabled by turning on the kernel configuration
42 options:
43
44         CONFIG_AF_RXRPC         - The RxRPC protocol transport
45         CONFIG_RXKAD            - The RxRPC Kerberos security handler
46         CONFIG_AFS              - The AFS filesystem
47
48 Additionally, 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
53 They permit the debugging messages to be turned on dynamically by manipulating
54 the masks in the following files:
55
56         /sys/module/af_rxrpc/parameters/debug
57         /sys/module/kafs/parameters/debug
58
59
60 =====
61 USAGE
62 =====
63
64 When inserting the driver modules the root cell must be specified along with a
65 list of volume location server IP addresses:
66
67         modprobe af_rxrpc
68         modprobe rxkad
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 (hash) or whether you'd prefer a R/O
96 volume, but are willing to use a R/W volume instead (percent).
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 PROC FILESYSTEM
133 ===============
134
135 The AFS modules creates a "/proc/fs/afs/" directory and populates it:
136
137   (*) 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
143
144   (*) A directory per cell that contains files that list volume location
145       servers, volumes, and active servers known within that cell.
146
147         [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
156
157
158 =================
159 THE CELL DATABASE
160 =================
161
162 The filesystem maintains an internal database of all the cells it knows and the
163 IP addresses of the volume location servers for those cells.  The cell to which
164 the system belongs is added to the database when modprobe is performed by the
165 "rootcell=" argument or, if compiled in, using a "kafs.rootcell=" argument on
166 the kernel command line.
167
168 Further cells can be added by commands similar to the following:
169
170         echo add CELLNAME VLADDR[:VLADDR][:VLADDR]... >/proc/fs/afs/cells
171         echo add grand.central.org 18.9.48.14:128.2.203.61:130.237.48.87 >/proc/fs/afs/cells
172
173 No other cell database operations are available at this time.
174
175
176 ========
177 SECURITY
178 ========
179
180 Secure operations are initiated by acquiring a key using the klog program.  A
181 very primitive klog program is available at:
182
183         http://people.redhat.com/~dhowells/rxrpc/klog.c
184
185 This should be compiled by:
186
187         make klog LDLIBS="-lcrypto -lcrypt -lkrb4 -lkeyutils"
188
189 And then run as:
190
191         ./klog
192
193 Assuming it's successful, this adds a key of type RxRPC, named for the service
194 and cell, eg: "afs@<cellname>".  This can be viewed with the keyctl program or
195 by 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
203 Currently the username, realm, password and proposed ticket lifetime are
204 compiled in to the program.
205
206 It is not required to acquire a key before using AFS facilities, but if one is
207 not acquired then all operations will be governed by the anonymous user parts
208 of the ACLs.
209
210 If a key is acquired, then all AFS operations, including mounts and automounts,
211 made by a possessor of that key will be secured with that key.
212
213 If a file is opened with a particular key and then the file descriptor is
214 passed to a process that doesn't have that key (perhaps over an AF_UNIX
215 socket), then the operations on the file will be made with key that was used to
216 open the file.
217
218
219 ========
220 EXAMPLES
221 ========
222
223 Here's what I use to test this.  Some of the names and IP addresses are local
224 to my internal DNS.  My "root.afs" partition has a mount point within it for
225 some public volumes volumes.
226
227 insmod /tmp/rxrpc.o
228 insmod /tmp/rxkad.o
229 insmod /tmp/kafs.o rootcell=cambridge.redhat.com:172.16.18.91
230
231 mount -t afs \%root.afs. /afs
232 mount -t afs \%cambridge.redhat.com:root.cell. /afs/cambridge.redhat.com/
233
234 echo add grand.central.org 18.9.48.14:128.2.203.61:130.237.48.87 > /proc/fs/afs/cells
235 mount -t afs "#grand.central.org:root.cell." /afs/grand.central.org/
236 mount -t afs "#grand.central.org:root.archive." /afs/grand.central.org/archive
237 mount -t afs "#grand.central.org:root.contrib." /afs/grand.central.org/contrib
238 mount -t afs "#grand.central.org:root.doc." /afs/grand.central.org/doc
239 mount -t afs "#grand.central.org:root.project." /afs/grand.central.org/project
240 mount -t afs "#grand.central.org:root.service." /afs/grand.central.org/service
241 mount -t afs "#grand.central.org:root.software." /afs/grand.central.org/software
242 mount -t afs "#grand.central.org:root.user." /afs/grand.central.org/user
243
244 umount /afs
245 rmmod kafs
246 rmmod rxkad
247 rmmod rxrpc