1 |
<?xml version='1.0' encoding="UTF-8"?> |
2 |
<!-- $Header$ --> |
3 |
|
4 |
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> |
5 |
|
6 |
<guide link = "/doc/en/openafs.xml"> |
7 |
<title>Gentoo Linux OpenAFS Guide</title> |
8 |
<author title="Editor"> |
9 |
<mail link="darks@gentoo.org">Holger Brueckner</mail> |
10 |
</author> |
11 |
<author title="Editor"> |
12 |
<mail link="bennyc@gentoo.org">Benny Chuang</mail> |
13 |
</author> |
14 |
<author title="Editor"> |
15 |
<mail link="blubber@gentoo.org">Tiemo Kieft</mail> |
16 |
</author> |
17 |
|
18 |
<abstract> |
19 |
This guide shows you how to install a openafs server and client on gentoo linux |
20 |
</abstract> |
21 |
|
22 |
<license/> |
23 |
|
24 |
<version>0.4</version> |
25 |
<date>November 7, 2003</date> |
26 |
|
27 |
<chapter> |
28 |
<title>Overview</title> |
29 |
<section> |
30 |
<title>About this Document</title> |
31 |
<body> |
32 |
<p>This document provides you with all neccessary steps to install an openafs server on Gentoo Linux. |
33 |
Parts of this document are taken from the AFS FAQ and IBM's Quick Beginnings guide on AFS. Well, never reinvent |
34 |
the wheel :)</p> |
35 |
</body> |
36 |
</section> |
37 |
<section> |
38 |
<title>What is AFS ?</title> |
39 |
<body> |
40 |
|
41 |
<p> |
42 |
AFS is a distributed filesystem that enables co-operating hosts |
43 |
(clients and servers) to efficiently share filesystem resources |
44 |
across both local area and wide area networks. Clients hold a |
45 |
cache for often used objects (files), to get quicker |
46 |
access to them. |
47 |
</p> |
48 |
<p> |
49 |
AFS is based on a distributed file system originally developed |
50 |
at the Information Technology Center at Carnegie-Mellon University |
51 |
that was called the "Andrew File System". "Andrew" was the name of the research project at CMU - honouring the |
52 |
founders of the University. Once Transarc was formed and AFS became a |
53 |
product, the "Andrew" was dropped to indicate that AFS had gone beyond |
54 |
the Andrew research project and had become a supported, product quality |
55 |
filesystem. However, there were a number of existing cells that rooted |
56 |
their filesystem as /afs. At the time, changing the root of the filesystem |
57 |
was a non-trivial undertaking. So, to save the early AFS sites from having |
58 |
to rename their filesystem, AFS remained as the name and filesystem root. |
59 |
</p> |
60 |
</body> |
61 |
</section> |
62 |
<section> |
63 |
<title>What is an AFS cell ?</title> |
64 |
<body> |
65 |
<p>An AFS cell is a collection of servers grouped together administratively |
66 |
and presenting a single, cohesive filesystem. Typically, an AFS cell is a set of |
67 |
hosts that use the same Internet domain name (like for example gentoo.org) |
68 |
Users log into AFS client workstations which request information and files |
69 |
from the cell's servers on behalf of the users. Users won't know on which server |
70 |
a file which they are accessing, is located. They even won't notice if a server |
71 |
will be located to another room, since every volume can be replicated and moved |
72 |
to another server without any user noticing. The files are always accessable. |
73 |
Well it's like NFS on steroids :) |
74 |
</p> |
75 |
</body> |
76 |
</section> |
77 |
<section> |
78 |
<title>What are the benefits of using AFS ?</title> |
79 |
<body> |
80 |
<p>The main strengths of AFS are its: |
81 |
|
82 |
caching facility (on client side, typically 100M to 1GB), |
83 |
security features (Kerberos 4 based, access control lists), |
84 |
simplicity of addressing (you just have one filesystem), |
85 |
scalability (add further servers to your cell as needed), |
86 |
communications protocol. |
87 |
</p> |
88 |
</body> |
89 |
</section> |
90 |
<section> |
91 |
<title>Where can i get more information ?</title> |
92 |
<body> |
93 |
<p> |
94 |
Read the <uri link="http://www.angelfire.com/hi/plutonic/afs-faq.html">AFS FAQ</uri>. |
95 |
</p> |
96 |
<p> |
97 |
Openafs main page is at <uri link="http://www.openafs.org">www.openafs.org</uri>. |
98 |
</p> |
99 |
<p> |
100 |
AFS was originally developed by Transarc which is now owned by IBM. |
101 |
You can find some information about AFS on |
102 |
<uri link="http://www.transarc.ibm.com/Product/EFS/AFS/index.html">Transarcs Webpage</uri> |
103 |
</p> |
104 |
</body> |
105 |
</section> |
106 |
|
107 |
</chapter> |
108 |
|
109 |
<chapter> |
110 |
<title>Documentation</title> |
111 |
<section> |
112 |
<title>Getting AFS Documentation</title> |
113 |
<body> |
114 |
<p> |
115 |
You can get the original IBM AFS Documentation. It is very well written and you |
116 |
really want |
117 |
read it if it is up to you to administer a AFS Server. |
118 |
</p> |
119 |
<pre> |
120 |
# <i>emerge app-doc/afsdoc</i> |
121 |
</pre> |
122 |
</body> |
123 |
</section> |
124 |
</chapter> |
125 |
|
126 |
<chapter> |
127 |
<title>Client Installation</title> |
128 |
<section> |
129 |
<title>Preliminary Work</title> |
130 |
<body> |
131 |
<note> |
132 |
All commands should be written in one line !! In this document they are |
133 |
sometimes wrapped to two lines to make them easier to read. |
134 |
</note> |
135 |
<note> |
136 |
Unfortunately the AFS Client needs a ext2 partiton for it's cache to run |
137 |
correctly, because there are some locking issues with reiserfs. You need to |
138 |
create a ext2 partition of approx. 200MB (more won't hurt) and mount it to |
139 |
<path>/usr/vice/cache</path> |
140 |
</note> |
141 |
<p> |
142 |
You should adjust the two files CellServDB and ThisCell before you build the |
143 |
afs client. (These files are in <path>/usr/portage/net-fs/openafs/files</path>) |
144 |
</p> |
145 |
<pre> |
146 |
CellServDB: |
147 |
>netlabs #Cell name |
148 |
10.0.0.1 #storage |
149 |
|
150 |
ThisCell: |
151 |
netlabs |
152 |
</pre> |
153 |
<p> |
154 |
CellServDB tells your client which server(s) he needs to contact for a |
155 |
specific cell. ThisCell should be quite obvious. Normally you use a name |
156 |
which is unique for your organisation. Your (official) domain might be a |
157 |
good choice. |
158 |
</p> |
159 |
</body> |
160 |
</section> |
161 |
<section> |
162 |
<title>Building the Client</title> |
163 |
<body> |
164 |
<pre> |
165 |
# <i>emerge net-fs/openafs</i> |
166 |
</pre> |
167 |
<p> |
168 |
After successful compilation you're ready to go. |
169 |
</p> |
170 |
</body> |
171 |
</section> |
172 |
<section> |
173 |
<title>Starting afs on startup</title> |
174 |
<body> |
175 |
<p> |
176 |
The following command will create the appropriate links to start your afs client |
177 |
on system startup. |
178 |
</p> |
179 |
<warn> |
180 |
You should always have a running afs server in your domain when trying to start the afs client. You're system won't boot |
181 |
until it gets some timeout if your afs server is down. (and this is quite a long long time) |
182 |
</warn> |
183 |
<pre> |
184 |
# <i>rc-update add afs default</i> |
185 |
</pre> |
186 |
</body> |
187 |
</section> |
188 |
</chapter> |
189 |
|
190 |
<chapter> |
191 |
<title>Server Installation</title> |
192 |
<section> |
193 |
<title>Building the Server</title> |
194 |
<body> |
195 |
<p> |
196 |
The following command will install all necessary binaries for setting up a AFS Server |
197 |
<i>and</i> Client |
198 |
</p> |
199 |
<pre> |
200 |
# <i>emerge net-fs/openafs</i> |
201 |
</pre> |
202 |
</body> |
203 |
</section> |
204 |
<section> |
205 |
<title>Starting AFS Server</title> |
206 |
<body> |
207 |
<p> |
208 |
You need to remove the sample CellServDB and ThisCell file first. |
209 |
</p> |
210 |
<pre> |
211 |
# <i>rm /usr/vice/etc/ThisCell</i> |
212 |
# <i>rm /usr/vice/etc/CellServDB</i> |
213 |
</pre> |
214 |
<p> |
215 |
Next you will run the <b>bosserver</b> command to initialize the Basic OverSeer (BOS) |
216 |
Server, which monitors and controls other AFS server processes on its server |
217 |
machine. Think of it as init for the system. Include the <b>-noauth</b> |
218 |
flag to disable authorization checking, since you haven't added the admin user yet. |
219 |
</p> |
220 |
<p> |
221 |
<warn> |
222 |
Disabling authorization checking gravely compromises cell security. |
223 |
You must complete all subsequent steps in one uninterrupted pass |
224 |
and must not leave the machine unattended until you restart the BOS Server with |
225 |
authorization checking enabled. Well this is what the AFS documentation says :) |
226 |
</warn> |
227 |
</p> |
228 |
<pre> |
229 |
# <i>/usr/afs/bin/bosserver -noauth &</i> |
230 |
</pre> |
231 |
<p> |
232 |
Verify that the BOS Server created <path>/usr/vice/etc/CellServDB</path> |
233 |
and <path>/usr/vice/etc/ThisCell</path> |
234 |
</p> |
235 |
<pre> |
236 |
# <i>ls -al /usr/vice/etc/</i> |
237 |
-rw-r--r-- 1 root root 41 Jun 4 22:21 CellServDB |
238 |
-rw-r--r-- 1 root root 7 Jun 4 22:21 ThisCell |
239 |
</pre> |
240 |
|
241 |
</body> |
242 |
</section> |
243 |
<section> |
244 |
<title>Defining Cell Name and Membership for Server Process</title> |
245 |
<body> |
246 |
<p> |
247 |
Now assign your cells name. |
248 |
</p> |
249 |
<p> |
250 |
<impo>There are some restrictions on the name format. |
251 |
Two of the most important restrictions are that the name |
252 |
cannot include uppercase letters or more than 64 characters. Remember that |
253 |
your cell name will show up under <path>/afs</path>, so you might want to choose |
254 |
a short one.</impo> |
255 |
</p> |
256 |
<p> |
257 |
<note>In the following and every instruction in this guide, for the <i><server name></i> |
258 |
argument substitute the full-qualified hostname |
259 |
(such as <b>afs.gentoo.org</b>) of the machine you are installing. |
260 |
For the <i><cell name></i> |
261 |
argument substitute your cell's complete name (such as <b>gentoo</b>)</note> |
262 |
</p> |
263 |
<p> |
264 |
Run the <b>bos setcellname</b> command to set the cell name: |
265 |
</p> |
266 |
<pre> |
267 |
# <i>/usr/afs/bin/bos setcellname <server name> <cell name> -noauth</i> |
268 |
</pre> |
269 |
</body> |
270 |
</section> |
271 |
<section> |
272 |
<title>Starting the Database Server Process</title> |
273 |
<body><p> |
274 |
Next use the <b>bos create</b> command to create entries for the four database |
275 |
server processes in the |
276 |
<path>/usr/afs/local/BosConfig</path> file. The four processes run on database |
277 |
server machines only. |
278 |
</p> |
279 |
<p> |
280 |
<table> |
281 |
<tr> |
282 |
<ti>kaserver</ti> |
283 |
<ti>The Authentication Server maintains the Authentication Database. |
284 |
This can be replaced by a Kerberos 5 daemon. If anybody want's to try that |
285 |
feel free to update this document :)</ti> |
286 |
</tr> |
287 |
<tr> |
288 |
<ti>buserver</ti> |
289 |
<ti>The Backup Server maintains the Backup Database</ti> |
290 |
</tr> |
291 |
<tr> |
292 |
<ti>ptserver</ti> |
293 |
<ti>The Protection Server maintains the Protection Database</ti> |
294 |
</tr> |
295 |
<tr> |
296 |
<ti>vlserver</ti> |
297 |
<ti>The Volume Location Server maintains the Volume Location Database (VLDB). |
298 |
Very important :)</ti> |
299 |
</tr> |
300 |
</table> |
301 |
</p> |
302 |
<pre> |
303 |
# <i>/usr/afs/bin/bos create <server name> kaserver simple |
304 |
/usr/afs/bin/kaserver -cell <cell name> -noauth</i> |
305 |
# <i>/usr/afs/bin/bos create <server name> buserver simple |
306 |
/usr/afs/bin/buserver -cell <cell name> -noauth</i> |
307 |
# <i>/usr/afs/bin/bos create <server name> ptserver simple |
308 |
/usr/afs/bin/ptserver -cell <cell name> -noauth</i> |
309 |
# <i>/usr/afs/bin/bos create <server name> vlserver simple |
310 |
/usr/afs/bin/vlserver -cell <cell name> -noauth</i> |
311 |
</pre> |
312 |
<p> |
313 |
You can verify that all servers are running with the <b>bos status</b> command: |
314 |
</p> |
315 |
<pre> |
316 |
# <i>/usr/afs/bin/bos status <server name> -noauth</i> |
317 |
Instance kaserver, currently running normally. |
318 |
Instance buserver, currently running normally. |
319 |
Instance ptserver, currently running normally. |
320 |
Instance vlserver, currently running normally. |
321 |
</pre> |
322 |
|
323 |
</body> |
324 |
</section> |
325 |
<section> |
326 |
<title>Initializing Cell Security</title> |
327 |
<body> |
328 |
<p> |
329 |
Now we'll initialize the cell's security mechanisms. We'll begin by creating the |
330 |
following two initial entries in the |
331 |
Authentication Database: The main administrative account, called <b>admin</b> by |
332 |
convention and an entry for |
333 |
the AFS server processes, called <b>afs</b>. No user logs in under the |
334 |
identity <b>afs</b>, but the Authentication |
335 |
Server's Ticket Granting Service (TGS) module uses the account |
336 |
to encrypt the server tickets that it grants to AFS clients. This sounds |
337 |
pretty much like Kerberos :) |
338 |
</p> |
339 |
<p> |
340 |
Enter <b>kas</b> interactive mode |
341 |
</p> |
342 |
<pre> |
343 |
# <i>/usr/afs/bin/kas -cell <cell name> -noauth</i> |
344 |
ka> <i>create afs</i> |
345 |
initial_password: |
346 |
Verifying, please re-enter initial_password: |
347 |
ka> <i>create admin</i> |
348 |
initial_password: |
349 |
Verifying, please re-enter initial_password: |
350 |
ka> <i>examine afs</i> |
351 |
|
352 |
User data for afs |
353 |
key (0) cksum is 2651715259, last cpw: Mon Jun 4 20:49:30 2001 |
354 |
password will never expire. |
355 |
An unlimited number of unsuccessful authentications is permitted. |
356 |
entry never expires. Max ticket lifetime 100.00 hours. |
357 |
last mod on Mon Jun 4 20:49:30 2001 by $lt;none> |
358 |
permit password reuse |
359 |
ka> <i>setfields admin -flags admin</i> |
360 |
ka> <i>examine admin</i> |
361 |
|
362 |
User data for admin (ADMIN) |
363 |
key (0) cksum is 2651715259, last cpw: Mon Jun 4 20:49:59 2001 |
364 |
password will never expire. |
365 |
An unlimited number of unsuccessful authentications is permitted. |
366 |
entry never expires. Max ticket lifetime 25.00 hours. |
367 |
last mod on Mon Jun 4 20:51:10 2001 by $lt;none> |
368 |
permit password reuse |
369 |
ka> |
370 |
</pre> |
371 |
<p> |
372 |
Run the <b>bos adduser</b> command, to add the <b>admin</b> user to |
373 |
the <path>/usr/afs/etc/UserList</path>. |
374 |
</p> |
375 |
<pre> |
376 |
# <i>/usr/afs/bin/bos adduser <server name> admin -cell <cell name> -noauth</i> |
377 |
</pre> |
378 |
<p> |
379 |
Issue the <b>bos addkey</b> command to define the AFS Server |
380 |
encryption key in <path>/usr/afs/etc/KeyFile</path> |
381 |
</p> |
382 |
<note> |
383 |
If asked for the input key, give the password you entered when creating |
384 |
the afs entry with <b>kas</b> |
385 |
</note> |
386 |
<pre> |
387 |
# <i>/usr/afs/bin/bos addkey <server name> -kvno 0 -cell <cell name> -noauth</i> |
388 |
input key: |
389 |
Retype input key: |
390 |
</pre> |
391 |
<p> |
392 |
Issue the <b>pts createuser</b> command to create a Protection Database |
393 |
entry for the admin user |
394 |
</p> |
395 |
<note> |
396 |
By default, the Protection Server assigns AFS UID 1 to the <b>admin</b> user, because |
397 |
it is the first user |
398 |
entry you are creating. If the local password file (/etc/passwd or equivalent) |
399 |
already has an entry for |
400 |
<b>admin</b> that assigns a different UID use the <b>-id</b> argument |
401 |
to create matching UID's |
402 |
</note> |
403 |
<pre> |
404 |
# <i>/usr/afs/bin/pts createuser -name admin -cell <cell name> [-id <AFS UID>] -noauth</i> |
405 |
</pre> |
406 |
<p> |
407 |
Issue the <b>pts adduser</b> command to make the <b>admin</b> user a member |
408 |
of the system:administrators group, |
409 |
and the <b>pts membership</b> command to verify the new membership |
410 |
</p> |
411 |
<pre> |
412 |
# <i>/usr/afs/bin/pts adduser admin system:administrators -cell <cell name> -noauth</i> |
413 |
# <i>/usr/afs/bin/pts membership admin -cell <cell name> -noauth</i> |
414 |
Groups admin (id: 1) is a member of: |
415 |
system:administrators |
416 |
</pre> |
417 |
<p> |
418 |
Restart all AFS Server processes |
419 |
</p> |
420 |
<pre> |
421 |
# <i>/usr/afs/bin/bos restart <server name> -all -cell <cell name> -noauth</i> |
422 |
</pre> |
423 |
</body> |
424 |
</section> |
425 |
<section> |
426 |
<title>Starting the File Server, Volume Server and Salvager</title> |
427 |
<body> |
428 |
<p> |
429 |
Start the <b>fs</b> process, which consists of the File Server, Volume Server and Salvager (fileserver, |
430 |
volserver and salvager processes). |
431 |
</p> |
432 |
<pre> |
433 |
# <i>/usr/afs/bin/bos create <server name> fs fs /usr/afs/bin/fileserver |
434 |
/usr/afs/bin/volserver |
435 |
/usr/afs/bin/salvager |
436 |
-cell <cell name> -noauth</i> |
437 |
</pre> |
438 |
<p> |
439 |
Verify that all processes are running |
440 |
</p> |
441 |
<pre> |
442 |
# <i>/usr/afs/bin/bos status <server name> -long -noauth</i> |
443 |
Instance kaserver, (type is simple) currently running normally. |
444 |
Process last started at Mon Jun 4 21:07:17 2001 (2 proc starts) |
445 |
Last exit at Mon Jun 4 21:07:17 2001 |
446 |
Command 1 is '/usr/afs/bin/kaserver' |
447 |
|
448 |
Instance buserver, (type is simple) currently running normally. |
449 |
Process last started at Mon Jun 4 21:07:17 2001 (2 proc starts) |
450 |
Last exit at Mon Jun 4 21:07:17 2001 |
451 |
Command 1 is '/usr/afs/bin/buserver' |
452 |
|
453 |
Instance ptserver, (type is simple) currently running normally. |
454 |
Process last started at Mon Jun 4 21:07:17 2001 (2 proc starts) |
455 |
Last exit at Mon Jun 4 21:07:17 2001 |
456 |
Command 1 is '/usr/afs/bin/ptserver' |
457 |
|
458 |
Instance vlserver, (type is simple) currently running normally. |
459 |
Process last started at Mon Jun 4 21:07:17 2001 (2 proc starts) |
460 |
Last exit at Mon Jun 4 21:07:17 2001 |
461 |
Command 1 is '/usr/afs/bin/vlserver' |
462 |
|
463 |
Instance fs, (type is fs) currently running normally. |
464 |
Auxiliary status is: file server running. |
465 |
Process last started at Mon Jun 4 21:09:30 2001 (2 proc starts) |
466 |
Command 1 is '/usr/afs/bin/fileserver' |
467 |
Command 2 is '/usr/afs/bin/volserver' |
468 |
Command 3 is '/usr/afs/bin/salvager' |
469 |
</pre> |
470 |
<p> |
471 |
Your next action depends on whether you have ever run AFS file server machines |
472 |
in the cell: |
473 |
</p> |
474 |
<p> |
475 |
If you are installing the first AFS Server ever in the cell create the |
476 |
first AFS volume, <b>root.afs</b> |
477 |
</p> |
478 |
<note> |
479 |
For the partition name argument, substitute the name of one of the machine's |
480 |
AFS Server partitions. By convention |
481 |
these partitions are named <path>/vicex</path>, where x is in the range of a-z. |
482 |
</note> |
483 |
<pre> |
484 |
# <i>/usr/afs/bin/vos create <server name> |
485 |
<partition name> root.afs |
486 |
-cell <cell name> -noauth</i> |
487 |
</pre> |
488 |
<p> |
489 |
If there are existing AFS file server machines and volumes in the cell |
490 |
issue the <b>vos sncvldb</b> and <b>vos |
491 |
syncserv</b> commands to synchronize the VLDB (Volume Location Database) with |
492 |
the actual state of volumes on the local machine. This will copy all necessary data to your |
493 |
new server. |
494 |
</p> |
495 |
<pre> |
496 |
# <i>/usr/afs/bin/vos syncvldb <server name> -cell <cell name> -verbose -noauth</i> |
497 |
# <i>/usr/afs/bin/vos syncserv <server name> -cell <cell name> -verbose -noauth</i> |
498 |
</pre> |
499 |
</body> |
500 |
</section> |
501 |
<section> |
502 |
<title>Starting the Server Portion of the Update Server</title> |
503 |
<body> |
504 |
<pre> |
505 |
# <i>/usr/afs/bin/bos create <server name> |
506 |
upserver simple "/usr/afs/bin/upserver |
507 |
-crypt /usr/afs/etc -clear /usr/afs/bin" |
508 |
-cell <cell name> -noauth</i> |
509 |
</pre> |
510 |
</body> |
511 |
</section> |
512 |
<section> |
513 |
<title>Configuring the Top Level of the AFS filespace</title> |
514 |
<body> |
515 |
<p> |
516 |
First you need to set some acl's, so that any user can lookup <path>/afs</path>. |
517 |
</p> |
518 |
<pre> |
519 |
# <i>/usr/afs/bin/fs setacl /afs system:anyuser rl</i> |
520 |
</pre> |
521 |
<p> |
522 |
Then you need to create the root volume, mount it readonly on <path>/afs/<cell name></path> and read/write |
523 |
on <path>/afs/.<cell name></path> |
524 |
<pre> |
525 |
# <i>/usr/afs/bin/vos create <server name><partition name> root.cell</i> |
526 |
# <i>/usr/afs/bin/fs mkmount /afs/<cell name> root.cell </i> |
527 |
# <i>/usr/afs/bin/fs setacl /afs/<cell name> system:anyuser rl</i> |
528 |
# <i>/usr/afs/bin/fs mkmount /afs/.<cell name> root.cell -rw</i> |
529 |
</pre> |
530 |
</p> |
531 |
<p> |
532 |
Finally you're done !!! You should now have a working AFS file server |
533 |
on your local network. Time to get a big |
534 |
cup of coffee and print out the AFS documentation !!! |
535 |
</p> |
536 |
<note> |
537 |
It is very important for the AFS server to function properly, that all system |
538 |
clock's are synchronized. |
539 |
This is best |
540 |
accomplished by installing a ntp server on one machine (e.g. the AFS server) |
541 |
and synchronize all client clock's |
542 |
with the ntp client. This can also be done by the afs client. |
543 |
</note> |
544 |
</body> |
545 |
</section> |
546 |
|
547 |
</chapter> |
548 |
|
549 |
<chapter> |
550 |
<title>Basic Administration</title> |
551 |
<section> |
552 |
<title></title> |
553 |
<body> |
554 |
<p>To be done ... For now read the AFS Documentation :)</p> |
555 |
</body> |
556 |
</section> |
557 |
</chapter> |
558 |
</guide> |