/[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 - (hide annotations) (download) (as text)
Thu Sep 25 00:18:10 2003 UTC (10 years, 9 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 zhen 1.3 <?xml version='1.0' encoding="UTF-8"?>
2 drobbins 1.1
3     <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
4    
5 zhen 1.2 <guide link = "/doc/en/openafs.xml">
6 drobbins 1.1 <title>Gentoo Linux OpenAFS Guide</title>
7     <author title="Editor">
8     <mail link="darks@gentoo.org">Holger Brueckner</mail>
9     </author>
10 bennyc 1.8 <author title="Editor">
11     <mail link="bennyc@gentoo.org">Benny Chuang</mail>
12     </author>
13 drobbins 1.1
14     <abstract>
15     This guide shows you how to install a openafs server and client on gentoo linux
16     </abstract>
17    
18 swift 1.7 <version>0.2</version>
19     <date>September 15, 2003</date>
20 drobbins 1.1
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 swift 1.7 afs client. (These files are in <path>/usr/portage/sys-fs/openafs/files</path>)
138 drobbins 1.1 </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 swift 1.7 <i>emerge sys-fs/openafs</i>
160 drobbins 1.1 </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 swift 1.4 The following command will install all necessary binaries for setting up a AFS Server
191 drobbins 1.1 <i>and</i> Client
192     </p>
193     <pre>
194 swift 1.7 # <i>emerge sys-fs/openafs</i>
195 drobbins 1.1 </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 bennyc 1.8 <ti>The Authentication Server maintains the Authentication Database.
278 drobbins 1.1 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 bennyc 1.8 a
308     a
309     a
310     a
311 drobbins 1.1 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 bennyc 1.8 Authentication Database: The main administrative account, called <b>admin</b> by
330 drobbins 1.1 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 swift 1.5 and the <b>pts membership</b> command to verify the new membership
408 drobbins 1.1 </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 swift 1.5 Start the <b>fs</b> process, which consists of the File Server, Volume Server and Salvager (fileserver,
428 drobbins 1.1 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 swift 1.6 Then you need to create the root volume, mount it readonly on <path>/afs/&lt;cell name&gt;</path> and read/write
521 drobbins 1.1 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