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