About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / filesystems / afs.txt




Custom Search

Based on kernel version 4.13.3. Page generated on 2017-09-23 13:55 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 rxrpc
68		modprobe kafs rootcell=cambridge.redhat.com:172.16.18.73:172.16.18.91
69	
70	The first module is the AF_RXRPC network protocol driver.  This provides the
71	RxRPC remote operation protocol and may also be accessed from userspace.  See:
72	
73		Documentation/networking/rxrpc.txt
74	
75	The second module is the kerberos RxRPC security driver, and the third module
76	is the actual filesystem driver for the AFS filesystem.
77	
78	Once the module has been loaded, more modules can be added by the following
79	procedure:
80	
81		echo add grand.central.org 18.9.48.14:128.2.203.61:130.237.48.87 >/proc/fs/afs/cells
82	
83	Where the parameters to the "add" command are the name of a cell and a list of
84	volume location servers within that cell, with the latter separated by colons.
85	
86	Filesystems can be mounted anywhere by commands similar to the following:
87	
88		mount -t afs "%cambridge.redhat.com:root.afs." /afs
89		mount -t afs "#cambridge.redhat.com:root.cell." /afs/cambridge
90		mount -t afs "#root.afs." /afs
91		mount -t afs "#root.cell." /afs/cambridge
92	
93	Where the initial character is either a hash or a percent symbol depending on
94	whether you definitely want a R/W volume (hash) or whether you'd prefer a R/O
95	volume, but are willing to use a R/W volume instead (percent).
96	
97	The name of the volume can be suffixes with ".backup" or ".readonly" to
98	specify connection to only volumes of those types.
99	
100	The name of the cell is optional, and if not given during a mount, then the
101	named volume will be looked up in the cell specified during modprobe.
102	
103	Additional cells can be added through /proc (see later section).
104	
105	
106	===========
107	MOUNTPOINTS
108	===========
109	
110	AFS has a concept of mountpoints. In AFS terms, these are specially formatted
111	symbolic links (of the same form as the "device name" passed to mount).  kAFS
112	presents these to the user as directories that have a follow-link capability
113	(ie: symbolic link semantics).  If anyone attempts to access them, they will
114	automatically cause the target volume to be mounted (if possible) on that site.
115	
116	Automatically mounted filesystems will be automatically unmounted approximately
117	twenty minutes after they were last used.  Alternatively they can be unmounted
118	directly with the umount() system call.
119	
120	Manually unmounting an AFS volume will cause any idle submounts upon it to be
121	culled first.  If all are culled, then the requested volume will also be
122	unmounted, otherwise error EBUSY will be returned.
123	
124	This can be used by the administrator to attempt to unmount the whole AFS tree
125	mounted on /afs in one go by doing:
126	
127		umount /afs
128	
129	
130	===============
131	PROC FILESYSTEM
132	===============
133	
134	The AFS modules creates a "/proc/fs/afs/" directory and populates it:
135	
136	  (*) A "cells" file that lists cells currently known to the afs module and
137	      their usage counts:
138	
139		[root@andromeda ~]# cat /proc/fs/afs/cells
140		USE NAME
141		  3 cambridge.redhat.com
142	
143	  (*) A directory per cell that contains files that list volume location
144	      servers, volumes, and active servers known within that cell.
145	
146		[root@andromeda ~]# cat /proc/fs/afs/cambridge.redhat.com/servers
147		USE ADDR            STATE
148		  4 172.16.18.91        0
149		[root@andromeda ~]# cat /proc/fs/afs/cambridge.redhat.com/vlservers
150		ADDRESS
151		172.16.18.91
152		[root@andromeda ~]# cat /proc/fs/afs/cambridge.redhat.com/volumes
153		USE STT VLID[0]  VLID[1]  VLID[2]  NAME
154		  1 Val 20000000 20000001 20000002 root.afs
155	
156	
157	=================
158	THE CELL DATABASE
159	=================
160	
161	The filesystem maintains an internal database of all the cells it knows and the
162	IP addresses of the volume location servers for those cells.  The cell to which
163	the system belongs is added to the database when modprobe is performed by the
164	"rootcell=" argument or, if compiled in, using a "kafs.rootcell=" argument on
165	the kernel command line.
166	
167	Further cells can be added by commands similar to the following:
168	
169		echo add CELLNAME VLADDR[:VLADDR][:VLADDR]... >/proc/fs/afs/cells
170		echo add grand.central.org 18.9.48.14:128.2.203.61:130.237.48.87 >/proc/fs/afs/cells
171	
172	No other cell database operations are available at this time.
173	
174	
175	========
176	SECURITY
177	========
178	
179	Secure operations are initiated by acquiring a key using the klog program.  A
180	very primitive klog program is available at:
181	
182		http://people.redhat.com/~dhowells/rxrpc/klog.c
183	
184	This should be compiled by:
185	
186		make klog LDLIBS="-lcrypto -lcrypt -lkrb4 -lkeyutils"
187	
188	And then run as:
189	
190		./klog
191	
192	Assuming it's successful, this adds a key of type RxRPC, named for the service
193	and cell, eg: "afs@<cellname>".  This can be viewed with the keyctl program or
194	by cat'ing /proc/keys:
195	
196		[root@andromeda ~]# keyctl show
197		Session Keyring
198		       -3 --alswrv      0     0  keyring: _ses.3268
199			2 --alswrv      0     0   \_ keyring: _uid.0
200		111416553 --als--v      0     0   \_ rxrpc: afs@CAMBRIDGE.REDHAT.COM
201	
202	Currently the username, realm, password and proposed ticket lifetime are
203	compiled in to the program.
204	
205	It is not required to acquire a key before using AFS facilities, but if one is
206	not acquired then all operations will be governed by the anonymous user parts
207	of the ACLs.
208	
209	If a key is acquired, then all AFS operations, including mounts and automounts,
210	made by a possessor of that key will be secured with that key.
211	
212	If a file is opened with a particular key and then the file descriptor is
213	passed to a process that doesn't have that key (perhaps over an AF_UNIX
214	socket), then the operations on the file will be made with key that was used to
215	open the file.
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.