doc/xml/QuickStartUnix/auqbg005.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <chapter id="HDRWQ17">
   3   <title>Installing the First AFS Machine</title>
   4
   5   <para>
   6   <indexterm>
   7     <primary>file server machine</primary>
   8
   9     <seealso>first AFS machine</seealso>
  10
  11     <seealso>file server machine, additional</seealso>
  12   </indexterm>
  13
  14   <indexterm>
  15     <primary>instructions</primary>
  16
  17     <secondary>first AFS machine</secondary>
  18   </indexterm>
  19
  20   <indexterm>
  21     <primary>installing</primary>
  22
  23     <secondary>first AFS machine</secondary>
  24   </indexterm>
  25
  26   This chapter describes how to install the first AFS machine in your cell, configuring it as both a file server machine and a
  27   client machine. After completing all procedures in this chapter, you can remove the client functionality if you wish, as described
  28   in <link linkend="HDRWQ98">Removing Client Functionality</link>.</para>
  29
  30   <para>To install additional file server machines after completing this chapter, see <link linkend="HDRWQ99">Installing Additional
  31   Server Machines</link>.</para>
  32
  33   <para>To install additional client machines after completing this chapter, see <link linkend="HDRWQ133">Installing Additional
  34   Client Machines</link>. <indexterm>
  35       <primary>requirements</primary>
  36
  37       <secondary>first AFS machine</secondary>
  38     </indexterm></para>
  39
  40   <sect1 id="Header_29">
  41     <title>Requirements and Configuration Decisions</title>
  42
  43     <para>The instructions in this chapter assume that you meet the following requirements.
  44       <itemizedlist>
  45         <listitem>
  46           <para>You are logged onto the machine's console as the local superuser <emphasis role="bold">root</emphasis></para>
  47         </listitem>
  48
  49         <listitem>
  50           <para>A standard version of one of the operating systems supported by the current version of AFS is running on the
  51           machine</para>
  52         </listitem>
  53
  54         <listitem>
  55           <para>You have either installed the provided OpenAFS packages for
  56           your system, have access to a binary distribution tarball, or have
  57           successfully built OpenAFS from source</para>
  58         </listitem>
  59
  60         <listitem>
  61           <para>You have a Kerberos v5 realm running for your site. If you are
  62           working with an existing cell which uses
  63           <emphasis role="bold">kaserver</emphasis> or Kerberos v4 for
  64           authentication, please see
  65           <link linkend="KAS001">kaserver and Legacy Kerberos v4 Authentication</link>
  66           for the modifications required to this installation procedure.</para>
  67         </listitem>
  68
  69         <listitem>
  70           <para>You have NTP or a similar time service deployed to ensure
  71           rough clock syncronistation between your clients and servers.</para>
  72         </listitem>
  73       </itemizedlist></para>
  74
  75     <para>You must make the following configuration decisions while installing the first AFS machine. To speed the installation
  76     itself, it is best to make the decisions before beginning. See the chapter in the <emphasis>OpenAFS Administration
  77     Guide</emphasis> about issues in cell administration and configuration for detailed guidelines. <indexterm>
  78         <primary>cell name</primary>
  79
  80         <secondary>choosing</secondary>
  81       </indexterm> <indexterm>
  82         <primary>AFS filespace</primary>
  83
  84         <secondary>deciding how to configure</secondary>
  85       </indexterm> <indexterm>
  86         <primary>filespace</primary>
  87
  88         <see>AFS filespace</see>
  89       </indexterm> <itemizedlist>
  90         <listitem>
  91           <para>Select the first AFS machine</para>
  92         </listitem>
  93
  94         <listitem>
  95           <para>Select the cell name</para>
  96         </listitem>
  97
  98         <listitem>
  99           <para>Decide which partitions or logical volumes to configure as AFS server partitions, and choose the directory names on
 100           which to mount them</para>
 101         </listitem>
 102
 103         <listitem>
 104           <para>Decide how big to make the client cache</para>
 105         </listitem>
 106
 107         <listitem>
 108           <para>Decide how to configure the top levels of your cell's AFS filespace</para>
 109         </listitem>
 110       </itemizedlist></para>
 111
 112     <para>This chapter is divided into three large sections corresponding to the three parts of installing the first AFS machine.
 113     Perform all of the steps in the order they appear. Each functional section begins with a summary of the procedures to perform.
 114     The sections are as follows: <itemizedlist>
 115         <listitem>
 116           <para>Installing server functionality (begins in <link linkend="HDRWQ18">Overview: Installing Server
 117           Functionality</link>)</para>
 118         </listitem>
 119
 120         <listitem>
 121           <para>Installing client functionality (begins in <link linkend="HDRWQ63">Overview: Installing Client
 122           Functionality</link>)</para>
 123         </listitem>
 124
 125         <listitem>
 126           <para>Configuring your cell's filespace, establishing further security mechanisms, and enabling access to foreign cells
 127           (begins in <link linkend="HDRWQ71">Overview: Completing the Installation of the First AFS Machine</link>)</para>
 128         </listitem>
 129       </itemizedlist></para>
 130
 131     <indexterm>
 132       <primary>overview</primary>
 133
 134       <secondary>installing server functionality on first AFS machine</secondary>
 135     </indexterm>
 136
 137     <indexterm>
 138       <primary>first AFS machine</primary>
 139
 140       <secondary>server functionality</secondary>
 141     </indexterm>
 142
 143     <indexterm>
 144       <primary>installing</primary>
 145
 146       <secondary>server functionality</secondary>
 147
 148       <tertiary>first AFS machine</tertiary>
 149     </indexterm>
 150   </sect1>
 151
 152   <sect1 id="HDRWQ18">
 153     <title>Overview: Installing Server Functionality</title>
 154
 155     <para>In the first phase of installing your cell's first AFS machine, you install file server and database server functionality
 156     by performing the following procedures:
 157     <orderedlist>
 158         <listitem>
 159           <para>Choose which machine to install as the first AFS machine</para>
 160         </listitem>
 161
 162         <listitem>
 163           <para>Create AFS-related directories on the local disk</para>
 164         </listitem>
 165
 166         <listitem>
 167           <para>Incorporate AFS modifications into the machine's kernel</para>
 168         </listitem>
 169
 170         <listitem>
 171           <para>Configure partitions or logical volumes for storing AFS volumes</para>
 172         </listitem>
 173
 174         <listitem>
 175           <para>On some system types, install and configure an AFS-modified version of the <emphasis role="bold">fsck</emphasis>
 176           program</para>
 177         </listitem>
 178
 179         <listitem>
 180           <para>If the machine is to remain a client machine, incorporate AFS into its authentication system</para>
 181         </listitem>
 182
 183         <listitem>
 184           <para>Start the Basic OverSeer (BOS) Server</para>
 185         </listitem>
 186
 187         <listitem>
 188           <para>Define the cell name and the machine's cell membership</para>
 189         </listitem>
 190
 191         <listitem>
 192           <para>Start the database server processes: Backup Server, Protection Server, and Volume Location
 193           (VL) Server</para>
 194         </listitem>
 195
 196         <listitem>
 197           <para>Configure initial security mechanisms</para>
 198         </listitem>
 199
 200         <listitem>
 201           <para>Start the <emphasis role="bold">fs</emphasis> process, which incorporates three component processes: the File
 202           Server, Volume Server, and Salvager</para>
 203         </listitem>
 204
 205         <listitem>
 206           <para>Optionally, start the server portion of the Update Server</para>
 207         </listitem>
 208
 209       </orderedlist></para>
 210   </sect1>
 211
 212   <sect1 id="HDRWQ19">
 213     <title>Choosing the First AFS Machine</title>
 214
 215     <para>The first AFS machine you install must have sufficient disk space to store AFS volumes. To take best advantage of AFS's
 216     capabilities, store client-side binaries as well as user files in volumes. When you later install additional file server
 217     machines in your cell, you can distribute these volumes among the different machines as you see fit.</para>
 218
 219     <para>These instructions configure the first AFS machine as a <emphasis>database server machine</emphasis>, the <emphasis>binary
 220     distribution machine</emphasis> for its system type, and the cell's <emphasis>system control machine</emphasis>. For a
 221     description of these roles, see the <emphasis>OpenAFS Administration Guide</emphasis>.</para>
 222
 223     <para>Installation of additional machines is simplest if the first machine has the lowest IP address of any database server
 224     machine you currently plan to install. If you later install database server functionality on a machine with a lower IP address,
 225     you must first update the <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file on all of your cell's client machines.
 226     For more details, see <link linkend="HDRWQ114">Installing Database Server Functionality</link>.</para>
 227   </sect1>
 228
 229   <sect1 id="Header_32">
 230     <title>Creating AFS Directories</title>
 231
 232     <indexterm>
 233       <primary>usr/afs directory</primary>
 234
 235       <secondary>first AFS machine</secondary>
 236     </indexterm>
 237
 238     <indexterm>
 239       <primary>first AFS machine</primary>
 240
 241       <secondary>/usr/afs directory</secondary>
 242     </indexterm>
 243
 244     <indexterm>
 245       <primary>creating</primary>
 246
 247       <secondary>/usr/afs directory</secondary>
 248
 249       <tertiary>first AFS machine</tertiary>
 250     </indexterm>
 251
 252     <indexterm>
 253       <primary>usr/vice/etc directory</primary>
 254
 255       <secondary>first AFS machine</secondary>
 256     </indexterm>
 257
 258     <indexterm>
 259       <primary>first AFS machine</primary>
 260
 261       <secondary>/usr/vice/etc directory</secondary>
 262     </indexterm>
 263
 264     <indexterm>
 265       <primary>creating</primary>
 266
 267       <secondary>/usr/vice/etc directory</secondary>
 268
 269       <tertiary>first AFS machine</tertiary>
 270     </indexterm>
 271
 272     <indexterm>
 273       <primary>/ as start to file and directory names</primary>
 274
 275       <secondary>see alphabetized entries without initial slash</secondary>
 276     </indexterm>
 277
 278     <para>If you are installing from packages (such as Debian .deb or
 279     Fedora/SuSe .rpm files), you should now install all of the available
 280     OpenAFS packages for your system type. Typically, these will include
 281     packages for client and server functionality, and a seperate package
 282     containing a suitable kernel module for your running kernel. Consult
 283     the package lists on the OpenAFS website to determine the packages
 284     appropriate for your system.</para>
 285
 286     <para>If you are installing from a tarfile, or from a locally compiled
 287     source tree you should create the <emphasis role="bold">/usr/afs</emphasis>
 288     and <emphasis role="bold">/usr/vice/etc</emphasis> directories on the
 289     local disk, to house server and client files respectively. Subsequent
 290     instructions copy files from the distribution tarfile into them. </para>
 291 <programlisting>
 292    # <emphasis role="bold">mkdir /usr/afs</emphasis>
 293    # <emphasis role="bold">mkdir /usr/vice</emphasis>
 294    # <emphasis role="bold">mkdir /usr/vice/etc</emphasis>
 295 </programlisting>
 296   </sect1>
 297
 298   <sect1 id="HDRWQ20">
 299     <title>Performing Platform-Specific Procedures</title>
 300
 301     <para>Several of the initial procedures for installing a file server machine differ for each system type. For convenience, the
 302     following sections group them together for each system type: <itemizedlist>
 303         <indexterm>
 304           <primary>kernel extensions</primary>
 305
 306           <see>AFS kernel extensions</see>
 307         </indexterm>
 308
 309         <indexterm>
 310           <primary>loading AFS kernel extensions</primary>
 311
 312           <see>incorporating</see>
 313         </indexterm>
 314
 315         <indexterm>
 316           <primary>building</primary>
 317
 318           <secondary>AFS extensions into kernel</secondary>
 319
 320           <see>incorporating AFS kernel extensions</see>
 321         </indexterm>
 322
 323         <listitem>
 324           <para>Incorporate AFS modifications into the kernel.</para>
 325
 326           <para>The kernel on every AFS client machine and, on some systems,
 327           the AFS fileservers, must incorporate AFS extensions. On machines
 328           that use a dynamic kernel module loader, it is conventional to
 329           alter the machine's initialization script to load the AFS extensions
 330           at each reboot. <indexterm>
 331               <primary>AFS server partition</primary>
 332
 333               <secondary>mounted on /vicep directory</secondary>
 334             </indexterm> <indexterm>
 335               <primary>partition</primary>
 336
 337               <see>AFS server partition</see>
 338             </indexterm> <indexterm>
 339               <primary>logical volume</primary>
 340
 341               <see>AFS server partition</see>
 342             </indexterm> <indexterm>
 343               <primary>requirements</primary>
 344
 345               <secondary>AFS server partition name and location</secondary>
 346             </indexterm> <indexterm>
 347               <primary>naming conventions for AFS server partition</primary>
 348             </indexterm> <indexterm>
 349               <primary>vicep<emphasis>xx</emphasis> directory</primary>
 350
 351               <see>AFS server partition</see>
 352             </indexterm> <indexterm>
 353               <primary>directories</primary>
 354
 355               <secondary>/vicep<emphasis>xx</emphasis></secondary>
 356
 357               <see>AFS server partition</see>
 358             </indexterm></para>
 359         </listitem>
 360
 361         <listitem>
 362           <para>Configure server partitions or logical volumes to house AFS volumes.</para>
 363
 364           <para>Every AFS file server machine must have at least one partition or logical volume dedicated to storing AFS volumes
 365           (for convenience, the documentation hereafter refers to partitions only). Each server partition is mounted at a directory
 366           named <emphasis role="bold">/vicep</emphasis><replaceable>xx</replaceable>, where <replaceable>xx</replaceable> is one or
 367           two lowercase letters. By convention, the first 26 partitions are mounted on the directories called <emphasis
 368           role="bold">/vicepa</emphasis> through <emphasis role="bold">/vicepz</emphasis>, the 27th one is mounted on the <emphasis
 369           role="bold">/vicepaa</emphasis> directory, and so on through <emphasis role="bold">/vicepaz</emphasis> and <emphasis
 370           role="bold">/vicepba</emphasis>, continuing up to the index corresponding to the maximum number of server partitions
 371           supported in the current version of AFS (which is specified in the <emphasis>OpenAFS Release Notes</emphasis>).</para>
 372
 373           <para>The <emphasis role="bold">/vicep</emphasis><replaceable>xx</replaceable> directories must reside in the file server
 374           machine's root directory, not in one of its subdirectories (for example, <emphasis role="bold">/usr/vicepa</emphasis> is
 375           not an acceptable directory location).
 376
 377           The <emphasis role="bold">fileserver</emphasis> will refuse to
 378           mount
 379           any <emphasis role="bold">/vicep</emphasis><replaceable>xx</replaceable>
 380           folders that are not separate partitions. </para>
 381
 382           <warning>
 383             <para>The separate partition requirement may be overridden by
 384               creating a file named
 385               <emphasis role="bold">/vicep<replaceable>xx</replaceable>/AlwaysAttach</emphasis>;
 386               however, mixed-use partitions, whether cache or fileserver,
 387               have the risk that a non-AFS use will fill the partition and
 388               not leave enough free space for AFS.  Even though it is
 389               allowed, be wary of configuring a mixed-use partition
 390               without understanding the ramifications of doing so with the
 391               workload on your filesystem.
 392               <indexterm>
 393                 <primary>AFS server partition</primary>
 394                 <secondary>AlwaysAttach</secondary>
 395               </indexterm>
 396             </para>
 397           </warning>
 398
 399           <para>You can also add or remove server partitions on an existing file server machine. For instructions, see the chapter
 400           in the <emphasis>OpenAFS Administration Guide</emphasis> about maintaining server machines.</para>
 401
 402           <note>
 403             <para>Not all file system types supported by an operating system are necessarily supported as AFS server partitions. For
 404             possible restrictions, see the <emphasis>OpenAFS Release Notes</emphasis>.</para>
 405           </note>
 406         </listitem>
 407
 408         <listitem>
 409           <para>On system types using the <emphasis role="bold">inode</emphasis> storage format, install and configure a modified <emphasis role="bold">fsck</emphasis> program which
 410           recognizes the structures that the File Server uses to organize volume data on AFS server partitions. The <emphasis
 411           role="bold">fsck</emphasis> program provided with the operating system does not understand the AFS data structures, and so
 412           removes them to the <emphasis role="bold">lost+found</emphasis> directory.</para>
 413         </listitem>
 414
 415         <listitem>
 416           <para>If the machine is to remain an AFS client machine, modify the machine's authentication system so that users obtain
 417           an AFS token as they log into the local file system. Using AFS is simpler and more convenient for your users if you make
 418           the modifications on all client machines. Otherwise, users must perform a two or three step login procedure (login to the local
 419           system, then obtain Kerberos credentials, and then issue the <emphasis role="bold">aklog</emphasis> command). For further discussion of AFS
 420           authentication, see the chapter in the <emphasis>OpenAFS Administration Guide</emphasis> about cell configuration and
 421           administration issues.</para>
 422         </listitem>
 423       </itemizedlist></para>
 424
 425     <para>To continue, proceed to the appropriate section: <itemizedlist>
 426         <listitem>
 427           <para><link linkend="HDRWQ41">Getting Started on Linux Systems</link></para>
 428         </listitem>
 429
 430         <listitem>
 431           <para><link linkend="HDRWQ45">Getting Started on Solaris Systems</link></para>
 432         </listitem>
 433
 434         <listitem>
 435           <para><link linkend="HDRWQ21">Getting Started on AIX Systems</link></para>
 436         </listitem>
 437       </itemizedlist></para>
 438   </sect1>
 439
 440   <sect1 id="HDRWQ41">
 441     <title>Getting Started on Linux Systems</title>
 442
 443     <indexterm>
 444       <primary>replacing fsck program</primary>
 445
 446       <secondary>not necessary on Linux</secondary>
 447     </indexterm>
 448
 449     <indexterm>
 450       <primary>fsck program</primary>
 451
 452       <secondary>on first AFS machine</secondary>
 453
 454       <tertiary>Linux</tertiary>
 455     </indexterm>
 456
 457     <indexterm>
 458       <primary>first AFS machine</primary>
 459
 460       <secondary>fsck program</secondary>
 461
 462       <tertiary>on Linux</tertiary>
 463     </indexterm>
 464
 465     <indexterm>
 466       <primary>Linux</primary>
 467
 468       <secondary>fsck program replacement not necessary</secondary>
 469     </indexterm>
 470
 471     <para>Since this guide was originally written, the procedure for starting
 472     OpenAFS has diverged significantly between different Linux distributions.
 473     The instructions that follow are appropriate for both the Fedora and
 474     RedHat Enterprise Linux packages distributed by OpenAFS. Additional
 475     instructions are provided for those building from source.</para>
 476
 477     <para>Begin by running the AFS client startup scripts, which call the
 478     <emphasis role="bold">modprobe</emphasis> program to dynamically
 479     load the AFS modifications into the kernel. Then create partitions for
 480     storing AFS volumes. You do not need to replace the Linux <emphasis
 481     role="bold">fsck</emphasis> program. If the machine is to remain an
 482     AFS client machine, incorporate AFS into the machine's Pluggable
 483     Authentication Module (PAM) scheme. <indexterm>
 484         <primary>incorporating AFS kernel extensions</primary>
 485
 486         <secondary>first AFS machine</secondary>
 487
 488         <tertiary>Linux</tertiary>
 489       </indexterm> <indexterm>
 490         <primary>AFS kernel extensions</primary>
 491
 492         <secondary>on first AFS machine</secondary>
 493
 494         <tertiary>Linux</tertiary>
 495       </indexterm> <indexterm>
 496         <primary>first AFS machine</primary>
 497
 498         <secondary>AFS kernel extensions</secondary>
 499
 500         <tertiary>on Linux</tertiary>
 501       </indexterm> <indexterm>
 502         <primary>Linux</primary>
 503
 504         <secondary>AFS kernel extensions</secondary>
 505
 506         <tertiary>on first AFS machine</tertiary>
 507       </indexterm></para>
 508
 509     <sect2 id="HDRWQ42">
 510       <title>Loading AFS into the Linux Kernel</title>
 511
 512       <para>The <emphasis role="bold">modprobe</emphasis> program is the dynamic kernel loader for Linux. Linux does not support
 513       incorporation of AFS modifications during a kernel build.</para>
 514
 515       <para>For AFS to function correctly, the <emphasis role="bold">modprobe</emphasis> program must run each time the machine
 516       reboots, so your distribution's AFS initialization script invokes it automatically. The script also includes
 517       commands that select the appropriate AFS library file automatically. In this section you run the script.</para>
 518
 519       <para>In later sections you verify that the script correctly initializes all AFS components, then activate a configuration
 520       variable, which results in the script being incorporated into the Linux startup and shutdown sequence.</para>
 521
 522       <para>The procedure for starting up OpenAFS depends upon your distribution</para>
 523       <sect3>
 524         <title>Fedora and RedHat Enterprise Linux</title>
 525         <para>OpenAFS provides RPMS for all current Fedora and RedHat Enterprise Linux (RHEL) releases on the OpenAFS web site and the OpenAFS yum repository.
 526         <orderedlist>
 527           <listitem>
 528             <para>Browse to
 529             http://dl.openafs.org/dl/openafs/<replaceable>VERSION</replaceable>,
 530             where VERSION is the latest stable release of
 531             OpenAFS. Download the
 532             openafs-repository-<replaceable>VERSION</replaceable>.noarch.rpm
 533             file for Fedora systems or the
 534             openafs-repository-rhel-<replaceable>VERSION</replaceable>.noarch.rpm
 535             file for RedHat-based systems.
 536             </para>
 537           </listitem>
 538           <listitem>
 539             <para>Install the downloaded RPM file using the following command:
 540               <programlisting>
 541                 # rpm -U openafs-repository*.rpm
 542               </programlisting>
 543             </para>
 544           </listitem>
 545           <listitem>
 546             <para>Install the RPM set for your operating system using the yum command as follows:
 547               <programlisting>
 548                 # yum -y install openafs-client openafs-server openafs-krb5 kmod-openafs
 549               </programlisting>
 550
 551             </para>
 552             <para>Alternatively, you may use dynamically-compiled kernel
 553               modules if you have the kernel headers, a compiler, and the
 554               dkms package from
 555               <ulink url="http://fedoraproject.org/wiki/EPEL"><citetitle>EPEL</citetitle></ulink> installed.
 556
 557             </para>
 558             <para>To use dynamically-compiled kernel modules instead of statically compiled modules, use the following command instead of the kmod-openafs as shown above:
 559               <programlisting>
 560                 # yum install openafs-client openafs-server openafs-krb5 dkms-openafs
 561               </programlisting>
 562             </para>
 563           </listitem>
 564 <!-- If you do this with current RHEL and Fedora releases you end up with
 565      a dynroot'd client running - this breaks setting up the root.afs volume
 566      as described later in this guide
 567           <listitem>
 568             <para>Run the AFS initialization script to load AFS extensions into
 569             the kernel. You can ignore any error messages about the inability
 570             to start the BOS Server or the Cache Manager or AFS client.</para>
 571 <programlisting>
 572    # <emphasis role="bold">/etc/rc.d/init.d/openafs-client  start</emphasis>
 573 </programlisting>
 574           </listitem>
 575 -->
 576         </orderedlist>
 577       </para>
 578       </sect3>
 579       <sect3>
 580         <title>Debian and Ubuntu Linux</title>
 581         <para>OpenAFS is available as binary packages from the Debian
 582           linux distribution and its derivatives such as Ubuntu.
 583         <orderedlist>
 584           <listitem>
 585             <para>Install the client and server packages using the following command:
 586               <programlisting>
 587 # apt-get install openafs-client openafs-modules-dkms openafs-krb5 \
 588   openafs-fileserver openafs-dbserver
 589               </programlisting>
 590               You will be prompted by debconf to select your cell name and
 591               the size of your local cache.
 592             </para>
 593           </listitem>
 594         </orderedlist>
 595       </para>
 596       <para>The Debian package also includes helper scripts
 597         <literal>afs-newcell</literal> and <literal>afs-rootvol</literal>,
 598         which can automate much of the remainder of this document.
 599       </para>
 600       </sect3>
 601       <sect3>
 602          <title>Systems packaged as tar files</title>
 603          <para>If you are running a system where the OpenAFS Binary Distribution
 604          is provided as a tar file, or where you have built the system from
 605          source yourself, you need to install the relevant components by hand
 606          </para>
 607          <orderedlist>
 608
 609           <listitem>
 610             <para>Unpack the distribution tarball. The examples below assume
 611             that you have unpacked the files into the
 612             <emphasis role="bold">/tmp/afsdist</emphasis> directory. If you
 613             pick a different location, substitute this in all of the following
 614             examples. Once you have unpacked the distribution,
 615             change directory as indicated.
 616 <programlisting>
 617   # <emphasis role="bold">cd /tmp/afsdist/linux/dest/root.client/usr/vice/etc</emphasis>
 618 </programlisting></para>
 619           </listitem>
 620
 621           <listitem>
 622             <para>Copy the AFS kernel library files to the local <emphasis role="bold">/usr/vice/etc/modload</emphasis> directory.
 623             The filenames for the libraries have the format <emphasis
 624             role="bold">libafs-</emphasis><replaceable>version</replaceable><emphasis role="bold">.o</emphasis>, where
 625             <replaceable>version</replaceable> indicates the kernel build level. The string <emphasis role="bold">.mp</emphasis> in
 626             the <replaceable>version</replaceable> indicates that the file is appropriate for machines running a multiprocessor
 627             kernel. <programlisting>
 628    # <emphasis role="bold">cp -rp  modload  /usr/vice/etc</emphasis>
 629 </programlisting></para>
 630           </listitem>
 631
 632           <listitem>
 633             <para>Copy the AFS initialization script to the local directory for initialization files (by convention, <emphasis
 634             role="bold">/etc/rc.d/init.d</emphasis> on Linux machines). Note the removal of the <emphasis role="bold">.rc</emphasis>
 635             extension as you copy the script. <programlisting>
 636    # <emphasis role="bold">cp -p   afs.rc  /etc/rc.d/init.d/afs</emphasis>
 637 </programlisting></para>
 638           </listitem>
 639
 640 <!-- I don't think we need to do this for Linux, and it complicates things if
 641      dynroot is enabled ...
 642           <listitem>
 643             <para>Run the AFS initialization script to load AFS extensions into the kernel. You can ignore any error messages about
 644             the inability to start the BOS Server or the Cache Manager or AFS client.</para>
 645 <programlisting>
 646    # <emphasis role="bold">/etc/rc.d/init.d/afs start</emphasis>
 647 </programlisting>
 648           </listitem>
 649 -->
 650         </orderedlist>
 651
 652       <indexterm>
 653         <primary>configuring</primary>
 654
 655         <secondary>AFS server partition on first AFS machine</secondary>
 656
 657         <tertiary>Linux</tertiary>
 658       </indexterm>
 659
 660       <indexterm>
 661         <primary>AFS server partition</primary>
 662
 663         <secondary>configuring on first AFS machine</secondary>
 664
 665         <tertiary>Linux</tertiary>
 666       </indexterm>
 667
 668       <indexterm>
 669         <primary>first AFS machine</primary>
 670
 671         <secondary>AFS server partition</secondary>
 672
 673         <tertiary>on Linux</tertiary>
 674       </indexterm>
 675
 676       <indexterm>
 677         <primary>Linux</primary>
 678
 679         <secondary>AFS server partition</secondary>
 680
 681         <tertiary>on first AFS machine</tertiary>
 682       </indexterm>
 683     </sect3>
 684     </sect2>
 685
 686     <sect2 id="HDRWQ43">
 687       <title>Configuring Server Partitions on Linux Systems</title>
 688
 689       <para>Every AFS file server machine must have at least one partition or logical volume dedicated to storing AFS volumes. Each
 690       server partition is mounted at a directory named <emphasis role="bold">/vicep</emphasis><replaceable>xx</replaceable>, where
 691       <replaceable>xx</replaceable> is one or two lowercase letters. The <emphasis
 692       role="bold">/vicep</emphasis><replaceable>xx</replaceable> directories must reside in the file server machine's root
 693       directory, not in one of its subdirectories (for example, <emphasis role="bold">/usr/vicepa</emphasis> is not an acceptable
 694       directory location). For additional information, see <link linkend="HDRWQ20">Performing Platform-Specific Procedures</link>.
 695       <orderedlist>
 696           <listitem>
 697             <para>Create a directory called <emphasis role="bold">/vicep</emphasis><replaceable>xx</replaceable> for each AFS server
 698             partition you are configuring (there must be at least one). Repeat the command for each partition. <programlisting>
 699    # <emphasis role="bold">mkdir /vicep</emphasis><replaceable>xx</replaceable>
 700 </programlisting></para>
 701           </listitem>
 702
 703           <listitem>
 704             <para>Add a line with the following format to the file systems registry file, <emphasis
 705             role="bold">/etc/fstab</emphasis>, for each directory just created. The entry maps the directory name to the disk
 706             partition to be mounted on it. <programlisting>
 707    /dev/<replaceable>disk</replaceable>  /vicep<replaceable>xx</replaceable>  ext2  defaults  0  2
 708 </programlisting></para>
 709
 710             <para>The following is an example for the first partition being configured.</para>
 711
 712             <programlisting>
 713    /dev/sda8 /vicepa ext2 defaults 0 2
 714 </programlisting>
 715           </listitem>
 716
 717           <listitem>
 718             <para>Create a file system on each partition that is to be mounted at a <emphasis
 719             role="bold">/vicep</emphasis><replaceable>xx</replaceable> directory. The following command is probably appropriate, but
 720             consult the Linux documentation for more information. <programlisting>
 721    # <emphasis role="bold">mkfs -v /dev/</emphasis><replaceable>disk</replaceable>
 722 </programlisting></para>
 723           </listitem>
 724
 725           <listitem>
 726             <para>Mount each partition by issuing either the <emphasis role="bold">mount -a</emphasis> command to mount all
 727             partitions at once or the <emphasis role="bold">mount</emphasis> command to mount each partition in turn.</para>
 728           </listitem>
 729
 730           <listitem>
 731             <para>If you plan to retain client functionality on this machine after completing the installation, proceed to <link
 732             linkend="HDRWQ44">Enabling AFS Login on Linux Systems</link>. Otherwise, proceed to <link linkend="HDRWQ50">Starting the
 733             BOS Server</link>.</para>
 734           </listitem>
 735         </orderedlist></para>
 736
 737       <indexterm>
 738         <primary>enabling AFS login</primary>
 739
 740         <secondary>file server machine</secondary>
 741
 742         <tertiary>Linux</tertiary>
 743       </indexterm>
 744
 745       <indexterm>
 746         <primary>AFS login</primary>
 747
 748         <secondary>on file server machine</secondary>
 749
 750         <tertiary>Linux</tertiary>
 751       </indexterm>
 752
 753       <indexterm>
 754         <primary>first AFS machine</primary>
 755
 756         <secondary>AFS login</secondary>
 757
 758         <tertiary>on Linux</tertiary>
 759       </indexterm>
 760
 761       <indexterm>
 762         <primary>Linux</primary>
 763
 764         <secondary>AFS login</secondary>
 765
 766         <tertiary>on file server machine</tertiary>
 767       </indexterm>
 768
 769       <indexterm>
 770         <primary>PAM</primary>
 771
 772         <secondary>on Linux</secondary>
 773
 774         <tertiary>file server machine</tertiary>
 775       </indexterm>
 776     </sect2>
 777
 778     <sect2 id="HDRWQ44">
 779       <title>Enabling AFS Login on Linux Systems</title>
 780
 781       <note>
 782         <para>If you plan to remove client functionality from this machine
 783         after completing the installation, skip this section and proceed
 784         to <link linkend="HDRWQ50">Starting the BOS Server</link>.</para>
 785       </note>
 786
 787       <para>At this point you incorporate AFS into the operating system's
 788       Pluggable Authentication Module (PAM) scheme.  PAM integrates all
 789       authentication mechanisms on the machine, including login, to provide
 790       the security infrastructure for authenticated access to and from the
 791       machine.</para>
 792
 793       <para>You should first configure your system to obtain Kerberos v5
 794       tickets as part of the authentication process, and then run an AFS PAM
 795       module to obtain tokens from those tickets after authentication.  Many
 796       Linux distributions come with a Kerberos v5 PAM module (usually called
 797       pam-krb5 or pam_krb5), or you can download and install <ulink
 798       url="http://www.eyrie.org/~eagle/software/pam-krb5">Russ Allbery's
 799       Kerberos v5 PAM module</ulink>, which is tested regularly with AFS.
 800       See the instructions of whatever PAM module you use for how to
 801       configure it.</para>
 802
 803       <para>Some Kerberos v5 PAM modules do come with native AFS support
 804       (usually requiring the Heimdal Kerberos implementation rather than the
 805       MIT Kerberos implementation).  If you are using one of those PAM
 806       modules, you can configure it to obtain AFS tokens.  It's more common,
 807       however, to separate the AFS token acquisition into a separate PAM
 808       module.</para>
 809
 810       <para>The recommended AFS PAM module is <ulink
 811       url="http://www.eyrie.org/~eagle/software/pam-afs-session/">Russ
 812       Allbery's pam-afs-session module</ulink>.  It should work with any of
 813       the Kerberos v5 PAM modules.  To add it to the PAM configuration, you
 814       often only need to add configuration to the session group:</para>
 815
 816       <example>
 817         <title>Linux PAM session example</title>
 818         <literallayout>session  required  pam_afs_session.so</literallayout>
 819       </example>
 820
 821       <para>If you also want to obtain AFS tokens for <command>scp</command>
 822       and similar commands that don't open a session, you will also need to
 823       add the AFS PAM module to the auth group so that the PAM
 824       <function>setcred</function> call will obtain tokens.  The
 825       <literal>pam_afs_session</literal> module will always return success
 826       for authentication so that it can be added to the auth group only for
 827       <function>setcred</function>, so make sure that it's not marked as
 828       <literal>sufficient</literal>.</para>
 829
 830       <example>
 831         <title>Linux PAM auth example</title>
 832 <literallayout>auth  [success=ok default=1]  pam_krb5.so
 833 auth  [default=done]          pam_afs_session.so
 834 auth  required                pam_unix.so try_first_pass</literallayout>
 835       </example>
 836
 837       <para>This example will work if you want to try Kerberos v5 first and
 838       then fall back to regular Unix authentication.
 839       <literal>success=ok</literal> for the Kerberos PAM module followed by
 840       <literal>default=done</literal> for the AFS PAM module will cause a
 841       successful Kerberos login to run the AFS PAM module and then skip the
 842       Unix authentication module.  <literal>default=1</literal> on the
 843       Kerberos PAM module causes failure of that module to skip the next
 844       module (the AFS PAM module) and fall back to the Unix module.  If you
 845       want to try Unix authentication first and rearrange the order, be sure
 846       to use <literal>default=die</literal> instead.</para>
 847
 848       <para>The PAM configuration is stored in different places in different
 849       Linux distributions.  On Red Hat, look in
 850       <filename>/etc/pam.d/system-auth</filename>.  On Debian and
 851       derivatives, look in <filename>/etc/pam.d/common-session</filename>
 852       and <filename>/etc/pam.d/common-auth</filename>.</para>
 853
 854       <para>For additional configuration examples and the configuration
 855       options of the AFS PAM module, see its documentation.  For more
 856       details on the available options for the PAM configuration, see the
 857       Linux PAM documentation.</para>
 858
 859       <para>Sites which still require <command>kaserver</command> or
 860       external Kerberos v4 authentication should consult <link
 861       linkend="KAS015">Enabling kaserver based AFS Login on Linux
 862       Systems</link> for details of how to enable AFS login on Linux.</para>
 863
 864       <para>Proceed to <link linkend="HDRWQ50">Starting the BOS
 865       Server</link> (or if referring to these instructions while installing
 866       an additional file server machine, return to <link
 867       linkend="HDRWQ108">Starting Server Programs</link>).</para>
 868     </sect2>
 869   </sect1>
 870
 871   <sect1 id="HDRWQ45">
 872     <title>Getting Started on Solaris Systems</title>
 873
 874     <para>Begin by running the AFS initialization script to call the <emphasis role="bold">modload</emphasis> program distributed by
 875     Sun Microsystems, which dynamically loads AFS modifications into the kernel. Then create partitions for storing AFS volumes, and
 876     install and configure the AFS-modified <emphasis role="bold">fsck</emphasis> program to run on AFS server partitions. If the
 877     machine is to remain an AFS client machine, incorporate AFS into the machine's Pluggable Authentication Module (PAM) scheme.
 878     <indexterm>
 879         <primary>incorporating AFS kernel extensions</primary>
 880
 881         <secondary>first AFS machine</secondary>
 882
 883         <tertiary>Solaris</tertiary>
 884       </indexterm> <indexterm>
 885         <primary>AFS kernel extensions</primary>
 886
 887         <secondary>on first AFS machine</secondary>
 888
 889         <tertiary>Solaris</tertiary>
 890       </indexterm> <indexterm>
 891         <primary>first AFS machine</primary>
 892
 893         <secondary>AFS kernel extensions</secondary>
 894
 895         <tertiary>on Solaris</tertiary>
 896       </indexterm> <indexterm>
 897         <primary>Solaris</primary>
 898
 899         <secondary>AFS kernel extensions</secondary>
 900
 901         <tertiary>on first AFS machine</tertiary>
 902       </indexterm></para>
 903
 904     <sect2 id="HDRWQ46">
 905       <title>Loading AFS into the Solaris Kernel</title>
 906
 907       <para>The <emphasis role="bold">modload</emphasis> program is the dynamic kernel loader provided by Sun Microsystems for
 908       Solaris systems. Solaris does not support incorporation of AFS modifications during a kernel build.</para>
 909
 910       <para>For AFS to function correctly, the <emphasis role="bold">modload</emphasis> program must run each time the machine
 911       reboots, so the AFS initialization script (included on the AFS CD-ROM) invokes it automatically. In this section you copy the
 912       appropriate AFS library file to the location where the <emphasis role="bold">modload</emphasis> program accesses it and then
 913       run the script.</para>
 914
 915       <para>In later sections you verify that the script correctly initializes all AFS components, then create the links that
 916       incorporate AFS into the Solaris startup and shutdown sequence. <orderedlist>
 917           <listitem>
 918             <para>Unpack the OpenAFS Solaris distribution tarball. The examples
 919             below assume that you have unpacked the files into the
 920             <emphasis role="bold">/tmp/afsdist</emphasis> directory. If you
 921             pick a diferent location, substitute this in all of the following
 922             exmaples. Once you have unpacked the distribution, change directory
 923             as indicated.
 924 <programlisting>
 925    # <emphasis role="bold">cd  /tmp/afsdist/sun4x_56/dest/root.client/usr/vice/etc</emphasis>
 926 </programlisting></para>
 927           </listitem>
 928
 929           <listitem>
 930             <para>Copy the AFS initialization script to the local directory for initialization files (by convention, <emphasis
 931             role="bold">/etc/init.d</emphasis> on Solaris machines). Note the removal of the <emphasis role="bold">.rc</emphasis>
 932             extension as you copy the script. <programlisting>
 933    # <emphasis role="bold">cp -p  afs.rc  /etc/init.d/afs</emphasis>
 934 </programlisting></para>
 935           </listitem>
 936
 937           <listitem>
 938             <para>Copy the appropriate AFS kernel library file to the local file <emphasis
 939             role="bold">/kernel/fs/afs</emphasis>.</para>
 940
 941             <para>If the machine is running Solaris 11 on the x86_64 platform:</para>
 942
 943             <programlisting>
 944    # <emphasis role="bold">cp -p modload/libafs64.o /kernel/drv/amd64/afs</emphasis>
 945 </programlisting>
 946
 947             <para>If the machine is running Solaris 10 on the x86_64 platform:</para>
 948
 949             <programlisting>
 950    # <emphasis role="bold">cp -p modload/libafs64.o /kernel/fs/amd64/afs</emphasis>
 951 </programlisting>
 952
 953             <para>If the machine is running Solaris 2.6 or the 32-bit version of Solaris 7, its kernel supports NFS server
 954             functionality, and the <emphasis role="bold">nfsd</emphasis> process is running:</para>
 955
 956             <programlisting>
 957    # <emphasis role="bold">cp -p modload/libafs.o /kernel/fs/afs</emphasis>
 958 </programlisting>
 959
 960             <para>If the machine is running Solaris 2.6 or the 32-bit version of Solaris 7, and its kernel does not support NFS
 961             server functionality or the <emphasis role="bold">nfsd</emphasis> process is not running:</para>
 962
 963             <programlisting>
 964    # <emphasis role="bold">cp -p modload/libafs.nonfs.o /kernel/fs/afs</emphasis>
 965 </programlisting>
 966
 967             <para>If the machine is running the 64-bit version of Solaris 7, its kernel supports NFS server functionality, and the
 968             <emphasis role="bold">nfsd</emphasis> process is running:</para>
 969
 970             <programlisting>
 971    # <emphasis role="bold">cp -p modload/libafs64.o /kernel/fs/sparcv9/afs</emphasis>
 972 </programlisting>
 973
 974             <para>If the machine is running the 64-bit version of Solaris 7, and its kernel does not support NFS server
 975             functionality or the <emphasis role="bold">nfsd</emphasis> process is not running:</para>
 976
 977             <programlisting>
 978    # <emphasis role="bold">cp -p modload/libafs64.nonfs.o /kernel/fs/sparcv9/afs</emphasis>
 979 </programlisting>
 980           </listitem>
 981
 982           <listitem>
 983             <para>Run the AFS initialization script to load AFS modifications into the kernel. You can ignore any error messages
 984             about the inability to start the BOS Server or the Cache Manager or AFS client. <programlisting>
 985    # <emphasis role="bold">/etc/init.d/afs start</emphasis>
 986 </programlisting></para>
 987
 988             <para>When an entry called <computeroutput>afs</computeroutput> does not already exist in the local <emphasis
 989             role="bold">/etc/name_to_sysnum</emphasis> file, the script automatically creates it and reboots the machine to start
 990             using the new version of the file. If this happens, log in again as the superuser <emphasis role="bold">root</emphasis>
 991             after the reboot and run the initialization script again. This time the required entry exists in the <emphasis
 992             role="bold">/etc/name_to_sysnum</emphasis> file, and the <emphasis role="bold">modload</emphasis> program runs.</para>
 993
 994             <programlisting>
 995    login: <emphasis role="bold">root</emphasis>
 996    Password: <replaceable>root_password</replaceable>
 997    # <emphasis role="bold">/etc/init.d/afs start</emphasis>
 998 </programlisting>
 999           </listitem>
1000         </orderedlist></para>
1001
1002       <indexterm>
1003         <primary>replacing fsck program</primary>
1004
1005         <secondary>first AFS machine</secondary>
1006
1007         <tertiary>Solaris</tertiary>
1008       </indexterm>
1009
1010       <indexterm>
1011         <primary>fsck program</primary>
1012
1013         <secondary>on first AFS machine</secondary>
1014
1015         <tertiary>Solaris</tertiary>
1016       </indexterm>
1017
1018       <indexterm>
1019         <primary>first AFS machine</primary>
1020
1021         <secondary>fsck program</secondary>
1022
1023         <tertiary>on Solaris</tertiary>
1024       </indexterm>
1025
1026       <indexterm>
1027         <primary>Solaris</primary>
1028
1029         <secondary>fsck program</secondary>
1030
1031         <tertiary>on first AFS machine</tertiary>
1032       </indexterm>
1033     </sect2>
1034
1035     <sect2 id="HDRWQ47">
1036       <title>Configuring the AFS-modified fsck Program on Solaris Systems</title>
1037
1038       <para>In this section, you make modifications to guarantee that the appropriate <emphasis role="bold">fsck</emphasis> program
1039       runs on AFS server partitions. The <emphasis role="bold">fsck</emphasis> program provided with the operating system must never
1040       run on AFS server partitions. Because it does not recognize the structures that the File Server uses to organize volume data,
1041       it removes all of the data. To repeat:</para>
1042
1043       <para><emphasis role="bold">Never run the standard fsck program on AFS server partitions. It discards AFS volumes.</emphasis>
1044       <orderedlist>
1045           <listitem>
1046             <para>Create the <emphasis role="bold">/usr/lib/fs/afs</emphasis> directory to house the AFS-modified <emphasis
1047             role="bold">fsck</emphasis> program and related files. <programlisting>
1048    # <emphasis role="bold">mkdir /usr/lib/fs/afs</emphasis>
1049    # <emphasis role="bold">cd /usr/lib/fs/afs</emphasis>
1050 </programlisting></para>
1051           </listitem>
1052
1053           <listitem>
1054             <para>Copy the <emphasis role="bold">vfsck</emphasis> binary to the newly created directory, changing the name as you do
1055             so. <programlisting>
1056    # <emphasis role="bold">cp  /tmp/afsdist/sun4x_56/dest/root.server/etc/vfsck  fsck</emphasis>
1057 </programlisting></para>
1058           </listitem>
1059
1060           <listitem>
1061             <para>Working in the <emphasis role="bold">/usr/lib/fs/afs</emphasis> directory, create the following links to Solaris
1062             libraries: <programlisting>
1063    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/clri</emphasis>
1064    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/df</emphasis>
1065    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/edquota</emphasis>
1066    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/ff</emphasis>
1067    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/fsdb</emphasis>
1068    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/fsirand</emphasis>
1069    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/fstyp</emphasis>
1070    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/labelit</emphasis>
1071    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/lockfs</emphasis>
1072    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/mkfs</emphasis>
1073    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/mount</emphasis>
1074    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/ncheck</emphasis>
1075    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/newfs</emphasis>
1076    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/quot</emphasis>
1077    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/quota</emphasis>
1078    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/quotaoff</emphasis>
1079    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/quotaon</emphasis>
1080    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/repquota</emphasis>
1081    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/tunefs</emphasis>
1082    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/ufsdump</emphasis>
1083    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/ufsrestore</emphasis>
1084    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/volcopy</emphasis>
1085 </programlisting></para>
1086           </listitem>
1087
1088           <listitem>
1089             <para>Append the following line to the end of the file <emphasis role="bold">/etc/dfs/fstypes</emphasis>.
1090             <programlisting>
1091    afs AFS Utilities
1092 </programlisting></para>
1093           </listitem>
1094
1095           <listitem>
1096             <para>Edit the <emphasis role="bold">/sbin/mountall</emphasis> file, making two changes. <itemizedlist>
1097                 <listitem>
1098                   <para>Add an entry for AFS to the <computeroutput>case</computeroutput> statement for option 2, so that it reads
1099                   as follows: <programlisting>
1100    case "$2" in
1101    ufs)    foptions="-o p"
1102            ;;
1103    afs)    foptions="-o p"
1104            ;;
1105    s5)     foptions="-y -t /var/tmp/tmp$$ -D"
1106            ;;
1107    *)      foptions="-y"
1108            ;;
1109 </programlisting></para>
1110                 </listitem>
1111
1112                 <listitem>
1113                   <para>Edit the file so that all AFS and UFS partitions are checked in parallel. Replace the following section of
1114                   code: <programlisting>
1115    # For  fsck purposes, we make a distinction between ufs and
1116    # other file systems
1117    #
1118    if [ "$fstype" = "ufs" ]; then
1119         ufs_fscklist="$ufs_fscklist $fsckdev"
1120         saveentry $fstype "$OPTIONS" $special $mountp
1121         continue
1122    fi
1123 </programlisting></para>
1124
1125                   <para>with the following section of code:</para>
1126
1127                   <programlisting>
1128    # For fsck purposes, we make a distinction between ufs/afs
1129    # and other file systems.
1130    #
1131    if [ "$fstype" = "ufs" -o "$fstype" = "afs" ]; then
1132         ufs_fscklist="$ufs_fscklist $fsckdev"
1133         saveentry $fstype "$OPTIONS" $special $mountp
1134         continue
1135    fi
1136 </programlisting>
1137                 </listitem>
1138               </itemizedlist></para>
1139           </listitem>
1140         </orderedlist></para>
1141
1142       <indexterm>
1143         <primary>configuring</primary>
1144
1145         <secondary>AFS server partition on first AFS machine</secondary>
1146
1147         <tertiary>Solaris</tertiary>
1148       </indexterm>
1149
1150       <indexterm>
1151         <primary>AFS server partition</primary>
1152
1153         <secondary>configuring on first AFS machine</secondary>
1154
1155         <tertiary>Solaris</tertiary>
1156       </indexterm>
1157
1158       <indexterm>
1159         <primary>first AFS machine</primary>
1160
1161         <secondary>AFS server partition</secondary>
1162
1163         <tertiary>on Solaris</tertiary>
1164       </indexterm>
1165
1166       <indexterm>
1167         <primary>Solaris</primary>
1168
1169         <secondary>AFS server partition</secondary>
1170
1171         <tertiary>on first AFS machine</tertiary>
1172       </indexterm>
1173     </sect2>
1174
1175     <sect2 id="HDRWQ48">
1176       <title>Configuring Server Partitions on Solaris Systems</title>
1177
1178       <para>Every AFS file server machine must have at least one partition or logical volume dedicated to storing AFS volumes. Each
1179       server partition is mounted at a directory named <emphasis role="bold">/vicep</emphasis><replaceable>xx</replaceable>, where
1180       <replaceable>xx</replaceable> is one or two lowercase letters. The <emphasis
1181       role="bold">/vicep</emphasis><replaceable>xx</replaceable> directories must reside in the file server machine's root
1182       directory, not in one of its subdirectories (for example, <emphasis role="bold">/usr/vicepa</emphasis> is not an acceptable
1183       directory location). For additional information, see <link linkend="HDRWQ20">Performing Platform-Specific Procedures</link>.
1184       <orderedlist>
1185           <listitem>
1186             <para>Create a directory called <emphasis role="bold">/vicep</emphasis><replaceable>xx</replaceable> for each AFS server
1187             partition you are configuring (there must be at least one). Repeat the command for each partition. <programlisting>
1188    # <emphasis role="bold">mkdir /vicep</emphasis><replaceable>xx</replaceable>
1189 </programlisting></para>
1190           </listitem>
1191
1192           <listitem>
1193             <para>Add a line with the following format to the file systems registry file, <emphasis
1194             role="bold">/etc/vfstab</emphasis>, for each partition to be mounted on a directory created in the previous step. Note
1195             the value <computeroutput>afs</computeroutput> in the fourth field, which tells Solaris to use the AFS-modified
1196             <emphasis role="bold">fsck</emphasis> program on this partition. <programlisting>
1197    /dev/dsk/<replaceable>disk</replaceable>   /dev/rdsk/<replaceable>disk</replaceable>   /vicep<replaceable>xx</replaceable>   afs   <replaceable>boot_order</replaceable>  yes
1198 </programlisting></para>
1199
1200             <para>The following is an example for the first partition being configured.</para>
1201
1202             <programlisting>
1203    /dev/dsk/c0t6d0s1 /dev/rdsk/c0t6d0s1 /vicepa afs 3 yes
1204 </programlisting>
1205           </listitem>
1206
1207           <listitem>
1208             <para>Create a file system on each partition that is to be mounted at a <emphasis
1209             role="bold">/vicep</emphasis><replaceable>xx</replaceable> directory. The following command is probably appropriate, but
1210             consult the Solaris documentation for more information. <programlisting>
1211    # <emphasis role="bold">newfs -v /dev/rdsk/</emphasis><replaceable>disk</replaceable>
1212 </programlisting></para>
1213           </listitem>
1214
1215           <listitem>
1216             <para>Issue the <emphasis role="bold">mountall</emphasis> command to mount all partitions at once.</para>
1217           </listitem>
1218
1219           <listitem>
1220             <para>If you plan to retain client functionality on this machine after completing the installation, proceed to <link
1221             linkend="HDRWQ49">Enabling AFS Login and Editing the File Systems Clean-up Script on Solaris Systems</link>. Otherwise,
1222             proceed to <link linkend="HDRWQ50">Starting the BOS Server</link>.</para>
1223           </listitem>
1224         </orderedlist></para>
1225     </sect2>
1226
1227     <sect2 id="HDRWQ49">
1228       <title>Enabling AFS Login on Solaris Systems</title>
1229       <indexterm>
1230         <primary>enabling AFS login</primary>
1231
1232         <secondary>file server machine</secondary>
1233
1234         <tertiary>Solaris</tertiary>
1235       </indexterm>
1236
1237       <indexterm>
1238         <primary>AFS login</primary>
1239
1240         <secondary>on file server machine</secondary>
1241
1242         <tertiary>Solaris</tertiary>
1243       </indexterm>
1244
1245       <indexterm>
1246         <primary>first AFS machine</primary>
1247
1248         <secondary>AFS login</secondary>
1249
1250         <tertiary>on Solaris</tertiary>
1251       </indexterm>
1252
1253       <indexterm>
1254         <primary>Solaris</primary>
1255
1256         <secondary>AFS login</secondary>
1257
1258         <tertiary>on file server machine</tertiary>
1259       </indexterm>
1260
1261       <indexterm>
1262         <primary>PAM</primary>
1263
1264         <secondary>on Solaris</secondary>
1265
1266         <tertiary>file server machine</tertiary>
1267       </indexterm>
1268
1269       <note>
1270         <para>If you plan to remove client functionality from this machine after completing the installation, skip this section and
1271         proceed to <link linkend="HDRWQ50">Starting the BOS Server</link>.</para>
1272       </note>
1273
1274       <para>At this point you incorporate AFS into the operating system's
1275       Pluggable Authentication Module (PAM) scheme.  PAM integrates all
1276       authentication mechanisms on the machine, including login, to provide
1277       the security infrastructure for authenticated access to and from the
1278       machine.</para>
1279
1280       <para>Explaining PAM is beyond the scope of this document.  It is
1281       assumed that you understand the syntax and meanings of settings in the
1282       PAM configuration file (for example, how the
1283       <computeroutput>other</computeroutput> entry works, the effect of
1284       marking an entry as <computeroutput>required</computeroutput>,
1285       <computeroutput>optional</computeroutput>, or
1286       <computeroutput>sufficient</computeroutput>, and so on).</para>
1287
1288       <para>You should first configure your system to obtain Kerberos v5
1289       tickets as part of the authentication process, and then run an AFS PAM
1290       module to obtain tokens from those tickets after authentication.
1291       Current versions of Solaris come with a Kerberos v5 PAM module that
1292       will work, or you can download and install <ulink
1293       url="http://www.eyrie.org/~eagle/software/pam-krb5">Russ Allbery's
1294       Kerberos v5 PAM module</ulink>, which is tested regularly with AFS.
1295       See the instructions of whatever PAM module you use for how to
1296       configure it.</para>
1297
1298       <para>Some Kerberos v5 PAM modules do come with native AFS support
1299       (usually requiring the Heimdal Kerberos implementation rather than the
1300       MIT Kerberos implementation).  If you are using one of those PAM
1301       modules, you can configure it to obtain AFS tokens.  It's more common,
1302       however, to separate the AFS token acquisition into a separate PAM
1303       module.</para>
1304
1305       <para>The recommended AFS PAM module is <ulink
1306       url="http://www.eyrie.org/~eagle/software/pam-afs-session/">Russ
1307       Allbery's pam-afs-session module</ulink>.  It should work with any of
1308       the Kerberos v5 PAM modules.  To add it to the PAM configuration, you
1309       often only need to add configuration to the session group in
1310       <filename>pam.conf</filename>:</para>
1311
1312       <example>
1313         <title>Solaris PAM session example</title>
1314         <literallayout>login session required pam_afs_session.so</literallayout>
1315       </example>
1316
1317       <para>This example enables PAM authentication only for console login.
1318       You may want to add a similar line for the ssh service and for any
1319       other login service that you use, including possibly the
1320       <literal>other</literal> service (which serves as a catch-all).  You
1321       may also want to add options to the AFS PAM session module
1322       (particularly <literal>retain_after_close</literal>, which is
1323       necessary for some versions of Solaris.</para>
1324
1325       <para>For additional configuration examples and the configuration
1326       options of the AFS PAM module, see its documentation.  For more
1327       details on the available options for the PAM configuration, see the
1328       <filename>pam.conf</filename> manual page.</para>
1329
1330       <para>Sites which still require <emphasis
1331       role="bold">kaserver</emphasis> or external Kerberos v4 authentication
1332       should consult <link linkend="KAS016">"Enabling kaserver based AFS
1333       Login on Solaris Systems"</link> for details of how to enable AFS
1334       login on Solaris.</para>
1335
1336       <para>Proceed to <link linkend="HDRWQ49a">Editing the File Systems
1337       Clean-up Script on Solaris Systems</link></para>
1338     </sect2>
1339     <sect2 id="HDRWQ49a">
1340       <title>Editing the File Systems Clean-up Script on Solaris Systems</title>
1341       <indexterm>
1342         <primary>Solaris</primary>
1343
1344         <secondary>file systems clean-up script</secondary>
1345
1346         <tertiary>on file server machine</tertiary>
1347       </indexterm>
1348
1349       <indexterm>
1350         <primary>file systems clean-up script (Solaris)</primary>
1351
1352         <secondary>file server machine</secondary>
1353       </indexterm>
1354
1355       <indexterm>
1356         <primary>scripts</primary>
1357
1358         <secondary>file systems clean-up (Solaris)</secondary>
1359
1360         <tertiary>file server machine</tertiary>
1361       </indexterm>
1362
1363
1364         <orderedlist>
1365           <listitem>
1366             <para>Some Solaris distributions include a script that locates and removes unneeded files from various file systems. Its
1367             conventional location is <emphasis role="bold">/usr/lib/fs/nfs/nfsfind</emphasis>. The script generally uses an argument
1368             to the <emphasis role="bold">find</emphasis> command to define which file systems to search. In this step you modify the
1369             command to exclude the <emphasis role="bold">/afs</emphasis> directory. Otherwise, the command traverses the AFS
1370             filespace of every cell that is accessible from the machine, which can take many hours. The following alterations are
1371             possibilities, but you must verify that they are appropriate for your cell.</para>
1372
1373             <para>The first possible alteration is to add the <emphasis role="bold">-local</emphasis> flag to the existing command,
1374             so that it looks like the following:</para>
1375
1376             <programlisting>
1377    find $dir -local -name .nfs\* -mtime +7 -mount -exec rm -f {} \;
1378 </programlisting>
1379
1380             <para>Another alternative is to exclude any directories whose names begin with the lowercase letter <emphasis
1381             role="bold">a</emphasis> or a non-alphabetic character.</para>
1382
1383             <programlisting>
1384    find /[A-Zb-z]*  <replaceable>remainder of existing command</replaceable>
1385 </programlisting>
1386
1387             <para>Do not use the following command, which still searches under the <emphasis role="bold">/afs</emphasis> directory,
1388             looking for a subdirectory of type <emphasis role="bold">4.2</emphasis>.</para>
1389
1390             <programlisting>
1391    find / -fstype 4.2     /* <replaceable>do not use</replaceable> */
1392 </programlisting>
1393           </listitem>
1394
1395           <listitem>
1396             <para>Proceed to <link linkend="HDRWQ50">Starting the BOS Server</link> (or if referring to these instructions while
1397             installing an additional file server machine, return to <link linkend="HDRWQ108">Starting Server
1398             Programs</link>).</para>
1399           </listitem>
1400         </orderedlist>
1401
1402       <indexterm>
1403         <primary>Basic OverSeer Server</primary>
1404
1405         <see>BOS Server</see>
1406       </indexterm>
1407
1408       <indexterm>
1409         <primary>BOS Server</primary>
1410
1411         <secondary>starting</secondary>
1412
1413         <tertiary>first AFS machine</tertiary>
1414       </indexterm>
1415
1416       <indexterm>
1417         <primary>starting</primary>
1418
1419         <secondary>BOS Server</secondary>
1420
1421         <tertiary>first AFS machine</tertiary>
1422       </indexterm>
1423
1424       <indexterm>
1425         <primary>first AFS machine</primary>
1426
1427         <secondary>BOS Server</secondary>
1428       </indexterm>
1429
1430       <indexterm>
1431         <primary>authorization checking (disabling)</primary>
1432
1433         <secondary>first AFS machine</secondary>
1434       </indexterm>
1435
1436       <indexterm>
1437         <primary>disabling authorization checking</primary>
1438
1439         <secondary>first AFS machine</secondary>
1440       </indexterm>
1441
1442       <indexterm>
1443         <primary>first AFS machine</primary>
1444
1445         <secondary>authorization checking (disabling)</secondary>
1446       </indexterm>
1447     </sect2>
1448   </sect1>
1449
1450   <sect1 id="HDRWQ21">
1451     <title>Getting Started on AIX Systems</title>
1452
1453     <para>Begin by running the AFS initialization script to call the AIX kernel extension facility, which dynamically loads AFS
1454     modifications into the kernel. Then use the <emphasis role="bold">SMIT</emphasis> program to configure partitions for storing
1455     AFS volumes, and replace the AIX <emphasis role="bold">fsck</emphasis> program helper with a version that correctly handles AFS
1456     volumes. If the machine is to remain an AFS client machine, incorporate AFS into the AIX secondary authentication system.
1457     <indexterm>
1458         <primary>incorporating AFS kernel extensions</primary>
1459
1460         <secondary>first AFS machine</secondary>
1461
1462         <tertiary>AIX</tertiary>
1463       </indexterm> <indexterm>
1464         <primary>AFS kernel extensions</primary>
1465
1466         <secondary>on first AFS machine</secondary>
1467
1468         <tertiary>AIX</tertiary>
1469       </indexterm> <indexterm>
1470         <primary>first AFS machine</primary>
1471
1472         <secondary>AFS kernel extensions</secondary>
1473
1474         <tertiary>on AIX</tertiary>
1475       </indexterm> <indexterm>
1476         <primary>AIX</primary>
1477
1478         <secondary>AFS kernel extensions</secondary>
1479
1480         <tertiary>on first AFS machine</tertiary>
1481       </indexterm></para>
1482
1483     <sect2 id="HDRWQ22">
1484       <title>Loading AFS into the AIX Kernel</title>
1485
1486       <para>The AIX kernel extension facility is the dynamic kernel loader
1487       provided by IBM Corporation.  AIX does not support incorporation of
1488       AFS modifications during a kernel build.</para>
1489
1490       <para>For AFS to function correctly, the kernel extension facility must run each time the machine reboots, so the AFS
1491       initialization script (included in the AFS distribution) invokes it automatically. In this section you copy the script to the
1492       conventional location and edit it to select the appropriate options depending on whether NFS is also to run.</para>
1493
1494       <para>After editing the script, you run it to incorporate AFS into the kernel. In later sections you verify that the script
1495       correctly initializes all AFS components, then configure the AIX <emphasis role="bold">inittab</emphasis> file so that the
1496       script runs automatically at reboot. <orderedlist>
1497           <listitem>
1498             <para>Unpack the distribution tarball. The examples below assume
1499             that you have unpacked the files into the
1500             <emphasis role="bold">/tmp/afsdist</emphasis> directory. If you
1501             pick a different location, substitute this in all of the following
1502             examples. Once you have unpacked the distribution,
1503             change directory as indicated.
1504 <programlisting>
1505    # <emphasis role="bold">cd /tmp/afsdist/rs_aix42/dest/root.client/usr/vice/etc</emphasis>
1506 </programlisting></para>
1507           </listitem>
1508
1509           <listitem>
1510             <para>Copy the AFS kernel library files to the local <emphasis role="bold">/usr/vice/etc/dkload</emphasis> directory,
1511             and the AFS initialization script to the <emphasis role="bold">/etc</emphasis> directory. <programlisting>
1512    # <emphasis role="bold">cp -rp  dkload  /usr/vice/etc</emphasis>
1513    # <emphasis role="bold">cp -p  rc.afs  /etc/rc.afs</emphasis>
1514 </programlisting></para>
1515           </listitem>
1516
1517           <listitem>
1518             <para>Edit the <emphasis role="bold">/etc/rc.afs</emphasis> script, setting the <computeroutput>NFS</computeroutput>
1519             variable as indicated.</para>
1520
1521             <para>If the machine is not to function as an NFS/AFS Translator, set the <computeroutput>NFS</computeroutput> variable
1522             as follows.</para>
1523
1524             <programlisting>
1525    NFS=$NFS_NONE
1526 </programlisting>
1527
1528             <para>If the machine is to function as an NFS/AFS Translator and is running AIX 4.2.1 or higher, set the
1529             <computeroutput>NFS</computeroutput> variable as follows. Note that NFS must already be loaded into the kernel, which
1530             happens automatically on systems running AIX 4.1.1 and later, as long as the file <emphasis
1531             role="bold">/etc/exports</emphasis> exists.</para>
1532
1533             <programlisting>
1534    NFS=$NFS_IAUTH
1535 </programlisting>
1536           </listitem>
1537
1538           <listitem>
1539             <para>Invoke the <emphasis role="bold">/etc/rc.afs</emphasis> script to load AFS modifications into the kernel. You can
1540             ignore any error messages about the inability to start the BOS Server or the Cache Manager or AFS client.
1541             <programlisting>
1542    # <emphasis role="bold">/etc/rc.afs</emphasis>
1543 </programlisting></para>
1544           </listitem>
1545         </orderedlist></para>
1546
1547       <indexterm>
1548         <primary>configuring</primary>
1549
1550         <secondary>AFS server partition on first AFS machine</secondary>
1551
1552         <tertiary>AIX</tertiary>
1553       </indexterm>
1554
1555       <indexterm>
1556         <primary>AFS server partition</primary>
1557
1558         <secondary>configuring on first AFS machine</secondary>
1559
1560         <tertiary>AIX</tertiary>
1561       </indexterm>
1562
1563       <indexterm>
1564         <primary>first AFS machine</primary>
1565
1566         <secondary>AFS server partition</secondary>
1567
1568         <tertiary>on AIX</tertiary>
1569       </indexterm>
1570
1571       <indexterm>
1572         <primary>AIX</primary>
1573
1574         <secondary>AFS server partition</secondary>
1575
1576         <tertiary>on first AFS machine</tertiary>
1577       </indexterm>
1578     </sect2>
1579
1580     <sect2 id="HDRWQ23">
1581       <title>Configuring Server Partitions on AIX Systems</title>
1582
1583       <para>Every AFS file server machine must have at least one partition or logical volume dedicated to storing AFS volumes. Each
1584       server partition is mounted at a directory named <emphasis role="bold">/vicep</emphasis><replaceable>xx</replaceable>, where
1585       <replaceable>xx</replaceable> is one or two lowercase letters. The <emphasis
1586       role="bold">/vicep</emphasis><replaceable>xx</replaceable> directories must reside in the file server machine's root
1587       directory, not in one of its subdirectories (for example, <emphasis role="bold">/usr/vicepa</emphasis> is not an acceptable
1588       directory location). For additional information, see <link linkend="HDRWQ20">Performing Platform-Specific
1589       Procedures</link>.</para>
1590
1591       <para>To configure server partitions on an AIX system, perform the following procedures: <orderedlist>
1592           <listitem>
1593             <para>Create a directory called <emphasis role="bold">/vicep</emphasis><replaceable>xx</replaceable> for each AFS server
1594             partition you are configuring (there must be at least one). Repeat the command for each partition. <programlisting>
1595    # <emphasis role="bold">mkdir /vicep</emphasis><replaceable>xx</replaceable>
1596 </programlisting></para>
1597           </listitem>
1598
1599           <listitem>
1600             <para>Use the <emphasis role="bold">SMIT</emphasis> program to create a journaling file system on each partition to be
1601             configured as an AFS server partition.</para>
1602           </listitem>
1603
1604           <listitem>
1605             <para>Mount each partition at one of the <emphasis role="bold">/vicep</emphasis><replaceable>xx</replaceable>
1606             directories. Choose one of the following three methods: <itemizedlist>
1607                 <listitem>
1608                   <para>Use the <emphasis role="bold">SMIT</emphasis> program</para>
1609                 </listitem>
1610
1611                 <listitem>
1612                   <para>Use the <emphasis role="bold">mount -a</emphasis> command to mount all partitions at once</para>
1613                 </listitem>
1614
1615                 <listitem>
1616                   <para>Use the <emphasis role="bold">mount</emphasis> command on each partition in turn</para>
1617                 </listitem>
1618               </itemizedlist></para>
1619
1620             <para>Also configure the partitions so that they are mounted automatically at each reboot. For more information, refer
1621             to the AIX documentation.</para>
1622           </listitem>
1623         </orderedlist></para>
1624
1625       <indexterm>
1626         <primary>replacing fsck program</primary>
1627
1628         <secondary>first AFS machine</secondary>
1629
1630         <tertiary>AIX</tertiary>
1631       </indexterm>
1632
1633       <indexterm>
1634         <primary>fsck program</primary>
1635
1636         <secondary>on first AFS machine</secondary>
1637
1638         <tertiary>AIX</tertiary>
1639       </indexterm>
1640
1641       <indexterm>
1642         <primary>first AFS machine</primary>
1643
1644         <secondary>fsck program</secondary>
1645
1646         <tertiary>on AIX</tertiary>
1647       </indexterm>
1648
1649       <indexterm>
1650         <primary>AIX</primary>
1651
1652         <secondary>fsck program</secondary>
1653
1654         <tertiary>on first AFS machine</tertiary>
1655       </indexterm>
1656     </sect2>
1657
1658     <sect2 id="HDRWQ24">
1659       <title>Replacing the fsck Program Helper on AIX Systems</title>
1660
1661       <note><para>The AFS modified fsck program is not required on AIX 5.1
1662       systems, and the <emphasis role="bold">v3fshelper</emphasis> program
1663       refered to below is not shipped for these systems.</para></note>
1664
1665       <para>In this section, you make modifications to guarantee that the appropriate <emphasis role="bold">fsck</emphasis> program
1666       runs on AFS server partitions. The <emphasis role="bold">fsck</emphasis> program provided with the operating system must never
1667       run on AFS server partitions. Because it does not recognize the structures that the File Server uses to organize volume data,
1668       it removes all of the data. To repeat:</para>
1669
1670       <para><emphasis role="bold">Never run the standard fsck program on AFS server partitions. It discards AFS
1671       volumes.</emphasis></para>
1672
1673       <para>On AIX systems, you do not replace the <emphasis role="bold">fsck</emphasis> binary itself, but rather the
1674       <emphasis>program helper</emphasis> file included in the AIX distribution as <emphasis
1675       role="bold">/sbin/helpers/v3fshelper</emphasis>. <orderedlist>
1676           <listitem>
1677             <para>Move the AIX <emphasis role="bold">fsck</emphasis> program helper to a safe location and install the version from
1678             the AFS distribution in its place.
1679 <programlisting>
1680    # <emphasis role="bold">cd /sbin/helpers</emphasis>
1681    # <emphasis role="bold">mv v3fshelper v3fshelper.noafs</emphasis>
1682    # <emphasis role="bold">cp -p /tmp/afsdist/rs_aix42/dest/root.server/etc/v3fshelper v3fshelper</emphasis>
1683 </programlisting></para>
1684           </listitem>
1685
1686           <listitem>
1687             <para>If you plan to retain client functionality on this machine after completing the installation, proceed to <link
1688             linkend="HDRWQ25">Enabling AFS Login on AIX Systems</link>. Otherwise, proceed to <link linkend="HDRWQ50">Starting the
1689             BOS Server</link>.</para>
1690           </listitem>
1691         </orderedlist></para>
1692
1693       <indexterm>
1694         <primary>enabling AFS login</primary>
1695
1696         <secondary>file server machine</secondary>
1697
1698         <tertiary>AIX</tertiary>
1699       </indexterm>
1700
1701       <indexterm>
1702         <primary>AFS login</primary>
1703
1704         <secondary>on file server machine</secondary>
1705
1706         <tertiary>AIX</tertiary>
1707       </indexterm>
1708
1709       <indexterm>
1710         <primary>first AFS machine</primary>
1711
1712         <secondary>AFS login</secondary>
1713
1714         <tertiary>on AIX</tertiary>
1715       </indexterm>
1716
1717       <indexterm>
1718         <primary>AIX</primary>
1719
1720         <secondary>AFS login</secondary>
1721
1722         <tertiary>on file server machine</tertiary>
1723       </indexterm>
1724
1725       <indexterm>
1726         <primary>secondary authentication system (AIX)</primary>
1727
1728         <secondary>server machine</secondary>
1729       </indexterm>
1730     </sect2>
1731
1732     <sect2 id="HDRWQ25">
1733       <title>Enabling AFS Login on AIX Systems</title>
1734
1735       <note>
1736         <para>If you plan to remove client functionality from this machine after completing the installation, skip this section and
1737         proceed to <link linkend="HDRWQ50">Starting the BOS Server</link>.</para>
1738       </note>
1739
1740       <para>In modern AFS installations, you should be using Kerberos v5
1741       for user login, and obtaining AFS tokens following this authentication
1742       step.</para>
1743
1744       <para>There are currently no instructions available on configuring AIX to
1745       automatically obtain AFS tokens at login. Following login, users can
1746       obtain tokens by running the <emphasis role="bold">aklog</emphasis>
1747       command</para>
1748
1749       <para>Sites which still require <emphasis role="bold">kaserver</emphasis>
1750       or external Kerberos v4 authentication should consult
1751       <link linkend="KAS012">Enabling kaserver based AFS login on AIX systems</link>
1752       for details of how to enable AIX login.</para>
1753
1754       <para>Proceed to <link linkend="HDRWQ50">Starting the BOS Server</link>
1755       (or if referring to these instructions while installing an additional
1756       file server machine, return to <link linkend="HDRWQ108">Starting Server
1757       Programs</link>).</para>
1758     </sect2>
1759   </sect1>
1760   <sect1 id="HDRWQ50">
1761     <title>Starting the BOS Server</title>
1762
1763     <para>You are now ready to start the AFS server processes on this machine.
1764     If you are not working from a packaged distribution, begin by copying the
1765     AFS server binaries from the distribution to the conventional local disk
1766     location, the <emphasis role="bold">/usr/afs/bin</emphasis> directory. The
1767     following instructions also create files in other subdirectories of the
1768     <emphasis role="bold">/usr/afs</emphasis> directory.</para>
1769
1770     <para>Then issue the <emphasis role="bold">bosserver</emphasis> command to initialize the Basic OverSeer (BOS) Server, which
1771     monitors and controls other AFS server processes on its server machine. Include the <emphasis role="bold">-noauth</emphasis>
1772     flag to disable authorization checking. Because you have not yet configured your cell's AFS authentication and authorization
1773     mechanisms, the BOS Server cannot perform authorization checking as it does during normal operation. In no-authorization mode,
1774     it does not verify the identity or privilege of the issuer of a <emphasis role="bold">bos</emphasis> command, and so performs
1775     any operation for anyone.</para>
1776
1777     <para>Disabling authorization checking gravely compromises cell security. You must complete all subsequent steps in one
1778     uninterrupted pass and must not leave the machine unattended until you restart the BOS Server with authorization checking
1779     enabled, in <link linkend="HDRWQ72">Verifying the AFS Initialization Script</link>.</para>
1780
1781     <para>As it initializes for the first time, the BOS Server creates the following directories and files, setting the owner to the
1782     local superuser <emphasis role="bold">root</emphasis> and the mode bits to limit the ability to write (and in some cases, read)
1783     them. For a description of the contents and function of these directories and files, see the chapter in the <emphasis>OpenAFS
1784     Administration Guide</emphasis> about administering server machines. For further discussion of the mode bit settings, see <link
1785     linkend="HDRWQ96">Protecting Sensitive AFS Directories</link>. <indexterm>
1786         <primary>Binary Distribution</primary>
1787
1788         <secondary>copying server files from</secondary>
1789
1790         <tertiary>first AFS machine</tertiary>
1791       </indexterm> <indexterm>
1792         <primary>first AFS machine</primary>
1793
1794         <secondary>subdirectories of /usr/afs</secondary>
1795       </indexterm> <indexterm>
1796         <primary>creating</primary>
1797
1798         <secondary>/usr/afs/bin directory</secondary>
1799
1800         <tertiary>first AFS machine</tertiary>
1801       </indexterm> <indexterm>
1802         <primary>creating</primary>
1803
1804         <secondary>/usr/afs/etc directory</secondary>
1805
1806         <tertiary>first AFS machine</tertiary>
1807       </indexterm> <indexterm>
1808         <primary>copying</primary>
1809
1810         <secondary>server files to local disk</secondary>
1811
1812         <tertiary>first AFS machine</tertiary>
1813       </indexterm> <indexterm>
1814         <primary>first AFS machine</primary>
1815
1816         <secondary>copying</secondary>
1817
1818         <tertiary>server files to local disk</tertiary>
1819       </indexterm> <indexterm>
1820         <primary>usr/afs/bin directory</primary>
1821
1822         <secondary>first AFS machine</secondary>
1823       </indexterm> <indexterm>
1824         <primary>usr/afs/etc directory</primary>
1825
1826         <secondary>first AFS machine</secondary>
1827       </indexterm> <indexterm>
1828         <primary>usr/afs/db directory</primary>
1829       </indexterm> <indexterm>
1830         <primary>usr/afs/local directory</primary>
1831       </indexterm> <indexterm>
1832         <primary>usr/afs/logs directory</primary>
1833       </indexterm> <itemizedlist>
1834         <listitem>
1835           <para><emphasis role="bold">/usr/afs/db</emphasis></para>
1836         </listitem>
1837
1838         <listitem>
1839           <para><emphasis role="bold">/usr/afs/etc/CellServDB</emphasis></para>
1840         </listitem>
1841
1842         <listitem>
1843           <para><emphasis role="bold">/usr/afs/etc/ThisCell</emphasis></para>
1844         </listitem>
1845
1846         <listitem>
1847           <para><emphasis role="bold">/usr/afs/local</emphasis></para>
1848         </listitem>
1849
1850         <listitem>
1851           <para><emphasis role="bold">/usr/afs/logs</emphasis></para>
1852         </listitem>
1853       </itemizedlist></para>
1854
1855     <para>The BOS Server also creates symbolic links called <emphasis role="bold">/usr/vice/etc/ThisCell</emphasis> and <emphasis
1856     role="bold">/usr/vice/etc/CellServDB</emphasis> to the corresponding files in the <emphasis role="bold">/usr/afs/etc</emphasis>
1857     directory. The AFS command interpreters consult the <emphasis role="bold">CellServDB</emphasis> and <emphasis
1858     role="bold">ThisCell</emphasis> files in the <emphasis role="bold">/usr/vice/etc</emphasis> directory because they generally run
1859     on client machines. On machines that are AFS servers only (as this machine currently is), the files reside only in the <emphasis
1860     role="bold">/usr/afs/etc</emphasis> directory; the links enable the command interpreters to retrieve the information they need.
1861     Later instructions for installing the client functionality replace the links with actual files. <orderedlist>
1862         <listitem>
1863           <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.
1864 <programlisting>
1865    # <emphasis role="bold">cd /tmp/afsdist/</emphasis><replaceable>sysname</replaceable><emphasis role="bold">/root.server/usr/afs</emphasis>
1866    # <emphasis role="bold">cp -rp  *  /usr/afs</emphasis>
1867 </programlisting> <indexterm>
1868               <primary>commands</primary>
1869
1870               <secondary>bosserver</secondary>
1871             </indexterm> <indexterm>
1872               <primary>bosserver command</primary>
1873             </indexterm></para>
1874         </listitem>
1875
1876         <listitem>
1877           <para>Issue the <emphasis role="bold">bosserver</emphasis> command. Include the <emphasis role="bold">-noauth</emphasis>
1878           flag to disable authorization checking. <programlisting>
1879    # <emphasis role="bold">/usr/afs/bin/bosserver -noauth &amp;</emphasis>
1880 </programlisting></para>
1881         </listitem>
1882
1883         <listitem>
1884           <para>Verify that the BOS Server created <emphasis role="bold">/usr/vice/etc/ThisCell</emphasis> and <emphasis
1885           role="bold">/usr/vice/etc/CellServDB</emphasis> as symbolic links to the corresponding files in the <emphasis
1886           role="bold">/usr/afs/etc</emphasis> directory. <programlisting>
1887    # <emphasis role="bold">ls -l  /usr/vice/etc</emphasis>
1888 </programlisting></para>
1889
1890           <para>If either or both of <emphasis role="bold">/usr/vice/etc/ThisCell</emphasis> and <emphasis
1891           role="bold">/usr/vice/etc/CellServDB</emphasis> do not exist, or are not links, issue the following commands.</para>
1892
1893           <programlisting>
1894    # <emphasis role="bold">cd /usr/vice/etc</emphasis>
1895    # <emphasis role="bold">ln -s /usr/afs/etc/ThisCell</emphasis>
1896    # <emphasis role="bold">ln -s /usr/afs/etc/CellServDB</emphasis>
1897 </programlisting>
1898         </listitem>
1899       </orderedlist></para>
1900
1901     <indexterm>
1902       <primary>cell name</primary>
1903
1904       <secondary>defining during installation of first machine</secondary>
1905     </indexterm>
1906
1907     <indexterm>
1908       <primary>defining</primary>
1909
1910       <secondary>cell name during installation of first machine</secondary>
1911     </indexterm>
1912
1913     <indexterm>
1914       <primary>cell name</primary>
1915
1916       <secondary>setting in server ThisCell file</secondary>
1917
1918       <tertiary>first AFS machine</tertiary>
1919     </indexterm>
1920
1921     <indexterm>
1922       <primary>setting</primary>
1923
1924       <secondary>cell name in server ThisCell file</secondary>
1925
1926       <tertiary>first AFS machine</tertiary>
1927     </indexterm>
1928
1929     <indexterm>
1930       <primary>first AFS machine</primary>
1931
1932       <secondary>ThisCell file (server)</secondary>
1933     </indexterm>
1934
1935     <indexterm>
1936       <primary>usr/afs/etc/ThisCell</primary>
1937
1938       <see>ThisCell file (server)</see>
1939     </indexterm>
1940
1941     <indexterm>
1942       <primary>ThisCell file (server)</primary>
1943
1944       <secondary>first AFS machine</secondary>
1945     </indexterm>
1946
1947     <indexterm>
1948       <primary>files</primary>
1949
1950       <secondary>ThisCell (server)</secondary>
1951     </indexterm>
1952
1953     <indexterm>
1954       <primary>database server machine</primary>
1955
1956       <secondary>entry in server CellServDB file</secondary>
1957
1958       <tertiary>on first AFS machine</tertiary>
1959     </indexterm>
1960
1961     <indexterm>
1962       <primary>first AFS machine</primary>
1963
1964       <secondary>cell membership, defining</secondary>
1965
1966       <tertiary>for server processes</tertiary>
1967     </indexterm>
1968
1969     <indexterm>
1970       <primary>usr/afs/etc/CellServDB file</primary>
1971
1972       <see>CellServDB file (server)</see>
1973     </indexterm>
1974
1975     <indexterm>
1976       <primary>CellServDB file (server)</primary>
1977
1978       <secondary>creating</secondary>
1979
1980       <tertiary>on first AFS machine</tertiary>
1981     </indexterm>
1982
1983     <indexterm>
1984       <primary>creating</primary>
1985
1986       <secondary>CellServDB file (server)</secondary>
1987
1988       <tertiary>first AFS machine</tertiary>
1989     </indexterm>
1990
1991     <indexterm>
1992       <primary>files</primary>
1993
1994       <secondary>CellServDB (server)</secondary>
1995     </indexterm>
1996
1997     <indexterm>
1998       <primary>first AFS machine</primary>
1999
2000       <secondary>CellServDB file (server)</secondary>
2001     </indexterm>
2002
2003     <indexterm>
2004       <primary>first AFS machine</primary>
2005
2006       <secondary>defining</secondary>
2007
2008       <tertiary>as database server</tertiary>
2009     </indexterm>
2010
2011     <indexterm>
2012       <primary>defining</primary>
2013
2014       <secondary>first AFS machine as database server</secondary>
2015     </indexterm>
2016   </sect1>
2017
2018   <sect1 id="HDRWQ51">
2019     <title>Defining Cell Name and Membership for Server Processes</title>
2020
2021     <para>Now assign your cell's name. The chapter in the <emphasis>OpenAFS Administration Guide</emphasis> about cell configuration
2022     and administration issues discusses the important considerations, explains why changing the name is difficult, and outlines the
2023     restrictions on name format. Two of the most important restrictions are that the name cannot include uppercase letters or more
2024     than 64 characters.</para>
2025
2026     <para>Use the <emphasis role="bold">bos setcellname</emphasis> command to assign the cell name. It creates two files:
2027     <itemizedlist>
2028         <listitem>
2029           <para><emphasis role="bold">/usr/afs/etc/ThisCell</emphasis>, which defines this machine's cell membership</para>
2030         </listitem>
2031
2032         <listitem>
2033           <para><emphasis role="bold">/usr/afs/etc/CellServDB</emphasis>, which lists the cell's database server machines; the
2034           machine named on the command line is placed on the list automatically</para>
2035         </listitem>
2036       </itemizedlist> <note>
2037         <para>In the following and every instruction in this guide, for the <replaceable>machine name</replaceable> argument
2038         substitute the fully-qualified hostname (such as <emphasis role="bold">fs1.example.com</emphasis>) of the machine you are
2039         installing. For the <replaceable>cell name</replaceable> argument substitute your cell's complete name (such as <emphasis
2040         role="bold">example.com</emphasis>).</para>
2041       </note></para>
2042
2043     <indexterm>
2044       <primary>commands</primary>
2045
2046       <secondary>bos setcellname</secondary>
2047     </indexterm>
2048
2049     <indexterm>
2050       <primary>bos commands</primary>
2051
2052       <secondary>setcellname</secondary>
2053     </indexterm>
2054
2055     <orderedlist>
2056       <listitem>
2057         <para>If necessary, add the directory containing the <emphasis role="bold">bos</emphasis> command to your path.
2058       <programlisting>
2059    # <emphasis role="bold">export PATH=$PATH:/usr/afs/bin</emphasis>
2060       </programlisting>
2061         </para>
2062       </listitem>
2063
2064       <listitem>
2065         <para>Issue the <emphasis role="bold">bos setcellname</emphasis> command to set the cell name. <programlisting>
2066    # <emphasis role="bold">bos setcellname</emphasis> &lt;<replaceable>machine name</replaceable>&gt; &lt;<replaceable>cell name</replaceable>&gt; <emphasis
2067               role="bold">-noauth</emphasis>
2068 </programlisting></para>
2069
2070         <para>Because you are not authenticated and authorization checking is disabled, the <emphasis role="bold">bos</emphasis>
2071         command interpreter possibly produces error messages about being unable to obtain tickets and running unauthenticated. You
2072         can safely ignore the messages. <indexterm>
2073             <primary>commands</primary>
2074
2075             <secondary>bos listhosts</secondary>
2076           </indexterm> <indexterm>
2077             <primary>bos commands</primary>
2078
2079             <secondary>listhosts</secondary>
2080           </indexterm> <indexterm>
2081             <primary>CellServDB file (server)</primary>
2082
2083             <secondary>displaying entries</secondary>
2084           </indexterm> <indexterm>
2085             <primary>displaying</primary>
2086
2087             <secondary>CellServDB file (server) entries</secondary>
2088           </indexterm></para>
2089       </listitem>
2090
2091       <listitem>
2092         <para>Issue the <emphasis role="bold">bos listhosts</emphasis> command to verify that the machine you are installing is now
2093         registered as the cell's first database server machine. <programlisting>
2094    # <emphasis role="bold">bos listhosts</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">-noauth</emphasis>
2095    Cell name is <replaceable>cell_name</replaceable>
2096        Host 1 is <replaceable>machine_name</replaceable>
2097 </programlisting></para>
2098       </listitem>
2099     </orderedlist>
2100
2101     <indexterm>
2102       <primary>database server machine</primary>
2103
2104       <secondary>installing</secondary>
2105
2106       <tertiary>first</tertiary>
2107     </indexterm>
2108
2109     <indexterm>
2110       <primary>instructions</primary>
2111
2112       <secondary>database server machine, installing first</secondary>
2113     </indexterm>
2114
2115     <indexterm>
2116       <primary>installing</primary>
2117
2118       <secondary>database server machine</secondary>
2119
2120       <tertiary>first</tertiary>
2121     </indexterm>
2122
2123     <indexterm>
2124       <primary>Backup Server</primary>
2125
2126       <secondary>starting</secondary>
2127
2128       <tertiary>first AFS machine</tertiary>
2129     </indexterm>
2130
2131     <indexterm>
2132       <primary>buserver process</primary>
2133
2134       <see>Backup Server</see>
2135     </indexterm>
2136
2137     <indexterm>
2138       <primary>starting</primary>
2139
2140       <secondary>Backup Server</secondary>
2141
2142       <tertiary>first AFS machine</tertiary>
2143     </indexterm>
2144
2145     <indexterm>
2146       <primary>first AFS machine</primary>
2147
2148       <secondary>Backup Server</secondary>
2149     </indexterm>
2150
2151     <indexterm>
2152       <primary>Protection Server</primary>
2153
2154       <secondary>starting</secondary>
2155
2156       <tertiary>first AFS machine</tertiary>
2157     </indexterm>
2158
2159     <indexterm>
2160       <primary>ptserver process</primary>
2161
2162       <see>Protection Server</see>
2163     </indexterm>
2164
2165     <indexterm>
2166       <primary>starting</primary>
2167
2168       <secondary>Protection Server</secondary>
2169
2170       <tertiary>first AFS machine</tertiary>
2171     </indexterm>
2172
2173     <indexterm>
2174       <primary>first AFS machine</primary>
2175
2176       <secondary>Protection Server</secondary>
2177     </indexterm>
2178
2179     <indexterm>
2180       <primary>VL Server (vlserver process)</primary>
2181
2182       <secondary>starting</secondary>
2183
2184       <tertiary>first AFS machine</tertiary>
2185     </indexterm>
2186
2187     <indexterm>
2188       <primary>Volume Location Server</primary>
2189
2190       <see>VL Server</see>
2191     </indexterm>
2192
2193     <indexterm>
2194       <primary>starting</primary>
2195
2196       <secondary>VL Server</secondary>
2197
2198       <tertiary>first AFS machine</tertiary>
2199     </indexterm>
2200
2201     <indexterm>
2202       <primary>first AFS machine</primary>
2203
2204       <secondary>VL Server</secondary>
2205     </indexterm>
2206
2207     <indexterm>
2208       <primary>usr/afs/local/BosConfig</primary>
2209
2210       <see>BosConfig file</see>
2211     </indexterm>
2212
2213     <indexterm>
2214       <primary>BosConfig file</primary>
2215
2216       <secondary>adding entries</secondary>
2217
2218       <tertiary>first AFS machine</tertiary>
2219     </indexterm>
2220
2221     <indexterm>
2222       <primary>adding</primary>
2223
2224       <secondary>entries to BosConfig file</secondary>
2225
2226       <tertiary>first AFS machine</tertiary>
2227     </indexterm>
2228
2229     <indexterm>
2230       <primary>files</primary>
2231
2232       <secondary>BosConfig</secondary>
2233     </indexterm>
2234
2235     <indexterm>
2236       <primary>initializing</primary>
2237
2238       <secondary>server process</secondary>
2239
2240       <see>starting</see>
2241     </indexterm>
2242
2243     <indexterm>
2244       <primary>server process</primary>
2245
2246       <secondary>see also entry for each server's name</secondary>
2247     </indexterm>
2248   </sect1>
2249
2250   <sect1 id="HDRWQ52">
2251     <title>Starting the Database Server Processes</title>
2252
2253     <para>Next use the <emphasis role="bold">bos create</emphasis> command to create entries for the three database server processes
2254     in the <emphasis role="bold">/usr/afs/local/BosConfig</emphasis> file and start them running. The three processes run on database
2255     server machines only: <itemizedlist>
2256
2257         <listitem>
2258           <para>The Backup Server (the <emphasis role="bold">buserver</emphasis> process) maintains the Backup Database</para>
2259         </listitem>
2260
2261         <listitem>
2262           <para>The Protection Server (the <emphasis role="bold">ptserver</emphasis> process) maintains the Protection
2263           Database</para>
2264         </listitem>
2265
2266         <listitem>
2267           <para>The Volume Location (VL) Server (the <emphasis role="bold">vlserver</emphasis> process) maintains the Volume
2268           Location Database (VLDB)</para>
2269         </listitem>
2270       </itemizedlist></para>
2271
2272     <indexterm>
2273       <primary>Kerberos</primary>
2274     </indexterm>
2275
2276     <note>
2277       <para>AFS ships with an additional database server named 'kaserver', which
2278       was historically used to provide authentication services to AFS cells.
2279       kaserver was based on <emphasis>Kerberos v4</emphasis>, as such, it is
2280       not recommended for new cells. This guide assumes you have already
2281       configured a Kerberos v5 realm for your site, and details the procedures
2282       required to use AFS with this realm. If you do wish to use
2283       <emphasis role="bold">kaserver</emphasis>, please see the modifications
2284       to these instructions detailed in
2285       <link linkend="KAS006">Starting the kaserver Database Server Process</link>
2286       </para>
2287     </note>
2288
2289     <para>The remaining instructions in this chapter include the <emphasis role="bold">-cell</emphasis> argument on all applicable
2290     commands. Provide the cell name you assigned in <link linkend="HDRWQ51">Defining Cell Name and Membership for Server
2291     Processes</link>. If a command appears on multiple lines, it is only for legibility. <indexterm>
2292         <primary>commands</primary>
2293
2294         <secondary>bos create</secondary>
2295       </indexterm> <indexterm>
2296         <primary>bos commands</primary>
2297
2298         <secondary>create</secondary>
2299       </indexterm> <orderedlist>
2300         <listitem>
2301           <para>Issue the <emphasis role="bold">bos create</emphasis> command to start the Backup Server. <programlisting>
2302    # <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>
2303 </programlisting></para>
2304         </listitem>
2305
2306         <listitem>
2307           <para>Issue the <emphasis role="bold">bos create</emphasis> command to start the Protection Server. <programlisting>
2308    # <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>
2309 </programlisting></para>
2310         </listitem>
2311
2312         <listitem>
2313           <para>Issue the <emphasis role="bold">bos create</emphasis> command to start the VL Server. <programlisting>
2314    # <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>
2315 </programlisting></para>
2316         </listitem>
2317       </orderedlist></para>
2318
2319     <indexterm>
2320       <primary>admin account</primary>
2321
2322       <secondary>creating</secondary>
2323     </indexterm>
2324
2325     <indexterm>
2326       <primary>afs entry in Kerberos Database</primary>
2327     </indexterm>
2328
2329     <indexterm>
2330       <primary>Kerberos Database</primary>
2331     </indexterm>
2332
2333     <indexterm>
2334       <primary>creating</primary>
2335
2336       <secondary>afs entry in Kerberos Database</secondary>
2337     </indexterm>
2338
2339     <indexterm>
2340       <primary>creating</primary>
2341
2342       <secondary>admin account in Kerberos Database</secondary>
2343     </indexterm>
2344
2345     <indexterm>
2346       <primary>security</primary>
2347
2348       <secondary>initializing cell-wide</secondary>
2349     </indexterm>
2350
2351     <indexterm>
2352       <primary>cell</primary>
2353
2354       <secondary>initializing security mechanisms</secondary>
2355     </indexterm>
2356
2357     <indexterm>
2358       <primary>initializing</primary>
2359
2360       <secondary>cell security mechanisms</secondary>
2361     </indexterm>
2362
2363     <indexterm>
2364       <primary>usr/afs/etc/KeyFile</primary>
2365
2366       <see>KeyFile file</see>
2367     </indexterm>
2368
2369     <indexterm>
2370       <primary>KeyFile file</primary>
2371
2372       <secondary>first AFS machine</secondary>
2373     </indexterm>
2374
2375     <indexterm>
2376       <primary>files</primary>
2377
2378       <secondary>KeyFile</secondary>
2379     </indexterm>
2380
2381     <indexterm>
2382       <primary>key</primary>
2383
2384       <see>server encryption key</see>
2385     </indexterm>
2386
2387     <indexterm>
2388       <primary>encryption key</primary>
2389
2390       <see>server encryption key</see>
2391     </indexterm>
2392   </sect1>
2393
2394   <sect1 id="HDRWQ53">
2395     <title>Initializing Cell Security </title>
2396
2397     <para>If you are working with an existing cell which uses
2398     <emphasis role="bold">kaserver</emphasis> or Kerberos v4 for authentication,
2399     please see
2400     <link linkend="HDRWQ53">Initializing Cell Security with kaserver</link>
2401     for installation instructions which replace this section.</para>
2402
2403     <para>Now initialize the cell's security mechanisms. Begin by creating the following two entires in your site's Kerberos database: <itemizedlist>
2404         <listitem>
2405           <para>A generic administrative account, called <emphasis role="bold">admin</emphasis> by convention. If you choose to
2406           assign a different name, substitute it throughout the remainder of this document.</para>
2407
2408           <para>After you complete the installation of the first machine, you can continue to have all administrators use the
2409           <emphasis role="bold">admin</emphasis> account, or you can create a separate administrative account for each of them. The
2410           latter scheme implies somewhat more overhead, but provides a more informative audit trail for administrative
2411           operations.</para>
2412         </listitem>
2413
2414         <listitem>
2415           <para>The entry for AFS server processes, called either
2416           <emphasis role="bold">afs</emphasis> or
2417           <emphasis role="bold">afs/<replaceable>cell</replaceable></emphasis>.
2418           The latter form is preferred since it works regardless of whether
2419           your cell name matches your Kerberos realm name and allows multiple
2420           AFS cells to be served from a single Kerberos realm.
2421           No user logs in under this identity, but it is used to encrypt the
2422           server tickets that granted to AFS clients for presentation to
2423           server processes during mutual authentication. (The
2424           chapter in the <emphasis>OpenAFS Administration Guide</emphasis> about cell configuration and administration describes the
2425           role of server encryption keys in mutual authentication.)</para>
2426
2427           <para>In Step <link linkend="LIWQ58">7</link>, you also place the initial AFS server encryption key into the <emphasis
2428           role="bold">/usr/afs/etc/KeyFile</emphasis> file. The AFS server processes refer to this file to learn the server
2429           encryption key when they need to decrypt server tickets.</para>
2430         </listitem>
2431       </itemizedlist></para>
2432
2433     <para>You also issue several commands that enable the new <emphasis role="bold">admin</emphasis> user to issue privileged
2434     commands in all of the AFS suites.</para>
2435
2436     <para>The following instructions do not configure all of the security mechanisms related to the AFS Backup System. See the
2437     chapter in the <emphasis>OpenAFS Administration Guide</emphasis> about configuring the Backup System.</para>
2438
2439     <para>The examples below assume you are using MIT Kerberos. Please refer
2440     to the documentation for your KDC's administrative interface if you are
2441     using a different vendor</para>
2442
2443     <orderedlist>
2444         <listitem>
2445           <para>Enter <emphasis role="bold">kadmin</emphasis> interactive mode.
2446 <programlisting>
2447    # <emphasis role="bold">kadmin</emphasis>
2448 Authenticating as principal <replaceable>you</replaceable>/admin@<replaceable>YOUR REALM</replaceable> with password
2449 Password for <replaceable>you/admin@REALM</replaceable>: <replaceable>your_password</replaceable>
2450 </programlisting> <indexterm>
2451               <primary>server encryption key</primary>
2452
2453               <secondary>in Kerberos Database</secondary>
2454             </indexterm> <indexterm>
2455               <primary>creating</primary>
2456
2457               <secondary>server encryption key</secondary>
2458
2459               <tertiary>Kerberos Database</tertiary>
2460             </indexterm></para>
2461         </listitem>
2462
2463         <listitem id="LIWQ54">
2464           <para>Issue the
2465           <emphasis role="bold">add_principal</emphasis> command to create
2466           Kerberos Database entries called
2467           <emphasis role="bold">admin</emphasis> and
2468           <emphasis role="bold">afs/&lt;<replaceable>cell name</replaceable>&gt;</emphasis>.</para>
2469
2470           <para>You should make the <replaceable>admin_passwd</replaceable> as
2471           long and complex as possible, but keep in mind that administrators
2472           need to enter it often. It must be at least six characters long.</para>
2473           <para>Note that when creating the
2474           <emphasis role="bold">afs/&lt;<replaceable>cell name</replaceable>&gt;</emphasis>
2475           entry, the encryption types should be restricted to des-cbc-crc:v4.
2476           For more details regarding encryption types, see the documentation
2477           for your Kerberos installation.
2478
2479 <programlisting>
2480    kadmin: <emphasis role="bold">add_principal -randkey -e des-cbc-crc:v4 afs/</emphasis>&lt;<replaceable>cell name</replaceable>&gt;
2481    Principal "afs/<replaceable>cell name</replaceable>@<replaceable>REALM</replaceable>" created.
2482    kadmin:  <emphasis role="bold">add_principal admin</emphasis>
2483    Enter password for principal "admin@<replaceable>REALM</replaceable>": <emphasis role="bold"><replaceable>admin_password</replaceable></emphasis>
2484    Principal "admin@<replaceable>REALM</replaceable>" created.
2485 </programlisting>
2486           </para>
2487
2488           <indexterm>
2489             <primary>commands</primary>
2490
2491             <secondary>kas examine</secondary>
2492           </indexterm>
2493
2494           <indexterm>
2495             <primary>kas commands</primary>
2496
2497             <secondary>examine</secondary>
2498           </indexterm>
2499
2500           <indexterm>
2501             <primary>displaying</primary>
2502
2503             <secondary>server encryption key</secondary>
2504
2505             <tertiary>Authentication Database</tertiary>
2506           </indexterm>
2507         </listitem>
2508
2509         <listitem id="LIWQ55">
2510           <para>Issue the <emphasis role="bold">kadmin
2511           get_principal</emphasis> command to display the <emphasis
2512           role="bold">afs/</emphasis>&lt;<replaceable>cell name</replaceable>&gt; entry.
2513 <programlisting>
2514   kadmin: <emphasis role="bold">get_principal afs/&lt;<replaceable>cell name</replaceable>&gt;</emphasis>
2515   Principal: afs/<replaceable>cell</replaceable>
2516   [ ... ]
2517   Key: vno 2, DES cbc mode with CRC-32, no salt
2518   [ ... ]
2519 </programlisting>
2520 </para>
2521         </listitem>
2522         <listitem>
2523           <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>
2524
2525           <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>
2526
2527 <programlisting>
2528   kadmin: <emphasis role="bold">ktadd -k /etc/afs.keytab -e des-cbc-crc:v4 afs/&lt;<replaceable>cell name</replaceable>&gt;</emphasis>
2529 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
2530 </programlisting>
2531           <para>Make a note of the key version number (kvno) given in the
2532           response, as you will need it to load the key into bos in a later
2533           step</para>
2534
2535           <note><para>Note that each time you run
2536           <emphasis role="bold">ktadd</emphasis> a new key is generated
2537           for the item being extracted. This means that you cannot run ktadd
2538           multiple times and end up with the same key material each time.
2539           </para></note>
2540
2541         </listitem>
2542         <listitem>
2543           <para>Issue the <emphasis role="bold">quit</emphasis> command to leave <emphasis role="bold">kadmin</emphasis>
2544           interactive mode. <programlisting>
2545    kadmin: <emphasis role="bold">quit</emphasis>
2546 </programlisting> <indexterm>
2547               <primary>commands</primary>
2548
2549               <secondary>bos adduser</secondary>
2550             </indexterm> <indexterm>
2551               <primary>bos commands</primary>
2552
2553               <secondary>adduser</secondary>
2554             </indexterm> <indexterm>
2555               <primary>usr/afs/etc/UserList</primary>
2556
2557               <see>UserList file</see>
2558             </indexterm> <indexterm>
2559               <primary>UserList file</primary>
2560
2561               <secondary>first AFS machine</secondary>
2562             </indexterm> <indexterm>
2563               <primary>files</primary>
2564
2565               <secondary>UserList</secondary>
2566             </indexterm> <indexterm>
2567               <primary>creating</primary>
2568
2569               <secondary>UserList file entry</secondary>
2570             </indexterm> <indexterm>
2571               <primary>admin account</primary>
2572
2573               <secondary>adding</secondary>
2574
2575               <tertiary>to UserList file</tertiary>
2576             </indexterm></para>
2577         </listitem>
2578
2579         <listitem id="LIWQ57">
2580           <para>Issue the <emphasis role="bold">bos adduser</emphasis> command to add the <emphasis
2581           role="bold">admin</emphasis> user to the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. This enables the
2582           <emphasis role="bold">admin</emphasis> user to issue privileged <emphasis role="bold">bos</emphasis> and <emphasis
2583           role="bold">vos</emphasis> commands. <programlisting>
2584    # <emphasis role="bold">./bos adduser</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">admin -noauth</emphasis>
2585 </programlisting>
2586             <indexterm>
2587               <primary>commands</primary>
2588               <secondary>asetkey</secondary>
2589             </indexterm>
2590             <indexterm>
2591               <primary>creating</primary>
2592               <secondary>server encryption key</secondary>
2593               <tertiary>KeyFile file</tertiary>
2594             </indexterm>
2595             <indexterm>
2596               <primary>server encryption key</primary>
2597               <secondary>in KeyFile file</secondary>
2598             </indexterm></para>
2599         </listitem>
2600
2601         <listitem id="LIWQ58">
2602           <para>Issue the
2603           <emphasis role="bold">asetkey</emphasis> command to set the AFS
2604           server encryption key in the
2605           <emphasis role="bold">/usr/afs/etc/KeyFile</emphasis> file. This key
2606           is created from the <emphasis role="bold">/etc/afs.keytab</emphasis>
2607           file created earlier.</para>
2608
2609           <para>asetkey requires the key version number (or kvno) of the
2610           <emphasis role="bold">afs/</emphasis><replaceable>cell</replaceable>
2611           key. You should have made note of the kvno when creating the key
2612           earlier.  The key version number can also be found by running the
2613           <emphasis role="bold">kvno</emphasis> command</para>
2614 <programlisting>
2615    # <emphasis role="bold">kvno -k /etc/afs.keytab afs/</emphasis>&lt;<replaceable>cell name</replaceable>&gt;
2616 </programlisting>
2617
2618           <para>Once the kvno is known, the key can then be extracted using
2619           asetkey</para>
2620 <programlisting>
2621    # <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;
2622 </programlisting>
2623
2624           <indexterm>
2625             <primary>commands</primary>
2626             <secondary>bos listkeys</secondary>
2627           </indexterm>
2628
2629           <indexterm>
2630             <primary>bos commands</primary>
2631             <secondary>listkeys</secondary>
2632           </indexterm>
2633
2634           <indexterm>
2635             <primary>displaying</primary>
2636             <secondary>server encryption key</secondary>
2637             <tertiary>KeyFile file</tertiary>
2638           </indexterm>
2639         </listitem>
2640
2641         <listitem id="LIWQ59">
2642           <para>Issue the
2643           <emphasis role="bold">bos listkeys</emphasis> command to verify that
2644           the key version number for the new key in the
2645           <emphasis role="bold">KeyFile</emphasis> file is the same as the key
2646           version number in the Authentication Database's
2647           <emphasis role="bold">afs/<replaceable>cell name</replaceable></emphasis>
2648           entry, which you displayed in Step <link linkend="LIWQ55">3</link>.
2649 <programlisting>
2650    # <emphasis role="bold">./bos listkeys</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">-noauth</emphasis>
2651    key 0 has cksum <replaceable>checksum</replaceable>
2652 </programlisting></para>
2653
2654           <para>You can safely ignore any error messages indicating that <emphasis role="bold">bos</emphasis> failed to get tickets
2655           or that authentication failed.</para>
2656         </listitem>
2657       </orderedlist>
2658     </sect1>
2659     <sect1 id="HDRWQ53a">
2660       <title>Initializing the Protection Database</title>
2661
2662       <para>Now continue to configure your cell's security systems by
2663       populating the Protection Database with the newly created
2664       <emphasis role="bold">admin</emphasis> user, and permitting it
2665       to issue priviledged commands on the AFS filesystem.</para>
2666
2667         <orderedlist>
2668           <listitem>
2669           <indexterm>
2670             <primary>commands</primary>
2671             <secondary>pts createuser</secondary>
2672           </indexterm>
2673
2674           <indexterm>
2675             <primary>pts commands</primary>
2676             <secondary>createuser</secondary>
2677           </indexterm>
2678
2679           <indexterm>
2680             <primary>Protection Database</primary>
2681           </indexterm>
2682           <para>Issue the <emphasis role="bold">pts createuser</emphasis> command to create a Protection Database entry for the
2683           <emphasis role="bold">admin</emphasis> user.</para>
2684
2685           <para>By default, the Protection Server assigns AFS UID 1 (one) to the <emphasis role="bold">admin</emphasis> user,
2686           because it is the first user entry you are creating. If the local password file (<emphasis
2687           role="bold">/etc/passwd</emphasis> or equivalent) already has an entry for <emphasis role="bold">admin</emphasis> that
2688           assigns it a UNIX UID other than 1, it is best to use the <emphasis role="bold">-id</emphasis> argument to the <emphasis
2689           role="bold">pts createuser</emphasis> command to make the new AFS UID match the existing UNIX UID. Otherwise, it is best
2690           to accept the default.</para>
2691
2692           <programlisting>
2693    # <emphasis role="bold">pts createuser -name admin</emphasis> [<emphasis
2694               role="bold">-id</emphasis> &lt;<replaceable>AFS UID</replaceable>&gt;]  <emphasis role="bold">-noauth</emphasis>
2695    User admin has id <replaceable>AFS UID</replaceable>
2696 </programlisting>
2697
2698           <indexterm>
2699             <primary>commands</primary>
2700             <secondary>pts adduser</secondary>
2701           </indexterm>
2702
2703           <indexterm>
2704             <primary>pts commands</primary>
2705             <secondary>adduser</secondary>
2706           </indexterm>
2707
2708           <indexterm>
2709             <primary>system:administrators group</primary>
2710           </indexterm>
2711
2712           <indexterm>
2713             <primary>admin account</primary>
2714             <secondary>adding</secondary>
2715             <tertiary>to system:administrators group</tertiary>
2716           </indexterm>
2717         </listitem>
2718
2719         <listitem>
2720           <para>Issue the <emphasis role="bold">pts adduser</emphasis> command to make the <emphasis role="bold">admin</emphasis>
2721           user a member of the <emphasis role="bold">system:administrators</emphasis> group, and the <emphasis role="bold">pts
2722           membership</emphasis> command to verify the new membership. Membership in the group enables the <emphasis
2723           role="bold">admin</emphasis> user to issue privileged <emphasis role="bold">pts</emphasis> commands and some privileged
2724           <emphasis role="bold">fs</emphasis> commands. <programlisting>
2725    # <emphasis role="bold">./pts adduser admin system:administrators</emphasis> <emphasis role="bold">-noauth</emphasis>
2726    # <emphasis role="bold">./pts membership admin</emphasis> <emphasis role="bold">-noauth</emphasis>
2727    Groups admin (id: 1) is a member of:
2728      system:administrators
2729 </programlisting> <indexterm>
2730               <primary>commands</primary>
2731               <secondary>bos restart</secondary>
2732               <tertiary>on first AFS machine</tertiary>
2733             </indexterm> <indexterm>
2734               <primary>bos commands</primary>
2735               <secondary>restart</secondary>
2736               <tertiary>on first AFS machine</tertiary>
2737             </indexterm> <indexterm>
2738               <primary>restarting server process</primary>
2739               <secondary>on first AFS machine</secondary>
2740             </indexterm> <indexterm>
2741               <primary>server process</primary>
2742               <secondary>restarting</secondary>
2743               <tertiary>on first AFS machine</tertiary>
2744             </indexterm></para>
2745         </listitem>
2746
2747         <listitem>
2748           <para>Issue the <emphasis role="bold">bos restart</emphasis> command with the <emphasis role="bold">-all</emphasis> flag
2749           to restart the database server processes, so that they start using the new server encryption key. <programlisting>
2750    # <emphasis role="bold">./bos restart</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">-all</emphasis>
2751    <emphasis role="bold">-noauth</emphasis>
2752 </programlisting></para>
2753         </listitem>
2754       </orderedlist>
2755
2756     <indexterm>
2757       <primary>File Server</primary>
2758
2759       <secondary>first AFS machine</secondary>
2760     </indexterm>
2761
2762     <indexterm>
2763       <primary>fileserver process</primary>
2764
2765       <see>File Server</see>
2766     </indexterm>
2767
2768     <indexterm>
2769       <primary>starting</primary>
2770
2771       <secondary>File Server</secondary>
2772
2773       <tertiary>first AFS machine</tertiary>
2774     </indexterm>
2775
2776     <indexterm>
2777       <primary>first AFS machine</primary>
2778
2779       <secondary>File Server, fs process</secondary>
2780     </indexterm>
2781
2782     <indexterm>
2783       <primary>Volume Server</primary>
2784
2785       <secondary>first AFS machine</secondary>
2786     </indexterm>
2787
2788     <indexterm>
2789       <primary>volserver process</primary>
2790
2791       <see>Volume Server</see>
2792     </indexterm>
2793
2794     <indexterm>
2795       <primary>starting</primary>
2796
2797       <secondary>Volume Server</secondary>
2798
2799       <tertiary>first AFS machine</tertiary>
2800     </indexterm>
2801
2802     <indexterm>
2803       <primary>first AFS machine</primary>
2804
2805       <secondary>Volume Server</secondary>
2806     </indexterm>
2807
2808     <indexterm>
2809       <primary>Salvager (salvager process)</primary>
2810
2811       <secondary>first AFS machine</secondary>
2812     </indexterm>
2813
2814     <indexterm>
2815       <primary>fs process</primary>
2816
2817       <secondary>first AFS machine</secondary>
2818     </indexterm>
2819
2820     <indexterm>
2821       <primary>starting</primary>
2822
2823       <secondary>fs process</secondary>
2824
2825       <tertiary>first AFS machine</tertiary>
2826     </indexterm>
2827
2828     <indexterm>
2829       <primary>first AFS machine</primary>
2830
2831       <secondary>Salvager</secondary>
2832     </indexterm>
2833   </sect1>
2834
2835   <sect1 id="HDRWQ60">
2836     <title>Starting the File Server processes</title>
2837
2838     <para>Start the
2839     <emphasis role="bold">dafs</emphasis> process.
2840     The <emphasis role="bold">dafs</emphasis> process consists of the
2841     Demand-Attach File Server, Volume Server, Salvage Server, and Salvager (<emphasis role="bold">dafileserver</emphasis>,
2842     <emphasis role="bold"> davolserver</emphasis>, <emphasis role="bold">salvageserver</emphasis>, and <emphasis
2843     role="bold">dasalvager</emphasis> processes). Most sites should run the
2844     Demand-Attach File Server, but the traditional/legacy File Server remains
2845     an option.  If you are uncertain whether to run the legacy File Server,
2846     see <link linkend="DAFS">Appendix C, The Demand-Attach File Server</link>.
2847      <orderedlist>
2848         <listitem>
2849           <para>Issue the <emphasis role="bold">bos create</emphasis> command to start the
2850           <emphasis role="bold">dafs</emphasis> process. The commands appear here on multiple lines only for legibility.
2851
2852             <itemizedlist>
2853              <listitem>
2854                <para>Create the <emphasis
2855                role="bold">dafs</emphasis> process:
2856                   <programlisting>
2857    # <emphasis role="bold">./bos create</emphasis>  &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">dafs dafs /usr/afs/bin/dafileserver</emphasis>   \
2858                    <emphasis role="bold">/usr/afs/bin/davolserver /usr/afs/bin/salvageserver</emphasis> \
2859                    <emphasis role="bold">/usr/afs/bin/dasalvager</emphasis> <emphasis role="bold">-noauth</emphasis>
2860 </programlisting></para>
2861              </listitem>
2862             </itemizedlist>
2863           </para>
2864
2865           <para>Sometimes a message about Volume Location Database (VLDB) initialization appears, along with one or more instances
2866           of an error message similar to the following:</para>
2867
2868           <programlisting>
2869    FSYNC_clientInit temporary failure (will retry)
2870 </programlisting>
2871
2872           <para>This message appears when the <emphasis role="bold">volserver</emphasis> process tries to start before the <emphasis
2873           role="bold">fileserver</emphasis> process has completed its initialization. Wait a few minutes after the last such message
2874           before continuing, to guarantee that both processes have started successfully. <indexterm>
2875               <primary>commands</primary>
2876
2877               <secondary>bos status</secondary>
2878             </indexterm> <indexterm>
2879               <primary>bos commands</primary>
2880
2881               <secondary>status</secondary>
2882             </indexterm></para>
2883
2884           <para>You can verify that the <emphasis role="bold">dafs</emphasis> process has started
2885           successfully by issuing the <emphasis role="bold">bos status</emphasis> command. Its output mentions two <computeroutput>proc
2886           starts</computeroutput>.</para>
2887
2888               <para>If you are running the Demand-Attach File Server:
2889           <programlisting>
2890    # <emphasis role="bold">./bos status</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">dafs -long -noauth</emphasis>
2891 </programlisting></para>
2892         </listitem>
2893
2894         <listitem>
2895           <para>Your next action depends on whether you have ever run AFS file server machines in the cell: <itemizedlist>
2896               <indexterm>
2897                 <primary>commands</primary>
2898
2899                 <secondary>vos create</secondary>
2900
2901                 <tertiary>root.afs volume</tertiary>
2902               </indexterm>
2903
2904               <indexterm>
2905                 <primary>vos commands</primary>
2906
2907                 <secondary>create</secondary>
2908
2909                 <tertiary>root.afs volume</tertiary>
2910               </indexterm>
2911
2912               <indexterm>
2913                 <primary>root.afs volume</primary>
2914
2915                 <secondary>creating</secondary>
2916               </indexterm>
2917
2918               <indexterm>
2919                 <primary>volume</primary>
2920
2921                 <secondary>creating</secondary>
2922
2923                 <tertiary>root.afs</tertiary>
2924               </indexterm>
2925
2926               <indexterm>
2927                 <primary>creating</primary>
2928
2929                 <secondary>root.afs volume</secondary>
2930               </indexterm>
2931
2932               <listitem>
2933                 <para>If you are installing the first AFS server machine ever in the cell (that is, you are not upgrading the AFS
2934                 software from a previous version), create the first AFS volume, <emphasis role="bold">root.afs</emphasis>.</para>
2935
2936                 <para>For the <replaceable>partition name</replaceable> argument, substitute the name of one of the machine's AFS
2937                 server partitions (such as <emphasis role="bold">/vicepa</emphasis>).</para>
2938
2939                 <programlisting>
2940    # <emphasis role="bold">./vos create</emphasis>  &lt;<replaceable>machine name</replaceable>&gt; &lt;<replaceable>partition name</replaceable>&gt; <emphasis
2941                     role="bold">root.afs</emphasis>   \
2942                    <emphasis role="bold">-noauth</emphasis>
2943 </programlisting>
2944
2945                 <para>The Volume Server produces a message confirming that it created the volume on the specified partition. You can
2946                 ignore error messages indicating that tokens are missing, or that authentication failed. <indexterm>
2947                     <primary>commands</primary>
2948
2949                     <secondary>vos syncvldb</secondary>
2950                   </indexterm> <indexterm>
2951                     <primary>vos commands</primary>
2952
2953                     <secondary>syncvldb</secondary>
2954                   </indexterm> <indexterm>
2955                     <primary>commands</primary>
2956
2957                     <secondary>vos syncserv</secondary>
2958                   </indexterm> <indexterm>
2959                     <primary>vos commands</primary>
2960
2961                     <secondary>syncserv</secondary>
2962                   </indexterm></para>
2963               </listitem>
2964
2965               <listitem>
2966                 <para>If there are existing AFS file server machines and volumes in the cell, issue the <emphasis role="bold">vos
2967                 syncvldb</emphasis> and <emphasis role="bold">vos syncserv</emphasis> commands to synchronize the VLDB with the
2968                 actual state of volumes on the local machine. To follow the progress of the synchronization operation, which can
2969                 take several minutes, use the <emphasis role="bold">-verbose</emphasis> flag. <programlisting>
2970    # <emphasis role="bold">./vos syncvldb</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis
2971                       role="bold">-verbose  -noauth</emphasis>
2972    # <emphasis role="bold">./vos syncserv</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis
2973                       role="bold">-verbose  -noauth</emphasis>
2974 </programlisting></para>
2975
2976                 <para>You can ignore error messages indicating that tokens are missing, or that authentication failed.</para>
2977               </listitem>
2978             </itemizedlist></para>
2979         </listitem>
2980       </orderedlist></para>
2981
2982     <indexterm>
2983       <primary>Update Server</primary>
2984
2985       <secondary>starting server portion</secondary>
2986
2987       <tertiary>first AFS machine</tertiary>
2988     </indexterm>
2989
2990     <indexterm>
2991       <primary>upserver process</primary>
2992
2993       <see>Update Server</see>
2994     </indexterm>
2995
2996     <indexterm>
2997       <primary>starting</primary>
2998
2999       <secondary>Update Server server portion</secondary>
3000
3001       <tertiary>first AFS machine</tertiary>
3002     </indexterm>
3003
3004     <indexterm>
3005       <primary>first AFS machine</primary>
3006
3007       <secondary>Update Server server portion</secondary>
3008     </indexterm>
3009
3010     <indexterm>
3011       <primary>first AFS machine</primary>
3012
3013       <secondary>defining</secondary>
3014
3015       <tertiary>as binary distribution machine</tertiary>
3016     </indexterm>
3017
3018     <indexterm>
3019       <primary>first AFS machine</primary>
3020
3021       <secondary>defining</secondary>
3022
3023       <tertiary>as system control machine</tertiary>
3024     </indexterm>
3025
3026     <indexterm>
3027       <primary>system control machine</primary>
3028     </indexterm>
3029
3030     <indexterm>
3031       <primary>binary distribution machine</primary>
3032     </indexterm>
3033   </sect1>
3034
3035   <sect1 id="HDRWQ62">
3036     <title>Clock Sync Considerations</title>
3037
3038     <para>Keeping the clocks on all server and client machines in your cell synchronized is crucial to several functions, and in
3039     particular to the correct operation of AFS's distributed database technology, Ubik. The chapter in the <emphasis>OpenAFS
3040     Administration Guide</emphasis> about administering server machines explains how time skew can disturb Ubik's performance and
3041     cause service outages in your cell.</para>
3042
3043     <para>You should install and configure your time service independently of
3044     AFS. Your Kerberos realm will also require a reliable time source, so your site
3045     may already have one available.</para>
3046
3047     <indexterm>
3048       <primary>overview</primary>
3049
3050       <secondary>installing client functionality on first machine</secondary>
3051     </indexterm>
3052
3053     <indexterm>
3054       <primary>first AFS machine</primary>
3055
3056       <secondary>client functionality</secondary>
3057
3058       <tertiary>installing</tertiary>
3059     </indexterm>
3060
3061     <indexterm>
3062       <primary>installing</primary>
3063
3064       <secondary>client functionality</secondary>
3065
3066       <tertiary>first AFS machine</tertiary>
3067     </indexterm>
3068   </sect1>
3069
3070   <sect1 id="HDRWQ63">
3071     <title>Overview: Installing Client Functionality</title>
3072
3073     <para>The machine you are installing is now an AFS file server machine,
3074     database server machine, system control machine, and binary distribution
3075     machine. Now make it a client machine by completing the following tasks:
3076     <orderedlist>
3077         <listitem>
3078           <para>Define the machine's cell membership for client processes</para>
3079         </listitem>
3080
3081         <listitem>
3082           <para>Create the client version of the <emphasis role="bold">CellServDB</emphasis> file</para>
3083         </listitem>
3084
3085         <listitem>
3086           <para>Define cache location and size</para>
3087         </listitem>
3088
3089         <listitem>
3090           <para>Create the <emphasis role="bold">/afs</emphasis> directory and start the Cache Manager</para>
3091         </listitem>
3092       </orderedlist></para>
3093
3094     <indexterm>
3095       <primary>Distribution</primary>
3096
3097       <secondary>copying client files from</secondary>
3098
3099       <tertiary>first AFS machine</tertiary>
3100     </indexterm>
3101
3102     <indexterm>
3103       <primary>first AFS machine</primary>
3104
3105       <secondary>copying</secondary>
3106
3107       <tertiary>client files to local disk</tertiary>
3108     </indexterm>
3109
3110     <indexterm>
3111       <primary>copying</primary>
3112
3113       <secondary>client files to local disk</secondary>
3114
3115       <tertiary>first AFS machine</tertiary>
3116     </indexterm>
3117   </sect1>
3118
3119   <sect1 id="HDRWQ64">
3120     <title>Copying Client Files to the Local Disk</title>
3121
3122     <para>You need only undertake the steps in this section, if you are using
3123     a tar file distribution, or one built from scratch. Packaged distributions,
3124     such as RPMs or DEBs will already have installed the necessary files in
3125     the correct locations.</para>
3126
3127     <para>Before installing and configuring the AFS client, copy the necessary files from the tarball to the local <emphasis
3128     role="bold">/usr/vice/etc</emphasis> directory. <orderedlist>
3129         <listitem>
3130           <para>If you have not already done so, unpack the distribution
3131           tarball for this machine's system type into a suitable location on
3132           the filesystem, such as <emphasis role="bold">/tmp/afsdist</emphasis>.
3133           If you use a different location, substitue that in the examples that
3134           follow.</para>
3135         </listitem>
3136
3137         <listitem>
3138           <para>Copy files to the local <emphasis role="bold">/usr/vice/etc</emphasis> directory.</para>
3139
3140           <para>This step places a copy of the AFS initialization script (and related files, if applicable) into the <emphasis
3141           role="bold">/usr/vice/etc</emphasis> directory. In the preceding instructions for incorporating AFS into the kernel, you
3142           copied the script directly to the operating system's conventional location for initialization files. When you incorporate
3143           AFS into the machine's startup sequence in a later step, you can choose to link the two files.</para>
3144
3145           <para>On some system types that use a dynamic kernel loader program, you previously copied AFS library files into a
3146           subdirectory of the <emphasis role="bold">/usr/vice/etc</emphasis> directory. On other system types, you copied the
3147           appropriate AFS library file directly to the directory where the operating system accesses it. The following commands do
3148           not copy or recopy the AFS library files into the <emphasis role="bold">/usr/vice/etc</emphasis> directory, because on
3149           some system types the library files consume a large amount of space. If you want to copy them, add the <emphasis
3150           role="bold">-r</emphasis> flag to the first <emphasis role="bold">cp</emphasis> command and skip the second <emphasis
3151           role="bold">cp</emphasis> command.</para>
3152
3153           <programlisting>
3154    # <emphasis role="bold">cd /tmp/afsdist/</emphasis><replaceable>sysname</replaceable><emphasis role="bold">/root.client/usr/vice/etc</emphasis>
3155    # <emphasis role="bold">cp -p  *  /usr/vice/etc</emphasis>
3156    # <emphasis role="bold">cp -rp  C  /usr/vice/etc</emphasis>
3157 </programlisting>
3158         </listitem>
3159       </orderedlist></para>
3160
3161     <indexterm>
3162       <primary>cell name</primary>
3163
3164       <secondary>setting in client ThisCell file</secondary>
3165
3166       <tertiary>first AFS machine</tertiary>
3167     </indexterm>
3168
3169     <indexterm>
3170       <primary>setting</primary>
3171
3172       <secondary>cell name in client ThisCell file</secondary>
3173
3174       <tertiary>first AFS machine</tertiary>
3175     </indexterm>
3176
3177     <indexterm>
3178       <primary>first AFS machine</primary>
3179
3180       <secondary>ThisCell file (client)</secondary>
3181     </indexterm>
3182
3183     <indexterm>
3184       <primary>first AFS machine</primary>
3185
3186       <secondary>cell membership, defining</secondary>
3187
3188       <tertiary>for client processes</tertiary>
3189     </indexterm>
3190
3191     <indexterm>
3192       <primary>usr/vice/etc/ThisCell</primary>
3193
3194       <see>ThisCell file (client)</see>
3195     </indexterm>
3196
3197     <indexterm>
3198       <primary>ThisCell file (client)</primary>
3199
3200       <secondary>first AFS machine</secondary>
3201     </indexterm>
3202
3203     <indexterm>
3204       <primary>files</primary>
3205
3206       <secondary>ThisCell (client)</secondary>
3207     </indexterm>
3208   </sect1>
3209
3210   <sect1 id="HDRWQ65">
3211     <title>Defining Cell Membership for Client Processes</title>
3212
3213     <para>Every AFS client machine has a copy of the <emphasis role="bold">/usr/vice/etc/ThisCell</emphasis> file on its local disk
3214     to define the machine's cell membership for the AFS client programs that run on it. The <emphasis
3215     role="bold">ThisCell</emphasis> file you created in the <emphasis role="bold">/usr/afs/etc</emphasis> directory (in <link
3216     linkend="HDRWQ51">Defining Cell Name and Membership for Server Processes</link>) is used only by server processes.</para>
3217
3218     <para>Among other functions, the <emphasis role="bold">ThisCell</emphasis> file on a client machine determines the following:
3219     <itemizedlist>
3220         <listitem>
3221           <para>The cell in which users gain tokens when they log onto the
3222           machine, assuming it is using an AFS-modified login utility</para>
3223         </listitem>
3224
3225         <listitem>
3226           <para>The cell in which users gain tokens by default when they issue
3227           the <emphasis role="bold">aklog</emphasis> command</para>
3228         </listitem>
3229
3230         <listitem>
3231           <para>The cell membership of the AFS server processes that the AFS
3232           command interpreters on this machine contact by default</para>
3233         </listitem>
3234       </itemizedlist>
3235     <orderedlist>
3236         <listitem>
3237           <para>Change to the <emphasis role="bold">/usr/vice/etc</emphasis> directory and remove the symbolic link created in <link
3238           linkend="HDRWQ50">Starting the BOS Server</link>. <programlisting>
3239    # <emphasis role="bold">cd /usr/vice/etc</emphasis>
3240    # <emphasis role="bold">rm ThisCell</emphasis>
3241 </programlisting></para>
3242         </listitem>
3243
3244         <listitem>
3245           <para>Create the <emphasis role="bold">ThisCell</emphasis> file as a copy of the <emphasis
3246           role="bold">/usr/afs/etc/ThisCell</emphasis> file. Defining the same local cell for both server and client processes leads
3247           to the most consistent AFS performance. <programlisting>
3248    # <emphasis role="bold">cp  /usr/afs/etc/ThisCell  ThisCell</emphasis>
3249 </programlisting></para>
3250         </listitem>
3251       </orderedlist></para>
3252
3253     <indexterm>
3254       <primary>database server machine</primary>
3255
3256       <secondary>entry in client CellServDB file</secondary>
3257
3258       <tertiary>on first AFS machine</tertiary>
3259     </indexterm>
3260
3261     <indexterm>
3262       <primary>usr/vice/etc/CellServDB</primary>
3263
3264       <see>CellServDB file (client)</see>
3265     </indexterm>
3266
3267     <indexterm>
3268       <primary>CellServDB file (client)</primary>
3269
3270       <secondary>creating</secondary>
3271
3272       <tertiary>on first AFS machine</tertiary>
3273     </indexterm>
3274
3275     <indexterm>
3276       <primary>creating</primary>
3277
3278       <secondary>CellServDB file (client)</secondary>
3279
3280       <tertiary>first AFS machine</tertiary>
3281     </indexterm>
3282
3283     <indexterm>
3284       <primary>CellServDB file (client)</primary>
3285
3286       <secondary>required format</secondary>
3287     </indexterm>
3288
3289     <indexterm>
3290       <primary>requirements</primary>
3291
3292       <secondary>CellServDB file format (client version)</secondary>
3293     </indexterm>
3294
3295     <indexterm>
3296       <primary>files</primary>
3297
3298       <secondary>CellServDB (client)</secondary>
3299     </indexterm>
3300
3301     <indexterm>
3302       <primary>first AFS machine</primary>
3303
3304       <secondary>CellServDB file (client)</secondary>
3305     </indexterm>
3306   </sect1>
3307
3308   <sect1 id="HDRWQ66">
3309     <title>Creating the Client CellServDB File</title>
3310
3311     <para>The <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file on a client machine's local disk lists the database
3312     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
3313     list of database server machines is wrong, then users working on this machine cannot access the cell. The chapter in the
3314     <emphasis>OpenAFS Administration Guide</emphasis> about administering client machines explains how to maintain the file after
3315     creating it.</para>
3316
3317     <para>As the <emphasis role="bold">afsd</emphasis> program initializes the Cache Manager, it copies the contents of the
3318     <emphasis role="bold">CellServDB</emphasis> file into kernel memory. The Cache Manager always consults the list in kernel memory
3319     rather than the <emphasis role="bold">CellServDB</emphasis> file itself. Between reboots of the machine, you can use the
3320     <emphasis role="bold">fs newcell</emphasis> command to update the list in kernel memory directly; see the chapter in the
3321     <emphasis>OpenAFS Administration Guide</emphasis> about administering client machines.</para>
3322
3323     <para>The AFS distribution includes the file
3324     <emphasis role="bold">CellServDB.dist</emphasis>. It includes an entry for
3325     all AFS cells that agreed to share their database server machine
3326     information at the time the distribution was
3327     created. The definitive copy of this file is maintained at
3328     grand.central.org, and updates may be obtained from
3329     /afs/grand.central.org/service/CellServDB or
3330     <ulink url="http://grand.central.org/dl/cellservdb/CellServDB">
3331     http://grand.central.org/dl/cellservdb/CellServDB</ulink></para>
3332
3333     <para>The <emphasis role="bold">CellServDB.dist</emphasis> file can be a
3334     good basis for the client <emphasis role="bold">CellServDB</emphasis> file,
3335     because all of the entries in it use the correct format. You can add or
3336     remove cell entries as you see fit. Depending on your cache manager
3337     configuration, additional steps (as detailed in
3338     <link linkend="HDRWQ91">Enabling Access to Foreign Cells</link>) may be
3339     required to enable the Cache Manager to actually reach the cells.</para>
3340
3341     <para>In this section, you add an entry for the local cell to the local <emphasis role="bold">CellServDB</emphasis> file. The
3342     current working directory is still <emphasis role="bold">/usr/vice/etc</emphasis>. <orderedlist>
3343         <listitem>
3344           <para>Remove the symbolic link created in <link linkend="HDRWQ50">Starting the BOS Server</link> and rename the <emphasis
3345           role="bold">CellServDB.sample</emphasis> file to <emphasis role="bold">CellServDB</emphasis>. <programlisting>
3346    # <emphasis role="bold">rm CellServDB</emphasis>
3347    # <emphasis role="bold">mv CellServDB.sample CellServDB</emphasis>
3348 </programlisting></para>
3349         </listitem>
3350
3351         <listitem>
3352           <para>Add an entry for the local cell to the <emphasis role="bold">CellServDB</emphasis> file. One easy method is to use
3353           the <emphasis role="bold">cat</emphasis> command to append the contents of the server <emphasis
3354           role="bold">/usr/afs/etc/CellServDB</emphasis> file to the client version. <programlisting>
3355     # <emphasis role="bold">cat  /usr/afs/etc/CellServDB &gt;&gt;  CellServDB</emphasis>
3356 </programlisting></para>
3357
3358           <para>Then open the file in a text editor to verify that there are no blank lines, and that all entries have the required
3359           format, which is described just following. The ordering of cells is not significant, but it can be convenient to have the
3360           client machine's home cell at the top; move it there now if you wish. <itemizedlist>
3361               <listitem>
3362                 <para>The first line of a cell's entry has the following format: <programlisting>
3363    &gt;<replaceable>cell_name</replaceable>      #<replaceable>organization</replaceable>
3364 </programlisting></para>
3365
3366                 <para>where <replaceable>cell_name</replaceable> is the cell's complete Internet domain name (for example, <emphasis
3367                 role="bold">example.com</emphasis>) and <replaceable>organization</replaceable> is an optional field that follows any
3368                 number of spaces and the number sign (<computeroutput>#</computeroutput>). By convention it names the organization
3369                 to which the cell corresponds (for example, the Example Corporation).</para>
3370               </listitem>
3371
3372               <listitem>
3373                 <para>After the first line comes a separate line for each database server machine. Each line has the following
3374                 format: <programlisting>
3375    <replaceable>IP_address</replaceable>   #<replaceable>machine_name</replaceable>
3376 </programlisting></para>
3377
3378                 <para>where <replaceable>IP_address</replaceable> is the machine's IP address in dotted decimal format (for example,
3379                 192.12.105.3). Following any number of spaces and the number sign (<computeroutput>#</computeroutput>) is
3380                 <replaceable>machine_name</replaceable>, the machine's fully-qualified hostname (for example, <emphasis
3381                 role="bold">db1.example.com</emphasis>). In this case, the number sign does not indicate a comment;
3382                 <replaceable>machine_name</replaceable> is a required field.</para>
3383               </listitem>
3384             </itemizedlist></para>
3385         </listitem>
3386
3387         <listitem>
3388           <para>If the file includes cells that you do not wish users of this machine to access, remove their entries.</para>
3389         </listitem>
3390       </orderedlist></para>
3391
3392     <para>The following example shows entries for two cells, each of which has three database server machines:</para>
3393
3394     <programlisting>
3395    &gt;example.com       #Example Corporation (home cell)
3396    192.12.105.3      #db1.example.com
3397    192.12.105.4      #db2.example.com
3398    192.12.105.55     #db3.example.com
3399    &gt;example.org    #Example Organization cell
3400    138.255.68.93     #serverA.example.org
3401    138.255.68.72     #serverB.example.org
3402    138.255.33.154    #serverC.example.org
3403 </programlisting>
3404
3405     <indexterm>
3406       <primary>cache</primary>
3407
3408       <secondary>configuring</secondary>
3409
3410       <tertiary>first AFS machine</tertiary>
3411     </indexterm>
3412
3413     <indexterm>
3414       <primary>configuring</primary>
3415
3416       <secondary>cache</secondary>
3417
3418       <tertiary>first AFS machine</tertiary>
3419     </indexterm>
3420
3421     <indexterm>
3422       <primary>setting</primary>
3423
3424       <secondary>cache size and location</secondary>
3425
3426       <tertiary>first AFS machine</tertiary>
3427     </indexterm>
3428
3429     <indexterm>
3430       <primary>first AFS machine</primary>
3431
3432       <secondary>cache size and location</secondary>
3433     </indexterm>
3434   </sect1>
3435
3436   <sect1 id="HDRWQ67">
3437     <title>Configuring the Cache</title>
3438
3439     <para>The Cache Manager uses a cache on the local disk or in machine memory to store local copies of files fetched from file
3440     server machines. As the <emphasis role="bold">afsd</emphasis> program initializes the Cache Manager, it sets basic cache
3441     configuration parameters according to definitions in the local <emphasis role="bold">/usr/vice/etc/cacheinfo</emphasis> file.
3442     The file has three fields: <orderedlist>
3443         <listitem>
3444           <para>The first field names the local directory on which to mount the AFS filespace. The conventional location is the
3445           <emphasis role="bold">/afs</emphasis> directory.</para>
3446         </listitem>
3447
3448         <listitem>
3449           <para>The second field defines the local disk directory to use for the disk cache. The conventional location is the
3450           <emphasis role="bold">/usr/vice/cache</emphasis> directory, but you can specify an alternate directory if another
3451           partition has more space available. There must always be a value in this field, but the Cache Manager ignores it if the
3452           machine uses a memory cache.</para>
3453         </listitem>
3454
3455         <listitem>
3456           <para>The third field specifies the number of kilobyte (1024 byte) blocks to allocate for the cache.</para>
3457         </listitem>
3458       </orderedlist></para>
3459
3460     <para>The values you define must meet the following requirements. <itemizedlist>
3461         <listitem>
3462           <para>On a machine using a disk cache, the Cache Manager expects always to be able to use the amount of space specified in
3463           the third field. Failure to meet this requirement can cause serious problems, some of which can be repaired only by
3464           rebooting. You must prevent non-AFS processes from filling up the cache partition. The simplest way is to devote a
3465           partition to the cache exclusively.</para>
3466         </listitem>
3467
3468         <listitem>
3469           <para>The amount of space available in memory or on the partition housing the disk cache directory imposes an absolute
3470           limit on cache size.</para>
3471         </listitem>
3472
3473         <listitem>
3474           <para>The maximum supported cache size can vary in each AFS release; see the <emphasis>OpenAFS Release Notes</emphasis>
3475           for the current version.</para>
3476         </listitem>
3477
3478         <listitem>
3479           <para>For a disk cache, you cannot specify a value in the third field that exceeds 95% of the space available on the
3480           partition mounted at the directory named in the second field. If you violate this restriction, the <emphasis
3481           role="bold">afsd</emphasis> program exits without starting the Cache Manager and prints an appropriate message on the
3482           standard output stream. A value of 90% is more appropriate on most machines. Some operating systems (such as AIX) do not
3483           automatically reserve some space to prevent the partition from filling completely; for them, a smaller value (say, 80% to
3484           85% of the space available) is more appropriate.</para>
3485         </listitem>
3486
3487         <listitem>
3488           <para>For a memory cache, you must leave enough memory for other processes and applications to run. If you try to allocate
3489           more memory than is actually available, the <emphasis role="bold">afsd</emphasis> program exits without initializing the
3490           Cache Manager and produces the following message on the standard output stream. <programlisting>
3491    afsd: memCache allocation failure at <replaceable>number</replaceable> KB
3492 </programlisting></para>
3493
3494           <para>The <replaceable>number</replaceable> value is how many kilobytes were allocated just before the failure, and so
3495           indicates the approximate amount of memory available.</para>
3496         </listitem>
3497       </itemizedlist></para>
3498
3499     <para>Within these hard limits, the factors that determine appropriate cache size include the number of users working on the
3500     machine, the size of the files with which they work, and (for a memory cache) the number of processes that run on the machine.
3501     The higher the demand from these factors, the larger the cache needs to be to maintain good performance.</para>
3502
3503     <para>Disk caches smaller than 10 MB do not generally perform well. Machines serving multiple users usually perform better with
3504     a cache of at least 60 to 70 MB. The point at which enlarging the cache further does not really improve performance depends on
3505     the factors mentioned previously and is difficult to predict.</para>
3506
3507     <para>Memory caches smaller than 1 MB are nonfunctional, and the performance of caches smaller than 5 MB is usually
3508     unsatisfactory. Suitable upper limits are similar to those for disk caches but are probably determined more by the demands on
3509     memory from other sources on the machine (number of users and processes). Machines running only a few processes possibly can use
3510     a smaller memory cache.</para>
3511
3512     <sect2 id="HDRWQ68">
3513       <title>Configuring a Disk Cache</title>
3514
3515       <note>
3516         <para>Not all file system types that an operating system supports are necessarily supported for use as the cache partition.
3517         For possible restrictions, see the <emphasis>OpenAFS Release Notes</emphasis>.</para>
3518       </note>
3519
3520       <para>To configure the disk cache, perform the following procedures: <orderedlist>
3521           <listitem>
3522             <para>Create the local directory to use for caching. The following instruction shows the conventional location,
3523             <emphasis role="bold">/usr/vice/cache</emphasis>. If you are devoting a partition exclusively to caching, as
3524             recommended, you must also configure it, make a file system on it, and mount it at the directory created in this step.
3525             <programlisting>
3526    # <emphasis role="bold">mkdir /usr/vice/cache</emphasis>
3527 </programlisting></para>
3528           </listitem>
3529
3530           <listitem>
3531             <para>Create the <emphasis role="bold">cacheinfo</emphasis> file to define the configuration parameters discussed
3532             previously. The following instruction shows the standard mount location, <emphasis role="bold">/afs</emphasis>, and the
3533             standard cache location, <emphasis role="bold">/usr/vice/cache</emphasis>. <programlisting>
3534    # <emphasis role="bold">echo "/afs:/usr/vice/cache:</emphasis><replaceable>#blocks</replaceable><emphasis role="bold">" &gt; /usr/vice/etc/cacheinfo</emphasis>
3535 </programlisting></para>
3536
3537             <para>The following example defines the disk cache size as 50,000 KB:</para>
3538
3539             <programlisting>
3540    # <emphasis role="bold">echo "/afs:/usr/vice/cache:50000" &gt; /usr/vice/etc/cacheinfo</emphasis>
3541 </programlisting>
3542           </listitem>
3543         </orderedlist></para>
3544     </sect2>
3545
3546     <sect2 id="HDRWQ69">
3547       <title>Configuring a Memory Cache</title>
3548
3549       <para>To configure a memory cache, create the <emphasis role="bold">cacheinfo</emphasis> file to define the configuration
3550       parameters discussed previously. The following instruction shows the standard mount location, <emphasis
3551       role="bold">/afs</emphasis>, and the standard cache location, <emphasis role="bold">/usr/vice/cache</emphasis> (though the
3552       exact value of the latter is irrelevant for a memory cache).</para>
3553
3554       <programlisting>
3555    # <emphasis role="bold">echo "/afs:/usr/vice/cache:</emphasis><replaceable>#blocks</replaceable><emphasis role="bold">" &gt; /usr/vice/etc/cacheinfo</emphasis>
3556 </programlisting>
3557
3558       <para>The following example allocates 25,000 KB of memory for the cache.</para>
3559
3560       <programlisting>
3561    # <emphasis role="bold">echo "/afs:/usr/vice/cache:25000" &gt; /usr/vice/etc/cacheinfo</emphasis>
3562 </programlisting>
3563
3564       <indexterm>
3565         <primary>Cache Manager</primary>
3566
3567         <secondary>first AFS machine</secondary>
3568       </indexterm>
3569
3570       <indexterm>
3571         <primary>configuring</primary>
3572
3573         <secondary>Cache Manager</secondary>
3574
3575         <tertiary>first AFS machine</tertiary>
3576       </indexterm>
3577
3578       <indexterm>
3579         <primary>first AFS machine</primary>
3580
3581         <secondary>Cache Manager</secondary>
3582       </indexterm>
3583
3584       <indexterm>
3585         <primary>afs (/afs) directory</primary>
3586
3587         <secondary>creating</secondary>
3588
3589         <tertiary>first AFS machine</tertiary>
3590       </indexterm>
3591
3592       <indexterm>
3593         <primary>AFS initialization script</primary>
3594
3595         <secondary>setting afsd parameters</secondary>
3596
3597         <tertiary>first AFS machine</tertiary>
3598       </indexterm>
3599
3600       <indexterm>
3601         <primary>first AFS machine</primary>
3602
3603         <secondary>afsd command parameters</secondary>
3604       </indexterm>
3605     </sect2>
3606   </sect1>
3607
3608   <sect1 id="HDRWQ70">
3609     <title>Configuring the Cache Manager</title>
3610
3611     <para>By convention, the Cache Manager mounts the AFS filespace on the local <emphasis role="bold">/afs</emphasis> directory. In
3612     this section you create that directory.</para>
3613
3614     <para>The <emphasis role="bold">afsd</emphasis> program sets several cache configuration parameters as it initializes the Cache
3615     Manager, and starts daemons that improve performance. You can use the <emphasis role="bold">afsd</emphasis> command's arguments
3616     to override the parameters' default values and to change the number of some of the daemons. Depending on the machine's cache
3617     size, its amount of RAM, and how many people work on it, you can sometimes improve Cache Manager performance by overriding the
3618     default values. For a discussion of all of the <emphasis role="bold">afsd</emphasis> command's arguments, see its reference page
3619     in the <emphasis>OpenAFS Administration Reference</emphasis>.</para>
3620
3621     <para>On platforms using the standard 'afs' initialisation script (this does not apply to Fedora or RHEL based distributions), the <emphasis role="bold">afsd</emphasis> command line in the AFS initialization script on each system type includes an
3622     <computeroutput>OPTIONS</computeroutput> variable. You can use it to set nondefault values for the command's arguments, in one
3623     of the following ways: <itemizedlist>
3624         <listitem>
3625           <para>You can create an <emphasis role="bold">afsd</emphasis> <emphasis>options file</emphasis> that sets values for
3626           arguments to the <emphasis role="bold">afsd</emphasis> command. If the file exists, its contents are automatically
3627           substituted for the <computeroutput>OPTIONS</computeroutput> variable in the AFS initialization script. The AFS
3628           distribution for some system types includes an options file; on other system types, you must create it.</para>
3629
3630           <para>You use two variables in the AFS initialization script to specify the path to the options file:
3631           <computeroutput>CONFIG</computeroutput> and <computeroutput>AFSDOPT</computeroutput>. On system types that define a
3632           conventional directory for configuration files, the <computeroutput>CONFIG</computeroutput> variable indicates it by
3633           default; otherwise, the variable indicates an appropriate location.</para>
3634
3635           <para>List the desired <emphasis role="bold">afsd</emphasis> options on a single line in the options file, separating each
3636           option with one or more spaces. The following example sets the <emphasis role="bold">-stat</emphasis> argument to 2500,
3637           the <emphasis role="bold">-daemons</emphasis> argument to 4, and the <emphasis role="bold">-volumes</emphasis> argument to
3638           100.</para>
3639
3640           <programlisting>
3641    -stat 2500 -daemons 4 -volumes 100
3642 </programlisting>
3643         </listitem>
3644
3645         <listitem>
3646           <para>On a machine that uses a disk cache, you can set the <computeroutput>OPTIONS</computeroutput> variable in the AFS
3647           initialization script to one of <computeroutput>$SMALL</computeroutput>, <computeroutput>$MEDIUM</computeroutput>, or
3648           <computeroutput>$LARGE</computeroutput>. The AFS initialization script uses one of these settings if the <emphasis
3649           role="bold">afsd</emphasis> options file named by the <computeroutput>AFSDOPT</computeroutput> variable does not exist. In
3650           the script as distributed, the <computeroutput>OPTIONS</computeroutput> variable is set to the value
3651           <computeroutput>$MEDIUM</computeroutput>.</para>
3652
3653           <note>
3654             <para>Do not set the <computeroutput>OPTIONS</computeroutput> variable to <computeroutput>$SMALL</computeroutput>,
3655             <computeroutput>$MEDIUM</computeroutput>, or <computeroutput>$LARGE</computeroutput> on a machine that uses a memory
3656             cache. The arguments it sets are appropriate only on a machine that uses a disk cache.</para>
3657           </note>
3658
3659           <para>The script (or on some system types the <emphasis role="bold">afsd</emphasis> options file named by the
3660           <computeroutput>AFSDOPT</computeroutput> variable) defines a value for each of <computeroutput>SMALL</computeroutput>,
3661           <computeroutput>MEDIUM</computeroutput>, and <computeroutput>LARGE</computeroutput> that sets <emphasis
3662           role="bold">afsd</emphasis> command arguments appropriately for client machines of different sizes: <itemizedlist>
3663               <listitem>
3664                 <para><computeroutput>SMALL</computeroutput> is suitable for a small machine that serves one or two users and has
3665                 approximately 8 MB of RAM and a 20-MB cache</para>
3666               </listitem>
3667
3668               <listitem>
3669                 <para><computeroutput>MEDIUM</computeroutput> is suitable for a medium-sized machine that serves two to six users
3670                 and has 16 MB of RAM and a 40-MB cache</para>
3671               </listitem>
3672
3673               <listitem>
3674                 <para><computeroutput>LARGE</computeroutput> is suitable for a large machine that serves five to ten users and has
3675                 32 MB of RAM and a 100-MB cache</para>
3676               </listitem>
3677             </itemizedlist></para>
3678         </listitem>
3679
3680         <listitem>
3681           <para>You can choose not to create an <emphasis role="bold">afsd</emphasis> options file and to set the
3682           <computeroutput>OPTIONS</computeroutput> variable in the initialization script to a null value rather than to the default
3683           <computeroutput>$MEDIUM</computeroutput> value. You can then either set arguments directly on the <emphasis
3684           role="bold">afsd</emphasis> command line in the script, or set no arguments (and so accept default values for all Cache
3685           Manager parameters).</para>
3686         </listitem>
3687       </itemizedlist>
3688
3689       <note>
3690       <para>If you are running on a Fedora or RHEL based system, the
3691       openafs-client initialization script behaves differently from that
3692       described above. It sources /etc/sysconfig/openafs, in which the
3693       AFSD_ARGS variable may be set to contain any, or all, of the afsd options
3694       detailed. Note that this script does not support setting an OPTIONS
3695       variable, or the SMALL, MEDIUM and LARGE methods of defining cache size
3696       </para>
3697       </note>
3698
3699  <orderedlist>
3700         <listitem>
3701           <para>Create the local directory on which to mount the AFS filespace, by convention <emphasis role="bold">/afs</emphasis>.
3702           If the directory already exists, verify that it is empty. <programlisting>
3703    # <emphasis role="bold">mkdir /afs</emphasis>
3704 </programlisting></para>
3705         </listitem>
3706
3707         <listitem>
3708           <para>On AIX systems, add the following line to the <emphasis role="bold">/etc/vfs</emphasis> file. It enables AIX to
3709           unmount AFS correctly during shutdown. <programlisting>
3710    afs     4     none     none
3711 </programlisting></para>
3712         </listitem>
3713
3714         <listitem>
3715           <para>On non-package based Linux systems, copy the <emphasis role="bold">afsd</emphasis> options file from the <emphasis
3716           role="bold">/usr/vice/etc</emphasis> directory to the <emphasis role="bold">/etc/sysconfig</emphasis> directory, removing
3717           the <emphasis role="bold">.conf</emphasis> extension as you do so. <programlisting>
3718    # <emphasis role="bold">cp /usr/vice/etc/afs.conf /etc/sysconfig/afs</emphasis>
3719 </programlisting></para>
3720         </listitem>
3721
3722         <listitem>
3723           <para>Edit the machine's AFS initialization script or <emphasis role="bold">afsd</emphasis> options file to set
3724           appropriate values for <emphasis role="bold">afsd</emphasis> command parameters. The script resides in the indicated
3725           location on each system type: <itemizedlist>
3726               <listitem>
3727                 <para>On AIX systems, <emphasis role="bold">/etc/rc.afs</emphasis></para>
3728               </listitem>
3729
3730               <listitem>
3731                 <para>On HP-UX systems, <emphasis role="bold">/sbin/init.d/afs</emphasis></para>
3732               </listitem>
3733
3734               <listitem>
3735                 <para>On IRIX systems, <emphasis role="bold">/etc/init.d/afs</emphasis></para>
3736               </listitem>
3737
3738                   <listitem>
3739                 <para>On Fedora and RHEL systems, <emphasis role="bold">/etc/sysconfg/openafs</emphasis></para>
3740               </listitem>
3741
3742               <listitem>
3743                 <para>On non-package based Linux systems, <emphasis role="bold">/etc/sysconfig/afs</emphasis> (the <emphasis
3744                 role="bold">afsd</emphasis> options file)</para>
3745               </listitem>
3746
3747               <listitem>
3748                 <para>On Solaris systems, <emphasis role="bold">/etc/init.d/afs</emphasis></para>
3749               </listitem>
3750             </itemizedlist></para>
3751
3752           <para>Use one of the methods described in the introduction to this section to add the following flags to the <emphasis
3753           role="bold">afsd</emphasis> command line. If you intend for the machine to remain an AFS client, also set any
3754           performance-related arguments you wish. <itemizedlist>
3755               <listitem>
3756                 <para>Add the <emphasis role="bold">-memcache</emphasis> flag if the machine is to use a memory cache.</para>
3757               </listitem>
3758
3759               <listitem>
3760                 <para>Add the <emphasis role="bold">-verbose</emphasis> flag to display a trace of the Cache Manager's
3761                 initialization on the standard output stream.</para>
3762               </listitem>
3763             </itemizedlist></para>
3764         </listitem>
3765       </orderedlist>
3766       <note><para>In order to successfully complete the instructions in the
3767       remainder of this guide, it is important that the machine does not have
3768       a synthetic root (as discussed in <link linkend="HDRWQ91">Enabling Access
3769       to Foreign Cells</link>). As some distributions ship with this enabled, it
3770       may be necessary to remove any occurences of the
3771       <emphasis role="bold">-dynroot</emphasis> and
3772       <emphasis role="bold">-afsdb</emphasis> options from both the AFS
3773       initialisation script and options file. If this functionality is
3774       required it may be renabled as detailed in
3775       <link linkend="HDRWQ91">Enabling Access to Foreign Cells</link>.
3776       </para></note>
3777       </para>
3778
3779     <indexterm>
3780       <primary>overview</primary>
3781
3782       <secondary>completing installation of first machine</secondary>
3783     </indexterm>
3784
3785     <indexterm>
3786       <primary>first AFS machine</primary>
3787
3788       <secondary>completion of installation</secondary>
3789     </indexterm>
3790   </sect1>
3791
3792   <sect1 id="HDRWQ71">
3793     <title>Overview: Completing the Installation of the First AFS Machine</title>
3794
3795     <para>The machine is now configured as an AFS file server and client machine. In this final phase of the installation, you
3796     initialize the Cache Manager and then create the upper levels of your AFS filespace, among other procedures. The procedures are:
3797     <orderedlist>
3798         <listitem>
3799           <para>Verify that the initialization script works correctly, and incorporate it into the operating system's startup and
3800           shutdown sequence</para>
3801         </listitem>
3802
3803         <listitem>
3804           <para>Create and mount top-level volumes</para>
3805         </listitem>
3806
3807         <listitem>
3808           <para>Create and mount volumes to store system binaries in AFS</para>
3809         </listitem>
3810
3811         <listitem>
3812           <para>Enable access to foreign cells</para>
3813         </listitem>
3814
3815         <listitem>
3816           <para>Institute additional security measures</para>
3817         </listitem>
3818
3819         <listitem>
3820           <para>Remove client functionality if desired</para>
3821         </listitem>
3822       </orderedlist></para>
3823
3824     <indexterm>
3825       <primary>AFS initialization script</primary>
3826
3827       <secondary>verifying on first AFS machine</secondary>
3828     </indexterm>
3829
3830     <indexterm>
3831       <primary>AFS initialization script</primary>
3832
3833       <secondary>running</secondary>
3834
3835       <tertiary>first AFS machine</tertiary>
3836     </indexterm>
3837
3838     <indexterm>
3839       <primary>first AFS machine</primary>
3840
3841       <secondary>AFS initialization script</secondary>
3842
3843       <tertiary>running/verifying</tertiary>
3844     </indexterm>
3845
3846     <indexterm>
3847       <primary>running AFS init. script</primary>
3848
3849       <secondary>first AFS machine</secondary>
3850     </indexterm>
3851
3852     <indexterm>
3853       <primary>invoking AFS init. script</primary>
3854
3855       <see>running</see>
3856     </indexterm>
3857   </sect1>
3858
3859   <sect1 id="HDRWQ72">
3860     <title>Verifying the AFS Initialization Script</title>
3861
3862     <para>At this point you run the AFS initialization script to verify that it correctly invokes all of the necessary programs and
3863     AFS processes, and that they start correctly. The following are the relevant commands: <itemizedlist>
3864         <listitem>
3865           <para>The command that dynamically loads AFS modifications into the kernel, on some system types (not applicable if the
3866           kernel has AFS modifications built in)</para>
3867         </listitem>
3868
3869         <listitem>
3870           <para>The <emphasis role="bold">bosserver</emphasis> command, which starts the BOS Server; it in turn starts the server
3871           processes for which you created entries in the <emphasis role="bold">/usr/afs/local/BosConfig</emphasis> file</para>
3872         </listitem>
3873
3874         <listitem>
3875           <para>The <emphasis role="bold">afsd</emphasis> command, which initializes the Cache Manager</para>
3876         </listitem>
3877       </itemizedlist></para>
3878
3879     <para>On system types that use a dynamic loader program, you must reboot the machine before running the initialization script,
3880     so that it can freshly load AFS modifications into the kernel.</para>
3881
3882     <para>If there are problems during the initialization, attempt to resolve them. The OpenAFS mailing lists can provide assistance if necessary.
3883
3884      <orderedlist>
3885         <indexterm>
3886           <primary>commands</primary>
3887
3888           <secondary>bos shutdown</secondary>
3889         </indexterm>
3890
3891         <indexterm>
3892           <primary>bos commands</primary>
3893
3894           <secondary>shutdown</secondary>
3895         </indexterm>
3896
3897         <listitem>
3898           <para>Issue the <emphasis role="bold">bos shutdown</emphasis> command to shut down the AFS server processes other than the
3899           BOS Server. Include the <emphasis role="bold">-wait</emphasis> flag to delay return of the command shell prompt until all
3900           processes shut down completely. <programlisting>
3901    # <emphasis role="bold">/usr/afs/bin/bos shutdown</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis
3902                 role="bold">-wait</emphasis>
3903 </programlisting></para>
3904         </listitem>
3905
3906         <listitem>
3907           <para>Issue the <emphasis role="bold">ps</emphasis> command to learn the <emphasis role="bold">bosserver</emphasis>
3908           process's process ID number (PID), and then the <emphasis role="bold">kill</emphasis> command to stop it. <programlisting>
3909    # <emphasis role="bold">ps</emphasis> <replaceable>appropriate_ps_options</replaceable> <emphasis role="bold">| grep bosserver</emphasis>
3910    # <emphasis role="bold">kill</emphasis> <replaceable>bosserver_PID</replaceable>
3911 </programlisting></para>
3912         </listitem>
3913
3914         <listitem>
3915           <para>Issue the appropriate commands to run the AFS initialization script for this system type.</para>
3916
3917           <indexterm>
3918             <primary>AIX</primary>
3919
3920             <secondary>AFS initialization script</secondary>
3921
3922             <tertiary>on first AFS machine</tertiary>
3923           </indexterm>
3924
3925           <para><emphasis role="bold">On AIX systems:</emphasis> <orderedlist>
3926               <listitem>
3927                 <para>Reboot the machine and log in again as the local superuser <emphasis role="bold">root</emphasis>.
3928                 <programlisting>
3929    # <emphasis role="bold">cd /</emphasis>
3930    # <emphasis role="bold">shutdown -r now</emphasis>
3931    login: <emphasis role="bold">root</emphasis>
3932    Password: <replaceable>root_password</replaceable>
3933 </programlisting></para>
3934               </listitem>
3935
3936               <listitem>
3937                 <para>Run the AFS initialization script. <programlisting>
3938    # <emphasis role="bold">/etc/rc.afs</emphasis>
3939 </programlisting></para>
3940               </listitem>
3941             </orderedlist></para>
3942
3943           <indexterm>
3944             <primary>HP-UX</primary>
3945
3946             <secondary>AFS initialization script</secondary>
3947
3948             <tertiary>on first AFS machine</tertiary>
3949           </indexterm>
3950
3951           <para><emphasis role="bold">On HP-UX systems:</emphasis> <orderedlist>
3952               <listitem>
3953                 <para>Run the AFS initialization script. <programlisting>
3954    # <emphasis role="bold">/sbin/init.d/afs  start</emphasis>
3955 </programlisting></para>
3956               </listitem>
3957             </orderedlist></para>
3958
3959           <indexterm>
3960             <primary>IRIX</primary>
3961
3962             <secondary>AFS initialization script</secondary>
3963
3964             <tertiary>on first AFS machine</tertiary>
3965           </indexterm>
3966
3967           <indexterm>
3968             <primary>afsclient variable (IRIX)</primary>
3969
3970             <secondary>first AFS machine</secondary>
3971           </indexterm>
3972
3973           <indexterm>
3974             <primary>variables</primary>
3975
3976             <secondary>afsclient (IRIX)</secondary>
3977
3978             <tertiary>first AFS machine</tertiary>
3979           </indexterm>
3980
3981           <indexterm>
3982             <primary>IRIX</primary>
3983
3984             <secondary>afsclient variable</secondary>
3985
3986             <tertiary>first AFS machine</tertiary>
3987           </indexterm>
3988
3989           <indexterm>
3990             <primary>afsserver variable (IRIX)</primary>
3991
3992             <secondary>first AFS machine</secondary>
3993           </indexterm>
3994
3995           <indexterm>
3996             <primary>variables</primary>
3997
3998             <secondary>afsserver (IRIX)</secondary>
3999
4000             <tertiary>first AFS machine</tertiary>
4001           </indexterm>
4002
4003           <indexterm>
4004             <primary>IRIX</primary>
4005
4006             <secondary>afsserver variable</secondary>
4007
4008             <tertiary>first AFS machine</tertiary>
4009           </indexterm>
4010
4011           <para><emphasis role="bold">On IRIX systems:</emphasis> <orderedlist>
4012               <listitem>
4013                 <para>If you have configured the machine to use the <emphasis role="bold">ml</emphasis> dynamic loader program,
4014                 reboot the machine and log in again as the local superuser <emphasis role="bold">root</emphasis>. <programlisting>
4015    # <emphasis role="bold">cd /</emphasis>
4016    # <emphasis role="bold">shutdown -i6 -g0 -y</emphasis>
4017    login: <emphasis role="bold">root</emphasis>
4018    Password: <replaceable>root_password</replaceable>
4019 </programlisting></para>
4020               </listitem>
4021
4022               <listitem>
4023                 <para>Issue the <emphasis role="bold">chkconfig</emphasis> command to activate the <emphasis
4024                 role="bold">afsserver</emphasis> and <emphasis role="bold">afsclient</emphasis> configuration variables.
4025                 <programlisting>
4026    # <emphasis role="bold">/etc/chkconfig -f afsserver on</emphasis>
4027    # <emphasis role="bold">/etc/chkconfig -f afsclient on</emphasis>
4028 </programlisting></para>
4029               </listitem>
4030
4031               <listitem>
4032                 <para>Run the AFS initialization script. <programlisting>
4033    # <emphasis role="bold">/etc/init.d/afs  start</emphasis>
4034 </programlisting></para>
4035               </listitem>
4036             </orderedlist></para>
4037
4038           <indexterm>
4039             <primary>Linux</primary>
4040
4041             <secondary>AFS initialization script</secondary>
4042
4043             <tertiary>on first AFS machine</tertiary>
4044           </indexterm>
4045
4046           <para><emphasis role="bold">On Linux systems:</emphasis> <orderedlist>
4047               <listitem>
4048                 <para>Reboot the machine and log in again as the local superuser <emphasis role="bold">root</emphasis>.
4049                 <programlisting>
4050    # <emphasis role="bold">cd /</emphasis>
4051    # <emphasis role="bold">shutdown -r now</emphasis>
4052    login: <emphasis role="bold">root</emphasis>
4053    Password: <replaceable>root_password</replaceable>
4054 </programlisting></para>
4055               </listitem>
4056
4057               <listitem>
4058                 <para>Run the AFS initialization scripts.
4059 <programlisting>
4060    # <emphasis role="bold">/etc/rc.d/init.d/openafs-client  start</emphasis>
4061    # <emphasis role="bold">/etc/rc.d/init.d/openafs-server  start</emphasis>
4062 </programlisting></para>
4063               </listitem>
4064             </orderedlist></para>
4065
4066           <indexterm>
4067             <primary>Solaris</primary>
4068
4069             <secondary>AFS initialization script</secondary>
4070
4071             <tertiary>on first AFS machine</tertiary>
4072           </indexterm>
4073
4074           <para><emphasis role="bold">On Solaris systems:</emphasis> <orderedlist>
4075               <listitem>
4076                 <para>Reboot the machine and log in again as the local superuser <emphasis role="bold">root</emphasis>.
4077                 <programlisting>
4078    # <emphasis role="bold">cd /</emphasis>
4079    # <emphasis role="bold">shutdown -i6 -g0 -y</emphasis>
4080    login: <emphasis role="bold">root</emphasis>
4081    Password: <replaceable>root_password</replaceable>
4082 </programlisting></para>
4083               </listitem>
4084
4085               <listitem>
4086                 <para>Run the AFS initialization script. <programlisting>
4087    # <emphasis role="bold">/etc/init.d/afs  start</emphasis>
4088 </programlisting></para>
4089               </listitem>
4090             </orderedlist></para>
4091         </listitem>
4092
4093         <listitem>
4094           <para>Wait for the message that confirms that Cache Manager initialization is complete.</para>
4095
4096           <para>On machines that use a disk cache, it can take a while to initialize the Cache Manager for the first time, because
4097           the <emphasis role="bold">afsd</emphasis> program must create all of the <emphasis
4098           role="bold">V</emphasis><replaceable>n</replaceable> files in the cache directory. Subsequent Cache Manager
4099           initializations do not take nearly as long, because the <emphasis role="bold">V</emphasis><replaceable>n</replaceable>
4100           files already exist.</para>
4101         </listitem>
4102         <listitem>
4103
4104           <indexterm>
4105             <primary>commands</primary>
4106             <secondary>aklog</secondary>
4107           </indexterm>
4108
4109           <indexterm>
4110             <primary>aklog command</primary>
4111           </indexterm>
4112
4113           <para>If you are working with an existing cell which uses
4114           <emphasis role="bold">kaserver</emphasis> for authentication,
4115           please recall the note in
4116           <link linkend="KAS003">Using this Appendix</link> detailing the
4117           substitution of <emphasis role="bold">kinit</emphasis> and
4118           <emphasis role="bold">aklog</emphasis> with
4119           <emphasis role="bold">klog</emphasis>.</para>
4120
4121           <para>As a basic test of correct AFS functioning, issue the
4122           <emphasis role="bold">kinit</emphasis> and
4123           <emphasis role="bold">aklog</emphasis> commands to authenticate
4124           as the <emphasis role="bold">admin</emphasis> user.
4125           Provide the password (<replaceable>admin_passwd</replaceable>) you
4126           defined in <link linkend="HDRWQ53">Initializing Cell Security</link>.</para>
4127
4128           <programlisting>
4129    # <emphasis role="bold">kinit admin</emphasis>
4130    Password:  <replaceable>admin_passwd</replaceable>
4131    # <emphasis role="bold">aklog</emphasis>
4132 </programlisting>
4133
4134           <indexterm>
4135             <primary>commands</primary>
4136
4137             <secondary>tokens</secondary>
4138           </indexterm>
4139
4140           <indexterm>
4141             <primary>tokens command</primary>
4142           </indexterm>
4143         </listitem>
4144
4145         <listitem>
4146           <para>Issue the <emphasis role="bold">tokens</emphasis> command to
4147           verify that the <emphasis role="bold">aklog</emphasis>
4148           command worked correctly. If it did, the output looks similar to the following example for the <emphasis
4149           role="bold">example.com</emphasis> cell, where <emphasis role="bold">admin</emphasis>'s AFS UID is 1. If the output does not
4150           seem correct, resolve the problem. Changes to the AFS initialization script are possibly necessary. The OpenAFS mailing lists can provide assistance as necessary. <programlisting>
4151    # <emphasis role="bold">tokens</emphasis>
4152    Tokens held by the Cache Manager:
4153    User's (AFS ID 1) tokens for afs@example.com [Expires May 22 11:52]
4154        --End of list--
4155 </programlisting></para>
4156         </listitem>
4157
4158         <listitem>
4159           <para>Issue the <emphasis role="bold">bos status</emphasis> command to verify that the output for each process reads
4160           <computeroutput>Currently running normally</computeroutput>. <programlisting>
4161    # <emphasis role="bold">/usr/afs/bin/bos status</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
4162 </programlisting> <indexterm>
4163               <primary>fs commands</primary>
4164
4165               <secondary>checkvolumes</secondary>
4166             </indexterm> <indexterm>
4167               <primary>commands</primary>
4168
4169               <secondary>fs checkvolumes</secondary>
4170             </indexterm></para>
4171         </listitem>
4172
4173         <listitem>
4174           <para>Change directory to the local file system root (<emphasis role="bold">/</emphasis>) and issue the <emphasis
4175           role="bold">fs checkvolumes</emphasis> command. <programlisting>
4176    # <emphasis role="bold">cd /</emphasis>
4177    # <emphasis role="bold">/usr/afs/bin/fs checkvolumes</emphasis>
4178 </programlisting></para>
4179         </listitem>
4180       </orderedlist></para>
4181
4182     <indexterm>
4183       <primary>AFS initialization script</primary>
4184
4185       <secondary>adding to machine startup sequence</secondary>
4186
4187       <tertiary>first AFS machine</tertiary>
4188     </indexterm>
4189
4190     <indexterm>
4191       <primary>installing</primary>
4192
4193       <secondary>AFS initialization script</secondary>
4194
4195       <tertiary>first AFS machine</tertiary>
4196     </indexterm>
4197
4198     <indexterm>
4199       <primary>first AFS machine</primary>
4200
4201       <secondary>AFS initialization script</secondary>
4202
4203       <tertiary>activating</tertiary>
4204     </indexterm>
4205
4206     <indexterm>
4207       <primary>activating AFS init. script</primary>
4208
4209       <see>installing</see>
4210     </indexterm>
4211   </sect1>
4212
4213   <sect1 id="HDRWQ73">
4214     <title>Activating the AFS Initialization Script</title>
4215
4216     <para>Now that you have confirmed that the AFS initialization script works correctly, take the action necessary to have it run
4217     automatically at each reboot. Proceed to the instructions for your system type: <itemizedlist>
4218         <listitem>
4219           <para><link linkend="HDRWQ74">Activating the Script on AIX Systems</link></para>
4220         </listitem>
4221
4222         <listitem>
4223           <para><link linkend="HDRWQ76">Activating the Script on HP-UX Systems</link></para>
4224         </listitem>
4225
4226         <listitem>
4227           <para><link linkend="HDRWQ77">Activating the Script on IRIX Systems</link></para>
4228         </listitem>
4229
4230         <listitem>
4231           <para><link linkend="HDRWQ78">Activating the Script on Linux Systems</link></para>
4232         </listitem>
4233
4234         <listitem>
4235           <para><link linkend="HDRWQ79">Activating the Script on Solaris Systems</link></para>
4236         </listitem>
4237       </itemizedlist></para>
4238
4239     <indexterm>
4240       <primary>AIX</primary>
4241
4242       <secondary>AFS initialization script</secondary>
4243
4244       <tertiary>on first AFS machine</tertiary>
4245     </indexterm>
4246
4247     <sect2 id="HDRWQ74">
4248       <title>Activating the Script on AIX Systems</title>
4249
4250       <orderedlist>
4251         <listitem>
4252           <para>Edit the AIX initialization file, <emphasis role="bold">/etc/inittab</emphasis>, adding the following line to invoke
4253           the AFS initialization script. Place it just after the line that starts NFS daemons. <programlisting>
4254    rcafs:2:wait:/etc/rc.afs &gt; /dev/console 2&gt;&amp;1 # Start AFS services
4255 </programlisting></para>
4256         </listitem>
4257
4258         <listitem>
4259           <para><emphasis role="bold">(Optional)</emphasis> There are now copies of the AFS initialization file in both the
4260           <emphasis role="bold">/usr/vice/etc</emphasis> and <emphasis role="bold">/etc</emphasis> directories. If you want to avoid
4261           potential confusion by guaranteeing that they are always the same, create a link between them. You can always retrieve the
4262           original script from the AFS CD-ROM if necessary. <programlisting>
4263    # <emphasis role="bold">cd  /usr/vice/etc</emphasis>
4264    # <emphasis role="bold">rm  rc.afs</emphasis>
4265    # <emphasis role="bold">ln -s  /etc/rc.afs</emphasis>
4266 </programlisting></para>
4267         </listitem>
4268
4269         <listitem>
4270           <para>Proceed to <link linkend="HDRWQ80">Configuring the Top Levels of the AFS Filespace</link>.</para>
4271         </listitem>
4272       </orderedlist>
4273
4274       <indexterm>
4275         <primary>HP-UX</primary>
4276
4277         <secondary>AFS initialization script</secondary>
4278
4279         <tertiary>on first AFS machine</tertiary>
4280       </indexterm>
4281     </sect2>
4282
4283     <sect2 id="HDRWQ76">
4284       <title>Activating the Script on HP-UX Systems</title>
4285
4286       <orderedlist>
4287         <listitem>
4288           <para>Change to the <emphasis role="bold">/sbin/init.d</emphasis> directory and issue the <emphasis role="bold">ln
4289           -s</emphasis> command to create symbolic links that incorporate the AFS initialization script into the HP-UX startup and
4290           shutdown sequence. <programlisting>
4291    # <emphasis role="bold">cd /sbin/init.d</emphasis>
4292    # <emphasis role="bold">ln -s ../init.d/afs /sbin/rc2.d/S460afs</emphasis>
4293    # <emphasis role="bold">ln -s ../init.d/afs /sbin/rc2.d/K800afs</emphasis>
4294 </programlisting></para>
4295         </listitem>
4296
4297         <listitem>
4298           <para><emphasis role="bold">(Optional)</emphasis> There are now copies of the AFS initialization file in both the
4299           <emphasis role="bold">/usr/vice/etc</emphasis> and <emphasis role="bold">/sbin/init.d</emphasis> directories. If you want
4300           to avoid potential confusion by guaranteeing that they are always the same, create a link between them. You can always
4301           retrieve the original script from the AFS CD-ROM if necessary. <programlisting>
4302    # <emphasis role="bold">cd /usr/vice/etc</emphasis>
4303    # <emphasis role="bold">rm afs.rc</emphasis>
4304    # <emphasis role="bold">ln -s  /sbin/init.d/afs  afs.rc</emphasis>
4305 </programlisting></para>
4306         </listitem>
4307
4308         <listitem>
4309           <para>Proceed to <link linkend="HDRWQ80">Configuring the Top Levels of the AFS Filespace</link>.</para>
4310         </listitem>
4311       </orderedlist>
4312
4313       <indexterm>
4314         <primary>IRIX</primary>
4315
4316         <secondary>AFS initialization script</secondary>
4317
4318         <tertiary>on first AFS machine</tertiary>
4319       </indexterm>
4320     </sect2>
4321
4322     <sect2 id="HDRWQ77">
4323       <title>Activating the Script on IRIX Systems</title>
4324
4325       <orderedlist>
4326         <listitem>
4327           <para>Change to the <emphasis role="bold">/etc/init.d</emphasis> directory and issue the <emphasis role="bold">ln
4328           -s</emphasis> command to create symbolic links that incorporate the AFS initialization script into the IRIX startup and
4329           shutdown sequence. <programlisting>
4330    # <emphasis role="bold">cd /etc/init.d</emphasis>
4331    # <emphasis role="bold">ln -s ../init.d/afs /etc/rc2.d/S35afs</emphasis>
4332    # <emphasis role="bold">ln -s ../init.d/afs /etc/rc0.d/K35afs</emphasis>
4333 </programlisting></para>
4334         </listitem>
4335
4336         <listitem>
4337           <para><emphasis role="bold">(Optional)</emphasis> There are now copies of the AFS initialization file in both the
4338           <emphasis role="bold">/usr/vice/etc</emphasis> and <emphasis role="bold">/etc/init.d</emphasis> directories. If you want
4339           to avoid potential confusion by guaranteeing that they are always the same, create a link between them. You can always
4340           retrieve the original script from the AFS CD-ROM if necessary. <programlisting>
4341    # <emphasis role="bold">cd /usr/vice/etc</emphasis>
4342    # <emphasis role="bold">rm afs.rc</emphasis>
4343    # <emphasis role="bold">ln -s  /etc/init.d/afs  afs.rc</emphasis>
4344 </programlisting></para>
4345         </listitem>
4346
4347         <listitem>
4348           <para>Proceed to <link linkend="HDRWQ80">Configuring the Top Levels of the AFS Filespace</link>.</para>
4349         </listitem>
4350       </orderedlist>
4351
4352       <indexterm>
4353         <primary>Linux</primary>
4354
4355         <secondary>AFS initialization script</secondary>
4356
4357         <tertiary>on first AFS machine</tertiary>
4358       </indexterm>
4359     </sect2>
4360
4361     <sect2 id="HDRWQ78">
4362       <title>Activating the Script on Linux Systems</title>
4363
4364       <orderedlist>
4365         <listitem>
4366           <para>Issue the <emphasis role="bold">chkconfig</emphasis> command to activate the <emphasis role="bold">openafs-client</emphasis> and <emphasis role="bold">openafs-server</emphasis>
4367           configuration variables. Based on the instruction in the AFS initialization file that begins with the string
4368           <computeroutput>#chkconfig</computeroutput>, the command automatically creates the symbolic links that incorporate the
4369           script into the Linux startup and shutdown sequence. <programlisting>
4370    # <emphasis role="bold">/sbin/chkconfig  --add openafs-client</emphasis>
4371    # <emphasis role="bold">/sbin/chkconfig  --add openafs-server</emphasis>
4372 </programlisting></para>
4373         </listitem>
4374
4375         <listitem>
4376           <para><emphasis role="bold">(Optional)</emphasis> There are now copies of the AFS initialization file in both the
4377           <emphasis role="bold">/usr/vice/etc</emphasis> and <emphasis role="bold">/etc/rc.d/init.d</emphasis> directories, and
4378           copies of the <emphasis role="bold">afsd</emphasis> options file in both the <emphasis
4379           role="bold">/usr/vice/etc</emphasis> and <emphasis role="bold">/etc/sysconfig</emphasis> directories. If you want to avoid
4380           potential confusion by guaranteeing that the two copies of each file are always the same, create a link between them. You
4381           can always retrieve the original script or options file from the AFS CD-ROM if necessary. <programlisting>
4382    # <emphasis role="bold">cd /usr/vice/etc</emphasis>
4383    # <emphasis role="bold">rm afs.rc afs.conf</emphasis>
4384    # <emphasis role="bold">ln -s  /etc/rc.d/init.d/afs  afs.rc</emphasis>
4385    # <emphasis role="bold">ln -s  /etc/sysconfig/afs  afs.conf</emphasis>
4386 </programlisting></para>
4387         </listitem>
4388
4389         <listitem>
4390           <para>Proceed to <link linkend="HDRWQ80">Configuring the Top Levels of the AFS Filespace</link>.</para>
4391         </listitem>
4392       </orderedlist>
4393
4394       <indexterm>
4395         <primary>Solaris</primary>
4396
4397         <secondary>AFS initialization script</secondary>
4398
4399         <tertiary>on first AFS machine</tertiary>
4400       </indexterm>
4401     </sect2>
4402
4403     <sect2 id="HDRWQ79">
4404       <title>Activating the Script on Solaris Systems</title>
4405
4406       <orderedlist>
4407         <listitem>
4408           <para>Change to the <emphasis role="bold">/etc/init.d</emphasis> directory and issue the <emphasis role="bold">ln
4409           -s</emphasis> command to create symbolic links that incorporate the AFS initialization script into the Solaris startup and
4410           shutdown sequence. <programlisting>
4411    # <emphasis role="bold">cd /etc/init.d</emphasis>
4412    # <emphasis role="bold">ln -s ../init.d/afs /etc/rc3.d/S99afs</emphasis>
4413    # <emphasis role="bold">ln -s ../init.d/afs /etc/rc0.d/K66afs</emphasis>
4414 </programlisting></para>
4415         </listitem>
4416
4417         <listitem>
4418           <para><emphasis role="bold">(Optional)</emphasis> There are now copies of the AFS initialization file in both the
4419           <emphasis role="bold">/usr/vice/etc</emphasis> and <emphasis role="bold">/etc/init.d</emphasis> directories. If you want
4420           to avoid potential confusion by guaranteeing that they are always the same, create a link between them. You can always
4421           retrieve the original script from the AFS CD-ROM if necessary. <programlisting>
4422    # <emphasis role="bold">cd /usr/vice/etc</emphasis>
4423    # <emphasis role="bold">rm afs.rc</emphasis>
4424    # <emphasis role="bold">ln -s  /etc/init.d/afs  afs.rc</emphasis>
4425 </programlisting></para>
4426         </listitem>
4427       </orderedlist>
4428
4429       <indexterm>
4430         <primary>AFS filespace</primary>
4431
4432         <secondary>configuring top levels</secondary>
4433       </indexterm>
4434
4435       <indexterm>
4436         <primary>configuring</primary>
4437
4438         <secondary>AFS filespace (top levels)</secondary>
4439       </indexterm>
4440     </sect2>
4441   </sect1>
4442
4443   <sect1 id="HDRWQ80">
4444     <title>Configuring the Top Levels of the AFS Filespace</title>
4445
4446     <para>If you have not previously run AFS in your cell, you now configure the top levels of your cell's AFS filespace. If you
4447     have run a previous version of AFS, the filespace is already configured. Proceed to <link linkend="HDRWQ83">Storing AFS Binaries
4448     in AFS</link>. <indexterm>
4449         <primary>root.cell volume</primary>
4450
4451         <secondary>creating and replicating</secondary>
4452       </indexterm> <indexterm>
4453         <primary>volume</primary>
4454
4455         <secondary>creating</secondary>
4456
4457         <tertiary>root.cell</tertiary>
4458       </indexterm> <indexterm>
4459         <primary>creating</primary>
4460
4461         <secondary>root.cell volume</secondary>
4462       </indexterm></para>
4463
4464     <para>You created the <emphasis role="bold">root.afs</emphasis> volume in <link linkend="HDRWQ60">Starting the File Server,
4465     Volume Server, and Salvager</link>, and the Cache Manager mounted it automatically on the local <emphasis
4466     role="bold">/afs</emphasis> directory when you ran the AFS initialization script in <link linkend="HDRWQ72">Verifying the AFS
4467     Initialization Script</link>. You now set the access control list (ACL) on the <emphasis role="bold">/afs</emphasis> directory;
4468     creating, mounting, and setting the ACL are the three steps required when creating any volume.</para>
4469
4470     <para>After setting the ACL on the <emphasis role="bold">root.afs</emphasis> volume, you create your cell's <emphasis
4471     role="bold">root.cell</emphasis> volume, mount it as a subdirectory of the <emphasis role="bold">/afs</emphasis> directory, and
4472     set the ACL. Create both a read/write and a regular mount point for the <emphasis role="bold">root.cell</emphasis> volume. The
4473     read/write mount point enables you to access the read/write version of replicated volumes when necessary. Creating both mount
4474     points essentially creates separate read-only and read-write copies of your filespace, and enables the Cache Manager to traverse
4475     the filespace on a read-only path or read/write path as appropriate. For further discussion of these concepts, see the chapter
4476     in the <emphasis>OpenAFS Administration Guide</emphasis> about administering volumes. <indexterm>
4477         <primary>root.afs volume</primary>
4478
4479         <secondary>replicating</secondary>
4480       </indexterm> <indexterm>
4481         <primary>volume</primary>
4482
4483         <secondary>replicating root.afs and root.cell</secondary>
4484       </indexterm> <indexterm>
4485         <primary>replicating volumes</primary>
4486       </indexterm></para>
4487
4488     <para>Then replicate both the <emphasis role="bold">root.afs</emphasis> and <emphasis role="bold">root.cell</emphasis> volumes.
4489     This is required if you want to replicate any other volumes in your cell, because all volumes mounted above a replicated volume
4490     must themselves be replicated in order for the Cache Manager to access the replica.</para>
4491
4492     <para>When the <emphasis role="bold">root.afs</emphasis> volume is replicated, the Cache Manager is programmed to access its
4493     read-only version (<emphasis role="bold">root.afs.readonly</emphasis>) whenever possible. To make changes to the contents of the
4494     <emphasis role="bold">root.afs</emphasis> volume (when, for example, you mount another cell's <emphasis
4495     role="bold">root.cell</emphasis> volume at the second level in your filespace), you must mount the <emphasis
4496     role="bold">root.afs</emphasis> volume temporarily, make the changes, release the volume and remove the temporary mount point.
4497     For instructions, see <link linkend="HDRWQ91">Enabling Access to Foreign Cells</link>. <indexterm>
4498         <primary>fs commands</primary>
4499
4500         <secondary>setacl</secondary>
4501       </indexterm> <indexterm>
4502         <primary>commands</primary>
4503
4504         <secondary>fs setacl</secondary>
4505       </indexterm> <indexterm>
4506         <primary>access control list (ACL), setting</primary>
4507       </indexterm> <indexterm>
4508         <primary>setting</primary>
4509
4510         <secondary>ACL</secondary>
4511       </indexterm> <orderedlist>
4512         <listitem>
4513           <para>Issue the <emphasis role="bold">fs setacl</emphasis> command to edit the ACL on the <emphasis
4514           role="bold">/afs</emphasis> directory. Add an entry that grants the <emphasis role="bold">l</emphasis> (<emphasis
4515           role="bold">lookup</emphasis>) and <emphasis role="bold">r</emphasis> (<emphasis role="bold">read</emphasis>) permissions
4516           to the <emphasis role="bold">system:anyuser</emphasis> group, to enable all AFS users who can reach your cell to traverse
4517           through the directory. If you prefer to enable access only to locally authenticated users, substitute the <emphasis
4518           role="bold">system:authuser</emphasis> group.</para>
4519
4520           <para>Note that there is already an ACL entry that grants all seven access rights to the <emphasis
4521           role="bold">system:administrators</emphasis> group. It is a default entry that AFS places on every new volume's root
4522           directory.</para>
4523
4524           <para>The top-level AFS directory, typically /afs, is a special case:
4525             when the client is configured to run in dynroot mode (e.g.
4526             <emphasis role="bold">afsd -dynroot</emphasis>, attempts to set
4527             the ACL on this directory will return <emphasis role="bold">
4528               Connection timed out</emphasis>. This is because the dynamically-
4529             generated root directory is not a part of the global AFS space,
4530             and cannot have an access control list set on it.</para>
4531
4532           <programlisting>
4533    # <emphasis role="bold">/usr/afs/bin/fs setacl /afs system:anyuser rl</emphasis>
4534 </programlisting>
4535
4536           <indexterm>
4537             <primary>commands</primary>
4538
4539             <secondary>vos create</secondary>
4540
4541             <tertiary>root.cell volume</tertiary>
4542           </indexterm>
4543
4544           <indexterm>
4545             <primary>vos commands</primary>
4546
4547             <secondary>create</secondary>
4548
4549             <tertiary>root.cell volume</tertiary>
4550           </indexterm>
4551
4552           <indexterm>
4553             <primary>fs commands</primary>
4554
4555             <secondary>mkmount</secondary>
4556           </indexterm>
4557
4558           <indexterm>
4559             <primary>commands</primary>
4560
4561             <secondary>fs mkmount</secondary>
4562           </indexterm>
4563
4564           <indexterm>
4565             <primary>mount point</primary>
4566           </indexterm>
4567
4568           <indexterm>
4569             <primary>creating</primary>
4570
4571             <secondary>mount point</secondary>
4572           </indexterm>
4573
4574           <indexterm>
4575             <primary>volume</primary>
4576
4577             <secondary>mounting</secondary>
4578           </indexterm>
4579         </listitem>
4580
4581         <listitem id="LIWQ81">
4582           <para>Issue the <emphasis role="bold">vos create</emphasis> command to create the <emphasis
4583           role="bold">root.cell</emphasis> volume. Then issue the <emphasis role="bold">fs mkmount</emphasis> command to mount it as
4584           a subdirectory of the <emphasis role="bold">/afs</emphasis> directory, where it serves as the root of your cell's local
4585           AFS filespace. Finally, issue the <emphasis role="bold">fs setacl</emphasis> command to create an ACL entry for the
4586           <emphasis role="bold">system:anyuser</emphasis> group (or <emphasis role="bold">system:authuser</emphasis> group).</para>
4587
4588           <para>For the <replaceable>partition name</replaceable> argument, substitute the name of one of the machine's AFS server
4589           partitions (such as <emphasis role="bold">/vicepa</emphasis>). For the <replaceable>cellname</replaceable> argument,
4590           substitute your cell's fully-qualified Internet domain name (such as <emphasis role="bold">example.com</emphasis>).</para>
4591
4592           <programlisting>
4593    # <emphasis role="bold">/usr/afs/bin/vos create</emphasis>  &lt;<replaceable>machine name</replaceable>&gt; &lt;<replaceable>partition name</replaceable>&gt; <emphasis
4594               role="bold">root.cell</emphasis>
4595    # <emphasis role="bold">/usr/afs/bin/fs mkmount /afs/</emphasis><replaceable>cellname</replaceable>  <emphasis role="bold">root.cell</emphasis>
4596    # <emphasis role="bold">/usr/afs/bin/fs setacl /afs/</emphasis><replaceable>cellname</replaceable>  <emphasis role="bold">system:anyuser rl</emphasis>
4597 </programlisting>
4598
4599           <indexterm>
4600             <primary>creating</primary>
4601
4602             <secondary>symbolic link</secondary>
4603
4604             <tertiary>for abbreviated cell name</tertiary>
4605           </indexterm>
4606
4607           <indexterm>
4608             <primary>symbolic link</primary>
4609
4610             <secondary>for abbreviated cell name</secondary>
4611           </indexterm>
4612
4613           <indexterm>
4614             <primary>cell name</primary>
4615
4616             <secondary>symbolic link for abbreviated</secondary>
4617           </indexterm>
4618         </listitem>
4619
4620         <listitem>
4621           <para><emphasis role="bold">(Optional)</emphasis> Create a symbolic link to a shortened cell name, to reduce the length of
4622           pathnames for users in the local cell. For example, in the <emphasis role="bold">example.com</emphasis> cell, <emphasis
4623           role="bold">/afs/example</emphasis> is a link to <emphasis role="bold">/afs/example.com</emphasis>. <programlisting>
4624    # <emphasis role="bold">cd /afs</emphasis>
4625    # <emphasis role="bold">ln -s</emphasis>  <replaceable>full_cellname</replaceable>  <replaceable>short_cellname</replaceable>
4626 </programlisting> <indexterm>
4627               <primary>read/write mount point for root.afs volume</primary>
4628             </indexterm> <indexterm>
4629               <primary>root.afs volume</primary>
4630
4631               <secondary>read/write mount point</secondary>
4632             </indexterm> <indexterm>
4633               <primary>creating</primary>
4634
4635               <secondary>read/write mount point</secondary>
4636             </indexterm></para>
4637         </listitem>
4638
4639         <listitem>
4640           <para>Issue the <emphasis role="bold">fs mkmount</emphasis> command to create a read/write mount point for the <emphasis
4641           role="bold">root.cell</emphasis> volume (you created a regular mount point in Step <link
4642           linkend="LIWQ81">2</link>).</para>
4643
4644           <para>By convention, the name of a read/write mount point begins with a period, both to distinguish it from the regular
4645           mount point and to make it visible only when the <emphasis role="bold">-a</emphasis> flag is used on the <emphasis
4646           role="bold">ls</emphasis> command.</para>
4647
4648           <para>Change directory to <emphasis role="bold">/usr/afs/bin</emphasis> to make it easier to access the command
4649           binaries.</para>
4650
4651           <programlisting>
4652    # <emphasis role="bold">cd /usr/afs/bin</emphasis>
4653    # <emphasis role="bold">./fs mkmount   /afs/.</emphasis><replaceable>cellname</replaceable>   <emphasis role="bold">root.cell -rw</emphasis>
4654 </programlisting>
4655
4656           <indexterm>
4657             <primary>commands</primary>
4658
4659             <secondary>vos addsite</secondary>
4660           </indexterm>
4661
4662           <indexterm>
4663             <primary>vos commands</primary>
4664
4665             <secondary>addsite</secondary>
4666           </indexterm>
4667
4668           <indexterm>
4669             <primary>volume</primary>
4670
4671             <secondary>defining replication site</secondary>
4672           </indexterm>
4673
4674           <indexterm>
4675             <primary>defining</primary>
4676
4677             <secondary>replication site for volume</secondary>
4678           </indexterm>
4679         </listitem>
4680
4681         <listitem id="LIWQ82">
4682           <para>Issue the <emphasis role="bold">vos addsite</emphasis> command to define a replication site
4683           for both the <emphasis role="bold">root.afs</emphasis> and <emphasis role="bold">root.cell</emphasis> volumes. In each
4684           case, substitute for the <replaceable>partition name</replaceable> argument the partition where the volume's read/write
4685           version resides. When you install additional file server machines, it is a good idea to create replication sites on them
4686           as well. <programlisting>
4687    # <emphasis role="bold">./vos addsite</emphasis> &lt;<replaceable>machine name</replaceable>&gt; &lt;<replaceable>partition name</replaceable>&gt; <emphasis
4688                 role="bold">root.afs</emphasis>
4689    # <emphasis role="bold">./vos addsite</emphasis> &lt;<replaceable>machine name</replaceable>&gt; &lt;<replaceable>partition name</replaceable>&gt; <emphasis
4690                 role="bold">root.cell</emphasis>
4691 </programlisting> <indexterm>
4692               <primary>fs commands</primary>
4693
4694               <secondary>examine</secondary>
4695             </indexterm> <indexterm>
4696               <primary>commands</primary>
4697
4698               <secondary>fs examine</secondary>
4699             </indexterm></para>
4700         </listitem>
4701
4702         <listitem>
4703           <para>Issue the <emphasis role="bold">fs examine</emphasis> command to verify that the Cache Manager can access both the
4704           <emphasis role="bold">root.afs</emphasis> and <emphasis role="bold">root.cell</emphasis> volumes, before you attempt to
4705           replicate them. The output lists each volume's name, volumeID number, quota, size, and the size of the partition that
4706           houses them. If you get an error message instead, do not continue before taking corrective action. <programlisting>
4707    # <emphasis role="bold">./fs examine /afs</emphasis>
4708    # <emphasis role="bold">./fs examine /afs/</emphasis><replaceable>cellname</replaceable>
4709 </programlisting> <indexterm>
4710               <primary>commands</primary>
4711
4712               <secondary>vos release</secondary>
4713             </indexterm> <indexterm>
4714               <primary>vos commands</primary>
4715
4716               <secondary>release</secondary>
4717             </indexterm> <indexterm>
4718               <primary>volume</primary>
4719
4720               <secondary>releasing replicated</secondary>
4721             </indexterm> <indexterm>
4722               <primary>releasing replicated volume</primary>
4723             </indexterm></para>
4724         </listitem>
4725
4726         <listitem>
4727           <para>Issue the <emphasis role="bold">vos release</emphasis> command to release a replica of the <emphasis
4728           role="bold">root.afs</emphasis> and <emphasis role="bold">root.cell</emphasis> volumes to the sites you defined in Step
4729           <link linkend="LIWQ82">5</link>. <programlisting>
4730    # <emphasis role="bold">./vos release root.afs</emphasis>
4731    # <emphasis role="bold">./vos release root.cell</emphasis>
4732 </programlisting> <indexterm>
4733               <primary>fs commands</primary>
4734
4735               <secondary>checkvolumes</secondary>
4736             </indexterm> <indexterm>
4737               <primary>commands</primary>
4738
4739               <secondary>fs checkvolumes</secondary>
4740             </indexterm></para>
4741         </listitem>
4742
4743         <listitem>
4744           <para>Issue the <emphasis role="bold">fs checkvolumes</emphasis> to force the Cache Manager to notice that you have
4745           released read-only versions of the volumes, then issue the <emphasis role="bold">fs examine</emphasis> command again. This
4746           time its output mentions the read-only version of the volumes (<emphasis role="bold">root.afs.readonly</emphasis> and
4747           <emphasis role="bold">root.cell.readonly</emphasis>) instead of the read/write versions, because of the Cache Manager's
4748           bias to access the read-only version of the <emphasis role="bold">root.afs</emphasis> volume if it exists.
4749           <programlisting>
4750    # <emphasis role="bold">./fs checkvolumes</emphasis>
4751    # <emphasis role="bold">./fs examine /afs</emphasis>
4752    # <emphasis role="bold">./fs examine /afs/</emphasis><replaceable>cellname</replaceable>
4753 </programlisting></para>
4754         </listitem>
4755       </orderedlist></para>
4756
4757     <indexterm>
4758       <primary>storing</primary>
4759
4760       <secondary>AFS binaries in volumes</secondary>
4761     </indexterm>
4762
4763     <indexterm>
4764       <primary>creating</primary>
4765
4766       <secondary>volume</secondary>
4767
4768       <tertiary>for AFS binaries</tertiary>
4769     </indexterm>
4770
4771     <indexterm>
4772       <primary>volume</primary>
4773
4774       <secondary>for AFS binaries</secondary>
4775     </indexterm>
4776
4777     <indexterm>
4778       <primary>binaries</primary>
4779
4780       <secondary>storing AFS in volume</secondary>
4781     </indexterm>
4782
4783     <indexterm>
4784       <primary>usr/afsws directory</primary>
4785     </indexterm>
4786
4787     <indexterm>
4788       <primary>directories</primary>
4789
4790       <secondary>/usr/afsws</secondary>
4791     </indexterm>
4792   </sect1>
4793
4794   <sect1 id="HDRWQ83">
4795     <title>Storing AFS Binaries in AFS</title>
4796
4797     <note><para>Sites with existing binary distribution mechanisms, including
4798     those which use packaging systems such as RPM, may wish to skip this step,
4799     and use tools native to their operating system to manage AFS configuration
4800     information.</para></note>
4801
4802     <para>In the conventional configuration, you make AFS client binaries and configuration files available in the subdirectories of
4803     the <emphasis role="bold">/usr/afsws</emphasis> directory on client machines (<emphasis role="bold">afsws</emphasis> is an
4804     acronym for <emphasis role="bold">AFS w</emphasis><emphasis>ork</emphasis><emphasis
4805     role="bold">s</emphasis><emphasis>tation</emphasis>). You can conserve local disk space by creating <emphasis
4806     role="bold">/usr/afsws</emphasis> as a link to an AFS volume that houses the AFS client binaries and configuration files for
4807     this system type.</para>
4808
4809     <para>In this section you create the necessary volumes. The conventional location to which to link <emphasis
4810     role="bold">/usr/afsws</emphasis> is <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
4811     role="bold">/</emphasis><replaceable>sysname</replaceable><emphasis role="bold">/usr/afsws</emphasis>, where
4812     <replaceable>sysname</replaceable> is the appropriate system type name as specified in the <emphasis>OpenAFS Release
4813     Notes</emphasis>. The instructions in <link linkend="HDRWQ133">Installing Additional Client Machines</link> assume that you have
4814     followed the instructions in this section.</para>
4815
4816     <para>If you have previously run AFS in the cell, the volumes possibly already exist. If so, you need to perform Step <link
4817     linkend="LIWQ86">8</link> only.</para>
4818
4819     <para>The current working directory is still <emphasis role="bold">/usr/afs/bin</emphasis>, which houses the <emphasis
4820     role="bold">fs</emphasis> and <emphasis role="bold">vos</emphasis> command suite binaries. In the following commands, it is
4821     possible you still need to specify the pathname to the commands, depending on how your PATH environment variable is set.
4822     <orderedlist>
4823         <indexterm>
4824           <primary>commands</primary>
4825
4826           <secondary>vos create</secondary>
4827
4828           <tertiary>volume for AFS binaries</tertiary>
4829         </indexterm>
4830
4831         <indexterm>
4832           <primary>vos commands</primary>
4833
4834           <secondary>create</secondary>
4835
4836           <tertiary>volume for AFS binaries</tertiary>
4837         </indexterm>
4838
4839         <listitem id="LIWQ84">
4840           <para>Issue the <emphasis role="bold">vos create</emphasis> command to create volumes for storing
4841           the AFS client binaries for this system type. The following example instruction creates volumes called
4842           <replaceable>sysname</replaceable>, <replaceable>sysname</replaceable>.<emphasis role="bold">usr</emphasis>, and
4843           <replaceable>sysname</replaceable>.<emphasis role="bold">usr.afsws</emphasis>. Refer to the <emphasis>OpenAFS Release
4844           Notes</emphasis> to learn the proper value of <replaceable>sysname</replaceable> for this system type. <programlisting>
4845    # <emphasis role="bold">vos create</emphasis> &lt;<replaceable>machine name</replaceable>&gt; &lt;<replaceable>partition name</replaceable>&gt; <replaceable>sysname</replaceable>
4846    # <emphasis role="bold">vos create</emphasis> &lt;<replaceable>machine name</replaceable>&gt; &lt;<replaceable>partition name</replaceable>&gt; <replaceable>sysname</replaceable><emphasis
4847                 role="bold">.usr</emphasis>
4848    # <emphasis role="bold">vos create</emphasis> &lt;<replaceable>machine name</replaceable>&gt; &lt;<replaceable>partition name</replaceable>&gt; <replaceable>sysname</replaceable><emphasis
4849                 role="bold">.usr.afsws</emphasis>
4850 </programlisting></para>
4851         </listitem>
4852
4853         <listitem>
4854           <para>Issue the <emphasis role="bold">fs mkmount</emphasis> command to mount the newly created volumes. Because the
4855           <emphasis role="bold">root.cell</emphasis> volume is replicated, you must precede the <emphasis>cellname</emphasis> part
4856           of the pathname with a period to specify the read/write mount point, as shown. Then issue the <emphasis role="bold">vos
4857           release</emphasis> command to release a new replica of the <emphasis role="bold">root.cell</emphasis> volume, and the
4858           <emphasis role="bold">fs checkvolumes</emphasis> command to force the local Cache Manager to access them. <programlisting>
4859    # <emphasis role="bold">fs mkmount -dir /afs/.</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/</emphasis><replaceable>sysname</replaceable> <emphasis
4860                 role="bold">-vol</emphasis> <replaceable>sysname</replaceable>
4861    # <emphasis role="bold">fs mkmount -dir /afs/.</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/</emphasis><replaceable>sysname</replaceable><emphasis
4862                 role="bold">/usr</emphasis>  <emphasis role="bold">-vol</emphasis> <replaceable>sysname</replaceable><emphasis
4863                 role="bold">.usr</emphasis>
4864    # <emphasis role="bold">fs mkmount -dir /afs/.</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/</emphasis><replaceable>sysname</replaceable><emphasis
4865                 role="bold">/usr/afsws</emphasis> <emphasis role="bold">-vol</emphasis> <replaceable>sysname</replaceable><emphasis
4866                 role="bold">.usr.afsws</emphasis>
4867    # <emphasis role="bold">vos release root.cell</emphasis>
4868    # <emphasis role="bold">fs checkvolumes</emphasis>
4869 </programlisting></para>
4870         </listitem>
4871
4872         <listitem>
4873           <para>Issue the <emphasis role="bold">fs setacl</emphasis> command to grant the <emphasis role="bold">l</emphasis>
4874           (<emphasis role="bold">lookup</emphasis>) and <emphasis role="bold">r</emphasis> (<emphasis role="bold">read</emphasis>)
4875           permissions to the <emphasis role="bold">system:anyuser</emphasis> group on each new directory's ACL. <programlisting>
4876    # <emphasis role="bold">cd /afs/.</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/</emphasis><replaceable>sysname</replaceable>
4877    # <emphasis role="bold">fs setacl  -dir  .  usr  usr/afsws  -acl  system:anyuser rl</emphasis>
4878 </programlisting> <indexterm>
4879               <primary>commands</primary>
4880
4881               <secondary>fs setquota</secondary>
4882             </indexterm> <indexterm>
4883               <primary>fs commands</primary>
4884
4885               <secondary>setquota</secondary>
4886             </indexterm> <indexterm>
4887               <primary>quota for volume</primary>
4888             </indexterm> <indexterm>
4889               <primary>volume</primary>
4890
4891               <secondary>setting quota</secondary>
4892             </indexterm> <indexterm>
4893               <primary>setting</primary>
4894
4895               <secondary>volume quota</secondary>
4896             </indexterm></para>
4897         </listitem>
4898
4899         <listitem id="LIWQ85">
4900           <para>Issue the <emphasis role="bold">fs setquota</emphasis> command to set an unlimited quota on
4901           the volume mounted at the <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
4902           role="bold">/</emphasis><replaceable>sysname</replaceable><emphasis role="bold">/usr/afsws</emphasis> directory. This
4903           enables you to copy all of the appropriate files from the CD-ROM into the volume without exceeding the volume's
4904           quota.</para>
4905
4906           <para>If you wish, you can set the volume's quota to a finite value after you complete the copying operation. At that
4907           point, use the <emphasis role="bold">vos examine</emphasis> command to determine how much space the volume is occupying.
4908           Then issue the <emphasis role="bold">fs setquota</emphasis> command to set a quota that is slightly larger.</para>
4909
4910           <programlisting>
4911    # <emphasis role="bold">fs setquota /afs/.</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/</emphasis><replaceable>sysname</replaceable><emphasis
4912               role="bold">/usr/afsws  0</emphasis>
4913 </programlisting>
4914         </listitem>
4915
4916         <listitem>
4917           <para>Unpack the distribution tarball into the <emphasis role="bold">/tmp/afsdist</emphasis> directory,
4918           if it is not already. <indexterm>
4919               <primary>copying</primary>
4920
4921               <secondary>AFS binaries into volume</secondary>
4922             </indexterm> <indexterm>
4923               <primary>CD-ROM</primary>
4924
4925               <secondary>copying AFS binaries into volume</secondary>
4926             </indexterm> <indexterm>
4927               <primary>first AFS machine</primary>
4928
4929               <secondary>copying</secondary>
4930
4931               <tertiary>AFS binaries into volume</tertiary>
4932             </indexterm></para>
4933         </listitem>
4934
4935         <listitem>
4936           <para>Copy the contents of the indicated directories from the
4937           distribution into the <emphasis
4938           role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
4939           role="bold">/</emphasis><replaceable>sysname</replaceable><emphasis role="bold">/usr/afsws</emphasis> directory.
4940           <programlisting>
4941    # <emphasis role="bold">cd /afs/.</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/</emphasis><replaceable>sysname</replaceable><emphasis
4942                 role="bold">/usr/afsws</emphasis>
4943    # <emphasis role="bold">cp -rp /tmp/afsdist/</emphasis><replaceable>sysname</replaceable><emphasis role="bold">/bin  .</emphasis>
4944    # <emphasis role="bold">cp -rp /tmp/afsdist/</emphasis><replaceable>sysname</replaceable><emphasis role="bold">/etc  .</emphasis>
4945    # <emphasis role="bold">cp -rp /tmp/afsdist/</emphasis><replaceable>sysname</replaceable><emphasis role="bold">/include  .</emphasis>
4946    # <emphasis role="bold">cp -rp /tmp/afsdist/</emphasis><replaceable>sysname</replaceable><emphasis role="bold">/lib  .</emphasis>
4947 </programlisting>
4948 <indexterm>
4949               <primary>creating</primary>
4950
4951               <secondary>symbolic link</secondary>
4952
4953               <tertiary>to AFS binaries</tertiary>
4954             </indexterm> <indexterm>
4955               <primary>symbolic link</primary>
4956
4957               <secondary>to AFS binaries from local disk</secondary>
4958             </indexterm></para>
4959         </listitem>
4960
4961         <listitem id="LIWQ86">
4962           <para>Create <emphasis role="bold">/usr/afsws</emphasis> on the local disk as a symbolic link to the
4963           directory <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
4964           role="bold">/@sys/usr/afsws</emphasis>. You can specify the actual system name instead of <emphasis
4965           role="bold">@sys</emphasis> if you wish, but the advantage of using <emphasis role="bold">@sys</emphasis> is that it
4966           remains valid if you upgrade this machine to a different system type. <programlisting>
4967    # <emphasis role="bold">ln -s /afs/</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/@sys/usr/afsws  /usr/afsws</emphasis>
4968 </programlisting> <indexterm>
4969               <primary>PATH environment variable for users</primary>
4970             </indexterm> <indexterm>
4971               <primary>variables</primary>
4972
4973               <secondary>PATH, setting for users</secondary>
4974             </indexterm></para>
4975         </listitem>
4976
4977         <listitem>
4978           <para><emphasis role="bold">(Optional)</emphasis> To enable users to issue commands from the AFS suites (such as <emphasis
4979           role="bold">fs</emphasis>) without having to specify a pathname to their binaries, include the <emphasis
4980           role="bold">/usr/afsws/bin</emphasis> and <emphasis role="bold">/usr/afsws/etc</emphasis> directories in the PATH
4981           environment variable you define in each user's shell initialization file (such as <emphasis
4982           role="bold">.cshrc</emphasis>).</para>
4983         </listitem>
4984       </orderedlist></para>
4985
4986     <indexterm>
4987       <primary>storing</primary>
4988
4989       <secondary>AFS documentation in volumes</secondary>
4990     </indexterm>
4991
4992     <indexterm>
4993       <primary>creating</primary>
4994
4995       <secondary>volume</secondary>
4996
4997       <tertiary>for AFS documentation</tertiary>
4998     </indexterm>
4999
5000     <indexterm>
5001       <primary>volume</primary>
5002
5003       <secondary>for AFS documentation</secondary>
5004     </indexterm>
5005
5006     <indexterm>
5007       <primary>documentation, creating volume for AFS</primary>
5008     </indexterm>
5009
5010     <indexterm>
5011       <primary>usr/afsdoc directory</primary>
5012     </indexterm>
5013
5014     <indexterm>
5015       <primary>directories</primary>
5016
5017       <secondary>/usr/afsdoc</secondary>
5018     </indexterm>
5019   </sect1>
5020
5021   <sect1 id="HDRWQ87">
5022     <title>Storing AFS Documents in AFS</title>
5023
5024     <para>The AFS distribution includes the following documents: <itemizedlist>
5025         <listitem>
5026           <para><emphasis>OpenAFS Release Notes</emphasis></para>
5027         </listitem>
5028
5029         <listitem>
5030           <para><emphasis>OpenAFS Quick Beginnings</emphasis></para>
5031         </listitem>
5032
5033         <listitem>
5034           <para><emphasis>OpenAFS User Guide</emphasis></para>
5035         </listitem>
5036
5037         <listitem>
5038           <para><emphasis>OpenAFS Administration Reference</emphasis></para>
5039         </listitem>
5040
5041         <listitem>
5042           <para><emphasis>OpenAFS Administration Guide</emphasis></para>
5043         </listitem>
5044       </itemizedlist></para>
5045
5046     <note><para>OpenAFS Documentation is not currently provided with all
5047     distributions, but may be downloaded separately from the OpenAFS
5048     website</para></note>
5049
5050     <para>The OpenAFS Documentation Distribution has a directory for each
5051     document format provided. The different formats are suitable for online
5052     viewing, printing, or both.</para>
5053
5054     <para>This section explains how to create and mount a volume to house the documents, making them available to your users. The
5055     recommended mount point for the volume is <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
5056     role="bold">/afsdoc</emphasis>. If you wish, you can create a link to the mount point on each client machine's local disk,
5057     called <emphasis role="bold">/usr/afsdoc</emphasis>. Alternatively, you can create a link to the mount point in each user's home
5058     directory. You can also choose to permit users to access only certain documents (most probably, the <emphasis>OpenAFS User
5059     Guide</emphasis>) by creating different mount points or setting different ACLs on different document directories.</para>
5060
5061     <para>The current working directory is still <emphasis role="bold">/usr/afs/bin</emphasis>, which houses the <emphasis
5062     role="bold">fs</emphasis> and <emphasis role="bold">vos</emphasis> command suite binaries you use to create and mount volumes.
5063     In the following commands, it is possible you still need to specify the pathname to the commands, depending on how your PATH
5064     environment variable is set. <orderedlist>
5065         <indexterm>
5066           <primary>commands</primary>
5067
5068           <secondary>vos create</secondary>
5069
5070           <tertiary>volume for AFS documentation</tertiary>
5071         </indexterm>
5072
5073         <indexterm>
5074           <primary>vos commands</primary>
5075
5076           <secondary>create</secondary>
5077
5078           <tertiary>volume for AFS documentation</tertiary>
5079         </indexterm>
5080
5081         <listitem>
5082           <para>Issue the <emphasis role="bold">vos create</emphasis> command to create a volume for storing the AFS documentation.
5083           Include the <emphasis role="bold">-maxquota</emphasis> argument to set an unlimited quota on the volume. This enables you
5084           to copy all of the appropriate files from the CD-ROM into the volume without exceeding the volume's quota.</para>
5085
5086           <para>If you wish, you can set the volume's quota to a finite value after you complete the copying operations. At that
5087           point, use the <emphasis role="bold">vos examine</emphasis> command to determine how much space the volume is occupying.
5088           Then issue the <emphasis role="bold">fs setquota</emphasis> command to set a quota that is slightly larger.</para>
5089
5090           <programlisting>
5091    # <emphasis role="bold">vos create</emphasis>  &lt;<replaceable>machine name</replaceable>&gt; &lt;<replaceable>partition name</replaceable>&gt;  <emphasis
5092               role="bold">afsdoc  -maxquota  0</emphasis>
5093 </programlisting>
5094         </listitem>
5095
5096         <listitem>
5097           <para>Issue the <emphasis role="bold">fs mkmount</emphasis> command to mount the new volume. Because the <emphasis
5098           role="bold">root.cell</emphasis> volume is replicated, you must precede the <emphasis>cellname</emphasis> with a period to
5099           specify the read/write mount point, as shown. Then issue the <emphasis role="bold">vos release</emphasis> command to
5100           release a new replica of the <emphasis role="bold">root.cell</emphasis> volume, and the <emphasis role="bold">fs
5101           checkvolumes</emphasis> command to force the local Cache Manager to access them. <programlisting>
5102    # <emphasis role="bold">fs mkmount -dir /afs/.</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/afsdoc</emphasis> <emphasis
5103                 role="bold">-vol</emphasis> <emphasis role="bold">afsdoc</emphasis>
5104    # <emphasis role="bold">vos release root.cell</emphasis>
5105    # <emphasis role="bold">fs checkvolumes</emphasis>
5106 </programlisting></para>
5107         </listitem>
5108
5109         <listitem>
5110           <para>Issue the <emphasis role="bold">fs setacl</emphasis> command to grant the <emphasis role="bold">rl</emphasis>
5111           permissions to the <emphasis role="bold">system:anyuser</emphasis> group on the new directory's ACL. <programlisting>
5112    # <emphasis role="bold">cd /afs/.</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/afsdoc</emphasis>
5113    # <emphasis role="bold">fs setacl  .  system:anyuser rl</emphasis>
5114 </programlisting></para>
5115         </listitem>
5116
5117         <listitem>
5118           <para>Unpack the OpenAFS documentation distribution into the
5119           <emphasis role="bold">/tmp/afsdocs</emphasis> directory. You may use
5120           a different directory, in which case the location you use should be
5121           subsituted in the following examples. For instructions on unpacking
5122           the distribution, consult the documentation for your operating
5123           system's <emphasis role="bold">tar</emphasis> command.
5124           <indexterm>
5125               <primary>copying</primary>
5126
5127               <secondary>AFS documentation from distribution</secondary>
5128             </indexterm> <indexterm>
5129               <primary>OpenAFS Distribution</primary>
5130
5131               <secondary>copying AFS documentation from</secondary>
5132             </indexterm> <indexterm>
5133               <primary>first AFS machine</primary>
5134
5135               <secondary>copying</secondary>
5136
5137               <tertiary>AFS documentation from OpenAFS distribution</tertiary>
5138             </indexterm> <indexterm>
5139               <primary>index.htm file</primary>
5140             </indexterm> <indexterm>
5141               <primary>files</primary>
5142
5143               <secondary>index.htm</secondary>
5144             </indexterm></para>
5145         </listitem>
5146
5147         <listitem>
5148           <para>Copy the AFS documents in one or more formats from the unpacked distribution into subdirectories of the <emphasis
5149           role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/afsdoc</emphasis> directory. Repeat
5150           the commands for each format. <programlisting>
5151    # <emphasis role="bold">mkdir</emphasis> <replaceable>format_name</replaceable>
5152    # <emphasis role="bold">cd</emphasis> <replaceable>format_name</replaceable>
5153    # <emphasis role="bold">cp -rp /tmp/afsdocs/</emphasis><replaceable>format</replaceable>  <emphasis role="bold">.</emphasis>
5154 </programlisting></para>
5155
5156           <para>If you choose to store the HTML version of the documents in AFS, note that in addition to a subdirectory for each
5157           document there are several files with a <emphasis role="bold">.gif</emphasis> extension, which enable readers to move
5158           easily between sections of a document. The file called <emphasis role="bold">index.htm</emphasis> is an introductory HTML
5159           page that contains a hyperlink to each of the documents. For online viewing to work properly, these files must remain in
5160           the top-level HTML directory (the one named, for example, <emphasis
5161           role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/afsdoc/html</emphasis>).</para>
5162         </listitem>
5163
5164         <listitem>
5165           <para><emphasis role="bold">(Optional)</emphasis> If you believe it is helpful to your users to access the AFS documents
5166           in a certain format via a local disk directory, create <emphasis role="bold">/usr/afsdoc</emphasis> on the local disk as a
5167           symbolic link to the documentation directory in AFS (<emphasis
5168           role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
5169           role="bold">/afsdoc/</emphasis><replaceable>format_name</replaceable>). <programlisting>
5170    # <emphasis role="bold">ln -s /afs/</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/afsdoc/</emphasis><replaceable>format_name</replaceable> <emphasis
5171                 role="bold">/usr/afsdoc</emphasis>
5172 </programlisting></para>
5173
5174           <para>An alternative is to create a link in each user's home directory to the <emphasis
5175           role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
5176           role="bold">/afsdoc/</emphasis><replaceable>format_name</replaceable> directory.</para>
5177         </listitem>
5178       </orderedlist></para>
5179
5180     <indexterm>
5181       <primary>storing</primary>
5182
5183       <secondary>system binaries in volumes</secondary>
5184     </indexterm>
5185
5186     <indexterm>
5187       <primary>creating</primary>
5188
5189       <secondary>volume</secondary>
5190
5191       <tertiary>for system binaries</tertiary>
5192     </indexterm>
5193
5194     <indexterm>
5195       <primary>volume</primary>
5196
5197       <secondary>for system binaries</secondary>
5198     </indexterm>
5199
5200     <indexterm>
5201       <primary>binaries</primary>
5202
5203       <secondary>storing system in volumes</secondary>
5204     </indexterm>
5205   </sect1>
5206
5207   <sect1 id="HDRWQ88">
5208     <title>Storing System Binaries in AFS</title>
5209
5210     <para>You can also choose to store other system binaries in AFS volumes, such as the standard UNIX programs conventionally
5211     located in local disk directories such as <emphasis role="bold">/etc</emphasis>, <emphasis role="bold">/bin</emphasis>, and
5212     <emphasis role="bold">/lib</emphasis>. Storing such binaries in an AFS volume not only frees local disk space, but makes it
5213     easier to update binaries on all client machines.</para>
5214
5215     <para>The following is a suggested scheme for storing system binaries in AFS. It does not include instructions, but you can use
5216     the instructions in <link linkend="HDRWQ83">Storing AFS Binaries in AFS</link> (which are for AFS-specific binaries) as a
5217     template.</para>
5218
5219     <para>Some files must remain on the local disk for use when AFS is inaccessible (during bootup and file server or network
5220     outages). The required binaries include the following: <itemizedlist>
5221         <listitem>
5222           <para>A text editor, network commands, and so on</para>
5223         </listitem>
5224
5225         <listitem>
5226           <para>Files used during the boot sequence before the <emphasis role="bold">afsd</emphasis> program runs, such as
5227           initialization and configuration files, and binaries for commands that mount file systems</para>
5228         </listitem>
5229
5230         <listitem>
5231           <para>Files used by dynamic kernel loader programs</para>
5232         </listitem>
5233       </itemizedlist></para>
5234
5235     <para>In most cases, it is more secure to enable only locally authenticated users to access system binaries, by granting the
5236     <emphasis role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>) and <emphasis role="bold">r</emphasis> (<emphasis
5237     role="bold">read</emphasis>) permissions to the <emphasis role="bold">system:authuser</emphasis> group on the ACLs of
5238     directories that contain the binaries. If users need to access a binary while unauthenticated, however, the ACL on its directory
5239     must grant those permissions to the <emphasis role="bold">system:anyuser</emphasis> group.</para>
5240
5241     <para>The following chart summarizes the suggested volume and mount point names for storing system binaries. It uses a separate
5242     volume for each directory. You already created a volume called <replaceable>sysname</replaceable> for this machine's system type
5243     when you followed the instructions in <link linkend="HDRWQ83">Storing AFS Binaries in AFS</link>.</para>
5244
5245     <para>You can name volumes in any way you wish, and mount them at other locations than those suggested here. However, this
5246     scheme has several advantages: <itemizedlist>
5247         <listitem>
5248           <para>Volume names clearly identify volume contents</para>
5249         </listitem>
5250
5251         <listitem>
5252           <para>Using the <replaceable>sysname</replaceable> prefix on every volume makes it is easy to back up all of the volumes
5253           together, because the AFS Backup System enables you to define sets of volumes based on a string included in all of their
5254           names</para>
5255         </listitem>
5256
5257         <listitem>
5258           <para>It makes it easy to track related volumes, keeping them together on the same file server machine if desired</para>
5259         </listitem>
5260
5261         <listitem>
5262           <para>There is a clear relationship between volume name and mount point name</para>
5263         </listitem>
5264       </itemizedlist></para>
5265
5266     <informaltable frame="none">
5267       <tgroup cols="2">
5268         <colspec colwidth="50*" />
5269
5270         <colspec colwidth="50*" />
5271
5272         <thead>
5273           <row>
5274             <entry><emphasis role="bold">Volume Name</emphasis></entry>
5275
5276             <entry><emphasis role="bold">Mount Point</emphasis></entry>
5277           </row>
5278         </thead>
5279
5280         <tbody>
5281           <row>
5282             <entry><replaceable>sysname</replaceable></entry>
5283
5284             <entry><emphasis
5285             role="bold">/afs/</emphasis><replaceable>cellname</replaceable>/<replaceable>sysname</replaceable></entry>
5286           </row>
5287
5288           <row>
5289             <entry><replaceable>sysname</replaceable>.<emphasis role="bold">bin</emphasis></entry>
5290
5291             <entry><emphasis
5292             role="bold">/afs/</emphasis><replaceable>cellname</replaceable>/<replaceable>sysname</replaceable><emphasis
5293             role="bold">/bin</emphasis></entry>
5294           </row>
5295
5296           <row>
5297             <entry><replaceable>sysname</replaceable>.<emphasis role="bold">etc</emphasis></entry>
5298
5299             <entry><emphasis
5300             role="bold">/afs/</emphasis><replaceable>cellname</replaceable>/<replaceable>sysname</replaceable><emphasis
5301             role="bold">/etc</emphasis></entry>
5302           </row>
5303
5304           <row>
5305             <entry><replaceable>sysname</replaceable>.<emphasis role="bold">usr</emphasis></entry>
5306
5307             <entry><emphasis
5308             role="bold">/afs/</emphasis><replaceable>cellname</replaceable>/<replaceable>sysname</replaceable><emphasis
5309             role="bold">/usr</emphasis></entry>
5310           </row>
5311
5312           <row>
5313             <entry><replaceable>sysname</replaceable>.<emphasis role="bold">usr.afsws</emphasis></entry>
5314
5315             <entry><emphasis
5316             role="bold">/afs/</emphasis><replaceable>cellname</replaceable>/<replaceable>sysname</replaceable><emphasis
5317             role="bold">/usr/afsws</emphasis></entry>
5318           </row>
5319
5320           <row>
5321             <entry><replaceable>sysname</replaceable>.<emphasis role="bold">usr.bin</emphasis></entry>
5322
5323             <entry><emphasis
5324             role="bold">/afs/</emphasis><replaceable>cellname</replaceable>/<replaceable>sysname</replaceable><emphasis
5325             role="bold">/usr/bin</emphasis></entry>
5326           </row>
5327
5328           <row>
5329             <entry><replaceable>sysname</replaceable>.<emphasis role="bold">usr.etc</emphasis></entry>
5330
5331             <entry><emphasis
5332             role="bold">/afs/</emphasis><replaceable>cellname</replaceable>/<replaceable>sysname</replaceable><emphasis
5333             role="bold">/usr/etc</emphasis></entry>
5334           </row>
5335
5336           <row>
5337             <entry><replaceable>sysname</replaceable>.<emphasis role="bold">usr.inc</emphasis></entry>
5338
5339             <entry><emphasis
5340             role="bold">/afs/</emphasis><replaceable>cellname</replaceable>/<replaceable>sysname</replaceable><emphasis
5341             role="bold">/usr/include</emphasis></entry>
5342           </row>
5343
5344           <row>
5345             <entry><replaceable>sysname</replaceable>.<emphasis role="bold">usr.lib</emphasis></entry>
5346
5347             <entry><emphasis
5348             role="bold">/afs/</emphasis><replaceable>cellname</replaceable>/<replaceable>sysname</replaceable><emphasis
5349             role="bold">/usr/lib</emphasis></entry>
5350           </row>
5351
5352           <row>
5353             <entry><replaceable>sysname</replaceable>.<emphasis role="bold">usr.loc</emphasis></entry>
5354
5355             <entry><emphasis
5356             role="bold">/afs/</emphasis><replaceable>cellname</replaceable>/<replaceable>sysname</replaceable><emphasis
5357             role="bold">/usr/local</emphasis></entry>
5358           </row>
5359
5360           <row>
5361             <entry><replaceable>sysname</replaceable>.<emphasis role="bold">usr.man</emphasis></entry>
5362
5363             <entry><emphasis
5364             role="bold">/afs/</emphasis><replaceable>cellname</replaceable>/<replaceable>sysname</replaceable><emphasis
5365             role="bold">/usr/man</emphasis></entry>
5366           </row>
5367
5368           <row>
5369             <entry><replaceable>sysname</replaceable>.<emphasis role="bold">usr.sys</emphasis></entry>
5370
5371             <entry><emphasis
5372             role="bold">/afs/</emphasis><replaceable>cellname</replaceable>/<replaceable>sysname</replaceable><emphasis
5373             role="bold">/usr/sys</emphasis></entry>
5374           </row>
5375         </tbody>
5376       </tgroup>
5377     </informaltable>
5378
5379     <indexterm>
5380       <primary>foreign cell, enabling access</primary>
5381     </indexterm>
5382
5383     <indexterm>
5384       <primary>cell</primary>
5385
5386       <secondary>enabling access to foreign</secondary>
5387     </indexterm>
5388
5389     <indexterm>
5390       <primary>access</primary>
5391
5392       <secondary>to local and foreign cells</secondary>
5393     </indexterm>
5394
5395     <indexterm>
5396       <primary>AFS filespace</primary>
5397
5398       <secondary>enabling access to foreign cells</secondary>
5399     </indexterm>
5400
5401     <indexterm>
5402       <primary>root.cell volume</primary>
5403
5404       <secondary>mounting for foreign cells in local filespace</secondary>
5405     </indexterm>
5406
5407     <indexterm>
5408       <primary>database server machine</primary>
5409
5410       <secondary>entry in client CellServDB file</secondary>
5411
5412       <tertiary>for foreign cell</tertiary>
5413     </indexterm>
5414
5415     <indexterm>
5416       <primary>CellServDB file (client)</primary>
5417
5418       <secondary>adding entry</secondary>
5419
5420       <tertiary>for foreign cell</tertiary>
5421     </indexterm>
5422   </sect1>
5423
5424   <sect1 id="HDRWQ91">
5425     <title>Enabling Access to Foreign Cells</title>
5426
5427     <para>With current OpenAFS releases, there exist a number of mechanisms for
5428     providing access to foreign cells. You may add mount points in your AFS
5429     filespace for each foreign cell you wish users to access, or you can
5430     enable a 'synthetic' AFS root, which contains mountpoints for either all
5431     AFS cells defined in the client machine's local
5432     <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis>, or for all cells
5433     providing location information in the DNS.
5434     </para>
5435
5436     <sect2>
5437     <title>Enabling a Synthetic AFS root</title>
5438
5439     <para>When a synthetic root is enabled, the client cache machine creates its
5440     own root.afs volume, rather than using the one provided with your cell. This
5441     allows clients to access all cells in the
5442     <emphasis role="bold">CellServDB</emphasis> file and, optionally, all cells
5443     registered in the DNS, without requiring system administrator action to
5444     enable this access. Using a synthetic root has the additional advantage that
5445     it allows a client to start its AFS service without a network available, as
5446     it is no longer necessary to contact a fileserver to obtain the root volume.
5447     </para>
5448
5449     <para>OpenAFS supports two complimentary mechanisms for creating the
5450     synthetic root. Starting the cache manager with the
5451     <emphasis role="bold">-dynroot</emphasis> option adds all cells listed
5452     in <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> to the client's
5453     AFS root. Adding the <emphasis role="bold">-afsdb</emphasis> option in
5454     addition to this enables DNS lookups for any cells that are not found in
5455     the client's CellServDB file. Both of these options are added to the AFS
5456     initialisation script, or options file, as detailed in
5457     <link linkend="HDRWQ70">Configuring the Cache Manager</link>.</para>
5458     </sect2>
5459     <sect2>
5460       <title>Adding foreign cells to a conventional root volume</title>
5461
5462     <para>In this section you create a mount point in your AFS filespace for the <emphasis role="bold">root.cell</emphasis> volume
5463     of each foreign cell that you want to enable your users to access. For users working on a client machine to access the cell,
5464     there must in addition be an entry for it in the client machine's local <emphasis
5465     role="bold">/usr/vice/etc/CellServDB</emphasis> file. (The instructions in <link linkend="HDRWQ66">Creating the Client
5466     CellServDB File</link> suggest that you use the <emphasis role="bold">CellServDB.sample</emphasis> file included in the AFS
5467     distribution as the basis for your cell's client <emphasis role="bold">CellServDB</emphasis> file. The sample file lists all of
5468     the cells that had agreed to participate in the AFS global namespace at the time your AFS CD-ROM was created. As mentioned in
5469     that section, the AFS Product Support group also maintains a copy of the file, updating it as necessary.)</para>
5470
5471     <para>The chapter in the <emphasis>OpenAFS Administration Guide</emphasis> about cell administration and configuration issues
5472     discusses the implications of participating in the global AFS namespace. The chapter about administering client machines
5473     explains how to maintain knowledge of foreign cells on client machines, and includes suggestions for maintaining a central
5474     version of the file in AFS. <orderedlist>
5475         <listitem>
5476           <para>Issue the <emphasis role="bold">fs mkmount</emphasis> command to mount each foreign cell's <emphasis
5477           role="bold">root.cell</emphasis> volume on a directory called <emphasis
5478           role="bold">/afs/</emphasis><replaceable>foreign_cell</replaceable>. Because the <emphasis role="bold">root.afs</emphasis>
5479           volume is replicated, you must create a temporary mount point for its read/write version in a directory to which you have
5480           write access (such as your cell's <emphasis role="bold">/afs/.</emphasis><replaceable>cellname</replaceable> directory).
5481           Create the mount points, issue the <emphasis role="bold">vos release</emphasis> command to release new replicas to the
5482           read-only sites for the <emphasis role="bold">root.afs</emphasis> volume, and issue the <emphasis role="bold">fs
5483           checkvolumes</emphasis> command to force the local Cache Manager to access the new replica.</para>
5484
5485           <note>
5486             <para>You need to issue the <emphasis role="bold">fs mkmount</emphasis> command only once for each foreign cell's
5487             <emphasis role="bold">root.cell</emphasis> volume. You do not need to repeat the command on each client machine.</para>
5488           </note>
5489
5490           <para>Substitute your cell's name for <replaceable>cellname</replaceable>.</para>
5491
5492           <programlisting>
5493    # <emphasis role="bold">cd /afs/.</emphasis><replaceable>cellname</replaceable>
5494    # <emphasis role="bold">/usr/afs/bin/fs  mkmount  temp  root.afs</emphasis>
5495 </programlisting>
5496
5497           <para>Repeat the <emphasis role="bold">fs mkmount</emphasis> command for each foreign cell you wish to mount at this
5498           time.</para>
5499
5500           <programlisting>
5501    # <emphasis role="bold">/usr/afs/bin/fs mkmount temp/</emphasis><replaceable>foreign_cell</replaceable> <emphasis role="bold">root.cell -c</emphasis> <replaceable>foreign_cell</replaceable>
5502 </programlisting>
5503
5504           <para>Issue the following commands only once.</para>
5505
5506           <programlisting>
5507    # <emphasis role="bold">/usr/afs/bin/fs rmmount temp</emphasis>
5508    # <emphasis role="bold">/usr/afs/bin/vos release root.afs</emphasis>
5509    # <emphasis role="bold">/usr/afs/bin/fs checkvolumes</emphasis>
5510 </programlisting>
5511
5512           <indexterm>
5513             <primary>fs commands</primary>
5514
5515             <secondary>newcell</secondary>
5516           </indexterm>
5517
5518           <indexterm>
5519             <primary>commands</primary>
5520
5521             <secondary>fs newcell</secondary>
5522           </indexterm>
5523         </listitem>
5524
5525         <listitem id="LIWQ92">
5526           <para>If this machine is going to remain an AFS client after you complete the installation, verify
5527           that the local <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file includes an entry for each foreign
5528           cell.</para>
5529
5530           <para>For each cell that does not already have an entry, complete the following instructions: <orderedlist>
5531               <listitem>
5532                 <para>Create an entry in the <emphasis role="bold">CellServDB</emphasis> file. Be sure to comply with the formatting
5533                 instructions in <link linkend="HDRWQ66">Creating the Client CellServDB File</link>.</para>
5534               </listitem>
5535
5536               <listitem>
5537                 <para>Issue the <emphasis role="bold">fs newcell</emphasis> command to add an entry for the cell directly to the
5538                 list that the Cache Manager maintains in kernel memory. Provide each database server machine's fully qualified
5539                 hostname. <programlisting>
5540    # <emphasis role="bold">/usr/afs/bin/fs newcell</emphasis> &lt;<replaceable>foreign_cell</replaceable>&gt; &lt;<replaceable>dbserver1&gt;</replaceable>    \
5541             [&lt;<replaceable>dbserver2&gt;</replaceable>] [&lt;<replaceable>dbserver3&gt;</replaceable>]
5542 </programlisting></para>
5543               </listitem>
5544
5545               <listitem>
5546                 <para>If you plan to maintain a central version of the <emphasis role="bold">CellServDB</emphasis> file (the
5547                 conventional location is <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
5548                 role="bold">/common/etc/CellServDB</emphasis>), create it now as a copy of the local <emphasis
5549                 role="bold">/usr/vice/etc/CellServDB</emphasis> file. Verify that it includes an entry for each foreign cell you
5550                 want your users to be able to access. <programlisting>
5551    # <emphasis role="bold">mkdir common</emphasis>
5552    # <emphasis role="bold">mkdir common/etc</emphasis>
5553    # <emphasis role="bold">cp  /usr/vice/etc/CellServDB  common/etc</emphasis>
5554    # <emphasis role="bold">/usr/afs/bin/vos release root.cell</emphasis>
5555 </programlisting></para>
5556               </listitem>
5557             </orderedlist></para>
5558         </listitem>
5559
5560         <listitem>
5561           <para>Issue the <emphasis role="bold">ls</emphasis> command to verify that the new cell's mount point is visible in your
5562           filespace. The output lists the directories at the top level of the new cell's AFS filespace. <programlisting>
5563    # <emphasis role="bold">ls /afs/</emphasis><replaceable>foreign_cell</replaceable>
5564 </programlisting></para>
5565         </listitem>
5566
5567         <listitem>
5568           <para>If you wish to participate in the global AFS namespace, and only
5569           intend running one database server, please
5570           register your cell with grand.central.org at this time.
5571           To do so, email the <emphasis role="bold">CellServDB</emphasis> fragment
5572           describing your cell, together with a contact name and email address
5573           for any queries, to cellservdb@grand.central.org. If you intend
5574           on deploying multiple database servers, please wait until you have
5575           installed all of them before registering your cell.</para>
5576         </listitem>
5577         <listitem>
5578           <para>If you wish to allow your cell to be located through DNS lookups,
5579           at this time you should also add the necessary configuration to your
5580           DNS.</para>
5581
5582           <para>AFS database servers may be located by creating AFSDB records
5583           in the DNS for the domain name corresponding to the name of your cell.
5584           It's outside the scope of this guide to give an indepth description of
5585           managing, or configuring, your site's DNS. You should consult the
5586           documentation for your DNS server for further details on AFSDB
5587           records.</para>
5588         </listitem>
5589       </orderedlist></para>
5590     </sect2>
5591   </sect1>
5592
5593   <sect1 id="HDRWQ93">
5594     <title>Improving Cell Security</title>
5595
5596     <indexterm>
5597       <primary>cell</primary>
5598
5599       <secondary>improving security</secondary>
5600     </indexterm>
5601
5602     <indexterm>
5603       <primary>security</primary>
5604
5605       <secondary>improving</secondary>
5606     </indexterm>
5607
5608     <indexterm>
5609       <primary>root superuser</primary>
5610
5611       <secondary>controlling access</secondary>
5612     </indexterm>
5613
5614     <indexterm>
5615       <primary>access</primary>
5616
5617       <secondary>to root and admin accounts</secondary>
5618     </indexterm>
5619
5620     <indexterm>
5621       <primary>admin account</primary>
5622
5623       <secondary>controlling access to</secondary>
5624     </indexterm>
5625
5626     <indexterm>
5627       <primary>AFS filespace</primary>
5628
5629       <secondary>controlling access by root superuser</secondary>
5630     </indexterm>
5631
5632     <para>This section discusses ways to improve the security of AFS data
5633     in your cell. Also see the chapter in the <emphasis>OpenAFS
5634     Administration Guide</emphasis> about configuration and administration
5635     issues.</para>
5636
5637     <sect2 id="HDRWQ94">
5638       <title>Controlling root Access</title>
5639
5640       <para>As on any machine, it is important to prevent unauthorized users from logging onto an AFS server or client machine as
5641       the local superuser <emphasis role="bold">root</emphasis>. Take care to keep the <emphasis role="bold">root</emphasis>
5642       password secret.</para>
5643
5644       <para>The local <emphasis role="bold">root</emphasis> superuser does not have special access to AFS data through the Cache
5645       Manager (as members of the <emphasis role="bold">system:administrators</emphasis> group do), but it does have the following
5646       privileges: <itemizedlist>
5647           <listitem>
5648             <para>On client machines, the ability to issue commands from the <emphasis role="bold">fs</emphasis> suite that affect
5649             AFS performance</para>
5650           </listitem>
5651
5652           <listitem>
5653             <para>On server machines, the ability to disable authorization checking, or to install rogue process binaries</para>
5654           </listitem>
5655         </itemizedlist></para>
5656     </sect2>
5657
5658     <sect2 id="HDRWQ95">
5659       <title>Controlling System Administrator Access</title>
5660
5661       <para>Following are suggestions for managing AFS administrative privilege: <itemizedlist>
5662           <listitem>
5663             <para>Create an administrative account for each administrator named
5664             something like
5665             <replaceable>username</replaceable><emphasis role="bold">.admin</emphasis>.
5666             Administrators authenticate under these identities only when
5667             performing administrative tasks, and destroy the administrative
5668             tokens immediately after finishing the task (either by issuing the
5669             <emphasis role="bold">unlog</emphasis> command, or the
5670             <emphasis role="bold">kinit</emphasis> and
5671             <emphasis role="bold">aklog</emphasis> commands to adopt their
5672             regular identity).</para>
5673           </listitem>
5674
5675           <listitem>
5676             <para>Set a short ticket lifetime for administrator accounts (for example, 20 minutes) by using the
5677             facilities of your KDC. For instance, with a MIT Kerberos KDC, this
5678             can be performed using the
5679             <emphasis role="bold">--max-ticket-life</emphasis> argument to
5680             the <emphasis role="bold">kadmin modify_principal</emphasis>
5681             command. Do not however, use a short lifetime for users
5682             who issue long-running <emphasis role="bold">backup</emphasis> commands.</para>
5683           </listitem>
5684
5685           <listitem>
5686             <para>Limit the number of system administrators in your cell, especially those who belong to the <emphasis
5687             role="bold">system:administrators</emphasis> group. By default they have all ACL rights on all directories in the local
5688             AFS filespace, and therefore must be trusted not to examine private files.</para>
5689           </listitem>
5690
5691           <listitem>
5692             <para>Limit the use of system administrator accounts on machines in public areas. It is especially important not to
5693             leave such machines unattended without first destroying the administrative tokens.</para>
5694           </listitem>
5695
5696           <listitem>
5697             <para>Limit the use by administrators of standard UNIX commands that make connections to remote machines (such as the
5698             <emphasis role="bold">telnet</emphasis> utility). Many of these programs send passwords across the network without
5699             encrypting them.</para>
5700           </listitem>
5701         </itemizedlist></para>
5702
5703       <indexterm>
5704         <primary>BOS Server</primary>
5705
5706         <secondary>checking mode bits on AFS directories</secondary>
5707       </indexterm>
5708
5709       <indexterm>
5710         <primary>mode bits on local AFS directories</primary>
5711       </indexterm>
5712
5713       <indexterm>
5714         <primary>UNIX mode bits on local AFS directories</primary>
5715       </indexterm>
5716     </sect2>
5717
5718     <sect2 id="HDRWQ96">
5719       <title>Protecting Sensitive AFS Directories</title>
5720
5721       <para>Some subdirectories of the <emphasis role="bold">/usr/afs</emphasis> directory contain files crucial to cell security.
5722       Unauthorized users must not read or write to these files because of the potential for misuse of the information they
5723       contain.</para>
5724
5725       <para>As the BOS Server initializes for the first time on a server machine, it creates several files and directories (as
5726       mentioned in <link linkend="HDRWQ50">Starting the BOS Server</link>). It sets their owner to the local superuser <emphasis
5727       role="bold">root</emphasis> and sets their mode bits to enable writing by the owner only; in some cases, it also restricts
5728       reading.</para>
5729
5730       <para>At each subsequent restart, the BOS Server checks that the owner and mode bits on these files are still set
5731       appropriately. If they are not, it write the following message to the <emphasis role="bold">/usr/afs/logs/BosLog</emphasis>
5732       file:</para>
5733
5734       <programlisting>
5735    Bosserver reports inappropriate access on server directories
5736 </programlisting>
5737
5738       <para>The BOS Server does not reset the mode bits, which enables you to set alternate values if you wish.</para>
5739
5740       <para>The following charts lists the expected mode bit settings. A question mark indicates that the BOS Server does not check
5741       that mode bit.</para>
5742
5743       <informaltable frame="none">
5744         <tgroup cols="2">
5745           <colspec colwidth="30*" />
5746
5747           <colspec colwidth="70*" />
5748
5749           <tbody>
5750             <row>
5751               <entry><emphasis role="bold">/usr/afs</emphasis></entry>
5752
5753               <entry><computeroutput>drwxr</computeroutput>?<computeroutput>xr-x</computeroutput></entry>
5754             </row>
5755
5756             <row>
5757               <entry><emphasis role="bold">/usr/afs/backup</emphasis></entry>
5758
5759               <entry><computeroutput>drwx</computeroutput>???<computeroutput>---</computeroutput></entry>
5760             </row>
5761
5762             <row>
5763               <entry><emphasis role="bold">/usr/afs/bin</emphasis></entry>
5764
5765               <entry><computeroutput>drwxr</computeroutput>?<computeroutput>xr-x</computeroutput></entry>
5766             </row>
5767
5768             <row>
5769               <entry><emphasis role="bold">/usr/afs/db</emphasis></entry>
5770
5771               <entry><computeroutput>drwx</computeroutput>???<computeroutput>---</computeroutput></entry>
5772             </row>
5773
5774             <row>
5775               <entry><emphasis role="bold">/usr/afs/etc</emphasis></entry>
5776
5777               <entry><computeroutput>drwxr</computeroutput>?<computeroutput>xr-x</computeroutput></entry>
5778             </row>
5779
5780             <row>
5781               <entry><emphasis role="bold">/usr/afs/etc/KeyFile</emphasis></entry>
5782
5783               <entry><computeroutput>-rw</computeroutput>????<computeroutput>---</computeroutput></entry>
5784             </row>
5785
5786             <row>
5787               <entry><emphasis role="bold">/usr/afs/etc/UserList</emphasis></entry>
5788
5789               <entry><computeroutput>-rw</computeroutput>?????<computeroutput>--</computeroutput></entry>
5790             </row>
5791
5792             <row>
5793               <entry><emphasis role="bold">/usr/afs/local</emphasis></entry>
5794
5795               <entry><computeroutput>drwx</computeroutput>???<computeroutput>---</computeroutput></entry>
5796             </row>
5797
5798             <row>
5799               <entry><emphasis role="bold">/usr/afs/logs</emphasis></entry>
5800
5801               <entry><computeroutput>drwxr</computeroutput>?<computeroutput>xr-x</computeroutput></entry>
5802             </row>
5803           </tbody>
5804         </tgroup>
5805       </informaltable>
5806
5807       <indexterm>
5808         <primary>first AFS machine</primary>
5809
5810         <secondary>client functionality</secondary>
5811
5812         <tertiary>removing</tertiary>
5813       </indexterm>
5814
5815       <indexterm>
5816         <primary>removing</primary>
5817
5818         <secondary>client functionality from first AFS machine</secondary>
5819       </indexterm>
5820     </sect2>
5821   </sect1>
5822
5823   <sect1 id="HDRWQ98">
5824     <title>Removing Client Functionality</title>
5825
5826     <para>Follow the instructions in this section only if you do not wish this machine to remain an AFS client. Removing client
5827     functionality means that you cannot use this machine to access AFS files. <orderedlist>
5828         <listitem>
5829           <para>Remove the files from the <emphasis role="bold">/usr/vice/etc</emphasis> directory. The command does not remove the
5830           directory for files used by the dynamic kernel loader program, if it exists on this system type. Those files are still
5831           needed on a server-only machine. <programlisting>
5832    # <emphasis role="bold">cd /usr/vice/etc</emphasis>
5833    # <emphasis role="bold">rm  *</emphasis>
5834    # <emphasis role="bold">rm -rf  C</emphasis>
5835 </programlisting></para>
5836         </listitem>
5837
5838         <listitem>
5839           <para>Create symbolic links to the <emphasis role="bold">ThisCell</emphasis> and <emphasis
5840           role="bold">CellServDB</emphasis> files in the <emphasis role="bold">/usr/afs/etc</emphasis> directory. This makes it
5841           possible to issue commands from the AFS command suites (such as <emphasis role="bold">bos</emphasis> and <emphasis
5842           role="bold">fs</emphasis>) on this machine. <programlisting>
5843    # <emphasis role="bold">ln -s /usr/afs/etc/ThisCell ThisCell</emphasis>
5844    # <emphasis role="bold">ln -s /usr/afs/etc/CellServDB CellServDB</emphasis>
5845 </programlisting></para>
5846         </listitem>
5847
5848         <listitem>
5849           <para>On IRIX systems, issue the <emphasis role="bold">chkconfig</emphasis> command to deactivate the <emphasis
5850           role="bold">afsclient</emphasis> configuration variable. <programlisting>
5851    # <emphasis role="bold">/etc/chkconfig -f afsclient off</emphasis>
5852 </programlisting></para>
5853         </listitem>
5854
5855         <listitem>
5856           <para>Reboot the machine. Most system types use the <emphasis role="bold">shutdown</emphasis> command, but the appropriate
5857           options vary. <programlisting>
5858    # <emphasis role="bold">cd /</emphasis>
5859    # <emphasis role="bold">shutdown</emphasis> <replaceable>appropriate_options</replaceable>
5860 </programlisting></para>
5861         </listitem>
5862       </orderedlist></para>
5863   </sect1>
5864 </chapter>