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