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