DOC: Add a missing quote in the QuickStart Guide
[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   <indexterm>
6     <primary>file server machine</primary>
7
8     <seealso>first AFS machine</seealso>
9
10     <seealso>file server machine, additional</seealso>
11   </indexterm>
12
13   <indexterm>
14     <primary>instructions</primary>
15
16     <secondary>first AFS machine</secondary>
17   </indexterm>
18
19   <indexterm>
20     <primary>installing</primary>
21
22     <secondary>first AFS machine</secondary>
23   </indexterm>
24
25   <para>This chapter describes how to install the first AFS machine in your cell, configuring it as both a file server machine and a
26   client machine. After completing all procedures in this chapter, you can remove the client functionality if you wish, as described
27   in <link linkend="HDRWQ98">Removing Client Functionality</link>.</para>
28
29   <para>To install additional file server machines after completing this chapter, see <link linkend="HDRWQ99">Installing Additional
30   Server Machines</link>.</para>
31
32   <para>To install additional client machines after completing this chapter, see <link linkend="HDRWQ133">Installing Additional
33   Client Machines</link>. <indexterm>
34       <primary>requirements</primary>
35
36       <secondary>first AFS machine</secondary>
37     </indexterm></para>
38
39   <sect1 id="Header_29">
40     <title>Requirements and Configuration Decisions</title>
41
42     <para>The instructions in this chapter assume that you meet the following requirements. 
43       <itemizedlist>
44         <listitem>
45           <para>You are logged onto the machine's console as the local superuser <emphasis role="bold">root</emphasis></para>
46         </listitem>
47
48         <listitem>
49           <para>A standard version of one of the operating systems supported by the current version of AFS is running on the
50           machine</para>
51         </listitem>
52
53         <listitem>
54           <para>You have either installed the provided OpenAFS packages for 
55           your system, have access to a binary distribution tarball, or have 
56           successfully built OpenAFS from source</para>
57         </listitem>
58
59         <listitem>
60           <para>You have a Kerberos v5 realm running for your site. If you are
61           working with an existing cell which uses 
62           <emphasis role="bold">kaserver</emphasis> or Kerberos v4 for
63           authentication, please see 
64           <link linkend="KAS001">kaserver and Legacy Kerberos v4 Authentication</link>
65           for the modifications required to this installation procedure.</para>
66         </listitem>
67
68         <listitem>
69           <para>You have a NTP, or similar, time service deployed to ensure 
70           rough clock syncronistation between your clients and servers. If you
71           wish to use AFS's built in timeservice (which is deprecated) please
72           see Appendix B for the necessary modifications to this installation
73           procedure.</para>
74         </listitem>
75       </itemizedlist></para>
76
77     <para>You must make the following configuration decisions while installing the first AFS machine. To speed the installation
78     itself, it is best to make the decisions before beginning. See the chapter in the <emphasis>OpenAFS Administration
79     Guide</emphasis> about issues in cell administration and configuration for detailed guidelines. <indexterm>
80         <primary>cell name</primary>
81
82         <secondary>choosing</secondary>
83       </indexterm> <indexterm>
84         <primary>AFS filespace</primary>
85
86         <secondary>deciding how to configure</secondary>
87       </indexterm> <indexterm>
88         <primary>filespace</primary>
89
90         <see>AFS filespace</see>
91       </indexterm> <itemizedlist>
92         <listitem>
93           <para>Select the first AFS machine</para>
94         </listitem>
95
96         <listitem>
97           <para>Select the cell name</para>
98         </listitem>
99
100         <listitem>
101           <para>Decide which partitions or logical volumes to configure as AFS server partitions, and choose the directory names on
102           which to mount them</para>
103         </listitem>
104
105         <listitem>
106           <para>Decide how big to make the client cache</para>
107         </listitem>
108
109         <listitem>
110           <para>Decide how to configure the top levels of your cell's AFS filespace</para>
111         </listitem>
112       </itemizedlist></para>
113
114     <para>This chapter is divided into three large sections corresponding to the three parts of installing the first AFS machine.
115     Perform all of the steps in the order they appear. Each functional section begins with a summary of the procedures to perform.
116     The sections are as follows: <itemizedlist>
117         <listitem>
118           <para>Installing server functionality (begins in <link linkend="HDRWQ18">Overview: Installing Server
119           Functionality</link>)</para>
120         </listitem>
121
122         <listitem>
123           <para>Installing client functionality (begins in <link linkend="HDRWQ63">Overview: Installing Client
124           Functionality</link>)</para>
125         </listitem>
126
127         <listitem>
128           <para>Configuring your cell's filespace, establishing further security mechanisms, and enabling access to foreign cells
129           (begins in <link linkend="HDRWQ71">Overview: Completing the Installation of the First AFS Machine</link>)</para>
130         </listitem>
131       </itemizedlist></para>
132
133     <indexterm>
134       <primary>overview</primary>
135
136       <secondary>installing server functionality on first AFS machine</secondary>
137     </indexterm>
138
139     <indexterm>
140       <primary>first AFS machine</primary>
141
142       <secondary>server functionality</secondary>
143     </indexterm>
144
145     <indexterm>
146       <primary>installing</primary>
147
148       <secondary>server functionality</secondary>
149
150       <tertiary>first AFS machine</tertiary>
151     </indexterm>
152   </sect1>
153
154   <sect1 id="HDRWQ18">
155     <title>Overview: Installing Server Functionality</title>
156
157     <para>In the first phase of installing your cell's first AFS machine, you install file server and database server functionality
158     by performing the following procedures: 
159     <orderedlist>
160         <listitem>
161           <para>Choose which machine to install as the first AFS machine</para>
162         </listitem>
163
164         <listitem>
165           <para>Create AFS-related directories on the local disk</para>
166         </listitem>
167
168         <listitem>
169           <para>Incorporate AFS modifications into the machine's kernel</para>
170         </listitem>
171
172         <listitem>
173           <para>Configure partitions or logical volumes for storing AFS volumes</para>
174         </listitem>
175
176         <listitem>
177           <para>On some system types, install and configure an AFS-modified version of the <emphasis role="bold">fsck</emphasis>
178           program</para>
179         </listitem>
180
181         <listitem>
182           <para>If the machine is to remain a client machine, incorporate AFS into its authentication system</para>
183         </listitem>
184
185         <listitem>
186           <para>Start the Basic OverSeer (BOS) Server</para>
187         </listitem>
188
189         <listitem>
190           <para>Define the cell name and the machine's cell membership</para>
191         </listitem>
192
193         <listitem>
194           <para>Start the database server processes: Backup Server, Protection Server, and Volume Location
195           (VL) Server</para>
196         </listitem>
197
198         <listitem>
199           <para>Configure initial security mechanisms</para>
200         </listitem>
201
202         <listitem>
203           <para>Start the <emphasis role="bold">fs</emphasis> process, which incorporates three component processes: the File
204           Server, Volume Server, and Salvager</para>
205         </listitem>
206
207         <listitem>
208           <para>Optionally, start the server portion of the Update Server</para>
209         </listitem>
210
211       </orderedlist></para>
212   </sect1>
213
214   <sect1 id="HDRWQ19">
215     <title>Choosing the First AFS Machine</title>
216
217     <para>The first AFS machine you install must have sufficient disk space to store AFS volumes. To take best advantage of AFS's
218     capabilities, store client-side binaries as well as user files in volumes. When you later install additional file server
219     machines in your cell, you can distribute these volumes among the different machines as you see fit.</para>
220
221     <para>These instructions configure the first AFS machine as a <emphasis>database server machine</emphasis>, the <emphasis>binary
222     distribution machine</emphasis> for its system type, and the cell's <emphasis>system control machine</emphasis>. For a
223     description of these roles, see the <emphasis>OpenAFS Administration Guide</emphasis>.</para>
224
225     <para>Installation of additional machines is simplest if the first machine has the lowest IP address of any database server
226     machine you currently plan to install. If you later install database server functionality on a machine with a lower IP address,
227     you must first update the <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file on all of your cell's client machines.
228     For more details, see <link linkend="HDRWQ114">Installing Database Server Functionality</link>.</para>
229   </sect1>
230
231   <sect1 id="Header_32">
232     <title>Creating AFS Directories</title>
233
234     <indexterm>
235       <primary>usr/afs directory</primary>
236
237       <secondary>first AFS machine</secondary>
238     </indexterm>
239
240     <indexterm>
241       <primary>first AFS machine</primary>
242
243       <secondary>/usr/afs directory</secondary>
244     </indexterm>
245
246     <indexterm>
247       <primary>creating</primary>
248
249       <secondary>/usr/afs directory</secondary>
250
251       <tertiary>first AFS machine</tertiary>
252     </indexterm>
253
254     <indexterm>
255       <primary>usr/vice/etc directory</primary>
256
257       <secondary>first AFS machine</secondary>
258     </indexterm>
259
260     <indexterm>
261       <primary>first AFS machine</primary>
262
263       <secondary>/usr/vice/etc directory</secondary>
264     </indexterm>
265
266     <indexterm>
267       <primary>creating</primary>
268
269       <secondary>/usr/vice/etc directory</secondary>
270
271       <tertiary>first AFS machine</tertiary>
272     </indexterm>
273
274     <indexterm>
275       <primary>/ as start to file and directory names</primary>
276
277       <secondary>see alphabetized entries without initial slash</secondary>
278     </indexterm>
279
280     <para>If you are installing from packages (such as Debian .deb or 
281     Fedora/SuSe .rpm files), you should now install all of the available 
282     OpenAFS packages for your system type. Typically, these will include 
283     packages for client and server functionality, and a seperate package 
284     containing a suitable kernel module for your running kernel. Consult 
285     the package lists on the OpenAFS website to determine the packages 
286     appropriate for your system.</para>
287
288     <para>If you are installing from a tarfile, or from a locally compiled 
289     source tree you should create the <emphasis role="bold">/usr/afs</emphasis>
290     and <emphasis role="bold">/usr/vice/etc</emphasis> directories on the
291     local disk, to house server and client files respectively. Subsequent 
292     instructions copy files from the distribution tarfile into them. </para>
293 <programlisting>
294    # <emphasis role="bold">mkdir /usr/afs</emphasis>
295    # <emphasis role="bold">mkdir /usr/vice</emphasis>
296    # <emphasis role="bold">mkdir /usr/vice/etc</emphasis>
297 </programlisting>
298   </sect1>
299
300   <sect1 id="HDRWQ20">
301     <title>Performing Platform-Specific Procedures</title>
302
303     <para>Several of the initial procedures for installing a file server machine differ for each system type. For convenience, the
304     following sections group them together for each system type: <itemizedlist>
305         <indexterm>
306           <primary>kernel extensions</primary>
307
308           <see>AFS kernel extensions</see>
309         </indexterm>
310
311         <indexterm>
312           <primary>loading AFS kernel extensions</primary>
313
314           <see>incorporating</see>
315         </indexterm>
316
317         <indexterm>
318           <primary>building</primary>
319
320           <secondary>AFS extensions into kernel</secondary>
321
322           <see>incorporating AFS kernel extensions</see>
323         </indexterm>
324
325         <listitem>
326           <para>Incorporate AFS modifications into the kernel.</para>
327
328           <para>The kernel on every AFS client machine and, on some systems, 
329           the AFS fileservers, must incorporate AFS extensions. On machines 
330           that use a dynamic kernel module loader, it is conventional to 
331           alter the machine's initialization script to load the AFS extensions
332           at each reboot. <indexterm>
333               <primary>AFS server partition</primary>
334
335               <secondary>mounted on /vicep directory</secondary>
336             </indexterm> <indexterm>
337               <primary>partition</primary>
338
339               <see>AFS server partition</see>
340             </indexterm> <indexterm>
341               <primary>logical volume</primary>
342
343               <see>AFS server partition</see>
344             </indexterm> <indexterm>
345               <primary>requirements</primary>
346
347               <secondary>AFS server partition name and location</secondary>
348             </indexterm> <indexterm>
349               <primary>naming conventions for AFS server partition</primary>
350             </indexterm> <indexterm>
351               <primary>vicep<emphasis>xx</emphasis> directory</primary>
352
353               <see>AFS server partition</see>
354             </indexterm> <indexterm>
355               <primary>directories</primary>
356
357               <secondary>/vicep<emphasis>xx</emphasis></secondary>
358
359               <see>AFS server partition</see>
360             </indexterm></para>
361         </listitem>
362
363         <listitem>
364           <para>Configure server partitions or logical volumes to house AFS volumes.</para>
365
366           <para>Every AFS file server machine must have at least one partition or logical volume dedicated to storing AFS volumes
367           (for convenience, the documentation hereafter refers to partitions only). Each server partition is mounted at a directory
368           named <emphasis role="bold">/vicep</emphasis><replaceable>xx</replaceable>, where <replaceable>xx</replaceable> is one or
369           two lowercase letters. By convention, the first 26 partitions are mounted on the directories called <emphasis
370           role="bold">/vicepa</emphasis> through <emphasis role="bold">/vicepz</emphasis>, the 27th one is mounted on the <emphasis
371           role="bold">/vicepaa</emphasis> directory, and so on through <emphasis role="bold">/vicepaz</emphasis> and <emphasis
372           role="bold">/vicepba</emphasis>, continuing up to the index corresponding to the maximum number of server partitions
373           supported in the current version of AFS (which is specified in the <emphasis>OpenAFS Release Notes</emphasis>).</para>
374
375           <para>The <emphasis role="bold">/vicep</emphasis><replaceable>xx</replaceable> directories must reside in the file server
376           machine's root directory, not in one of its subdirectories (for example, <emphasis role="bold">/usr/vicepa</emphasis> is
377           not an acceptable directory location).
378
379           The <emphasis role="bold">fileserver</emphasis> will refuse to
380           mount
381           any <emphasis role="bold">/vicep</emphasis><replaceable>xx</replaceable>
382           folders that are not separate partitions. </para>
383
384           <warning>
385             <para>The separate partition requirement may be overridden by
386               creating a file named
387               <emphasis role="bold">/vicep<replaceable>xx</replaceable>/AlwaysAttach</emphasis>;
388               however, mixed-use partitions, whether cache or fileserver,
389               have the risk that a non-AFS use will fill the partition and
390               not leave enough free space for AFS.  Even though it is
391               allowed, be wary of configuring a mixed-use partition
392               without understanding the ramifications of doing so with the
393               workload on your filesystem.
394               <indexterm>
395                 <primary>AFS server partition</primary>
396                 <secondary>AlwaysAttach</secondary>
397               </indexterm>
398             </para>
399           </warning>
400
401           <para>You can also add or remove server partitions on an existing file server machine. For instructions, see the chapter
402           in the <emphasis>OpenAFS Administration Guide</emphasis> about maintaining server machines.</para>
403
404           <note>
405             <para>Not all file system types supported by an operating system are necessarily supported as AFS server partitions. For
406             possible restrictions, see the <emphasis>OpenAFS Release Notes</emphasis>.</para>
407           </note>
408         </listitem>
409
410         <listitem>
411           <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
412           recognizes the structures that the File Server uses to organize volume data on AFS server partitions. The <emphasis
413           role="bold">fsck</emphasis> program provided with the operating system does not understand the AFS data structures, and so
414           removes them to the <emphasis role="bold">lost+found</emphasis> directory.</para>
415         </listitem>
416
417         <listitem>
418           <para>If the machine is to remain an AFS client machine, modify the machine's authentication system so that users obtain
419           an AFS token as they log into the local file system. Using AFS is simpler and more convenient for your users if you make
420           the modifications on all client machines. Otherwise, users must perform a two or three step login procedure (login to the local
421           system, then obtain Kerberos credentials, and then issue the <emphasis role="bold">aklog</emphasis> command). For further discussion of AFS
422           authentication, see the chapter in the <emphasis>OpenAFS Administration Guide</emphasis> about cell configuration and
423           administration issues.</para>
424         </listitem>
425       </itemizedlist></para>
426
427     <para>To continue, proceed to the appropriate section: <itemizedlist>
428         <listitem>
429           <para><link linkend="HDRWQ21">Getting Started on AIX Systems</link></para>
430         </listitem>
431
432         <listitem>
433           <para><link linkend="HDRWQ31">Getting Started on HP-UX Systems</link></para>
434         </listitem>
435
436         <listitem>
437           <para><link linkend="HDRWQ36">Getting Started on IRIX Systems</link></para>
438         </listitem>
439
440         <listitem>
441           <para><link linkend="HDRWQ41">Getting Started on Linux Systems</link></para>
442         </listitem>
443
444         <listitem>
445           <para><link linkend="HDRWQ45">Getting Started on Solaris Systems</link></para>
446         </listitem>
447       </itemizedlist></para>
448   </sect1>
449
450   <sect1 id="HDRWQ21">
451     <title>Getting Started on AIX Systems</title>
452
453     <para>Begin by running the AFS initialization script to call the AIX kernel extension facility, which dynamically loads AFS
454     modifications into the kernel. Then use the <emphasis role="bold">SMIT</emphasis> program to configure partitions for storing
455     AFS volumes, and replace the AIX <emphasis role="bold">fsck</emphasis> program helper with a version that correctly handles AFS
456     volumes. If the machine is to remain an AFS client machine, incorporate AFS into the AIX secondary authentication system.
457     <indexterm>
458         <primary>incorporating AFS kernel extensions</primary>
459
460         <secondary>first AFS machine</secondary>
461
462         <tertiary>AIX</tertiary>
463       </indexterm> <indexterm>
464         <primary>AFS kernel extensions</primary>
465
466         <secondary>on first AFS machine</secondary>
467
468         <tertiary>AIX</tertiary>
469       </indexterm> <indexterm>
470         <primary>first AFS machine</primary>
471
472         <secondary>AFS kernel extensions</secondary>
473
474         <tertiary>on AIX</tertiary>
475       </indexterm> <indexterm>
476         <primary>AIX</primary>
477
478         <secondary>AFS kernel extensions</secondary>
479
480         <tertiary>on first AFS machine</tertiary>
481       </indexterm></para>
482
483     <sect2 id="HDRWQ22">
484       <title>Loading AFS into the AIX Kernel</title>
485
486       <para>The AIX kernel extension facility is the dynamic kernel loader
487       provided by IBM Corporation.  AIX does not support incorporation of
488       AFS modifications during a kernel build.</para>
489
490       <para>For AFS to function correctly, the kernel extension facility must run each time the machine reboots, so the AFS
491       initialization script (included in the AFS distribution) invokes it automatically. In this section you copy the script to the
492       conventional location and edit it to select the appropriate options depending on whether NFS is also to run.</para>
493
494       <para>After editing the script, you run it to incorporate AFS into the kernel. In later sections you verify that the script
495       correctly initializes all AFS components, then configure the AIX <emphasis role="bold">inittab</emphasis> file so that the
496       script runs automatically at reboot. <orderedlist>
497           <listitem>
498             <para>Unpack the distribution tarball. The examples below assume 
499             that you have unpacked the files into the 
500             <emphasis role="bold">/tmp/afsdist</emphasis> directory. If you 
501             pick a different location, substitute this in all of the following 
502             examples. Once you have unpacked the distribution, 
503             change directory as indicated.
504 <programlisting>
505    # <emphasis role="bold">cd /tmp/afsdist/rs_aix42/root.client/usr/vice/etc</emphasis>
506 </programlisting></para>
507           </listitem>
508
509           <listitem>
510             <para>Copy the AFS kernel library files to the local <emphasis role="bold">/usr/vice/etc/dkload</emphasis> directory,
511             and the AFS initialization script to the <emphasis role="bold">/etc</emphasis> directory. <programlisting>
512    # <emphasis role="bold">cp -rp  dkload  /usr/vice/etc</emphasis>
513    # <emphasis role="bold">cp -p  rc.afs  /etc/rc.afs</emphasis>
514 </programlisting></para>
515           </listitem>
516
517           <listitem>
518             <para>Edit the <emphasis role="bold">/etc/rc.afs</emphasis> script, setting the <computeroutput>NFS</computeroutput>
519             variable as indicated.</para>
520
521             <para>If the machine is not to function as an NFS/AFS Translator, set the <computeroutput>NFS</computeroutput> variable
522             as follows.</para>
523
524             <programlisting>
525    NFS=$NFS_NONE
526 </programlisting>
527
528             <para>If the machine is to function as an NFS/AFS Translator and is running AIX 4.2.1 or higher, set the
529             <computeroutput>NFS</computeroutput> variable as follows. Note that NFS must already be loaded into the kernel, which
530             happens automatically on systems running AIX 4.1.1 and later, as long as the file <emphasis
531             role="bold">/etc/exports</emphasis> exists.</para>
532
533             <programlisting>
534    NFS=$NFS_IAUTH
535 </programlisting>
536           </listitem>
537
538           <listitem>
539             <para>Invoke the <emphasis role="bold">/etc/rc.afs</emphasis> script to load AFS modifications into the kernel. You can
540             ignore any error messages about the inability to start the BOS Server or the Cache Manager or AFS client.
541             <programlisting>
542    # <emphasis role="bold">/etc/rc.afs</emphasis>
543 </programlisting></para>
544           </listitem>
545         </orderedlist></para>
546
547       <indexterm>
548         <primary>configuring</primary>
549
550         <secondary>AFS server partition on first AFS machine</secondary>
551
552         <tertiary>AIX</tertiary>
553       </indexterm>
554
555       <indexterm>
556         <primary>AFS server partition</primary>
557
558         <secondary>configuring on first AFS machine</secondary>
559
560         <tertiary>AIX</tertiary>
561       </indexterm>
562
563       <indexterm>
564         <primary>first AFS machine</primary>
565
566         <secondary>AFS server partition</secondary>
567
568         <tertiary>on AIX</tertiary>
569       </indexterm>
570
571       <indexterm>
572         <primary>AIX</primary>
573
574         <secondary>AFS server partition</secondary>
575
576         <tertiary>on first AFS machine</tertiary>
577       </indexterm>
578     </sect2>
579
580     <sect2 id="HDRWQ23">
581       <title>Configuring Server Partitions on AIX Systems</title>
582
583       <para>Every AFS file server machine must have at least one partition or logical volume dedicated to storing AFS volumes. Each
584       server partition is mounted at a directory named <emphasis role="bold">/vicep</emphasis><replaceable>xx</replaceable>, where
585       <replaceable>xx</replaceable> is one or two lowercase letters. The <emphasis
586       role="bold">/vicep</emphasis><replaceable>xx</replaceable> directories must reside in the file server machine's root
587       directory, not in one of its subdirectories (for example, <emphasis role="bold">/usr/vicepa</emphasis> is not an acceptable
588       directory location). For additional information, see <link linkend="HDRWQ20">Performing Platform-Specific
589       Procedures</link>.</para>
590
591       <para>To configure server partitions on an AIX system, perform the following procedures: <orderedlist>
592           <listitem>
593             <para>Create a directory called <emphasis role="bold">/vicep</emphasis><replaceable>xx</replaceable> for each AFS server
594             partition you are configuring (there must be at least one). Repeat the command for each partition. <programlisting>
595    # <emphasis role="bold">mkdir /vicep</emphasis><replaceable>xx</replaceable>
596 </programlisting></para>
597           </listitem>
598
599           <listitem>
600             <para>Use the <emphasis role="bold">SMIT</emphasis> program to create a journaling file system on each partition to be
601             configured as an AFS server partition.</para>
602           </listitem>
603
604           <listitem>
605             <para>Mount each partition at one of the <emphasis role="bold">/vicep</emphasis><replaceable>xx</replaceable>
606             directories. Choose one of the following three methods: <itemizedlist>
607                 <listitem>
608                   <para>Use the <emphasis role="bold">SMIT</emphasis> program</para>
609                 </listitem>
610
611                 <listitem>
612                   <para>Use the <emphasis role="bold">mount -a</emphasis> command to mount all partitions at once</para>
613                 </listitem>
614
615                 <listitem>
616                   <para>Use the <emphasis role="bold">mount</emphasis> command on each partition in turn</para>
617                 </listitem>
618               </itemizedlist></para>
619
620             <para>Also configure the partitions so that they are mounted automatically at each reboot. For more information, refer
621             to the AIX documentation.</para>
622           </listitem>
623         </orderedlist></para>
624
625       <indexterm>
626         <primary>replacing fsck program</primary>
627
628         <secondary>first AFS machine</secondary>
629
630         <tertiary>AIX</tertiary>
631       </indexterm>
632
633       <indexterm>
634         <primary>fsck program</primary>
635
636         <secondary>on first AFS machine</secondary>
637
638         <tertiary>AIX</tertiary>
639       </indexterm>
640
641       <indexterm>
642         <primary>first AFS machine</primary>
643
644         <secondary>fsck program</secondary>
645
646         <tertiary>on AIX</tertiary>
647       </indexterm>
648
649       <indexterm>
650         <primary>AIX</primary>
651
652         <secondary>fsck program</secondary>
653
654         <tertiary>on first AFS machine</tertiary>
655       </indexterm>
656     </sect2>
657
658     <sect2 id="HDRWQ24">
659       <title>Replacing the fsck Program Helper on AIX Systems</title>
660
661       <note><para>The AFS modified fsck program is not required on AIX 5.1 
662       systems, and the <emphasis role="bold">v3fshelper</emphasis> program
663       refered to below is not shipped for these systems.</para></note>
664       
665       <para>In this section, you make modifications to guarantee that the appropriate <emphasis role="bold">fsck</emphasis> program
666       runs on AFS server partitions. The <emphasis role="bold">fsck</emphasis> program provided with the operating system must never
667       run on AFS server partitions. Because it does not recognize the structures that the File Server uses to organize volume data,
668       it removes all of the data. To repeat:</para>
669
670       <para><emphasis role="bold">Never run the standard fsck program on AFS server partitions. It discards AFS
671       volumes.</emphasis></para>
672
673       <para>On AIX systems, you do not replace the <emphasis role="bold">fsck</emphasis> binary itself, but rather the
674       <emphasis>program helper</emphasis> file included in the AIX distribution as <emphasis
675       role="bold">/sbin/helpers/v3fshelper</emphasis>. <orderedlist>
676           <listitem>
677             <para>Move the AIX <emphasis role="bold">fsck</emphasis> program helper to a safe location and install the version from
678             the AFS distribution in its place. 
679 <programlisting>
680    # <emphasis role="bold">cd /sbin/helpers</emphasis>
681    # <emphasis role="bold">mv v3fshelper v3fshelper.noafs</emphasis>
682    # <emphasis role="bold">cp -p /tmp/afsdist/rs_aix42/root.server/etc/v3fshelper v3fshelper</emphasis>
683 </programlisting></para>
684           </listitem>
685
686           <listitem>
687             <para>If you plan to retain client functionality on this machine after completing the installation, proceed to <link
688             linkend="HDRWQ25">Enabling AFS Login on AIX Systems</link>. Otherwise, proceed to <link linkend="HDRWQ50">Starting the
689             BOS Server</link>.</para>
690           </listitem>
691         </orderedlist></para>
692
693       <indexterm>
694         <primary>enabling AFS login</primary>
695
696         <secondary>file server machine</secondary>
697
698         <tertiary>AIX</tertiary>
699       </indexterm>
700
701       <indexterm>
702         <primary>AFS login</primary>
703
704         <secondary>on file server machine</secondary>
705
706         <tertiary>AIX</tertiary>
707       </indexterm>
708
709       <indexterm>
710         <primary>first AFS machine</primary>
711
712         <secondary>AFS login</secondary>
713
714         <tertiary>on AIX</tertiary>
715       </indexterm>
716
717       <indexterm>
718         <primary>AIX</primary>
719
720         <secondary>AFS login</secondary>
721
722         <tertiary>on file server machine</tertiary>
723       </indexterm>
724
725       <indexterm>
726         <primary>secondary authentication system (AIX)</primary>
727
728         <secondary>server machine</secondary>
729       </indexterm>
730     </sect2>
731
732     <sect2 id="HDRWQ25">
733       <title>Enabling AFS Login on AIX Systems</title>
734
735       <note>
736         <para>If you plan to remove client functionality from this machine after completing the installation, skip this section and
737         proceed to <link linkend="HDRWQ50">Starting the BOS Server</link>.</para>
738       </note>
739
740       <para>In modern AFS installations, you should be using Kerberos v5
741       for user login, and obtaining AFS tokens following this authentication
742       step.</para>
743       
744       <para>There are currently no instructions available on configuring AIX to
745       automatically obtain AFS tokens at login. Following login, users can 
746       obtain tokens by running the <emphasis role="bold">aklog</emphasis> 
747       command</para>
748      
749       <para>Sites which still require <emphasis role="bold">kaserver</emphasis>
750       or external Kerberos v4 authentication should consult 
751       <link linkend="KAS012">Enabling kaserver based AFS login on AIX systems</link>
752       for details of how to enable AIX login.</para>
753       
754       <para>Proceed to <link linkend="HDRWQ50">Starting the BOS Server</link> 
755       (or if referring to these instructions while installing an additional 
756       file server machine, return to <link linkend="HDRWQ108">Starting Server
757       Programs</link>).</para>
758     </sect2>
759   </sect1>
760
761   <sect1 id="HDRWQ31">
762     <title>Getting Started on HP-UX Systems</title>
763
764     <para>Begin by building AFS modifications into a new kernel; HP-UX
765     does not support dynamic loading. Then create partitions for storing
766     AFS volumes, and install and configure the AFS-modified <emphasis
767     role="bold">fsck</emphasis> program to run on AFS server
768     partitions. If the machine is to remain an AFS client machine,
769     incorporate AFS into the machine's Pluggable Authentication Module
770     (PAM) scheme. <indexterm>
771         <primary>incorporating AFS kernel extensions</primary>
772
773         <secondary>first AFS machine</secondary>
774
775         <tertiary>HP-UX</tertiary>
776       </indexterm> <indexterm>
777         <primary>AFS kernel extensions</primary>
778
779         <secondary>on first AFS machine</secondary>
780
781         <tertiary>HP-UX</tertiary>
782       </indexterm> <indexterm>
783         <primary>first AFS machine</primary>
784
785         <secondary>AFS kernel extensions</secondary>
786
787         <tertiary>on HP-UX</tertiary>
788       </indexterm> <indexterm>
789         <primary>HP-UX</primary>
790
791         <secondary>AFS-modified kernel</secondary>
792
793         <tertiary>on first AFS machine</tertiary>
794       </indexterm></para>
795
796     <sect2 id="HDRWQ32">
797       <title>Building AFS into the HP-UX Kernel</title>
798
799       <para>Use the following instructions to build AFS modifications into the kernel on an HP-UX system. <orderedlist>
800           <listitem>
801             <para>Move the existing kernel-related files to a safe location. <programlisting>
802    # <emphasis role="bold">cp /stand/vmunix /stand/vmunix.noafs</emphasis>
803    # <emphasis role="bold">cp /stand/system /stand/system.noafs</emphasis>
804 </programlisting></para>
805           </listitem>
806
807           <listitem>
808             <para>Unpack the OpenAFS HP-UX distribution tarball. The examples 
809             below assume that you have unpacked the files into the 
810             <emphasis role="bold">/tmp/afsdist</emphasis> directory. If you 
811             pick a different location, substitute this in all of the following 
812             examples. Once you have unpacked the distribution, change directory 
813             as indicated.
814             <programlisting>
815    # <emphasis role="bold">cd /tmp/afsdist/hp_ux110/root.client</emphasis>
816 </programlisting></para>
817           </listitem>
818
819           <listitem>
820             <para>Copy the AFS initialization file to the local directory for initialization files (by convention, <emphasis
821             role="bold">/sbin/init.d</emphasis> on HP-UX machines). Note the removal of the <emphasis role="bold">.rc</emphasis>
822             extension as you copy the file. <programlisting>
823    # <emphasis role="bold">cp usr/vice/etc/afs.rc  /sbin/init.d/afs</emphasis>
824 </programlisting></para>
825           </listitem>
826
827           <listitem>
828             <para>Copy the file <emphasis role="bold">afs.driver</emphasis> to the local <emphasis
829             role="bold">/usr/conf/master.d</emphasis> directory, changing its name to <emphasis role="bold">afs</emphasis> as you
830             do. <programlisting>
831    # <emphasis role="bold">cp  usr/vice/etc/afs.driver  /usr/conf/master.d/afs</emphasis>
832 </programlisting></para>
833           </listitem>
834
835           <listitem>
836             <para>Copy the AFS kernel module to the local <emphasis role="bold">/usr/conf/lib</emphasis> directory.</para>
837
838             <para>If the machine's kernel supports NFS server functionality:</para>
839
840             <programlisting>
841    # <emphasis role="bold">cp bin/libafs.a /usr/conf/lib</emphasis>   
842 </programlisting>
843
844             <para>If the machine's kernel does not support NFS server functionality, change the file's name as you copy it:</para>
845
846             <programlisting>
847    # <emphasis role="bold">cp bin/libafs.nonfs.a /usr/conf/lib/libafs.a</emphasis>
848 </programlisting>
849           </listitem>
850
851           <listitem>
852             <para>Incorporate the AFS driver into the kernel, either using the <emphasis role="bold">SAM</emphasis> program or a
853             series of individual commands. <itemizedlist>
854                 <listitem>
855                   <para>To use the <emphasis role="bold">SAM</emphasis> program: <orderedlist>
856                       <listitem>
857                         <para>Invoke the <emphasis role="bold">SAM</emphasis> program, specifying the hostname of the local machine
858                         as <replaceable>local_hostname</replaceable>. The <emphasis role="bold">SAM</emphasis> graphical user
859                         interface pops up. <programlisting>
860    # <emphasis role="bold">sam -display</emphasis> <replaceable>local_hostname</replaceable><emphasis role="bold">:0</emphasis> 
861 </programlisting></para>
862                       </listitem>
863
864                       <listitem>
865                         <para>Choose the <emphasis role="bold">Kernel Configuration</emphasis> icon, then the <emphasis
866                         role="bold">Drivers</emphasis> icon. From the list of drivers, select <emphasis
867                         role="bold">afs</emphasis>.</para>
868                       </listitem>
869
870                       <listitem>
871                         <para>Open the pull-down <emphasis role="bold">Actions</emphasis> menu and choose the <emphasis
872                         role="bold">Add Driver to Kernel</emphasis> option.</para>
873                       </listitem>
874
875                       <listitem>
876                         <para>Open the <emphasis role="bold">Actions</emphasis> menu again and choose the <emphasis
877                         role="bold">Create a New Kernel</emphasis> option.</para>
878                       </listitem>
879
880                       <listitem>
881                         <para>Confirm your choices by choosing <emphasis role="bold">Yes</emphasis> and <emphasis
882                         role="bold">OK</emphasis> when prompted by subsequent pop-up windows. The <emphasis
883                         role="bold">SAM</emphasis> program builds the kernel and reboots the system.</para>
884                       </listitem>
885
886                       <listitem>
887                         <para>Login again as the superuser <emphasis role="bold">root</emphasis>. <programlisting>
888    login: <emphasis role="bold">root</emphasis>
889    Password: <replaceable>root_password</replaceable>
890 </programlisting></para>
891                       </listitem>
892                     </orderedlist></para>
893                 </listitem>
894
895                 <listitem>
896                   <para>To use individual commands: <orderedlist>
897                       <listitem>
898                         <para>Edit the file <emphasis role="bold">/stand/system</emphasis>, adding an entry for <emphasis
899                         role="bold">afs</emphasis> to the <computeroutput>Subsystems</computeroutput> section.</para>
900                       </listitem>
901
902                       <listitem>
903                         <para>Change to the <emphasis role="bold">/stand/build</emphasis> directory and issue the <emphasis
904                         role="bold">mk_kernel</emphasis> command to build the kernel. <programlisting>
905    # <emphasis role="bold">cd /stand/build</emphasis>
906    # <emphasis role="bold">mk_kernel</emphasis>
907 </programlisting></para>
908                       </listitem>
909
910                       <listitem>
911                         <para>Move the new kernel to the standard location (<emphasis role="bold">/stand/vmunix</emphasis>), reboot
912                         the machine to start using it, and login again as the superuser <emphasis role="bold">root</emphasis>.
913                         <programlisting>
914    # <emphasis role="bold">mv /stand/build/vmunix_test /stand/vmunix</emphasis>
915    # <emphasis role="bold">cd /</emphasis>
916    # <emphasis role="bold">shutdown -r now</emphasis>             
917    login: <emphasis role="bold">root</emphasis>
918    Password: <replaceable>root_password</replaceable>
919 </programlisting></para>
920                       </listitem>
921                     </orderedlist></para>
922                 </listitem>
923               </itemizedlist></para>
924           </listitem>
925         </orderedlist></para>
926
927       <indexterm>
928         <primary>configuring</primary>
929
930         <secondary>AFS server partition on first AFS machine</secondary>
931
932         <tertiary>HP-UX</tertiary>
933       </indexterm>
934
935       <indexterm>
936         <primary>AFS server partition</primary>
937
938         <secondary>configuring on first AFS machine</secondary>
939
940         <tertiary>HP-UX</tertiary>
941       </indexterm>
942
943       <indexterm>
944         <primary>first AFS machine</primary>
945
946         <secondary>AFS server partition</secondary>
947
948         <tertiary>on HP-UX</tertiary>
949       </indexterm>
950
951       <indexterm>
952         <primary>HP-UX</primary>
953
954         <secondary>AFS server partition</secondary>
955
956         <tertiary>on first AFS machine</tertiary>
957       </indexterm>
958     </sect2>
959
960     <sect2 id="HDRWQ33">
961       <title>Configuring Server Partitions on HP-UX Systems</title>
962
963       <para>Every AFS file server machine must have at least one partition or logical volume dedicated to storing AFS volumes. Each
964       server partition is mounted at a directory named <emphasis role="bold">/vicep</emphasis><replaceable>xx</replaceable>, where
965       <replaceable>xx</replaceable> is one or two lowercase letters. The <emphasis
966       role="bold">/vicep</emphasis><replaceable>xx</replaceable> directories must reside in the file server machine's root
967       directory, not in one of its subdirectories (for example, <emphasis role="bold">/usr/vicepa</emphasis> is not an acceptable
968       directory location). For additional information, see <link linkend="HDRWQ20">Performing Platform-Specific Procedures</link>.
969       <orderedlist>
970           <listitem>
971             <para>Create a directory called <emphasis role="bold">/vicep</emphasis><replaceable>xx</replaceable> for each AFS server
972             partition you are configuring (there must be at least one). Repeat the command for each partition. <programlisting>
973    # <emphasis role="bold">mkdir /vicep</emphasis><replaceable>xx</replaceable>
974 </programlisting></para>
975           </listitem>
976
977           <listitem>
978             <para>Use the <emphasis role="bold">SAM</emphasis> program to create a file system on each partition. For instructions,
979             consult the HP-UX documentation.</para>
980           </listitem>
981
982           <listitem>
983             <para>On some HP-UX systems that use logical volumes, the <emphasis role="bold">SAM</emphasis> program automatically
984             mounts the partitions. If it has not, mount each partition by issuing either the <emphasis role="bold">mount
985             -a</emphasis> command to mount all partitions at once or the <emphasis role="bold">mount</emphasis> command to mount
986             each partition in turn.</para>
987           </listitem>
988         </orderedlist></para>
989
990       <indexterm>
991         <primary>replacing fsck program</primary>
992
993         <secondary>first AFS machine</secondary>
994
995         <tertiary>HP-UX</tertiary>
996       </indexterm>
997
998       <indexterm>
999         <primary>fsck program</primary>
1000
1001         <secondary>on first AFS machine</secondary>
1002
1003         <tertiary>HP-UX</tertiary>
1004       </indexterm>
1005
1006       <indexterm>
1007         <primary>first AFS machine</primary>
1008
1009         <secondary>fsck program</secondary>
1010
1011         <tertiary>on HP-UX</tertiary>
1012       </indexterm>
1013
1014       <indexterm>
1015         <primary>HP-UX</primary>
1016
1017         <secondary>fsck program</secondary>
1018
1019         <tertiary>on first AFS machine</tertiary>
1020       </indexterm>
1021     </sect2>
1022
1023     <sect2 id="HDRWQ34">
1024       <title>Configuring the AFS-modified fsck Program on HP-UX Systems</title>
1025
1026       <para>In this section, you make modifications to guarantee that the appropriate <emphasis role="bold">fsck</emphasis> program
1027       runs on AFS server partitions. The <emphasis role="bold">fsck</emphasis> program provided with the operating system must never
1028       run on AFS server partitions. Because it does not recognize the structures that the File Server uses to organize volume data,
1029       it removes all of the data. To repeat:</para>
1030
1031       <para><emphasis role="bold">Never run the standard fsck program on AFS server partitions. It discards AFS
1032       volumes.</emphasis></para>
1033
1034       <para>On HP-UX systems, there are several configuration files to install in addition to the AFS-modified <emphasis
1035       role="bold">fsck</emphasis> program (the <emphasis role="bold">vfsck</emphasis> binary). <orderedlist>
1036           <listitem>
1037             <para>Create the command configuration file <emphasis role="bold">/sbin/lib/mfsconfig.d/afs</emphasis>. Use a text
1038             editor to place the indicated two lines in it: <programlisting>
1039    format_revision 1
1040    fsck            0        m,P,p,d,f,b:c:y,n,Y,N,q,
1041 </programlisting></para>
1042           </listitem>
1043
1044           <listitem>
1045             <para>Create and change directory to an AFS-specific command directory called <emphasis
1046             role="bold">/sbin/fs/afs</emphasis>. <programlisting>
1047    # <emphasis role="bold">mkdir /sbin/fs/afs</emphasis>
1048    # <emphasis role="bold">cd  /sbin/fs/afs</emphasis>
1049 </programlisting></para>
1050           </listitem>
1051
1052           <listitem>
1053             <para>Copy the AFS-modified version of the <emphasis role="bold">fsck</emphasis> program (the <emphasis
1054             role="bold">vfsck</emphasis> binary) and related files from the distribution directory to the new AFS-specific command
1055             directory. <programlisting>
1056    # <emphasis role="bold">cp -p /tmp/afsdist/hp_ux110/root.server/etc/*  .</emphasis>
1057 </programlisting></para>
1058           </listitem>
1059
1060           <listitem>
1061             <para>Change the <emphasis role="bold">vfsck</emphasis> binary's name to <emphasis role="bold">fsck</emphasis> and set
1062             the mode bits appropriately on all of the files in the <emphasis role="bold">/sbin/fs/afs</emphasis> directory.
1063             <programlisting>
1064    # <emphasis role="bold">mv  vfsck  fsck</emphasis>
1065    # <emphasis role="bold">chmod  755  *</emphasis>
1066 </programlisting></para>
1067           </listitem>
1068
1069           <listitem>
1070             <para>Edit the <emphasis role="bold">/etc/fstab</emphasis> file, changing the file system type for each AFS server
1071             partition from <computeroutput>hfs</computeroutput> to <computeroutput>afs</computeroutput>. This ensures that the
1072             AFS-modified <emphasis role="bold">fsck</emphasis> program runs on the appropriate partitions.</para>
1073
1074             <para>The sixth line in the following example of an edited file shows an AFS server partition, <emphasis
1075             role="bold">/vicepa</emphasis>.</para>
1076
1077             <programlisting>
1078    /dev/vg00/lvol1 / hfs defaults 0 1
1079    /dev/vg00/lvol4 /opt hfs defaults 0 2
1080    /dev/vg00/lvol5 /tmp hfs defaults 0 2
1081    /dev/vg00/lvol6 /usr hfs defaults 0 2
1082    /dev/vg00/lvol8 /var hfs defaults 0 2
1083    /dev/vg00/lvol9 /vicepa afs defaults 0 2
1084    /dev/vg00/lvol7 /usr/vice/cache hfs defaults 0 2
1085 </programlisting>
1086           </listitem>
1087
1088           <listitem>
1089             <para>If you plan to retain client functionality on this machine after completing the installation, proceed to <link
1090             linkend="HDRWQ35">Enabling AFS Login on HP-UX Systems</link>. Otherwise, proceed to <link linkend="HDRWQ50">Starting the
1091             BOS Server</link>.</para>
1092           </listitem>
1093         </orderedlist></para>
1094
1095       <indexterm>
1096         <primary>enabling AFS login</primary>
1097
1098         <secondary>file server machine</secondary>
1099
1100         <tertiary>HP-UX</tertiary>
1101       </indexterm>
1102
1103       <indexterm>
1104         <primary>AFS login</primary>
1105
1106         <secondary>on file server machine</secondary>
1107
1108         <tertiary>HP-UX</tertiary>
1109       </indexterm>
1110
1111       <indexterm>
1112         <primary>first AFS machine</primary>
1113
1114         <secondary>AFS login</secondary>
1115
1116         <tertiary>on HP-UX</tertiary>
1117       </indexterm>
1118
1119       <indexterm>
1120         <primary>HP-UX</primary>
1121
1122         <secondary>AFS login</secondary>
1123
1124         <tertiary>on file server machine</tertiary>
1125       </indexterm>
1126
1127       <indexterm>
1128         <primary>PAM</primary>
1129
1130         <secondary>on HP-UX</secondary>
1131
1132         <tertiary>file server machine</tertiary>
1133       </indexterm>
1134
1135       <indexterm>
1136         <primary>Pluggable Authentication Module</primary>
1137
1138         <see>PAM</see>
1139       </indexterm>
1140     </sect2>
1141
1142     <sect2 id="HDRWQ35">
1143       <title>Enabling AFS Login on HP-UX Systems</title>
1144
1145       <note><para>If you plan to remove client functionality from this machine after completing the installation, skip this section and proceed to <link linkend="HDRWQ50">Starting the BOS Server</link>.</para></note>
1146
1147       <para>At this point you incorporate AFS into the operating system's
1148       Pluggable Authentication Module (PAM) scheme. PAM integrates all
1149       authentication mechanisms on the machine, including login, to
1150       provide the security infrastructure for authenticated access to and
1151       from the machine.</para>
1152
1153       <para>In modern AFS installations, you should be using Kerberos v5
1154       for user login, and obtaining AFS tokens subsequent to this
1155       authentication step. OpenAFS does not currently distribute a PAM
1156       module allowing AFS tokens to be automatically gained at
1157       login. Whilst there are a number of third party modules providing
1158       this functionality, it is not know if these have been tested with
1159       HP/UX.</para>
1160       
1161       <para>Following login, users can obtain tokens by running the
1162       <emphasis role="bold">aklog</emphasis> command</para>
1163
1164       <para>Sites which still require <emphasis
1165       role="bold">kaserver</emphasis> or external Kerberos v4
1166       authentication should consult <link linkend="KAS013">Enabling
1167       kaserver based AFS login on HP-UX systems</link> for details of how
1168       to enable HP-UX login.</para>
1169
1170       <para>Proceed to <link linkend="HDRWQ50">Starting the BOS
1171       Server</link> (or if referring to these instructions while
1172       installing an additional file server machine, return to <link
1173       linkend="HDRWQ108">Starting Server Programs</link>).</para>
1174     </sect2>
1175   </sect1>
1176
1177   <sect1 id="HDRWQ36">
1178     <title>Getting Started on IRIX Systems</title>
1179
1180     <indexterm>
1181       <primary>incorporating AFS kernel extensions</primary>
1182
1183       <secondary>first AFS machine</secondary>
1184
1185       <tertiary>IRIX</tertiary>
1186     </indexterm>
1187
1188     <indexterm>
1189       <primary>AFS kernel extensions</primary>
1190
1191       <secondary>on first AFS machine</secondary>
1192
1193       <tertiary>IRIX</tertiary>
1194     </indexterm>
1195
1196     <indexterm>
1197       <primary>first AFS machine</primary>
1198
1199       <secondary>AFS kernel extensions</secondary>
1200
1201       <tertiary>on IRIX</tertiary>
1202     </indexterm>
1203
1204     <indexterm>
1205       <primary>replacing fsck program</primary>
1206
1207       <secondary>not necessary on IRIX</secondary>
1208     </indexterm>
1209
1210     <indexterm>
1211       <primary>fsck program</primary>
1212
1213       <secondary>on first AFS machine</secondary>
1214
1215       <tertiary>IRIX</tertiary>
1216     </indexterm>
1217
1218     <indexterm>
1219       <primary>first AFS machine</primary>
1220
1221       <secondary>fsck program</secondary>
1222
1223       <tertiary>on IRIX</tertiary>
1224     </indexterm>
1225
1226     <indexterm>
1227       <primary>IRIX</primary>
1228
1229       <secondary>fsck program replacement not necessary</secondary>
1230     </indexterm>
1231
1232     <para>To incorporate AFS into the kernel on IRIX systems, choose one of two methods: <itemizedlist>
1233         <listitem>
1234           <para>Run the AFS initialization script to invoke the <emphasis role="bold">ml</emphasis> program distributed by Silicon
1235           Graphics, Incorporated (SGI), which dynamically loads AFS modifications into the kernel</para>
1236         </listitem>
1237
1238         <listitem>
1239           <para>Build a new static kernel</para>
1240         </listitem>
1241       </itemizedlist></para>
1242
1243     <para>Then create partitions for storing AFS volumes. You do not need to replace the IRIX <emphasis role="bold">fsck</emphasis>
1244     program because SGI has already modified it to handle AFS volumes properly. If the machine is to remain an AFS client machine,
1245     verify that the IRIX login utility installed on the machine grants an AFS token.</para>
1246
1247     <para>In preparation for either dynamic loading or kernel building, perform the following procedures: <orderedlist>
1248         <listitem>
1249           <para>Unpack the OpenAFS IRIX distribution tarball. The examples
1250           below assume that you have unpacked the files into the 
1251           <emphasis role="bold">/tmp/afsdist</emphasis> directory. If you
1252           pick a different location, substitue this in all of the following
1253           examples. Once you have unpacked the distribution, change directory
1254           as indicated.
1255 <programlisting>
1256    # <emphasis role="bold">cd  /tmp/afsdist/sgi_65/root.client</emphasis>
1257 </programlisting></para>
1258         </listitem>
1259
1260         <listitem>
1261           <para>Copy the AFS initialization script to the local directory for initialization files (by convention, <emphasis
1262           role="bold">/etc/init.d</emphasis> on IRIX machines). Note the removal of the <emphasis role="bold">.rc</emphasis>
1263           extension as you copy the script. <programlisting>
1264    # <emphasis role="bold">cp -p   usr/vice/etc/afs.rc  /etc/init.d/afs</emphasis>
1265 </programlisting></para>
1266         </listitem>
1267
1268         <listitem>
1269           <para>Issue the <emphasis role="bold">uname -m</emphasis> command to determine the machine's CPU board type. The <emphasis
1270           role="bold">IP</emphasis><replaceable>xx</replaceable> value in the output must match one of the supported CPU board types
1271           listed in the <emphasis>OpenAFS Release Notes</emphasis> for the current version of AFS. <programlisting>
1272    # <emphasis role="bold">uname -m</emphasis>
1273 </programlisting></para>
1274         </listitem>
1275
1276         <listitem>
1277           <para>Proceed to either <link linkend="HDRWQ37">Loading AFS into the IRIX Kernel</link> or <link
1278           linkend="HDRWQ38">Building AFS into the IRIX Kernel</link>.</para>
1279         </listitem>
1280       </orderedlist></para>
1281
1282     <indexterm>
1283       <primary>IRIX</primary>
1284
1285       <secondary>AFS kernel extensions</secondary>
1286
1287       <tertiary>on first AFS machine</tertiary>
1288     </indexterm>
1289
1290     <indexterm>
1291       <primary>afsml variable (IRIX)</primary>
1292
1293       <secondary>first AFS machine</secondary>
1294     </indexterm>
1295
1296     <indexterm>
1297       <primary>variables</primary>
1298
1299       <secondary>afsml (IRIX)</secondary>
1300
1301       <tertiary>first AFS machine</tertiary>
1302     </indexterm>
1303
1304     <indexterm>
1305       <primary>IRIX</primary>
1306
1307       <secondary>afsml variable</secondary>
1308
1309       <tertiary>first AFS machine</tertiary>
1310     </indexterm>
1311
1312     <indexterm>
1313       <primary>afsxnfs variable (IRIX)</primary>
1314
1315       <secondary>first AFS machine</secondary>
1316     </indexterm>
1317
1318     <indexterm>
1319       <primary>variables</primary>
1320
1321       <secondary>afsxnfs (IRIX)</secondary>
1322
1323       <tertiary>first AFS machine</tertiary>
1324     </indexterm>
1325
1326     <indexterm>
1327       <primary>IRIX</primary>
1328
1329       <secondary>afsxnfs variable</secondary>
1330
1331       <tertiary>first AFS machine</tertiary>
1332     </indexterm>
1333
1334     <sect2 id="HDRWQ37">
1335       <title>Loading AFS into the IRIX Kernel</title>
1336
1337       <para>The <emphasis role="bold">ml</emphasis> program is the dynamic kernel loader provided by SGI for IRIX systems. If you
1338       use it rather than building AFS modifications into a static kernel, then for AFS to function correctly the <emphasis
1339       role="bold">ml</emphasis> program must run each time the machine reboots. Therefore, the AFS initialization script (included
1340       on the AFS CD-ROM) invokes it automatically when the <emphasis role="bold">afsml</emphasis> configuration variable is
1341       activated. In this section you activate the variable and run the script.</para>
1342
1343       <para>In later sections you verify that the script correctly initializes all AFS components, then create the links that
1344       incorporate AFS into the IRIX startup and shutdown sequence. <orderedlist>
1345           <listitem>
1346             <para>Create the local <emphasis role="bold">/usr/vice/etc/sgiload</emphasis> directory to house the AFS kernel library
1347             file. <programlisting>
1348    # <emphasis role="bold">mkdir /usr/vice/etc/sgiload</emphasis>
1349 </programlisting></para>
1350           </listitem>
1351
1352           <listitem>
1353             <para>Copy the appropriate AFS kernel library file to the <emphasis role="bold">/usr/vice/etc/sgiload</emphasis>
1354             directory. The <emphasis role="bold">IP</emphasis><replaceable>xx</replaceable> portion of the library file name must
1355             match the value previously returned by the <emphasis role="bold">uname -m</emphasis> command. Also choose the file
1356             appropriate to whether the machine's kernel supports NFS server functionality (NFS must be supported for the machine to
1357             act as an NFS/AFS Translator). Single- and multiprocessor machines use the same library file.</para>
1358
1359             <para>(You can choose to copy all of the kernel library files into the <emphasis
1360             role="bold">/usr/vice/etc/sgiload</emphasis> directory, but they require a significant amount of space.)</para>
1361
1362             <para>If the machine's kernel supports NFS server functionality:</para>
1363
1364             <programlisting>
1365    # <emphasis role="bold">cp -p  usr/vice/etc/sgiload/libafs.IP</emphasis><replaceable>xx</replaceable><emphasis role="bold">.o  /usr/vice/etc/sgiload</emphasis>   
1366 </programlisting>
1367
1368             <para>If the machine's kernel does not support NFS server functionality:</para>
1369
1370             <programlisting>
1371    # <emphasis role="bold">cp -p  usr/vice/etc/sgiload/libafs.IP</emphasis><replaceable>xx</replaceable><emphasis role="bold">.nonfs.o</emphasis>   \
1372                    <emphasis role="bold">/usr/vice/etc/sgiload</emphasis>
1373 </programlisting>
1374           </listitem>
1375
1376           <listitem>
1377             <para>Issue the <emphasis role="bold">chkconfig</emphasis> command to activate the <emphasis
1378             role="bold">afsml</emphasis> configuration variable. <programlisting>
1379    # <emphasis role="bold">/etc/chkconfig -f afsml on</emphasis>   
1380 </programlisting></para>
1381
1382             <para>If the machine is to function as an NFS/AFS Translator and the kernel supports NFS server functionality, activate
1383             the <emphasis role="bold">afsxnfs</emphasis> variable.</para>
1384
1385             <programlisting>
1386    # <emphasis role="bold">/etc/chkconfig -f afsxnfs on</emphasis>
1387 </programlisting>
1388           </listitem>
1389
1390           <listitem>
1391             <para>Run the <emphasis role="bold">/etc/init.d/afs</emphasis> script to load AFS extensions into the kernel. The script
1392             invokes the <emphasis role="bold">ml</emphasis> command, automatically determining which kernel library file to use
1393             based on this machine's CPU type and the activation state of the <emphasis role="bold">afsxnfs</emphasis>
1394             variable.</para>
1395
1396             <para>You can ignore any error messages about the inability to start the BOS Server or the Cache Manager or AFS
1397             client.</para>
1398
1399             <programlisting>
1400    # <emphasis role="bold">/etc/init.d/afs start</emphasis>
1401 </programlisting>
1402           </listitem>
1403
1404           <listitem>
1405             <para>Proceed to <link linkend="HDRWQ39">Configuring Server Partitions on IRIX Systems</link>.</para>
1406           </listitem>
1407         </orderedlist></para>
1408
1409       <indexterm>
1410         <primary>IRIX</primary>
1411
1412         <secondary>AFS-modified kernel</secondary>
1413
1414         <tertiary>on first AFS machine</tertiary>
1415       </indexterm>
1416     </sect2>
1417
1418     <sect2 id="HDRWQ38">
1419       <title>Building AFS into the IRIX Kernel</title>
1420
1421       <para>Use the following instructions to build AFS modifications into the kernel on an IRIX system. <orderedlist>
1422           <listitem>
1423             <para>Copy the kernel initialization file <emphasis role="bold">afs.sm</emphasis> to the local <emphasis
1424             role="bold">/var/sysgen/system</emphasis> directory, and the kernel master file <emphasis role="bold">afs</emphasis> to
1425             the local <emphasis role="bold">/var/sysgen/master.d</emphasis> directory. <programlisting>
1426    # <emphasis role="bold">cp -p  bin/afs.sm  /var/sysgen/system</emphasis>
1427    # <emphasis role="bold">cp -p  bin/afs  /var/sysgen/master.d</emphasis>
1428 </programlisting></para>
1429           </listitem>
1430
1431           <listitem>
1432             <para>Copy the appropriate AFS kernel library file to the local file <emphasis
1433             role="bold">/var/sysgen/boot/afs.a</emphasis>; the <emphasis role="bold">IP</emphasis><replaceable>xx</replaceable>
1434             portion of the library file name must match the value previously returned by the <emphasis role="bold">uname
1435             -m</emphasis> command. Also choose the file appropriate to whether the machine's kernel supports NFS server
1436             functionality (NFS must be supported for the machine to act as an NFS/AFS Translator). Single- and multiprocessor
1437             machines use the same library file.</para>
1438
1439             <para>If the machine's kernel supports NFS server functionality:</para>
1440
1441             <programlisting>
1442    # <emphasis role="bold">cp -p   bin/libafs.IP</emphasis><replaceable>xx</replaceable><emphasis role="bold">.a   /var/sysgen/boot/afs.a</emphasis>   
1443 </programlisting>
1444
1445             <para>If the machine's kernel does not support NFS server functionality:</para>
1446
1447             <programlisting>
1448    # <emphasis role="bold">cp -p  bin/libafs.IP</emphasis><replaceable>xx</replaceable><emphasis role="bold">.nonfs.a  /var/sysgen/boot/afs.a</emphasis>
1449 </programlisting>
1450           </listitem>
1451
1452           <listitem>
1453             <para>Issue the <emphasis role="bold">chkconfig</emphasis> command to deactivate the <emphasis
1454             role="bold">afsml</emphasis> configuration variable. <programlisting>
1455    # <emphasis role="bold">/etc/chkconfig -f afsml off</emphasis>   
1456 </programlisting></para>
1457
1458             <para>If the machine is to function as an NFS/AFS Translator and the kernel supports NFS server functionality, activate
1459             the <emphasis role="bold">afsxnfs</emphasis> variable.</para>
1460
1461             <programlisting>
1462    # <emphasis role="bold">/etc/chkconfig -f afsxnfs on</emphasis>
1463 </programlisting>
1464           </listitem>
1465
1466           <listitem>
1467             <para>Copy the existing kernel file, <emphasis role="bold">/unix</emphasis>, to a safe location. Compile the new kernel,
1468             which is created in the file <emphasis role="bold">/unix.install</emphasis>. It overwrites the existing <emphasis
1469             role="bold">/unix</emphasis> file when the machine reboots in the next step. <programlisting>
1470    # <emphasis role="bold">cp /unix /unix_noafs</emphasis>
1471    # <emphasis role="bold">autoconfig</emphasis>
1472 </programlisting></para>
1473           </listitem>
1474
1475           <listitem>
1476             <para>Reboot the machine to start using the new kernel, and login again as the superuser <emphasis
1477             role="bold">root</emphasis>. <programlisting>
1478    # <emphasis role="bold">cd /</emphasis>
1479    # <emphasis role="bold">shutdown -i6 -g0 -y</emphasis>
1480    login: <emphasis role="bold">root</emphasis>
1481    Password: <replaceable>root_password</replaceable>
1482 </programlisting></para>
1483           </listitem>
1484         </orderedlist></para>
1485
1486       <indexterm>
1487         <primary>configuring</primary>
1488
1489         <secondary>AFS server partition on first AFS machine</secondary>
1490
1491         <tertiary>IRIX</tertiary>
1492       </indexterm>
1493
1494       <indexterm>
1495         <primary>AFS server partition</primary>
1496
1497         <secondary>configuring on first AFS machine</secondary>
1498
1499         <tertiary>IRIX</tertiary>
1500       </indexterm>
1501
1502       <indexterm>
1503         <primary>first AFS machine</primary>
1504
1505         <secondary>AFS server partition</secondary>
1506
1507         <tertiary>on IRIX</tertiary>
1508       </indexterm>
1509
1510       <indexterm>
1511         <primary>IRIX</primary>
1512
1513         <secondary>AFS server partition</secondary>
1514
1515         <tertiary>on first AFS machine</tertiary>
1516       </indexterm>
1517     </sect2>
1518
1519     <sect2 id="HDRWQ39">
1520       <title>Configuring Server Partitions on IRIX Systems</title>
1521
1522       <para>Every AFS file server machine must have at least one partition or logical volume dedicated to storing AFS volumes. Each
1523       server partition is mounted at a directory named <emphasis role="bold">/vicep</emphasis><replaceable>xx</replaceable>, where
1524       <replaceable>xx</replaceable> is one or two lowercase letters. The <emphasis
1525       role="bold">/vicep</emphasis><replaceable>xx</replaceable> directories must reside in the file server machine's root
1526       directory, not in one of its subdirectories (for example, <emphasis role="bold">/usr/vicepa</emphasis> is not an acceptable
1527       directory location). For additional information, see <link linkend="HDRWQ20">Performing Platform-Specific
1528       Procedures</link>.</para>
1529
1530       <para>AFS supports use of both EFS and XFS partitions for housing AFS volumes. SGI encourages use of XFS partitions.
1531       <orderedlist>
1532           <listitem>
1533             <para>Create a directory called <emphasis role="bold">/vicep</emphasis><replaceable>xx</replaceable> for each AFS server
1534             partition you are configuring (there must be at least one). Repeat the command for each partition. <programlisting>
1535    # <emphasis role="bold">mkdir /vicep</emphasis><replaceable>xx</replaceable>
1536 </programlisting></para>
1537           </listitem>
1538
1539           <listitem>
1540             <para>Add a line with the following format to the file systems registry file, <emphasis
1541             role="bold">/etc/fstab</emphasis>, for each partition (or logical volume created with the XLV volume manager) to be
1542             mounted on one of the directories created in the previous step.</para>
1543
1544             <para>For an XFS partition or logical volume:</para>
1545
1546             <programlisting>
1547    /dev/dsk/<replaceable>disk</replaceable>  /vicep<replaceable>xx</replaceable>  xfs  rw,raw=/dev/rdsk/<replaceable>disk</replaceable>  0  0   
1548 </programlisting>
1549
1550             <para>For an EFS partition:</para>
1551
1552             <programlisting>
1553    /dev/dsk/<replaceable>disk</replaceable>  /vicep<replaceable>xx</replaceable>  efs  rw,raw=/dev/rdsk/<replaceable>disk</replaceable>  0  0   
1554 </programlisting>
1555
1556             <para>The following are examples of an entry for each file system type:</para>
1557
1558             <programlisting>
1559    /dev/dsk/dks0d2s6 /vicepa  xfs rw,raw=/dev/rdsk/dks0d2s6  0 0
1560    /dev/dsk/dks0d3s1 /vicepb  efs rw,raw=/dev/rdsk/dks0d3s1  0 0
1561 </programlisting>
1562           </listitem>
1563
1564           <listitem>
1565             <para>Create a file system on each partition that is to be mounted on a <emphasis
1566             role="bold">/vicep</emphasis><replaceable>xx</replaceable> directory. The following commands are probably appropriate,
1567             but consult the IRIX documentation for more information. In both cases, <replaceable>raw_device</replaceable> is a raw
1568             device name like <emphasis role="bold">/dev/rdsk/dks0d0s0</emphasis> for a single disk partition or <emphasis
1569             role="bold">/dev/rxlv/xlv0</emphasis> for a logical volume.</para>
1570
1571             <para>For XFS file systems, include the indicated options to configure the partition or logical volume with inodes large
1572             enough to accommodate AFS-specific information:</para>
1573
1574             <programlisting>
1575    # <emphasis role="bold">mkfs -t xfs -i size=512 -l size=4000b</emphasis> <replaceable>raw_device</replaceable>   
1576 </programlisting>
1577
1578             <para>For EFS file systems:</para>
1579
1580             <programlisting>
1581    # <emphasis role="bold">mkfs -t efs</emphasis> <replaceable>raw_device</replaceable>
1582 </programlisting>
1583           </listitem>
1584
1585           <listitem>
1586             <para>Mount each partition by issuing either the <emphasis role="bold">mount -a</emphasis> command to mount all
1587             partitions at once or the <emphasis role="bold">mount</emphasis> command to mount each partition in turn.</para>
1588           </listitem>
1589
1590           <listitem>
1591             <para><emphasis role="bold">(Optional)</emphasis> If you have configured partitions or logical volumes to use XFS, issue
1592             the following command to verify that the inodes are configured properly (are large enough to accommodate AFS-specific
1593             information). If the configuration is correct, the command returns no output. Otherwise, it specifies the command to run
1594             in order to configure each partition or logical volume properly. <programlisting>
1595    # <emphasis role="bold">/usr/afs/bin/xfs_size_check</emphasis>
1596 </programlisting></para>
1597           </listitem>
1598
1599           <listitem>
1600             <para>If you plan to retain client functionality on this machine after completing the installation, proceed to <link
1601             linkend="HDRWQ40">Enabling AFS Login on IRIX Systems</link>. Otherwise, proceed to <link linkend="HDRWQ50">Starting the
1602             BOS Server</link>.</para>
1603           </listitem>
1604         </orderedlist></para>
1605
1606       <indexterm>
1607         <primary>enabling AFS login</primary>
1608
1609         <secondary>file server machine</secondary>
1610
1611         <tertiary>IRIX</tertiary>
1612       </indexterm>
1613
1614       <indexterm>
1615         <primary>AFS login</primary>
1616
1617         <secondary>on file server machine</secondary>
1618
1619         <tertiary>IRIX</tertiary>
1620       </indexterm>
1621
1622       <indexterm>
1623         <primary>first AFS machine</primary>
1624
1625         <secondary>AFS login</secondary>
1626
1627         <tertiary>on IRIX</tertiary>
1628       </indexterm>
1629
1630       <indexterm>
1631         <primary>IRIX</primary>
1632
1633         <secondary>AFS login</secondary>
1634       </indexterm>
1635     </sect2>
1636
1637     <sect2 id="HDRWQ40">
1638       <title>Enabling AFS Login on IRIX Systems</title>
1639
1640       <note>
1641         <para>If you plan to remove client functionality from this machine after completing the installation, skip this section and
1642         proceed to <link linkend="HDRWQ50">Starting the BOS Server</link>.</para>
1643       </note>
1644
1645       <para>Whilst the standard IRIX command-line 
1646       <emphasis role="bold">login</emphasis> program and the 
1647       graphical <emphasis role="bold">xdm</emphasis> login program both have
1648       the ability to grant AFS tokens, this ability relies upon the deprecated
1649       kaserver authentication system.</para>
1650         
1651       <para>Users who have been successfully authenticated via Kerberos 5
1652       authentication may obtain AFS tokens following login by running the
1653       <emphasis role="bold">aklog</emphasis> command.</para>
1654
1655       <para>Sites which still require <emphasis role="bold">kaserver</emphasis>
1656       or external Kerberos v4 authentication should consult 
1657       <link linkend="KAS014">Enabling kaserver based AFS Login on IRIX Systems</link>
1658       for details of how to enable IRIX login.</para>       
1659
1660       <para>After taking any necessary action, proceed to 
1661       <link linkend="HDRWQ50">Starting the BOS Server</link>.</para>
1662     </sect2>
1663   </sect1>
1664
1665   <sect1 id="HDRWQ41">
1666     <title>Getting Started on Linux Systems</title>
1667
1668     <indexterm>
1669       <primary>replacing fsck program</primary>
1670
1671       <secondary>not necessary on Linux</secondary>
1672     </indexterm>
1673
1674     <indexterm>
1675       <primary>fsck program</primary>
1676
1677       <secondary>on first AFS machine</secondary>
1678
1679       <tertiary>Linux</tertiary>
1680     </indexterm>
1681
1682     <indexterm>
1683       <primary>first AFS machine</primary>
1684
1685       <secondary>fsck program</secondary>
1686
1687       <tertiary>on Linux</tertiary>
1688     </indexterm>
1689
1690     <indexterm>
1691       <primary>Linux</primary>
1692
1693       <secondary>fsck program replacement not necessary</secondary>
1694     </indexterm>
1695
1696     <para>Since this guide was originally written, the procedure for starting 
1697     OpenAFS has diverged significantly between different Linux distributions. 
1698     The instructions that follow are appropriate for both the Fedora and 
1699     RedHat Enterprise Linux packages distributed by OpenAFS. Additional 
1700     instructions are provided for those building from source.</para>
1701
1702     <para>Begin by running the AFS client startup scripts, which call the
1703     <emphasis role="bold">modprobe</emphasis> program to dynamically
1704     load the AFS modifications into the kernel. Then create partitions for
1705     storing AFS volumes. You do not need to replace the Linux <emphasis
1706     role="bold">fsck</emphasis> program. If the machine is to remain an
1707     AFS client machine, incorporate AFS into the machine's Pluggable
1708     Authentication Module (PAM) scheme. <indexterm>
1709         <primary>incorporating AFS kernel extensions</primary>
1710
1711         <secondary>first AFS machine</secondary>
1712
1713         <tertiary>Linux</tertiary>
1714       </indexterm> <indexterm>
1715         <primary>AFS kernel extensions</primary>
1716
1717         <secondary>on first AFS machine</secondary>
1718
1719         <tertiary>Linux</tertiary>
1720       </indexterm> <indexterm>
1721         <primary>first AFS machine</primary>
1722
1723         <secondary>AFS kernel extensions</secondary>
1724
1725         <tertiary>on Linux</tertiary>
1726       </indexterm> <indexterm>
1727         <primary>Linux</primary>
1728
1729         <secondary>AFS kernel extensions</secondary>
1730
1731         <tertiary>on first AFS machine</tertiary>
1732       </indexterm></para>
1733
1734     <sect2 id="HDRWQ42">
1735       <title>Loading AFS into the Linux Kernel</title>
1736
1737       <para>The <emphasis role="bold">modprobe</emphasis> program is the dynamic kernel loader for Linux. Linux does not support
1738       incorporation of AFS modifications during a kernel build.</para>
1739
1740       <para>For AFS to function correctly, the <emphasis role="bold">modprobe</emphasis> program must run each time the machine
1741       reboots, so your distribution's AFS initialization script invokes it automatically. The script also includes
1742       commands that select the appropriate AFS library file automatically. In this section you run the script.</para>
1743
1744       <para>In later sections you verify that the script correctly initializes all AFS components, then activate a configuration
1745       variable, which results in the script being incorporated into the Linux startup and shutdown sequence.</para> 
1746       
1747       <para>The procedure for starting up OpenAFS depends upon your distribution</para>
1748       <sect3>
1749         <title>Fedora and RedHat Enterprise Linux</title>
1750         <para>OpenAFS provides RPMS for all current Fedora and RedHat Enterprise Linux (RHEL) releases on the OpenAFS web site and the OpenAFS yum repository.
1751         <orderedlist>
1752           <listitem>
1753             <para>Browse to
1754             http://dl.openafs.org/dl/openafs/<replaceable>VERSION</replaceable>,
1755             where VERSION is the latest stable release of
1756             OpenAFS. Download the
1757             openafs-repository-<replaceable>VERSION</replaceable>.noarch.rpm
1758             file for Fedora systems or the
1759             openafs-repository-rhel-<replaceable>VERSION</replaceable>.noarch.rpm
1760             file for RedHat-based systems.
1761             </para>
1762           </listitem>
1763           <listitem>
1764             <para>Install the downloaded RPM file using the following command:
1765               <programlisting>
1766                 # rpm -U openafs-repository*.rpm
1767               </programlisting>
1768             </para>
1769           </listitem>
1770           <listitem>
1771             <para>Install the RPM set for your operating system using the yum command as follows:
1772               <programlisting>
1773                 # yum -y install openafs-client openafs-server openafs-krb5 kmod-openafs
1774               </programlisting>
1775
1776             </para>
1777             <para>Alternatively, you may use dynamically-compiled kernel
1778               modules if you have the kernel headers, a compiler, and the
1779               dkms package from
1780               <ulink url="http://fedoraproject.org/wiki/EPEL"><citetitle>EPEL</citetitle></ulink> installed. 
1781
1782             </para>
1783             <para>To use dynamically-compiled kernel modules instead of statically compiled modules, use the following command instead of the kmod-openafs as shown above:
1784               <programlisting>
1785                 # yum install openafs-client openafs-server openafs-krb5 dkms-openafs
1786               </programlisting>
1787             </para>
1788           </listitem>
1789 <!-- If you do this with current RHEL and Fedora releases you end up with
1790      a dynroot'd client running - this breaks setting up the root.afs volume
1791      as described later in this guide
1792           <listitem>
1793             <para>Run the AFS initialization script to load AFS extensions into 
1794             the kernel. You can ignore any error messages about the inability 
1795             to start the BOS Server or the Cache Manager or AFS client.</para>
1796 <programlisting>
1797    # <emphasis role="bold">/etc/rc.d/init.d/openafs-client  start</emphasis>
1798 </programlisting>
1799           </listitem>
1800 -->
1801         </orderedlist>
1802       </para>
1803       </sect3>
1804       <sect3>
1805          <title>Systems packaged as tar files</title>
1806          <para>If you are running a system where the OpenAFS Binary Distribution
1807          is provided as a tar file, or where you have built the system from
1808          source yourself, you need to install the relevant components by hand
1809          </para>
1810          <orderedlist>
1811            
1812           <listitem>
1813             <para>Unpack the distribution tarball. The examples below assume
1814             that you have unpacked the files into the
1815             <emphasis role="bold">/tmp/afsdist</emphasis> directory. If you
1816             pick a different location, substitute this in all of the following
1817             examples. Once you have unpacked the distribution,
1818             change directory as indicated.
1819 <programlisting>
1820   # <emphasis role="bold">cd /tmp/afsdist/linux/root.client/usr/vice/etc</emphasis>
1821 </programlisting></para>
1822           </listitem>
1823           
1824           <listitem>
1825             <para>Copy the AFS kernel library files to the local <emphasis role="bold">/usr/vice/etc/modload</emphasis> directory.
1826             The filenames for the libraries have the format <emphasis
1827             role="bold">libafs-</emphasis><replaceable>version</replaceable><emphasis role="bold">.o</emphasis>, where
1828             <replaceable>version</replaceable> indicates the kernel build level. The string <emphasis role="bold">.mp</emphasis> in
1829             the <replaceable>version</replaceable> indicates that the file is appropriate for machines running a multiprocessor
1830             kernel. <programlisting>
1831    # <emphasis role="bold">cp -rp  modload  /usr/vice/etc</emphasis>
1832 </programlisting></para>
1833           </listitem>
1834
1835           <listitem>
1836             <para>Copy the AFS initialization script to the local directory for initialization files (by convention, <emphasis
1837             role="bold">/etc/rc.d/init.d</emphasis> on Linux machines). Note the removal of the <emphasis role="bold">.rc</emphasis>
1838             extension as you copy the script. <programlisting>
1839    # <emphasis role="bold">cp -p   afs.rc  /etc/rc.d/init.d/afs</emphasis> 
1840 </programlisting></para>
1841           </listitem>
1842
1843 <!-- I don't think we need to do this for Linux, and it complicates things if
1844      dynroot is enabled ...
1845           <listitem>
1846             <para>Run the AFS initialization script to load AFS extensions into the kernel. You can ignore any error messages about
1847             the inability to start the BOS Server or the Cache Manager or AFS client.</para>
1848 <programlisting>
1849    # <emphasis role="bold">/etc/rc.d/init.d/afs start</emphasis>
1850 </programlisting>
1851           </listitem>
1852 -->
1853         </orderedlist>
1854
1855       <indexterm>
1856         <primary>configuring</primary>
1857    
1858         <secondary>AFS server partition on first AFS machine</secondary>
1859
1860         <tertiary>Linux</tertiary>
1861       </indexterm>
1862
1863       <indexterm>
1864         <primary>AFS server partition</primary>
1865
1866         <secondary>configuring on first AFS machine</secondary>
1867
1868         <tertiary>Linux</tertiary>
1869       </indexterm>
1870
1871       <indexterm>
1872         <primary>first AFS machine</primary>
1873
1874         <secondary>AFS server partition</secondary>
1875
1876         <tertiary>on Linux</tertiary>
1877       </indexterm>
1878
1879       <indexterm>
1880         <primary>Linux</primary>
1881
1882         <secondary>AFS server partition</secondary>
1883
1884         <tertiary>on first AFS machine</tertiary>
1885       </indexterm>
1886     </sect3>
1887     </sect2>
1888
1889     <sect2 id="HDRWQ43">
1890       <title>Configuring Server Partitions on Linux Systems</title>
1891
1892       <para>Every AFS file server machine must have at least one partition or logical volume dedicated to storing AFS volumes. Each
1893       server partition is mounted at a directory named <emphasis role="bold">/vicep</emphasis><replaceable>xx</replaceable>, where
1894       <replaceable>xx</replaceable> is one or two lowercase letters. The <emphasis
1895       role="bold">/vicep</emphasis><replaceable>xx</replaceable> directories must reside in the file server machine's root
1896       directory, not in one of its subdirectories (for example, <emphasis role="bold">/usr/vicepa</emphasis> is not an acceptable
1897       directory location). For additional information, see <link linkend="HDRWQ20">Performing Platform-Specific Procedures</link>.
1898       <orderedlist>
1899           <listitem>
1900             <para>Create a directory called <emphasis role="bold">/vicep</emphasis><replaceable>xx</replaceable> for each AFS server
1901             partition you are configuring (there must be at least one). Repeat the command for each partition. <programlisting>
1902    # <emphasis role="bold">mkdir /vicep</emphasis><replaceable>xx</replaceable>
1903 </programlisting></para>
1904           </listitem>
1905
1906           <listitem>
1907             <para>Add a line with the following format to the file systems registry file, <emphasis
1908             role="bold">/etc/fstab</emphasis>, for each directory just created. The entry maps the directory name to the disk
1909             partition to be mounted on it. <programlisting>
1910    /dev/<replaceable>disk</replaceable>  /vicep<replaceable>xx</replaceable>  ext2  defaults  0  2   
1911 </programlisting></para>
1912
1913             <para>The following is an example for the first partition being configured.</para>
1914
1915             <programlisting>
1916    /dev/sda8 /vicepa ext2 defaults 0 2
1917 </programlisting>
1918           </listitem>
1919
1920           <listitem>
1921             <para>Create a file system on each partition that is to be mounted at a <emphasis
1922             role="bold">/vicep</emphasis><replaceable>xx</replaceable> directory. The following command is probably appropriate, but
1923             consult the Linux documentation for more information. <programlisting>
1924    # <emphasis role="bold">mkfs -v /dev/</emphasis><replaceable>disk</replaceable>
1925 </programlisting></para>
1926           </listitem>
1927
1928           <listitem>
1929             <para>Mount each partition by issuing either the <emphasis role="bold">mount -a</emphasis> command to mount all
1930             partitions at once or the <emphasis role="bold">mount</emphasis> command to mount each partition in turn.</para>
1931           </listitem>
1932
1933           <listitem>
1934             <para>If you plan to retain client functionality on this machine after completing the installation, proceed to <link
1935             linkend="HDRWQ44">Enabling AFS Login on Linux Systems</link>. Otherwise, proceed to <link linkend="HDRWQ50">Starting the
1936             BOS Server</link>.</para>
1937           </listitem>
1938         </orderedlist></para>
1939
1940       <indexterm>
1941         <primary>enabling AFS login</primary>
1942
1943         <secondary>file server machine</secondary>
1944
1945         <tertiary>Linux</tertiary>
1946       </indexterm>
1947
1948       <indexterm>
1949         <primary>AFS login</primary>
1950
1951         <secondary>on file server machine</secondary>
1952
1953         <tertiary>Linux</tertiary>
1954       </indexterm>
1955
1956       <indexterm>
1957         <primary>first AFS machine</primary>
1958
1959         <secondary>AFS login</secondary>
1960
1961         <tertiary>on Linux</tertiary>
1962       </indexterm>
1963
1964       <indexterm>
1965         <primary>Linux</primary>
1966
1967         <secondary>AFS login</secondary>
1968
1969         <tertiary>on file server machine</tertiary>
1970       </indexterm>
1971
1972       <indexterm>
1973         <primary>PAM</primary>
1974
1975         <secondary>on Linux</secondary>
1976
1977         <tertiary>file server machine</tertiary>
1978       </indexterm>
1979     </sect2>
1980
1981     <sect2 id="HDRWQ44">
1982       <title>Enabling AFS Login on Linux Systems</title>
1983
1984       <note>
1985         <para>If you plan to remove client functionality from this machine
1986         after completing the installation, skip this section and proceed
1987         to <link linkend="HDRWQ50">Starting the BOS Server</link>.</para>
1988       </note>
1989
1990       <para>At this point you incorporate AFS into the operating system's
1991       Pluggable Authentication Module (PAM) scheme.  PAM integrates all
1992       authentication mechanisms on the machine, including login, to provide
1993       the security infrastructure for authenticated access to and from the
1994       machine.</para>
1995
1996       <para>You should first configure your system to obtain Kerberos v5
1997       tickets as part of the authentication process, and then run an AFS PAM
1998       module to obtain tokens from those tickets after authentication.  Many
1999       Linux distributions come with a Kerberos v5 PAM module (usually called
2000       pam-krb5 or pam_krb5), or you can download and install <ulink
2001       url="http://www.eyrie.org/~eagle/software/pam-krb5">Russ Allbery's
2002       Kerberos v5 PAM module</ulink>, which is tested regularly with AFS.
2003       See the instructions of whatever PAM module you use for how to
2004       configure it.</para>
2005
2006       <para>Some Kerberos v5 PAM modules do come with native AFS support
2007       (usually requiring the Heimdal Kerberos implementation rather than the
2008       MIT Kerberos implementation).  If you are using one of those PAM
2009       modules, you can configure it to obtain AFS tokens.  It's more common,
2010       however, to separate the AFS token acquisition into a separate PAM
2011       module.</para>
2012
2013       <para>The recommended AFS PAM module is <ulink
2014       url="http://www.eyrie.org/~eagle/software/pam-afs-session/">Russ
2015       Allbery's pam-afs-session module</ulink>.  It should work with any of
2016       the Kerberos v5 PAM modules.  To add it to the PAM configuration, you
2017       often only need to add configuration to the session group:</para>
2018
2019       <example>
2020         <title>Linux PAM session example</title>
2021         <literallayout>session  required  pam_afs_session.so</literallayout>
2022       </example>
2023
2024       <para>If you also want to obtain AFS tokens for <command>scp</command>
2025       and similar commands that don't open a session, you will also need to
2026       add the AFS PAM module to the auth group so that the PAM
2027       <function>setcred</function> call will obtain tokens.  The
2028       <literal>pam_afs_session</literal> module will always return success
2029       for authentication so that it can be added to the auth group only for
2030       <function>setcred</function>, so make sure that it's not marked as
2031       <literal>sufficient</literal>.</para>
2032
2033       <example>
2034         <title>Linux PAM auth example</title>
2035 <literallayout>auth  [success=ok default=1]  pam_krb5.so
2036 auth  [default=done]          pam_afs_session.so
2037 auth  required                pam_unix.so try_first_pass</literallayout>
2038       </example>
2039
2040       <para>This example will work if you want to try Kerberos v5 first and
2041       then fall back to regular Unix authentication.
2042       <literal>success=ok</literal> for the Kerberos PAM module followed by
2043       <literal>default=done</literal> for the AFS PAM module will cause a
2044       successful Kerberos login to run the AFS PAM module and then skip the
2045       Unix authentication module.  <literal>default=1</literal> on the
2046       Kerberos PAM module causes failure of that module to skip the next
2047       module (the AFS PAM module) and fall back to the Unix module.  If you
2048       want to try Unix authentication first and rearrange the order, be sure
2049       to use <literal>default=die</literal> instead.</para>
2050
2051       <para>The PAM configuration is stored in different places in different
2052       Linux distributions.  On Red Hat, look in
2053       <filename>/etc/pam.d/system-auth</filename>.  On Debian and
2054       derivatives, look in <filename>/etc/pam.d/common-session</filename>
2055       and <filename>/etc/pam.d/common-auth</filename>.</para>
2056
2057       <para>For additional configuration examples and the configuration
2058       options of the AFS PAM module, see its documentation.  For more
2059       details on the available options for the PAM configuration, see the
2060       Linux PAM documentation.</para>
2061
2062       <para>Sites which still require <command>kaserver</command> or
2063       external Kerberos v4 authentication should consult <link
2064       linkend="KAS015">Enabling kaserver based AFS Login on Linux
2065       Systems</link> for details of how to enable AFS login on Linux.</para>
2066       
2067       <para>Proceed to <link linkend="HDRWQ50">Starting the BOS
2068       Server</link> (or if referring to these instructions while installing
2069       an additional file server machine, return to <link
2070       linkend="HDRWQ108">Starting Server Programs</link>).</para>
2071     </sect2>
2072   </sect1>
2073
2074   <sect1 id="HDRWQ45">
2075     <title>Getting Started on Solaris Systems</title>
2076
2077     <para>Begin by running the AFS initialization script to call the <emphasis role="bold">modload</emphasis> program distributed by
2078     Sun Microsystems, which dynamically loads AFS modifications into the kernel. Then create partitions for storing AFS volumes, and
2079     install and configure the AFS-modified <emphasis role="bold">fsck</emphasis> program to run on AFS server partitions. If the
2080     machine is to remain an AFS client machine, incorporate AFS into the machine's Pluggable Authentication Module (PAM) scheme.
2081     <indexterm>
2082         <primary>incorporating AFS kernel extensions</primary>
2083
2084         <secondary>first AFS machine</secondary>
2085
2086         <tertiary>Solaris</tertiary>
2087       </indexterm> <indexterm>
2088         <primary>AFS kernel extensions</primary>
2089
2090         <secondary>on first AFS machine</secondary>
2091
2092         <tertiary>Solaris</tertiary>
2093       </indexterm> <indexterm>
2094         <primary>first AFS machine</primary>
2095
2096         <secondary>AFS kernel extensions</secondary>
2097
2098         <tertiary>on Solaris</tertiary>
2099       </indexterm> <indexterm>
2100         <primary>Solaris</primary>
2101
2102         <secondary>AFS kernel extensions</secondary>
2103
2104         <tertiary>on first AFS machine</tertiary>
2105       </indexterm></para>
2106
2107     <sect2 id="HDRWQ46">
2108       <title>Loading AFS into the Solaris Kernel</title>
2109
2110       <para>The <emphasis role="bold">modload</emphasis> program is the dynamic kernel loader provided by Sun Microsystems for
2111       Solaris systems. Solaris does not support incorporation of AFS modifications during a kernel build.</para>
2112
2113       <para>For AFS to function correctly, the <emphasis role="bold">modload</emphasis> program must run each time the machine
2114       reboots, so the AFS initialization script (included on the AFS CD-ROM) invokes it automatically. In this section you copy the
2115       appropriate AFS library file to the location where the <emphasis role="bold">modload</emphasis> program accesses it and then
2116       run the script.</para>
2117
2118       <para>In later sections you verify that the script correctly initializes all AFS components, then create the links that
2119       incorporate AFS into the Solaris startup and shutdown sequence. <orderedlist>
2120           <listitem>
2121             <para>Unpack the OpenAFS Solaris distribution tarball. The examples
2122             below assume that you have unpacked the files into the 
2123             <emphasis role="bold">/tmp/afsdist</emphasis> directory. If you 
2124             pick a diferent location, substitute this in all of the following
2125             exmaples. Once you have unpacked the distribution, change directory
2126             as indicated. 
2127 <programlisting>
2128    # <emphasis role="bold">cd  /tmp/afsdist/sun4x_56/root.client/usr/vice/etc</emphasis>
2129 </programlisting></para>
2130           </listitem>
2131
2132           <listitem>
2133             <para>Copy the AFS initialization script to the local directory for initialization files (by convention, <emphasis
2134             role="bold">/etc/init.d</emphasis> on Solaris machines). Note the removal of the <emphasis role="bold">.rc</emphasis>
2135             extension as you copy the script. <programlisting>
2136    # <emphasis role="bold">cp -p  afs.rc  /etc/init.d/afs</emphasis>
2137 </programlisting></para>
2138           </listitem>
2139
2140           <listitem>
2141             <para>Copy the appropriate AFS kernel library file to the local file <emphasis
2142             role="bold">/kernel/fs/afs</emphasis>.</para>
2143
2144             <para>If the machine is running Solaris 2.6 or the 32-bit version of Solaris 7, its kernel supports NFS server
2145             functionality, and the <emphasis role="bold">nfsd</emphasis> process is running:</para>
2146
2147             <programlisting>
2148    # <emphasis role="bold">cp -p modload/libafs.o /kernel/fs/afs</emphasis>   
2149 </programlisting>
2150
2151             <para>If the machine is running Solaris 2.6 or the 32-bit version of Solaris 7, and its kernel does not support NFS
2152             server functionality or the <emphasis role="bold">nfsd</emphasis> process is not running:</para>
2153
2154             <programlisting>
2155    # <emphasis role="bold">cp -p modload/libafs.nonfs.o /kernel/fs/afs</emphasis>   
2156 </programlisting>
2157
2158             <para>If the machine is running the 64-bit version of Solaris 7, its kernel supports NFS server functionality, and the
2159             <emphasis role="bold">nfsd</emphasis> process is running:</para>
2160
2161             <programlisting>
2162    # <emphasis role="bold">cp -p modload/libafs64.o /kernel/fs/sparcv9/afs</emphasis>   
2163 </programlisting>
2164
2165             <para>If the machine is running the 64-bit version of Solaris 7, and its kernel does not support NFS server
2166             functionality or the <emphasis role="bold">nfsd</emphasis> process is not running:</para>
2167
2168             <programlisting>
2169    # <emphasis role="bold">cp -p modload/libafs64.nonfs.o /kernel/fs/sparcv9/afs</emphasis>
2170 </programlisting>
2171           </listitem>
2172
2173           <listitem>
2174             <para>Run the AFS initialization script to load AFS modifications into the kernel. You can ignore any error messages
2175             about the inability to start the BOS Server or the Cache Manager or AFS client. <programlisting>
2176    # <emphasis role="bold">/etc/init.d/afs start</emphasis>   
2177 </programlisting></para>
2178
2179             <para>When an entry called <computeroutput>afs</computeroutput> does not already exist in the local <emphasis
2180             role="bold">/etc/name_to_sysnum</emphasis> file, the script automatically creates it and reboots the machine to start
2181             using the new version of the file. If this happens, log in again as the superuser <emphasis role="bold">root</emphasis>
2182             after the reboot and run the initialization script again. This time the required entry exists in the <emphasis
2183             role="bold">/etc/name_to_sysnum</emphasis> file, and the <emphasis role="bold">modload</emphasis> program runs.</para>
2184
2185             <programlisting>
2186    login: <emphasis role="bold">root</emphasis>
2187    Password: <replaceable>root_password</replaceable>
2188    # <emphasis role="bold">/etc/init.d/afs start</emphasis>
2189 </programlisting>
2190           </listitem>
2191         </orderedlist></para>
2192
2193       <indexterm>
2194         <primary>replacing fsck program</primary>
2195
2196         <secondary>first AFS machine</secondary>
2197
2198         <tertiary>Solaris</tertiary>
2199       </indexterm>
2200
2201       <indexterm>
2202         <primary>fsck program</primary>
2203
2204         <secondary>on first AFS machine</secondary>
2205
2206         <tertiary>Solaris</tertiary>
2207       </indexterm>
2208
2209       <indexterm>
2210         <primary>first AFS machine</primary>
2211
2212         <secondary>fsck program</secondary>
2213
2214         <tertiary>on Solaris</tertiary>
2215       </indexterm>
2216
2217       <indexterm>
2218         <primary>Solaris</primary>
2219
2220         <secondary>fsck program</secondary>
2221
2222         <tertiary>on first AFS machine</tertiary>
2223       </indexterm>
2224     </sect2>
2225
2226     <sect2 id="HDRWQ47">
2227       <title>Configuring the AFS-modified fsck Program on Solaris Systems</title>
2228
2229       <para>In this section, you make modifications to guarantee that the appropriate <emphasis role="bold">fsck</emphasis> program
2230       runs on AFS server partitions. The <emphasis role="bold">fsck</emphasis> program provided with the operating system must never
2231       run on AFS server partitions. Because it does not recognize the structures that the File Server uses to organize volume data,
2232       it removes all of the data. To repeat:</para>
2233
2234       <para><emphasis role="bold">Never run the standard fsck program on AFS server partitions. It discards AFS volumes.</emphasis>
2235       <orderedlist>
2236           <listitem>
2237             <para>Create the <emphasis role="bold">/usr/lib/fs/afs</emphasis> directory to house the AFS-modified <emphasis
2238             role="bold">fsck</emphasis> program and related files. <programlisting>
2239    # <emphasis role="bold">mkdir /usr/lib/fs/afs</emphasis>
2240    # <emphasis role="bold">cd /usr/lib/fs/afs</emphasis>  
2241 </programlisting></para>
2242           </listitem>
2243
2244           <listitem>
2245             <para>Copy the <emphasis role="bold">vfsck</emphasis> binary to the newly created directory, changing the name as you do
2246             so. <programlisting>
2247    # <emphasis role="bold">cp  /tmp/afsdist/sun4x_56/root.server/etc/vfsck  fsck</emphasis>
2248 </programlisting></para>
2249           </listitem>
2250
2251           <listitem>
2252             <para>Working in the <emphasis role="bold">/usr/lib/fs/afs</emphasis> directory, create the following links to Solaris
2253             libraries: <programlisting>
2254    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/clri</emphasis>  
2255    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/df</emphasis>
2256    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/edquota</emphasis>
2257    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/ff</emphasis>
2258    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/fsdb</emphasis>  
2259    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/fsirand</emphasis>
2260    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/fstyp</emphasis>
2261    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/labelit</emphasis>
2262    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/lockfs</emphasis>
2263    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/mkfs</emphasis>  
2264    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/mount</emphasis>
2265    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/ncheck</emphasis>
2266    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/newfs</emphasis>
2267    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/quot</emphasis>
2268    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/quota</emphasis>
2269    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/quotaoff</emphasis>
2270    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/quotaon</emphasis>
2271    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/repquota</emphasis>
2272    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/tunefs</emphasis>
2273    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/ufsdump</emphasis>
2274    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/ufsrestore</emphasis>
2275    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/volcopy</emphasis>
2276 </programlisting></para>
2277           </listitem>
2278
2279           <listitem>
2280             <para>Append the following line to the end of the file <emphasis role="bold">/etc/dfs/fstypes</emphasis>.
2281             <programlisting>
2282    afs AFS Utilities
2283 </programlisting></para>
2284           </listitem>
2285
2286           <listitem>
2287             <para>Edit the <emphasis role="bold">/sbin/mountall</emphasis> file, making two changes. <itemizedlist>
2288                 <listitem>
2289                   <para>Add an entry for AFS to the <computeroutput>case</computeroutput> statement for option 2, so that it reads
2290                   as follows: <programlisting>
2291    case "$2" in
2292    ufs)    foptions="-o p"
2293            ;;
2294    afs)    foptions="-o p"
2295            ;;
2296    s5)     foptions="-y -t /var/tmp/tmp$$ -D"
2297            ;;
2298    *)      foptions="-y"
2299            ;;
2300 </programlisting></para>
2301                 </listitem>
2302
2303                 <listitem>
2304                   <para>Edit the file so that all AFS and UFS partitions are checked in parallel. Replace the following section of
2305                   code: <programlisting>
2306    # For  fsck purposes, we make a distinction between ufs and
2307    # other file systems
2308    #
2309    if [ "$fstype" = "ufs" ]; then
2310         ufs_fscklist="$ufs_fscklist $fsckdev"
2311         saveentry $fstype "$OPTIONS" $special $mountp
2312         continue
2313    fi  
2314 </programlisting></para>
2315
2316                   <para>with the following section of code:</para>
2317
2318                   <programlisting>
2319    # For fsck purposes, we make a distinction between ufs/afs
2320    # and other file systems.
2321    #
2322    if [ "$fstype" = "ufs" -o "$fstype" = "afs" ]; then
2323         ufs_fscklist="$ufs_fscklist $fsckdev"
2324         saveentry $fstype "$OPTIONS" $special $mountp
2325         continue
2326    fi
2327 </programlisting>
2328                 </listitem>
2329               </itemizedlist></para>
2330           </listitem>
2331         </orderedlist></para>
2332
2333       <indexterm>
2334         <primary>configuring</primary>
2335
2336         <secondary>AFS server partition on first AFS machine</secondary>
2337
2338         <tertiary>Solaris</tertiary>
2339       </indexterm>
2340
2341       <indexterm>
2342         <primary>AFS server partition</primary>
2343
2344         <secondary>configuring on first AFS machine</secondary>
2345
2346         <tertiary>Solaris</tertiary>
2347       </indexterm>
2348
2349       <indexterm>
2350         <primary>first AFS machine</primary>
2351
2352         <secondary>AFS server partition</secondary>
2353
2354         <tertiary>on Solaris</tertiary>
2355       </indexterm>
2356
2357       <indexterm>
2358         <primary>Solaris</primary>
2359
2360         <secondary>AFS server partition</secondary>
2361
2362         <tertiary>on first AFS machine</tertiary>
2363       </indexterm>
2364     </sect2>
2365
2366     <sect2 id="HDRWQ48">
2367       <title>Configuring Server Partitions on Solaris Systems</title>
2368
2369       <para>Every AFS file server machine must have at least one partition or logical volume dedicated to storing AFS volumes. Each
2370       server partition is mounted at a directory named <emphasis role="bold">/vicep</emphasis><replaceable>xx</replaceable>, where
2371       <replaceable>xx</replaceable> is one or two lowercase letters. The <emphasis
2372       role="bold">/vicep</emphasis><replaceable>xx</replaceable> directories must reside in the file server machine's root
2373       directory, not in one of its subdirectories (for example, <emphasis role="bold">/usr/vicepa</emphasis> is not an acceptable
2374       directory location). For additional information, see <link linkend="HDRWQ20">Performing Platform-Specific Procedures</link>.
2375       <orderedlist>
2376           <listitem>
2377             <para>Create a directory called <emphasis role="bold">/vicep</emphasis><replaceable>xx</replaceable> for each AFS server
2378             partition you are configuring (there must be at least one). Repeat the command for each partition. <programlisting>
2379    # <emphasis role="bold">mkdir /vicep</emphasis><replaceable>xx</replaceable>
2380 </programlisting></para>
2381           </listitem>
2382
2383           <listitem>
2384             <para>Add a line with the following format to the file systems registry file, <emphasis
2385             role="bold">/etc/vfstab</emphasis>, for each partition to be mounted on a directory created in the previous step. Note
2386             the value <computeroutput>afs</computeroutput> in the fourth field, which tells Solaris to use the AFS-modified
2387             <emphasis role="bold">fsck</emphasis> program on this partition. <programlisting>
2388    /dev/dsk/<replaceable>disk</replaceable>   /dev/rdsk/<replaceable>disk</replaceable>   /vicep<replaceable>xx</replaceable>   afs   <replaceable>boot_order</replaceable>  yes  
2389 </programlisting></para>
2390
2391             <para>The following is an example for the first partition being configured.</para>
2392
2393             <programlisting>
2394    /dev/dsk/c0t6d0s1 /dev/rdsk/c0t6d0s1 /vicepa afs 3 yes
2395 </programlisting>
2396           </listitem>
2397
2398           <listitem>
2399             <para>Create a file system on each partition that is to be mounted at a <emphasis
2400             role="bold">/vicep</emphasis><replaceable>xx</replaceable> directory. The following command is probably appropriate, but
2401             consult the Solaris documentation for more information. <programlisting>
2402    # <emphasis role="bold">newfs -v /dev/rdsk/</emphasis><replaceable>disk</replaceable>
2403 </programlisting></para>
2404           </listitem>
2405
2406           <listitem>
2407             <para>Issue the <emphasis role="bold">mountall</emphasis> command to mount all partitions at once.</para>
2408           </listitem>
2409
2410           <listitem>
2411             <para>If you plan to retain client functionality on this machine after completing the installation, proceed to <link
2412             linkend="HDRWQ49">Enabling AFS Login and Editing the File Systems Clean-up Script on Solaris Systems</link>. Otherwise,
2413             proceed to <link linkend="HDRWQ50">Starting the BOS Server</link>.</para>
2414           </listitem>
2415         </orderedlist></para>
2416     </sect2>
2417
2418     <sect2 id="HDRWQ49">
2419       <title>Enabling AFS Login on Solaris Systems</title>
2420       <indexterm>
2421         <primary>enabling AFS login</primary>
2422
2423         <secondary>file server machine</secondary>
2424
2425         <tertiary>Solaris</tertiary>
2426       </indexterm>
2427
2428       <indexterm>
2429         <primary>AFS login</primary>
2430
2431         <secondary>on file server machine</secondary>
2432
2433         <tertiary>Solaris</tertiary>
2434       </indexterm>
2435
2436       <indexterm>
2437         <primary>first AFS machine</primary>
2438
2439         <secondary>AFS login</secondary>
2440
2441         <tertiary>on Solaris</tertiary>
2442       </indexterm>
2443
2444       <indexterm>
2445         <primary>Solaris</primary>
2446
2447         <secondary>AFS login</secondary>
2448
2449         <tertiary>on file server machine</tertiary>
2450       </indexterm>
2451
2452       <indexterm>
2453         <primary>PAM</primary>
2454
2455         <secondary>on Solaris</secondary>
2456
2457         <tertiary>file server machine</tertiary>
2458       </indexterm>
2459
2460       <note>
2461         <para>If you plan to remove client functionality from this machine after completing the installation, skip this section and
2462         proceed to <link linkend="HDRWQ50">Starting the BOS Server</link>.</para>
2463       </note>
2464
2465       <para>At this point you incorporate AFS into the operating system's
2466       Pluggable Authentication Module (PAM) scheme.  PAM integrates all
2467       authentication mechanisms on the machine, including login, to provide
2468       the security infrastructure for authenticated access to and from the
2469       machine.</para>
2470
2471       <para>Explaining PAM is beyond the scope of this document.  It is
2472       assumed that you understand the syntax and meanings of settings in the
2473       PAM configuration file (for example, how the
2474       <computeroutput>other</computeroutput> entry works, the effect of
2475       marking an entry as <computeroutput>required</computeroutput>,
2476       <computeroutput>optional</computeroutput>, or
2477       <computeroutput>sufficient</computeroutput>, and so on).</para>
2478
2479       <para>You should first configure your system to obtain Kerberos v5
2480       tickets as part of the authentication process, and then run an AFS PAM
2481       module to obtain tokens from those tickets after authentication.
2482       Current versions of Solaris come with a Kerberos v5 PAM module that
2483       will work, or you can download and install <ulink
2484       url="http://www.eyrie.org/~eagle/software/pam-krb5">Russ Allbery's
2485       Kerberos v5 PAM module</ulink>, which is tested regularly with AFS.
2486       See the instructions of whatever PAM module you use for how to
2487       configure it.</para>
2488
2489       <para>Some Kerberos v5 PAM modules do come with native AFS support
2490       (usually requiring the Heimdal Kerberos implementation rather than the
2491       MIT Kerberos implementation).  If you are using one of those PAM
2492       modules, you can configure it to obtain AFS tokens.  It's more common,
2493       however, to separate the AFS token acquisition into a separate PAM
2494       module.</para>
2495
2496       <para>The recommended AFS PAM module is <ulink
2497       url="http://www.eyrie.org/~eagle/software/pam-afs-session/">Russ
2498       Allbery's pam-afs-session module</ulink>.  It should work with any of
2499       the Kerberos v5 PAM modules.  To add it to the PAM configuration, you
2500       often only need to add configuration to the session group in
2501       <filename>pam.conf</filename>:</para>
2502
2503       <example>
2504         <title>Solaris PAM session example</title>
2505         <literallayout>login session required pam_afs_session.so</literallayout>
2506       </example>
2507
2508       <para>This example enables PAM authentication only for console login.
2509       You may want to add a similar line for the ssh service and for any
2510       other login service that you use, including possibly the
2511       <literal>other</literal> service (which serves as a catch-all).  You
2512       may also want to add options to the AFS PAM session module
2513       (particularly <literal>retain_after_close</literal>, which is
2514       necessary for some versions of Solaris.</para>
2515
2516       <para>For additional configuration examples and the configuration
2517       options of the AFS PAM module, see its documentation.  For more
2518       details on the available options for the PAM configuration, see the
2519       <filename>pam.conf</filename> manual page.</para>
2520
2521       <para>Sites which still require <emphasis
2522       role="bold">kaserver</emphasis> or external Kerberos v4 authentication
2523       should consult <link linkend="KAS016">"Enabling kaserver based AFS
2524       Login on Solaris Systems"</link> for details of how to enable AFS
2525       login on Solaris.</para>
2526
2527       <para>Proceed to <link linkend="HDRWQ49a">Editing the File Systems 
2528       Clean-up Script on Solaris Systems</link></para>
2529     </sect2>
2530     <sect2 id="HDRWQ49a">
2531       <title>Editing the File Systems Clean-up Script on Solaris Systems</title>
2532       <indexterm>
2533         <primary>Solaris</primary>
2534
2535         <secondary>file systems clean-up script</secondary>
2536
2537         <tertiary>on file server machine</tertiary>
2538       </indexterm>
2539
2540       <indexterm>
2541         <primary>file systems clean-up script (Solaris)</primary>
2542
2543         <secondary>file server machine</secondary>
2544       </indexterm>
2545
2546       <indexterm>
2547         <primary>scripts</primary>
2548
2549         <secondary>file systems clean-up (Solaris)</secondary>
2550
2551         <tertiary>file server machine</tertiary>
2552       </indexterm>
2553
2554       
2555         <orderedlist>
2556           <listitem>
2557             <para>Some Solaris distributions include a script that locates and removes unneeded files from various file systems. Its
2558             conventional location is <emphasis role="bold">/usr/lib/fs/nfs/nfsfind</emphasis>. The script generally uses an argument
2559             to the <emphasis role="bold">find</emphasis> command to define which file systems to search. In this step you modify the
2560             command to exclude the <emphasis role="bold">/afs</emphasis> directory. Otherwise, the command traverses the AFS
2561             filespace of every cell that is accessible from the machine, which can take many hours. The following alterations are
2562             possibilities, but you must verify that they are appropriate for your cell.</para>
2563
2564             <para>The first possible alteration is to add the <emphasis role="bold">-local</emphasis> flag to the existing command,
2565             so that it looks like the following:</para>
2566
2567             <programlisting>
2568    find $dir -local -name .nfs\* -mtime +7 -mount -exec rm -f {} \;   
2569 </programlisting>
2570
2571             <para>Another alternative is to exclude any directories whose names begin with the lowercase letter <emphasis
2572             role="bold">a</emphasis> or a non-alphabetic character.</para>
2573
2574             <programlisting>
2575    find /[A-Zb-z]*  <replaceable>remainder of existing command</replaceable>   
2576 </programlisting>
2577
2578             <para>Do not use the following command, which still searches under the <emphasis role="bold">/afs</emphasis> directory,
2579             looking for a subdirectory of type <emphasis role="bold">4.2</emphasis>.</para>
2580
2581             <programlisting>
2582    find / -fstype 4.2     /* <replaceable>do not use</replaceable> */
2583 </programlisting>
2584           </listitem>
2585
2586           <listitem>
2587             <para>Proceed to <link linkend="HDRWQ50">Starting the BOS Server</link> (or if referring to these instructions while
2588             installing an additional file server machine, return to <link linkend="HDRWQ108">Starting Server
2589             Programs</link>).</para>
2590           </listitem>
2591         </orderedlist>
2592
2593       <indexterm>
2594         <primary>Basic OverSeer Server</primary>
2595
2596         <see>BOS Server</see>
2597       </indexterm>
2598
2599       <indexterm>
2600         <primary>BOS Server</primary>
2601
2602         <secondary>starting</secondary>
2603
2604         <tertiary>first AFS machine</tertiary>
2605       </indexterm>
2606
2607       <indexterm>
2608         <primary>starting</primary>
2609
2610         <secondary>BOS Server</secondary>
2611
2612         <tertiary>first AFS machine</tertiary>
2613       </indexterm>
2614
2615       <indexterm>
2616         <primary>first AFS machine</primary>
2617
2618         <secondary>BOS Server</secondary>
2619       </indexterm>
2620
2621       <indexterm>
2622         <primary>authorization checking (disabling)</primary>
2623
2624         <secondary>first AFS machine</secondary>
2625       </indexterm>
2626
2627       <indexterm>
2628         <primary>disabling authorization checking</primary>
2629
2630         <secondary>first AFS machine</secondary>
2631       </indexterm>
2632
2633       <indexterm>
2634         <primary>first AFS machine</primary>
2635
2636         <secondary>authorization checking (disabling)</secondary>
2637       </indexterm>
2638     </sect2>
2639   </sect1>
2640   <sect1 id="HDRWQ50">
2641     <title>Starting the BOS Server</title>
2642
2643     <para>You are now ready to start the AFS server processes on this machine. 
2644     If you are not working from a packaged distribution, begin by copying the 
2645     AFS server binaries from the distribution to the conventional local disk
2646     location, the <emphasis role="bold">/usr/afs/bin</emphasis> directory. The 
2647     following instructions also create files in other subdirectories of the 
2648     <emphasis role="bold">/usr/afs</emphasis> directory.</para>
2649
2650     <para>Then issue the <emphasis role="bold">bosserver</emphasis> command to initialize the Basic OverSeer (BOS) Server, which
2651     monitors and controls other AFS server processes on its server machine. Include the <emphasis role="bold">-noauth</emphasis>
2652     flag to disable authorization checking. Because you have not yet configured your cell's AFS authentication and authorization
2653     mechanisms, the BOS Server cannot perform authorization checking as it does during normal operation. In no-authorization mode,
2654     it does not verify the identity or privilege of the issuer of a <emphasis role="bold">bos</emphasis> command, and so performs
2655     any operation for anyone.</para>
2656
2657     <para>Disabling authorization checking gravely compromises cell security. You must complete all subsequent steps in one
2658     uninterrupted pass and must not leave the machine unattended until you restart the BOS Server with authorization checking
2659     enabled, in <link linkend="HDRWQ72">Verifying the AFS Initialization Script</link>.</para>
2660
2661     <para>As it initializes for the first time, the BOS Server creates the following directories and files, setting the owner to the
2662     local superuser <emphasis role="bold">root</emphasis> and the mode bits to limit the ability to write (and in some cases, read)
2663     them. For a description of the contents and function of these directories and files, see the chapter in the <emphasis>OpenAFS
2664     Administration Guide</emphasis> about administering server machines. For further discussion of the mode bit settings, see <link
2665     linkend="HDRWQ96">Protecting Sensitive AFS Directories</link>. <indexterm>
2666         <primary>Binary Distribution</primary>
2667
2668         <secondary>copying server files from</secondary>
2669
2670         <tertiary>first AFS machine</tertiary>
2671       </indexterm> <indexterm>
2672         <primary>first AFS machine</primary>
2673
2674         <secondary>subdirectories of /usr/afs</secondary>
2675       </indexterm> <indexterm>
2676         <primary>creating</primary>
2677
2678         <secondary>/usr/afs/bin directory</secondary>
2679
2680         <tertiary>first AFS machine</tertiary>
2681       </indexterm> <indexterm>
2682         <primary>creating</primary>
2683
2684         <secondary>/usr/afs/etc directory</secondary>
2685
2686         <tertiary>first AFS machine</tertiary>
2687       </indexterm> <indexterm>
2688         <primary>copying</primary>
2689
2690         <secondary>server files to local disk</secondary>
2691
2692         <tertiary>first AFS machine</tertiary>
2693       </indexterm> <indexterm>
2694         <primary>first AFS machine</primary>
2695
2696         <secondary>copying</secondary>
2697
2698         <tertiary>server files to local disk</tertiary>
2699       </indexterm> <indexterm>
2700         <primary>usr/afs/bin directory</primary>
2701
2702         <secondary>first AFS machine</secondary>
2703       </indexterm> <indexterm>
2704         <primary>usr/afs/etc directory</primary>
2705
2706         <secondary>first AFS machine</secondary>
2707       </indexterm> <indexterm>
2708         <primary>usr/afs/db directory</primary>
2709       </indexterm> <indexterm>
2710         <primary>usr/afs/local directory</primary>
2711       </indexterm> <indexterm>
2712         <primary>usr/afs/logs directory</primary>
2713       </indexterm> <itemizedlist>
2714         <listitem>
2715           <para><emphasis role="bold">/usr/afs/db</emphasis></para>
2716         </listitem>
2717
2718         <listitem>
2719           <para><emphasis role="bold">/usr/afs/etc/CellServDB</emphasis></para>
2720         </listitem>
2721
2722         <listitem>
2723           <para><emphasis role="bold">/usr/afs/etc/ThisCell</emphasis></para>
2724         </listitem>
2725
2726         <listitem>
2727           <para><emphasis role="bold">/usr/afs/local</emphasis></para>
2728         </listitem>
2729
2730         <listitem>
2731           <para><emphasis role="bold">/usr/afs/logs</emphasis></para>
2732         </listitem>
2733       </itemizedlist></para>
2734
2735     <para>The BOS Server also creates symbolic links called <emphasis role="bold">/usr/vice/etc/ThisCell</emphasis> and <emphasis
2736     role="bold">/usr/vice/etc/CellServDB</emphasis> to the corresponding files in the <emphasis role="bold">/usr/afs/etc</emphasis>
2737     directory. The AFS command interpreters consult the <emphasis role="bold">CellServDB</emphasis> and <emphasis
2738     role="bold">ThisCell</emphasis> files in the <emphasis role="bold">/usr/vice/etc</emphasis> directory because they generally run
2739     on client machines. On machines that are AFS servers only (as this machine currently is), the files reside only in the <emphasis
2740     role="bold">/usr/afs/etc</emphasis> directory; the links enable the command interpreters to retrieve the information they need.
2741     Later instructions for installing the client functionality replace the links with actual files. <orderedlist>
2742         <listitem>
2743           <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. 
2744 <programlisting>
2745    # <emphasis role="bold">cd /tmp/afsdist/</emphasis><replaceable>sysname</replaceable><emphasis role="bold">/root.server/usr/afs</emphasis>
2746    # <emphasis role="bold">cp -rp  *  /usr/afs</emphasis>
2747 </programlisting> <indexterm>
2748               <primary>commands</primary>
2749
2750               <secondary>bosserver</secondary>
2751             </indexterm> <indexterm>
2752               <primary>bosserver command</primary>
2753             </indexterm></para>
2754         </listitem>
2755
2756         <listitem>
2757           <para>Issue the <emphasis role="bold">bosserver</emphasis> command. Include the <emphasis role="bold">-noauth</emphasis>
2758           flag to disable authorization checking. <programlisting>
2759    # <emphasis role="bold">/usr/afs/bin/bosserver -noauth &amp;</emphasis>
2760 </programlisting></para>
2761         </listitem>
2762
2763         <listitem>
2764           <para>Verify that the BOS Server created <emphasis role="bold">/usr/vice/etc/ThisCell</emphasis> and <emphasis
2765           role="bold">/usr/vice/etc/CellServDB</emphasis> as symbolic links to the corresponding files in the <emphasis
2766           role="bold">/usr/afs/etc</emphasis> directory. <programlisting>
2767    # <emphasis role="bold">ls -l  /usr/vice/etc</emphasis>
2768 </programlisting></para>
2769
2770           <para>If either or both of <emphasis role="bold">/usr/vice/etc/ThisCell</emphasis> and <emphasis
2771           role="bold">/usr/vice/etc/CellServDB</emphasis> do not exist, or are not links, issue the following commands.</para>
2772
2773           <programlisting>
2774    # <emphasis role="bold">cd /usr/vice/etc</emphasis>
2775    # <emphasis role="bold">ln -s /usr/afs/etc/ThisCell</emphasis>
2776    # <emphasis role="bold">ln -s /usr/afs/etc/CellServDB</emphasis> 
2777 </programlisting>
2778         </listitem>
2779       </orderedlist></para>
2780
2781     <indexterm>
2782       <primary>cell name</primary>
2783
2784       <secondary>defining during installation of first machine</secondary>
2785     </indexterm>
2786
2787     <indexterm>
2788       <primary>defining</primary>
2789
2790       <secondary>cell name during installation of first machine</secondary>
2791     </indexterm>
2792
2793     <indexterm>
2794       <primary>cell name</primary>
2795
2796       <secondary>setting in server ThisCell file</secondary>
2797
2798       <tertiary>first AFS machine</tertiary>
2799     </indexterm>
2800
2801     <indexterm>
2802       <primary>setting</primary>
2803
2804       <secondary>cell name in server ThisCell file</secondary>
2805
2806       <tertiary>first AFS machine</tertiary>
2807     </indexterm>
2808
2809     <indexterm>
2810       <primary>first AFS machine</primary>
2811
2812       <secondary>ThisCell file (server)</secondary>
2813     </indexterm>
2814
2815     <indexterm>
2816       <primary>usr/afs/etc/ThisCell</primary>
2817
2818       <see>ThisCell file (server)</see>
2819     </indexterm>
2820
2821     <indexterm>
2822       <primary>ThisCell file (server)</primary>
2823
2824       <secondary>first AFS machine</secondary>
2825     </indexterm>
2826
2827     <indexterm>
2828       <primary>files</primary>
2829
2830       <secondary>ThisCell (server)</secondary>
2831     </indexterm>
2832
2833     <indexterm>
2834       <primary>database server machine</primary>
2835
2836       <secondary>entry in server CellServDB file</secondary>
2837
2838       <tertiary>on first AFS machine</tertiary>
2839     </indexterm>
2840
2841     <indexterm>
2842       <primary>first AFS machine</primary>
2843
2844       <secondary>cell membership, defining</secondary>
2845
2846       <tertiary>for server processes</tertiary>
2847     </indexterm>
2848
2849     <indexterm>
2850       <primary>usr/afs/etc/CellServDB file</primary>
2851
2852       <see>CellServDB file (server)</see>
2853     </indexterm>
2854
2855     <indexterm>
2856       <primary>CellServDB file (server)</primary>
2857
2858       <secondary>creating</secondary>
2859
2860       <tertiary>on first AFS machine</tertiary>
2861     </indexterm>
2862
2863     <indexterm>
2864       <primary>creating</primary>
2865
2866       <secondary>CellServDB file (server)</secondary>
2867
2868       <tertiary>first AFS machine</tertiary>
2869     </indexterm>
2870
2871     <indexterm>
2872       <primary>files</primary>
2873
2874       <secondary>CellServDB (server)</secondary>
2875     </indexterm>
2876
2877     <indexterm>
2878       <primary>first AFS machine</primary>
2879
2880       <secondary>CellServDB file (server)</secondary>
2881     </indexterm>
2882
2883     <indexterm>
2884       <primary>first AFS machine</primary>
2885
2886       <secondary>defining</secondary>
2887
2888       <tertiary>as database server</tertiary>
2889     </indexterm>
2890
2891     <indexterm>
2892       <primary>defining</primary>
2893
2894       <secondary>first AFS machine as database server</secondary>
2895     </indexterm>
2896   </sect1>
2897
2898   <sect1 id="HDRWQ51">
2899     <title>Defining Cell Name and Membership for Server Processes</title>
2900
2901     <para>Now assign your cell's name. The chapter in the <emphasis>OpenAFS Administration Guide</emphasis> about cell configuration
2902     and administration issues discusses the important considerations, explains why changing the name is difficult, and outlines the
2903     restrictions on name format. Two of the most important restrictions are that the name cannot include uppercase letters or more
2904     than 64 characters.</para>
2905
2906     <para>Use the <emphasis role="bold">bos setcellname</emphasis> command to assign the cell name. It creates two files:
2907     <itemizedlist>
2908         <listitem>
2909           <para><emphasis role="bold">/usr/afs/etc/ThisCell</emphasis>, which defines this machine's cell membership</para>
2910         </listitem>
2911
2912         <listitem>
2913           <para><emphasis role="bold">/usr/afs/etc/CellServDB</emphasis>, which lists the cell's database server machines; the
2914           machine named on the command line is placed on the list automatically</para>
2915         </listitem>
2916       </itemizedlist> <note>
2917         <para>In the following and every instruction in this guide, for the <replaceable>machine name</replaceable> argument
2918         substitute the fully-qualified hostname (such as <emphasis role="bold">fs1.example.com</emphasis>) of the machine you are
2919         installing. For the <replaceable>cell name</replaceable> argument substitute your cell's complete name (such as <emphasis
2920         role="bold">example.com</emphasis>).</para>
2921       </note></para>
2922
2923     <indexterm>
2924       <primary>commands</primary>
2925
2926       <secondary>bos setcellname</secondary>
2927     </indexterm>
2928
2929     <indexterm>
2930       <primary>bos commands</primary>
2931
2932       <secondary>setcellname</secondary>
2933     </indexterm>
2934
2935     <orderedlist>
2936       <listitem>
2937         <para>If necessary, add the directory containing the <emphasis role="bold">bos</emphasis> command to your path.
2938       <programlisting>
2939    # <emphasis role="bold">export PATH=$PATH:/usr/afs/bin</emphasis>
2940       </programlisting>
2941         </para>
2942       </listitem>
2943
2944       <listitem>
2945         <para>Issue the <emphasis role="bold">bos setcellname</emphasis> command to set the cell name. <programlisting>
2946    # <emphasis role="bold">bos setcellname</emphasis> &lt;<replaceable>machine name</replaceable>&gt; &lt;<replaceable>cell name</replaceable>&gt; <emphasis
2947               role="bold">-noauth</emphasis>
2948 </programlisting></para>
2949
2950         <para>Because you are not authenticated and authorization checking is disabled, the <emphasis role="bold">bos</emphasis>
2951         command interpreter possibly produces error messages about being unable to obtain tickets and running unauthenticated. You
2952         can safely ignore the messages. <indexterm>
2953             <primary>commands</primary>
2954
2955             <secondary>bos listhosts</secondary>
2956           </indexterm> <indexterm>
2957             <primary>bos commands</primary>
2958
2959             <secondary>listhosts</secondary>
2960           </indexterm> <indexterm>
2961             <primary>CellServDB file (server)</primary>
2962
2963             <secondary>displaying entries</secondary>
2964           </indexterm> <indexterm>
2965             <primary>displaying</primary>
2966
2967             <secondary>CellServDB file (server) entries</secondary>
2968           </indexterm></para>
2969       </listitem>
2970
2971       <listitem>
2972         <para>Issue the <emphasis role="bold">bos listhosts</emphasis> command to verify that the machine you are installing is now
2973         registered as the cell's first database server machine. <programlisting>
2974    # <emphasis role="bold">bos listhosts</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">-noauth</emphasis>
2975    Cell name is <replaceable>cell_name</replaceable>
2976        Host 1 is <replaceable>machine_name</replaceable>
2977 </programlisting></para>
2978       </listitem>
2979     </orderedlist>
2980
2981     <indexterm>
2982       <primary>database server machine</primary>
2983
2984       <secondary>installing</secondary>
2985
2986       <tertiary>first</tertiary>
2987     </indexterm>
2988
2989     <indexterm>
2990       <primary>instructions</primary>
2991
2992       <secondary>database server machine, installing first</secondary>
2993     </indexterm>
2994
2995     <indexterm>
2996       <primary>installing</primary>
2997
2998       <secondary>database server machine</secondary>
2999
3000       <tertiary>first</tertiary>
3001     </indexterm>
3002
3003     <indexterm>
3004       <primary>Backup Server</primary>
3005
3006       <secondary>starting</secondary>
3007
3008       <tertiary>first AFS machine</tertiary>
3009     </indexterm>
3010
3011     <indexterm>
3012       <primary>buserver process</primary>
3013
3014       <see>Backup Server</see>
3015     </indexterm>
3016
3017     <indexterm>
3018       <primary>starting</primary>
3019
3020       <secondary>Backup Server</secondary>
3021
3022       <tertiary>first AFS machine</tertiary>
3023     </indexterm>
3024
3025     <indexterm>
3026       <primary>first AFS machine</primary>
3027
3028       <secondary>Backup Server</secondary>
3029     </indexterm>
3030
3031     <indexterm>
3032       <primary>Protection Server</primary>
3033
3034       <secondary>starting</secondary>
3035
3036       <tertiary>first AFS machine</tertiary>
3037     </indexterm>
3038
3039     <indexterm>
3040       <primary>ptserver process</primary>
3041
3042       <see>Protection Server</see>
3043     </indexterm>
3044
3045     <indexterm>
3046       <primary>starting</primary>
3047
3048       <secondary>Protection Server</secondary>
3049
3050       <tertiary>first AFS machine</tertiary>
3051     </indexterm>
3052
3053     <indexterm>
3054       <primary>first AFS machine</primary>
3055
3056       <secondary>Protection Server</secondary>
3057     </indexterm>
3058
3059     <indexterm>
3060       <primary>VL Server (vlserver process)</primary>
3061
3062       <secondary>starting</secondary>
3063
3064       <tertiary>first AFS machine</tertiary>
3065     </indexterm>
3066
3067     <indexterm>
3068       <primary>Volume Location Server</primary>
3069
3070       <see>VL Server</see>
3071     </indexterm>
3072
3073     <indexterm>
3074       <primary>starting</primary>
3075
3076       <secondary>VL Server</secondary>
3077
3078       <tertiary>first AFS machine</tertiary>
3079     </indexterm>
3080
3081     <indexterm>
3082       <primary>first AFS machine</primary>
3083
3084       <secondary>VL Server</secondary>
3085     </indexterm>
3086
3087     <indexterm>
3088       <primary>usr/afs/local/BosConfig</primary>
3089
3090       <see>BosConfig file</see>
3091     </indexterm>
3092
3093     <indexterm>
3094       <primary>BosConfig file</primary>
3095
3096       <secondary>adding entries</secondary>
3097
3098       <tertiary>first AFS machine</tertiary>
3099     </indexterm>
3100
3101     <indexterm>
3102       <primary>adding</primary>
3103
3104       <secondary>entries to BosConfig file</secondary>
3105
3106       <tertiary>first AFS machine</tertiary>
3107     </indexterm>
3108
3109     <indexterm>
3110       <primary>files</primary>
3111
3112       <secondary>BosConfig</secondary>
3113     </indexterm>
3114
3115     <indexterm>
3116       <primary>initializing</primary>
3117
3118       <secondary>server process</secondary>
3119
3120       <see>starting</see>
3121     </indexterm>
3122
3123     <indexterm>
3124       <primary>server process</primary>
3125
3126       <secondary>see also entry for each server's name</secondary>
3127     </indexterm>
3128   </sect1>
3129
3130   <sect1 id="HDRWQ52">
3131     <title>Starting the Database Server Processes</title>
3132
3133     <para>Next use the <emphasis role="bold">bos create</emphasis> command to create entries for the three database server processes
3134     in the <emphasis role="bold">/usr/afs/local/BosConfig</emphasis> file and start them running. The three processes run on database
3135     server machines only: <itemizedlist>
3136
3137         <listitem>
3138           <para>The Backup Server (the <emphasis role="bold">buserver</emphasis> process) maintains the Backup Database</para>
3139         </listitem>
3140
3141         <listitem>
3142           <para>The Protection Server (the <emphasis role="bold">ptserver</emphasis> process) maintains the Protection
3143           Database</para>
3144         </listitem>
3145
3146         <listitem>
3147           <para>The Volume Location (VL) Server (the <emphasis role="bold">vlserver</emphasis> process) maintains the Volume
3148           Location Database (VLDB)</para>
3149         </listitem>
3150       </itemizedlist></para>
3151
3152     <indexterm>
3153       <primary>Kerberos</primary>
3154     </indexterm>
3155
3156     <note>
3157       <para>AFS ships with an additional database server named 'kaserver', which
3158       was historically used to provide authentication services to AFS cells.
3159       kaserver was based on <emphasis>Kerberos v4</emphasis>, as such, it is
3160       not recommended for new cells. This guide assumes you have already
3161       configured a Kerberos v5 realm for your site, and details the procedures 
3162       required to use AFS with this realm. If you do wish to use
3163       <emphasis role="bold">kaserver</emphasis>, please see the modifications
3164       to these instructions detailed in 
3165       <link linkend="KAS006">Starting the kaserver Database Server Process</link>
3166       </para>
3167     </note>
3168
3169     <para>The remaining instructions in this chapter include the <emphasis role="bold">-cell</emphasis> argument on all applicable
3170     commands. Provide the cell name you assigned in <link linkend="HDRWQ51">Defining Cell Name and Membership for Server
3171     Processes</link>. If a command appears on multiple lines, it is only for legibility. <indexterm>
3172         <primary>commands</primary>
3173
3174         <secondary>bos create</secondary>
3175       </indexterm> <indexterm>
3176         <primary>bos commands</primary>
3177
3178         <secondary>create</secondary>
3179       </indexterm> <orderedlist>
3180         <listitem>
3181           <para>Issue the <emphasis role="bold">bos create</emphasis> command to start the Backup Server. <programlisting>
3182    # <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>
3183 </programlisting></para>
3184         </listitem>
3185
3186         <listitem>
3187           <para>Issue the <emphasis role="bold">bos create</emphasis> command to start the Protection Server. <programlisting>
3188    # <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>
3189 </programlisting></para>
3190         </listitem>
3191
3192         <listitem>
3193           <para>Issue the <emphasis role="bold">bos create</emphasis> command to start the VL Server. <programlisting>
3194    # <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>
3195 </programlisting></para>
3196         </listitem>
3197       </orderedlist></para>
3198
3199     <indexterm>
3200       <primary>admin account</primary>
3201
3202       <secondary>creating</secondary>
3203     </indexterm>
3204
3205     <indexterm>
3206       <primary>afs entry in Kerberos Database</primary>
3207     </indexterm>
3208
3209     <indexterm>
3210       <primary>Kerberos Database</primary>
3211     </indexterm>
3212
3213     <indexterm>
3214       <primary>creating</primary>
3215
3216       <secondary>afs entry in Kerberos Database</secondary>
3217     </indexterm>
3218
3219     <indexterm>
3220       <primary>creating</primary>
3221
3222       <secondary>admin account in Kerberos Database</secondary>
3223     </indexterm>
3224
3225     <indexterm>
3226       <primary>security</primary>
3227
3228       <secondary>initializing cell-wide</secondary>
3229     </indexterm>
3230
3231     <indexterm>
3232       <primary>cell</primary>
3233
3234       <secondary>initializing security mechanisms</secondary>
3235     </indexterm>
3236
3237     <indexterm>
3238       <primary>initializing</primary>
3239
3240       <secondary>cell security mechanisms</secondary>
3241     </indexterm>
3242
3243     <indexterm>
3244       <primary>usr/afs/etc/KeyFile</primary>
3245
3246       <see>KeyFile file</see>
3247     </indexterm>
3248
3249     <indexterm>
3250       <primary>KeyFile file</primary>
3251
3252       <secondary>first AFS machine</secondary>
3253     </indexterm>
3254
3255     <indexterm>
3256       <primary>files</primary>
3257
3258       <secondary>KeyFile</secondary>
3259     </indexterm>
3260
3261     <indexterm>
3262       <primary>key</primary>
3263
3264       <see>server encryption key</see>
3265     </indexterm>
3266
3267     <indexterm>
3268       <primary>encryption key</primary>
3269
3270       <see>server encryption key</see>
3271     </indexterm>
3272   </sect1>
3273
3274   <sect1 id="HDRWQ53">
3275     <title>Initializing Cell Security </title>
3276
3277     <para>If you are working with an existing cell which uses
3278     <emphasis role="bold">kaserver</emphasis> or Kerberos v4 for authentication,
3279     please see 
3280     <link linkend="HDRWQ53">Initializing Cell Security with kaserver</link>
3281     for installation instructions which replace this section.</para>
3282     
3283     <para>Now initialize the cell's security mechanisms. Begin by creating the following two entires in your site's Kerberos database: <itemizedlist>
3284         <listitem>
3285           <para>A generic administrative account, called <emphasis role="bold">admin</emphasis> by convention. If you choose to
3286           assign a different name, substitute it throughout the remainder of this document.</para>
3287
3288           <para>After you complete the installation of the first machine, you can continue to have all administrators use the
3289           <emphasis role="bold">admin</emphasis> account, or you can create a separate administrative account for each of them. The
3290           latter scheme implies somewhat more overhead, but provides a more informative audit trail for administrative
3291           operations.</para>
3292         </listitem>
3293
3294         <listitem>
3295           <para>The entry for AFS server processes, called either 
3296           <emphasis role="bold">afs</emphasis> or 
3297           <emphasis role="bold">afs/<replaceable>cell</replaceable></emphasis>. 
3298           No user logs in under this identity, but it is used to encrypt the
3299           server tickets that granted to AFS clients for presentation to 
3300           server processes during mutual authentication. (The
3301           chapter in the <emphasis>OpenAFS Administration Guide</emphasis> about cell configuration and administration describes the
3302           role of server encryption keys in mutual authentication.)</para>
3303
3304           <para>In Step <link linkend="LIWQ58">7</link>, you also place the initial AFS server encryption key into the <emphasis
3305           role="bold">/usr/afs/etc/KeyFile</emphasis> file. The AFS server processes refer to this file to learn the server
3306           encryption key when they need to decrypt server tickets.</para>
3307         </listitem>
3308       </itemizedlist></para>
3309
3310     <para>You also issue several commands that enable the new <emphasis role="bold">admin</emphasis> user to issue privileged
3311     commands in all of the AFS suites.</para>
3312
3313     <para>The following instructions do not configure all of the security mechanisms related to the AFS Backup System. See the
3314     chapter in the <emphasis>OpenAFS Administration Guide</emphasis> about configuring the Backup System.</para>
3315
3316     <para>The examples below assume you are using MIT Kerberos. Please refer 
3317     to the documentation for your KDC's administrative interface if you are 
3318     using a different vendor</para>
3319
3320     <orderedlist>
3321         <listitem>
3322           <para>Enter <emphasis role="bold">kadmin</emphasis> interactive mode.
3323 <programlisting>