doc/xml/QuickStartUnix/auqbg005.xml

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