/[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.22 Revision 1.23
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.22 2005/10/29 21:10:15 so Exp $ --> 2<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/openafs.xml,v 1.23 2005/11/09 20:58:07 fox2mike 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 link="/doc/en/openafs.xml">
7<title>Gentoo Linux OpenAFS Guide</title> 7<title>Gentoo Linux OpenAFS Guide</title>
16 <mail link="blubber@gentoo.org">Tiemo Kieft</mail> 16 <mail link="blubber@gentoo.org">Tiemo Kieft</mail>
17</author> 17</author>
18<author title="Editor"> 18<author title="Editor">
19 <mail link="fnjordy@gmail.com">Steven McCoy</mail> 19 <mail link="fnjordy@gmail.com">Steven McCoy</mail>
20</author> 20</author>
21<author title="Editor">
22 <mail link="stefaan@gentoo.org">Stefaan De Roeck</mail>
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 an OpenAFS server and client on Gentoo 29This guide shows you how to install an OpenAFS server and client on Gentoo
24Linux. 30Linux.
25</abstract> 31</abstract>
26 32
27<!-- 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 -->
28<!-- See http://creativecommons.org/licenses/by-sa/2.5 --> 34<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
29<license/> 35<license/>
30 36
31<version>1.0</version> 37<version>1.1</version>
32<date>2005-10-29</date> 38<date>2005-11-10</date>
33 39
34<chapter> 40<chapter>
35<title>Overview</title> 41<title>Overview</title>
36<section> 42<section>
37<title>About this Document</title> 43<title>About this Document</title>
84log into AFS client workstations which request information and files from the 90log into AFS client workstations which request information and files from the
85cell's servers on behalf of the users. Users won't know on which server a 91cell's servers on behalf of the users. Users won't know on which server a
86file 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
87will be located to another room, since every volume can be replicated and 93will be located to another room, since every volume can be replicated and
88moved to another server without any user noticing. The files are always 94moved to another server without any user noticing. The files are always
89accessable. Well, it's like NFS on steroids :) 95accessible. Well, it's like NFS on steroids :)
90</p> 96</p>
91 97
92</body> 98</body>
93</section> 99</section>
94<section> 100<section>
143</body> 149</body>
144</section> 150</section>
145</chapter> 151</chapter>
146 152
147<chapter> 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 not 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
559let's analyze the situation. Please file a bug at
560<uri link="http://bugs.gentoo.org">bugs.gentoo.org</uri> in any case,
561preferably with 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>
615</chapter>
616
617<chapter>
148<title>Documentation</title> 618<title>Documentation</title>
149<section> 619<section>
150<title>Getting AFS Documentation</title> 620<title>Getting AFS Documentation</title>
151<body> 621<body>
152 622
157 627
158<pre caption="Installing afsdoc"> 628<pre caption="Installing afsdoc">
159# <i>emerge app-doc/afsdoc</i> 629# <i>emerge app-doc/afsdoc</i>
160</pre> 630</pre>
161 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
162</body> 641</body>
163</section> 642</section>
164</chapter> 643</chapter>
165 644
166<chapter> 645<chapter>
167<title>Client Installation</title> 646<title>Client Installation</title>
168<section> 647<section>
169<title>Preliminary Work</title> 648<title>Building the Client</title>
170<body> 649<body>
171 650
172<note> 651<note>
173All commands should be written in one line!! In this document they are 652All commands should be written in one line!! In this document they are
174sometimes wrapped to two lines to make them easier to read. 653sometimes wrapped to two lines to make them easier to read.
175</note> 654</note>
176 655
177<note> 656<pre caption="Installing openafs">
178Unfortunately the AFS Client needs a ext2 partiton for its cache to run 657# <i>emerge net-fs/openafs</i>
179correctly, because there are some locking issues with reiserfs. You need to 658</pre>
180create a ext2 partition of approx. 200MB (more won't hurt) and mount it to
181<path>/usr/vice/cache</path>
182</note>
183 659
660<p>
661After successful compilation you're ready to go.
184<p> 662</p>
185You should adjust the two files CellServDB and ThisCell before you build the 663
186AFS client. (These files are in <path>/usr/portage/net-fs/openafs/files</path>) 664</body>
665</section>
666<section>
667<title>A simple global-browsing client installation</title>
668<body>
669
670<p>
671If you're not part of a specific OpenAFS-cell you want to access, and you just
672want to try browsing globally available OpenAFS-shares, then you can just
673install OpenAFS, not touch the configuration at all, and start
674<path>/etc/init.d/openafs-client</path>.
675</p>
676
677</body>
678</section>
679<section>
680<title>Accessing a specific OpenAFS cell</title>
681<body>
682
683<p>
684If you need to access a specific cell, say your university's or company's own
685cell, then some adjustments to your configuration have to be made.
686</p>
687
688<p>
689Firstly, you need to update <path>/etc/openafs/CellServDB</path> with the
690database servers for your cell. This information is normally provided by your
691administrator.
692</p>
693
694<p>
695Secondly, in order to be able to log onto the OpenAFS cell, you need to specify
696its name in <path>/etc/openafs/ThisCell</path>.
187</p> 697</p>
188 698
189<pre caption="Adjusting CellServDB and ThisCell"> 699<pre caption="Adjusting CellServDB and ThisCell">
190CellServDB: 700CellServDB:
191>netlabs #Cell name 701>netlabs #Cell name
199Only use spaces inside the <path>CellServDB</path> file. The client will most 709Only use spaces inside the <path>CellServDB</path> file. The client will most
200likely fail if you use TABs. 710likely fail if you use TABs.
201</warn> 711</warn>
202 712
203<p> 713<p>
714For a quick start, you can now start <path>/etc/init.d/openafs/client</path> and
715use <c>klog</c> to authenticate yourself and start using your access to the
716cell. For automatic logons to you cell, you want to consult the appropriate
717section below.
718</p>
719
720</body>
721</section>
722<section>
723<title>Adjusting the cache</title>
724<body>
725
726<note>
727Unfortunately the AFS Client needs a ext2/3 filesystem for its cache to run
728correctly, because there are some issues with reiserfs.
729</note>
730
731<p>
732You can house your cache on an existing filesystem (if it's ext2/3), but some
733may want to create a separate partition for that. The default location of the
734cache is <path>/var/cache/openafs</path>, but you can change that by editing
735<path>/etc/openafs/cacheinfo</path>. A standard size for your cache is
736200MB, but more won't hurt.
737</p>
738
739</body>
740</section>
741<section>
742<title>Adjusting the cell access configuration</title>
743<body>
744
745<p>
746In case you want to do more than just read-only browsing of globally available
747AFS cells, you need to adjust the two files CellServDB and ThisCell. These
748are located in <path>/etc/openafs</path>.
749</p>
750
751<pre caption="Adjusting CellServDB and ThisCell">
752CellServDB:
753>netlabs #Cell name
75410.0.0.1 #storage
755
756ThisCell:
757netlabs
758</pre>
759
760<warn>
761Only use spaces inside the <path>CellServDB</path> file. The client will most
762likely fail if you use TABs.
763</warn>
764
765<p>
204CellServDB tells your client which server(s) it needs to contact for a 766CellServDB tells your client which server(s) it needs to contact for a
205specific cell. ThisCell should be quite obvious. Normally you use a name 767specific cell. ThisCell should be quite obvious. Normally you use a name
206which is unique for your organisation. Your (official) domain might be a 768which is unique for your organisation. Your (official) domain might be a
207good choice. 769good choice.
208</p>
209
210</body>
211</section>
212<section>
213<title>Building the Client</title>
214<body>
215
216<pre caption="Installing openafs">
217# <i>emerge net-fs/openafs</i>
218</pre>
219
220<p>
221After successful compilation you're ready to go.
222</p> 770</p>
223 771
224</body> 772</body>
225</section> 773</section>
226<section> 774<section>
236You should always have a running afs server in your domain when trying to 784You should always have a running afs server in your domain when trying to
237start the afs client. You're system won't boot until it gets some timeout 785start the afs client. You're system won't boot until it gets some timeout
238if your AFS server is down. (And this is quite a long long time) 786if your AFS server is down. (And this is quite a long long time)
239</warn> 787</warn>
240 788
241<pre caption="Adding AFS to the default runlevel"> 789<pre caption="Adding AFS server to the default runlevel">
242# <i>rc-update add afs default</i> 790# <i>rc-update add openafs-server default</i>
243</pre> 791</pre>
244 792
245</body> 793</body>
246</section> 794</section>
247</chapter> 795</chapter>
290the machine unattended until you restart the BOS Server with authorization 838the machine unattended until you restart the BOS Server with authorization
291checking enabled. Well, this is what the AFS documentation says. :) 839checking enabled. Well, this is what the AFS documentation says. :)
292</warn> 840</warn>
293 841
294<pre caption="Initialize the Basic OverSeer Server"> 842<pre caption="Initialize the Basic OverSeer Server">
295# <i>/usr/afs/bin/bosserver -noauth &amp;</i> 843# <i>bosserver -noauth &amp;</i>
296</pre> 844</pre>
297 845
298<p> 846<p>
299Verify that the BOS Server created <path>/usr/vice/etc/CellServDB</path> 847Verify that the BOS Server created <path>/usr/vice/etc/CellServDB</path>
300and <path>/usr/vice/etc/ThisCell</path> 848and <path>/usr/vice/etc/ThisCell</path>
334<p> 882<p>
335Run the <c>bos setcellname</c> command to set the cell name: 883Run the <c>bos setcellname</c> command to set the cell name:
336</p> 884</p>
337 885
338<pre caption="Set the cell name"> 886<pre caption="Set the cell name">
339# <i>/usr/afs/bin/bos setcellname &lt;server name&gt; &lt;cell name&gt; -noauth</i> 887# <i>bos setcellname &lt;server name&gt; &lt;cell name&gt; -noauth</i>
340</pre> 888</pre>
341 889
342</body> 890</body>
343</section> 891</section>
344<section> 892<section>
345<title>Starting the Database Server Process</title> 893<title>Starting the Database Server Process</title>
346<body> 894<body>
347 895
348<p> 896<p>
349Next use the <c>bos create</c> command to create entries for the four database 897Next 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 898server processes in the <path>/etc/openafs/BosConfig</path> file. The four
351processes run on database server machines only. 899processes run on database server machines only.
352</p> 900</p>
353 901
354<table> 902<table>
355<tr> 903<tr>
376 </ti> 924 </ti>
377</tr> 925</tr>
378</table> 926</table>
379 927
380<pre caption="Create entries for the database processes"> 928<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> 929# <i>bos create &lt;server name&gt; kaserver simple /usr/libexec/openafs/kaserver -cell &lt;cell name&gt; -noauth</i>
382# <i>/usr/afs/bin/bos create &lt;server name&gt; buserver simple /usr/afs/bin/buserver -cell &lt;cell name&gt; -noauth</i> 930# <i>bos create &lt;server name&gt; buserver simple /usr/libexec/openafs/buserver -cell &lt;cell name&gt; -noauth</i>
383# <i>/usr/afs/bin/bos create &lt;server name&gt; ptserver simple /usr/afs/bin/ptserver -cell &lt;cell name&gt; -noauth</i> 931# <i>bos create &lt;server name&gt; ptserver simple /usr/libexec/openafs/ptserver -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> 932# <i>bos create &lt;server name&gt; vlserver simple /usr/libexec/openafs/vlserver -cell &lt;cell name&gt; -noauth</i>
385</pre> 933</pre>
386 934
387<p> 935<p>
388You can verify that all servers are running with the <c>bos status</c> command: 936You can verify that all servers are running with the <c>bos status</c> command:
389</p> 937</p>
390 938
391<pre caption="Check if all the servers are running"> 939<pre caption="Check if all the servers are running">
392# <i>/usr/afs/bin/bos status &lt;server name&gt; -noauth</i> 940# <i>bos status &lt;server name&gt; -noauth</i>
393Instance kaserver, currently running normally. 941Instance kaserver, currently running normally.
394Instance buserver, currently running normally. 942Instance buserver, currently running normally.
395Instance ptserver, currently running normally. 943Instance ptserver, currently running normally.
396Instance vlserver, currently running normally. 944Instance vlserver, currently running normally.
397</pre> 945</pre>
415<p> 963<p>
416Enter <c>kas</c> interactive mode 964Enter <c>kas</c> interactive mode
417</p> 965</p>
418 966
419<pre caption="Entering the interactive mode"> 967<pre caption="Entering the interactive mode">
420# <i>/usr/afs/bin/kas -cell &lt;cell name&gt; -noauth</i> 968# <i>kas -cell &lt;cell name&gt; -noauth</i>
421ka&gt; <i>create afs</i> 969ka&gt; <i>create afs</i>
422initial_password: 970initial_password:
423Verifying, please re-enter initial_password: 971Verifying, please re-enter initial_password:
424ka&gt; <i>create admin</i> 972ka&gt; <i>create admin</i>
425initial_password: 973initial_password:
429User data for afs 977User data for afs
430key (0) cksum is 2651715259, last cpw: Mon Jun 4 20:49:30 2001 978key (0) cksum is 2651715259, last cpw: Mon Jun 4 20:49:30 2001
431password will never expire. 979password will never expire.
432An unlimited number of unsuccessful authentications is permitted. 980An unlimited number of unsuccessful authentications is permitted.
433entry never expires. Max ticket lifetime 100.00 hours. 981entry never expires. Max ticket lifetime 100.00 hours.
434last mod on Mon Jun 4 20:49:30 2001 by $lt;none&gt; 982last mod on Mon Jun 4 20:49:30 2001 by &lt;none&gt;
435permit password reuse 983permit password reuse
436ka&gt; <i>setfields admin -flags admin</i> 984ka&gt; <i>setfields admin -flags admin</i>
437ka&gt; <i>examine admin</i> 985ka&gt; <i>examine admin</i>
438 986
439User data for admin (ADMIN) 987User data for admin (ADMIN)
440key (0) cksum is 2651715259, last cpw: Mon Jun 4 20:49:59 2001 988key (0) cksum is 2651715259, last cpw: Mon Jun 4 20:49:59 2001
441password will never expire. 989password will never expire.
442An unlimited number of unsuccessful authentications is permitted. 990An unlimited number of unsuccessful authentications is permitted.
443entry never expires. Max ticket lifetime 25.00 hours. 991entry never expires. Max ticket lifetime 25.00 hours.
444last mod on Mon Jun 4 20:51:10 2001 by $lt;none&gt; 992last mod on Mon Jun 4 20:51:10 2001 by &lt;none&gt;
445permit password reuse 993permit password reuse
446ka&gt; 994ka&gt;
447</pre> 995</pre>
448 996
449<p> 997<p>
450Run the <c>bos adduser</c> command, to add the <b>admin</b> user to 998Run the <c>bos adduser</c> command, to add the <b>admin</b> user to
451the <path>/usr/afs/etc/UserList</path>. 999the <path>/etc/openafs/server/UserList</path>.
452</p> 1000</p>
453 1001
454<pre caption="Add the admin user to the UserList"> 1002<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> 1003# <i>bos adduser &lt;server name&gt; admin -cell &lt;cell name&gt; -noauth</i>
456</pre> 1004</pre>
457 1005
458<p> 1006<p>
459Issue the <c>bos addkey</c> command to define the AFS Server 1007Issue the <c>bos addkey</c> command to define the AFS Server
460encryption key in <path>/usr/afs/etc/KeyFile</path>. 1008encryption key in <path>/etc/openafs/server/KeyFile</path>
461</p> 1009</p>
462 1010
463<note> 1011<note>
464If asked for the input key, give the password you entered when creating 1012If asked for the input key, give the password you entered when creating
465the AFS entry with <c>kas</c> 1013the AFS entry with <c>kas</c>
466</note> 1014</note>
467 1015
468<pre caption="Entering the password"> 1016<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> 1017# <i>bos addkey &lt;server name&gt; -kvno 0 -cell &lt;cell name&gt; -noauth</i>
470input key: 1018input key:
471Retype input key: 1019Retype input key:
472</pre> 1020</pre>
473 1021
474<p> 1022<p>
483that assigns a different UID use the <c>-id</c> argument to create matching 1031that assigns a different UID use the <c>-id</c> argument to create matching
484UIDs. 1032UIDs.
485</note> 1033</note>
486 1034
487<pre caption="Create a Protection Database entry for the database user"> 1035<pre caption="Create a Protection Database entry for the database user">
488# <i>/usr/afs/bin/pts createuser -name admin -cell &lt;cell name&gt; [-id &lt;AFS UID&gt;] -noauth</i> 1036# <i>pts createuser -name admin -cell &lt;cell name&gt; [-id &lt;AFS UID&gt;] -noauth</i>
489</pre> 1037</pre>
490 1038
491<p> 1039<p>
492Issue the <c>pts adduser</c> command to make the <b>admin</b> user a member 1040Issue the <c>pts adduser</c> command to make the <b>admin</b> user a member
493of the system:administrators group, and the <c>pts membership</c> command to 1041of the system:administrators group, and the <c>pts membership</c> command to
494verify the new membership 1042verify the new membership
495</p> 1043</p>
496 1044
497<pre caption="Make admin a member of the administrators group and verify"> 1045<pre caption="Make admin a member of the administrators group and verify">
498# <i>/usr/afs/bin/pts adduser admin system:administrators -cell &lt;cell name&gt; -noauth</i> 1046# <i>pts adduser admin system:administrators -cell &lt;cell name&gt; -noauth</i>
499# <i>/usr/afs/bin/pts membership admin -cell &lt;cell name&gt; -noauth</i> 1047# <i>pts membership admin -cell &lt;cell name&gt; -noauth</i>
500Groups admin (id: 1) is a member of: 1048Groups admin (id: 1) is a member of:
501system:administrators 1049system:administrators
502</pre> 1050</pre>
503 1051
504<p> 1052<p>
505Restart all AFS Server processes 1053Restart all AFS Server processes
506</p> 1054</p>
507 1055
508<pre caption="Restart all AFS server processes"> 1056<pre caption="Restart all AFS server processes">
509# <i>/usr/afs/bin/bos restart &lt;server name&gt; -all -cell &lt;cell name&gt; -noauth</i> 1057# <i>bos restart &lt;server name&gt; -all -cell &lt;cell name&gt; -noauth</i>
510</pre> 1058</pre>
511 1059
512</body> 1060</body>
513</section> 1061</section>
514<section> 1062<section>
521Volume Server and Salvager (fileserver, 1069Volume Server and Salvager (fileserver,
522volserver and salvager processes). 1070volserver and salvager processes).
523</p> 1071</p>
524 1072
525<pre caption="Start the fs process"> 1073<pre caption="Start the fs process">
526# <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> 1074# <i>bos create &lt;server name&gt; fs fs /usr/libexec/openafs/fileserver /usr/libexec/openafs/volserver /usr/libexec/openafs/salvager -cell &lt;cell name&gt; -noauth</i>
527</pre> 1075</pre>
528 1076
529<p> 1077<p>
530Verify that all processes are running 1078Verify that all processes are running
531</p> 1079</p>
532 1080
533<pre caption="Check if all processes are running"> 1081<pre caption="Check if all processes are running">
534# <i>/usr/afs/bin/bos status &lt;server name&gt; -long -noauth</i> 1082# <i>bos status &lt;server name&gt; -long -noauth</i>
535Instance kaserver, (type is simple) currently running normally. 1083Instance kaserver, (type is simple) currently running normally.
536Process last started at Mon Jun 4 21:07:17 2001 (2 proc starts) 1084Process last started at Mon Jun 4 21:07:17 2001 (2 proc starts)
537Last exit at Mon Jun 4 21:07:17 2001 1085Last exit at Mon Jun 4 21:07:17 2001
538Command 1 is '/usr/afs/bin/kaserver' 1086Command 1 is '/usr/libexec/openafs/kaserver'
539 1087
540Instance buserver, (type is simple) currently running normally. 1088Instance buserver, (type is simple) currently running normally.
541Process last started at Mon Jun 4 21:07:17 2001 (2 proc starts) 1089Process last started at Mon Jun 4 21:07:17 2001 (2 proc starts)
542Last exit at Mon Jun 4 21:07:17 2001 1090Last exit at Mon Jun 4 21:07:17 2001
543Command 1 is '/usr/afs/bin/buserver' 1091Command 1 is '/usr/libexec/openafs/buserver'
544 1092
545Instance ptserver, (type is simple) currently running normally. 1093Instance ptserver, (type is simple) currently running normally.
546Process last started at Mon Jun 4 21:07:17 2001 (2 proc starts) 1094Process last started at Mon Jun 4 21:07:17 2001 (2 proc starts)
547Last exit at Mon Jun 4 21:07:17 2001 1095Last exit at Mon Jun 4 21:07:17 2001
548Command 1 is '/usr/afs/bin/ptserver' 1096Command 1 is '/usr/libexec/openafs/ptserver'
549 1097
550Instance vlserver, (type is simple) currently running normally. 1098Instance vlserver, (type is simple) currently running normally.
551Process last started at Mon Jun 4 21:07:17 2001 (2 proc starts) 1099Process last started at Mon Jun 4 21:07:17 2001 (2 proc starts)
552Last exit at Mon Jun 4 21:07:17 2001 1100Last exit at Mon Jun 4 21:07:17 2001
553Command 1 is '/usr/afs/bin/vlserver' 1101Command 1 is '/usr/libexec/openafs/vlserver'
554 1102
555Instance fs, (type is fs) currently running normally. 1103Instance fs, (type is fs) currently running normally.
556Auxiliary status is: file server running. 1104Auxiliary status is: file server running.
557Process last started at Mon Jun 4 21:09:30 2001 (2 proc starts) 1105Process last started at Mon Jun 4 21:09:30 2001 (2 proc starts)
558Command 1 is '/usr/afs/bin/fileserver' 1106Command 1 is '/usr/libexec/openafs/fileserver'
559Command 2 is '/usr/afs/bin/volserver' 1107Command 2 is '/usr/libexec/openafs/volserver'
560Command 3 is '/usr/afs/bin/salvager' 1108Command 3 is '/usr/libexec/openafs/salvager'
561</pre> 1109</pre>
562 1110
563<p> 1111<p>
564Your next action depends on whether you have ever run AFS file server machines 1112Your next action depends on whether you have ever run AFS file server machines
565in the cell. 1113in the cell.
575AFS Server partitions. By convention 1123AFS Server partitions. By convention
576these partitions are named <path>/vicepx</path>, where x is in the range of a-z. 1124these partitions are named <path>/vicepx</path>, where x is in the range of a-z.
577</note> 1125</note>
578 1126
579<pre caption="Create the root.afs volume"> 1127<pre caption="Create the root.afs volume">
580# <i>/usr/afs/bin/vos create &lt;server name&gt; &lt;partition name&gt; root.afs -cell &lt;cell name&gt; -noauth</i> 1128# <i>vos create &lt;server name&gt; &lt;partition name&gt; root.afs -cell &lt;cell name&gt; -noauth</i>
581</pre> 1129</pre>
582 1130
583<p> 1131<p>
584If there are existing AFS file server machines and volumes in the cell 1132If there are existing AFS file server machines and volumes in the cell
585issue the <c>vos sncvldb</c> and <c>vos syncserv</c> commands to synchronize 1133issue the <c>vos sncvldb</c> and <c>vos syncserv</c> commands to synchronize
589 1137
590<p> 1138<p>
591If the command fails with the message "partition /vicepa does not exist on 1139If the command fails with the message "partition /vicepa does not exist on
592the server", ensure that the partition is mounted before running OpenAFS 1140the server", ensure that the partition is mounted before running OpenAFS
593servers, or mount the directory and restart the processes using 1141servers, or mount the directory and restart the processes using
594<c>/usr/afs/bin/bos restart &lt;server name&gt; -all -cell &lt;cell 1142<c>bos restart &lt;server name&gt; -all -cell &lt;cell
595name&gt; -noauth</c>. 1143name&gt; -noauth</c>.
596</p> 1144</p>
597 1145
598<pre caption="Synchronise the VLDB"> 1146<pre caption="Synchronise the VLDB">
599# <i>/usr/afs/bin/vos syncvldb &lt;server name&gt; -cell &lt;cell name&gt; -verbose -noauth</i> 1147# <i>vos syncvldb &lt;server name&gt; -cell &lt;cell name&gt; -verbose -noauth</i>
600# <i>/usr/afs/bin/vos syncserv &lt;server name&gt; -cell &lt;cell name&gt; -verbose -noauth</i> 1148# <i>vos syncserv &lt;server name&gt; -cell &lt;cell name&gt; -verbose -noauth</i>
601</pre> 1149</pre>
602 1150
603</body> 1151</body>
604</section> 1152</section>
605<section> 1153<section>
606<title>Starting the Server Portion of the Update Server</title> 1154<title>Starting the Server Portion of the Update Server</title>
607<body> 1155<body>
608 1156
609<pre caption="Start the update server"> 1157<pre caption="Start the update server">
610# <i>/usr/afs/bin/bos create &lt;server name&gt; 1158# <i>bos create &lt;server name&gt;
611upserver simple "/usr/afs/bin/upserver 1159upserver simple "/usr/libexec/openafs/upserver
612-crypt /usr/afs/etc -clear /usr/afs/bin" 1160-crypt /etc/openafs/server -clear /usr/libexec/openafs"
613-cell &lt;cell name&gt; -noauth</i> 1161-cell &lt;cell name&gt; -noauth</i>
614</pre> 1162</pre>
615 1163
616</body> 1164</body>
617</section> 1165</section>
623First you need to set some ACLs, so that any user can lookup 1171First you need to set some ACLs, so that any user can lookup
624<path>/afs</path>. 1172<path>/afs</path>.
625</p> 1173</p>
626 1174
627<pre caption="Set access control lists"> 1175<pre caption="Set access control lists">
628# <i>/usr/afs/bin/fs setacl /afs system:anyuser rl</i> 1176# <i>fs setacl /afs system:anyuser rl</i>
629</pre> 1177</pre>
630 1178
631<p> 1179<p>
632Then you need to create the root volume, mount it readonly on 1180Then you need to create the root volume, mount it readonly on
633<path>/afs/&lt;cell name&gt;</path> and read/write on <path>/afs/.&lt;cell 1181<path>/afs/&lt;cell name&gt;</path> and read/write on <path>/afs/.&lt;cell
634name&gt;</path>. 1182name&gt;</path>.
635</p> 1183</p>
636 1184
637<pre caption="Prepare the root volume"> 1185<pre caption="Prepare the root volume">
638# <i>/usr/afs/bin/vos create &lt;server name&gt;&lt;partition name&gt; root.cell</i> 1186# <i>vos create &lt;server name&gt;&lt;partition name&gt; root.cell</i>
639# <i>/usr/afs/bin/fs mkmount /afs/&lt;cell name&gt; root.cell </i> 1187# <i>fs mkmount /afs/&lt;cell name&gt; root.cell </i>
640# <i>/usr/afs/bin/fs setacl /afs/&lt;cell name&gt; system:anyuser rl</i> 1188# <i>fs setacl /afs/&lt;cell name&gt; system:anyuser rl</i>
641# <i>/usr/afs/bin/fs mkmount /afs/.&lt;cell name&gt; root.cell -rw</i> 1189# <i>fs mkmount /afs/.&lt;cell name&gt; root.cell -rw</i>
642</pre> 1190</pre>
643 1191
644<p> 1192<p>
645Finally you're done!!! You should now have a working AFS file server 1193Finally you're done!!! You should now have a working AFS file server
646on your local network. Time to get a big 1194on your local network. Time to get a big
715</p> 1263</p>
716 1264
717<pre caption="/etc/pam.d/su"> 1265<pre caption="/etc/pam.d/su">
718<comment># Here, users with uid &gt; 100 are considered to belong to AFS and users with 1266<comment># Here, users with uid &gt; 100 are considered to belong to AFS and users with
719# uid &lt;= 100 are ignored by pam_afs.</comment> 1267# uid &lt;= 100 are ignored by pam_afs.</comment>
720auth sufficient /usr/afsws/lib/pam_afs.so.1 ignore_uid 100 1268auth sufficient pam_afs.so.1 ignore_uid 100
721 1269
722auth sufficient /lib/security/pam_rootok.so 1270auth sufficient pam_rootok.so
723 1271
724<comment># If you want to restrict users begin allowed to su even more, 1272<comment># If you want to restrict users begin allowed to su even more,
725# create /etc/security/suauth.allow (or to that matter) that is only 1273# create /etc/security/suauth.allow (or to that matter) that is only
726# writable by root, and add users that are allowed to su to that 1274# writable by root, and add users that are allowed to su to that
727# file, one per line. 1275# file, one per line.
728#auth required /lib/security/pam_listfile.so item=ruser \ 1276#auth required pam_listfile.so item=ruser \
729# sense=allow onerr=fail file=/etc/security/suauth.allow 1277# sense=allow onerr=fail file=/etc/security/suauth.allow
730 1278
731# Uncomment this to allow users in the wheel group to su without 1279# Uncomment this to allow users in the wheel group to su without
732# entering a passwd. 1280# entering a passwd.
733#auth sufficient /lib/security/pam_wheel.so use_uid trust 1281#auth sufficient pam_wheel.so use_uid trust
734 1282
735# Alternatively to above, you can implement a list of users that do 1283# Alternatively to above, you can implement a list of users that do
736# not need to supply a passwd with a list. 1284# not need to supply a passwd with a list.
737#auth sufficient /lib/security/pam_listfile.so item=ruser \ 1285#auth sufficient pam_listfile.so item=ruser \
738# sense=allow onerr=fail file=/etc/security/suauth.nopass 1286# sense=allow onerr=fail file=/etc/security/suauth.nopass
739 1287
740# Comment this to allow any user, even those not in the 'wheel' 1288# Comment this to allow any user, even those not in the 'wheel'
741# group to su</comment> 1289# group to su</comment>
742auth required /lib/security/pam_wheel.so use_uid 1290auth required pam_wheel.so use_uid
743 1291
744auth required /lib/security/pam_stack.so service=system-auth 1292auth required pam_stack.so service=system-auth
745 1293
746account required /lib/security/pam_stack.so service=system-auth 1294account required pam_stack.so service=system-auth
747 1295
748password required /lib/security/pam_stack.so service=system-auth 1296password required pam_stack.so service=system-auth
749 1297
750session required /lib/security/pam_stack.so service=system-auth 1298session required pam_stack.so service=system-auth
751session optional /lib/security/pam_xauth.so 1299session optional pam_xauth.so
752 1300
753<comment># Here we prevent the real user id's token from being dropped</comment> 1301<comment># Here we prevent the real user id's token from being dropped</comment>
754session optional /usr/afsws/lib/pam_afs.so.1 no_unlog 1302session optional pam_afs.so.1 no_unlog
755</pre> 1303</pre>
756 1304
757</body> 1305</body>
758</section> 1306</section>
759</chapter> 1307</chapter>

Legend:
Removed from v.1.22  
changed lines
  Added in v.1.23

  ViewVC Help
Powered by ViewVC 1.1.20