/[gentoo]/xml/htdocs/doc/en/openafs.xml
Gentoo

Contents of /xml/htdocs/doc/en/openafs.xml

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.15 - (show annotations) (download) (as text)
Thu Sep 9 13:13:06 2004 UTC (9 years, 10 months ago) by swift
Branch: MAIN
Changes since 1.14: +11 -4 lines
File MIME type: application/xml
The partitions are vicep[a-z], not vice[a-z]. Also add a note on a possible error ppl receive quite often

1 <?xml version='1.0' encoding="UTF-8"?>
2 <!-- $Header: /home/cvsroot/gentoo/xml/htdocs/doc/en/openafs.xml,v 1.14 2004/04/11 10:52:16 cam Exp $ -->
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.6</version>
25 <date>September 09, 2004</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
154 <warn>
155 Only use spaces inside the <path>CellServDB</path> file. The client will most
156 likely fail if you use TABs.
157 </warn>
158
159 <p>
160 CellServDB tells your client which server(s) he needs to contact for a
161 specific cell. ThisCell should be quite obvious. Normally you use a name
162 which is unique for your organisation. Your (official) domain might be a
163 good choice.
164 </p>
165 </body>
166 </section>
167 <section>
168 <title>Building the Client</title>
169 <body>
170 <pre>
171 # <i>emerge net-fs/openafs</i>
172 </pre>
173 <p>
174 After successful compilation you're ready to go.
175 </p>
176 </body>
177 </section>
178 <section>
179 <title>Starting afs on startup</title>
180 <body>
181 <p>
182 The following command will create the appropriate links to start your afs client
183 on system startup.
184 </p>
185 <warn>
186 You should always have a running afs server in your domain when trying to start the afs client. You're system won't boot
187 until it gets some timeout if your afs server is down. (and this is quite a long long time)
188 </warn>
189 <pre>
190 # <i>rc-update add afs default</i>
191 </pre>
192 </body>
193 </section>
194 </chapter>
195
196 <chapter>
197 <title>Server Installation</title>
198 <section>
199 <title>Building the Server</title>
200 <body>
201 <p>
202 The following command will install all necessary binaries for setting up a AFS Server
203 <e>and</e> Client.
204 </p>
205 <pre>
206 # <i>emerge net-fs/openafs</i>
207 </pre>
208 </body>
209 </section>
210 <section>
211 <title>Starting AFS Server</title>
212 <body>
213 <p>
214 You need to remove the sample CellServDB and ThisCell file first.
215 </p>
216 <pre>
217 # <i>rm /usr/vice/etc/ThisCell</i>
218 # <i>rm /usr/vice/etc/CellServDB</i>
219 </pre>
220 <p>
221 Next you will run the <b>bosserver</b> command to initialize the Basic OverSeer (BOS)
222 Server, which monitors and controls other AFS server processes on its server
223 machine. Think of it as init for the system. Include the <b>-noauth</b>
224 flag to disable authorization checking, since you haven't added the admin user yet.
225 </p>
226 <warn>
227 Disabling authorization checking gravely compromises cell security.
228 You must complete all subsequent steps in one uninterrupted pass
229 and must not leave the machine unattended until you restart the BOS Server with
230 authorization checking enabled. Well this is what the AFS documentation says :)
231 </warn>
232 <pre>
233 # <i>/usr/afs/bin/bosserver -noauth &amp;</i>
234 </pre>
235 <p>
236 Verify that the BOS Server created <path>/usr/vice/etc/CellServDB</path>
237 and <path>/usr/vice/etc/ThisCell</path>
238 </p>
239 <pre>
240 # <i>ls -al /usr/vice/etc/</i>
241 -rw-r--r-- 1 root root 41 Jun 4 22:21 CellServDB
242 -rw-r--r-- 1 root root 7 Jun 4 22:21 ThisCell
243 </pre>
244
245 </body>
246 </section>
247 <section>
248 <title>Defining Cell Name and Membership for Server Process</title>
249 <body>
250 <p>
251 Now assign your cells name.
252 </p>
253 <impo>There are some restrictions on the name format.
254 Two of the most important restrictions are that the name
255 cannot include uppercase letters or more than 64 characters. Remember that
256 your cell name will show up under <path>/afs</path>, so you might want to choose
257 a short one.</impo>
258 <note>In the following and every instruction in this guide, for the &lt;server name&gt;
259 argument substitute the full-qualified hostname
260 (such as <b>afs.gentoo.org</b>) of the machine you are installing.
261 For the &lt;cell name&gt;
262 argument substitute your cell's complete name (such as <b>gentoo</b>)</note>
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 &lt;server name&gt; &lt;cell name&gt; -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
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 <pre>
302 # <i>/usr/afs/bin/bos create &lt;server name&gt; kaserver simple
303 /usr/afs/bin/kaserver -cell &lt;cell name&gt; -noauth</i>
304 # <i>/usr/afs/bin/bos create &lt;server name&gt; buserver simple
305 /usr/afs/bin/buserver -cell &lt;cell name&gt; -noauth</i>
306 # <i>/usr/afs/bin/bos create &lt;server name&gt; ptserver simple
307 /usr/afs/bin/ptserver -cell &lt;cell name&gt; -noauth</i>
308 # <i>/usr/afs/bin/bos create &lt;server name&gt; vlserver simple
309 /usr/afs/bin/vlserver -cell &lt;cell name&gt; -noauth</i>
310 </pre>
311 <p>
312 You can verify that all servers are running with the <b>bos status</b> command:
313 </p>
314 <pre>
315 # <i>/usr/afs/bin/bos status &lt;server name&gt; -noauth</i>
316 Instance kaserver, currently running normally.
317 Instance buserver, currently running normally.
318 Instance ptserver, currently running normally.
319 Instance vlserver, currently running normally.
320 </pre>
321
322 </body>
323 </section>
324 <section>
325 <title>Initializing Cell Security</title>
326 <body>
327 <p>
328 Now we'll initialize the cell's security mechanisms. We'll begin by creating the
329 following two initial entries in the
330 Authentication Database: The main administrative account, called <b>admin</b> by
331 convention and an entry for
332 the AFS server processes, called <b>afs</b>. No user logs in under the
333 identity <b>afs</b>, but the Authentication
334 Server's Ticket Granting Service (TGS) module uses the account
335 to encrypt the server tickets that it grants to AFS clients. This sounds
336 pretty much like Kerberos :)
337 </p>
338 <p>
339 Enter <b>kas</b> interactive mode
340 </p>
341 <pre>
342 # <i>/usr/afs/bin/kas -cell &lt;cell name&gt; -noauth</i>
343 ka&gt; <i>create afs</i>
344 initial_password:
345 Verifying, please re-enter initial_password:
346 ka&gt; <i>create admin</i>
347 initial_password:
348 Verifying, please re-enter initial_password:
349 ka&gt; <i>examine afs</i>
350
351 User data for afs
352 key (0) cksum is 2651715259, last cpw: Mon Jun 4 20:49:30 2001
353 password will never expire.
354 An unlimited number of unsuccessful authentications is permitted.
355 entry never expires. Max ticket lifetime 100.00 hours.
356 last mod on Mon Jun 4 20:49:30 2001 by $lt;none&gt;
357 permit password reuse
358 ka&gt; <i>setfields admin -flags admin</i>
359 ka&gt; <i>examine admin</i>
360
361 User data for admin (ADMIN)
362 key (0) cksum is 2651715259, last cpw: Mon Jun 4 20:49:59 2001
363 password will never expire.
364 An unlimited number of unsuccessful authentications is permitted.
365 entry never expires. Max ticket lifetime 25.00 hours.
366 last mod on Mon Jun 4 20:51:10 2001 by $lt;none&gt;
367 permit password reuse
368 ka&gt;
369 </pre>
370 <p>
371 Run the <b>bos adduser</b> command, to add the <b>admin</b> user to
372 the <path>/usr/afs/etc/UserList</path>.
373 </p>
374 <pre>
375 # <i>/usr/afs/bin/bos adduser &lt;server name&gt; admin -cell &lt;cell name&gt; -noauth</i>
376 </pre>
377 <p>
378 Issue the <b>bos addkey</b> command to define the AFS Server
379 encryption key in <path>/usr/afs/etc/KeyFile</path>
380 </p>
381 <note>
382 If asked for the input key, give the password you entered when creating
383 the afs entry with <b>kas</b>
384 </note>
385 <pre>
386 # <i>/usr/afs/bin/bos addkey &lt;server name&gt; -kvno 0 -cell &lt;cell name&gt; -noauth</i>
387 input key:
388 Retype input key:
389 </pre>
390 <p>
391 Issue the <b>pts createuser</b> command to create a Protection Database
392 entry for the admin user
393 </p>
394 <note>
395 By default, the Protection Server assigns AFS UID 1 to the <b>admin</b> user, because
396 it is the first user
397 entry you are creating. If the local password file (/etc/passwd or equivalent)
398 already has an entry for
399 <b>admin</b> that assigns a different UID use the <b>-id</b> argument
400 to create matching UID's
401 </note>
402 <pre>
403 # <i>/usr/afs/bin/pts createuser -name admin -cell &lt;cell name&gt; [-id &lt;AFS UID&gt;] -noauth</i>
404 </pre>
405 <p>
406 Issue the <b>pts adduser</b> command to make the <b>admin</b> user a member
407 of the system:administrators group,
408 and the <b>pts membership</b> command to verify the new membership
409 </p>
410 <pre>
411 # <i>/usr/afs/bin/pts adduser admin system:administrators -cell &lt;cell name&gt; -noauth</i>
412 # <i>/usr/afs/bin/pts membership admin -cell &lt;cell name&gt; -noauth</i>
413 Groups admin (id: 1) is a member of:
414 system:administrators
415 </pre>
416 <p>
417 Restart all AFS Server processes
418 </p>
419 <pre>
420 # <i>/usr/afs/bin/bos restart &lt;server name&gt; -all -cell &lt;cell name&gt; -noauth</i>
421 </pre>
422 </body>
423 </section>
424 <section>
425 <title>Starting the File Server, Volume Server and Salvager</title>
426 <body>
427 <p>
428 Start the <b>fs</b> process, which consists of the File Server, Volume Server and Salvager (fileserver,
429 volserver and salvager processes).
430 </p>
431 <pre>
432 # <i>/usr/afs/bin/bos create &lt;server name&gt; fs fs /usr/afs/bin/fileserver
433 /usr/afs/bin/volserver
434 /usr/afs/bin/salvager
435 -cell &lt;cell name&gt; -noauth</i>
436 </pre>
437 <p>
438 Verify that all processes are running
439 </p>
440 <pre>
441 # <i>/usr/afs/bin/bos status &lt;server name&gt; -long -noauth</i>
442 Instance kaserver, (type is simple) currently running normally.
443 Process last started at Mon Jun 4 21:07:17 2001 (2 proc starts)
444 Last exit at Mon Jun 4 21:07:17 2001
445 Command 1 is '/usr/afs/bin/kaserver'
446
447 Instance buserver, (type is simple) currently running normally.
448 Process last started at Mon Jun 4 21:07:17 2001 (2 proc starts)
449 Last exit at Mon Jun 4 21:07:17 2001
450 Command 1 is '/usr/afs/bin/buserver'
451
452 Instance ptserver, (type is simple) currently running normally.
453 Process last started at Mon Jun 4 21:07:17 2001 (2 proc starts)
454 Last exit at Mon Jun 4 21:07:17 2001
455 Command 1 is '/usr/afs/bin/ptserver'
456
457 Instance vlserver, (type is simple) currently running normally.
458 Process last started at Mon Jun 4 21:07:17 2001 (2 proc starts)
459 Last exit at Mon Jun 4 21:07:17 2001
460 Command 1 is '/usr/afs/bin/vlserver'
461
462 Instance fs, (type is fs) currently running normally.
463 Auxiliary status is: file server running.
464 Process last started at Mon Jun 4 21:09:30 2001 (2 proc starts)
465 Command 1 is '/usr/afs/bin/fileserver'
466 Command 2 is '/usr/afs/bin/volserver'
467 Command 3 is '/usr/afs/bin/salvager'
468 </pre>
469 <p>
470 Your next action depends on whether you have ever run AFS file server machines
471 in the cell:
472 </p>
473 <p>
474 If you are installing the first AFS Server ever in the cell create the
475 first AFS volume, <b>root.afs</b>
476 </p>
477 <note>
478 For the partition name argument, substitute the name of one of the machine's
479 AFS Server partitions. By convention
480 these partitions are named <path>/vicepx</path>, where x is in the range of a-z.
481 </note>
482 <pre>
483 # <i>/usr/afs/bin/vos create &lt;server name&gt;
484 &lt;partition name&gt; root.afs
485 -cell &lt;cell name&gt; -noauth</i>
486 </pre>
487 <p>
488 If there are existing AFS file server machines and volumes in the cell
489 issue the <b>vos sncvldb</b> and <b>vos
490 syncserv</b> commands to synchronize the VLDB (Volume Location Database) with
491 the actual state of volumes on the local machine. This will copy all necessary data to your
492 new server.
493 </p>
494 <p>
495 If the command fails with the message "partition /vicepa does not exist on
496 the server" ensure that the partition is mounted before runningt OpenAFS
497 servers, or mount the directory and restart the processes using
498 <c>/usr/afs/bin/bos restart &lt;server name&gt; -all -cell &lt;cell
499 name&gt; -noauth</c>.
500 </p>
501 <pre>
502 # <i>/usr/afs/bin/vos syncvldb &lt;server name&gt; -cell &lt;cell name&gt; -verbose -noauth</i>
503 # <i>/usr/afs/bin/vos syncserv &lt;server name&gt; -cell &lt;cell name&gt; -verbose -noauth</i>
504 </pre>
505 </body>
506 </section>
507 <section>
508 <title>Starting the Server Portion of the Update Server</title>
509 <body>
510 <pre>
511 # <i>/usr/afs/bin/bos create &lt;server name&gt;
512 upserver simple "/usr/afs/bin/upserver
513 -crypt /usr/afs/etc -clear /usr/afs/bin"
514 -cell &lt;cell name&gt; -noauth</i>
515 </pre>
516 </body>
517 </section>
518 <section>
519 <title>Configuring the Top Level of the AFS filespace</title>
520 <body>
521 <p>
522 First you need to set some acl's, so that any user can lookup <path>/afs</path>.
523 </p>
524 <pre>
525 # <i>/usr/afs/bin/fs setacl /afs system:anyuser rl</i>
526 </pre>
527 <p>
528 Then you need to create the root volume, mount it readonly on <path>/afs/&lt;cell name&gt;</path> and read/write
529 on <path>/afs/.&lt;cell name&gt;</path>
530 </p>
531 <pre>
532 # <i>/usr/afs/bin/vos create &lt;server name&gt;&lt;partition name&gt; root.cell</i>
533 # <i>/usr/afs/bin/fs mkmount /afs/&lt;cell name&gt; root.cell </i>
534 # <i>/usr/afs/bin/fs setacl /afs/&lt;cell name&gt; system:anyuser rl</i>
535 # <i>/usr/afs/bin/fs mkmount /afs/.&lt;cell name&gt; root.cell -rw</i>
536 </pre>
537 <p>
538 Finally you're done !!! You should now have a working AFS file server
539 on your local network. Time to get a big
540 cup of coffee and print out the AFS documentation !!!
541 </p>
542 <note>
543 It is very important for the AFS server to function properly, that all system
544 clock's are synchronized.
545 This is best
546 accomplished by installing a ntp server on one machine (e.g. the AFS server)
547 and synchronize all client clock's
548 with the ntp client. This can also be done by the afs client.
549 </note>
550 </body>
551 </section>
552
553 </chapter>
554
555 <chapter>
556 <title>Basic Administration</title>
557 <section>
558 <title></title>
559 <body>
560 <p>To be done ... For now read the AFS Documentation :)</p>
561 </body>
562 </section>
563 </chapter>
564 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20