/[gentoo]/xml/htdocs/doc/en/openafs.xml
Gentoo

Diff of /xml/htdocs/doc/en/openafs.xml

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

Revision 1.3 Revision 1.27
1<?xml version='1.0' encoding="UTF-8"?> 1<?xml version='1.0' encoding="UTF-8"?>
2<?xml-stylesheet href="/xsl/guide.xsl" type="text/xsl"?> 2<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/openafs.xml,v 1.27 2011/09/04 17:53:40 swift Exp $ -->
3 3
4<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> 4<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
5 5
6<guide link = "/doc/en/openafs.xml"> 6<guide>
7<title>Gentoo Linux OpenAFS Guide</title> 7<title>Gentoo Linux OpenAFS Guide</title>
8
9<author title="Editor">
10 <mail link="stefaan@gentoo.org">Stefaan De Roeck</mail>
11</author>
8<author title="Editor"> 12<author title="Editor">
9 <mail link="darks@gentoo.org">Holger Brueckner</mail> 13 <mail link="darks@gentoo.org">Holger Brueckner</mail>
10</author> 14</author>
15<author title="Editor">
16 <mail link="bennyc@gentoo.org">Benny Chuang</mail>
17</author>
18<author title="Editor">
19 <mail link="blubber@gentoo.org">Tiemo Kieft</mail>
20</author>
21<author title="Editor">
22 <mail link="fnjordy@gmail.com">Steven McCoy</mail>
23</author>
24<author title="Editor">
25 <mail link="fox2mike@gentoo.org">Shyam Mani</mail>
26</author>
11 27
12<abstract> 28<abstract>
13This guide shows you how to install a openafs server and client on gentoo linux 29This guide shows you how to install an OpenAFS server and client on Gentoo
30Linux.
14</abstract> 31</abstract>
15 32
33<!-- The content of this document is licensed under the CC-BY-SA license -->
34<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
35<license/>
36
16<version>0.1</version> 37<version>1.2</version>
17<date>05 June 2001</date> 38<date>2007-06-29</date>
18 39
19<chapter> 40<chapter>
20 <title>Overview</title> 41<title>Overview</title>
21 <section> 42<section>
22 <title>About this Document</title> 43<title>About this Document</title>
23 <body> 44<body>
45
46<p>
24 <p>This document provides you with all neccessary steps to install an openafs server on Gentoo Linux. 47This document provides you with all necessary steps to install an OpenAFS
25 Parts of this document are taken from the AFS FAQ and IBM's Quick Beginnings guide on AFS. Well, never reinvent 48server on Gentoo Linux. Parts of this document are taken from the AFS FAQ and
26 the weel :)</p> 49IBM's Quick Beginnings guide on AFS. Well, never reinvent the wheel. :)
50</p>
51
27 </body> 52</body>
28 </section> 53</section>
29 <section> 54<section>
30 <title>What is AFS ?</title> 55<title>What is AFS?</title>
31 <body> 56<body>
32 57
33 <p> 58<p>
34 AFS is a distributed filesystem that enables co-operating hosts 59AFS is a distributed filesystem that enables co-operating hosts
35 (clients and servers) to efficiently share filesystem resources 60(clients and servers) to efficiently share filesystem resources
36 across both local area and wide area networks. Clients hold a 61across both local area and wide area networks. Clients hold a
37 cache for often used objects (files), to get quicker 62cache for often used objects (files), to get quicker
38 access to them. 63access to them.
39 </p> 64</p>
40 <p> 65
66<p>
41 AFS is based on a distributed file system originally developed 67AFS is based on a distributed file system originally developed
42 at the Information Technology Center at Carnegie-Mellon University 68at the Information Technology Center at Carnegie-Mellon University
43 that was called the "Andrew File System". "Andrew" was the name of the research project at CMU - honouring the 69that was called the "Andrew File System". "Andrew" was the name of the
44 founders of the University. Once Transarc was formed and AFS became a 70research project at CMU - honouring the founders of the University. Once
45 product, the "Andrew" was dropped to indicate that AFS had gone beyond 71Transarc was formed and AFS became a product, the "Andrew" was dropped to
46 the Andrew research project and had become a supported, product quality 72indicate that AFS had gone beyond the Andrew research project and had become
47 filesystem. However, there were a number of existing cells that rooted 73a supported, product quality filesystem. However, there were a number of
48 their filesystem as /afs. At the time, changing the root of the filesystem 74existing cells that rooted their filesystem as /afs. At the time, changing
49 was a non-trivial undertaking. So, to save the early AFS sites from having 75the root of the filesystem was a non-trivial undertaking. So, to save the
50 to rename their filesystem, AFS remained as the name and filesystem root. 76early AFS sites from having to rename their filesystem, AFS remained as the
51 </p> 77name and filesystem root.
78</p>
79
52 </body> 80</body>
53 </section> 81</section>
54 <section> 82<section>
55 <title>What is an AFS cell ?</title> 83<title>What is an AFS cell?</title>
56 <body> 84<body>
85
86<p>
57 <p>An AFS cell is a collection of servers grouped together administratively 87An AFS cell is a collection of servers grouped together administratively and
58 and presenting a single, cohesive filesystem. Typically, an AFS cell is a set of 88presenting a single, cohesive filesystem. Typically, an AFS cell is a set of
59 hosts that use the same Internet domain name (like for example gentoo.org) 89hosts that use the same Internet domain name (for example, gentoo.org) Users
60 Users log into AFS client workstations which request information and files 90log into AFS client workstations which request information and files from the
61 from the cell's servers on behalf of the users. Users won't know on which server 91cell's servers on behalf of the users. Users won't know on which server a
62 a file which they are accessing, is located. They even won't notice if a server 92file which they are accessing, is located. They even won't notice if a server
63 will be located to another room, since every volume can be replicated and moved 93will be located to another room, since every volume can be replicated and
64 to another server without user an user noticing. The files are always accessable. 94moved to another server without any user noticing. The files are always
65 Well it's like NFS on steroids :) 95accessible. Well, it's like NFS on steroids :)
66 </p> 96</p>
97
67 </body> 98</body>
68 </section> 99</section>
69 <section> 100<section>
70 <title>What are the benefits of using AFS ?</title> 101<title>What are the benefits of using AFS?</title>
71 <body> 102<body>
103
104<p>
72 <p>The main strengths of AFS are its: 105The main strengths of AFS are its:
73
74 caching facility (on client side, typically 100M to 1GB), 106caching facility (on client side, typically 100M to 1GB),
75 security features (Kerberos 4 based, access control lists), 107security features (Kerberos 4 based, access control lists),
76 simplicity of addressing (you just have one filesystem), 108simplicity of addressing (you just have one filesystem),
77 scalability (add further servers to your cell as needed), 109scalability (add further servers to your cell as needed),
78 communications protocol. 110communications protocol.
79 </p> 111</p>
112
80 </body> 113</body>
81 </section> 114</section>
82 <section> 115<section>
83 <title>Where can i get more information ?</title> 116<title>Where can I get more information?</title>
84 <body> 117<body>
85 <p> 118
119<p>
86 Read the <uri link="http://www.angelfire.com/hi/plutonic/afs-faq.html">AFS FAQ</uri>. 120Read the <uri link="http://www.angelfire.com/hi/plutonic/afs-faq.html">AFS
87 </p> 121FAQ</uri>.
88 <p> 122</p>
123
124<p>
125OpenAFS main page is at <uri
89 Openafs main page is at <uri link="http://www.openafs.org">www.openafs.org</uri>. 126link="http://www.openafs.org">www.openafs.org</uri>.
90 </p> 127</p>
91 <p> 128
129<p>
92 AFS was originally developed by Transarc which is now owned by IBM. 130AFS was originally developed by Transarc which is now owned by IBM.
93 You can find some information about AFS on 131You can find some information about AFS on
94 <uri link="http://www.transarc.ibm.com/Product/EFS/AFS/index.html">Transarcs Webpage</uri> 132<uri link="http://www.transarc.ibm.com/Product/EFS/AFS/index.html">Transarc's
95 </p> 133Webpage</uri>.
134</p>
135
96 </body> 136</body>
97 </section> 137</section>
138<section>
139<title>How Can I Debug Problems?</title>
140<body>
98 141
142<p>
143OpenAFS has great logging facilities. However, by default it logs straight into
144its own logs instead of through the system logging facilities you have on your
145system. To have the servers log through your system logger, use the
146<c>-syslog</c> option for all <c>bos</c> commands.
147</p>
148
149</body>
150</section>
151</chapter>
152
153<chapter>
154<title>Upgrading from previous versions</title>
155<section>
156<title>Introduction</title>
157<body>
158
159<p>
160This section aims to help you through the process of upgrading an existing
161OpenAFS installation to OpenAFS version 1.4.0 or higher (or 1.2.x starting from
1621.2.13. The latter will not be handled specifically, as most people will want
1631.4 for a.o. linux-2.6 support, large file support and bug fixes).
164</p>
165
166<p>
167If you're dealing with a clean install of a 1.4 version of OpenAFS, then you can
168safely skip this chapter. However, if you're upgrading from a previous version,
169we strongly urge you to follow the guidelines in the next sections. The
170transition script in the ebuild is designed to assist you in quickly upgrading
171and restarting. Please note that it will (for safety reasons) not delete
172configuration files and startup scripts in old places, not automatically change
173your boot configuration to use the new scripts, etc. If you need further
174convincing, using an old OpenAFS kernel module together with the updated system
175binaries, may very well cause your kernel to freak out. So, let's read on for a
176clean and easy transition, shall we?
177</p>
178
179<note>
180This chapter has been written bearing many different system configurations in
181mind. Still, it is possible that due to peculiar tweaks a user has made, his or
182her specific situation may not be described here. A user with enough
183self-confidence to tweak his system should be experienced enough to apply the
184given remarks where appropriate. Vice versa, a user that has done little
185to his system but install the previous ebuild, can skip most of the warnings
186further on.
187</note>
188
189</body>
190</section>
191<section>
192<title>Differences to previous versions</title>
193<body>
194
195<p>
196Traditionally, OpenAFS has used the same path-conventions that IBM TransArc labs
197had used, before the code was forked. Understandably, old AFS setups continue
198using these legacy path conventions. More recent setups conform with FHS by
199using standard locations (as seen in many Linux distributions). The following
200table is a compilation of the configure-script and the README accompanying the
201OpenAFS distribution tarballs:
202</p>
203
204<table>
205<tr>
206 <th>Directory</th>
207 <th>Purpose</th>
208 <th>Transarc Mode</th>
209 <th>Default Mode</th>
210 <th>translation to Gentoo</th>
211</tr>
212<tr>
213 <ti>viceetcdir</ti>
214 <ti>Client configuration</ti>
215 <ti>/usr/vice/etc</ti>
216 <ti>$(sysconfdir)/openafs</ti>
217 <ti>/etc/openafs</ti>
218</tr>
219<tr>
220 <ti>unnamed</ti>
221 <ti>Client binaries</ti>
222 <ti>unspecified</ti>
223 <ti>$(bindir)</ti>
224 <ti>/usr/bin</ti>
225</tr>
226<tr>
227 <ti>afsconfdir</ti>
228 <ti>Server configuration</ti>
229 <ti>/usr/afs/etc</ti>
230 <ti>$(sysconfdir)/openafs/server</ti>
231 <ti>/etc/openafs/server</ti>
232</tr>
233<tr>
234 <ti>afssrvdir</ti>
235 <ti>Internal server binaries</ti>
236 <ti>/usr/afs/bin (servers)</ti>
237 <ti>$(libexecdir)/openafs</ti>
238 <ti>/usr/libexec/openafs</ti>
239</tr>
240<tr>
241 <ti>afslocaldir</ti>
242 <ti>Server state</ti>
243 <ti>/usr/afs/local</ti>
244 <ti>$(localstatedir)/openafs</ti>
245 <ti>/var/lib/openafs</ti>
246</tr>
247<tr>
248 <ti>afsdbdir</ti>
249 <ti>Auth/serverlist/... databases</ti>
250 <ti>/usr/afs/db</ti>
251 <ti>$(localstatedir)/openafs/db</ti>
252 <ti>/var/lib/openafs/db</ti>
253</tr>
254<tr>
255 <ti>afslogdir</ti>
256 <ti>Log files</ti>
257 <ti>/usr/afs/logs</ti>
258 <ti>$(localstatedir)/openafs/logs</ti>
259 <ti>/var/lib/openafs/logs</ti>
260</tr>
261<tr>
262 <ti>afsbosconfig</ti>
263 <ti>Overseer config</ti>
264 <ti>$(afslocaldir)/BosConfig</ti>
265 <ti>$(afsconfdir)/BosConfig</ti>
266 <ti>/etc/openafs/BosConfig</ti>
267</tr>
268</table>
269
270<p>
271There are some other oddities, like binaries being put in
272<path>/usr/vice/etc</path> in Transarc mode, but this list is not intended
273to be comprehensive. It is rather meant to serve as a reference to those
274troubleshooting config file transition.
275</p>
276
277<p>
278Also as a result of the path changes, the default disk cache location has
279been changed from <path>/usr/vice/cache</path> to
280<path>/var/cache/openafs</path>.
281</p>
282
283<p>
284Furthermore, the init-script has been split into a client and a server part.
285You used to have <path>/etc/init.d/afs</path>, but now you'll end up with both
286<path>/etc/init.d/openafs-client</path> and
287<path>/etc/init.d/openafs-server</path>.
288Consequently, the configuration file <path>/etc/conf.d/afs</path> has been split
289into <path>/etc/conf.d/openafs-client</path> and
290<path>/etc/conf.d/openafs-server</path>. Also, options in
291<path>/etc/conf.d/afs</path> to turn either client or server on or off have
292been obsoleted.
293</p>
294
295<p>
296Another change to the init script is that it doesn't check your disk cache
297setup anymore. The old code required that a separate ext2 partition be
298mounted at <path>/usr/vice/cache</path>. There were some problems with that:
299</p>
300
301<ul>
302 <li>
303 Though it's a very logical setup, your cache doesn't need to be on a
304 separate partition. As long as you make sure that the amount of space
305 specified in <path>/etc/openafs/cacheinfo</path> really is available
306 for disk cache usage, you're safe. So there is no real problem with
307 having the cache on your root partition.
308 </li>
309 <li>
310 Some people use soft-links to point to the real disk cache location.
311 The init script didn't like this, because then this cache location
312 didn't turn up in <path>/proc/mounts</path>.
313 </li>
314 <li>
315 Many prefer ext3 over ext2 nowadays. Both filesystems are valid for
316 usage as a disk cache. Any other filesystem is unsupported
317 (like: don't try reiserfs, you'll get a huge warning, expect failure
318 afterwards).
319 </li>
320</ul>
321
322</body>
323</section>
324<section>
325<title>Transition to the new paths</title>
326<body>
327
328<p>
329First of all, emerging a newer OpenAFS version should not overwrite any old
330configuration files. The script is designed to not change any files
331already present on the system. So even if you have a totally messed up
332configuration with a mix of old and new locations, the script should not
333cause further problems. Also, if a running OpenAFS server is detected, the
334installation will abort, preventing possible database corruption.
335</p>
336
337<p>
338One caveat though -- there have been ebuilds floating around the internet that
339partially disable the protection that Gentoo puts on <path>/etc</path>. These
340ebuilds have never been distributed by Gentoo. You might want to check the
341<c>CONFIG_PROTECT_MASK</c> variable in the output of the following command:
342</p>
343
344<pre caption="Checking your CONFIG_PROTECT_MASK">
345# <i>emerge info | grep "CONFIG_PROTECT_MASK"</i>
346CONFIG_PROTECT_MASK="/etc/gconf /etc/terminfo /etc/texmf/web2c /etc/env.d"
347</pre>
348
349<p>
350Though nothing in this ebuild would touch the files in <path>/etc/afs</path>,
351upgrading will cause the removal of your older OpenAFS installation. Files in
352<c>CONFIG_PROTECT_MASK</c> that belong to the older installation will be removed
353as well.
354</p>
355
356<p>
357It should be clear to the experienced user that in the case he has tweaked his
358system by manually adding soft links (e.g. <path>/usr/afs/etc</path> to
359<path>/etc/openafs</path>), the new installation may run fine while still using
360the old configuration files. In this case, there has been no real transition,
361and cleaning up the old installation will result in a broken OpenAFS config.
362</p>
363
364<p>
365Now that you know what doesn't happen, you may want to know what does:
366</p>
367
368<ul>
369 <li>
370 <path>/usr/afs/etc</path> is copied to <path>/etc/openafs/server</path>
371 </li>
372 <li>
373 <path>/usr/vice/etc</path> is copied to <path>/etc/openafs</path>
374 </li>
375 <li>
376 <path>/usr/afs/local</path> is copied to <path>/var/lib/openafs</path>
377 </li>
378 <li>
379 <path>/usr/afs/local/BosConfig</path> is copied to
380 <path>/etc/openafs/BosConfig</path>, while replacing occurrences of
381 <path>/usr/afs/bin/</path> with <path>/usr/libexec/openafs</path>,
382 <path>/usr/afs/etc</path> with <path>/etc/openafs/server</path>
383 and <path>/usr/afs/bin</path> (without the / as previously) with
384 <path>/usr/bin</path>
385 </li>
386 <li>
387 <path>/usr/afs/db</path> is copied to <path>/var/lib/openafs/db</path>
388 </li>
389 <li>
390 The configuration file <path>/etc/conf.d/afs</path> is copied to
391 <path>/etc/conf.d/openafs-client</path>, as all known old options were
392 destined for client usage only.
393 </li>
394</ul>
395
396</body>
397</section>
398<section>
399<title>The upgrade itself</title>
400<body>
401
402<p>
403So you haven't got an OpenAFS server setup? Or maybe you do, the previous
404sections have informed you about what is going to happen, and you're still
405ready for it?
406</p>
407
408<p>
409Let's go ahead with it then!
410</p>
411
412<p>
413If you do have a server running, you want to shut it down now.
414</p>
415
416<pre caption="Stopping OpenAFS (in case you have a server)">
417# <i>/etc/init.d/afs stop</i>
418</pre>
419
420<p>
421And then the upgrade itself.
422</p>
423
424<pre caption="Now upgrade!">
425# <i>emerge -u openafs</i>
426</pre>
427
428</body>
429</section>
430<section>
431<title>Restarting OpenAFS</title>
432<body>
433
434<p>
435If you had an OpenAFS server running, you would have not have been forced to
436shut it down. Now is the time to do that.
437</p>
438
439<pre caption="Stopping OpenAFS client after upgrade">
440# <i>/etc/init.d/afs stop</i>
441</pre>
442
443<p>
444As you may want keep the downtime to a minimum, so you can restart
445your OpenAFS server right away.
446</p>
447
448<pre caption="Restarting OpenAFS server after upgrade">
449# <i>/etc/init.d/openafs-server start</i>
450</pre>
451
452<p>
453You can check whether it's running properly with the following command:
454</p>
455
456<pre caption="Checking OpenAFS server status">
457# <i>/usr/bin/bos status localhost -localauth</i>
458</pre>
459
460<p>
461Before starting the OpenAFS client again, please take time to check your
462cache settings. They are determined by <path>/etc/openafs/cacheinfo</path>.
463To restart your OpenAFS client installation, please type the following:
464</p>
465
466<pre caption="Restarting OpenAFS client after upgrade">
467# <i>/etc/init.d/openafs-client start</i>
468</pre>
469
470</body>
471</section>
472<section>
473<title>Cleaning up afterwards</title>
474<body>
475
476<p>
477Before cleaning up, please make really sure that everything runs smoothly and
478that you have restarted after the upgrade (otherwise, you may still be running
479your old installation).
480</p>
481
482<impo>
483Please make sure you're not using <path>/usr/vice/cache</path> for disk cache
484if you are deleting <path>/usr/vice</path>!!
485</impo>
486
487<p>
488The following directories may be safely removed from the system:
489</p>
490
491<ul>
492 <li><path>/etc/afs</path></li>
493 <li><path>/usr/vice</path></li>
494 <li><path>/usr/afs</path></li>
495 <li><path>/usr/afsws</path></li>
496</ul>
497
498<p>
499The following files are also unnecessary:
500</p>
501
502<ul>
503 <li><path>/etc/init.d/afs</path></li>
504 <li><path>/etc/conf.d/afs</path></li>
505</ul>
506
507<pre caption="Removing the old files">
508# <i>tar czf /root/oldafs-backup.tgz /etc/afs /usr/vice /usr/afs /usr/afsws</i>
509# <i>rm -R /etc/afs /usr/vice /usr/afs /usr/afsws</i>
510# <i>rm /etc/init.d/afs /etc/conf.d/afs</i>
511</pre>
512
513<p>
514In case you've previously used ebuilds =openafs-1.2.13 or =openafs-1.3.85, you
515may also have some other unnecessary files:
516</p>
517
518<ul>
519 <li><path>/etc/init.d/afs-client</path></li>
520 <li><path>/etc/init.d/afs-server</path></li>
521 <li><path>/etc/conf.d/afs-client</path></li>
522 <li><path>/etc/conf.d/afs-server</path></li>
523</ul>
524
525</body>
526</section>
527<section>
528<title>Init Script changes</title>
529<body>
530
531<p>
532Now most people would have their systems configured to automatically start
533the OpenAFS client and server on startup. Those who don't can safely skip
534this section. If you had your system configured to start them automatically,
535you will need to re-enable this, because the names of the init scripts have
536changed.
537</p>
538
539<pre caption="Re-enabling OpenAFS startup at boot time">
540# <i>rc-update del afs default</i>
541# <i>rc-update add openafs-client default</i>
542# <i>rc-update add openafs-server default</i>
543</pre>
544
545<p>
546If you had <c>=openafs-1.2.13</c> or <c>=openafs-1.3.85</c>, you should remove
547<path>afs-client</path> and <path>afs-server</path> from the default runlevel,
548instead of <path>afs</path>.
549</p>
550
551</body>
552</section>
553<section>
554<title>Troubleshooting: what if the automatic upgrade fails</title>
555<body>
556
557<p>
558Don't panic. You shouldn't have lost any data or configuration files. So let's
559analyze the situation. Please file a bug at <uri
560link="http://bugs.gentoo.org">bugs.gentoo.org</uri> in any case, preferably
561with as much information as possible.
562</p>
563
564<p>
565If you're having problems starting the client, this should help you diagnosing
566the problem:
567</p>
568
569<ul>
570 <li>
571 Run <c>dmesg</c>. The client normally sends error messages there.
572 </li>
573 <li>
574 Check <path>/etc/openafs/cacheinfo</path>. It should be of the form:
575 /afs:{path to disk cache}:{number of blocks for disk cache}.
576 Normally, your disk cache will be located at
577 <path>/var/cache/openafs</path>.
578 </li>
579 <li>
580 Check the output of <c>lsmod</c>. You will want to see a line beginning
581 with the word openafs.
582 </li>
583 <li><c>pgrep afsd</c> will tell you whether afsd is running or not</li>
584 <li>
585 <c>cat /proc/mounts</c> should reveal whether <path>/afs</path> has been
586 mounted.
587 </li>
588</ul>
589
590<p>
591If you're having problems starting the server, then these hints may be useful:
592</p>
593
594<ul>
595 <li>
596 <c>pgrep bosserver</c> tells you whether the overseer is running or not. If
597 you have more than one overseer running, then something has gone wrong. In
598 that case, you should try a graceful OpenAFS server shutdown with <c>bos
599 shutdown localhost -localauth -wait</c>, check the result with <c>bos
600 status localhost -localauth</c>, kill all remaining overseer processes and
601 then finally check whether any server processes are still running (<c>ls
602 /usr/libexec/openafs</c> to get a list of them). Afterwards, do
603 <c>/etc/init.d/openafs-server zap</c> to reset the status of the server and
604 <c>/etc/init.d/openafs-server start</c> to try launching it again.
605 </li>
606 <li>
607 If you're using OpenAFS' own logging system (which is the default setting),
608 check out <path>/var/lib/openafs/logs/*</path>. If you're using the syslog
609 service, go check out its logs for any useful information.
610 </li>
611</ul>
612
613</body>
614</section>
99</chapter> 615</chapter>
100 616
101<chapter> 617<chapter>
102<title>Documentation</title> 618<title>Documentation</title>
103 <section> 619<section>
104 <title>Getting AFS Documentation</title> 620<title>Getting AFS Documentation</title>
105 <body> 621<body>
106 <p> 622
623<p>
107 You can get the original IBM AFS Documentation. It is very well written and you 624You can get the original IBM AFS Documentation. It is very well written and you
108 really want
109 read it if it is up to you to administer a AFS Server. 625really want read it if it is up to you to administer a AFS Server.
110 </p> 626</p>
111<pre> 627
628<pre caption="Installing afsdoc">
112# <i>emerge app-doc/afsdoc</i> 629# <i>emerge app-doc/afsdoc</i>
113</pre> 630</pre>
114 </body> 631
632<p>
633You also have the option of using the documentation delivered with OpenAFS. It
634is installed when you have the USE flag <c>doc</c> enabled while emerging
635OpenAFS. It can be found in <path>/usr/share/doc/openafs-*/</path>. At the time
636of writing, this documentation was a work in progress. It may however document
637newer features in OpenAFS that aren't described in the original IBM AFS
638Documentation.
639</p>
640
641</body>
115 </section> 642</section>
116</chapter> 643</chapter>
117 644
118<chapter> 645<chapter>
119<title>Client Installation</title> 646<title>Client Installation</title>
120 <section> 647<section>
121 <title>Preliminary Work</title> 648<title>Building the Client</title>
122 <body> 649<body>
123 <note> 650
124 All commands should be written in on line !! In this document they are 651<pre caption="Installing openafs">
125 sometimes wrapped to two lines to make them easier to read. 652# <i>emerge net-fs/openafs</i>
126 </note>
127 <note>
128 Unfortunately the AFS Client needs a ext2 partiton for it's cache to run
129 correctly, because there are some locking issues with reiserfs. You need to
130 create a ext2 partition of approx. 200MB (more won't hurt) and mount it to
131 <path>/usr/vice/cache</path>
132 </note>
133 <p>
134 You should adjust the two files CellServDB ans ThisCell before you build the
135 afs client. (These files are in <path>/usr/portage/net-fs/openafs/files</path>)
136 </p>
137 <pre> 653</pre>
654
655<p>
656After successful compilation you're ready to go.
657</p>
658
659</body>
660</section>
661<section>
662<title>A simple global-browsing client installation</title>
663<body>
664
665<p>
666If you're not part of a specific OpenAFS-cell you want to access, and you just
667want to try browsing globally available OpenAFS-shares, then you can just
668install OpenAFS, not touch the configuration at all, and start
669<path>/etc/init.d/openafs-client</path>.
670</p>
671
672</body>
673</section>
674<section>
675<title>Accessing a specific OpenAFS cell</title>
676<body>
677
678<p>
679If you need to access a specific cell, say your university's or company's own
680cell, then some adjustments to your configuration have to be made.
681</p>
682
683<p>
684Firstly, you need to update <path>/etc/openafs/CellServDB</path> with the
685database servers for your cell. This information is normally provided by your
686administrator.
687</p>
688
689<p>
690Secondly, in order to be able to log onto the OpenAFS cell, you need to specify
691its name in <path>/etc/openafs/ThisCell</path>.
692</p>
693
694<pre caption="Adjusting CellServDB and ThisCell">
138 CellServDB: 695CellServDB:
139 >netlabs #Cell name 696>netlabs #Cell name
140 10.0.0.1 #storage 69710.0.0.1 #storage
141 698
142 ThisCell: 699ThisCell:
143 netlabs 700netlabs
144 </pre> 701</pre>
145 <p> 702
703<warn>
704Only use spaces inside the <path>CellServDB</path> file. The client will most
705likely fail if you use TABs.
706</warn>
707
708<p>
146 CellServDB tells your client which server(s) he needs to contact for a 709CellServDB tells your client which server(s) it needs to contact for a
147 specific cell. ThisCell should be quite obvious. Normally you use a name 710specific cell. ThisCell should be quite obvious. Normally you use a name
148 which is unique for your organisation. Your (official) domain might be a 711which is unique for your organisation. Your (official) domain might be a
149 good choice. 712good choice.
150 </p> 713</p>
151 </body> 714
715<p>
716For a quick start, you can now start <path>/etc/init.d/openafs-client</path> and
717use <c>klog</c> to authenticate yourself and start using your access to the
718cell. For automatic logons to you cell, you want to consult the appropriate
719section below.
720</p>
721
722</body>
152 </section> 723</section>
153 <section> 724<section>
154 <title>Building the Client</title> 725<title>Adjusting the cache</title>
155 <body> 726<body>
727
728<note>
729Unfortunately the AFS Client needs a ext2/3 filesystem for its cache to run
730correctly. There are some issues when using other filesystems (using e.g.
731reiserfs is not a good idea).
732</note>
733
156<pre> 734<p>
157<i>emerge net-fs/openafs</i> 735You can house your cache on an existing filesystem (if it's ext2/3), or you
736may want to have a separate partition for that. The default location of the
737cache is <path>/var/cache/openafs</path>, but you can change that by editing
738<path>/etc/openafs/cacheinfo</path>. A standard size for your cache is
739200MB, but more won't hurt.
158</pre> 740</p>
159 <p> 741
160 After successfull compilation you're ready to go. 742</body>
161 </p>
162 </body>
163 </section> 743</section>
164 <section> 744<section>
165 <title>Starting afs on startup</title> 745<title>Starting AFS on startup</title>
166 <body> 746<body>
167 <p> 747
748<p>
168 The following command will create the appropriate links to start your afs client 749The following command will create the appropriate links to start your afs
169 on system startup. 750client on system startup.
170 </p> 751</p>
171 <warn> 752
753<warn>
172 You should always have a running afs server in your domain when trying to start the afs client. You're system won't boot 754You should always have a running afs server in your domain when trying to start
173 until it gets some timeout if your afs server is down. (and this is quite a long long time) 755the afs client. Your system won't boot until it gets some timeout if your AFS
174 </warn> 756server is down (and this is quite a long long time.)
757</warn>
758
759<pre caption="Adding AFS client to the default runlevel">
760# <i>rc-update add openafs-client default</i>
175<pre> 761</pre>
176# <i>rc-update add afs default</i> 762
177</pre> 763</body>
178 </body>
179 </section> 764</section>
180</chapter> 765</chapter>
181 766
182<chapter> 767<chapter>
183<title>Server Installation</title> 768<title>Server Installation</title>
184 <section> 769<section>
185 <title>Building the Server</title> 770<title>Building the Server</title>
186 <body> 771<body>
187 <p> 772
188 The follwing command will install all necessary binaries for setting up a AFS Server 773<note>
189 <i>and</i> Client 774All commands should be written in one line!! In this document they are
190 </p> 775sometimes wrapped to two lines to make them easier to read.
776</note>
777
191<pre> 778<p>
779If you haven't already done so, the following command will install all
780necessary binaries for setting up an AFS Server <e>and</e> Client.
781</p>
782
783<pre caption="Installing openafs">
192# <i>emerge net-fs/openafs</i> 784# <i>emerge net-fs/openafs</i>
193</pre> 785</pre>
194 </body> 786
787</body>
195 </section> 788</section>
196 <section> 789<section>
197 <title>Starting AFS Server</title> 790<title>Starting AFS Server</title>
198 <body> 791<body>
199 <p> 792
200 You need to remove the sample CellServDB and ThisCell file first.
201 </p>
202<pre> 793<p>
203# <i>rm /usr/vice/etc/ThisCell</i>
204# <i>rm /usr/vice/etc/CellServDB</i>
205</pre>
206 <p>
207 Next you will run the <b>bosserver</b> command to initialize the Basic OverSeer (BOS) 794You need to run the <c>bosserver</c> command to initialize the Basic OverSeer
208 Server, which monitors and controls other AFS server processes on its server 795(BOS) Server, which monitors and controls other AFS server processes on its
209 machine. Think of it as init for the system. Include the <b>-noauth</b> 796server machine. Think of it as init for the system. Include the <c>-noauth</c>
210 flag to disable authorization checking, since you haven't added the admin user yet. 797flag to disable authorization checking, since you haven't added the admin user
211 </p> 798yet.
212 <p> 799</p>
213 <warn> 800
801<warn>
214 Disabling authorization checking gravely compromises cell security. 802Disabling authorization checking gravely compromises cell security. You must
215 You must complete all subsequent steps in one uninterrupted pass 803complete all subsequent steps in one uninterrupted pass and must not leave
216 and must not leave the machine unattended until you restart the BOS Server with 804the machine unattended until you restart the BOS Server with authorization
217 authorization checking enabled. Well this is what the AFS documentation says :) 805checking enabled. Well, this is what the AFS documentation says. :)
218 </warn> 806</warn>
219 </p> 807
808<pre caption="Initialize the Basic OverSeer Server">
809# <i>bosserver -noauth &amp;</i>
220<pre> 810</pre>
221# <i>/usr/afs/bin/bosserver -noauth &amp;</i> 811
222</pre> 812<p>
223 <p>
224 Verify that the BOS Server created <path>/usr/vice/etc/CellServDB</path> 813Verify that the BOS Server created <path>/etc/openafs/server/CellServDB</path>
225 and <path>/usr/vice/etc/ThisCell</path> 814and <path>/etc/openafs/server/ThisCell</path>
226 </p> 815</p>
227<pre> 816
228# <i>ls -al /usr/vice/etc/</i> 817<pre caption="Check if CellServDB and ThisCell are created">
818# <i>ls -al /etc/openafs/server/</i>
229-rw-r--r-- 1 root root 41 Jun 4 22:21 CellServDB 819-rw-r--r-- 1 root root 41 Jun 4 22:21 CellServDB
230-rw-r--r-- 1 root root 7 Jun 4 22:21 ThisCell 820-rw-r--r-- 1 root root 7 Jun 4 22:21 ThisCell
231</pre> 821</pre>
232 822
233 </body> 823</body>
234 </section> 824</section>
235 <section> 825<section>
236 <title>Defining Cell Name and Membership for Server Process</title> 826<title>Defining Cell Name and Membership for Server Process</title>
237 <body> 827<body>
238 <p> 828
829<p>
239 Now assign your cells name. 830Now assign your cell's name.
240 </p> 831</p>
241 <p> 832
242 <impo>There are some restrictions on the name format. 833<impo>
243 Two of the most important restrictions are that the name 834There are some restrictions on the name format. Two of the most important
244 cannot include uppercase letters or more than 64 characters. Remember that 835restrictions are that the name cannot include uppercase letters or more than
245 your cell name will show up under <path>/afs</path>, so you might want to choose 83664 characters. Remember that your cell name will show up under
246 a short one.</impo> 837<path>/afs</path>, so you might want to choose a short one.
247 </p> 838</impo>
248 <p> 839
840<note>
249 <note>In the following and every instruction in this guide, for the <i>&lt;server name&gt;</i> 841In the following and every instruction in this guide, for the &lt;server
250 argument substitute the full-qualified hostname 842name&gt; argument substitute the full-qualified hostname (such as
251 (such as <b>afs.gentoo.org</b>) of the machine you are installing. 843<b>afs.gentoo.org</b>) of the machine you are installing. For the &lt;cell
252 For the <i>&lt;cell name&gt;</i>
253 argument substitute your cell's complete name (such as <b>gentoo</b>)</note> 844name&gt; argument substitute your cell's complete name (such as
254 </p> 845<b>gentoo</b>)
255 <p> 846</note>
847
848<p>
256 Run the <b>bos setcellname</b> command to set the cell name: 849Run the <c>bos setcellname</c> command to set the cell name:
257 </p> 850</p>
851
852<pre caption="Set the cell name">
853# <i>bos setcellname &lt;server name&gt; &lt;cell name&gt; -noauth</i>
258<pre> 854</pre>
259 # <i>/usr/afs/bin/bos setcellname &lt;server name&gt; &lt;cell name&gt; -noauth</i> 855
260</pre>
261 </body> 856</body>
262 </section> 857</section>
263 <section> 858<section>
264 <title>Starting the Database Server Process</title> 859<title>Starting the Database Server Process</title>
265 <body><p> 860<body>
861
862<p>
266 Next use the <b>bos create</b> command to create entries for the four database 863Next use the <c>bos create</c> command to create entries for the four database
267 server processes in the 864server processes in the <path>/etc/openafs/BosConfig</path> file. The four
268 <path>/usr/afs/local/BosConfig</path> file. The four processes run on database 865processes run on database server machines only.
269 server machines only. 866</p>
270 </p> 867
271 <p> 868<table>
272 <table> 869<tr>
273 <tr>
274 <ti>kaserver</ti> 870 <ti>kaserver</ti>
871 <ti>
275 <ti>The Authentification Server maintains the Authentification Database. 872 The Authentication Server maintains the Authentication Database.
276 This can be replaced by a Kerberos 5 daemon. If anybody want's to try that 873 This can be replaced by a Kerberos 5 daemon. If anybody wants to try that
277 feel free to update this document :)</ti> 874 feel free to update this document :)
278 </tr> 875 </ti>
279 <tr> 876</tr>
877<tr>
280 <ti>buserver</ti> 878 <ti>buserver</ti>
281 <ti>The Backup Server maintains the Backup Database</ti> 879 <ti>The Backup Server maintains the Backup Database</ti>
282 </tr> 880</tr>
283 <tr> 881<tr>
284 <ti>ptserver</ti> 882 <ti>ptserver</ti>
285 <ti>The Protection Server maintains the Protection Database</ti> 883 <ti>The Protection Server maintains the Protection Database</ti>
286 </tr> 884</tr>
287 <tr> 885<tr>
288 <ti>vlserver</ti> 886 <ti>vlserver</ti>
887 <ti>
289 <ti>The Volume Location Server maintains the Volume Location Database (VLDB). 888 The Volume Location Server maintains the Volume Location Database (VLDB).
290 Very important :)</ti> 889 Very important :)
291 </tr> 890 </ti>
292 </table> 891</tr>
293 </p> 892</table>
893
894<pre caption="Create entries for the database processes">
895# <i>bos create &lt;server name&gt; kaserver \
896simple /usr/libexec/openafs/kaserver \
897-cell &lt;cell name&gt; -noauth</i>
898# <i>bos create &lt;server name&gt; buserver \
899simple /usr/libexec/openafs/buserver \
900-cell &lt;cell name&gt; -noauth</i>
901# <i>bos create &lt;server name&gt; ptserver \
902simple /usr/libexec/openafs/ptserver \
903-cell &lt;cell name&gt; -noauth</i>
904# <i>bos create &lt;server name&gt; \
905vlserver simple /usr/libexec/openafs/vlserver \
906-cell &lt;cell name&gt; -noauth</i>
294<pre> 907</pre>
295# <i>/usr/afs/bin/bos create &lt;server name&gt; kaserver simple 908
296 /usr/afs/bin/kaserver -cell &lt;cell name&gt; -noauth</i> 909<p>
297# <i>/usr/afs/bin/bos create &lt;server name&gt; buserver simple
298 /usr/afs/bin/buserver -cell &lt;cell name&gt; -noauth</i>
299# <i>/usr/afs/bin/bos create &lt;server name&gt; ptserver simple
300 /usr/afs/bin/ptserver -cell &lt;cell name&gt; -noauth</i>
301# <i>/usr/afs/bin/bos create &lt;server name&gt; vlserver simple
302 /usr/afs/bin/vlserver -cell &lt;cell name&gt; -noauth</i>
303</pre>
304 <p>
305 You can verify that all servers are running with the <b>bos status</b> command: 910You can verify that all servers are running with the <c>bos status</c> command:
306 </p> 911</p>
307<pre> 912
913<pre caption="Check if all the servers are running">
308# <i>/usr/afs/bin/bos status &lt;server name&gt; -noauth</i> 914# <i>bos status &lt;server name&gt; -noauth</i>
309Instance kaserver, currently running normally. 915Instance kaserver, currently running normally.
310Instance buserver, currently running normally. 916Instance buserver, currently running normally.
311Instance ptserver, currently running normally. 917Instance ptserver, currently running normally.
312Instance vlserver, currently running normally. 918Instance vlserver, currently running normally.
313</pre> 919</pre>
314 920
315 </body> 921</body>
316 </section> 922</section>
317 <section> 923<section>
318 <title>Initializing Cell Security</title> 924<title>Initializing Cell Security</title>
319 <body> 925<body>
320 <p> 926
927<p>
321 Now we'll initialize the cell's security mechanisms. We'll begin by creating the 928Now we'll initialize the cell's security mechanisms. We'll begin by creating
322 following two initial entries in the 929the following two initial entries in the Authentication Database: The main
323 Authentification Database: The main administrative account, called <b>admin</b> by 930administrative account, called <b>admin</b> by convention and an entry for
324 convention and an entry for
325 the AFS server processes, called <b>afs</b>. No user logs in under the 931the AFS server processes, called <c>afs</c>. No user logs in under the
326 identity <b>afs</b>, but the Authentication 932identity <b>afs</b>, but the Authentication Server's Ticket Granting
327 Server's Ticket Granting Service (TGS) module uses the account 933Service (TGS) module uses the account to encrypt the server tickets that
328 to encrypt the server tickets that it grants to AFS clients. This sounds 934it grants to AFS clients. This sounds pretty much like Kerberos :)
329 pretty much like Kerberos :) 935</p>
330 </p> 936
331 <p> 937<p>
332 Enter <b>kas</b> interactive mode 938Enter <c>kas</c> interactive mode
333 </p> 939</p>
334<pre> 940
941<pre caption="Entering the interactive mode">
335# <i>/usr/afs/bin/kas -cell &lt;cell name&gt; -noauth</i> 942# <i>kas -cell &lt;cell name&gt; -noauth</i>
336ka&gt; <i>create afs</i> 943ka&gt; <i>create afs</i>
337initial_password: 944initial_password:
338Verifying, please re-enter initial_password: 945Verifying, please re-enter initial_password:
339ka&gt; <i>create admin</i> 946ka&gt; <i>create admin</i>
340initial_password: 947initial_password:
341Verifying, please re-enter initial_password: 948Verifying, please re-enter initial_password:
342ka&gt; <i>examine afs</i> 949ka&gt; <i>examine afs</i>
343 950
344User data for afs 951User data for afs
345 key (0) cksum is 2651715259, last cpw: Mon Jun 4 20:49:30 2001 952key (0) cksum is 2651715259, last cpw: Mon Jun 4 20:49:30 2001
346 password will never expire. 953password will never expire.
347 An unlimited number of unsuccessful authentications is permitted. 954An unlimited number of unsuccessful authentications is permitted.
348 entry never expires. Max ticket lifetime 100.00 hours. 955entry never expires. Max ticket lifetime 100.00 hours.
349 last mod on Mon Jun 4 20:49:30 2001 by $lt;none&gt; 956last mod on Mon Jun 4 20:49:30 2001 by &lt;none&gt;
350 permit password reuse 957permit password reuse
351ka&gt; <i>setfields admin -flags admin</i> 958ka&gt; <i>setfields admin -flags admin</i>
352ka&gt; <i>examine admin</i> 959ka&gt; <i>examine admin</i>
353 960
354User data for admin (ADMIN) 961User data for admin (ADMIN)
355 key (0) cksum is 2651715259, last cpw: Mon Jun 4 20:49:59 2001 962key (0) cksum is 2651715259, last cpw: Mon Jun 4 20:49:59 2001
356 password will never expire. 963password will never expire.
357 An unlimited number of unsuccessful authentications is permitted. 964An unlimited number of unsuccessful authentications is permitted.
358 entry never expires. Max ticket lifetime 25.00 hours. 965entry never expires. Max ticket lifetime 25.00 hours.
359 last mod on Mon Jun 4 20:51:10 2001 by $lt;none&gt; 966last mod on Mon Jun 4 20:51:10 2001 by &lt;none&gt;
360 permit password reuse 967permit password reuse
361ka&gt; 968ka&gt;
362</pre> 969</pre>
363 <p> 970
971<p>
364 Run the <b>bos adduser</b> command, to add the <b>admin</b> user to 972Run the <c>bos adduser</c> command, to add the <b>admin</b> user to
365 the <path>/usr/afs/etc/UserList</path>. 973the <path>/etc/openafs/server/UserList</path>.
366 </p> 974</p>
367<pre> 975
976<pre caption="Add the admin user to the UserList">
368# <i>/usr/afs/bin/bos adduser &lt;server name&gt; admin -cell &lt;cell name&gt; -noauth</i> 977# <i>bos adduser &lt;server name&gt; admin -cell &lt;cell name&gt; -noauth</i>
369</pre> 978</pre>
370 <p> 979
980<p>
371 Issue the <b>bos addkey</b> command to define the AFS Server 981Issue the <c>bos addkey</c> command to define the AFS Server
372 encryption key in <path>/usr/afs/etc/KeyFile</path> 982encryption key in <path>/etc/openafs/server/KeyFile</path>
373 </p> 983</p>
374 <note> 984
985<note>
375 If asked for the input key, give the password you entered when creating 986If asked for the input key, give the password you entered when creating
376 the afs entry with <b>kas</b> 987the AFS entry with <c>kas</c>
377 </note> 988</note>
378<pre> 989
990<pre caption="Entering the password">
379# <i>/usr/afs/bin/bos addkey &lt;server name&gt; -kvno 0 -cell &lt;cell name&gt; -noauth</i> 991# <i>bos addkey &lt;server name&gt; -kvno 0 -cell &lt;cell name&gt; -noauth</i>
380 input key: 992input key:
381 Retype input key: 993Retype input key:
382</pre>
383 <p>
384 Issue the <b>pts createuser</b> command to create a Protection Database
385 entry for the admin user
386 </p>
387 <note>
388 By default, the Protection Server assigns AFS UID 1 to the <b>admin</b> user, because
389 it is the first user
390 entry you are creating. If the local password file (/etc/passwd or equivalent)
391 already has an entry for
392 <b>admin</b> that assigns a different UID use the <b>-id</b> argument
393 to create matching UID's
394 </note>
395<pre> 994</pre>
995
996<p>
997Issue the <c>pts createuser</c> command to create a Protection Database entry
998for the admin user.
999</p>
1000
1001<note>
1002By default, the Protection Server assigns AFS UID 1 to the <b>admin</b> user,
1003because it is the first user entry you are creating. If the local password file
1004(<path>/etc/passwd</path> or equivalent) already has an entry for <b>admin</b>
1005that assigns a different UID use the <c>-id</c> argument to create matching
1006UIDs.
1007</note>
1008
1009<pre caption="Create a Protection Database entry for the database user">
396# <i>/usr/afs/bin/pts createuser -name admin -cell &lt;cell name&gt; [-id &lt;AFS UID&gt;] -noauth</i> 1010# <i>pts createuser -name admin -cell &lt;cell name&gt; [-id &lt;AFS UID&gt;] -noauth</i>
397</pre> 1011</pre>
398 <p> 1012
1013<p>
399 Issue the <b>pts adduser</b> command to make the <b>admin</b> user a member 1014Issue the <c>pts adduser</c> command to make the <b>admin</b> user a member
400 of the system:administrators group, 1015of the system:administrators group, and the <c>pts membership</c> command to
401 and the <b>pts membership</b> command to verify the new membership> 1016verify the new membership
402 </p> 1017</p>
403<pre> 1018
1019<pre caption="Make admin a member of the administrators group and verify">
404# <i>/usr/afs/bin/pts adduser admin system:administrators -cell &lt;cell name&gt; -noauth</i> 1020# <i>pts adduser admin system:administrators -cell &lt;cell name&gt; -noauth</i>
405# <i>/usr/afs/bin/pts membership admin -cell &lt;cell name&gt; -noauth</i> 1021# <i>pts membership admin -cell &lt;cell name&gt; -noauth</i>
406 Groups admin (id: 1) is a member of: 1022Groups admin (id: 1) is a member of:
407 system:administrators 1023system:administrators
408</pre>
409 <p>
410 Restart all AFS Server processes
411 </p>
412<pre> 1024</pre>
1025
1026</body>
1027</section>
1028<section>
1029<title>Properly (re-)starting the AFS server</title>
1030<body>
1031
1032<p>
1033At this moment, proper authentication is possible, and the OpenAFS server can
1034be started in a normal fashion. Note that authentication also requires a
1035running OpenAFS client (setting it up is described in the previous chapter).
1036<!-- Left out because deemed confusing>
1037Continuing without this step is possible, but in that case a quick restart of
1038the server is required, as demonstrated at the end of this section.
1039<-->
1040</p>
1041
1042<pre caption="Shutdown bosserver">
1043# <i>bos shutdown &lt;server name&gt; -wait -noauth</i>
1044# <i>killall bosserver</i>
1045</pre>
1046
1047<pre caption="Normal OpenAFS server (and client) startup">
1048# <i>/etc/init.d/openafs-server start</i>
1049# <i>/etc/init.d/openafs-client start</i>
1050</pre>
1051
1052<pre caption="Adding AFS server to the default runlevel">
1053# <i>rc-update add openafs-server default</i>
1054</pre>
1055
1056<pre caption="Getting a token as the admin user">
1057# <i>klog admin</i>
1058</pre>
1059
1060<!-- Left out because deemed confusing>
1061<p>
1062If you chose not to restart OpenAFS without the -noauth flag, you can simply
1063perform the following procedure instead:
1064</p>
1065
1066<pre caption="Restart all AFS server processes">
413# <i>/usr/afs/bin/bos restart &lt;server name&gt; -all -cell &lt;cell name&gt; -noauth</i> 1067# <i>bos restart &lt;server name&gt; -all -cell &lt;cell name&gt; -noauth</i>
414</pre> 1068</pre>
1069<-->
1070
415 </body> 1071</body>
416 </section> 1072</section>
417 <section> 1073<section>
418 <title>Starting the File Server, Volume Server and Salvager</title> 1074<title>Starting the File Server, Volume Server and Salvager</title>
419 <body> 1075<body>
420 <p> 1076
1077<p>
421 Start the <b>fs</b> process, which consists of the File Server, Volume Server and Salavager (fileserver, 1078Start the <c>fs</c> process, which consists of the File Server, Volume Server
422 volserver and salvager processes). 1079and Salvager (fileserver, volserver and salvager processes).
423 </p> 1080</p>
1081
1082<pre caption="Start the fs process">
1083# <i>bos create &lt;server name&gt; fs \
1084fs /usr/libexec/openafs/fileserver /usr/libexec/openafs/volserver /usr/libexec/openafs/salvager \
1085-cell &lt;cell name&gt; -noauth</i>
424<pre> 1086</pre>
425# <i>/usr/afs/bin/bos create &lt;server name&gt; fs fs /usr/afs/bin/fileserver 1087
426 /usr/afs/bin/volserver 1088<p>
427 /usr/afs/bin/salvager
428 -cell &lt;cell name&gt; -noauth</i>
429</pre>
430 <p>
431 Verify that all processes are running 1089Verify that all processes are running:
432 </p> 1090</p>
433<pre> 1091
1092<pre caption="Check if all processes are running">
434 # <i>/usr/afs/bin/bos status &lt;server name&gt; -long -noauth</i> 1093# <i>bos status &lt;server name&gt; -long -noauth</i>
435 Instance kaserver, (type is simple) currently running normally. 1094Instance kaserver, (type is simple) currently running normally.
436 Process last started at Mon Jun 4 21:07:17 2001 (2 proc starts) 1095Process last started at Mon Jun 4 21:07:17 2001 (2 proc starts)
437 Last exit at Mon Jun 4 21:07:17 2001 1096Last exit at Mon Jun 4 21:07:17 2001
438 Command 1 is '/usr/afs/bin/kaserver' 1097Command 1 is '/usr/libexec/openafs/kaserver'
439 1098
440 Instance buserver, (type is simple) currently running normally. 1099Instance buserver, (type is simple) currently running normally.
441 Process last started at Mon Jun 4 21:07:17 2001 (2 proc starts) 1100Process last started at Mon Jun 4 21:07:17 2001 (2 proc starts)
442 Last exit at Mon Jun 4 21:07:17 2001 1101Last exit at Mon Jun 4 21:07:17 2001
443 Command 1 is '/usr/afs/bin/buserver' 1102Command 1 is '/usr/libexec/openafs/buserver'
444 1103
445 Instance ptserver, (type is simple) currently running normally. 1104Instance ptserver, (type is simple) currently running normally.
446 Process last started at Mon Jun 4 21:07:17 2001 (2 proc starts) 1105Process last started at Mon Jun 4 21:07:17 2001 (2 proc starts)
447 Last exit at Mon Jun 4 21:07:17 2001 1106Last exit at Mon Jun 4 21:07:17 2001
448 Command 1 is '/usr/afs/bin/ptserver' 1107Command 1 is '/usr/libexec/openafs/ptserver'
449 1108
450 Instance vlserver, (type is simple) currently running normally. 1109Instance vlserver, (type is simple) currently running normally.
451 Process last started at Mon Jun 4 21:07:17 2001 (2 proc starts) 1110Process last started at Mon Jun 4 21:07:17 2001 (2 proc starts)
452 Last exit at Mon Jun 4 21:07:17 2001 1111Last exit at Mon Jun 4 21:07:17 2001
453 Command 1 is '/usr/afs/bin/vlserver' 1112Command 1 is '/usr/libexec/openafs/vlserver'
454 1113
455 Instance fs, (type is fs) currently running normally. 1114Instance fs, (type is fs) currently running normally.
456 Auxiliary status is: file server running. 1115Auxiliary status is: file server running.
457 Process last started at Mon Jun 4 21:09:30 2001 (2 proc starts) 1116Process last started at Mon Jun 4 21:09:30 2001 (2 proc starts)
458 Command 1 is '/usr/afs/bin/fileserver' 1117Command 1 is '/usr/libexec/openafs/fileserver'
459 Command 2 is '/usr/afs/bin/volserver' 1118Command 2 is '/usr/libexec/openafs/volserver'
460 Command 3 is '/usr/afs/bin/salvager' 1119Command 3 is '/usr/libexec/openafs/salvager'
461</pre> 1120</pre>
462 <p> 1121
1122<p>
463 Your next action depends on whether you have ever run AFS file server machines 1123Your next action depends on whether you have ever run AFS file server machines
464 in the cell: 1124in the cell.
465 </p> 1125</p>
466 <p> 1126
1127<p>
467 If you are installing the first AFS Server ever in the cell create the 1128If you are installing the first AFS Server ever in the cell, create the first
468 first AFS volume, <b>root.afs</b> 1129AFS volume, <b>root.afs</b>
469 </p> 1130</p>
1131
470 <note> 1132<note>
471 For the partition name argument, substitute the name of one of the machine's 1133For the partition name argument, substitute the name of one of the machine's
472 AFS Server partitions. By convention 1134AFS Server partitions. Any filesystem mounted under a directory called
473 these partitions are named <path>/vicex</path>, where x is in the range of a-z. 1135<path>/vicepx</path>, where x is in the range of a-z, will be considered and
1136used as an AFS Server partition. Any unix filesystem will do (as opposed to the
1137client's cache, which can only be ext2/3). Tip: the server checks for each
1138<path>/vicepx</path> mount point whether a filesystem is mounted there. If not,
1139the server will not attempt to use it. This behaviour can be overridden by
1140putting a file named <path>AlwaysAttach</path> in this directory.
474 </note> 1141</note>
1142
1143<pre caption="Create the root.afs volume">
1144# <i>vos create &lt;server name&gt; &lt;partition name&gt; root.afs -cell &lt;cell name&gt; -noauth</i>
475<pre> 1145</pre>
476 # <i>/usr/afs/bin/vos create &lt;server name&gt; 1146
477 &lt;partition name&gt; root.afs 1147<p>
478 -cell &lt;cell name&gt; -noauth</i>
479</pre>
480 <p>
481 If there are existing AFS file server machines and volumes in the cell 1148If there are existing AFS file server machines and volumes in the cell
482 issue the <b>vos sncvldb</b> and <b>vos 1149issue the <c>vos sncvldb</c> and <c>vos syncserv</c> commands to synchronize
483 syncserv</b> commands to synchronize the VLDB (Volume Location Database) with 1150the VLDB (Volume Location Database) with the actual state of volumes on the
484 the actual state of volumes on the local machine. This will copy all necessary data to your 1151local machine. This will copy all necessary data to your new server.
485 new server. 1152</p>
486 </p> 1153
487<pre> 1154<p>
1155If the command fails with the message "partition /vicepa does not exist on
1156the server", ensure that the partition is mounted before running OpenAFS
1157servers, or mount the directory and restart the processes using
1158<c>bos restart &lt;server name&gt; -all -cell &lt;cell
1159name&gt; -noauth</c>.
1160</p>
1161
1162<pre caption="Synchronise the VLDB">
488 # <i>/usr/afs/bin/vos syncvldb &lt;server name&gt; -cell &lt;cell name&gt; -verbose -noauth</i> 1163# <i>vos syncvldb &lt;server name&gt; -cell &lt;cell name&gt; -verbose -noauth</i>
489 # <i>/usr/afs/bin/vos syncserv &lt;server name&gt; -cell &lt;cell name&gt; -verbose -noauth</i> 1164# <i>vos syncserv &lt;server name&gt; -cell &lt;cell name&gt; -verbose -noauth</i>
490</pre> 1165</pre>
1166
491 </body> 1167</body>
492 </section> 1168</section>
493 <section> 1169<section>
494 <title>Starting the Server Portion of the Update Server</title> 1170<title>Starting the Server Portion of the Update Server</title>
495 <body> 1171<body>
496<pre> 1172
1173<pre caption="Start the update server">
497# <i>/usr/afs/bin/bos create &lt;server name&gt; 1174# <i>bos create &lt;server name&gt; \
498 upserver simple "/usr/afs/bin/upserver 1175upserver simple "/usr/libexec/openafs/upserver \
499 -crypt /usr/afs/etc -clear /usr/afs/bin" 1176-crypt /etc/openafs/server -clear /usr/libexec/openafs" \
500 -cell &lt;cell name&gt; -noauth</i> 1177-cell &lt;cell name&gt; -noauth</i>
501</pre> 1178</pre>
1179
502 </body> 1180</body>
503 </section> 1181</section>
504 <section> 1182<section>
505 <title>Configuring the Top Level of the AFS filespace</title> 1183<title>Configuring the Top Level of the AFS filespace</title>
506 <body> 1184<body>
507 <p> 1185
1186<p>
508 First you need to set some acl's, so that any user can lookup <path>/afs</path>. 1187First you need to set some ACLs, so that any user can lookup
509 </p> 1188<path>/afs</path>.
1189</p>
1190
1191<note>
1192The default OpenAFS client configuration has <b>dynroot</b> enabled.
1193This option turns <path>/afs</path> into a virtual directory composed of the
1194contents of your <path>/etc/openafs/CellServDB</path> file. As such, the
1195following command will not work, because it requires a real AFS directory.
1196You can temporarily switch dynroot off by setting <b>ENABLE_DYNROOT</b> to
1197<b>no</b> in <path>/etc/conf.d/openafs-client</path>. Don't forget to issue
1198a client restart after changing parameters.
1199</note>
1200
1201<pre caption="Set access control lists">
1202# <i>fs setacl /afs system:anyuser rl</i>
510<pre> 1203</pre>
511# <i>/usr/afs/bin/fs setacl /afs system:anyuser rl</i> 1204
1205<p>
1206Then you need to create the root volume, mount it readonly on
1207<path>/afs/&lt;cell name&gt;</path> and read/write on <path>/afs/.&lt;cell
1208name&gt;</path>.
512</pre> 1209</p>
513 <p> 1210
514 The you need to create the root volume, mount it readonly on <path>/afs/&lt;cell name&gt;</path> and read/write 1211<pre caption="Prepare the root volume">
515 on <path>/afs/.&lt;cell name&gt;</path>
516<pre>
517# <i>/usr/afs/bin/vos create &lt;server name&gt;&lt;partition name&gt; root.cell</i> 1212# <i>vos create &lt;server name&gt; &lt;partition name&gt; root.cell</i>
518# <i>/usr/afs/bin/fs mkmount /afs/&lt;cell name&gt; root.cell </i> 1213# <i>fs mkmount /afs/&lt;cell name&gt; root.cell</i>
519# <i>/usr/afs/bin/fs setacl /afs/&lt;cell name&gt; system:anyuser rl</i> 1214# <i>fs setacl /afs/&lt;cell name&gt; system:anyuser rl</i>
520# <i>/usr/afs/bin/fs mkmount /afs/.&lt;cell name&gt; root.cell -rw</i> 1215# <i>fs mkmount /afs/.&lt;cell name&gt; root.cell -rw</i>
521</pre> 1216</pre>
522 </p> 1217
523 <p> 1218<pre caption="Adding volumes underneath">
1219# <i>vos create &lt;server name&gt; &lt;partition name&gt; &lt;myvolume&gt;</i>
1220# <i>fs mkmount /afs/&lt;cell name&gt;/&lt;mymountpoint&gt; &lt;myvolume&gt;</i>
1221# <i>fs mkmount /afs/&lt;cell name&gt;/.&lt;mymountpoint&gt; &lt;myvolume&gt; -rw</i>
1222# <i>fs setquota /afs/&lt;cell name&gt;/.&lt;mymountpoint&gt; -max &lt;quotum&gt;</i>
1223</pre>
1224
1225<p>
524 Finally you're done !!! You should now have a working AFS file server 1226Finally you're done!!! You should now have a working AFS file server
525 on your local network. Time to get a big 1227on your local network. Time to get a big
526 cup of coffee and print out the AFS documentation !!! 1228cup of coffee and print out the AFS documentation!!!
527 </p> 1229</p>
528 <note> 1230
1231<note>
529 It is very important for the AFS server to function properly, that all system 1232It is very important for the AFS server to function properly, that all system
530 clock's are synchronized. 1233clocks are synchronized. This is best accomplished by installing a ntp server
531 This is best 1234on one machine (e.g. the AFS server) and synchronize all client clocks
532 accomplished by installing a ntp server on one machine (e.g. the AFS server)
533 and synchronize all client clock's
534 with the ntp client. This can also be done by the afs client. 1235with the ntp client. This can also be done by the AFS client.
535 </note> 1236</note>
1237
536 </body> 1238</body>
537 </section> 1239</section>
538
539</chapter> 1240</chapter>
540 1241
541<chapter> 1242<chapter>
542 <title>Basic Administration</title> 1243<title>Basic Administration</title>
543 <section> 1244<section>
544 <title></title> 1245<title>Disclaimer</title>
545 <body> 1246<body>
546 <p>To be done ... For now read the AFS Documentation :)</p> 1247
1248<p>
1249OpenAFS is an extensive technology. Please read the AFS documentation for more
1250information. We only list a few administrative tasks in this chapter.
1251</p>
1252
547 </body> 1253</body>
548 </section> 1254</section>
1255<section>
1256<title>Configuring PAM to Acquire an AFS Token on Login</title>
1257<body>
1258
1259<p>
1260To use AFS you need to authenticate against the KA Server if using
1261an implementation AFS Kerberos 4, or against a Kerberos 5 KDC if using
1262MIT, Heimdal, or ShiShi Kerberos 5. However in order to login to a
1263machine you will also need a user account, this can be local in
1264<path>/etc/passwd</path>, NIS, LDAP (OpenLDAP), or a Hesiod database.
1265PAM allows Gentoo to tie the authentication against AFS and login to the
1266user account.
1267</p>
1268
1269<p>
1270You will need to update <path>/etc/pam.d/system-auth</path> which is
1271used by the other configurations. "use_first_pass" indicates it will be
1272checked first against the user login, and "ignore_root" stops the local
1273superuser being checked so as to order to allow login if AFS or the network
1274fails.
1275</p>
1276
1277<pre caption="/etc/pam.d/system-auth">
1278auth required pam_env.so
1279auth sufficient pam_unix.so likeauth nullok
1280auth sufficient pam_afs.so.1 use_first_pass ignore_root
1281auth required pam_deny.so
1282
1283account required pam_unix.so
1284
1285password required pam_cracklib.so retry=3
1286password sufficient pam_unix.so nullok md5 shadow use_authtok
1287password required pam_deny.so
1288
1289session required pam_limits.so
1290session required pam_unix.so
1291</pre>
1292
1293<p>
1294In order for <c>sudo</c> to keep the real user's token and to prevent local
1295users gaining AFS access change <path>/etc/pam.d/su</path> as follows:
1296</p>
1297
1298<pre caption="/etc/pam.d/su">
1299<comment># Here, users with uid &gt; 100 are considered to belong to AFS and users with
1300# uid &lt;= 100 are ignored by pam_afs.</comment>
1301auth sufficient pam_afs.so.1 ignore_uid 100
1302
1303auth sufficient pam_rootok.so
1304
1305<comment># If you want to restrict users begin allowed to su even more,
1306# create /etc/security/suauth.allow (or to that matter) that is only
1307# writable by root, and add users that are allowed to su to that
1308# file, one per line.
1309#auth required pam_listfile.so item=ruser \
1310# sense=allow onerr=fail file=/etc/security/suauth.allow
1311
1312# Uncomment this to allow users in the wheel group to su without
1313# entering a passwd.
1314#auth sufficient pam_wheel.so use_uid trust
1315
1316# Alternatively to above, you can implement a list of users that do
1317# not need to supply a passwd with a list.
1318#auth sufficient pam_listfile.so item=ruser \
1319# sense=allow onerr=fail file=/etc/security/suauth.nopass
1320
1321# Comment this to allow any user, even those not in the 'wheel'
1322# group to su</comment>
1323auth required pam_wheel.so use_uid
1324
1325auth required pam_stack.so service=system-auth
1326
1327account required pam_stack.so service=system-auth
1328
1329password required pam_stack.so service=system-auth
1330
1331session required pam_stack.so service=system-auth
1332session optional pam_xauth.so
1333
1334<comment># Here we prevent the real user id's token from being dropped</comment>
1335session optional pam_afs.so.1 no_unlog
1336</pre>
1337
1338</body>
1339</section>
549</chapter> 1340</chapter>
550</guide> 1341</guide>

Legend:
Removed from v.1.3  
changed lines
  Added in v.1.27

  ViewVC Help
Powered by ViewVC 1.1.20