/[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.9 - (show annotations) (download) (as text)
Tue Sep 30 08:43:16 2003 UTC (10 years, 10 months ago) by swift
Branch: MAIN
Changes since 1.8: +4 -2 lines
File MIME type: application/xml
Add license information

1 <?xml version='1.0' encoding="UTF-8"?>
2
3 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
4
5 <guide link = "/doc/en/openafs.xml">
6 <title>Gentoo Linux OpenAFS Guide</title>
7 <author title="Editor">
8 <mail link="darks@gentoo.org">Holger Brueckner</mail>
9 </author>
10 <author title="Editor">
11 <mail link="bennyc@gentoo.org">Benny Chuang</mail>
12 </author>
13
14 <abstract>
15 This guide shows you how to install a openafs server and client on gentoo linux
16 </abstract>
17
18 <license/>
19
20 <version>0.3</version>
21 <date>September 30, 2003</date>
22
23 <chapter>
24 <title>Overview</title>
25 <section>
26 <title>About this Document</title>
27 <body>
28 <p>This document provides you with all neccessary steps to install an openafs server on Gentoo Linux.
29 Parts of this document are taken from the AFS FAQ and IBM's Quick Beginnings guide on AFS. Well, never reinvent
30 the weel :)</p>
31 </body>
32 </section>
33 <section>
34 <title>What is AFS ?</title>
35 <body>
36
37 <p>
38 AFS is a distributed filesystem that enables co-operating hosts
39 (clients and servers) to efficiently share filesystem resources
40 across both local area and wide area networks. Clients hold a
41 cache for often used objects (files), to get quicker
42 access to them.
43 </p>
44 <p>
45 AFS is based on a distributed file system originally developed
46 at the Information Technology Center at Carnegie-Mellon University
47 that was called the "Andrew File System". "Andrew" was the name of the research project at CMU - honouring the
48 founders of the University. Once Transarc was formed and AFS became a
49 product, the "Andrew" was dropped to indicate that AFS had gone beyond
50 the Andrew research project and had become a supported, product quality
51 filesystem. However, there were a number of existing cells that rooted
52 their filesystem as /afs. At the time, changing the root of the filesystem
53 was a non-trivial undertaking. So, to save the early AFS sites from having
54 to rename their filesystem, AFS remained as the name and filesystem root.
55 </p>
56 </body>
57 </section>
58 <section>
59 <title>What is an AFS cell ?</title>
60 <body>
61 <p>An AFS cell is a collection of servers grouped together administratively
62 and presenting a single, cohesive filesystem. Typically, an AFS cell is a set of
63 hosts that use the same Internet domain name (like for example gentoo.org)
64 Users log into AFS client workstations which request information and files
65 from the cell's servers on behalf of the users. Users won't know on which server
66 a file which they are accessing, is located. They even won't notice if a server
67 will be located to another room, since every volume can be replicated and moved
68 to another server without user an user noticing. The files are always accessable.
69 Well it's like NFS on steroids :)
70 </p>
71 </body>
72 </section>
73 <section>
74 <title>What are the benefits of using AFS ?</title>
75 <body>
76 <p>The main strengths of AFS are its:
77
78 caching facility (on client side, typically 100M to 1GB),
79 security features (Kerberos 4 based, access control lists),
80 simplicity of addressing (you just have one filesystem),
81 scalability (add further servers to your cell as needed),
82 communications protocol.
83 </p>
84 </body>
85 </section>
86 <section>
87 <title>Where can i get more information ?</title>
88 <body>
89 <p>
90 Read the <uri link="http://www.angelfire.com/hi/plutonic/afs-faq.html">AFS FAQ</uri>.
91 </p>
92 <p>
93 Openafs main page is at <uri link="http://www.openafs.org">www.openafs.org</uri>.
94 </p>
95 <p>
96 AFS was originally developed by Transarc which is now owned by IBM.
97 You can find some information about AFS on
98 <uri link="http://www.transarc.ibm.com/Product/EFS/AFS/index.html">Transarcs Webpage</uri>
99 </p>
100 </body>
101 </section>
102
103 </chapter>
104
105 <chapter>
106 <title>Documentation</title>
107 <section>
108 <title>Getting AFS Documentation</title>
109 <body>
110 <p>
111 You can get the original IBM AFS Documentation. It is very well written and you
112 really want
113 read it if it is up to you to administer a AFS Server.
114 </p>
115 <pre>
116 # <i>emerge app-doc/afsdoc</i>
117 </pre>
118 </body>
119 </section>
120 </chapter>
121
122 <chapter>
123 <title>Client Installation</title>
124 <section>
125 <title>Preliminary Work</title>
126 <body>
127 <note>
128 All commands should be written in on line !! In this document they are
129 sometimes wrapped to two lines to make them easier to read.
130 </note>
131 <note>
132 Unfortunately the AFS Client needs a ext2 partiton for it's cache to run
133 correctly, because there are some locking issues with reiserfs. You need to
134 create a ext2 partition of approx. 200MB (more won't hurt) and mount it to
135 <path>/usr/vice/cache</path>
136 </note>
137 <p>
138 You should adjust the two files CellServDB ans ThisCell before you build the
139 afs client. (These files are in <path>/usr/portage/sys-fs/openafs/files</path>)
140 </p>
141 <pre>
142 CellServDB:
143 >netlabs #Cell name
144 10.0.0.1 #storage
145
146 ThisCell:
147 netlabs
148 </pre>
149 <p>
150 CellServDB tells your client which server(s) he needs to contact for a
151 specific cell. ThisCell should be quite obvious. Normally you use a name
152 which is unique for your organisation. Your (official) domain might be a
153 good choice.
154 </p>
155 </body>
156 </section>
157 <section>
158 <title>Building the Client</title>
159 <body>
160 <pre>
161 <i>emerge sys-fs/openafs</i>
162 </pre>
163 <p>
164 After successfull compilation you're ready to go.
165 </p>
166 </body>
167 </section>
168 <section>
169 <title>Starting afs on startup</title>
170 <body>
171 <p>
172 The following command will create the appropriate links to start your afs client
173 on system startup.
174 </p>
175 <warn>
176 You should always have a running afs server in your domain when trying to start the afs client. You're system won't boot
177 until it gets some timeout if your afs server is down. (and this is quite a long long time)
178 </warn>
179 <pre>
180 # <i>rc-update add afs default</i>
181 </pre>
182 </body>
183 </section>
184 </chapter>
185
186 <chapter>
187 <title>Server Installation</title>
188 <section>
189 <title>Building the Server</title>
190 <body>
191 <p>
192 The following command will install all necessary binaries for setting up a AFS Server
193 <i>and</i> Client
194 </p>
195 <pre>
196 # <i>emerge sys-fs/openafs</i>
197 </pre>
198 </body>
199 </section>
200 <section>
201 <title>Starting AFS Server</title>
202 <body>
203 <p>
204 You need to remove the sample CellServDB and ThisCell file first.
205 </p>
206 <pre>
207 # <i>rm /usr/vice/etc/ThisCell</i>
208 # <i>rm /usr/vice/etc/CellServDB</i>
209 </pre>
210 <p>
211 Next you will run the <b>bosserver</b> command to initialize the Basic OverSeer (BOS)
212 Server, which monitors and controls other AFS server processes on its server
213 machine. Think of it as init for the system. Include the <b>-noauth</b>
214 flag to disable authorization checking, since you haven't added the admin user yet.
215 </p>
216 <p>
217 <warn>
218 Disabling authorization checking gravely compromises cell security.
219 You must complete all subsequent steps in one uninterrupted pass
220 and must not leave the machine unattended until you restart the BOS Server with
221 authorization checking enabled. Well this is what the AFS documentation says :)
222 </warn>
223 </p>
224 <pre>
225 # <i>/usr/afs/bin/bosserver -noauth &amp;</i>
226 </pre>
227 <p>
228 Verify that the BOS Server created <path>/usr/vice/etc/CellServDB</path>
229 and <path>/usr/vice/etc/ThisCell</path>
230 </p>
231 <pre>
232 # <i>ls -al /usr/vice/etc/</i>
233 -rw-r--r-- 1 root root 41 Jun 4 22:21 CellServDB
234 -rw-r--r-- 1 root root 7 Jun 4 22:21 ThisCell
235 </pre>
236
237 </body>
238 </section>
239 <section>
240 <title>Defining Cell Name and Membership for Server Process</title>
241 <body>
242 <p>
243 Now assign your cells name.
244 </p>
245 <p>
246 <impo>There are some restrictions on the name format.
247 Two of the most important restrictions are that the name
248 cannot include uppercase letters or more than 64 characters. Remember that
249 your cell name will show up under <path>/afs</path>, so you might want to choose
250 a short one.</impo>
251 </p>
252 <p>
253 <note>In the following and every instruction in this guide, for the <i>&lt;server name&gt;</i>
254 argument substitute the full-qualified hostname
255 (such as <b>afs.gentoo.org</b>) of the machine you are installing.
256 For the <i>&lt;cell name&gt;</i>
257 argument substitute your cell's complete name (such as <b>gentoo</b>)</note>
258 </p>
259 <p>
260 Run the <b>bos setcellname</b> command to set the cell name:
261 </p>
262 <pre>
263 # <i>/usr/afs/bin/bos setcellname &lt;server name&gt; &lt;cell name&gt; -noauth</i>
264 </pre>
265 </body>
266 </section>
267 <section>
268 <title>Starting the Database Server Process</title>
269 <body><p>
270 Next use the <b>bos create</b> command to create entries for the four database
271 server processes in the
272 <path>/usr/afs/local/BosConfig</path> file. The four processes run on database
273 server machines only.
274 </p>
275 <p>
276 <table>
277 <tr>
278 <ti>kaserver</ti>
279 <ti>The Authentication Server maintains the Authentication Database.
280 This can be replaced by a Kerberos 5 daemon. If anybody want's to try that
281 feel free to update this document :)</ti>
282 </tr>
283 <tr>
284 <ti>buserver</ti>
285 <ti>The Backup Server maintains the Backup Database</ti>
286 </tr>
287 <tr>
288 <ti>ptserver</ti>
289 <ti>The Protection Server maintains the Protection Database</ti>
290 </tr>
291 <tr>
292 <ti>vlserver</ti>
293 <ti>The Volume Location Server maintains the Volume Location Database (VLDB).
294 Very important :)</ti>
295 </tr>
296 </table>
297 </p>
298 <pre>
299 # <i>/usr/afs/bin/bos create &lt;server name&gt; kaserver simple
300 /usr/afs/bin/kaserver -cell &lt;cell name&gt; -noauth</i>
301 # <i>/usr/afs/bin/bos create &lt;server name&gt; buserver simple
302 /usr/afs/bin/buserver -cell &lt;cell name&gt; -noauth</i>
303 # <i>/usr/afs/bin/bos create &lt;server name&gt; ptserver simple
304 /usr/afs/bin/ptserver -cell &lt;cell name&gt; -noauth</i>
305 # <i>/usr/afs/bin/bos create &lt;server name&gt; vlserver simple
306 /usr/afs/bin/vlserver -cell &lt;cell name&gt; -noauth</i>
307 </pre>
308 <p>
309 a
310 a
311 a
312 a
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 &lt;server name&gt; -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 &lt;cell name&gt; -noauth</i>
344 ka&gt; <i>create afs</i>
345 initial_password:
346 Verifying, please re-enter initial_password:
347 ka&gt; <i>create admin</i>
348 initial_password:
349 Verifying, please re-enter initial_password:
350 ka&gt; <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&gt;
358 permit password reuse
359 ka&gt; <i>setfields admin -flags admin</i>
360 ka&gt; <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&gt;
368 permit password reuse
369 ka&gt;
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 &lt;server name&gt; admin -cell &lt;cell name&gt; -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 &lt;server name&gt; -kvno 0 -cell &lt;cell name&gt; -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 &lt;cell name&gt; [-id &lt;AFS UID&gt;] -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 &lt;cell name&gt; -noauth</i>
413 # <i>/usr/afs/bin/pts membership admin -cell &lt;cell name&gt; -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 &lt;server name&gt; -all -cell &lt;cell name&gt; -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 &lt;server name&gt; fs fs /usr/afs/bin/fileserver
434 /usr/afs/bin/volserver
435 /usr/afs/bin/salvager
436 -cell &lt;cell name&gt; -noauth</i>
437 </pre>
438 <p>
439 Verify that all processes are running
440 </p>
441 <pre>
442 # <i>/usr/afs/bin/bos status &lt;server name&gt; -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 &lt;server name&gt;
485 &lt;partition name&gt; root.afs
486 -cell &lt;cell name&gt; -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 &lt;server name&gt; -cell &lt;cell name&gt; -verbose -noauth</i>
497 # <i>/usr/afs/bin/vos syncserv &lt;server name&gt; -cell &lt;cell name&gt; -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 &lt;server name&gt;
506 upserver simple "/usr/afs/bin/upserver
507 -crypt /usr/afs/etc -clear /usr/afs/bin"
508 -cell &lt;cell name&gt; -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/&lt;cell name&gt;</path> and read/write
523 on <path>/afs/.&lt;cell name&gt;</path>
524 <pre>
525 # <i>/usr/afs/bin/vos create &lt;server name&gt;&lt;partition name&gt; root.cell</i>
526 # <i>/usr/afs/bin/fs mkmount /afs/&lt;cell name&gt; root.cell </i>
527 # <i>/usr/afs/bin/fs setacl /afs/&lt;cell name&gt; system:anyuser rl</i>
528 # <i>/usr/afs/bin/fs mkmount /afs/.&lt;cell name&gt; 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>

  ViewVC Help
Powered by ViewVC 1.1.20