ac6ade597a51e21b5f917409360899b20d587308
[openafs.git] / doc / xml / QuickStartUnix / auqbg005.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <chapter id="HDRWQ17">
3   <title>Installing the First AFS Machine</title>
4
5   <para>
6   <indexterm>
7     <primary>file server machine</primary>
8
9     <seealso>first AFS machine</seealso>
10
11     <seealso>file server machine, additional</seealso>
12   </indexterm>
13
14   <indexterm>
15     <primary>instructions</primary>
16
17     <secondary>first AFS machine</secondary>
18   </indexterm>
19
20   <indexterm>
21     <primary>installing</primary>
22
23     <secondary>first AFS machine</secondary>
24   </indexterm>
25
26   This chapter describes how to install the first AFS machine in your cell, configuring it as both a file server machine and a
27   client machine. After completing all procedures in this chapter, you can remove the client functionality if you wish, as described
28   in <link linkend="HDRWQ98">Removing Client Functionality</link>.</para>
29
30   <para>To install additional file server machines after completing this chapter, see <link linkend="HDRWQ99">Installing Additional
31   Server Machines</link>.</para>
32
33   <para>To install additional client machines after completing this chapter, see <link linkend="HDRWQ133">Installing Additional
34   Client Machines</link>. <indexterm>
35       <primary>requirements</primary>
36
37       <secondary>first AFS machine</secondary>
38     </indexterm></para>
39
40   <sect1 id="Header_29">
41     <title>Requirements and Configuration Decisions</title>
42
43     <para>The instructions in this chapter assume that you meet the following requirements. 
44       <itemizedlist>
45         <listitem>
46           <para>You are logged onto the machine's console as the local superuser <emphasis role="bold">root</emphasis></para>
47         </listitem>
48
49         <listitem>
50           <para>A standard version of one of the operating systems supported by the current version of AFS is running on the
51           machine</para>
52         </listitem>
53
54         <listitem>
55           <para>You have either installed the provided OpenAFS packages for 
56           your system, have access to a binary distribution tarball, or have 
57           successfully built OpenAFS from source</para>
58         </listitem>
59
60         <listitem>
61           <para>You have a Kerberos v5 realm running for your site. If you are
62           working with an existing cell which uses legacy
63           <emphasis role="bold">kaserver</emphasis> or Kerberos v4 for
64           authentication, please see 
65           <link linkend="KAS001">kaserver and Legacy Kerberos v4 Authentication</link>
66           for the modifications required to this installation procedure.</para>
67         </listitem>
68
69         <listitem>
70           <para>You have NTP or a similar time service deployed to ensure
71           rough clock syncronistation between your clients and servers.</para>
72         </listitem>
73       </itemizedlist></para>
74
75     <para>You must make the following configuration decisions while installing the first AFS machine. To speed the installation
76     itself, it is best to make the decisions before beginning. See the chapter in the <emphasis>OpenAFS Administration
77     Guide</emphasis> about issues in cell administration and configuration for detailed guidelines. <indexterm>
78         <primary>cell name</primary>
79
80         <secondary>choosing</secondary>
81       </indexterm> <indexterm>
82         <primary>AFS filespace</primary>
83
84         <secondary>deciding how to configure</secondary>
85       </indexterm> <indexterm>
86         <primary>filespace</primary>
87
88         <see>AFS filespace</see>
89       </indexterm> <itemizedlist>
90         <listitem>
91           <para>Select the first AFS machine</para>
92         </listitem>
93
94         <listitem>
95           <para>Select the cell name</para>
96         </listitem>
97
98         <listitem>
99           <para>Decide which partitions or logical volumes to configure as AFS server partitions, and choose the directory names on
100           which to mount them</para>
101         </listitem>
102
103         <listitem>
104           <para>Decide how big to make the client cache</para>
105         </listitem>
106
107         <listitem>
108           <para>Decide how to configure the top levels of your cell's AFS filespace</para>
109         </listitem>
110       </itemizedlist></para>
111
112     <para>This chapter is divided into three large sections corresponding to the three parts of installing the first AFS machine.
113     Perform all of the steps in the order they appear. Each functional section begins with a summary of the procedures to perform.
114     The sections are as follows: <itemizedlist>
115         <listitem>
116           <para>Installing server functionality (begins in <link linkend="HDRWQ18">Overview: Installing Server
117           Functionality</link>)</para>
118         </listitem>
119
120         <listitem>
121           <para>Installing client functionality (begins in <link linkend="HDRWQ63">Overview: Installing Client
122           Functionality</link>)</para>
123         </listitem>
124
125         <listitem>
126           <para>Configuring your cell's filespace, establishing further security mechanisms, and enabling access to foreign cells
127           (begins in <link linkend="HDRWQ71">Overview: Completing the Installation of the First AFS Machine</link>)</para>
128         </listitem>
129       </itemizedlist></para>
130
131     <indexterm>
132       <primary>overview</primary>
133
134       <secondary>installing server functionality on first AFS machine</secondary>
135     </indexterm>
136
137     <indexterm>
138       <primary>first AFS machine</primary>
139
140       <secondary>server functionality</secondary>
141     </indexterm>
142
143     <indexterm>
144       <primary>installing</primary>
145
146       <secondary>server functionality</secondary>
147
148       <tertiary>first AFS machine</tertiary>
149     </indexterm>
150   </sect1>
151
152   <sect1 id="HDRWQ18">
153     <title>Overview: Installing Server Functionality</title>
154
155     <para>In the first phase of installing your cell's first AFS machine, you install file server and database server functionality
156     by performing the following procedures: 
157     <orderedlist>
158         <listitem>
159           <para>Choose which machine to install as the first AFS machine</para>
160         </listitem>
161
162         <listitem>
163           <para>Create AFS-related directories on the local disk</para>
164         </listitem>
165
166         <listitem>
167           <para>Incorporate AFS modifications into the machine's kernel</para>
168         </listitem>
169
170         <listitem>
171           <para>Configure partitions or logical volumes for storing AFS volumes</para>
172         </listitem>
173
174         <listitem>
175           <para>On some system types (very rare), install and configure
176           an AFS-modified version of the <emphasis role="bold">fsck</emphasis>
177           program</para>
178         </listitem>
179
180         <listitem>
181           <para>If the machine is to remain a client machine, incorporate AFS into its authentication system</para>
182         </listitem>
183
184         <listitem>
185           <para>Start the Basic OverSeer (BOS) Server</para>
186         </listitem>
187
188         <listitem>
189           <para>Define the cell name and the machine's cell membership</para>
190         </listitem>
191
192         <listitem>
193           <para>Start the database server processes: Backup Server, Protection Server, and Volume Location
194           (VL) Server</para>
195         </listitem>
196
197         <listitem>
198           <para>Configure initial security mechanisms</para>
199         </listitem>
200
201         <listitem>
202           <para>Start the <emphasis role="bold">fs</emphasis> process, which incorporates three component processes: the File
203           Server, Volume Server, and Salvager</para>
204         </listitem>
205
206         <listitem>
207           <para>Optionally, start the server portion of the Update Server</para>
208         </listitem>
209
210       </orderedlist></para>
211   </sect1>
212
213   <sect1 id="HDRWQ19">
214     <title>Choosing the First AFS Machine</title>
215
216     <para>The first AFS machine you install must have sufficient disk space to store AFS volumes.
217     When you later install additional file server
218     machines in your cell, you can distribute these volumes among the different machines as you see fit.</para>
219
220     <para>These instructions configure the first AFS machine as a <emphasis>database server machine</emphasis>, and optionally as the <emphasis>binary
221     distribution machine</emphasis> for its system type and the cell's <emphasis>system control machine</emphasis>. For a
222     description of these roles, see the <emphasis>OpenAFS Administration Guide</emphasis>.</para>
223
224     <para>Installation of additional machines is simplest if the first machine has the lowest IP address of any database server
225     machine you currently plan to install. If you later install database server functionality on a machine with a lower IP address,
226     you must first update the <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file on all of your cell's client machines.
227     For more details, see <link linkend="HDRWQ114">Installing Database Server Functionality</link>.</para>
228   </sect1>
229
230   <sect1 id="Header_32">
231     <title>Creating AFS Directories</title>
232
233     <indexterm>
234       <primary>usr/afs directory</primary>
235
236       <secondary>first AFS machine</secondary>
237     </indexterm>
238
239     <indexterm>
240       <primary>first AFS machine</primary>
241
242       <secondary>/usr/afs directory</secondary>
243     </indexterm>
244
245     <indexterm>
246       <primary>creating</primary>
247
248       <secondary>/usr/afs directory</secondary>
249
250       <tertiary>first AFS machine</tertiary>
251     </indexterm>
252
253     <indexterm>
254       <primary>usr/vice/etc directory</primary>
255
256       <secondary>first AFS machine</secondary>
257     </indexterm>
258
259     <indexterm>
260       <primary>first AFS machine</primary>
261
262       <secondary>/usr/vice/etc directory</secondary>
263     </indexterm>
264
265     <indexterm>
266       <primary>creating</primary>
267
268       <secondary>/usr/vice/etc directory</secondary>
269
270       <tertiary>first AFS machine</tertiary>
271     </indexterm>
272
273     <indexterm>
274       <primary>/ as start to file and directory names</primary>
275
276       <secondary>see alphabetized entries without initial slash</secondary>
277     </indexterm>
278
279     <para>If you are installing from packages (such as Debian .deb or 
280     Fedora/SuSe .rpm files), you should now install all of the available 
281     OpenAFS packages for your system type. Typically, these will include 
282     packages for client and server functionality, and a seperate package 
283     containing a suitable kernel module for your running kernel. Consult 
284     the package lists on the OpenAFS website to determine the packages 
285     appropriate for your system.  The preparer of such packages may
286     have included some helper scripts to partially automate the
287     creation of a new cell; such scripts can supersede much of the
288     procedures described in the rest of this document.</para>
289
290     <para>If you are installing from a tarfile, or from a locally compiled 
291     source tree you should create the <emphasis role="bold">/usr/afs</emphasis>
292     and <emphasis role="bold">/usr/vice/etc</emphasis> directories on the
293     local disk, to house server and client files respectively. Subsequent 
294     instructions copy files from the distribution tarfile into them. </para>
295 <programlisting>
296    # <emphasis role="bold">mkdir /usr/afs</emphasis>
297    # <emphasis role="bold">mkdir /usr/vice</emphasis>
298    # <emphasis role="bold">mkdir /usr/vice/etc</emphasis>
299 </programlisting>
300   </sect1>
301
302   <sect1 id="HDRWQ20">
303     <title>Performing Platform-Specific Procedures</title>
304
305     <para>Several of the initial procedures for installing a file server machine differ for each system type. For convenience, the
306     following sections group them together for each system type: <itemizedlist>
307         <indexterm>
308           <primary>kernel extensions</primary>
309
310           <see>AFS kernel extensions</see>
311         </indexterm>
312
313         <indexterm>
314           <primary>loading AFS kernel extensions</primary>
315
316           <see>incorporating</see>
317         </indexterm>
318
319         <indexterm>
320           <primary>building</primary>
321
322           <secondary>AFS extensions into kernel</secondary>
323
324           <see>incorporating AFS kernel extensions</see>
325         </indexterm>
326
327         <listitem>
328           <para>Incorporate AFS modifications into the kernel.</para>
329
330           <para>The kernel on every AFS client machine and, on some systems, 
331           the AFS fileservers, must incorporate AFS extensions. On machines 
332           that use a dynamic kernel module loader, it is conventional to 
333           alter the machine's initialization script to load the AFS extensions
334           at each reboot.  The preparer of OS-format binary packages
335           may have included an init script which automates the loading
336           of the needed kernel module, eliminating a need to manually
337           configure this step. <indexterm>
338               <primary>AFS server partition</primary>
339
340               <secondary>mounted on /vicep directory</secondary>
341             </indexterm> <indexterm>
342               <primary>partition</primary>
343
344               <see>AFS server partition</see>
345             </indexterm> <indexterm>
346               <primary>logical volume</primary>
347
348               <see>AFS server partition</see>
349             </indexterm> <indexterm>
350               <primary>requirements</primary>
351
352               <secondary>AFS server partition name and location</secondary>
353             </indexterm> <indexterm>
354               <primary>naming conventions for AFS server partition</primary>
355             </indexterm> <indexterm>
356               <primary>vicep<emphasis>xx</emphasis> directory</primary>
357
358               <see>AFS server partition</see>
359             </indexterm> <indexterm>
360               <primary>directories</primary>
361
362               <secondary>/vicep<emphasis>xx</emphasis></secondary>
363
364               <see>AFS server partition</see>
365             </indexterm></para>
366         </listitem>
367
368         <listitem>
369           <para>Configure server partitions or logical volumes to house AFS volumes.</para>
370
371           <para>Every AFS file server machine should have at least one partition or logical volume dedicated to storing AFS volumes
372           (for convenience, the documentation hereafter refers to partitions only). Each server partition is mounted at a directory
373           named <emphasis role="bold">/vicep</emphasis><replaceable>xx</replaceable>, where <replaceable>xx</replaceable> is one or
374           two lowercase letters. By convention, the first 26 partitions are mounted on the directories called <emphasis
375           role="bold">/vicepa</emphasis> through <emphasis role="bold">/vicepz</emphasis>, the 27th one is mounted on the <emphasis
376           role="bold">/vicepaa</emphasis> directory, and so on through <emphasis role="bold">/vicepaz</emphasis> and <emphasis
377           role="bold">/vicepba</emphasis>, continuing up to the index corresponding to the maximum number of server partitions
378           supported in the current version of AFS (which is specified in the <emphasis>OpenAFS Release Notes</emphasis>).</para>
379
380           <para>The <emphasis role="bold">/vicep</emphasis><replaceable>xx</replaceable> directories must reside in the file server
381           machine's root directory, not in one of its subdirectories (for example, <emphasis role="bold">/usr/vicepa</emphasis> is
382           not an acceptable directory location).
383
384           The <emphasis role="bold">fileserver</emphasis> will refuse to
385           mount
386           any <emphasis role="bold">/vicep</emphasis><replaceable>xx</replaceable>
387           folders that are not separate partitions without additional
388           configuration. </para>
389
390           <warning>
391             <para>The separate partition requirement may be overridden by
392               creating a file named
393               <emphasis role="bold">/vicep<replaceable>xx</replaceable>/AlwaysAttach</emphasis>;
394               however, mixed-use partitions, whether cache or fileserver,
395               have the risk that a non-AFS use will fill the partition and
396               not leave enough free space for AFS.  Even though it is
397               allowed, be wary of configuring a mixed-use partition
398               without understanding the ramifications of doing so with the
399               workload on your filesystem.
400               <indexterm>
401                 <primary>AFS server partition</primary>
402                 <secondary>AlwaysAttach</secondary>
403               </indexterm>
404             </para>
405           </warning>
406
407           <para>You can also add or remove server partitions on an existing file server machine. For instructions, see the chapter
408           in the <emphasis>OpenAFS Administration Guide</emphasis> about maintaining server machines.</para>
409
410           <note>
411             <para>Not all file system types supported by an operating system are necessarily supported as AFS server partitions. For
412             possible restrictions, see the <emphasis>OpenAFS Release Notes</emphasis>.</para>
413           </note>
414         </listitem>
415
416         <listitem>
417           <para>On (rare) system types using the <emphasis role="bold">inode</emphasis> storage format, install and configure a modified <emphasis role="bold">fsck</emphasis> program which
418           recognizes the structures that the File Server uses to organize volume data on AFS server partitions. The <emphasis
419           role="bold">fsck</emphasis> program provided with the operating system does not understand the AFS data structures, and so
420           removes them to the <emphasis role="bold">lost+found</emphasis> directory.</para>
421         </listitem>
422
423         <listitem>
424           <para>If the machine is to remain an AFS client machine, modify the machine's authentication system so that users obtain
425           an AFS token as they log into the local file system. Using AFS is simpler and more convenient for your users if you make
426           the modifications on all client machines. Otherwise, users must perform a two or three step login procedure (login to the local
427           system, then obtain Kerberos credentials, and then issue the <emphasis role="bold">aklog</emphasis> command). For further discussion of AFS
428           authentication, see the chapter in the <emphasis>OpenAFS Administration Guide</emphasis> about cell configuration and
429           administration issues.</para>
430         </listitem>
431       </itemizedlist></para>
432
433     <para>To continue, proceed to the appropriate section: <itemizedlist>
434         <listitem>
435           <para><link linkend="HDRWQ41">Getting Started on Linux Systems</link></para>
436         </listitem>
437
438         <listitem>
439           <para><link linkend="HDRWQ45">Getting Started on Solaris Systems</link></para>
440         </listitem>
441
442         <listitem>
443           <para><link linkend="HDRWQ21">Getting Started on AIX Systems</link></para>
444         </listitem>
445       </itemizedlist></para>
446   </sect1>
447
448   <sect1 id="HDRWQ41">
449     <title>Getting Started on Linux Systems</title>
450
451     <indexterm>
452       <primary>replacing fsck program</primary>
453
454       <secondary>not necessary on Linux</secondary>
455     </indexterm>
456
457     <indexterm>
458       <primary>fsck program</primary>
459
460       <secondary>on first AFS machine</secondary>
461
462       <tertiary>Linux</tertiary>
463     </indexterm>
464
465     <indexterm>
466       <primary>first AFS machine</primary>
467
468       <secondary>fsck program</secondary>
469
470       <tertiary>on Linux</tertiary>
471     </indexterm>
472
473     <indexterm>
474       <primary>Linux</primary>
475
476       <secondary>fsck program replacement not necessary</secondary>
477     </indexterm>
478
479     <para>Since this guide was originally written, the procedure for starting 
480     OpenAFS has diverged significantly between different Linux distributions. 
481     The instructions that follow are appropriate for both the Fedora and 
482     RedHat Enterprise Linux packages distributed by OpenAFS. Additional 
483     instructions are provided for those building from source.</para>
484
485     <para>Begin by running the AFS client startup scripts, which call the
486     <emphasis role="bold">modprobe</emphasis> program to dynamically
487     load the AFS modifications into the kernel. Then create partitions for
488     storing AFS volumes. You do not need to replace the Linux <emphasis
489     role="bold">fsck</emphasis> program. If the machine is to remain an
490     AFS client machine, incorporate AFS into the machine's Pluggable
491     Authentication Module (PAM) scheme. <indexterm>
492         <primary>incorporating AFS kernel extensions</primary>
493
494         <secondary>first AFS machine</secondary>
495
496         <tertiary>Linux</tertiary>
497       </indexterm> <indexterm>
498         <primary>AFS kernel extensions</primary>
499
500         <secondary>on first AFS machine</secondary>
501
502         <tertiary>Linux</tertiary>
503       </indexterm> <indexterm>
504         <primary>first AFS machine</primary>
505
506         <secondary>AFS kernel extensions</secondary>
507
508         <tertiary>on Linux</tertiary>
509       </indexterm> <indexterm>
510         <primary>Linux</primary>
511
512         <secondary>AFS kernel extensions</secondary>
513
514         <tertiary>on first AFS machine</tertiary>
515       </indexterm></para>
516
517     <sect2 id="HDRWQ42">
518       <title>Loading AFS into the Linux Kernel</title>
519
520       <para>The <emphasis role="bold">modprobe</emphasis> program is the dynamic kernel loader for Linux. Linux does not support
521       incorporation of AFS modifications during a kernel build.</para>
522
523       <para>For AFS to function correctly, the <emphasis role="bold">modprobe</emphasis> program must run each time the machine
524       reboots, so your distribution's AFS initialization script invokes it automatically. The script also includes
525       commands that select the appropriate AFS library file automatically. In this section you run the script.</para>
526
527       <para>In later sections you verify that the script correctly initializes all AFS components, then activate a configuration
528       variable, which results in the script being incorporated into the Linux startup and shutdown sequence.</para> 
529       
530       <para>The procedure for starting up OpenAFS depends upon your distribution</para>
531       <sect3>
532         <title>Fedora and RedHat Enterprise Linux</title>
533         <para>OpenAFS provides RPMS for all current Fedora and
534           RedHat Enterprise Linux (RHEL) releases prior to EL7 on the
535           OpenAFS web site and the OpenAFS yum repository.
536         <orderedlist>
537           <listitem>
538             <para>Browse to
539             http://dl.openafs.org/dl/openafs/<replaceable>VERSION</replaceable>,
540             where VERSION is the latest stable release of
541             OpenAFS for Unix. Download the
542             openafs-repository-<replaceable>VERSION</replaceable>.noarch.rpm
543             file for Fedora systems or the
544             openafs-repository-rhel-<replaceable>VERSION</replaceable>.noarch.rpm
545             file for RedHat-based systems.
546             </para>
547           </listitem>
548           <listitem>
549             <para>Install the downloaded RPM file using the following command:
550               <programlisting>
551 # rpm -U openafs-repository*.rpm
552               </programlisting>
553             </para>
554           </listitem>
555           <listitem>
556             <para>Install the RPM set for your operating system using the yum command as follows:
557               <programlisting>
558 # yum -y install openafs-client openafs-server openafs-krb5 kmod-openafs
559               </programlisting>
560
561             </para>
562             <para>Alternatively, you may use dynamically-compiled kernel
563               modules if you have the kernel headers, a compiler, and the
564               dkms package from
565               <ulink url="http://fedoraproject.org/wiki/EPEL"><citetitle>EPEL</citetitle></ulink> installed. 
566
567             </para>
568             <para>To use dynamically-compiled kernel modules instead of statically compiled modules, use the following command instead of the kmod-openafs as shown above:
569               <programlisting>
570 # yum install openafs-client openafs-server openafs-krb5 dkms-openafs
571               </programlisting>
572             </para>
573           </listitem>
574 <!-- If you do this with current RHEL and Fedora releases you end up with
575      a dynroot'd client running - this breaks setting up the root.afs volume
576      as described later in this guide
577           <listitem>
578             <para>Run the AFS initialization script to load AFS extensions into 
579             the kernel. You can ignore any error messages about the inability 
580             to start the BOS Server or the Cache Manager or AFS client.</para>
581 <programlisting>
582    # <emphasis role="bold">/etc/rc.d/init.d/openafs-client  start</emphasis>
583 </programlisting>
584           </listitem>
585 -->
586         </orderedlist>
587       </para>
588       </sect3>
589       <sect3>
590         <title>Debian and Ubuntu Linux</title>
591         <para>OpenAFS is available as binary packages from the Debian
592           linux distribution and its derivatives such as Ubuntu.
593         <orderedlist>
594           <listitem>
595             <para>Install the client and server packages using the following command:
596               <programlisting>
597 # apt-get install openafs-client openafs-modules-dkms openafs-krb5 \
598   openafs-fileserver openafs-dbserver
599               </programlisting>
600               You will be prompted by debconf to select your cell name and
601               the size of your local cache.
602             </para>
603           </listitem>
604         </orderedlist>
605       </para>
606       <para>The Debian package also includes helper scripts
607         <literal>afs-newcell</literal> and <literal>afs-rootvol</literal>,
608         which can automate much of the remainder of this document.
609       </para>
610       </sect3>
611       <sect3>
612          <title>Systems built from source</title>
613          <para>If you are running a system where
614          you have built the system from
615          source yourself, you need to install the relevant components by hand:
616          </para>
617          <orderedlist>
618            
619           <listitem>
620             <para>Unpack the distribution tarball. The examples below assume
621             that you have extracted and built OpenAFS in the
622             <emphasis role="bold">/tmp/afsdist</emphasis> directory. If you
623             pick a different location, substitute this in all of the following
624             examples. Once you have compiled the distribution,
625             change to the source directory as indicated.
626 <programlisting>
627   # <emphasis role="bold">cd /tmp/afsdist</emphasis>
628 </programlisting></para>
629           </listitem>
630           
631           <listitem>
632             <para>Copy the AFS kernel library files to the local <emphasis role="bold">/usr/vice/etc/modload</emphasis> directory.
633             The filenames for the libraries have the format <emphasis
634             role="bold">libafs-</emphasis><replaceable>version</replaceable><emphasis role="bold">.o</emphasis>, where
635             <replaceable>version</replaceable> indicates the kernel build level. The string <emphasis role="bold">.mp</emphasis> in
636             the <replaceable>version</replaceable> indicates that the file is appropriate for machines running a multiprocessor
637             kernel. <programlisting>
638    # <emphasis role="bold">mkdir -p /usr/vice/etc/modload</emphasis>
639    # <emphasis role="bold">cp -rp src/libafs/*.ko  /usr/vice/etc/modload</emphasis>
640 </programlisting></para>
641           </listitem>
642
643           <listitem>
644             <para>Copy the AFS initialization script to the local directory for initialization files (by convention, <emphasis
645             role="bold">/etc/rc.d/init.d</emphasis> on Linux machines). Note the removal of the <emphasis role="bold">.rc</emphasis>
646             extension as you copy the script. <programlisting>
647    # <emphasis role="bold">cp -p src/afsd/afs.rc.linux /etc/rc.d/init.d/afs</emphasis>
648 </programlisting></para>
649           </listitem>
650
651         </orderedlist>
652
653       <indexterm>
654         <primary>configuring</primary>
655    
656         <secondary>AFS server partition on first AFS machine</secondary>
657
658         <tertiary>Linux</tertiary>
659       </indexterm>
660
661       <indexterm>
662         <primary>AFS server partition</primary>
663
664         <secondary>configuring on first AFS machine</secondary>
665
666         <tertiary>Linux</tertiary>
667       </indexterm>
668
669       <indexterm>
670         <primary>first AFS machine</primary>
671
672         <secondary>AFS server partition</secondary>
673
674         <tertiary>on Linux</tertiary>
675       </indexterm>
676
677       <indexterm>
678         <primary>Linux</primary>
679
680         <secondary>AFS server partition</secondary>
681
682         <tertiary>on first AFS machine</tertiary>
683       </indexterm>
684     </sect3>
685     </sect2>
686
687     <sect2 id="HDRWQ43">
688       <title>Configuring Server Partitions on Linux Systems</title>
689
690       <para>Every AFS file server machine must have at least one partition or logical volume dedicated to storing AFS volumes. Each
691       server partition is mounted at a directory named <emphasis role="bold">/vicep</emphasis><replaceable>xx</replaceable>, where
692       <replaceable>xx</replaceable> is one or two lowercase letters. The <emphasis
693       role="bold">/vicep</emphasis><replaceable>xx</replaceable> directories must reside in the file server machine's root
694       directory, not in one of its subdirectories (for example, <emphasis role="bold">/usr/vicepa</emphasis> is not an acceptable
695       directory location). For additional information, see <link linkend="HDRWQ20">Performing Platform-Specific Procedures</link>.
696       <orderedlist>
697           <listitem>
698             <para>Create a directory called <emphasis role="bold">/vicep</emphasis><replaceable>xx</replaceable> for each AFS server
699             partition you are configuring (there must be at least one). Repeat the command for each partition. <programlisting>
700    # <emphasis role="bold">mkdir /vicep</emphasis><replaceable>xx</replaceable>
701 </programlisting></para>
702           </listitem>
703
704           <listitem>
705             <para>Add a line with the following format to the file systems registry file, <emphasis
706             role="bold">/etc/fstab</emphasis>, for each directory just created. The entry maps the directory name to the disk
707             partition to be mounted on it. <programlisting>
708    /dev/<replaceable>disk</replaceable>  /vicep<replaceable>xx</replaceable>  ext2  defaults  0  2   
709 </programlisting></para>
710
711             <para>The following is an example for the first partition being configured.</para>
712
713             <programlisting>
714    /dev/sda8 /vicepa ext2 defaults 0 2
715 </programlisting>
716           </listitem>
717
718           <listitem>
719             <para>Create a file system on each partition that is to be mounted at a <emphasis
720             role="bold">/vicep</emphasis><replaceable>xx</replaceable> directory. The following command is probably appropriate, but
721             consult the Linux documentation for more information. <programlisting>
722    # <emphasis role="bold">mkfs -v /dev/</emphasis><replaceable>disk</replaceable>
723 </programlisting></para>
724           </listitem>
725
726           <listitem>
727             <para>Mount each partition by issuing either the <emphasis role="bold">mount -a</emphasis> command to mount all
728             partitions at once or the <emphasis role="bold">mount</emphasis> command to mount each partition in turn.</para>
729           </listitem>
730
731           <listitem>
732             <para>If you plan to retain client functionality on this machine after completing the installation, proceed to <link
733             linkend="HDRWQ44">Enabling AFS Login on Linux Systems</link>. Otherwise, proceed to <link linkend="HDRWQ50">Starting the
734             BOS Server</link>.</para>
735           </listitem>
736         </orderedlist></para>
737
738       <indexterm>
739         <primary>enabling AFS login</primary>
740
741         <secondary>file server machine</secondary>
742
743         <tertiary>Linux</tertiary>
744       </indexterm>
745
746       <indexterm>
747         <primary>AFS login</primary>
748
749         <secondary>on file server machine</secondary>
750
751         <tertiary>Linux</tertiary>
752       </indexterm>
753
754       <indexterm>
755         <primary>first AFS machine</primary>
756
757         <secondary>AFS login</secondary>
758
759         <tertiary>on Linux</tertiary>
760       </indexterm>
761
762       <indexterm>
763         <primary>Linux</primary>
764
765         <secondary>AFS login</secondary>
766
767         <tertiary>on file server machine</tertiary>
768       </indexterm>
769
770       <indexterm>
771         <primary>PAM</primary>
772
773         <secondary>on Linux</secondary>
774
775         <tertiary>file server machine</tertiary>
776       </indexterm>
777     </sect2>
778
779     <sect2 id="HDRWQ44">
780       <title>Enabling AFS Login on Linux Systems</title>
781
782       <note>
783         <para>If you plan to remove client functionality from this machine
784         after completing the installation, skip this section and proceed
785         to <link linkend="HDRWQ50">Starting the BOS Server</link>.</para>
786       </note>
787
788       <para>At this point you incorporate AFS into the operating system's
789       Pluggable Authentication Module (PAM) scheme.  PAM integrates all
790       authentication mechanisms on the machine, including login, to provide
791       the security infrastructure for authenticated access to and from the
792       machine.</para>
793
794       <para>You should first configure your system to obtain Kerberos v5
795       tickets as part of the authentication process, and then run an AFS PAM
796       module to obtain tokens from those tickets after authentication.  Many
797       Linux distributions come with a Kerberos v5 PAM module (usually called
798       pam-krb5 or pam_krb5), or you can download and install <ulink
799       url="http://www.eyrie.org/~eagle/software/pam-krb5">Russ Allbery's
800       Kerberos v5 PAM module</ulink>, which is tested regularly with AFS.
801       See the instructions of whatever PAM module you use for how to
802       configure it.</para>
803
804       <para>Some Kerberos v5 PAM modules do come with native AFS support
805       (usually requiring the Heimdal Kerberos implementation rather than the
806       MIT Kerberos implementation).  If you are using one of those PAM
807       modules, you can configure it to obtain AFS tokens.  It's more common,
808       however, to separate the AFS token acquisition into a separate PAM
809       module.</para>
810
811       <para>The recommended AFS PAM module is <ulink
812       url="http://www.eyrie.org/~eagle/software/pam-afs-session/">Russ
813       Allbery's pam-afs-session module</ulink>.  It should work with any of
814       the Kerberos v5 PAM modules.  To add it to the PAM configuration, you
815       often only need to add configuration to the session group:</para>
816
817       <example>
818         <title>Linux PAM session example</title>
819         <literallayout>session  required  pam_afs_session.so</literallayout>
820       </example>
821
822       <para>If you also want to obtain AFS tokens for <command>scp</command>
823       and similar commands that don't open a session, you will also need to
824       add the AFS PAM module to the auth group so that the PAM
825       <function>setcred</function> call will obtain tokens.  The
826       <literal>pam_afs_session</literal> module will always return success
827       for authentication so that it can be added to the auth group only for
828       <function>setcred</function>, so make sure that it's not marked as
829       <literal>sufficient</literal>.</para>
830
831       <example>
832         <title>Linux PAM auth example</title>
833 <literallayout>auth  [success=ok default=1]  pam_krb5.so
834 auth  [default=done]          pam_afs_session.so
835 auth  required                pam_unix.so try_first_pass</literallayout>
836       </example>
837
838       <para>This example will work if you want to try Kerberos v5 first and
839       then fall back to regular Unix authentication.
840       <literal>success=ok</literal> for the Kerberos PAM module followed by
841       <literal>default=done</literal> for the AFS PAM module will cause a
842       successful Kerberos login to run the AFS PAM module and then skip the
843       Unix authentication module.  <literal>default=1</literal> on the
844       Kerberos PAM module causes failure of that module to skip the next
845       module (the AFS PAM module) and fall back to the Unix module.  If you
846       want to try Unix authentication first and rearrange the order, be sure
847       to use <literal>default=die</literal> instead.</para>
848
849       <para>The PAM configuration is stored in different places in different
850       Linux distributions.  On Red Hat, look in
851       <filename>/etc/pam.d/system-auth</filename>.  On Debian and
852       derivatives, look in <filename>/etc/pam.d/common-session</filename>
853       and <filename>/etc/pam.d/common-auth</filename>.</para>
854
855       <para>For additional configuration examples and the configuration
856       options of the AFS PAM module, see its documentation.  For more
857       details on the available options for the PAM configuration, see the
858       Linux PAM documentation.</para>
859
860       <para>Sites which still require the deprecated
861       <command>kaserver</command> or
862       external Kerberos v4 authentication should consult <link
863       linkend="KAS015">Enabling kaserver based AFS Login on Linux
864       Systems</link> for details of how to enable AFS login on Linux.</para>
865       
866       <para>Proceed to <link linkend="HDRWQ50">Starting the BOS
867       Server</link> (or if referring to these instructions while installing
868       an additional file server machine, return to <link
869       linkend="HDRWQ108">Starting Server Programs</link>).</para>
870     </sect2>
871   </sect1>
872
873   <sect1 id="HDRWQ45">
874     <title>Getting Started on Solaris Systems</title>
875
876     <para>Begin by running the AFS initialization script to call the <emphasis role="bold">modload</emphasis> program distributed by
877     Sun Microsystems, which dynamically loads AFS modifications into the kernel. Then create partitions for storing AFS volumes, and
878     install and configure the AFS-modified <emphasis role="bold">fsck</emphasis> program to run on AFS server partitions. If the
879     machine is to remain an AFS client machine, incorporate AFS into the machine's Pluggable Authentication Module (PAM) scheme.
880     <indexterm>
881         <primary>incorporating AFS kernel extensions</primary>
882
883         <secondary>first AFS machine</secondary>
884
885         <tertiary>Solaris</tertiary>
886       </indexterm> <indexterm>
887         <primary>AFS kernel extensions</primary>
888
889         <secondary>on first AFS machine</secondary>
890
891         <tertiary>Solaris</tertiary>
892       </indexterm> <indexterm>
893         <primary>first AFS machine</primary>
894
895         <secondary>AFS kernel extensions</secondary>
896
897         <tertiary>on Solaris</tertiary>
898       </indexterm> <indexterm>
899         <primary>Solaris</primary>
900
901         <secondary>AFS kernel extensions</secondary>
902
903         <tertiary>on first AFS machine</tertiary>
904       </indexterm></para>
905
906     <sect2 id="HDRWQ46">
907       <title>Loading AFS into the Solaris Kernel</title>
908
909       <para>The <emphasis role="bold">modload</emphasis> program is the dynamic kernel loader provided by Sun Microsystems for
910       Solaris systems. Solaris does not support incorporation of AFS modifications during a kernel build.</para>
911
912       <para>For AFS to function correctly, the <emphasis role="bold">modload</emphasis> program must run each time the machine
913       reboots, so the AFS initialization script (included on the AFS CD-ROM) invokes it automatically. In this section you copy the
914       appropriate AFS library file to the location where the <emphasis role="bold">modload</emphasis> program accesses it and then
915       run the script.</para>
916
917       <para>In later sections you verify that the script correctly initializes all AFS components, then create the links that
918       incorporate AFS into the Solaris startup and shutdown sequence. <orderedlist>
919           <listitem>
920             <para>Unpack the OpenAFS Solaris distribution tarball. The examples
921             below assume that you have unpacked the files into the 
922             <emphasis role="bold">/tmp/afsdist</emphasis> directory. If you 
923             pick a diferent location, substitute this in all of the following
924             exmaples. Once you have unpacked the distribution, change directory
925             as indicated. 
926 <programlisting>
927    # <emphasis role="bold">cd  /tmp/afsdist/sun4x_56/dest/root.client/usr/vice/etc</emphasis>
928 </programlisting></para>
929           </listitem>
930
931           <listitem>
932             <para>Copy the AFS initialization script to the local directory for initialization files (by convention, <emphasis
933             role="bold">/etc/init.d</emphasis> on Solaris machines). Note the removal of the <emphasis role="bold">.rc</emphasis>
934             extension as you copy the script. <programlisting>
935    # <emphasis role="bold">cp -p  afs.rc  /etc/init.d/afs</emphasis>
936 </programlisting></para>
937           </listitem>
938
939           <listitem>
940             <para>Copy the appropriate AFS kernel library file to the local file <emphasis
941             role="bold">/kernel/fs/afs</emphasis>.</para>
942
943             <para>If the machine is running Solaris 11 on the x86_64 platform:</para>
944
945             <programlisting>
946    # <emphasis role="bold">cp -p modload/libafs64.o /kernel/drv/amd64/afs</emphasis>
947 </programlisting>
948
949             <para>If the machine is running Solaris 10 on the x86_64 platform:</para>
950
951             <programlisting>
952    # <emphasis role="bold">cp -p modload/libafs64.o /kernel/fs/amd64/afs</emphasis>
953 </programlisting>
954
955             <para>If the machine is running Solaris 2.6 or the 32-bit version of Solaris 7, its kernel supports NFS server
956             functionality, and the <emphasis role="bold">nfsd</emphasis> process is running:</para>
957
958             <programlisting>
959    # <emphasis role="bold">cp -p modload/libafs.o /kernel/fs/afs</emphasis>   
960 </programlisting>
961
962             <para>If the machine is running Solaris 2.6 or the 32-bit version of Solaris 7, and its kernel does not support NFS
963             server functionality or the <emphasis role="bold">nfsd</emphasis> process is not running:</para>
964
965             <programlisting>
966    # <emphasis role="bold">cp -p modload/libafs.nonfs.o /kernel/fs/afs</emphasis>   
967 </programlisting>
968
969             <para>If the machine is running the 64-bit version of Solaris 7, its kernel supports NFS server functionality, and the
970             <emphasis role="bold">nfsd</emphasis> process is running:</para>
971
972             <programlisting>
973    # <emphasis role="bold">cp -p modload/libafs64.o /kernel/fs/sparcv9/afs</emphasis>   
974 </programlisting>
975
976             <para>If the machine is running the 64-bit version of Solaris 7, and its kernel does not support NFS server
977             functionality or the <emphasis role="bold">nfsd</emphasis> process is not running:</para>
978
979             <programlisting>
980    # <emphasis role="bold">cp -p modload/libafs64.nonfs.o /kernel/fs/sparcv9/afs</emphasis>
981 </programlisting>
982           </listitem>
983
984           <listitem>
985             <para>Run the AFS initialization script to load AFS modifications into the kernel. You can ignore any error messages
986             about the inability to start the BOS Server or the Cache Manager or AFS client. <programlisting>
987    # <emphasis role="bold">/etc/init.d/afs start</emphasis>   
988 </programlisting></para>
989
990             <para>When an entry called <computeroutput>afs</computeroutput> does not already exist in the local <emphasis
991             role="bold">/etc/name_to_sysnum</emphasis> file, the script automatically creates it and reboots the machine to start
992             using the new version of the file. If this happens, log in again as the superuser <emphasis role="bold">root</emphasis>
993             after the reboot and run the initialization script again. This time the required entry exists in the <emphasis
994             role="bold">/etc/name_to_sysnum</emphasis> file, and the <emphasis role="bold">modload</emphasis> program runs.</para>
995
996             <programlisting>
997    login: <emphasis role="bold">root</emphasis>
998    Password: <replaceable>root_password</replaceable>
999    # <emphasis role="bold">/etc/init.d/afs start</emphasis>
1000 </programlisting>
1001           </listitem>
1002         </orderedlist></para>
1003
1004       <indexterm>
1005         <primary>replacing fsck program</primary>
1006
1007         <secondary>first AFS machine</secondary>
1008
1009         <tertiary>Solaris</tertiary>
1010       </indexterm>
1011
1012       <indexterm>
1013         <primary>fsck program</primary>
1014
1015         <secondary>on first AFS machine</secondary>
1016
1017         <tertiary>Solaris</tertiary>
1018       </indexterm>
1019
1020       <indexterm>
1021         <primary>first AFS machine</primary>
1022
1023         <secondary>fsck program</secondary>
1024
1025         <tertiary>on Solaris</tertiary>
1026       </indexterm>
1027
1028       <indexterm>
1029         <primary>Solaris</primary>
1030
1031         <secondary>fsck program</secondary>
1032
1033         <tertiary>on first AFS machine</tertiary>
1034       </indexterm>
1035     </sect2>
1036
1037     <sect2 id="HDRWQ47">
1038       <title>Configuring the AFS-modified fsck Program on Solaris Systems</title>
1039
1040       <para>In this section, you make modifications to guarantee that the appropriate <emphasis role="bold">fsck</emphasis> program
1041       runs on AFS server partitions. The <emphasis role="bold">fsck</emphasis> program provided with the operating system must never
1042       run on AFS server partitions. Because it does not recognize the structures that the File Server uses to organize volume data,
1043       it removes all of the data. To repeat:</para>
1044
1045       <para><emphasis role="bold">Never run the standard fsck program on AFS server partitions. It discards AFS volumes.</emphasis>
1046       <orderedlist>
1047           <listitem>
1048             <para>Create the <emphasis role="bold">/usr/lib/fs/afs</emphasis> directory to house the AFS-modified <emphasis
1049             role="bold">fsck</emphasis> program and related files. <programlisting>
1050    # <emphasis role="bold">mkdir /usr/lib/fs/afs</emphasis>
1051    # <emphasis role="bold">cd /usr/lib/fs/afs</emphasis>  
1052 </programlisting></para>
1053           </listitem>
1054
1055           <listitem>
1056             <para>Copy the <emphasis role="bold">vfsck</emphasis> binary to the newly created directory, changing the name as you do
1057             so. <programlisting>
1058    # <emphasis role="bold">cp  /tmp/afsdist/sun4x_56/dest/root.server/etc/vfsck  fsck</emphasis>
1059 </programlisting></para>
1060           </listitem>
1061
1062           <listitem>
1063             <para>Working in the <emphasis role="bold">/usr/lib/fs/afs</emphasis> directory, create the following links to Solaris
1064             libraries: <programlisting>
1065    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/clri</emphasis>  
1066    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/df</emphasis>
1067    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/edquota</emphasis>
1068    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/ff</emphasis>
1069    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/fsdb</emphasis>  
1070    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/fsirand</emphasis>
1071    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/fstyp</emphasis>
1072    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/labelit</emphasis>
1073    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/lockfs</emphasis>
1074    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/mkfs</emphasis>  
1075    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/mount</emphasis>
1076    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/ncheck</emphasis>
1077    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/newfs</emphasis>
1078    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/quot</emphasis>
1079    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/quota</emphasis>
1080    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/quotaoff</emphasis>
1081    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/quotaon</emphasis>
1082    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/repquota</emphasis>
1083    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/tunefs</emphasis>
1084    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/ufsdump</emphasis>
1085    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/ufsrestore</emphasis>
1086    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/volcopy</emphasis>
1087 </programlisting></para>
1088           </listitem>
1089
1090           <listitem>
1091             <para>Append the following line to the end of the file <emphasis role="bold">/etc/dfs/fstypes</emphasis>.
1092             <programlisting>
1093    afs AFS Utilities
1094 </programlisting></para>
1095           </listitem>
1096
1097           <listitem>
1098             <para>Edit the <emphasis role="bold">/sbin/mountall</emphasis> file, making two changes. <itemizedlist>
1099                 <listitem>
1100                   <para>Add an entry for AFS to the <computeroutput>case</computeroutput> statement for option 2, so that it reads
1101                   as follows: <programlisting>
1102    case "$2" in
1103    ufs)    foptions="-o p"
1104            ;;
1105    afs)    foptions="-o p"
1106            ;;
1107    s5)     foptions="-y -t /var/tmp/tmp$$ -D"
1108            ;;
1109    *)      foptions="-y"
1110            ;;
1111 </programlisting></para>
1112                 </listitem>
1113
1114                 <listitem>
1115                   <para>Edit the file so that all AFS and UFS partitions are checked in parallel. Replace the following section of
1116                   code: <programlisting>
1117    # For  fsck purposes, we make a distinction between ufs and
1118    # other file systems
1119    #
1120    if [ "$fstype" = "ufs" ]; then
1121         ufs_fscklist="$ufs_fscklist $fsckdev"
1122         saveentry $fstype "$OPTIONS" $special $mountp
1123         continue
1124    fi  
1125 </programlisting></para>
1126
1127                   <para>with the following section of code:</para>
1128
1129                   <programlisting>
1130    # For fsck purposes, we make a distinction between ufs/afs
1131    # and other file systems.
1132    #
1133    if [ "$fstype" = "ufs" -o "$fstype" = "afs" ]; then
1134         ufs_fscklist="$ufs_fscklist $fsckdev"
1135         saveentry $fstype "$OPTIONS" $special $mountp
1136         continue
1137    fi
1138 </programlisting>
1139                 </listitem>
1140               </itemizedlist></para>
1141           </listitem>
1142         </orderedlist></para>
1143
1144       <indexterm>
1145         <primary>configuring</primary>
1146
1147         <secondary>AFS server partition on first AFS machine</secondary>
1148
1149         <tertiary>Solaris</tertiary>
1150       </indexterm>
1151
1152       <indexterm>
1153         <primary>AFS server partition</primary>
1154
1155         <secondary>configuring on first AFS machine</secondary>
1156
1157         <tertiary>Solaris</tertiary>
1158       </indexterm>
1159
1160       <indexterm>
1161         <primary>first AFS machine</primary>
1162
1163         <secondary>AFS server partition</secondary>
1164
1165         <tertiary>on Solaris</tertiary>
1166       </indexterm>
1167
1168       <indexterm>
1169         <primary>Solaris</primary>
1170
1171         <secondary>AFS server partition</secondary>
1172
1173         <tertiary>on first AFS machine</tertiary>
1174       </indexterm>
1175     </sect2>
1176
1177     <sect2 id="HDRWQ48">
1178       <title>Configuring Server Partitions on Solaris Systems</title>
1179
1180       <para>Every AFS file server machine must have at least one partition or logical volume dedicated to storing AFS volumes. Each
1181       server partition is mounted at a directory named <emphasis role="bold">/vicep</emphasis><replaceable>xx</replaceable>, where
1182       <replaceable>xx</replaceable> is one or two lowercase letters. The <emphasis
1183       role="bold">/vicep</emphasis><replaceable>xx</replaceable> directories must reside in the file server machine's root
1184       directory, not in one of its subdirectories (for example, <emphasis role="bold">/usr/vicepa</emphasis> is not an acceptable
1185       directory location). For additional information, see <link linkend="HDRWQ20">Performing Platform-Specific Procedures</link>.
1186       <orderedlist>
1187           <listitem>
1188             <para>Create a directory called <emphasis role="bold">/vicep</emphasis><replaceable>xx</replaceable> for each AFS server
1189             partition you are configuring (there must be at least one). Repeat the command for each partition. <programlisting>
1190    # <emphasis role="bold">mkdir /vicep</emphasis><replaceable>xx</replaceable>
1191 </programlisting></para>
1192           </listitem>
1193
1194           <listitem>
1195             <para>Add a line with the following format to the file systems registry file, <emphasis
1196             role="bold">/etc/vfstab</emphasis>, for each partition to be mounted on a directory created in the previous step. Note
1197             the value <computeroutput>afs</computeroutput> in the fourth field, which tells Solaris to use the AFS-modified
1198             <emphasis role="bold">fsck</emphasis> program on this partition. <programlisting>
1199    /dev/dsk/<replaceable>disk</replaceable>   /dev/rdsk/<replaceable>disk</replaceable>   /vicep<replaceable>xx</replaceable>   afs   <replaceable>boot_order</replaceable>  yes  
1200 </programlisting></para>
1201
1202             <para>The following is an example for the first partition being configured.</para>
1203
1204             <programlisting>
1205    /dev/dsk/c0t6d0s1 /dev/rdsk/c0t6d0s1 /vicepa afs 3 yes
1206 </programlisting>
1207           </listitem>
1208
1209           <listitem>
1210             <para>Create a file system on each partition that is to be mounted at a <emphasis
1211             role="bold">/vicep</emphasis><replaceable>xx</replaceable> directory. The following command is probably appropriate, but
1212             consult the Solaris documentation for more information. <programlisting>
1213    # <emphasis role="bold">newfs -v /dev/rdsk/</emphasis><replaceable>disk</replaceable>
1214 </programlisting></para>
1215           </listitem>
1216
1217           <listitem>
1218             <para>Issue the <emphasis role="bold">mountall</emphasis> command to mount all partitions at once.</para>
1219           </listitem>
1220
1221           <listitem>
1222             <para>If you plan to retain client functionality on this machine after completing the installation, proceed to <link
1223             linkend="HDRWQ49">Enabling AFS Login and Editing the File Systems Clean-up Script on Solaris Systems</link>. Otherwise,
1224             proceed to <link linkend="HDRWQ50">Starting the BOS Server</link>.</para>
1225           </listitem>
1226         </orderedlist></para>
1227     </sect2>
1228
1229     <sect2 id="HDRWQ49">
1230       <title>Enabling AFS Login on Solaris Systems</title>
1231       <indexterm>
1232         <primary>enabling AFS login</primary>
1233
1234         <secondary>file server machine</secondary>
1235
1236         <tertiary>Solaris</tertiary>
1237       </indexterm>
1238
1239       <indexterm>
1240         <primary>AFS login</primary>
1241
1242         <secondary>on file server machine</secondary>
1243
1244         <tertiary>Solaris</tertiary>
1245       </indexterm>
1246
1247       <indexterm>
1248         <primary>first AFS machine</primary>
1249
1250         <secondary>AFS login</secondary>
1251
1252         <tertiary>on Solaris</tertiary>
1253       </indexterm>
1254
1255       <indexterm>
1256         <primary>Solaris</primary>
1257
1258         <secondary>AFS login</secondary>
1259
1260         <tertiary>on file server machine</tertiary>
1261       </indexterm>
1262
1263       <indexterm>
1264         <primary>PAM</primary>
1265
1266         <secondary>on Solaris</secondary>
1267
1268         <tertiary>file server machine</tertiary>
1269       </indexterm>
1270
1271       <note>
1272         <para>If you plan to remove client functionality from this machine after completing the installation, skip this section and
1273         proceed to <link linkend="HDRWQ50">Starting the BOS Server</link>.</para>
1274       </note>
1275
1276       <para>At this point you incorporate AFS into the operating system's
1277       Pluggable Authentication Module (PAM) scheme.  PAM integrates all
1278       authentication mechanisms on the machine, including login, to provide
1279       the security infrastructure for authenticated access to and from the
1280       machine.</para>
1281
1282       <para>Explaining PAM is beyond the scope of this document.  It is
1283       assumed that you understand the syntax and meanings of settings in the
1284       PAM configuration file (for example, how the
1285       <computeroutput>other</computeroutput> entry works, the effect of
1286       marking an entry as <computeroutput>required</computeroutput>,
1287       <computeroutput>optional</computeroutput>, or
1288       <computeroutput>sufficient</computeroutput>, and so on).</para>
1289
1290       <para>You should first configure your system to obtain Kerberos v5
1291       tickets as part of the authentication process, and then run an AFS PAM
1292       module to obtain tokens from those tickets after authentication.
1293       Current versions of Solaris come with a Kerberos v5 PAM module that
1294       will work, or you can download and install <ulink
1295       url="http://www.eyrie.org/~eagle/software/pam-krb5">Russ Allbery's
1296       Kerberos v5 PAM module</ulink>, which is tested regularly with AFS.
1297       See the instructions of whatever PAM module you use for how to
1298       configure it.</para>
1299
1300       <para>Some Kerberos v5 PAM modules do come with native AFS support
1301       (usually requiring the Heimdal Kerberos implementation rather than the
1302       MIT Kerberos implementation).  If you are using one of those PAM
1303       modules, you can configure it to obtain AFS tokens.  It's more common,
1304       however, to separate the AFS token acquisition into a separate PAM
1305       module.</para>
1306
1307       <para>The recommended AFS PAM module is <ulink
1308       url="http://www.eyrie.org/~eagle/software/pam-afs-session/">Russ
1309       Allbery's pam-afs-session module</ulink>.  It should work with any of
1310       the Kerberos v5 PAM modules.  To add it to the PAM configuration, you
1311       often only need to add configuration to the session group in
1312       <filename>pam.conf</filename>:</para>
1313
1314       <example>
1315         <title>Solaris PAM session example</title>
1316         <literallayout>login session required pam_afs_session.so</literallayout>
1317       </example>
1318
1319       <para>This example enables PAM authentication only for console login.
1320       You may want to add a similar line for the ssh service and for any
1321       other login service that you use, including possibly the
1322       <literal>other</literal> service (which serves as a catch-all).  You
1323       may also want to add options to the AFS PAM session module
1324       (particularly <literal>retain_after_close</literal>, which is
1325       necessary for some versions of Solaris.</para>
1326
1327       <para>For additional configuration examples and the configuration
1328       options of the AFS PAM module, see its documentation.  For more
1329       details on the available options for the PAM configuration, see the
1330       <filename>pam.conf</filename> manual page.</para>
1331
1332       <para>Sites which still require <emphasis
1333       role="bold">kaserver</emphasis> or external Kerberos v4 authentication
1334       should consult <link linkend="KAS016">"Enabling kaserver based AFS
1335       Login on Solaris Systems"</link> for details of how to enable AFS
1336       login on Solaris.</para>
1337
1338       <para>Proceed to <link linkend="HDRWQ49a">Editing the File Systems 
1339       Clean-up Script on Solaris Systems</link></para>
1340     </sect2>
1341     <sect2 id="HDRWQ49a">
1342       <title>Editing the File Systems Clean-up Script on Solaris Systems</title>
1343       <indexterm>
1344         <primary>Solaris</primary>
1345
1346         <secondary>file systems clean-up script</secondary>
1347
1348         <tertiary>on file server machine</tertiary>
1349       </indexterm>
1350
1351       <indexterm>
1352         <primary>file systems clean-up script (Solaris)</primary>
1353
1354         <secondary>file server machine</secondary>
1355       </indexterm>
1356
1357       <indexterm>
1358         <primary>scripts</primary>
1359
1360         <secondary>file systems clean-up (Solaris)</secondary>
1361
1362         <tertiary>file server machine</tertiary>
1363       </indexterm>
1364
1365       
1366         <orderedlist>
1367           <listitem>
1368             <para>Some Solaris distributions include a script that locates and removes unneeded files from various file systems. Its
1369             conventional location is <emphasis role="bold">/usr/lib/fs/nfs/nfsfind</emphasis>. The script generally uses an argument
1370             to the <emphasis role="bold">find</emphasis> command to define which file systems to search. In this step you modify the
1371             command to exclude the <emphasis role="bold">/afs</emphasis> directory. Otherwise, the command traverses the AFS
1372             filespace of every cell that is accessible from the machine, which can take many hours. The following alterations are
1373             possibilities, but you must verify that they are appropriate for your cell.</para>
1374
1375             <para>The first possible alteration is to add the <emphasis role="bold">-local</emphasis> flag to the existing command,
1376             so that it looks like the following:</para>
1377
1378             <programlisting>
1379    find $dir -local -name .nfs\* -mtime +7 -mount -exec rm -f {} \;   
1380 </programlisting>
1381
1382             <para>Another alternative is to exclude any directories whose names begin with the lowercase letter <emphasis
1383             role="bold">a</emphasis> or a non-alphabetic character.</para>
1384
1385             <programlisting>
1386    find /[A-Zb-z]*  <replaceable>remainder of existing command</replaceable>   
1387 </programlisting>
1388
1389             <para>Do not use the following command, which still searches under the <emphasis role="bold">/afs</emphasis> directory,
1390             looking for a subdirectory of type <emphasis role="bold">4.2</emphasis>.</para>
1391
1392             <programlisting>
1393    find / -fstype 4.2     /* <replaceable>do not use</replaceable> */
1394 </programlisting>
1395           </listitem>
1396
1397           <listitem>
1398             <para>Proceed to <link linkend="HDRWQ50">Starting the BOS Server</link> (or if referring to these instructions while
1399             installing an additional file server machine, return to <link linkend="HDRWQ108">Starting Server
1400             Programs</link>).</para>
1401           </listitem>
1402         </orderedlist>
1403
1404       <indexterm>
1405         <primary>Basic OverSeer Server</primary>
1406
1407         <see>BOS Server</see>
1408       </indexterm>
1409
1410       <indexterm>
1411         <primary>BOS Server</primary>
1412
1413         <secondary>starting</secondary>
1414
1415         <tertiary>first AFS machine</tertiary>
1416       </indexterm>
1417
1418       <indexterm>
1419         <primary>starting</primary>
1420
1421         <secondary>BOS Server</secondary>
1422
1423         <tertiary>first AFS machine</tertiary>
1424       </indexterm>
1425
1426       <indexterm>
1427         <primary>first AFS machine</primary>
1428
1429         <secondary>BOS Server</secondary>
1430       </indexterm>
1431
1432       <indexterm>
1433         <primary>authorization checking (disabling)</primary>
1434
1435         <secondary>first AFS machine</secondary>
1436       </indexterm>
1437
1438       <indexterm>
1439         <primary>disabling authorization checking</primary>
1440
1441         <secondary>first AFS machine</secondary>
1442       </indexterm>
1443
1444       <indexterm>
1445         <primary>first AFS machine</primary>
1446
1447         <secondary>authorization checking (disabling)</secondary>
1448       </indexterm>
1449     </sect2>
1450   </sect1>
1451
1452   <sect1 id="HDRWQ21">
1453     <title>Getting Started on AIX Systems</title>
1454
1455     <para>Begin by running the AFS initialization script to call the AIX kernel extension facility, which dynamically loads AFS
1456     modifications into the kernel. Then use the <emphasis role="bold">SMIT</emphasis> program to configure partitions for storing
1457     AFS volumes, and replace the AIX <emphasis role="bold">fsck</emphasis> program helper with a version that correctly handles AFS
1458     volumes. If the machine is to remain an AFS client machine, incorporate AFS into the AIX secondary authentication system.
1459     <indexterm>
1460         <primary>incorporating AFS kernel extensions</primary>
1461
1462         <secondary>first AFS machine</secondary>
1463
1464         <tertiary>AIX</tertiary>
1465       </indexterm> <indexterm>
1466         <primary>AFS kernel extensions</primary>
1467
1468         <secondary>on first AFS machine</secondary>
1469
1470         <tertiary>AIX</tertiary>
1471       </indexterm> <indexterm>
1472         <primary>first AFS machine</primary>
1473
1474         <secondary>AFS kernel extensions</secondary>
1475
1476         <tertiary>on AIX</tertiary>
1477       </indexterm> <indexterm>
1478         <primary>AIX</primary>
1479
1480         <secondary>AFS kernel extensions</secondary>
1481
1482         <tertiary>on first AFS machine</tertiary>
1483       </indexterm></para>
1484
1485     <sect2 id="HDRWQ22">
1486       <title>Loading AFS into the AIX Kernel</title>
1487
1488       <para>The AIX kernel extension facility is the dynamic kernel loader
1489       provided by IBM Corporation.  AIX does not support incorporation of
1490       AFS modifications during a kernel build.</para>
1491
1492       <para>For AFS to function correctly, the kernel extension facility must run each time the machine reboots, so the AFS
1493       initialization script (included in the AFS distribution) invokes it automatically. In this section you copy the script to the
1494       conventional location and edit it to select the appropriate options depending on whether NFS is also to run.</para>
1495
1496       <para>After editing the script, you run it to incorporate AFS into the kernel. In later sections you verify that the script
1497       correctly initializes all AFS components, then configure the AIX <emphasis role="bold">inittab</emphasis> file so that the
1498       script runs automatically at reboot. <orderedlist>
1499           <listitem>
1500             <para>Unpack the distribution tarball. The examples below assume 
1501             that you have unpacked the files into the 
1502             <emphasis role="bold">/tmp/afsdist</emphasis> directory. If you 
1503             pick a different location, substitute this in all of the following 
1504             examples. Once you have unpacked the distribution, 
1505             change directory as indicated.
1506 <programlisting>
1507    # <emphasis role="bold">cd /tmp/afsdist/rs_aix42/dest/root.client/usr/vice/etc</emphasis>
1508 </programlisting></para>
1509           </listitem>
1510
1511           <listitem>
1512             <para>Copy the AFS kernel library files to the local <emphasis role="bold">/usr/vice/etc/dkload</emphasis> directory,
1513             and the AFS initialization script to the <emphasis role="bold">/etc</emphasis> directory. <programlisting>
1514    # <emphasis role="bold">cp -rp  dkload  /usr/vice/etc</emphasis>
1515    # <emphasis role="bold">cp -p  rc.afs  /etc/rc.afs</emphasis>
1516 </programlisting></para>
1517           </listitem>
1518
1519           <listitem>
1520             <para>Edit the <emphasis role="bold">/etc/rc.afs</emphasis> script, setting the <computeroutput>NFS</computeroutput>
1521             variable as indicated.</para>
1522
1523             <para>If the machine is not to function as an NFS/AFS Translator, set the <computeroutput>NFS</computeroutput> variable
1524             as follows.</para>
1525
1526             <programlisting>
1527    NFS=$NFS_NONE
1528 </programlisting>
1529
1530             <para>If the machine is to function as an NFS/AFS Translator and is running AIX 4.2.1 or higher, set the
1531             <computeroutput>NFS</computeroutput> variable as follows. Note that NFS must already be loaded into the kernel, which
1532             happens automatically on systems running AIX 4.1.1 and later, as long as the file <emphasis
1533             role="bold">/etc/exports</emphasis> exists.</para>
1534
1535             <programlisting>
1536    NFS=$NFS_IAUTH
1537 </programlisting>
1538           </listitem>
1539
1540           <listitem>
1541             <para>Invoke the <emphasis role="bold">/etc/rc.afs</emphasis> script to load AFS modifications into the kernel. You can
1542             ignore any error messages about the inability to start the BOS Server or the Cache Manager or AFS client.
1543             <programlisting>
1544    # <emphasis role="bold">/etc/rc.afs</emphasis>
1545 </programlisting></para>
1546           </listitem>
1547         </orderedlist></para>
1548
1549       <indexterm>
1550         <primary>configuring</primary>
1551
1552         <secondary>AFS server partition on first AFS machine</secondary>
1553
1554         <tertiary>AIX</tertiary>
1555       </indexterm>
1556
1557       <indexterm>
1558         <primary>AFS server partition</primary>
1559
1560         <secondary>configuring on first AFS machine</secondary>
1561
1562         <tertiary>AIX</tertiary>
1563       </indexterm>
1564
1565       <indexterm>
1566         <primary>first AFS machine</primary>
1567
1568         <secondary>AFS server partition</secondary>
1569
1570         <tertiary>on AIX</tertiary>
1571       </indexterm>
1572
1573       <indexterm>
1574         <primary>AIX</primary>
1575
1576         <secondary>AFS server partition</secondary>
1577
1578         <tertiary>on first AFS machine</tertiary>
1579       </indexterm>
1580     </sect2>
1581
1582     <sect2 id="HDRWQ23">
1583       <title>Configuring Server Partitions on AIX Systems</title>
1584
1585       <para>Every AFS file server machine must have at least one partition or logical volume dedicated to storing AFS volumes. Each
1586       server partition is mounted at a directory named <emphasis role="bold">/vicep</emphasis><replaceable>xx</replaceable>, where
1587       <replaceable>xx</replaceable> is one or two lowercase letters. The <emphasis
1588       role="bold">/vicep</emphasis><replaceable>xx</replaceable> directories must reside in the file server machine's root
1589       directory, not in one of its subdirectories (for example, <emphasis role="bold">/usr/vicepa</emphasis> is not an acceptable
1590       directory location). For additional information, see <link linkend="HDRWQ20">Performing Platform-Specific
1591       Procedures</link>.</para>
1592
1593       <para>To configure server partitions on an AIX system, perform the following procedures: <orderedlist>
1594           <listitem>
1595             <para>Create a directory called <emphasis role="bold">/vicep</emphasis><replaceable>xx</replaceable> for each AFS server
1596             partition you are configuring (there must be at least one). Repeat the command for each partition. <programlisting>
1597    # <emphasis role="bold">mkdir /vicep</emphasis><replaceable>xx</replaceable>
1598 </programlisting></para>
1599           </listitem>
1600
1601           <listitem>
1602             <para>Use the <emphasis role="bold">SMIT</emphasis> program to create a journaling file system on each partition to be
1603             configured as an AFS server partition.</para>
1604           </listitem>
1605
1606           <listitem>
1607             <para>Mount each partition at one of the <emphasis role="bold">/vicep</emphasis><replaceable>xx</replaceable>
1608             directories. Choose one of the following three methods: <itemizedlist>
1609                 <listitem>
1610                   <para>Use the <emphasis role="bold">SMIT</emphasis> program</para>
1611                 </listitem>
1612
1613                 <listitem>
1614                   <para>Use the <emphasis role="bold">mount -a</emphasis> command to mount all partitions at once</para>
1615                 </listitem>
1616
1617                 <listitem>
1618                   <para>Use the <emphasis role="bold">mount</emphasis> command on each partition in turn</para>
1619                 </listitem>
1620               </itemizedlist></para>
1621
1622             <para>Also configure the partitions so that they are mounted automatically at each reboot. For more information, refer
1623             to the AIX documentation.</para>
1624           </listitem>
1625         </orderedlist></para>
1626
1627       <indexterm>
1628         <primary>replacing fsck program</primary>
1629
1630         <secondary>first AFS machine</secondary>
1631
1632         <tertiary>AIX</tertiary>
1633       </indexterm>
1634
1635       <indexterm>
1636         <primary>fsck program</primary>
1637
1638         <secondary>on first AFS machine</secondary>
1639
1640         <tertiary>AIX</tertiary>
1641       </indexterm>
1642
1643       <indexterm>
1644         <primary>first AFS machine</primary>
1645
1646         <secondary>fsck program</secondary>
1647
1648         <tertiary>on AIX</tertiary>
1649       </indexterm>
1650
1651       <indexterm>
1652         <primary>AIX</primary>
1653
1654         <secondary>fsck program</secondary>
1655
1656         <tertiary>on first AFS machine</tertiary>
1657       </indexterm>
1658     </sect2>
1659
1660     <sect2 id="HDRWQ24">
1661       <title>Replacing the fsck Program Helper on AIX Systems</title>
1662
1663       <note><para>The AFS modified fsck program is not required on AIX 5.1 
1664       systems, and the <emphasis role="bold">v3fshelper</emphasis> program
1665       refered to below is not shipped for these systems.</para></note>
1666       
1667       <para>In this section, you make modifications to guarantee that the appropriate <emphasis role="bold">fsck</emphasis> program
1668       runs on AFS server partitions. The <emphasis role="bold">fsck</emphasis> program provided with the operating system must never
1669       run on AFS server partitions. Because it does not recognize the structures that the File Server uses to organize volume data,
1670       it removes all of the data. To repeat:</para>
1671
1672       <para><emphasis role="bold">Never run the standard fsck program on AFS server partitions. It discards AFS
1673       volumes.</emphasis></para>
1674
1675       <para>On AIX systems, you do not replace the <emphasis role="bold">fsck</emphasis> binary itself, but rather the
1676       <emphasis>program helper</emphasis> file included in the AIX distribution as <emphasis
1677       role="bold">/sbin/helpers/v3fshelper</emphasis>. <orderedlist>
1678           <listitem>
1679             <para>Move the AIX <emphasis role="bold">fsck</emphasis> program helper to a safe location and install the version from
1680             the AFS distribution in its place. 
1681 <programlisting>
1682    # <emphasis role="bold">cd /sbin/helpers</emphasis>
1683    # <emphasis role="bold">mv v3fshelper v3fshelper.noafs</emphasis>
1684    # <emphasis role="bold">cp -p /tmp/afsdist/rs_aix42/dest/root.server/etc/v3fshelper v3fshelper</emphasis>
1685 </programlisting></para>
1686           </listitem>
1687
1688           <listitem>
1689             <para>If you plan to retain client functionality on this machine after completing the installation, proceed to <link
1690             linkend="HDRWQ25">Enabling AFS Login on AIX Systems</link>. Otherwise, proceed to <link linkend="HDRWQ50">Starting the
1691             BOS Server</link>.</para>
1692           </listitem>
1693         </orderedlist></para>
1694
1695       <indexterm>
1696         <primary>enabling AFS login</primary>
1697
1698         <secondary>file server machine</secondary>
1699
1700         <tertiary>AIX</tertiary>
1701       </indexterm>
1702
1703       <indexterm>
1704         <primary>AFS login</primary>
1705
1706         <secondary>on file server machine</secondary>
1707
1708         <tertiary>AIX</tertiary>
1709       </indexterm>
1710
1711       <indexterm>
1712         <primary>first AFS machine</primary>
1713
1714         <secondary>AFS login</secondary>
1715
1716         <tertiary>on AIX</tertiary>
1717       </indexterm>
1718
1719       <indexterm>
1720         <primary>AIX</primary>
1721
1722         <secondary>AFS login</secondary>
1723
1724         <tertiary>on file server machine</tertiary>
1725       </indexterm>
1726
1727       <indexterm>
1728         <primary>secondary authentication system (AIX)</primary>
1729
1730         <secondary>server machine</secondary>
1731       </indexterm>
1732     </sect2>
1733
1734     <sect2 id="HDRWQ25">
1735       <title>Enabling AFS Login on AIX Systems</title>
1736
1737       <note>
1738         <para>If you plan to remove client functionality from this machine after completing the installation, skip this section and
1739         proceed to <link linkend="HDRWQ50">Starting the BOS Server</link>.</para>
1740       </note>
1741
1742       <para>In modern AFS installations, you should be using Kerberos v5
1743       for user login, and obtaining AFS tokens following this authentication
1744       step.</para>
1745       
1746       <para>There are currently no instructions available on configuring AIX to
1747       automatically obtain AFS tokens at login. Following login, users can 
1748       obtain tokens by running the <emphasis role="bold">aklog</emphasis> 
1749       command</para>
1750      
1751       <para>Sites which still require <emphasis role="bold">kaserver</emphasis>
1752       or external Kerberos v4 authentication should consult 
1753       <link linkend="KAS012">Enabling kaserver based AFS login on AIX systems</link>
1754       for details of how to enable AIX login.</para>
1755       
1756       <para>Proceed to <link linkend="HDRWQ50">Starting the BOS Server</link> 
1757       (or if referring to these instructions while installing an additional 
1758       file server machine, return to <link linkend="HDRWQ108">Starting Server
1759       Programs</link>).</para>
1760     </sect2>
1761   </sect1>
1762   <sect1 id="HDRWQ50">
1763     <title>Starting the BOS Server</title>
1764
1765     <para>You are now ready to start the AFS server processes on this machine. 
1766     If you are not working from a packaged distribution, begin by installing the
1767     AFS server binaries to the conventional local disk
1768     location, the <emphasis role="bold">/usr/afs/bin</emphasis> directory. The 
1769     following instructions also create files in other subdirectories of the 
1770     <emphasis role="bold">/usr/afs</emphasis> directory.</para>
1771
1772     <para>Then obtain a krb5 keytab for use by the servers in the cell.
1773     Once the keytab is in place, issue the
1774     <emphasis role="bold">bosserver</emphasis> command to initialize
1775     the Basic OverSeer (BOS) Server, which
1776     monitors and controls other AFS server processes on its server machine.
1777     Because you have not yet configured your cell's AFS authentication and authorization
1778     mechanisms, you must always use the
1779     <emphasis role="bold">-localauth</emphasis> flag to commands, to use a
1780     printed token that does not correspond to a normal krb5 identity.</para>
1781     <para>Older versions of these instructions used the
1782     <emphasis role="bold">-noauth</emphasis> flag, which completely disables
1783     all authentication and authorization checking, allowing anyone at all
1784     to control the system.  Do not use this flag!  It is highly insecure,
1785     and is no longer needed.</para>
1786
1787     <para>As it initializes for the first time, the BOS Server creates the following directories and files, setting the owner to the
1788     local superuser <emphasis role="bold">root</emphasis> and the mode bits to limit the ability to write (and in some cases, read)
1789     them. For a description of the contents and function of these directories and files, see the chapter in the <emphasis>OpenAFS
1790     Administration Guide</emphasis> about administering server machines. For further discussion of the mode bit settings, see <link
1791     linkend="HDRWQ96">Protecting Sensitive AFS Directories</link>. <indexterm>
1792         <primary>Binary Distribution</primary>
1793
1794         <secondary>copying server files from</secondary>
1795
1796         <tertiary>first AFS machine</tertiary>
1797       </indexterm> <indexterm>
1798         <primary>first AFS machine</primary>
1799
1800         <secondary>subdirectories of /usr/afs</secondary>
1801       </indexterm> <indexterm>
1802         <primary>creating</primary>
1803
1804         <secondary>/usr/afs/bin directory</secondary>
1805
1806         <tertiary>first AFS machine</tertiary>
1807       </indexterm> <indexterm>
1808         <primary>creating</primary>
1809
1810         <secondary>/usr/afs/etc directory</secondary>
1811
1812         <tertiary>first AFS machine</tertiary>
1813       </indexterm> <indexterm>
1814         <primary>copying</primary>
1815
1816         <secondary>server files to local disk</secondary>
1817
1818         <tertiary>first AFS machine</tertiary>
1819       </indexterm> <indexterm>
1820         <primary>first AFS machine</primary>
1821
1822         <secondary>copying</secondary>
1823
1824         <tertiary>server files to local disk</tertiary>
1825       </indexterm> <indexterm>
1826         <primary>usr/afs/bin directory</primary>
1827
1828         <secondary>first AFS machine</secondary>
1829       </indexterm> <indexterm>
1830         <primary>usr/afs/etc directory</primary>
1831
1832         <secondary>first AFS machine</secondary>
1833       </indexterm> <indexterm>
1834         <primary>usr/afs/db directory</primary>
1835       </indexterm> <indexterm>
1836         <primary>usr/afs/local directory</primary>
1837       </indexterm> <indexterm>
1838         <primary>usr/afs/logs directory</primary>
1839       </indexterm> <itemizedlist>
1840         <listitem>
1841           <para><emphasis role="bold">/usr/afs/db</emphasis></para>
1842         </listitem>
1843
1844         <listitem>
1845           <para><emphasis role="bold">/usr/afs/etc/CellServDB</emphasis></para>
1846         </listitem>
1847
1848         <listitem>
1849           <para><emphasis role="bold">/usr/afs/etc/ThisCell</emphasis></para>
1850         </listitem>
1851
1852         <listitem>
1853           <para><emphasis role="bold">/usr/afs/local</emphasis></para>
1854         </listitem>
1855
1856         <listitem>
1857           <para><emphasis role="bold">/usr/afs/logs</emphasis></para>
1858         </listitem>
1859       </itemizedlist></para>
1860
1861     <para>The BOS Server also creates symbolic links called <emphasis role="bold">/usr/vice/etc/ThisCell</emphasis> and <emphasis
1862     role="bold">/usr/vice/etc/CellServDB</emphasis> to the corresponding files in the <emphasis role="bold">/usr/afs/etc</emphasis>
1863     directory. The AFS command interpreters consult the <emphasis role="bold">CellServDB</emphasis> and <emphasis
1864     role="bold">ThisCell</emphasis> files in the <emphasis role="bold">/usr/vice/etc</emphasis> directory because they generally run
1865     on client machines. On machines that are AFS servers only (as this machine currently is), the files reside only in the <emphasis
1866     role="bold">/usr/afs/etc</emphasis> directory; the links enable the command interpreters to retrieve the information they need.
1867     Later instructions for installing the client functionality replace the links with actual files.</para>
1868     <sect2>
1869       <title>Generating the Cell's Kerberos V5 Keys</title>
1870
1871       <para>This guide uses krb5 for authentication; do not use the
1872         legacy <emphasis role="bold">kaserver</emphasis> for new
1873         installations.</para>
1874       <para>This section creates only the cell-wide shared secret key;
1875         administrative users will be created later in the procedure.
1876         This cell-wide key has the principal name
1877         <emphasis role="bold">afs/<replaceable>cell</replaceable></emphasis>. 
1878         No user logs in under this identity, but it is used to encrypt the
1879         server tickets that the KDC grants to AFS clients for presentation
1880         to server processes during mutual authentication.  (The
1881         chapter in the <emphasis>OpenAFS Administration Guide</emphasis>
1882         about cell configuration and administration describes the
1883         role of server encryption keys in mutual authentication.)</para>
1884       <para>The OpenAFS 1.8.x series stores the cell-wide shared keys in
1885         the file <emphasis role="bold">/usr/afs/etc/KeyFileExt</emphasis>,
1886         whereas the 1.6.x series uses a krb5 keytab format file in
1887         <emphasis role="bold">/usr/afs/etc/rxkad.keytab</emphasis>.
1888         These instructions create both files, but populating the
1889         <emphasis role="bold">KeyFileExt</emphasis> file will only succeed
1890         using the version of <emphasis role="bold">asetkey</emphasis>
1891         from OpenAFS 1.8.x.</para>
1892       <para>The examples below assume you are using MIT Kerberos. Please refer 
1893       to the documentation for your KDC's administrative interface if you are 
1894       using a different vendor</para>
1895
1896       <orderedlist>
1897           <listitem>
1898             <para>Enter <emphasis role="bold">kadmin</emphasis> interactive mode.
1899   <programlisting>
1900      # <emphasis role="bold">kadmin</emphasis>
1901   Authenticating as principal <replaceable>you</replaceable>/admin@<replaceable>YOUR REALM</replaceable> with password
1902   Password for <replaceable>you/admin@REALM</replaceable>: <replaceable>your_password</replaceable>
1903   </programlisting> <indexterm>
1904                 <primary>server encryption key</primary>
1905
1906                 <secondary>in Kerberos Database</secondary>
1907               </indexterm> <indexterm>
1908                 <primary>creating</primary>
1909
1910                 <secondary>server encryption key</secondary>
1911
1912                 <tertiary>Kerberos Database</tertiary>
1913               </indexterm></para>
1914           </listitem>
1915
1916           <listitem>
1917             <para>Issue the 
1918             <emphasis role="bold">add_principal</emphasis> command to create 
1919             a Kerberos Database entry for
1920             <emphasis role="bold">afs/&lt;<replaceable>cell name</replaceable>&gt;</emphasis>.</para>
1921
1922             <para>Note that when creating the 
1923             <emphasis role="bold">afs/&lt;<replaceable>cell name</replaceable>&gt;</emphasis> 
1924             entry, the encryption type list does not include any single-DES
1925             encryption types.  If such encryption types are included,
1926             additional <emphasis role="bold">asetkey</emphasis> commands
1927             will be needed to place those keys in the legacy
1928             <emphasis role="bold">KeyFile</emphasis> and ensure proper
1929             operation of the cell.
1930             For more details regarding encryption types, see the documentation 
1931             for your Kerberos installation.
1932
1933   <programlisting>
1934      kadmin: <emphasis role="bold">add_principal -randkey -e aes256-cts-hmac-sha1-96:normal,aes128-cts-hmac-sha1-96:normal afs/</emphasis>&lt;<replaceable>cell name</replaceable>&gt;
1935      Principal "afs/<replaceable>cell name</replaceable>@<replaceable>REALM</replaceable>" created.
1936   </programlisting>
1937             </para>
1938           </listitem>
1939
1940           <listitem>
1941             <para>Extract the newly created key for
1942             <emphasis role="bold">afs/<replaceable>cell</replaceable></emphasis>
1943             to a keytab on the local machine.</para>
1944
1945             <para>The keytab contains the key material that ensures the security of your AFS cell. You should ensure that it is kept in a secure location at all times.</para>
1946
1947   <programlisting>
1948     kadmin: <emphasis role="bold">ktadd -k /usr/afs/etc/rxkad.keytab -e aes256-cts-hmac-sha1-96:normal,aes128-cts-hmac-sha1-96:normal afs/&lt;<replaceable>cell name</replaceable>&gt;</emphasis>
1949   Entry for principal afs/&lt;<replaceable>cell name</replaceable>&gt; with kvno 2, encryption type aes256-cts-hmac-sha1-96 added to keytab WRFILE:/usr/afs/etc/rxkad.keytab
1950   Entry for principal afs/&lt;<replaceable>cell name</replaceable>&gt; with kvno 2, encryption type aes128-cts-hmac-sha1-96 added to keytab WRFILE:/usr/afs/etc/rxkad.keytab
1951   </programlisting>
1952             <para>Make a note of the key version number (kvno) given in the
1953             response, as you will need it to load the key into
1954             the <emphasis role="bold">KeyFileExt</emphasis> in a later
1955             step</para>
1956
1957             <note><para>Note that each time you run 
1958             <emphasis role="bold">ktadd</emphasis> a new key is generated
1959             for the item being extracted. This means that you cannot run ktadd
1960             multiple times and end up with the same key material each time.
1961             </para></note>
1962
1963           </listitem>
1964           <listitem>
1965             <para>Issue the <emphasis role="bold">quit</emphasis> command to leave <emphasis role="bold">kadmin</emphasis>
1966             interactive mode. <programlisting>
1967      kadmin: <emphasis role="bold">quit</emphasis>
1968   </programlisting></para>
1969           </listitem>
1970
1971           <listitem id="LIWQ58">
1972             <para>Issue the 
1973             <emphasis role="bold">asetkey</emphasis> command to set the AFS 
1974             server encryption key in the 
1975             <emphasis role="bold">/usr/afs/etc/KeyFileExt</emphasis> file.
1976             This key 
1977             is created from the <emphasis role="bold">rxkad.keytab</emphasis> 
1978             file created earlier.</para>
1979
1980             <para>asetkey requires the key version number (or kvno) of the 
1981             <emphasis role="bold">afs/</emphasis><replaceable>cell</replaceable>
1982             key, as well as the encryption type number of the key.
1983             You should have made note of the kvno when creating the key
1984             earlier.  The key version number can also be found by running the 
1985             <emphasis role="bold">kvno</emphasis> command</para>
1986   <programlisting>
1987      # <emphasis role="bold">kvno -kt /usr/afs/etc/rxkad.keytab</emphasis>
1988   </programlisting>
1989             <para>The encryption type numbers can be found in the local krb5
1990             headers or the IANA registry.  The most common numbers are
1991             18 for <emphasis role="bold">aes256-cts-hmac-sha1-96</emphasis> and
1992             17 for <emphasis role="bold">aes128-cts-hmac-sha1-96</emphasis>.
1993             </para>
1994
1995             <para>Once the kvno and enctypes are known, the keys
1996             can then be extracted using asetkey</para>
1997   <programlisting>
1998      # <emphasis role="bold">asetkey add rxkad_krb5</emphasis> &lt;<replaceable>kvno</replaceable>&gt;  <emphasis role="bold">18 /usr/afs/etc/rxkad.keytab afs/</emphasis>&lt;<replaceable>cell name</replaceable>&gt;
1999      # <emphasis role="bold">asetkey add rxkad_krb5</emphasis> &lt;<replaceable>kvno</replaceable>&gt;  <emphasis role="bold">17 /usr/afs/etc/rxkad.keytab afs/</emphasis>&lt;<replaceable>cell name</replaceable>&gt;
2000   </programlisting>
2001           </listitem>
2002         </orderedlist>
2003     </sect2>
2004     <sect2>
2005       <title>Starting the Server Processes</title>
2006
2007       <para>Now that the keys are in place, proceed to start the server
2008       processes:
2009       <orderedlist>
2010         <listitem>
2011           <para>If you are building from source, you need to install the
2012           compiled files to the local
2013           <emphasis role="bold">/usr/afs</emphasis> directory. <indexterm>
2014               <primary>commands</primary>
2015
2016               <secondary>bosserver</secondary>
2017             </indexterm> <indexterm>
2018               <primary>bosserver command</primary>
2019             </indexterm></para>
2020         </listitem>
2021
2022         <listitem>
2023           <para>Issue the <emphasis role="bold">bosserver</emphasis> command.
2024           <programlisting>
2025    # <emphasis role="bold">/usr/afs/bin/bosserver</emphasis>
2026 </programlisting></para>
2027         </listitem>
2028
2029         <listitem>
2030           <para>Verify that the BOS Server created <emphasis role="bold">/usr/vice/etc/ThisCell</emphasis> and <emphasis
2031           role="bold">/usr/vice/etc/CellServDB</emphasis> as symbolic links to the corresponding files in the <emphasis
2032           role="bold">/usr/afs/etc</emphasis> directory. <programlisting>
2033    # <emphasis role="bold">ls -l  /usr/vice/etc</emphasis>
2034 </programlisting></para>
2035
2036           <para>If either or both of <emphasis role="bold">/usr/vice/etc/ThisCell</emphasis> and <emphasis
2037           role="bold">/usr/vice/etc/CellServDB</emphasis> do not exist, or are not links, issue the following commands.</para>
2038
2039           <programlisting>
2040    # <emphasis role="bold">cd /usr/vice/etc</emphasis>
2041    # <emphasis role="bold">ln -s /usr/afs/etc/ThisCell</emphasis>
2042    # <emphasis role="bold">ln -s /usr/afs/etc/CellServDB</emphasis> 
2043 </programlisting>
2044         </listitem>
2045       </orderedlist></para>
2046
2047     <indexterm>
2048       <primary>cell name</primary>
2049
2050       <secondary>defining during installation of first machine</secondary>
2051     </indexterm>
2052
2053     <indexterm>
2054       <primary>defining</primary>
2055
2056       <secondary>cell name during installation of first machine</secondary>
2057     </indexterm>
2058
2059     <indexterm>
2060       <primary>cell name</primary>
2061
2062       <secondary>setting in server ThisCell file</secondary>
2063
2064       <tertiary>first AFS machine</tertiary>
2065     </indexterm>
2066
2067     <indexterm>
2068       <primary>setting</primary>
2069
2070       <secondary>cell name in server ThisCell file</secondary>
2071
2072       <tertiary>first AFS machine</tertiary>
2073     </indexterm>
2074
2075     <indexterm>
2076       <primary>first AFS machine</primary>
2077
2078       <secondary>ThisCell file (server)</secondary>
2079     </indexterm>
2080
2081     <indexterm>
2082       <primary>usr/afs/etc/ThisCell</primary>
2083
2084       <see>ThisCell file (server)</see>
2085     </indexterm>
2086
2087     <indexterm>
2088       <primary>ThisCell file (server)</primary>
2089
2090       <secondary>first AFS machine</secondary>
2091     </indexterm>
2092
2093     <indexterm>
2094       <primary>files</primary>
2095
2096       <secondary>ThisCell (server)</secondary>
2097     </indexterm>
2098
2099     <indexterm>
2100       <primary>database server machine</primary>
2101
2102       <secondary>entry in server CellServDB file</secondary>
2103
2104       <tertiary>on first AFS machine</tertiary>
2105     </indexterm>
2106
2107     <indexterm>
2108       <primary>first AFS machine</primary>
2109
2110       <secondary>cell membership, defining</secondary>
2111
2112       <tertiary>for server processes</tertiary>
2113     </indexterm>
2114
2115     <indexterm>
2116       <primary>usr/afs/etc/CellServDB file</primary>
2117
2118       <see>CellServDB file (server)</see>
2119     </indexterm>
2120
2121     <indexterm>
2122       <primary>CellServDB file (server)</primary>
2123
2124       <secondary>creating</secondary>
2125
2126       <tertiary>on first AFS machine</tertiary>
2127     </indexterm>
2128
2129     <indexterm>
2130       <primary>creating</primary>
2131
2132       <secondary>CellServDB file (server)</secondary>
2133
2134       <tertiary>first AFS machine</tertiary>
2135     </indexterm>
2136
2137     <indexterm>
2138       <primary>files</primary>
2139
2140       <secondary>CellServDB (server)</secondary>
2141     </indexterm>
2142
2143     <indexterm>
2144       <primary>first AFS machine</primary>
2145
2146       <secondary>CellServDB file (server)</secondary>
2147     </indexterm>
2148
2149     <indexterm>
2150       <primary>first AFS machine</primary>
2151
2152       <secondary>defining</secondary>
2153
2154       <tertiary>as database server</tertiary>
2155     </indexterm>
2156
2157     <indexterm>
2158       <primary>defining</primary>
2159
2160       <secondary>first AFS machine as database server</secondary>
2161     </indexterm>
2162     </sect2>
2163   </sect1>
2164
2165   <sect1 id="HDRWQ51">
2166     <title>Defining Cell Name and Membership for Server Processes</title>
2167
2168     <para>Now assign your cell's name. The chapter in the <emphasis>OpenAFS Administration Guide</emphasis> about cell configuration
2169     and administration issues discusses the important considerations, explains why changing the name is difficult, and outlines the
2170     restrictions on name format. Two of the most important restrictions are that the name cannot include uppercase letters or more
2171     than 64 characters.</para>
2172
2173     <para>Use the <emphasis role="bold">bos setcellname</emphasis> command to assign the cell name. It creates two files:
2174     <itemizedlist>
2175         <listitem>
2176           <para><emphasis role="bold">/usr/afs/etc/ThisCell</emphasis>, which defines this machine's cell membership</para>
2177         </listitem>
2178
2179         <listitem>
2180           <para><emphasis role="bold">/usr/afs/etc/CellServDB</emphasis>, which lists the cell's database server machines; the
2181           machine named on the command line is placed on the list automatically</para>
2182         </listitem>
2183       </itemizedlist> <note>
2184         <para>In the following and every instruction in this guide, for the <replaceable>machine name</replaceable> argument
2185         substitute the fully-qualified hostname (such as <emphasis role="bold">fs1.example.com</emphasis>) of the machine you are
2186         installing. For the <replaceable>cell name</replaceable> argument substitute your cell's complete name (such as <emphasis
2187         role="bold">example.com</emphasis>).</para>
2188       </note></para>
2189
2190     <indexterm>
2191       <primary>commands</primary>
2192
2193       <secondary>bos setcellname</secondary>
2194     </indexterm>
2195
2196     <indexterm>
2197       <primary>bos commands</primary>
2198
2199       <secondary>setcellname</secondary>
2200     </indexterm>
2201
2202     <orderedlist>
2203       <listitem>
2204         <para>If necessary, add the directory containing the <emphasis role="bold">bos</emphasis> command to your path.
2205       <programlisting>
2206    # <emphasis role="bold">export PATH=$PATH:/usr/afs/bin</emphasis>
2207       </programlisting>
2208         </para>
2209       </listitem>
2210
2211       <listitem>
2212         <para>Issue the <emphasis role="bold">bos setcellname</emphasis> command to set the cell name. <programlisting>
2213    # <emphasis role="bold">bos setcellname</emphasis> &lt;<replaceable>machine name</replaceable>&gt; &lt;<replaceable>cell name</replaceable>&gt; <emphasis
2214               role="bold">-localauth</emphasis>
2215 </programlisting></para> <indexterm>
2216             <primary>commands</primary>
2217
2218             <secondary>bos listhosts</secondary>
2219           </indexterm> <indexterm>
2220             <primary>bos commands</primary>
2221
2222             <secondary>listhosts</secondary>
2223           </indexterm> <indexterm>
2224             <primary>CellServDB file (server)</primary>
2225
2226             <secondary>displaying entries</secondary>
2227           </indexterm> <indexterm>
2228             <primary>displaying</primary>
2229
2230             <secondary>CellServDB file (server) entries</secondary>
2231           </indexterm>
2232       </listitem>
2233
2234       <listitem>
2235         <para>Issue the <emphasis role="bold">bos listhosts</emphasis> command to verify that the machine you are installing is now
2236         registered as the cell's first database server machine. <programlisting>
2237    # <emphasis role="bold">bos listhosts</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">-localauth</emphasis>
2238    Cell name is <replaceable>cell_name</replaceable>
2239        Host 1 is <replaceable>machine_name</replaceable>
2240 </programlisting></para>
2241       </listitem>
2242     </orderedlist>
2243
2244     <indexterm>
2245       <primary>database server machine</primary>
2246
2247       <secondary>installing</secondary>
2248
2249       <tertiary>first</tertiary>
2250     </indexterm>
2251
2252     <indexterm>
2253       <primary>instructions</primary>
2254
2255       <secondary>database server machine, installing first</secondary>
2256     </indexterm>
2257
2258     <indexterm>
2259       <primary>installing</primary>
2260
2261       <secondary>database server machine</secondary>
2262
2263       <tertiary>first</tertiary>
2264     </indexterm>
2265
2266     <indexterm>
2267       <primary>Backup Server</primary>
2268
2269       <secondary>starting</secondary>
2270
2271       <tertiary>first AFS machine</tertiary>
2272     </indexterm>
2273
2274     <indexterm>
2275       <primary>buserver process</primary>
2276
2277       <see>Backup Server</see>
2278     </indexterm>
2279
2280     <indexterm>
2281       <primary>starting</primary>
2282
2283       <secondary>Backup Server</secondary>
2284
2285       <tertiary>first AFS machine</tertiary>
2286     </indexterm>
2287
2288     <indexterm>
2289       <primary>first AFS machine</primary>
2290
2291       <secondary>Backup Server</secondary>
2292     </indexterm>
2293
2294     <indexterm>
2295       <primary>Protection Server</primary>
2296
2297       <secondary>starting</secondary>
2298
2299       <tertiary>first AFS machine</tertiary>
2300     </indexterm>
2301
2302     <indexterm>
2303       <primary>ptserver process</primary>
2304
2305       <see>Protection Server</see>
2306     </indexterm>
2307
2308     <indexterm>
2309       <primary>starting</primary>
2310
2311       <secondary>Protection Server</secondary>
2312
2313       <tertiary>first AFS machine</tertiary>
2314     </indexterm>
2315
2316     <indexterm>
2317       <primary>first AFS machine</primary>
2318
2319       <secondary>Protection Server</secondary>
2320     </indexterm>
2321
2322     <indexterm>
2323       <primary>VL Server (vlserver process)</primary>
2324
2325       <secondary>starting</secondary>
2326
2327       <tertiary>first AFS machine</tertiary>
2328     </indexterm>
2329
2330     <indexterm>
2331       <primary>Volume Location Server</primary>
2332
2333       <see>VL Server</see>
2334     </indexterm>
2335
2336     <indexterm>
2337       <primary>starting</primary>
2338
2339       <secondary>VL Server</secondary>
2340
2341       <tertiary>first AFS machine</tertiary>
2342     </indexterm>
2343
2344     <indexterm>
2345       <primary>first AFS machine</primary>
2346
2347       <secondary>VL Server</secondary>
2348     </indexterm>
2349
2350     <indexterm>
2351       <primary>usr/afs/local/BosConfig</primary>
2352
2353       <see>BosConfig file</see>
2354     </indexterm>
2355
2356     <indexterm>
2357       <primary>BosConfig file</primary>
2358
2359       <secondary>adding entries</secondary>
2360
2361       <tertiary>first AFS machine</tertiary>
2362     </indexterm>
2363
2364     <indexterm>
2365       <primary>adding</primary>
2366
2367       <secondary>entries to BosConfig file</secondary>
2368
2369       <tertiary>first AFS machine</tertiary>
2370     </indexterm>
2371
2372     <indexterm>
2373       <primary>files</primary>
2374
2375       <secondary>BosConfig</secondary>
2376     </indexterm>
2377
2378     <indexterm>
2379       <primary>initializing</primary>
2380
2381       <secondary>server process</secondary>
2382
2383       <see>starting</see>
2384     </indexterm>
2385
2386     <indexterm>
2387       <primary>server process</primary>
2388
2389       <secondary>see also entry for each server's name</secondary>
2390     </indexterm>
2391   </sect1>
2392
2393   <sect1 id="HDRWQ52">
2394     <title>Starting the Database Server Processes</title>
2395
2396     <para>Next use the <emphasis role="bold">bos create</emphasis> command to create entries for the three database server processes
2397     in the <emphasis role="bold">/usr/afs/local/BosConfig</emphasis> file and start them running. The three processes run on database
2398     server machines only: <itemizedlist>
2399
2400         <listitem>
2401           <para>The Protection Server (the <emphasis role="bold">ptserver</emphasis> process) maintains the Protection
2402           Database</para>
2403         </listitem>
2404
2405         <listitem>
2406           <para>The Volume Location (VL) Server (the <emphasis role="bold">vlserver</emphasis> process) maintains the Volume
2407           Location Database (VLDB)</para>
2408         </listitem>
2409
2410         <listitem>
2411           <para>The optional Backup Server (the <emphasis role="bold">buserver</emphasis> process) maintains the Backup Database</para>
2412         </listitem>
2413       </itemizedlist></para>
2414
2415     <indexterm>
2416       <primary>Kerberos</primary>
2417     </indexterm>
2418
2419     <note>
2420       <para>AFS ships with an additional database server named 'kaserver', which
2421       was historically used to provide authentication services to AFS cells.
2422       kaserver was based on <emphasis>Kerberos v4</emphasis>, as such, it is
2423       not recommended for new cells. This guide assumes you have already
2424       configured a Kerberos v5 realm for your site, and details the procedures 
2425       required to use AFS with this realm. If you do wish to use
2426       <emphasis role="bold">kaserver</emphasis>, please see the modifications
2427       to these instructions detailed in 
2428       <link linkend="KAS006">Starting the kaserver Database Server Process</link>
2429       </para>
2430     </note>
2431
2432     <para>The remaining instructions in this chapter include the <emphasis role="bold">-cell</emphasis> argument on all applicable
2433     commands. Provide the cell name you assigned in <link linkend="HDRWQ51">Defining Cell Name and Membership for Server
2434     Processes</link>. If a command appears on multiple lines, it is only for legibility. <indexterm>
2435         <primary>commands</primary>
2436
2437         <secondary>bos create</secondary>
2438       </indexterm> <indexterm>
2439         <primary>bos commands</primary>
2440
2441         <secondary>create</secondary>
2442       </indexterm> <orderedlist>
2443         <listitem>
2444           <para>Issue the <emphasis role="bold">bos create</emphasis> command to start the Protection Server. <programlisting>
2445    # <emphasis role="bold">./bos create</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">ptserver simple /usr/afs/bin/ptserver</emphasis> <emphasis role="bold">-localauth</emphasis>
2446 </programlisting></para>
2447         </listitem>
2448
2449         <listitem>
2450           <para>Issue the <emphasis role="bold">bos create</emphasis> command to start the VL Server. <programlisting>
2451    # <emphasis role="bold">./bos create</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">vlserver simple /usr/afs/bin/vlserver</emphasis> <emphasis role="bold">-localauth</emphasis>
2452 </programlisting></para>
2453         </listitem>
2454
2455         <listitem>
2456           <para>Optionally, issue the <emphasis role="bold">bos create</emphasis> command to start the Backup Server. <programlisting>
2457    # <emphasis role="bold">./bos create</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">buserver simple /usr/afs/bin/buserver</emphasis>  <emphasis role="bold">-localauth</emphasis>
2458 </programlisting></para>
2459         </listitem>
2460       </orderedlist></para>
2461
2462     <indexterm>
2463       <primary>admin account</primary>
2464
2465       <secondary>creating</secondary>
2466     </indexterm>
2467
2468     <indexterm>
2469       <primary>afs entry in Kerberos Database</primary>
2470     </indexterm>
2471
2472     <indexterm>
2473       <primary>Kerberos Database</primary>
2474     </indexterm>
2475
2476     <indexterm>
2477       <primary>creating</primary>
2478
2479       <secondary>afs entry in Kerberos Database</secondary>
2480     </indexterm>
2481
2482     <indexterm>
2483       <primary>creating</primary>
2484
2485       <secondary>admin account in Kerberos Database</secondary>
2486     </indexterm>
2487
2488     <indexterm>
2489       <primary>security</primary>
2490
2491       <secondary>initializing cell-wide</secondary>
2492     </indexterm>
2493
2494     <indexterm>
2495       <primary>cell</primary>
2496
2497       <secondary>initializing security mechanisms</secondary>
2498     </indexterm>
2499
2500     <indexterm>
2501       <primary>initializing</primary>
2502
2503       <secondary>cell security mechanisms</secondary>
2504     </indexterm>
2505
2506     <indexterm>
2507       <primary>usr/afs/etc/KeyFile</primary>
2508
2509       <see>KeyFile file</see>
2510     </indexterm>
2511
2512     <indexterm>
2513       <primary>KeyFile file</primary>
2514
2515       <secondary>first AFS machine</secondary>
2516     </indexterm>
2517
2518     <indexterm>
2519       <primary>files</primary>
2520
2521       <secondary>KeyFile</secondary>
2522     </indexterm>
2523
2524     <indexterm>
2525       <primary>key</primary>
2526
2527       <see>server encryption key</see>
2528     </indexterm>
2529
2530     <indexterm>
2531       <primary>encryption key</primary>
2532
2533       <see>server encryption key</see>
2534     </indexterm>
2535   </sect1>
2536
2537   <sect1 id="HDRWQ53">
2538     <title>Initializing Cell Security </title>
2539
2540     <para>If you are working with an existing cell which uses
2541     <emphasis role="bold">kaserver</emphasis> or Kerberos v4 for authentication,
2542     please see 
2543     <link linkend="HDRWQ53">Initializing Cell Security with kaserver</link>
2544     for installation instructions which replace this section.</para>
2545     
2546     <para>Now finish initializing the cell's security mechanisms. Begin by creating the following entry in your site's Kerberos database: <itemizedlist>
2547         <listitem>
2548           <para>A generic administrative account, called <emphasis role="bold">admin</emphasis> by convention. If you choose to
2549           assign a different name, substitute it throughout the remainder of this document.</para>
2550
2551           <para>After you complete the installation of the first machine, you can continue to have all administrators use the
2552           <emphasis role="bold">admin</emphasis> account, or you can create a separate administrative account for each of them. The
2553           latter scheme implies somewhat more overhead, but provides a more informative audit trail for administrative
2554           operations.</para>
2555         </listitem>
2556       </itemizedlist></para>
2557
2558     <para>You also issue several commands that enable the new <emphasis role="bold">admin</emphasis> user to issue privileged
2559     commands in all of the AFS suites.</para>
2560
2561     <para>The following instructions do not configure all of the security mechanisms related to the AFS Backup System. See the
2562     chapter in the <emphasis>OpenAFS Administration Guide</emphasis> about configuring the Backup System.</para>
2563
2564     <para>The examples below assume you are using MIT Kerberos. Please refer 
2565     to the documentation for your KDC's administrative interface if you are 
2566     using a different vendor</para>
2567
2568     <orderedlist>
2569         <listitem>
2570           <para>Enter <emphasis role="bold">kadmin</emphasis> interactive mode.
2571 <programlisting>
2572    # <emphasis role="bold">kadmin</emphasis>
2573 Authenticating as principal <replaceable>you</replaceable>/admin@<replaceable>YOUR REALM</replaceable> with password
2574 Password for <replaceable>you/admin@REALM</replaceable>: <replaceable>your_password</replaceable>
2575 </programlisting> </para>
2576         </listitem>
2577
2578         <listitem>
2579           <para>Issue the 
2580           <emphasis role="bold">add_principal</emphasis> command to create 
2581           the Kerberos Database entry for
2582           <emphasis role="bold">admin</emphasis>.</para>
2583
2584           <para>You should make the <replaceable>admin_passwd</replaceable> as
2585           long and complex as possible, but keep in mind that administrators 
2586           need to enter it often. It must be at least six characters long.
2587 <programlisting>
2588    kadmin:  <emphasis role="bold">add_principal admin</emphasis>
2589    Enter password for principal "admin@<replaceable>REALM</replaceable>": <emphasis role="bold"><replaceable>admin_password</replaceable></emphasis>
2590    Principal "admin@<replaceable>REALM</replaceable>" created.
2591 </programlisting>
2592           </para>
2593
2594           <indexterm>
2595             <primary>displaying</primary>
2596
2597             <secondary>server encryption key</secondary>
2598
2599             <tertiary>Authentication Database</tertiary>
2600           </indexterm>
2601         </listitem>
2602
2603         <listitem>
2604           <para>Issue the <emphasis role="bold">quit</emphasis> command to leave <emphasis role="bold">kadmin</emphasis>
2605           interactive mode. <programlisting>
2606    kadmin: <emphasis role="bold">quit</emphasis>
2607 </programlisting> <indexterm>
2608               <primary>commands</primary>
2609
2610               <secondary>bos adduser</secondary>
2611             </indexterm> <indexterm>
2612               <primary>bos commands</primary>
2613
2614               <secondary>adduser</secondary>
2615             </indexterm> <indexterm>
2616               <primary>usr/afs/etc/UserList</primary>
2617
2618               <see>UserList file</see>
2619             </indexterm> <indexterm>
2620               <primary>UserList file</primary>
2621
2622               <secondary>first AFS machine</secondary>
2623             </indexterm> <indexterm>
2624               <primary>files</primary>
2625
2626               <secondary>UserList</secondary>
2627             </indexterm> <indexterm>
2628               <primary>creating</primary>
2629
2630               <secondary>UserList file entry</secondary>
2631             </indexterm> <indexterm>
2632               <primary>admin account</primary>
2633
2634               <secondary>adding</secondary>
2635
2636               <tertiary>to UserList file</tertiary>
2637             </indexterm></para>
2638         </listitem>
2639
2640         <listitem id="LIWQ57">
2641           <para>Issue the <emphasis role="bold">bos adduser</emphasis> command to add the <emphasis
2642           role="bold">admin</emphasis> user to the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. This enables the
2643           <emphasis role="bold">admin</emphasis> user to issue privileged <emphasis role="bold">bos</emphasis> and <emphasis
2644           role="bold">vos</emphasis> commands. <programlisting>
2645    # <emphasis role="bold">./bos adduser</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">admin -localauth</emphasis>
2646 </programlisting> 
2647             <indexterm>
2648               <primary>commands</primary>
2649               <secondary>asetkey</secondary>
2650             </indexterm>
2651             <indexterm>
2652               <primary>creating</primary>
2653               <secondary>server encryption key</secondary>
2654               <tertiary>KeyFile file</tertiary>
2655             </indexterm> 
2656             <indexterm>
2657               <primary>server encryption key</primary>
2658               <secondary>in KeyFile file</secondary>
2659             </indexterm></para>
2660         </listitem>
2661       </orderedlist>
2662     </sect1>
2663     <sect1 id="HDRWQ53a">
2664       <title>Initializing the Protection Database</title>
2665       
2666       <para>Now continue to configure your cell's security systems by
2667       populating the Protection Database with the newly created
2668       <emphasis role="bold">admin</emphasis> user, and permitting it
2669       to issue priviledged commands on the AFS filesystem.
2670       There is nothing special about the name "admin"; it is just a
2671       convenient name for these instructions.  An other name could
2672       be used throughout this document, or multiple privileged
2673       accounts created.</para>
2674           
2675         <orderedlist>
2676           <listitem>
2677           <para>Issue the <emphasis role="bold">pts createuser</emphasis> command to create a Protection Database entry for the
2678           <emphasis role="bold">admin</emphasis> user.
2679           <indexterm>
2680             <primary>commands</primary>
2681             <secondary>pts createuser</secondary>
2682           </indexterm>
2683
2684           <indexterm>
2685             <primary>pts commands</primary>
2686             <secondary>createuser</secondary>
2687           </indexterm>
2688
2689           <indexterm>
2690             <primary>Protection Database</primary>
2691           </indexterm></para>
2692
2693           <para>By default, the Protection Server assigns AFS UID 1 (one) to the <emphasis role="bold">admin</emphasis> user,
2694           because it is the first user entry you are creating. If the local password file (<emphasis
2695           role="bold">/etc/passwd</emphasis> or equivalent) already has an entry for <emphasis role="bold">admin</emphasis> that
2696           assigns it a UNIX UID other than 1, it is best to use the <emphasis role="bold">-id</emphasis> argument to the <emphasis
2697           role="bold">pts createuser</emphasis> command to make the new AFS UID match the existing UNIX UID. Otherwise, it is best
2698           to accept the default.</para>
2699
2700           <programlisting>
2701    # <emphasis role="bold">pts createuser -name admin</emphasis> [<emphasis
2702               role="bold">-id</emphasis> &lt;<replaceable>AFS UID</replaceable>&gt;]  <emphasis role="bold">-localauth</emphasis>
2703    User admin has id <replaceable>AFS UID</replaceable>
2704 </programlisting>
2705
2706           <indexterm>
2707             <primary>commands</primary>
2708             <secondary>pts adduser</secondary>
2709           </indexterm>
2710
2711           <indexterm>
2712             <primary>pts commands</primary>
2713             <secondary>adduser</secondary>
2714           </indexterm>
2715
2716           <indexterm>
2717             <primary>system:administrators group</primary>
2718           </indexterm>
2719
2720           <indexterm>
2721             <primary>admin account</primary>
2722             <secondary>adding</secondary>
2723             <tertiary>to system:administrators group</tertiary>
2724           </indexterm>
2725         </listitem>
2726
2727         <listitem>
2728           <para>Issue the <emphasis role="bold">pts adduser</emphasis> command to make the <emphasis role="bold">admin</emphasis>
2729           user a member of the <emphasis role="bold">system:administrators</emphasis> group, and the <emphasis role="bold">pts
2730           membership</emphasis> command to verify the new membership. Membership in the group enables the <emphasis
2731           role="bold">admin</emphasis> user to issue privileged <emphasis role="bold">pts</emphasis> commands and some privileged
2732           <emphasis role="bold">fs</emphasis> commands. <programlisting>
2733    # <emphasis role="bold">./pts adduser admin system:administrators</emphasis> <emphasis role="bold">-localauth</emphasis>
2734    # <emphasis role="bold">./pts membership admin</emphasis> <emphasis role="bold">-localauth</emphasis>
2735    Groups admin (id: 1) is a member of:
2736      system:administrators
2737 </programlisting> <indexterm>
2738               <primary>commands</primary>
2739               <secondary>bos restart</secondary>
2740               <tertiary>on first AFS machine</tertiary>
2741             </indexterm> <indexterm>
2742               <primary>bos commands</primary>
2743               <secondary>restart</secondary>
2744               <tertiary>on first AFS machine</tertiary>
2745             </indexterm> <indexterm>
2746               <primary>restarting server process</primary>
2747               <secondary>on first AFS machine</secondary>
2748             </indexterm> <indexterm>
2749               <primary>server process</primary>
2750               <secondary>restarting</secondary>
2751               <tertiary>on first AFS machine</tertiary>
2752             </indexterm></para>
2753         </listitem>
2754       </orderedlist>
2755
2756     <indexterm>
2757       <primary>File Server</primary>
2758
2759       <secondary>first AFS machine</secondary>
2760     </indexterm>
2761
2762     <indexterm>
2763       <primary>fileserver process</primary>
2764
2765       <see>File Server</see>
2766     </indexterm>
2767
2768     <indexterm>
2769       <primary>starting</primary>
2770
2771       <secondary>File Server</secondary>
2772
2773       <tertiary>first AFS machine</tertiary>
2774     </indexterm>
2775
2776     <indexterm>
2777       <primary>first AFS machine</primary>
2778
2779       <secondary>File Server, fs process</secondary>
2780     </indexterm>
2781
2782     <indexterm>
2783       <primary>Volume Server</primary>
2784
2785       <secondary>first AFS machine</secondary>
2786     </indexterm>
2787
2788     <indexterm>
2789       <primary>volserver process</primary>
2790
2791       <see>Volume Server</see>
2792     </indexterm>
2793
2794     <indexterm>
2795       <primary>starting</primary>
2796
2797       <secondary>Volume Server</secondary>
2798
2799       <tertiary>first AFS machine</tertiary>
2800     </indexterm>
2801
2802     <indexterm>
2803       <primary>first AFS machine</primary>
2804
2805       <secondary>Volume Server</secondary>
2806     </indexterm>
2807
2808     <indexterm>
2809       <primary>Salvager (salvager process)</primary>
2810
2811       <secondary>first AFS machine</secondary>
2812     </indexterm>
2813
2814     <indexterm>
2815       <primary>fs process</primary>
2816
2817       <secondary>first AFS machine</secondary>
2818     </indexterm>
2819
2820     <indexterm>
2821       <primary>starting</primary>
2822
2823       <secondary>fs process</secondary>
2824
2825       <tertiary>first AFS machine</tertiary>
2826     </indexterm>
2827
2828     <indexterm>
2829       <primary>first AFS machine</primary>
2830
2831       <secondary>Salvager</secondary>
2832     </indexterm>
2833   </sect1>
2834
2835   <sect1 id="HDRWQ60">
2836     <title>Starting the File Server processes</title>
2837
2838     <para>Start the
2839     <emphasis role="bold">dafs</emphasis> process.
2840     The <emphasis role="bold">dafs</emphasis> process consists of the
2841     Demand-Attach File Server, Volume Server, Salvage Server, and Salvager (<emphasis role="bold">dafileserver</emphasis>,
2842     <emphasis role="bold"> davolserver</emphasis>, <emphasis role="bold">salvageserver</emphasis>, and <emphasis
2843     role="bold">dasalvager</emphasis> processes). Most sites should run the
2844     Demand-Attach File Server, but the traditional/legacy File Server remains
2845     an option.  If you are uncertain whether to run the legacy File Server,
2846     see <link linkend="DAFS">Appendix C, The Demand-Attach File Server</link>.
2847      <orderedlist>
2848         <listitem>
2849           <para>Issue the <emphasis role="bold">bos create</emphasis> command to start the 
2850           <emphasis role="bold">dafs</emphasis> process. The commands appear here on multiple lines only for legibility.
2851
2852             <itemizedlist>
2853              <listitem>
2854                <para>Create the <emphasis
2855                role="bold">dafs</emphasis> process:
2856                   <programlisting>
2857    # <emphasis role="bold">./bos create</emphasis>  &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">dafs dafs /usr/afs/bin/dafileserver</emphasis>   \
2858                    <emphasis role="bold">/usr/afs/bin/davolserver /usr/afs/bin/salvageserver</emphasis> \
2859                    <emphasis role="bold">/usr/afs/bin/dasalvager</emphasis> <emphasis role="bold">-localauth</emphasis>   
2860 </programlisting></para>
2861              </listitem>
2862             </itemizedlist>
2863           </para>
2864
2865           <para>Sometimes a message about Volume Location Database (VLDB) initialization appears, along with one or more instances
2866           of an error message similar to the following:</para>
2867
2868           <programlisting>
2869    FSYNC_clientInit temporary failure (will retry)   
2870 </programlisting>
2871
2872           <para>This message appears when the <emphasis role="bold">volserver</emphasis> process tries to start before the <emphasis
2873           role="bold">fileserver</emphasis> process has completed its initialization. Wait a few minutes after the last such message
2874           before continuing, to guarantee that both processes have started successfully. <indexterm>
2875               <primary>commands</primary>
2876
2877               <secondary>bos status</secondary>
2878             </indexterm> <indexterm>
2879               <primary>bos commands</primary>
2880
2881               <secondary>status</secondary>
2882             </indexterm></para>
2883
2884           <para>You can verify that the <emphasis role="bold">dafs</emphasis> process has started
2885           successfully by issuing the <emphasis role="bold">bos status</emphasis> command. Its output mentions two <computeroutput>proc
2886           starts</computeroutput>.</para>
2887
2888               <para>
2889           <programlisting>
2890    # <emphasis role="bold">./bos status</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">dafs -long -localauth</emphasis>
2891 </programlisting></para>
2892         </listitem>
2893
2894         <listitem>
2895           <para>Your next action depends on whether you have ever run AFS file server machines in the cell: <itemizedlist>
2896               <indexterm>
2897                 <primary>commands</primary>
2898
2899                 <secondary>vos create</secondary>
2900
2901                 <tertiary>root.afs volume</tertiary>
2902               </indexterm>
2903
2904               <indexterm>
2905                 <primary>vos commands</primary>
2906
2907                 <secondary>create</secondary>
2908
2909                 <tertiary>root.afs volume</tertiary>
2910               </indexterm>
2911
2912               <indexterm>
2913                 <primary>root.afs volume</primary>
2914
2915                 <secondary>creating</secondary>
2916               </indexterm>
2917
2918               <indexterm>
2919                 <primary>volume</primary>
2920
2921                 <secondary>creating</secondary>
2922
2923                 <tertiary>root.afs</tertiary>
2924               </indexterm>
2925
2926               <indexterm>
2927                 <primary>creating</primary>
2928
2929                 <secondary>root.afs volume</secondary>
2930               </indexterm>
2931
2932               <listitem>
2933                 <para>If you are installing the first AFS server machine ever in the cell (that is, you are not upgrading the AFS
2934                 software from a previous version), create the first AFS volume, <emphasis role="bold">root.afs</emphasis>.</para>
2935
2936                 <para>For the <replaceable>partition name</replaceable> argument, substitute the name of one of the machine's AFS
2937                 server partitions (such as <emphasis role="bold">/vicepa</emphasis>).</para>
2938
2939                 <programlisting>
2940    # <emphasis role="bold">./vos create</emphasis>  &lt;<replaceable>machine name</replaceable>&gt; &lt;<replaceable>partition name</replaceable>&gt; <emphasis
2941                     role="bold">root.afs</emphasis>   \
2942                    <emphasis role="bold">-localauth</emphasis>   
2943 </programlisting>
2944
2945                 <para>The Volume Server produces a message confirming that it created the volume on the specified partition.  <indexterm>
2946                     <primary>commands</primary>
2947
2948                     <secondary>vos syncvldb</secondary>
2949                   </indexterm> <indexterm>
2950                     <primary>vos commands</primary>
2951
2952                     <secondary>syncvldb</secondary>
2953                   </indexterm> <indexterm>
2954                     <primary>commands</primary>
2955
2956                     <secondary>vos syncserv</secondary>
2957                   </indexterm> <indexterm>
2958                     <primary>vos commands</primary>
2959
2960                     <secondary>syncserv</secondary>
2961                   </indexterm></para>
2962               </listitem>
2963             </itemizedlist></para>
2964         </listitem>
2965       </orderedlist></para>
2966
2967     <indexterm>
2968       <primary>Update Server</primary>
2969
2970       <secondary>starting server portion</secondary>
2971
2972       <tertiary>first AFS machine</tertiary>
2973     </indexterm>
2974
2975     <indexterm>
2976       <primary>upserver process</primary>
2977
2978       <see>Update Server</see>
2979     </indexterm>
2980
2981     <indexterm>
2982       <primary>starting</primary>
2983
2984       <secondary>Update Server server portion</secondary>
2985
2986       <tertiary>first AFS machine</tertiary>
2987     </indexterm>
2988
2989     <indexterm>
2990       <primary>first AFS machine</primary>
2991
2992       <secondary>Update Server server portion</secondary>
2993     </indexterm>
2994
2995     <indexterm>
2996       <primary>first AFS machine</primary>
2997
2998       <secondary>defining</secondary>
2999
3000       <tertiary>as binary distribution machine</tertiary>
3001     </indexterm>
3002
3003     <indexterm>
3004       <primary>first AFS machine</primary>
3005
3006       <secondary>defining</secondary>
3007
3008       <tertiary>as system control machine</tertiary>
3009     </indexterm>
3010
3011     <indexterm>
3012       <primary>system control machine</primary>
3013     </indexterm>
3014
3015     <indexterm>
3016       <primary>binary distribution machine</primary>
3017     </indexterm>
3018   </sect1>
3019
3020   <sect1 id="HDRWQ62">
3021     <title>Clock Sync Considerations</title>
3022
3023     <para>Keeping the clocks on all server and client machines in your cell synchronized is crucial to several functions, and in
3024     particular to the correct operation of AFS's distributed database technology, Ubik. The chapter in the <emphasis>OpenAFS
3025     Administration Guide</emphasis> about administering server machines explains how time skew can disturb Ubik's performance and
3026     cause service outages in your cell.</para>
3027
3028     <para>You should install and configure your time service independently of
3029     AFS. Your Kerberos realm will also require a reliable time source, so your site
3030     may already have one available.</para>
3031
3032     <indexterm>
3033       <primary>overview</primary>
3034
3035       <secondary>installing client functionality on first machine</secondary>
3036     </indexterm>
3037
3038     <indexterm>
3039       <primary>first AFS machine</primary>
3040
3041       <secondary>client functionality</secondary>
3042
3043       <tertiary>installing</tertiary>
3044     </indexterm>
3045
3046     <indexterm>
3047       <primary>installing</primary>
3048
3049       <secondary>client functionality</secondary>
3050
3051       <tertiary>first AFS machine</tertiary>
3052     </indexterm>
3053   </sect1>
3054
3055   <sect1 id="HDRWQ63">
3056     <title>Overview: Installing Client Functionality</title>
3057
3058     <para>The machine you are installing is now an AFS file server machine
3059     and database server machine.
3060     Now make it a client machine by completing the following tasks: 
3061     <orderedlist>
3062         <listitem>
3063           <para>Define the machine's cell membership for client processes</para>
3064         </listitem>
3065
3066         <listitem>
3067           <para>Create the client version of the <emphasis role="bold">CellServDB</emphasis> file</para>
3068         </listitem>
3069
3070         <listitem>
3071           <para>Define cache location and size</para>
3072         </listitem>
3073
3074         <listitem>
3075           <para>Create the <emphasis role="bold">/afs</emphasis> directory and start the Cache Manager</para>
3076         </listitem>
3077       </orderedlist></para>
3078
3079     <indexterm>
3080       <primary>Distribution</primary>
3081
3082       <secondary>copying client files from</secondary>
3083
3084       <tertiary>first AFS machine</tertiary>
3085     </indexterm>
3086
3087     <indexterm>
3088       <primary>first AFS machine</primary>
3089
3090       <secondary>copying</secondary>
3091
3092       <tertiary>client files to local disk</tertiary>
3093     </indexterm>
3094
3095     <indexterm>
3096       <primary>copying</primary>
3097
3098       <secondary>client files to local disk</secondary>
3099
3100       <tertiary>first AFS machine</tertiary>
3101     </indexterm>
3102   </sect1>
3103
3104   <sect1 id="HDRWQ64">
3105     <title>Copying Client Files to the Local Disk</title>
3106
3107     <para>You need only undertake the steps in this section, if you are using
3108     a tar file distribution, or one built from scratch. Packaged distributions,
3109     such as RPMs or DEBs will already have installed the necessary files in
3110     the correct locations.</para>
3111
3112     <para>Before installing and configuring the AFS client, copy the necessary files from the tarball to the local <emphasis
3113     role="bold">/usr/vice/etc</emphasis> directory. <orderedlist>
3114         <listitem>
3115           <para>If you have not already done so, unpack the distribution 
3116           tarball for this machine's system type into a suitable location on 
3117           the filesystem, such as <emphasis role="bold">/tmp/afsdist</emphasis>.
3118           If you use a different location, substitue that in the examples that 
3119           follow.</para>
3120         </listitem>
3121
3122         <listitem>
3123           <para>Copy files to the local <emphasis role="bold">/usr/vice/etc</emphasis> directory.</para>
3124
3125           <para>This step places a copy of the AFS initialization script (and related files, if applicable) into the <emphasis
3126           role="bold">/usr/vice/etc</emphasis> directory. In the preceding instructions for incorporating AFS into the kernel, you
3127           copied the script directly to the operating system's conventional location for initialization files. When you incorporate
3128           AFS into the machine's startup sequence in a later step, you can choose to link the two files.</para>
3129
3130           <para>On some system types that use a dynamic kernel loader program, you previously copied AFS library files into a
3131           subdirectory of the <emphasis role="bold">/usr/vice/etc</emphasis> directory. On other system types, you copied the
3132           appropriate AFS library file directly to the directory where the operating system accesses it. The following commands do
3133           not copy or recopy the AFS library files into the <emphasis role="bold">/usr/vice/etc</emphasis> directory, because on
3134           some system types the library files consume a large amount of space. If you want to copy them, add the <emphasis
3135           role="bold">-r</emphasis> flag to the first <emphasis role="bold">cp</emphasis> command and skip the second <emphasis
3136           role="bold">cp</emphasis> command.</para>
3137
3138           <programlisting>
3139    # <emphasis role="bold">cd /tmp/afsdist/</emphasis><replaceable>sysname</replaceable><emphasis role="bold">/root.client/usr/vice/etc</emphasis>
3140    # <emphasis role="bold">cp -p  *  /usr/vice/etc</emphasis>
3141    # <emphasis role="bold">cp -rp  C  /usr/vice/etc</emphasis>
3142 </programlisting>
3143         </listitem>
3144       </orderedlist></para>
3145
3146     <indexterm>
3147       <primary>cell name</primary>
3148
3149       <secondary>setting in client ThisCell file</secondary>
3150
3151       <tertiary>first AFS machine</tertiary>
3152     </indexterm>
3153
3154     <indexterm>
3155       <primary>setting</primary>
3156
3157       <secondary>cell name in client ThisCell file</secondary>
3158
3159       <tertiary>first AFS machine</tertiary>
3160     </indexterm>
3161
3162     <indexterm>
3163       <primary>first AFS machine</primary>
3164
3165       <secondary>ThisCell file (client)</secondary>
3166     </indexterm>
3167
3168     <indexterm>
3169       <primary>first AFS machine</primary>
3170
3171       <secondary>cell membership, defining</secondary>
3172
3173       <tertiary>for client processes</tertiary>
3174     </indexterm>
3175
3176     <indexterm>
3177       <primary>usr/vice/etc/ThisCell</primary>
3178
3179       <see>ThisCell file (client)</see>
3180     </indexterm>
3181
3182     <indexterm>
3183       <primary>ThisCell file (client)</primary>
3184
3185       <secondary>first AFS machine</secondary>
3186     </indexterm>
3187
3188     <indexterm>
3189       <primary>files</primary>
3190
3191       <secondary>ThisCell (client)</secondary>
3192     </indexterm>
3193   </sect1>
3194
3195   <sect1 id="HDRWQ65">
3196     <title>Defining Cell Membership for Client Processes</title>
3197
3198     <para>Every AFS client machine has a copy of the <emphasis role="bold">/usr/vice/etc/ThisCell</emphasis> file on its local disk
3199     to define the machine's cell membership for the AFS client programs that run on it. The <emphasis
3200     role="bold">ThisCell</emphasis> file you created in the <emphasis role="bold">/usr/afs/etc</emphasis> directory (in <link
3201     linkend="HDRWQ51">Defining Cell Name and Membership for Server Processes</link>) is used only by server processes.</para>
3202
3203     <para>Among other functions, the <emphasis role="bold">ThisCell</emphasis> file on a client machine determines the following:
3204     <itemizedlist>
3205         <listitem>
3206           <para>The cell in which users gain tokens when they log onto the 
3207           machine, assuming it is using an AFS-modified login utility</para>
3208         </listitem>
3209
3210         <listitem>
3211           <para>The cell in which users gain tokens by default when they issue
3212           the <emphasis role="bold">aklog</emphasis> command</para>
3213         </listitem>
3214
3215         <listitem>
3216           <para>The cell membership of the AFS server processes that the AFS 
3217           command interpreters on this machine contact by default</para>
3218         </listitem>
3219       </itemizedlist> 
3220     <orderedlist>
3221         <listitem>
3222           <para>Change to the <emphasis role="bold">/usr/vice/etc</emphasis> directory and remove the symbolic link created in <link
3223           linkend="HDRWQ50">Starting the BOS Server</link>. <programlisting>
3224    # <emphasis role="bold">cd /usr/vice/etc</emphasis>
3225    # <emphasis role="bold">rm ThisCell</emphasis>
3226 </programlisting></para>
3227         </listitem>
3228
3229         <listitem>
3230           <para>Create the <emphasis role="bold">ThisCell</emphasis> file as a copy of the <emphasis
3231           role="bold">/usr/afs/etc/ThisCell</emphasis> file. Defining the same local cell for both server and client processes leads
3232           to the most consistent AFS performance. <programlisting>
3233    # <emphasis role="bold">cp  /usr/afs/etc/ThisCell  ThisCell</emphasis>
3234 </programlisting></para>
3235         </listitem>
3236       </orderedlist></para>
3237
3238     <indexterm>
3239       <primary>database server machine</primary>
3240
3241       <secondary>entry in client CellServDB file</secondary>
3242
3243       <tertiary>on first AFS machine</tertiary>
3244     </indexterm>
3245
3246     <indexterm>
3247       <primary>usr/vice/etc/CellServDB</primary>
3248
3249       <see>CellServDB file (client)</see>
3250     </indexterm>
3251
3252     <indexterm>
3253       <primary>CellServDB file (client)</primary>
3254
3255       <secondary>creating</secondary>
3256
3257       <tertiary>on first AFS machine</tertiary>
3258     </indexterm>
3259
3260     <indexterm>
3261       <primary>creating</primary>
3262
3263       <secondary>CellServDB file (client)</secondary>
3264
3265       <tertiary>first AFS machine</tertiary>
3266     </indexterm>
3267
3268     <indexterm>
3269       <primary>CellServDB file (client)</primary>
3270
3271       <secondary>required format</secondary>
3272     </indexterm>
3273
3274     <indexterm>
3275       <primary>requirements</primary>
3276
3277       <secondary>CellServDB file format (client version)</secondary>
3278     </indexterm>
3279
3280     <indexterm>
3281       <primary>files</primary>
3282
3283       <secondary>CellServDB (client)</secondary>
3284     </indexterm>
3285
3286     <indexterm>
3287       <primary>first AFS machine</primary>
3288
3289       <secondary>CellServDB file (client)</secondary>
3290     </indexterm>
3291   </sect1>
3292
3293   <sect1 id="HDRWQ66">
3294     <title>Creating the Client CellServDB File</title>
3295
3296     <para>The <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file on a client machine's local disk lists the database
3297     server machines for each cell that the local Cache Manager can contact. If there is no entry in the file for a cell, or if the
3298     list of database server machines is wrong, then users working on this machine cannot access the cell. The chapter in the
3299     <emphasis>OpenAFS Administration Guide</emphasis> about administering client machines explains how to maintain the file after
3300     creating it.</para>
3301
3302     <para>As the <emphasis role="bold">afsd</emphasis> program initializes the Cache Manager, it copies the contents of the
3303     <emphasis role="bold">CellServDB</emphasis> file into kernel memory. The Cache Manager always consults the list in kernel memory
3304     rather than the <emphasis role="bold">CellServDB</emphasis> file itself. Between reboots of the machine, you can use the
3305     <emphasis role="bold">fs newcell</emphasis> command to update the list in kernel memory directly; see the chapter in the
3306     <emphasis>OpenAFS Administration Guide</emphasis> about administering client machines.</para>
3307
3308     <para>The AFS distribution includes the file 
3309     <emphasis role="bold">CellServDB.dist</emphasis>. It includes an entry for 
3310     all AFS cells that agreed to share their database server machine 
3311     information at the time the distribution was 
3312     created. The definitive copy of this file is maintained at 
3313     grand.central.org, and updates may be obtained from
3314     /afs/grand.central.org/service/CellServDB or 
3315     <ulink url="http://grand.central.org/dl/cellservdb/CellServDB">
3316     http://grand.central.org/dl/cellservdb/CellServDB</ulink></para>
3317
3318     <para>The <emphasis role="bold">CellServDB.dist</emphasis> file can be a 
3319     good basis for the client <emphasis role="bold">CellServDB</emphasis> file, 
3320     because all of the entries in it use the correct format. You can add or 
3321     remove cell entries as you see fit. Depending on your cache manager
3322     configuration, additional steps (as detailed in 
3323     <link linkend="HDRWQ91">Enabling Access to Foreign Cells</link>) may be
3324     required to enable the Cache Manager to actually reach the cells.</para>
3325
3326     <para>In this section, you add an entry for the local cell to the local <emphasis role="bold">CellServDB</emphasis> file. The
3327     current working directory is still <emphasis role="bold">/usr/vice/etc</emphasis>. <orderedlist>
3328         <listitem>
3329           <para>Remove the symbolic link created in <link linkend="HDRWQ50">Starting the BOS Server</link> and rename the <emphasis
3330           role="bold">CellServDB.sample</emphasis> file to <emphasis role="bold">CellServDB</emphasis>. <programlisting>
3331    # <emphasis role="bold">rm CellServDB</emphasis>
3332    # <emphasis role="bold">mv CellServDB.sample CellServDB</emphasis>
3333 </programlisting></para>
3334         </listitem>
3335
3336         <listitem>
3337           <para>Add an entry for the local cell to the <emphasis role="bold">CellServDB</emphasis> file. One easy method is to use
3338           the <emphasis role="bold">cat</emphasis> command to append the contents of the server <emphasis
3339           role="bold">/usr/afs/etc/CellServDB</emphasis> file to the client version. <programlisting>
3340     # <emphasis role="bold">cat  /usr/afs/etc/CellServDB &gt;&gt;  CellServDB</emphasis>   
3341 </programlisting></para>
3342
3343           <para>Then open the file in a text editor to verify that there are no blank lines, and that all entries have the required
3344           format, which is described just following. The ordering of cells is not significant, but it can be convenient to have the
3345           client machine's home cell at the top; move it there now if you wish. <itemizedlist>
3346               <listitem>
3347                 <para>The first line of a cell's entry has the following format: <programlisting>
3348    &gt;<replaceable>cell_name</replaceable>      #<replaceable>organization</replaceable>   
3349 </programlisting></para>
3350
3351                 <para>where <replaceable>cell_name</replaceable> is the cell's complete Internet domain name (for example, <emphasis
3352                 role="bold">example.com</emphasis>) and <replaceable>organization</replaceable> is an optional field that follows any
3353                 number of spaces and the number sign (<computeroutput>#</computeroutput>). By convention it names the organization
3354                 to which the cell corresponds (for example, the Example Corporation).</para>
3355               </listitem>
3356
3357               <listitem>
3358                 <para>After the first line comes a separate line for each database server machine. Each line has the following
3359                 format: <programlisting>
3360    <replaceable>IP_address</replaceable>   #<replaceable>machine_name</replaceable>   
3361 </programlisting></para>
3362
3363                 <para>where <replaceable>IP_address</replaceable> is the machine's IP address in dotted decimal format (for example,
3364                 192.12.105.3). Following any number of spaces and the number sign (<computeroutput>#</computeroutput>) is
3365                 <replaceable>machine_name</replaceable>, the machine's fully-qualified hostname (for example, <emphasis
3366                 role="bold">db1.example.com</emphasis>). In this case, the number sign does not indicate a comment;
3367                 <replaceable>machine_name</replaceable> is a required field.</para>
3368               </listitem>
3369             </itemizedlist></para>
3370         </listitem>
3371
3372         <listitem>
3373           <para>If the file includes cells that you do not wish users of this machine to access, remove their entries.</para>
3374         </listitem>
3375       </orderedlist></para>
3376
3377     <para>The following example shows entries for two cells, each of which has three database server machines:</para>
3378
3379     <programlisting>
3380    &gt;example.com       #Example Corporation (home cell)
3381    192.12.105.3      #db1.example.com
3382    192.12.105.4      #db2.example.com
3383    192.12.105.55     #db3.example.com
3384    &gt;example.org    #Example Organization cell
3385    138.255.68.93     #serverA.example.org
3386    138.255.68.72     #serverB.example.org
3387    138.255.33.154    #serverC.example.org
3388 </programlisting>
3389
3390     <indexterm>
3391       <primary>cache</primary>
3392
3393       <secondary>configuring</secondary>
3394
3395       <tertiary>first AFS machine</tertiary>
3396     </indexterm>
3397
3398     <indexterm>
3399       <primary>configuring</primary>
3400
3401       <secondary>cache</secondary>
3402
3403       <tertiary>first AFS machine</tertiary>
3404     </indexterm>
3405
3406     <indexterm>
3407       <primary>setting</primary>
3408
3409       <secondary>cache size and location</secondary>
3410
3411       <tertiary>first AFS machine</tertiary>
3412     </indexterm>
3413
3414     <indexterm>
3415       <primary>first AFS machine</primary>
3416
3417       <secondary>cache size and location</secondary>
3418     </indexterm>
3419   </sect1>
3420
3421   <sect1 id="HDRWQ67">
3422     <title>Configuring the Cache</title>
3423
3424     <para>The Cache Manager uses a cache on the local disk or in machine memory to store local copies of files fetched from file
3425     server machines. As the <emphasis role="bold">afsd</emphasis> program initializes the Cache Manager, it sets basic cache
3426     configuration parameters according to definitions in the local <emphasis role="bold">/usr/vice/etc/cacheinfo</emphasis> file.
3427     The file has three fields: <orderedlist>
3428         <listitem>
3429           <para>The first field names the local directory on which to mount the AFS filespace. The conventional location is the
3430           <emphasis role="bold">/afs</emphasis> directory.</para>
3431         </listitem>
3432
3433         <listitem>
3434           <para>The second field defines the local disk directory to use for the disk cache. The conventional location is the
3435           <emphasis role="bold">/usr/vice/cache</emphasis> directory, but you can specify an alternate directory if another
3436           partition has more space available. There must always be a value in this field, but the Cache Manager ignores it if the
3437           machine uses a memory cache.</para>
3438         </listitem>
3439
3440         <listitem>
3441           <para>The third field specifies the number of kilobyte (1024 byte) blocks to allocate for the cache.</para>
3442         </listitem>
3443       </orderedlist></para>
3444
3445     <para>The values you define must meet the following requirements. <itemizedlist>
3446         <listitem>
3447           <para>On a machine using a disk cache, the Cache Manager expects always to be able to use the amount of space specified in
3448           the third field. Failure to meet this requirement can cause serious problems, some of which can be repaired only by
3449           rebooting. You must prevent non-AFS processes from filling up the cache partition. The simplest way is to devote a
3450           partition to the cache exclusively.</para>
3451         </listitem>
3452
3453         <listitem>
3454           <para>The amount of space available in memory or on the partition housing the disk cache directory imposes an absolute
3455           limit on cache size.</para>
3456         </listitem>
3457
3458         <listitem>
3459           <para>The maximum supported cache size can vary in each AFS release; see the <emphasis>OpenAFS Release Notes</emphasis>
3460           for the current version.</para>
3461         </listitem>
3462
3463         <listitem>
3464           <para>For a disk cache, you cannot specify a value in the third field that exceeds 95% of the space available on the
3465           partition mounted at the directory named in the second field. If you violate this restriction, the <emphasis
3466           role="bold">afsd</emphasis> program exits without starting the Cache Manager and prints an appropriate message on the
3467           standard output stream. A value of 90% is more appropriate on most machines. Some operating systems (such as AIX) do not
3468           automatically reserve some space to prevent the partition from filling completely; for them, a smaller value (say, 80% to
3469           85% of the space available) is more appropriate.</para>
3470         </listitem>
3471
3472         <listitem>
3473           <para>For a memory cache, you must leave enough memory for other processes and applications to run. If you try to allocate
3474           more memory than is actually available, the <emphasis role="bold">afsd</emphasis> program exits without initializing the
3475           Cache Manager and produces the following message on the standard output stream. <programlisting>
3476    afsd: memCache allocation failure at <replaceable>number</replaceable> KB
3477 </programlisting></para>
3478
3479           <para>The <replaceable>number</replaceable> value is how many kilobytes were allocated just before the failure, and so
3480           indicates the approximate amount of memory available.</para>
3481         </listitem>
3482       </itemizedlist></para>
3483
3484     <para>Within these hard limits, the factors that determine appropriate cache size include the number of users working on the
3485     machine, the size of the files with which they work, and (for a memory cache) the number of processes that run on the machine.
3486     The higher the demand from these factors, the larger the cache needs to be to maintain good performance.</para>
3487
3488     <para>Disk caches smaller than 10 MB do not generally perform well. Machines serving multiple users usually perform better with
3489     a cache of at least 60 to 70 MB. The point at which enlarging the cache further does not really improve performance depends on
3490     the factors mentioned previously and is difficult to predict.</para>
3491
3492     <para>Memory caches smaller than 1 MB are nonfunctional, and the performance of caches smaller than 5 MB is usually
3493     unsatisfactory. Suitable upper limits are similar to those for disk caches but are probably determined more by the demands on
3494     memory from other sources on the machine (number of users and processes). Machines running only a few processes possibly can use
3495     a smaller memory cache.</para>
3496
3497     <sect2 id="HDRWQ68">
3498       <title>Configuring a Disk Cache</title>
3499
3500       <note>
3501         <para>Not all file system types that an operating system supports are necessarily supported for use as the cache partition.
3502         For possible restrictions, see the <emphasis>OpenAFS Release Notes</emphasis>.</para>
3503       </note>
3504
3505       <para>To configure the disk cache, perform the following procedures: <orderedlist>
3506           <listitem>
3507             <para>Create the local directory to use for caching. The following instruction shows the conventional location,
3508             <emphasis role="bold">/usr/vice/cache</emphasis>. If you are devoting a partition exclusively to caching, as
3509             recommended, you must also configure it, make a file system on it, and mount it at the directory created in this step.
3510             <programlisting>
3511    # <emphasis role="bold">mkdir /usr/vice/cache</emphasis>
3512 </programlisting></para>
3513           </listitem>
3514
3515           <listitem>
3516             <para>Create the <emphasis role="bold">cacheinfo</emphasis> file to define the configuration parameters discussed
3517             previously. The following instruction shows the standard mount location, <emphasis role="bold">/afs</emphasis>, and the
3518             standard cache location, <emphasis role="bold">/usr/vice/cache</emphasis>. <programlisting>
3519    # <emphasis role="bold">echo "/afs:/usr/vice/cache:</emphasis><replaceable>#blocks</replaceable><emphasis role="bold">" &gt; /usr/vice/etc/cacheinfo</emphasis>
3520 </programlisting></para>
3521
3522             <para>The following example defines the disk cache size as 50,000 KB:</para>
3523
3524             <programlisting>
3525    # <emphasis role="bold">echo "/afs:/usr/vice/cache:50000" &gt; /usr/vice/etc/cacheinfo</emphasis>
3526 </programlisting>
3527           </listitem>
3528         </orderedlist></para>
3529     </sect2>
3530
3531     <sect2 id="HDRWQ69">
3532       <title>Configuring a Memory Cache</title>
3533
3534       <para>To configure a memory cache, create the <emphasis role="bold">cacheinfo</emphasis> file to define the configuration
3535       parameters discussed previously. The following instruction shows the standard mount location, <emphasis
3536       role="bold">/afs</emphasis>, and the standard cache location, <emphasis role="bold">/usr/vice/cache</emphasis> (though the
3537       exact value of the latter is irrelevant for a memory cache).</para>
3538
3539       <programlisting>
3540    # <emphasis role="bold">echo "/afs:/usr/vice/cache:</emphasis><replaceable>#blocks</replaceable><emphasis role="bold">" &gt; /usr/vice/etc/cacheinfo</emphasis>
3541 </programlisting>
3542
3543       <para>The following example allocates 25,000 KB of memory for the cache.</para>
3544
3545       <programlisting>
3546    # <emphasis role="bold">echo "/afs:/usr/vice/cache:25000" &gt; /usr/vice/etc/cacheinfo</emphasis>
3547 </programlisting>
3548
3549       <indexterm>
3550         <primary>Cache Manager</primary>
3551
3552         <secondary>first AFS machine</secondary>
3553       </indexterm>
3554
3555       <indexterm>
3556         <primary>configuring</primary>
3557
3558         <secondary>Cache Manager</secondary>
3559
3560         <tertiary>first AFS machine</tertiary>
3561       </indexterm>
3562
3563       <indexterm>
3564         <primary>first AFS machine</primary>
3565
3566         <secondary>Cache Manager</secondary>
3567       </indexterm>
3568
3569       <indexterm>
3570         <primary>afs (/afs) directory</primary>
3571
3572         <secondary>creating</secondary>
3573
3574         <tertiary>first AFS machine</tertiary>
3575       </indexterm>
3576
3577       <indexterm>
3578         <primary>AFS initialization script</primary>
3579
3580         <secondary>setting afsd parameters</secondary>
3581
3582         <tertiary>first AFS machine</tertiary>
3583       </indexterm>
3584
3585       <indexterm>
3586         <primary>first AFS machine</primary>
3587
3588         <secondary>afsd command parameters</secondary>
3589       </indexterm>
3590     </sect2>
3591   </sect1>
3592
3593   <sect1 id="HDRWQ70">
3594     <title>Configuring the Cache Manager</title>
3595
3596     <para>By convention, the Cache Manager mounts the AFS filespace on the local <emphasis role="bold">/afs</emphasis> directory. In
3597     this section you create that directory.</para>
3598
3599     <para>The <emphasis role="bold">afsd</emphasis> program sets several cache configuration parameters as it initializes the Cache
3600     Manager, and starts daemons that improve performance. You can use the <emphasis role="bold">afsd</emphasis> command's arguments
3601     to override the parameters' default values and to change the number of some of the daemons. Depending on the machine's cache
3602     size, its amount of RAM, and how many people work on it, you can sometimes improve Cache Manager performance by overriding the
3603     default values. For a discussion of all of the <emphasis role="bold">afsd</emphasis> command's arguments, see its reference page
3604     in the <emphasis>OpenAFS Administration Reference</emphasis>.</para>
3605
3606     <para>On platforms using the standard 'afs' initialisation script (this does not apply to Fedora or RHEL based distributions), the <emphasis role="bold">afsd</emphasis> command line in the AFS initialization script on each system type includes an
3607     <computeroutput>OPTIONS</computeroutput> variable. You can use it to set nondefault values for the command's arguments, in one
3608     of the following ways: <itemizedlist>
3609         <listitem>
3610           <para>You can create an <emphasis role="bold">afsd</emphasis> <emphasis>options file</emphasis> that sets values for
3611           arguments to the <emphasis role="bold">afsd</emphasis> command. If the file exists, its contents are automatically
3612           substituted for the <computeroutput>OPTIONS</computeroutput> variable in the AFS initialization script. The AFS
3613           distribution for some system types includes an options file; on other system types, you must create it.</para>
3614
3615           <para>You use two variables in the AFS initialization script to specify the path to the options file:
3616           <computeroutput>CONFIG</computeroutput> and <computeroutput>AFSDOPT</computeroutput>. On system types that define a
3617           conventional directory for configuration files, the <computeroutput>CONFIG</computeroutput> variable indicates it by
3618           default; otherwise, the variable indicates an appropriate location.</para>
3619
3620           <para>List the desired <emphasis role="bold">afsd</emphasis> options on a single line in the options file, separating each
3621           option with one or more spaces. The following example sets the <emphasis role="bold">-stat</emphasis> argument to 2500,
3622           the <emphasis role="bold">-daemons</emphasis> argument to 4, and the <emphasis role="bold">-volumes</emphasis> argument to
3623           100.</para>
3624
3625           <programlisting>
3626    -stat 2500 -daemons 4 -volumes 100   
3627 </programlisting>
3628         </listitem>
3629
3630         <listitem>
3631           <para>On a machine that uses a disk cache, you can set the <computeroutput>OPTIONS</computeroutput> variable in the AFS
3632           initialization script to one of <computeroutput>$SMALL</computeroutput>, <computeroutput>$MEDIUM</computeroutput>, or
3633           <computeroutput>$LARGE</computeroutput>. The AFS initialization script uses one of these settings if the <emphasis
3634           role="bold">afsd</emphasis> options file named by the <computeroutput>AFSDOPT</computeroutput> variable does not exist. In
3635           the script as distributed, the <computeroutput>OPTIONS</computeroutput> variable is set to the value
3636           <computeroutput>$MEDIUM</computeroutput>.</para>
3637
3638           <note>
3639             <para>Do not set the <computeroutput>OPTIONS</computeroutput> variable to <computeroutput>$SMALL</computeroutput>,
3640             <computeroutput>$MEDIUM</computeroutput>, or <computeroutput>$LARGE</computeroutput> on a machine that uses a memory
3641             cache. The arguments it sets are appropriate only on a machine that uses a disk cache.</para>
3642           </note>
3643
3644           <para>The script (or on some system types the <emphasis role="bold">afsd</emphasis> options file named by the
3645           <computeroutput>AFSDOPT</computeroutput> variable) defines a value for each of <computeroutput>SMALL</computeroutput>,
3646           <computeroutput>MEDIUM</computeroutput>, and <computeroutput>LARGE</computeroutput> that sets <emphasis
3647           role="bold">afsd</emphasis> command arguments appropriately for client machines of different sizes: <itemizedlist>
3648               <listitem>
3649                 <para><computeroutput>SMALL</computeroutput> is suitable for a small machine that serves one or two users and has
3650                 approximately 8 MB of RAM and a 20-MB cache</para>
3651               </listitem>
3652
3653               <listitem>
3654                 <para><computeroutput>MEDIUM</computeroutput> is suitable for a medium-sized machine that serves two to six users
3655                 and has 16 MB of RAM and a 40-MB cache</para>
3656               </listitem>
3657
3658               <listitem>
3659                 <para><computeroutput>LARGE</computeroutput> is suitable for a large machine that serves five to ten users and has
3660                 32 MB of RAM and a 100-MB cache</para>
3661               </listitem>
3662             </itemizedlist></para>
3663         </listitem>
3664
3665         <listitem>
3666           <para>You can choose not to create an <emphasis role="bold">afsd</emphasis> options file and to set the
3667           <computeroutput>OPTIONS</computeroutput> variable in the initialization script to a null value rather than to the default
3668           <computeroutput>$MEDIUM</computeroutput> value. You can then either set arguments directly on the <emphasis
3669           role="bold">afsd</emphasis> command line in the script, or set no arguments (and so accept default values for all Cache
3670           Manager parameters).</para>
3671         </listitem>
3672       </itemizedlist>
3673
3674       <note>
3675       <para>If you are running on a Fedora or RHEL based system, the 
3676       openafs-client initialization script behaves differently from that 
3677       described above. It sources /etc/sysconfig/openafs, in which the
3678       AFSD_ARGS variable may be set to contain any, or all, of the afsd options
3679       detailed. Note that this script does not support setting an OPTIONS
3680       variable, or the SMALL, MEDIUM and LARGE methods of defining cache size
3681       </para>
3682       </note>
3683
3684  <orderedlist>
3685         <listitem>
3686           <para>Create the local directory on which to mount the AFS filespace, by convention <emphasis role="bold">/afs</emphasis>.
3687           If the directory already exists, verify that it is empty. <programlisting>
3688    # <emphasis role="bold">mkdir /afs</emphasis>
3689 </programlisting></para>
3690         </listitem>
3691
3692         <listitem>
3693           <para>On AIX systems, add the following line to the <emphasis role="bold">/etc/vfs</emphasis> file. It enables AIX to
3694           unmount AFS correctly during shutdown. <programlisting>
3695    afs     4     none     none
3696 </programlisting></para>
3697         </listitem>
3698
3699         <listitem>
3700           <para>On non-package based Linux systems, copy the <emphasis role="bold">afsd</emphasis> options file from the <emphasis
3701           role="bold">/usr/vice/etc</emphasis> directory to the <emphasis role="bold">/etc/sysconfig</emphasis> directory, removing
3702           the <emphasis role="bold">.conf</emphasis> extension as you do so. <programlisting>
3703    # <emphasis role="bold">cp /usr/vice/etc/afs.conf /etc/sysconfig/afs</emphasis>
3704 </programlisting></para>
3705         </listitem>
3706
3707         <listitem>
3708           <para>Edit the machine's AFS initialization script or <emphasis role="bold">afsd</emphasis> options file to set
3709           appropriate values for <emphasis role="bold">afsd</emphasis> command parameters. The script resides in the indicated
3710           location on each system type: <itemizedlist>
3711               <listitem>
3712                 <para>On AIX systems, <emphasis role="bold">/etc/rc.afs</emphasis></para>
3713               </listitem>
3714
3715                   <listitem>
3716                 <para>On Fedora and RHEL systems, <emphasis role="bold">/etc/sysconfg/openafs</emphasis></para>
3717               </listitem>
3718               
3719               <listitem>
3720                 <para>On non-package based Linux systems, <emphasis role="bold">/etc/sysconfig/afs</emphasis> (the <emphasis
3721                 role="bold">afsd</emphasis> options file)</para>
3722               </listitem>
3723
3724               <listitem>
3725                 <para>On Solaris systems, <emphasis role="bold">/etc/init.d/afs</emphasis></para>
3726               </listitem>
3727             </itemizedlist></para>
3728
3729           <para>Use one of the methods described in the introduction to this section to add the following flags to the <emphasis
3730           role="bold">afsd</emphasis> command line. If you intend for the machine to remain an AFS client, also set any
3731           performance-related arguments you wish. <itemizedlist>
3732               <listitem>
3733                 <para>Add the <emphasis role="bold">-memcache</emphasis> flag if the machine is to use a memory cache.</para>
3734               </listitem>
3735
3736               <listitem>
3737                 <para>Add the <emphasis role="bold">-verbose</emphasis> flag to display a trace of the Cache Manager's
3738                 initialization on the standard output stream.</para>
3739               </listitem>
3740             </itemizedlist></para>
3741         </listitem>
3742       </orderedlist>
3743       <note><para>In order to successfully complete the instructions in the
3744       remainder of this guide, it is important that the machine does not have
3745       a synthetic root (as discussed in <link linkend="HDRWQ91">Enabling Access
3746       to Foreign Cells</link>). As some distributions ship with this enabled, it
3747       may be necessary to remove any occurences of the 
3748       <emphasis role="bold">-dynroot</emphasis> and 
3749       <emphasis role="bold">-afsdb</emphasis> options from both the AFS 
3750       initialisation script and options file. If this functionality is 
3751       required it may be renabled as detailed in 
3752       <link linkend="HDRWQ91">Enabling Access to Foreign Cells</link>.
3753       </para></note>
3754       </para>
3755
3756     <indexterm>
3757       <primary>overview</primary>
3758
3759       <secondary>completing installation of first machine</secondary>
3760     </indexterm>
3761
3762     <indexterm>
3763       <primary>first AFS machine</primary>
3764
3765       <secondary>completion of installation</secondary>
3766     </indexterm>
3767   </sect1>
3768
3769   <sect1 id="HDRWQ71">
3770     <title>Overview: Completing the Installation of the First AFS Machine</title>
3771
3772     <para>The machine is now configured as an AFS file server and client machine. In this final phase of the installation, you
3773     initialize the Cache Manager and then create the upper levels of your AFS filespace, among other procedures. The procedures are:
3774     <orderedlist>
3775         <listitem>
3776           <para>Verify that the initialization script works correctly, and incorporate it into the operating system's startup and
3777           shutdown sequence</para>
3778         </listitem>
3779
3780         <listitem>
3781           <para>Create and mount top-level volumes</para>
3782         </listitem>
3783
3784         <listitem>
3785           <para>Create and mount volumes to store system binaries in AFS</para>
3786         </listitem>
3787
3788         <listitem>
3789           <para>Enable access to foreign cells</para>
3790         </listitem>
3791
3792         <listitem>
3793           <para>Institute additional security measures</para>
3794         </listitem>
3795
3796         <listitem>
3797           <para>Remove client functionality if desired</para>
3798         </listitem>
3799       </orderedlist></para>
3800
3801     <indexterm>
3802       <primary>AFS initialization script</primary>
3803
3804       <secondary>verifying on first AFS machine</secondary>
3805     </indexterm>
3806
3807     <indexterm>
3808       <primary>AFS initialization script</primary>
3809
3810       <secondary>running</secondary>
3811
3812       <tertiary>first AFS machine</tertiary>
3813     </indexterm>
3814
3815     <indexterm>
3816       <primary>first AFS machine</primary>
3817
3818       <secondary>AFS initialization script</secondary>
3819
3820       <tertiary>running/verifying</tertiary>
3821     </indexterm>
3822
3823     <indexterm>
3824       <primary>running AFS init. script</primary>
3825
3826       <secondary>first AFS machine</secondary>
3827     </indexterm>
3828
3829     <indexterm>
3830       <primary>invoking AFS init. script</primary>
3831
3832       <see>running</see>
3833     </indexterm>
3834   </sect1>
3835
3836   <sect1 id="HDRWQ72">
3837     <title>Verifying the AFS Initialization Script</title>
3838
3839     <para>At this point you run the AFS initialization script to verify that it correctly invokes all of the necessary programs and
3840     AFS processes, and that they start correctly. The following are the relevant commands: <itemizedlist>
3841         <listitem>
3842           <para>The command that dynamically loads AFS modifications into the kernel, on some system types (not applicable if the
3843           kernel has AFS modifications built in)</para>
3844         </listitem>
3845
3846         <listitem>
3847           <para>The <emphasis role="bold">bosserver</emphasis> command, which starts the BOS Server; it in turn starts the server
3848           processes for which you created entries in the <emphasis role="bold">/usr/afs/local/BosConfig</emphasis> file</para>
3849         </listitem>
3850
3851         <listitem>
3852           <para>The <emphasis role="bold">afsd</emphasis> command, which initializes the Cache Manager</para>
3853         </listitem>
3854       </itemizedlist></para>
3855