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