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