/[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.13 - (hide annotations) (download) (as text)
Fri Mar 5 09:35:35 2004 UTC (10 years, 4 months ago) by swift
Branch: MAIN
Changes since 1.12: +9 -3 lines
File MIME type: application/xml
CellServDB should only contain spaces, not tabs. Tx 2 Christophe Bernard, mailed to www@gentoo.org and confirmed by some mails in the OpenAFS mailinglist

1 zhen 1.3 <?xml version='1.0' encoding="UTF-8"?>
2 swift 1.13 <!-- $Header: /home/cvsroot/gentoo/xml/htdocs/doc/en/openafs.xml,v 1.12 2003/11/15 00:35:19 neysx Exp $ -->
3 drobbins 1.1
4     <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
5    
6 zhen 1.2 <guide link = "/doc/en/openafs.xml">
7 drobbins 1.1 <title>Gentoo Linux OpenAFS Guide</title>
8     <author title="Editor">
9     <mail link="darks@gentoo.org">Holger Brueckner</mail>
10     </author>
11 bennyc 1.8 <author title="Editor">
12     <mail link="bennyc@gentoo.org">Benny Chuang</mail>
13     </author>
14 blubber 1.10 <author title="Editor">
15     <mail link="blubber@gentoo.org">Tiemo Kieft</mail>
16     </author>
17 drobbins 1.1
18     <abstract>
19     This guide shows you how to install a openafs server and client on gentoo linux
20     </abstract>
21    
22 swift 1.9 <license/>
23    
24 swift 1.13 <version>0.5</version>
25     <date>March 5, 2004</date>
26 drobbins 1.1
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 blubber 1.10 the wheel :)</p>
35 drobbins 1.1 </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 swift 1.11 to another server without any user noticing. The files are always accessable.
73 drobbins 1.1 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 swift 1.11 All commands should be written in one line !! In this document they are
133 drobbins 1.1 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 swift 1.11 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 drobbins 1.1 </p>
145     <pre>
146     CellServDB:
147     >netlabs #Cell name
148     10.0.0.1 #storage
149    
150     ThisCell:
151     netlabs
152     </pre>
153 swift 1.13
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 drobbins 1.1 <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 swift 1.11 # <i>emerge net-fs/openafs</i>
172 drobbins 1.1 </pre>
173     <p>
174 blubber 1.10 After successful compilation you're ready to go.
175 drobbins 1.1 </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 swift 1.4 The following command will install all necessary binaries for setting up a AFS Server
203 drobbins 1.1 <i>and</i> Client
204     </p>
205     <pre>
206 swift 1.11 # <i>emerge net-fs/openafs</i>
207 drobbins 1.1 </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     <p>
227     <warn>
228     Disabling authorization checking gravely compromises cell security.
229     You must complete all subsequent steps in one uninterrupted pass
230     and must not leave the machine unattended until you restart the BOS Server with
231     authorization checking enabled. Well this is what the AFS documentation says :)
232     </warn>
233     </p>
234     <pre>
235     # <i>/usr/afs/bin/bosserver -noauth &amp;</i>
236     </pre>
237     <p>
238     Verify that the BOS Server created <path>/usr/vice/etc/CellServDB</path>
239     and <path>/usr/vice/etc/ThisCell</path>
240     </p>
241     <pre>
242     # <i>ls -al /usr/vice/etc/</i>
243     -rw-r--r-- 1 root root 41 Jun 4 22:21 CellServDB
244     -rw-r--r-- 1 root root 7 Jun 4 22:21 ThisCell
245     </pre>
246    
247     </body>
248     </section>
249     <section>
250     <title>Defining Cell Name and Membership for Server Process</title>
251     <body>
252     <p>
253     Now assign your cells name.
254     </p>
255     <p>
256     <impo>There are some restrictions on the name format.
257     Two of the most important restrictions are that the name
258     cannot include uppercase letters or more than 64 characters. Remember that
259     your cell name will show up under <path>/afs</path>, so you might want to choose
260     a short one.</impo>
261     </p>
262     <p>
263     <note>In the following and every instruction in this guide, for the <i>&lt;server name&gt;</i>
264     argument substitute the full-qualified hostname
265     (such as <b>afs.gentoo.org</b>) of the machine you are installing.
266     For the <i>&lt;cell name&gt;</i>
267     argument substitute your cell's complete name (such as <b>gentoo</b>)</note>
268     </p>
269     <p>
270     Run the <b>bos setcellname</b> command to set the cell name:
271     </p>
272     <pre>
273     # <i>/usr/afs/bin/bos setcellname &lt;server name&gt; &lt;cell name&gt; -noauth</i>
274     </pre>
275     </body>
276     </section>
277     <section>
278     <title>Starting the Database Server Process</title>
279     <body><p>
280     Next use the <b>bos create</b> command to create entries for the four database
281     server processes in the
282     <path>/usr/afs/local/BosConfig</path> file. The four processes run on database
283     server machines only.
284     </p>
285     <p>
286     <table>
287     <tr>
288     <ti>kaserver</ti>
289 bennyc 1.8 <ti>The Authentication Server maintains the Authentication Database.
290 drobbins 1.1 This can be replaced by a Kerberos 5 daemon. If anybody want's to try that
291     feel free to update this document :)</ti>
292     </tr>
293     <tr>
294     <ti>buserver</ti>
295     <ti>The Backup Server maintains the Backup Database</ti>
296     </tr>
297     <tr>
298     <ti>ptserver</ti>
299     <ti>The Protection Server maintains the Protection Database</ti>
300     </tr>
301     <tr>
302     <ti>vlserver</ti>
303     <ti>The Volume Location Server maintains the Volume Location Database (VLDB).
304     Very important :)</ti>
305     </tr>
306     </table>
307     </p>
308     <pre>
309     # <i>/usr/afs/bin/bos create &lt;server name&gt; kaserver simple
310     /usr/afs/bin/kaserver -cell &lt;cell name&gt; -noauth</i>
311     # <i>/usr/afs/bin/bos create &lt;server name&gt; buserver simple
312     /usr/afs/bin/buserver -cell &lt;cell name&gt; -noauth</i>
313     # <i>/usr/afs/bin/bos create &lt;server name&gt; ptserver simple
314     /usr/afs/bin/ptserver -cell &lt;cell name&gt; -noauth</i>
315     # <i>/usr/afs/bin/bos create &lt;server name&gt; vlserver simple
316     /usr/afs/bin/vlserver -cell &lt;cell name&gt; -noauth</i>
317     </pre>
318     <p>
319     You can verify that all servers are running with the <b>bos status</b> command:
320     </p>
321     <pre>
322     # <i>/usr/afs/bin/bos status &lt;server name&gt; -noauth</i>
323     Instance kaserver, currently running normally.
324     Instance buserver, currently running normally.
325     Instance ptserver, currently running normally.
326     Instance vlserver, currently running normally.
327     </pre>
328    
329     </body>
330     </section>
331     <section>
332     <title>Initializing Cell Security</title>
333     <body>
334     <p>
335     Now we'll initialize the cell's security mechanisms. We'll begin by creating the
336     following two initial entries in the
337 bennyc 1.8 Authentication Database: The main administrative account, called <b>admin</b> by
338 drobbins 1.1 convention and an entry for
339     the AFS server processes, called <b>afs</b>. No user logs in under the
340     identity <b>afs</b>, but the Authentication
341     Server's Ticket Granting Service (TGS) module uses the account
342     to encrypt the server tickets that it grants to AFS clients. This sounds
343     pretty much like Kerberos :)
344     </p>
345     <p>
346     Enter <b>kas</b> interactive mode
347     </p>
348     <pre>
349     # <i>/usr/afs/bin/kas -cell &lt;cell name&gt; -noauth</i>
350     ka&gt; <i>create afs</i>
351     initial_password:
352     Verifying, please re-enter initial_password:
353     ka&gt; <i>create admin</i>
354     initial_password:
355     Verifying, please re-enter initial_password:
356     ka&gt; <i>examine afs</i>
357    
358     User data for afs
359     key (0) cksum is 2651715259, last cpw: Mon Jun 4 20:49:30 2001
360     password will never expire.
361     An unlimited number of unsuccessful authentications is permitted.
362     entry never expires. Max ticket lifetime 100.00 hours.
363     last mod on Mon Jun 4 20:49:30 2001 by $lt;none&gt;
364     permit password reuse
365     ka&gt; <i>setfields admin -flags admin</i>
366     ka&gt; <i>examine admin</i>
367    
368     User data for admin (ADMIN)
369     key (0) cksum is 2651715259, last cpw: Mon Jun 4 20:49:59 2001
370     password will never expire.
371     An unlimited number of unsuccessful authentications is permitted.
372     entry never expires. Max ticket lifetime 25.00 hours.
373     last mod on Mon Jun 4 20:51:10 2001 by $lt;none&gt;
374     permit password reuse
375     ka&gt;
376     </pre>
377     <p>
378     Run the <b>bos adduser</b> command, to add the <b>admin</b> user to
379     the <path>/usr/afs/etc/UserList</path>.
380     </p>
381     <pre>
382     # <i>/usr/afs/bin/bos adduser &lt;server name&gt; admin -cell &lt;cell name&gt; -noauth</i>
383     </pre>
384     <p>
385     Issue the <b>bos addkey</b> command to define the AFS Server
386     encryption key in <path>/usr/afs/etc/KeyFile</path>
387     </p>
388     <note>
389     If asked for the input key, give the password you entered when creating
390     the afs entry with <b>kas</b>
391     </note>
392     <pre>
393     # <i>/usr/afs/bin/bos addkey &lt;server name&gt; -kvno 0 -cell &lt;cell name&gt; -noauth</i>
394     input key:
395     Retype input key:
396     </pre>
397     <p>
398     Issue the <b>pts createuser</b> command to create a Protection Database
399     entry for the admin user
400     </p>
401     <note>
402     By default, the Protection Server assigns AFS UID 1 to the <b>admin</b> user, because
403     it is the first user
404     entry you are creating. If the local password file (/etc/passwd or equivalent)
405     already has an entry for
406     <b>admin</b> that assigns a different UID use the <b>-id</b> argument
407     to create matching UID's
408     </note>
409     <pre>
410     # <i>/usr/afs/bin/pts createuser -name admin -cell &lt;cell name&gt; [-id &lt;AFS UID&gt;] -noauth</i>
411     </pre>
412     <p>
413     Issue the <b>pts adduser</b> command to make the <b>admin</b> user a member
414     of the system:administrators group,
415 swift 1.5 and the <b>pts membership</b> command to verify the new membership
416 drobbins 1.1 </p>
417     <pre>
418     # <i>/usr/afs/bin/pts adduser admin system:administrators -cell &lt;cell name&gt; -noauth</i>
419     # <i>/usr/afs/bin/pts membership admin -cell &lt;cell name&gt; -noauth</i>
420     Groups admin (id: 1) is a member of:
421     system:administrators
422     </pre>
423     <p>
424     Restart all AFS Server processes
425     </p>
426     <pre>
427     # <i>/usr/afs/bin/bos restart &lt;server name&gt; -all -cell &lt;cell name&gt; -noauth</i>
428     </pre>
429     </body>
430     </section>
431     <section>
432     <title>Starting the File Server, Volume Server and Salvager</title>
433     <body>
434     <p>
435 swift 1.5 Start the <b>fs</b> process, which consists of the File Server, Volume Server and Salvager (fileserver,
436 drobbins 1.1 volserver and salvager processes).
437     </p>
438     <pre>
439     # <i>/usr/afs/bin/bos create &lt;server name&gt; fs fs /usr/afs/bin/fileserver
440     /usr/afs/bin/volserver
441     /usr/afs/bin/salvager
442     -cell &lt;cell name&gt; -noauth</i>
443     </pre>
444     <p>
445     Verify that all processes are running
446     </p>
447     <pre>
448     # <i>/usr/afs/bin/bos status &lt;server name&gt; -long -noauth</i>
449     Instance kaserver, (type is simple) currently running normally.
450     Process last started at Mon Jun 4 21:07:17 2001 (2 proc starts)
451     Last exit at Mon Jun 4 21:07:17 2001
452     Command 1 is '/usr/afs/bin/kaserver'
453    
454     Instance buserver, (type is simple) currently running normally.
455     Process last started at Mon Jun 4 21:07:17 2001 (2 proc starts)
456     Last exit at Mon Jun 4 21:07:17 2001
457     Command 1 is '/usr/afs/bin/buserver'
458    
459     Instance ptserver, (type is simple) currently running normally.
460     Process last started at Mon Jun 4 21:07:17 2001 (2 proc starts)
461     Last exit at Mon Jun 4 21:07:17 2001
462     Command 1 is '/usr/afs/bin/ptserver'
463    
464     Instance vlserver, (type is simple) currently running normally.
465     Process last started at Mon Jun 4 21:07:17 2001 (2 proc starts)
466     Last exit at Mon Jun 4 21:07:17 2001
467     Command 1 is '/usr/afs/bin/vlserver'
468    
469     Instance fs, (type is fs) currently running normally.
470     Auxiliary status is: file server running.
471     Process last started at Mon Jun 4 21:09:30 2001 (2 proc starts)
472     Command 1 is '/usr/afs/bin/fileserver'
473     Command 2 is '/usr/afs/bin/volserver'
474     Command 3 is '/usr/afs/bin/salvager'
475     </pre>
476     <p>
477     Your next action depends on whether you have ever run AFS file server machines
478     in the cell:
479     </p>
480     <p>
481     If you are installing the first AFS Server ever in the cell create the
482     first AFS volume, <b>root.afs</b>
483     </p>
484     <note>
485     For the partition name argument, substitute the name of one of the machine's
486     AFS Server partitions. By convention
487     these partitions are named <path>/vicex</path>, where x is in the range of a-z.
488     </note>
489     <pre>
490     # <i>/usr/afs/bin/vos create &lt;server name&gt;
491     &lt;partition name&gt; root.afs
492     -cell &lt;cell name&gt; -noauth</i>
493     </pre>
494     <p>
495     If there are existing AFS file server machines and volumes in the cell
496     issue the <b>vos sncvldb</b> and <b>vos
497     syncserv</b> commands to synchronize the VLDB (Volume Location Database) with
498     the actual state of volumes on the local machine. This will copy all necessary data to your
499     new server.
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 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
529 drobbins 1.1 on <path>/afs/.&lt;cell name&gt;</path>
530     <pre>
531     # <i>/usr/afs/bin/vos create &lt;server name&gt;&lt;partition name&gt; root.cell</i>
532     # <i>/usr/afs/bin/fs mkmount /afs/&lt;cell name&gt; root.cell </i>
533     # <i>/usr/afs/bin/fs setacl /afs/&lt;cell name&gt; system:anyuser rl</i>
534     # <i>/usr/afs/bin/fs mkmount /afs/.&lt;cell name&gt; root.cell -rw</i>
535     </pre>
536     </p>
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