/[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.8 - (show annotations) (download) (as text)
Thu Sep 25 00:18:10 2003 UTC (10 years, 10 months ago) by bennyc
Branch: MAIN
Changes since 1.7: +9 -2 lines
File MIME type: application/xml
Fixed typo, Authentification -> Authentication
Bug# 29530

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

  ViewVC Help
Powered by ViewVC 1.1.20