/[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.11 - (hide annotations) (download) (as text)
Fri Nov 7 15:15:26 2003 UTC (10 years, 9 months ago) by swift
Branch: MAIN
Changes since 1.10: +8 -8 lines
File MIME type: application/xml
Fixed some typos, fixed sys-fs to net-fs

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

  ViewVC Help
Powered by ViewVC 1.1.20