aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation
diff options
context:
space:
mode:
authorDavid Howells <dhowells@redhat.com>2007-04-26 18:57:43 -0400
committerDavid S. Miller <davem@davemloft.net>2007-04-26 18:57:43 -0400
commit0795e7c031c4bda46fbdde678adf29de19bef7f4 (patch)
tree7a059454eb2da6984c07ea79d4eafcb085ae3bab /Documentation
parent00d3b7a4533e367b0dc2812a706db8f9f071c27f (diff)
[AFS]: Update the AFS fs documentation.
Update the AFS fs documentation. Signed-off-by: David Howells <dhowells@redhat.com> Signed-off-by: David S. Miller <davem@davemloft.net>
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/filesystems/afs.txt214
1 files changed, 154 insertions, 60 deletions
diff --git a/Documentation/filesystems/afs.txt b/Documentation/filesystems/afs.txt
index 2f4237dfb8c7..12ad6c7f4e50 100644
--- a/Documentation/filesystems/afs.txt
+++ b/Documentation/filesystems/afs.txt
@@ -1,31 +1,82 @@
1 ====================
1 kAFS: AFS FILESYSTEM 2 kAFS: AFS FILESYSTEM
2 ==================== 3 ====================
3 4
4ABOUT 5Contents:
5===== 6
7 - Overview.
8 - Usage.
9 - Mountpoints.
10 - Proc filesystem.
11 - The cell database.
12 - Security.
13 - Examples.
14
15
16========
17OVERVIEW
18========
6 19
7This filesystem provides a fairly simple AFS filesystem driver. It is under 20This filesystem provides a fairly simple secure AFS filesystem driver. It is
8development and only provides very basic facilities. It does not yet support 21under development and does not yet provide the full feature set. The features
9the following AFS features: 22it does support include:
10 23
11 (*) Write support. 24 (*) Security (currently only AFS kaserver and KerberosIV tickets).
12 (*) Communications security.
13 (*) Local caching.
14 (*) pioctl() system call.
15 (*) Automatic mounting of embedded mountpoints.
16 25
26 (*) File reading.
17 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
62=====
18USAGE 63USAGE
19===== 64=====
20 65
21When inserting the driver modules the root cell must be specified along with a 66When inserting the driver modules the root cell must be specified along with a
22list of volume location server IP addresses: 67list of volume location server IP addresses:
23 68
24 insmod rxrpc.o 69 insmod af_rxrpc.o
70 insmod rxkad.o
25 insmod kafs.o rootcell=cambridge.redhat.com:172.16.18.73:172.16.18.91 71 insmod kafs.o rootcell=cambridge.redhat.com:172.16.18.73:172.16.18.91
26 72
27The first module is a driver for the RxRPC remote operation protocol, and the 73The first module is the AF_RXRPC network protocol driver. This provides the
28second is the actual filesystem driver for the AFS filesystem. 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.
29 80
30Once the module has been loaded, more modules can be added by the following 81Once the module has been loaded, more modules can be added by the following
31procedure: 82procedure:
@@ -33,7 +84,7 @@ procedure:
33 echo add grand.central.org 18.7.14.88:128.2.191.224 >/proc/fs/afs/cells 84 echo add grand.central.org 18.7.14.88:128.2.191.224 >/proc/fs/afs/cells
34 85
35Where the parameters to the "add" command are the name of a cell and a list of 86Where the parameters to the "add" command are the name of a cell and a list of
36volume location servers within that cell. 87volume location servers within that cell, with the latter separated by colons.
37 88
38Filesystems can be mounted anywhere by commands similar to the following: 89Filesystems can be mounted anywhere by commands similar to the following:
39 90
@@ -42,11 +93,6 @@ Filesystems can be mounted anywhere by commands similar to the following:
42 mount -t afs "#root.afs." /afs 93 mount -t afs "#root.afs." /afs
43 mount -t afs "#root.cell." /afs/cambridge 94 mount -t afs "#root.cell." /afs/cambridge
44 95
45 NB: When using this on Linux 2.4, the mount command has to be different,
46 since the filesystem doesn't have access to the device name argument:
47
48 mount -t afs none /afs -ovol="#root.afs."
49
50Where the initial character is either a hash or a percent symbol depending on 96Where the initial character is either a hash or a percent symbol depending on
51whether you definitely want a R/W volume (hash) or whether you'd prefer a R/O 97whether you definitely want a R/W volume (hash) or whether you'd prefer a R/O
52volume, but are willing to use a R/W volume instead (percent). 98volume, but are willing to use a R/W volume instead (percent).
@@ -60,55 +106,66 @@ named volume will be looked up in the cell specified during insmod.
60Additional cells can be added through /proc (see later section). 106Additional cells can be added through /proc (see later section).
61 107
62 108
109===========
63MOUNTPOINTS 110MOUNTPOINTS
64=========== 111===========
65 112
66AFS has a concept of mountpoints. These are specially formatted symbolic links 113AFS has a concept of mountpoints. In AFS terms, these are specially formatted
67(of the same form as the "device name" passed to mount). kAFS presents these 114symbolic links (of the same form as the "device name" passed to mount). kAFS
68to the user as directories that have special properties: 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.
69 118
70 (*) They cannot be listed. Running a program like "ls" on them will incur an 119Automatically mounted filesystems will be automatically unmounted approximately
71 EREMOTE error (Object is remote). 120twenty minutes after they were last used. Alternatively they can be unmounted
121directly with the umount() system call.
72 122
73 (*) Other objects can't be looked up inside of them. This also incurs an 123Manually unmounting an AFS volume will cause any idle submounts upon it to be
74 EREMOTE error. 124culled first. If all are culled, then the requested volume will also be
125unmounted, otherwise error EBUSY will be returned.
75 126
76 (*) They can be queried with the readlink() system call, which will return 127This can be used by the administrator to attempt to unmount the whole AFS tree
77 the name of the mountpoint to which they point. The "readlink" program 128mounted on /afs in one go by doing:
78 will also work.
79 129
80 (*) They can be mounted on (which symbolic links can't). 130 umount /afs
81 131
82 132
133===============
83PROC FILESYSTEM 134PROC FILESYSTEM
84=============== 135===============
85 136
86The rxrpc module creates a number of files in various places in the /proc
87filesystem:
88
89 (*) Firstly, some information files are made available in a directory called
90 "/proc/net/rxrpc/". These list the extant transport endpoint, peer,
91 connection and call records.
92
93 (*) Secondly, some control files are made available in a directory called
94 "/proc/sys/rxrpc/". Currently, all these files can be used for is to
95 turn on various levels of tracing.
96
97The AFS modules creates a "/proc/fs/afs/" directory and populates it: 137The AFS modules creates a "/proc/fs/afs/" directory and populates it:
98 138
99 (*) A "cells" file that lists cells currently known to the afs module. 139 (*) 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
100 145
101 (*) A directory per cell that contains files that list volume location 146 (*) A directory per cell that contains files that list volume location
102 servers, volumes, and active servers known within that cell. 147 servers, volumes, and active servers known within that cell.
103 148
149 [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
104 158
159
160=================
105THE CELL DATABASE 161THE CELL DATABASE
106================= 162=================
107 163
108The filesystem maintains an internal database of all the cells it knows and 164The filesystem maintains an internal database of all the cells it knows and the
109the IP addresses of the volume location servers for those cells. The cell to 165IP addresses of the volume location servers for those cells. The cell to which
110which the computer belongs is added to the database when insmod is performed 166the system belongs is added to the database when insmod is performed by the
111by the "rootcell=" argument. 167"rootcell=" argument or, if compiled in, using a "kafs.rootcell=" argument on
168the kernel command line.
112 169
113Further cells can be added by commands similar to the following: 170Further cells can be added by commands similar to the following:
114 171
@@ -118,20 +175,65 @@ Further cells can be added by commands similar to the following:
118No other cell database operations are available at this time. 175No other cell database operations are available at this time.
119 176
120 177
178========
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========
121EXAMPLES 222EXAMPLES
122======== 223========
123 224
124Here's what I use to test this. Some of the names and IP addresses are local 225Here's what I use to test this. Some of the names and IP addresses are local
125to my internal DNS. My "root.afs" partition has a mount point within it for 226to my internal DNS. My "root.afs" partition has a mount point within it for
126some public volumes volumes. 227some public volumes volumes.
127 228
128insmod -S /tmp/rxrpc.o 229insmod /tmp/rxrpc.o
129insmod -S /tmp/kafs.o rootcell=cambridge.redhat.com:172.16.18.73:172.16.18.91 230insmod /tmp/rxkad.o
231insmod /tmp/kafs.o rootcell=cambridge.redhat.com:172.16.18.91
130 232
131mount -t afs \%root.afs. /afs 233mount -t afs \%root.afs. /afs
132mount -t afs \%cambridge.redhat.com:root.cell. /afs/cambridge.redhat.com/ 234mount -t afs \%cambridge.redhat.com:root.cell. /afs/cambridge.redhat.com/
133 235
134echo add grand.central.org 18.7.14.88:128.2.191.224 > /proc/fs/afs/cells 236echo add grand.central.org 18.7.14.88:128.2.191.224 > /proc/fs/afs/cells
135mount -t afs "#grand.central.org:root.cell." /afs/grand.central.org/ 237mount -t afs "#grand.central.org:root.cell." /afs/grand.central.org/
136mount -t afs "#grand.central.org:root.archive." /afs/grand.central.org/archive 238mount -t afs "#grand.central.org:root.archive." /afs/grand.central.org/archive
137mount -t afs "#grand.central.org:root.contrib." /afs/grand.central.org/contrib 239mount -t afs "#grand.central.org:root.contrib." /afs/grand.central.org/contrib
@@ -141,15 +243,7 @@ mount -t afs "#grand.central.org:root.service." /afs/grand.central.org/service
141mount -t afs "#grand.central.org:root.software." /afs/grand.central.org/software 243mount -t afs "#grand.central.org:root.software." /afs/grand.central.org/software
142mount -t afs "#grand.central.org:root.user." /afs/grand.central.org/user 244mount -t afs "#grand.central.org:root.user." /afs/grand.central.org/user
143 245
144umount /afs/grand.central.org/user
145umount /afs/grand.central.org/software
146umount /afs/grand.central.org/service
147umount /afs/grand.central.org/project
148umount /afs/grand.central.org/doc
149umount /afs/grand.central.org/contrib
150umount /afs/grand.central.org/archive
151umount /afs/grand.central.org
152umount /afs/cambridge.redhat.com
153umount /afs 246umount /afs
154rmmod kafs 247rmmod kafs
248rmmod rxkad
155rmmod rxrpc 249rmmod rxrpc