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

  ViewVC Help
Powered by ViewVC 1.1.20