About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / filesystems / afs.txt




Custom Search

Based on kernel version 3.13. Page generated on 2014-01-20 22:02 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 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
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.