/[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.20 Revision 1.27
1<?xml version='1.0' encoding="UTF-8"?> 1<?xml version='1.0' encoding="UTF-8"?>
2<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/openafs.xml,v 1.20 2005/07/18 10:44:57 swift Exp $ --> 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 8
9<author title="Editor">
10 <mail link="stefaan@gentoo.org">Stefaan De Roeck</mail>
11</author>
9<author title="Editor"> 12<author title="Editor">
10 <mail link="darks@gentoo.org">Holger Brueckner</mail> 13 <mail link="darks@gentoo.org">Holger Brueckner</mail>
11</author> 14</author>
12<author title="Editor"> 15<author title="Editor">
13 <mail link="bennyc@gentoo.org">Benny Chuang</mail> 16 <mail link="bennyc@gentoo.org">Benny Chuang</mail>
16 <mail link="blubber@gentoo.org">Tiemo Kieft</mail> 19 <mail link="blubber@gentoo.org">Tiemo Kieft</mail>
17</author> 20</author>
18<author title="Editor"> 21<author title="Editor">
19 <mail link="fnjordy@gmail.com">Steven McCoy</mail> 22 <mail link="fnjordy@gmail.com">Steven McCoy</mail>
20</author> 23</author>
24<author title="Editor">
25 <mail link="fox2mike@gentoo.org">Shyam Mani</mail>
26</author>
21 27
22<abstract> 28<abstract>
23This 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.
24</abstract> 31</abstract>
25 32
26<!-- The content of this document is licensed under the CC-BY-SA license --> 33<!-- The content of this document is licensed under the CC-BY-SA license -->
27<!-- See http://creativecommons.org/licenses/by-sa/2.5 --> 34<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
28<license/> 35<license/>
29 36
30<version>0.9</version> 37<version>1.2</version>
31<date>2005-07-18</date> 38<date>2007-06-29</date>
32 39
33<chapter> 40<chapter>
34<title>Overview</title> 41<title>Overview</title>
35<section> 42<section>
36<title>About this Document</title> 43<title>About this Document</title>
37<body> 44<body>
38 45
39<p> 46<p>
40This document provides you with all neccessary steps to install an openafs 47This document provides you with all necessary steps to install an OpenAFS
41server on Gentoo Linux. Parts of this document are taken from the AFS FAQ and 48server on Gentoo Linux. Parts of this document are taken from the AFS FAQ and
42IBM's Quick Beginnings guide on AFS. Well, never reinvent the wheel :) 49IBM's Quick Beginnings guide on AFS. Well, never reinvent the wheel. :)
43</p> 50</p>
44 51
45</body> 52</body>
46</section>
47<section> 53</section>
54<section>
48<title>What is AFS ?</title> 55<title>What is AFS?</title>
49<body> 56<body>
50 57
51<p> 58<p>
52AFS is a distributed filesystem that enables co-operating hosts 59AFS is a distributed filesystem that enables co-operating hosts
53(clients and servers) to efficiently share filesystem resources 60(clients and servers) to efficiently share filesystem resources
54across both local area and wide area networks. Clients hold a 61across both local area and wide area networks. Clients hold a
55cache for often used objects (files), to get quicker 62cache for often used objects (files), to get quicker
56access to them. 63access to them.
57</p> 64</p>
58 65
59<p> 66<p>
60AFS is based on a distributed file system originally developed 67AFS is based on a distributed file system originally developed
61at the Information Technology Center at Carnegie-Mellon University 68at the Information Technology Center at Carnegie-Mellon University
62that was called the "Andrew File System". "Andrew" was the name of the 69that was called the "Andrew File System". "Andrew" was the name of the
63research project at CMU - honouring the founders of the University. Once 70research project at CMU - honouring the founders of the University. Once
64Transarc was formed and AFS became a product, the "Andrew" was dropped to 71Transarc was formed and AFS became a product, the "Andrew" was dropped to
65indicate that AFS had gone beyond the Andrew research project and had become 72indicate that AFS had gone beyond the Andrew research project and had become
66a supported, product quality filesystem. However, there were a number of 73a supported, product quality filesystem. However, there were a number of
67existing cells that rooted their filesystem as /afs. At the time, changing 74existing cells that rooted their filesystem as /afs. At the time, changing
68the root of the filesystem was a non-trivial undertaking. So, to save the 75the root of the filesystem was a non-trivial undertaking. So, to save the
69early AFS sites from having to rename their filesystem, AFS remained as the 76early AFS sites from having to rename their filesystem, AFS remained as the
70name and filesystem root. 77name and filesystem root.
71</p> 78</p>
72 79
73</body> 80</body>
74</section>
75<section> 81</section>
82<section>
76<title>What is an AFS cell ?</title> 83<title>What is an AFS cell?</title>
77<body> 84<body>
78 85
79<p> 86<p>
80An AFS cell is a collection of servers grouped together administratively 87An AFS cell is a collection of servers grouped together administratively and
81and presenting a single, cohesive filesystem. Typically, an AFS cell is a set 88presenting a single, cohesive filesystem. Typically, an AFS cell is a set of
82of 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
83Users log into AFS client workstations which request information and files 90log into AFS client workstations which request information and files from the
84from 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
85a 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
86will 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
87to another server without any user noticing. The files are always accessable. 94moved to another server without any user noticing. The files are always
88Well it's like NFS on steroids :) 95accessible. Well, it's like NFS on steroids :)
89</p> 96</p>
90 97
91</body> 98</body>
92</section>
93<section> 99</section>
100<section>
94<title>What are the benefits of using AFS ?</title> 101<title>What are the benefits of using AFS?</title>
95<body> 102<body>
96 103
97<p> 104<p>
98The main strengths of AFS are its: 105The main strengths of AFS are its:
99caching facility (on client side, typically 100M to 1GB), 106caching facility (on client side, typically 100M to 1GB),
100security features (Kerberos 4 based, access control lists), 107security features (Kerberos 4 based, access control lists),
101simplicity of addressing (you just have one filesystem), 108simplicity of addressing (you just have one filesystem),
102scalability (add further servers to your cell as needed), 109scalability (add further servers to your cell as needed),
103communications protocol. 110communications protocol.
104</p> 111</p>
105 112
106</body> 113</body>
107</section>
108<section> 114</section>
115<section>
109<title>Where can i get more information ?</title> 116<title>Where can I get more information?</title>
110<body> 117<body>
111 118
112<p> 119<p>
113Read the <uri link="http://www.angelfire.com/hi/plutonic/afs-faq.html">AFS 120Read the <uri link="http://www.angelfire.com/hi/plutonic/afs-faq.html">AFS
114FAQ</uri>. 121FAQ</uri>.
115</p> 122</p>
116 123
117<p> 124<p>
118Openafs main page is at <uri 125OpenAFS main page is at <uri
119link="http://www.openafs.org">www.openafs.org</uri>. 126link="http://www.openafs.org">www.openafs.org</uri>.
120</p> 127</p>
121 128
122<p> 129<p>
123AFS was originally developed by Transarc which is now owned by IBM. 130AFS was originally developed by Transarc which is now owned by IBM.
124You can find some information about AFS on 131You can find some information about AFS on
125<uri link="http://www.transarc.ibm.com/Product/EFS/AFS/index.html">Transarcs 132<uri link="http://www.transarc.ibm.com/Product/EFS/AFS/index.html">Transarc's
126Webpage</uri>. 133Webpage</uri>.
127</p> 134</p>
128 135
129</body> 136</body>
130</section> 137</section>
131<section> 138<section>
132<title>How Can I Debug Problems?</title> 139<title>How Can I Debug Problems?</title>
133<body> 140<body>
134 141
135<p> 142<p>
136OpenAFS has great logging facilities. However, by default it logs straight into 143OpenAFS has great logging facilities. However, by default it logs straight into
137its own logs instead of through the system logging facilities you have on your 144its own logs instead of through the system logging facilities you have on your
138system. To have the servers log through your system logger, use the 145system. To have the servers log through your system logger, use the
139<c>-syslog</c> option for all <c>bos</c> commands. 146<c>-syslog</c> option for all <c>bos</c> commands.
140</p> 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>
141 612
142</body> 613</body>
143</section> 614</section>
144</chapter> 615</chapter>
145 616
148<section> 619<section>
149<title>Getting AFS Documentation</title> 620<title>Getting AFS Documentation</title>
150<body> 621<body>
151 622
152<p> 623<p>
153You 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
154really want 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.
155</p> 626</p>
156 627
157<pre caption="Installing afsdoc"> 628<pre caption="Installing afsdoc">
158# <i>emerge app-doc/afsdoc</i> 629# <i>emerge app-doc/afsdoc</i>
159</pre> 630</pre>
160 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
161</body> 641</body>
162</section> 642</section>
163</chapter> 643</chapter>
164 644
165<chapter> 645<chapter>
166<title>Client Installation</title> 646<title>Client Installation</title>
167<section> 647<section>
168<title>Preliminary Work</title> 648<title>Building the Client</title>
649<body>
650
651<pre caption="Installing openafs">
652# <i>emerge net-fs/openafs</i>
653</pre>
654
655<p>
656After successful compilation you're ready to go.
657</p>
658
169<body> 659</body>
660</section>
661<section>
662<title>A simple global-browsing client installation</title>
663<body>
170 664
171<note> 665<p>
172All commands should be written in one line !! In this document they are 666If you're not part of a specific OpenAFS-cell you want to access, and you just
173sometimes wrapped to two lines to make them easier to read. 667want to try browsing globally available OpenAFS-shares, then you can just
174</note> 668install OpenAFS, not touch the configuration at all, and start
175 669<path>/etc/init.d/openafs-client</path>.
176<note>
177Unfortunately the AFS Client needs a ext2 partiton for it's cache to run
178correctly, because there are some locking issues with reiserfs. You need to
179create a ext2 partition of approx. 200MB (more won't hurt) and mount it to
180<path>/usr/vice/cache</path>
181</note>
182
183<p> 670</p>
184You should adjust the two files CellServDB and ThisCell before you build the 671
185afs client. (These files are in <path>/usr/portage/net-fs/openafs/files</path>) 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>.
186</p> 692</p>
187 693
188<pre caption="Adjusting CellServDB and ThisCell"> 694<pre caption="Adjusting CellServDB and ThisCell">
189CellServDB: 695CellServDB:
190>netlabs #Cell name 696>netlabs #Cell name
19110.0.0.1 #storage 69710.0.0.1 #storage
192 698
193ThisCell: 699ThisCell:
194netlabs 700netlabs
195</pre> 701</pre>
196 702
197<warn> 703<warn>
198Only use spaces inside the <path>CellServDB</path> file. The client will most 704Only use spaces inside the <path>CellServDB</path> file. The client will most
199likely fail if you use TABs. 705likely fail if you use TABs.
200</warn> 706</warn>
201 707
202<p> 708<p>
203CellServDB 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
204specific cell. ThisCell should be quite obvious. Normally you use a name 710specific cell. ThisCell should be quite obvious. Normally you use a name
205which is unique for your organisation. Your (official) domain might be a 711which is unique for your organisation. Your (official) domain might be a
206good choice. 712good choice.
713</p>
714
207</p> 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>
208 721
209</body> 722</body>
210</section>
211<section> 723</section>
212<title>Building the Client</title> 724<section>
725<title>Adjusting the cache</title>
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
734<p>
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.
740</p>
741
213<body> 742</body>
743</section>
744<section>
745<title>Starting AFS on startup</title>
746<body>
747
748<p>
749The following command will create the appropriate links to start your afs
750client on system startup.
751</p>
752
753<warn>
754You should always have a running afs server in your domain when trying to start
755the afs client. Your system won't boot until it gets some timeout if your AFS
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>
761</pre>
762
763</body>
764</section>
765</chapter>
766
767<chapter>
768<title>Server Installation</title>
769<section>
770<title>Building the Server</title>
771<body>
772
773<note>
774All commands should be written in one line!! In this document they are
775sometimes wrapped to two lines to make them easier to read.
776</note>
777
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>
214 782
215<pre caption="Installing openafs"> 783<pre caption="Installing openafs">
216# <i>emerge net-fs/openafs</i> 784# <i>emerge net-fs/openafs</i>
217</pre> 785</pre>
218 786
219<p>
220After successful compilation you're ready to go.
221</p>
222
223</body> 787</body>
224</section>
225<section> 788</section>
226<title>Starting afs on startup</title>
227<body>
228
229<p>
230The following command will create the appropriate links to start your afs client
231on system startup.
232</p>
233
234<warn>
235You should always have a running afs server in your domain when trying to
236start the afs client. You're system won't boot until it gets some timeout
237if your afs server is down. (and this is quite a long long time)
238</warn>
239
240<pre caption="Adding afs to the default runlevel">
241# <i>rc-update add afs default</i>
242</pre>
243
244</body>
245</section> 789<section>
246</chapter>
247
248<chapter>
249<title>Server Installation</title>
250<section>
251<title>Building the Server</title>
252<body>
253
254<p>
255The following command will install all necessary binaries for setting up a AFS
256Server <e>and</e> Client.
257</p>
258
259<pre caption="Installing openafs">
260# <i>emerge net-fs/openafs</i>
261</pre>
262
263</body>
264</section>
265<section>
266<title>Starting AFS Server</title> 790<title>Starting AFS Server</title>
267<body> 791<body>
268 792
269<p>
270You need to remove the sample CellServDB and ThisCell file first.
271</p> 793<p>
272
273<pre caption="Remove sample files">
274# <i>rm /usr/vice/etc/ThisCell</i>
275# <i>rm /usr/vice/etc/CellServDB</i>
276</pre>
277
278<p>
279Next you will run the <b>bosserver</b> command to initialize the Basic OverSeer 794You need to run the <c>bosserver</c> command to initialize the Basic OverSeer
280(BOS) Server, which monitors and controls other AFS server processes on its 795(BOS) Server, which monitors and controls other AFS server processes on its
281server 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>
282flag to disable authorization checking, since you haven't added the admin user 797flag to disable authorization checking, since you haven't added the admin user
283yet. 798yet.
284</p> 799</p>
285 800
286<warn> 801<warn>
287Disabling authorization checking gravely compromises cell security. 802Disabling authorization checking gravely compromises cell security. You must
288You must complete all subsequent steps in one uninterrupted pass 803complete all subsequent steps in one uninterrupted pass and must not leave
289and must not leave the machine unattended until you restart the BOS Server with 804the machine unattended until you restart the BOS Server with authorization
290authorization checking enabled. Well this is what the AFS documentation says :) 805checking enabled. Well, this is what the AFS documentation says. :)
291</warn> 806</warn>
292 807
293<pre caption="Initialize the Basic OverSeer Server"> 808<pre caption="Initialize the Basic OverSeer Server">
294# <i>/usr/afs/bin/bosserver -noauth &amp;</i> 809# <i>bosserver -noauth &amp;</i>
295</pre> 810</pre>
296 811
297<p> 812<p>
298Verify that the BOS Server created <path>/usr/vice/etc/CellServDB</path> 813Verify that the BOS Server created <path>/etc/openafs/server/CellServDB</path>
299and <path>/usr/vice/etc/ThisCell</path> 814and <path>/etc/openafs/server/ThisCell</path>
300</p> 815</p>
301 816
302<pre caption="Check if CellServDB and ThisCell are created"> 817<pre caption="Check if CellServDB and ThisCell are created">
303# <i>ls -al /usr/vice/etc/</i> 818# <i>ls -al /etc/openafs/server/</i>
304-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
305-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
306</pre> 821</pre>
307 822
308</body> 823</body>
309</section> 824</section>
310<section> 825<section>
311<title>Defining Cell Name and Membership for Server Process</title> 826<title>Defining Cell Name and Membership for Server Process</title>
312<body> 827<body>
313 828
314<p> 829<p>
315Now assign your cells name. 830Now assign your cell's name.
316</p> 831</p>
317 832
318<impo> 833<impo>
319There are some restrictions on the name format. 834There are some restrictions on the name format. Two of the most important
320Two of the most important restrictions are that the name 835restrictions are that the name cannot include uppercase letters or more than
321cannot include uppercase letters or more than 64 characters. Remember that 83664 characters. Remember that your cell name will show up under
322your cell name will show up under <path>/afs</path>, so you might want to choose 837<path>/afs</path>, so you might want to choose a short one.
323a short one.
324</impo> 838</impo>
325 839
326<note> 840<note>
327In the following and every instruction in this guide, for the &lt;server 841In the following and every instruction in this guide, for the &lt;server
328name&gt; argument substitute the full-qualified hostname (such as 842name&gt; argument substitute the full-qualified hostname (such as
329<b>afs.gentoo.org</b>) of the machine you are installing. For the &lt;cell 843<b>afs.gentoo.org</b>) of the machine you are installing. For the &lt;cell
330name&gt; argument substitute your cell's complete name (such as 844name&gt; argument substitute your cell's complete name (such as
331<b>gentoo</b>) 845<b>gentoo</b>)
332</note> 846</note>
333 847
334<p> 848<p>
335Run the <b>bos setcellname</b> command to set the cell name: 849Run the <c>bos setcellname</c> command to set the cell name:
336</p> 850</p>
337 851
338<pre caption="Set the cell name"> 852<pre caption="Set the cell name">
339# <i>/usr/afs/bin/bos setcellname &lt;server name&gt; &lt;cell name&gt; -noauth</i> 853# <i>bos setcellname &lt;server name&gt; &lt;cell name&gt; -noauth</i>
340</pre> 854</pre>
341 855
342</body> 856</body>
343</section> 857</section>
344<section> 858<section>
345<title>Starting the Database Server Process</title> 859<title>Starting the Database Server Process</title>
346<body> 860<body>
347 861
348<p> 862<p>
349Next 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
350server processes in the <path>/usr/afs/local/BosConfig</path> file. The four 864server processes in the <path>/etc/openafs/BosConfig</path> file. The four
351processes run on database server machines only. 865processes run on database server machines only.
352</p> 866</p>
353 867
354<table> 868<table>
355<tr> 869<tr>
356 <ti>kaserver</ti> 870 <ti>kaserver</ti>
357 <ti> 871 <ti>
358 The Authentication Server maintains the Authentication Database. 872 The Authentication Server maintains the Authentication Database.
359 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
360 feel free to update this document :) 874 feel free to update this document :)
361 </ti> 875 </ti>
362</tr> 876</tr>
363<tr> 877<tr>
364 <ti>buserver</ti> 878 <ti>buserver</ti>
373 <ti> 887 <ti>
374 The Volume Location Server maintains the Volume Location Database (VLDB). 888 The Volume Location Server maintains the Volume Location Database (VLDB).
375 Very important :) 889 Very important :)
376 </ti> 890 </ti>
377</tr> 891</tr>
378</table> 892</table>
379 893
380<pre caption="Create entries for the database processes"> 894<pre caption="Create entries for the database processes">
381# <i>/usr/afs/bin/bos create &lt;server name&gt; kaserver simple /usr/afs/bin/kaserver -cell &lt;cell name&gt; -noauth</i> 895# <i>bos create &lt;server name&gt; kaserver \
382# <i>/usr/afs/bin/bos create &lt;server name&gt; buserver simple /usr/afs/bin/buserver -cell &lt;cell name&gt; -noauth</i> 896simple /usr/libexec/openafs/kaserver \
383# <i>/usr/afs/bin/bos create &lt;server name&gt; ptserver simple /usr/afs/bin/ptserver -cell &lt;cell name&gt; -noauth</i> 897-cell &lt;cell name&gt; -noauth</i>
384# <i>/usr/afs/bin/bos create &lt;server name&gt; vlserver simple /usr/afs/bin/vlserver -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>
385</pre> 907</pre>
386 908
387<p> 909<p>
388You 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:
389</p> 911</p>
390 912
391<pre caption="Check if all the servers are running"> 913<pre caption="Check if all the servers are running">
392# <i>/usr/afs/bin/bos status &lt;server name&gt; -noauth</i> 914# <i>bos status &lt;server name&gt; -noauth</i>
393Instance kaserver, currently running normally. 915Instance kaserver, currently running normally.
394Instance buserver, currently running normally. 916Instance buserver, currently running normally.
395Instance ptserver, currently running normally. 917Instance ptserver, currently running normally.
396Instance vlserver, currently running normally. 918Instance vlserver, currently running normally.
397</pre> 919</pre>
401<section> 923<section>
402<title>Initializing Cell Security</title> 924<title>Initializing Cell Security</title>
403<body> 925<body>
404 926
405<p> 927<p>
406Now we'll initialize the cell's security mechanisms. We'll begin by creating 928Now we'll initialize the cell's security mechanisms. We'll begin by creating
407the following two initial entries in the Authentication Database: The main 929the following two initial entries in the Authentication Database: The main
408administrative account, called <b>admin</b> by convention and an entry for 930administrative account, called <b>admin</b> by convention and an entry for
409the 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
410identity <b>afs</b>, but the Authentication Server's Ticket Granting 932identity <b>afs</b>, but the Authentication Server's Ticket Granting
411Service (TGS) module uses the account to encrypt the server tickets that 933Service (TGS) module uses the account to encrypt the server tickets that
412it grants to AFS clients. This sounds pretty much like Kerberos :) 934it grants to AFS clients. This sounds pretty much like Kerberos :)
413</p> 935</p>
414 936
415<p> 937<p>
416Enter <b>kas</b> interactive mode 938Enter <c>kas</c> interactive mode
417</p> 939</p>
418 940
419<pre caption="Entering the interactive mode"> 941<pre caption="Entering the interactive mode">
420# <i>/usr/afs/bin/kas -cell &lt;cell name&gt; -noauth</i> 942# <i>kas -cell &lt;cell name&gt; -noauth</i>
421ka&gt; <i>create afs</i> 943ka&gt; <i>create afs</i>
422initial_password: 944initial_password:
423Verifying, please re-enter initial_password: 945Verifying, please re-enter initial_password:
424ka&gt; <i>create admin</i> 946ka&gt; <i>create admin</i>
425initial_password: 947initial_password:
429User data for afs 951User data for afs
430key (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
431password will never expire. 953password will never expire.
432An unlimited number of unsuccessful authentications is permitted. 954An unlimited number of unsuccessful authentications is permitted.
433entry never expires. Max ticket lifetime 100.00 hours. 955entry never expires. Max ticket lifetime 100.00 hours.
434last 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;
435permit password reuse 957permit password reuse
436ka&gt; <i>setfields admin -flags admin</i> 958ka&gt; <i>setfields admin -flags admin</i>
437ka&gt; <i>examine admin</i> 959ka&gt; <i>examine admin</i>
438 960
439User data for admin (ADMIN) 961User data for admin (ADMIN)
440key (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
441password will never expire. 963password will never expire.
442An unlimited number of unsuccessful authentications is permitted. 964An unlimited number of unsuccessful authentications is permitted.
443entry never expires. Max ticket lifetime 25.00 hours. 965entry never expires. Max ticket lifetime 25.00 hours.
444last 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;
445permit password reuse 967permit password reuse
446ka&gt; 968ka&gt;
447</pre> 969</pre>
448 970
449<p> 971<p>
450Run 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
451the <path>/usr/afs/etc/UserList</path>. 973the <path>/etc/openafs/server/UserList</path>.
452</p> 974</p>
453 975
454<pre caption="Add the admin user to the UserList"> 976<pre caption="Add the admin user to the UserList">
455# <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>
456</pre> 978</pre>
457 979
458<p> 980<p>
459Issue the <b>bos addkey</b> command to define the AFS Server 981Issue the <c>bos addkey</c> command to define the AFS Server
460encryption key in <path>/usr/afs/etc/KeyFile</path> 982encryption key in <path>/etc/openafs/server/KeyFile</path>
461</p> 983</p>
462 984
463<note> 985<note>
464If 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
465the afs entry with <b>kas</b> 987the AFS entry with <c>kas</c>
466</note> 988</note>
467 989
468<pre caption="Entering the password"> 990<pre caption="Entering the password">
469# <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>
470input key: 992input key:
471Retype input key: 993Retype input key:
472</pre> 994</pre>
473 995
474<p> 996<p>
475Issue the <b>pts createuser</b> command to create a Protection Database 997Issue the <c>pts createuser</c> command to create a Protection Database entry
476entry for the admin user 998for the admin user.
477</p> 999</p>
478 1000
479<note> 1001<note>
480By default, the Protection Server assigns AFS UID 1 to the <b>admin</b> user, 1002By default, the Protection Server assigns AFS UID 1 to the <b>admin</b> user,
481because it is the first user entry you are creating. If the local password file 1003because it is the first user entry you are creating. If the local password file
482(/etc/passwd or equivalent) already has an entry for <b>admin</b> that assigns 1004(<path>/etc/passwd</path> or equivalent) already has an entry for <b>admin</b>
483a different UID use the <b>-id</b> argument to create matching UID's 1005that assigns a different UID use the <c>-id</c> argument to create matching
1006UIDs.
484</note> 1007</note>
485 1008
486<pre caption="Create a Protection Database entry for the database user"> 1009<pre caption="Create a Protection Database entry for the database user">
487# <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>
488</pre> 1011</pre>
489 1012
490<p> 1013<p>
491Issue 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
492of the system:administrators group, and the <b>pts membership</b> command to 1015of the system:administrators group, and the <c>pts membership</c> command to
493verify the new membership 1016verify the new membership
494</p> 1017</p>
495 1018
496<pre caption="Make admin a member of the administrators group and verify"> 1019<pre caption="Make admin a member of the administrators group and verify">
497# <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>
498# <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>
499Groups admin (id: 1) is a member of: 1022Groups admin (id: 1) is a member of:
500system:administrators 1023system:administrators
501</pre> 1024</pre>
502 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<-->
503<p> 1040</p>
504Restart all AFS Server processes 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:
505</p> 1064</p>
506 1065
507<pre caption="Restart all AFS server processes"> 1066<pre caption="Restart all AFS server processes">
508# <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>
509</pre> 1068</pre>
1069<-->
510 1070
511</body> 1071</body>
512</section> 1072</section>
513<section> 1073<section>
514<title>Starting the File Server, Volume Server and Salvager</title> 1074<title>Starting the File Server, Volume Server and Salvager</title>
515<body> 1075<body>
516 1076
517<p> 1077<p>
518Start the <b>fs</b> process, which consists of the File Server, Volume Server 1078Start the <c>fs</c> process, which consists of the File Server, Volume Server
519and Salvager (fileserver, volserver and salvager processes). 1079and Salvager (fileserver, volserver and salvager processes).
520</p> 1080</p>
521 1081
522<pre caption="Start the fs process"> 1082<pre caption="Start the fs process">
523# <i>/usr/afs/bin/bos create &lt;server name&gt; fs fs /usr/afs/bin/fileserver /usr/afs/bin/volserver /usr/afs/bin/salvager -cell &lt;cell name&gt; -noauth</i> 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>
524</pre> 1086</pre>
525 1087
526<p> 1088<p>
527Verify that all processes are running 1089Verify that all processes are running:
528</p> 1090</p>
529 1091
530<pre caption="Check if all processes are running"> 1092<pre caption="Check if all processes are running">
531# <i>/usr/afs/bin/bos status &lt;server name&gt; -long -noauth</i> 1093# <i>bos status &lt;server name&gt; -long -noauth</i>
532Instance kaserver, (type is simple) currently running normally. 1094Instance kaserver, (type is simple) currently running normally.
533Process 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)
534Last exit at Mon Jun 4 21:07:17 2001 1096Last exit at Mon Jun 4 21:07:17 2001
535Command 1 is '/usr/afs/bin/kaserver' 1097Command 1 is '/usr/libexec/openafs/kaserver'
536 1098
537Instance buserver, (type is simple) currently running normally. 1099Instance buserver, (type is simple) currently running normally.
538Process 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)
539Last exit at Mon Jun 4 21:07:17 2001 1101Last exit at Mon Jun 4 21:07:17 2001
540Command 1 is '/usr/afs/bin/buserver' 1102Command 1 is '/usr/libexec/openafs/buserver'
541 1103
542Instance ptserver, (type is simple) currently running normally. 1104Instance ptserver, (type is simple) currently running normally.
543Process 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)
544Last exit at Mon Jun 4 21:07:17 2001 1106Last exit at Mon Jun 4 21:07:17 2001
545Command 1 is '/usr/afs/bin/ptserver' 1107Command 1 is '/usr/libexec/openafs/ptserver'
546 1108
547Instance vlserver, (type is simple) currently running normally. 1109Instance vlserver, (type is simple) currently running normally.
548Process 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)
549Last exit at Mon Jun 4 21:07:17 2001 1111Last exit at Mon Jun 4 21:07:17 2001
550Command 1 is '/usr/afs/bin/vlserver' 1112Command 1 is '/usr/libexec/openafs/vlserver'
551 1113
552Instance fs, (type is fs) currently running normally. 1114Instance fs, (type is fs) currently running normally.
553Auxiliary status is: file server running. 1115Auxiliary status is: file server running.
554Process 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)
555Command 1 is '/usr/afs/bin/fileserver' 1117Command 1 is '/usr/libexec/openafs/fileserver'
556Command 2 is '/usr/afs/bin/volserver' 1118Command 2 is '/usr/libexec/openafs/volserver'
557Command 3 is '/usr/afs/bin/salvager' 1119Command 3 is '/usr/libexec/openafs/salvager'
558</pre> 1120</pre>
559 1121
560<p> 1122<p>
561Your 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
562in the cell: 1124in the cell.
563</p>
564
565<p> 1125</p>
1126
1127<p>
566If 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
567first AFS volume, <b>root.afs</b> 1129AFS volume, <b>root.afs</b>
568</p> 1130</p>
569 1131
570<note> 1132<note>
571For 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
572AFS Server partitions. By convention 1134AFS Server partitions. Any filesystem mounted under a directory called
573these partitions are named <path>/vicepx</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.
574</note> 1141</note>
575 1142
576<pre caption="Create the root.afs volume"> 1143<pre caption="Create the root.afs volume">
577# <i>/usr/afs/bin/vos create &lt;server name&gt; &lt;partition name&gt; root.afs -cell &lt;cell name&gt; -noauth</i> 1144# <i>vos create &lt;server name&gt; &lt;partition name&gt; root.afs -cell &lt;cell name&gt; -noauth</i>
578</pre> 1145</pre>
579 1146
580<p> 1147<p>
581If 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
582issue the <b>vos sncvldb</b> and <b>vos syncserv</b> commands to synchronize 1149issue the <c>vos sncvldb</c> and <c>vos syncserv</c> commands to synchronize
583the VLDB (Volume Location Database) with the actual state of volumes on the 1150the VLDB (Volume Location Database) with the actual state of volumes on the
584local machine. This will copy all necessary data to your new server. 1151local machine. This will copy all necessary data to your new server.
585</p> 1152</p>
586 1153
587<p> 1154<p>
588If the command fails with the message "partition /vicepa does not exist on 1155If the command fails with the message "partition /vicepa does not exist on
589the server", ensure that the partition is mounted before running OpenAFS 1156the server", ensure that the partition is mounted before running OpenAFS
590servers, or mount the directory and restart the processes using 1157servers, or mount the directory and restart the processes using
591<c>/usr/afs/bin/bos restart &lt;server name&gt; -all -cell &lt;cell 1158<c>bos restart &lt;server name&gt; -all -cell &lt;cell
592name&gt; -noauth</c>. 1159name&gt; -noauth</c>.
593</p> 1160</p>
594 1161
595<pre caption="Synchronise the VLDB"> 1162<pre caption="Synchronise the VLDB">
596# <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>
597# <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>
598</pre> 1165</pre>
599 1166
600</body> 1167</body>
601</section> 1168</section>
602<section> 1169<section>
603<title>Starting the Server Portion of the Update Server</title> 1170<title>Starting the Server Portion of the Update Server</title>
604<body> 1171<body>
605 1172
606<pre caption="Start the update server"> 1173<pre caption="Start the update server">
607# <i>/usr/afs/bin/bos create &lt;server name&gt; 1174# <i>bos create &lt;server name&gt; \
608upserver simple "/usr/afs/bin/upserver 1175upserver simple "/usr/libexec/openafs/upserver \
609-crypt /usr/afs/etc -clear /usr/afs/bin" 1176-crypt /etc/openafs/server -clear /usr/libexec/openafs" \
610-cell &lt;cell name&gt; -noauth</i> 1177-cell &lt;cell name&gt; -noauth</i>
611</pre> 1178</pre>
612 1179
613</body> 1180</body>
614</section> 1181</section>
615<section> 1182<section>
616<title>Configuring the Top Level of the AFS filespace</title> 1183<title>Configuring the Top Level of the AFS filespace</title>
617<body> 1184<body>
618 1185
619<p> 1186<p>
620First you need to set some acl's, so that any user can lookup 1187First you need to set some ACLs, so that any user can lookup
621<path>/afs</path>. 1188<path>/afs</path>.
622</p> 1189</p>
623 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
624<pre caption="Set access control lists"> 1201<pre caption="Set access control lists">
625# <i>/usr/afs/bin/fs setacl /afs system:anyuser rl</i> 1202# <i>fs setacl /afs system:anyuser rl</i>
626</pre> 1203</pre>
627 1204
628<p> 1205<p>
629Then you need to create the root volume, mount it readonly on 1206Then you need to create the root volume, mount it readonly on
630<path>/afs/&lt;cell name&gt;</path> and read/write on <path>/afs/.&lt;cell 1207<path>/afs/&lt;cell name&gt;</path> and read/write on <path>/afs/.&lt;cell
631name&gt;</path> 1208name&gt;</path>.
632</p> 1209</p>
633 1210
634<pre caption="Prepare the root volume"> 1211<pre caption="Prepare the root volume">
635# <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>
636# <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>
637# <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>
638# <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>
639</pre> 1216</pre>
640 1217
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
641<p> 1225<p>
642Finally 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
643on your local network. Time to get a big 1227on your local network. Time to get a big
644cup of coffee and print out the AFS documentation !!! 1228cup of coffee and print out the AFS documentation!!!
645</p> 1229</p>
646 1230
647<note> 1231<note>
648It 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
649clock's are synchronized. This is best accomplished by installing a ntp server 1233clocks are synchronized. This is best accomplished by installing a ntp server
650on one machine (e.g. the AFS server) and synchronize all client clock's 1234on one machine (e.g. the AFS server) and synchronize all client clocks
651with 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.
652</note> 1236</note>
653 1237
654</body> 1238</body>
655</section> 1239</section>
656</chapter> 1240</chapter>
673<body> 1257<body>
674 1258
675<p> 1259<p>
676To use AFS you need to authenticate against the KA Server if using 1260To use AFS you need to authenticate against the KA Server if using
677an implementation AFS Kerberos 4, or against a Kerberos 5 KDC if using 1261an implementation AFS Kerberos 4, or against a Kerberos 5 KDC if using
678MIT, Heimdal, or ShiShi Kerberos 5. However in order to login to a 1262MIT, Heimdal, or ShiShi Kerberos 5. However in order to login to a
679machine you will also need a user account, this can be local in 1263machine you will also need a user account, this can be local in
680/etc/passwd, NIS, LDAP (OpenLDAP), or a Hesiod database. PAM allows 1264<path>/etc/passwd</path>, NIS, LDAP (OpenLDAP), or a Hesiod database.
681Gentoo to tie the authentication against AFS and login to the user 1265PAM allows Gentoo to tie the authentication against AFS and login to the
682account. 1266user account.
683</p>
684
685<p> 1267</p>
1268
1269<p>
686You will need to update /etc/pam.d/system-auth which is used by the 1270You will need to update <path>/etc/pam.d/system-auth</path> which is
687other configurations. "use_first_pass" indicates it will be checked 1271used by the other configurations. "use_first_pass" indicates it will be
688first against the user login, and "ignore_root" stops the local super 1272checked first against the user login, and "ignore_root" stops the local
689user being checked so as to order to allow login if AFS or the network 1273superuser being checked so as to order to allow login if AFS or the network
690fails. 1274fails.
691</p> 1275</p>
692 1276
693<pre caption="/etc/pam.d/system-auth"> 1277<pre caption="/etc/pam.d/system-auth">
694auth required /lib/security/pam_env.so 1278auth required pam_env.so
695auth sufficient /lib/security/pam_unix.so likeauth nullok 1279auth sufficient pam_unix.so likeauth nullok
696auth sufficient /usr/afsws/lib/pam_afs.so.1 use_first_pass ignore_root 1280auth sufficient pam_afs.so.1 use_first_pass ignore_root
697auth required /lib/security/pam_deny.so 1281auth required pam_deny.so
698 1282
699account required /lib/security/pam_unix.so 1283account required pam_unix.so
700 1284
701password required /lib/security/pam_cracklib.so retry=3 1285password required pam_cracklib.so retry=3
702password sufficient /lib/security/pam_unix.so nullok md5 shadow use_authtok 1286password sufficient pam_unix.so nullok md5 shadow use_authtok
703password required /lib/security/pam_deny.so 1287password required pam_deny.so
704 1288
705session required /lib/security/pam_limits.so 1289session required pam_limits.so
706session required /lib/security/pam_unix.so 1290session required pam_unix.so
707</pre> 1291</pre>
708 1292
709<p> 1293<p>
710In order for sudo to keep the real user's token and to prevent local 1294In order for <c>sudo</c> to keep the real user's token and to prevent local
711users gaining AFS access change /etc/pam.d/su as follows: 1295users gaining AFS access change <path>/etc/pam.d/su</path> as follows:
712</p> 1296</p>
713 1297
714<pre caption="/etc/pam.d/su"> 1298<pre caption="/etc/pam.d/su">
715<comment># Here, users with uid &gt; 100 are considered to belong to AFS and users with 1299<comment># Here, users with uid &gt; 100 are considered to belong to AFS and users with
716# uid &lt;= 100 are ignored by pam_afs.</comment> 1300# uid &lt;= 100 are ignored by pam_afs.</comment>
717auth sufficient /usr/afsws/lib/pam_afs.so.1 ignore_uid 100 1301auth sufficient pam_afs.so.1 ignore_uid 100
718 1302
719auth sufficient /lib/security/pam_rootok.so 1303auth sufficient pam_rootok.so
720 1304
721<comment># If you want to restrict users begin allowed to su even more, 1305<comment># If you want to restrict users begin allowed to su even more,
722# create /etc/security/suauth.allow (or to that matter) that is only 1306# create /etc/security/suauth.allow (or to that matter) that is only
723# writable by root, and add users that are allowed to su to that 1307# writable by root, and add users that are allowed to su to that
724# file, one per line. 1308# file, one per line.
725#auth required /lib/security/pam_listfile.so item=ruser \ 1309#auth required pam_listfile.so item=ruser \
726# sense=allow onerr=fail file=/etc/security/suauth.allow 1310# sense=allow onerr=fail file=/etc/security/suauth.allow
727 1311
728# Uncomment this to allow users in the wheel group to su without 1312# Uncomment this to allow users in the wheel group to su without
729# entering a passwd. 1313# entering a passwd.
730#auth sufficient /lib/security/pam_wheel.so use_uid trust 1314#auth sufficient pam_wheel.so use_uid trust
731 1315
732# Alternatively to above, you can implement a list of users that do 1316# Alternatively to above, you can implement a list of users that do
733# not need to supply a passwd with a list. 1317# not need to supply a passwd with a list.
734#auth sufficient /lib/security/pam_listfile.so item=ruser \ 1318#auth sufficient pam_listfile.so item=ruser \
735# sense=allow onerr=fail file=/etc/security/suauth.nopass 1319# sense=allow onerr=fail file=/etc/security/suauth.nopass
736 1320
737# Comment this to allow any user, even those not in the 'wheel' 1321# Comment this to allow any user, even those not in the 'wheel'
738# group to su</comment> 1322# group to su</comment>
739auth required /lib/security/pam_wheel.so use_uid 1323auth required pam_wheel.so use_uid
740 1324
741auth required /lib/security/pam_stack.so service=system-auth 1325auth required pam_stack.so service=system-auth
742 1326
743account required /lib/security/pam_stack.so service=system-auth 1327account required pam_stack.so service=system-auth
744 1328
745password required /lib/security/pam_stack.so service=system-auth 1329password required pam_stack.so service=system-auth
746 1330
747session required /lib/security/pam_stack.so service=system-auth 1331session required pam_stack.so service=system-auth
748session optional /lib/security/pam_xauth.so 1332session optional pam_xauth.so
749 1333
750<comment># Here we prevent the real user id's token from being dropped</comment> 1334<comment># Here we prevent the real user id's token from being dropped</comment>
751session optional /usr/afsws/lib/pam_afs.so.1 no_unlog 1335session optional pam_afs.so.1 no_unlog
752</pre> 1336</pre>
753 1337
754</body> 1338</body>
755</section> 1339</section>
756</chapter> 1340</chapter>
757
758</guide> 1341</guide>

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

  ViewVC Help
Powered by ViewVC 1.1.20