/[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 - (show annotations) (download) (as text)
Mon Sep 15 19:28:32 2003 UTC (11 years 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 <?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
11 <abstract>
12 This guide shows you how to install a openafs server and client on gentoo linux
13 </abstract>
14
15 <version>0.2</version>
16 <date>September 15, 2003</date>
17
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 afs client. (These files are in <path>/usr/portage/sys-fs/openafs/files</path>)
135 </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 <i>emerge sys-fs/openafs</i>
157 </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 The following command will install all necessary binaries for setting up a AFS Server
188 <i>and</i> Client
189 </p>
190 <pre>
191 # <i>emerge sys-fs/openafs</i>
192 </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 and the <b>pts membership</b> command to verify the new membership
401 </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 Start the <b>fs</b> process, which consists of the File Server, Volume Server and Salvager (fileserver,
421 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 Then you need to create the root volume, mount it readonly on <path>/afs/&lt;cell name&gt;</path> and read/write
514 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