About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / filesystems / afs.txt

Based on kernel version 2.6.26. Page generated on 2008-07-16 21:12 EST.

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.
27	
28	 (*) Automounting.
29	
30	It does not yet support the following AFS features:
31	
32	 (*) Write support.
33	
34	 (*) Local caching.
35	
36	 (*) pioctl() system call.
37	
38	
39	===========
40	COMPILATION
41	===========
42	
43	The filesystem should be enabled by turning on the kernel configuration
44	options:
45	
46		CONFIG_AF_RXRPC		- The RxRPC protocol transport
47		CONFIG_RXKAD		- The RxRPC Kerberos security handler
48		CONFIG_AFS		- The AFS filesystem
49	
50	Additionally, 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	
55	They permit the debugging messages to be turned on dynamically by manipulating
56	the masks in the following files:
57	
58		/sys/module/af_rxrpc/parameters/debug
59		/sys/module/afs/parameters/debug
60	
61	
62	=====
63	USAGE
64	=====
65	
66	When inserting the driver modules the root cell must be specified along with a
67	list of volume location server IP addresses:
68	
69		insmod af_rxrpc.o
70		insmod rxkad.o
71		insmod kafs.o rootcell=cambridge.redhat.com:172.16.18.73:172.16.18.91
72	
73	The first module is the AF_RXRPC network protocol driver.  This provides the
74	RxRPC remote operation protocol and may also be accessed from userspace.  See:
75	
76		Documentation/networking/rxrpc.txt
77	
78	The second module is the kerberos RxRPC security driver, and the third module
79	is the actual filesystem driver for the AFS filesystem.
80	
81	Once the module has been loaded, more modules can be added by the following
82	procedure:
83	
84		echo add grand.central.org 18.7.14.88:128.2.191.224 >/proc/fs/afs/cells
85	
86	Where the parameters to the "add" command are the name of a cell and a list of
87	volume location servers within that cell, with the latter separated by colons.
88	
89	Filesystems 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	
96	Where the initial character is either a hash or a percent symbol depending on
97	whether you definitely want a R/W volume (hash) or whether you'd prefer a R/O
98	volume, but are willing to use a R/W volume instead (percent).
99	
100	The name of the volume can be suffixes with ".backup" or ".readonly" to
101	specify connection to only volumes of those types.
102	
103	The name of the cell is optional, and if not given during a mount, then the
104	named volume will be looked up in the cell specified during insmod.
105	
106	Additional cells can be added through /proc (see later section).
107	
108	
109	===========
110	MOUNTPOINTS
111	===========
112	
113	AFS has a concept of mountpoints. In AFS terms, these are specially formatted
114	symbolic links (of the same form as the "device name" passed to mount).  kAFS
115	presents 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
117	automatically cause the target volume to be mounted (if possible) on that site.
118	
119	Automatically mounted filesystems will be automatically unmounted approximately
120	twenty minutes after they were last used.  Alternatively they can be unmounted
121	directly with the umount() system call.
122	
123	Manually unmounting an AFS volume will cause any idle submounts upon it to be
124	culled first.  If all are culled, then the requested volume will also be
125	unmounted, otherwise error EBUSY will be returned.
126	
127	This can be used by the administrator to attempt to unmount the whole AFS tree
128	mounted on /afs in one go by doing:
129	
130		umount /afs
131	
132	
133	===============
134	PROC FILESYSTEM
135	===============
136	
137	The AFS modules creates a "/proc/fs/afs/" directory and populates it:
138	
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
145	
146	  (*) A directory per cell that contains files that list volume location
147	      servers, volumes, and active servers known within that cell.
148	
149		[root[AT]andromeda ~]# cat /proc/fs/afs/cambridge.redhat[DOT]com/servers
150		USE ADDR            STATE
151		  4 172.16.18.91        0
152		[root[AT]andromeda ~]# cat /proc/fs/afs/cambridge.redhat[DOT]com/vlservers
153		ADDRESS
154		172.16.18.91
155		[root[AT]andromeda ~]# cat /proc/fs/afs/cambridge.redhat[DOT]com/volumes
156		USE STT VLID[0]  VLID[1]  VLID[2]  NAME
157		  1 Val 20000000 20000001 20000002 root.afs
158	
159	
160	=================
161	THE CELL DATABASE
162	=================
163	
164	The filesystem maintains an internal database of all the cells it knows and the
165	IP addresses of the volume location servers for those cells.  The cell to which
166	the 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
168	the kernel command line.
169	
170	Further 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	
175	No other cell database operations are available at this time.
176	
177	
178	========
179	SECURITY
180	========
181	
182	Secure operations are initiated by acquiring a key using the klog program.  A
183	very primitive klog program is available at:
184	
185		http://people.redhat.com/~dhowells/rxrpc/klog.c
186	
187	This should be compiled by:
188	
189		make klog LDLIBS="-lcrypto -lcrypt -lkrb4 -lkeyutils"
190	
191	And then run as:
192	
193		./klog
194	
195	Assuming it's successful, this adds a key of type RxRPC, named for the service
196	and cell, eg: "afs[AT]<cellname>"[DOT]  This can be viewed with the keyctl program or
197	by 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[AT]CAMBRIDGE.REDHAT[DOT]COM
204	
205	Currently the username, realm, password and proposed ticket lifetime are
206	compiled in to the program.
207	
208	It is not required to acquire a key before using AFS facilities, but if one is
209	not acquired then all operations will be governed by the anonymous user parts
210	of the ACLs.
211	
212	If a key is acquired, then all AFS operations, including mounts and automounts,
213	made by a possessor of that key will be secured with that key.
214	
215	If a file is opened with a particular key and then the file descriptor is
216	passed to a process that doesn't have that key (perhaps over an AF_UNIX
217	socket), then the operations on the file will be made with key that was used to
218	open the file.
219	
220	
221	========
222	EXAMPLES
223	========
224	
225	Here's what I use to test this.  Some of the names and IP addresses are local
226	to my internal DNS.  My "root.afs" partition has a mount point within it for
227	some public volumes volumes.
228	
229	insmod /tmp/rxrpc.o
230	insmod /tmp/rxkad.o
231	insmod /tmp/kafs.o rootcell=cambridge.redhat.com:172.16.18.91
232	
233	mount -t afs \%root.afs. /afs
234	mount -t afs \%cambridge.redhat.com:root.cell. /afs/cambridge.redhat.com/
235	
236	echo add grand.central.org 18.7.14.88:128.2.191.224 > /proc/fs/afs/cells
237	mount -t afs "#grand.central.org:root.cell." /afs/grand.central.org/
238	mount -t afs "#grand.central.org:root.archive." /afs/grand.central.org/archive
239	mount -t afs "#grand.central.org:root.contrib." /afs/grand.central.org/contrib
240	mount -t afs "#grand.central.org:root.doc." /afs/grand.central.org/doc
241	mount -t afs "#grand.central.org:root.project." /afs/grand.central.org/project
242	mount -t afs "#grand.central.org:root.service." /afs/grand.central.org/service
243	mount -t afs "#grand.central.org:root.software." /afs/grand.central.org/software
244	mount -t afs "#grand.central.org:root.user." /afs/grand.central.org/user
245	
246	umount /afs
247	rmmod kafs
248	rmmod rxkad
249	rmmod rxrpc
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.