File: auagd008.xml

package info (click to toggle)
openafs 1.8.14-1
links: PTS, VCS
area: main
in suites: sid
size: 42,972 kB
sloc: ansic: 455,934; xml: 66,858; perl: 11,967; makefile: 10,038; sh: 7,955; objc: 6,354; java: 5,638; cpp: 2,268; asm: 1,214; yacc: 441; tcl: 249; lex: 201; csh: 85
file content (5562 lines) | stat: -rw-r--r-- 245,977 bytes
parent folder | download | duplicates (5)
<?xml version="1.0" encoding="UTF-8"?>
<chapter id="HDRWQ80">
  <title>Administering Server Machines</title>

  <para>
  <indexterm>
    <primary>server machine</primary>

    <secondary>administering</secondary>
  </indexterm>

  <indexterm>
    <primary>administering</primary>

    <secondary>server machine</secondary>
  </indexterm>

  This chapter describes how to administer an AFS server machine. It describes the following configuration information and
  administrative tasks: <itemizedlist>
      <listitem>
        <para>The binary and configuration files that must reside in the subdirectories of the <emphasis
        role="bold">/usr/afs</emphasis> directory on every server machine's local disk; see <link linkend="HDRWQ83">Local Disk Files
        on a Server Machine</link>.</para>
      </listitem>

      <listitem>
        <para>The various <emphasis>roles</emphasis> or functions that an AFS server machine can perform, and how to determine which
        machines are taking a role; see <link linkend="HDRWQ90">The Four Roles for File Server Machines</link>.</para>
      </listitem>

      <listitem>
        <para>How to maintain database server machines; see <link linkend="HDRWQ101">Administering Database Server
        Machines</link>.</para>
      </listitem>

      <listitem>
        <para>How to maintain the list of database server machines in the <emphasis role="bold">/usr/afs/etc/CellServDB</emphasis>
        file; see <link linkend="HDRWQ118">Maintaining the Server CellServDB File</link>.</para>
      </listitem>

      <listitem>
        <para>How to control authorization checking on a server machine; see <link linkend="HDRWQ123">Managing Authentication and
        Authorization Requirements</link>.</para>
      </listitem>

      <listitem>
        <para>How to install new disks or partitions on a file server machine; see <link linkend="HDRWQ130">Adding or Removing Disks
        and Partitions</link>.</para>
      </listitem>

      <listitem>
        <para>How to change a server machine's IP addresses and manager VLDB server entries; see <link linkend="HDRWQ138">Managing
        Server IP Addresses and VLDB Server Entries</link>.</para>
      </listitem>

      <listitem>
        <para>How to reboot a file server machine; see <link linkend="HDRWQ139">Rebooting a Server Machine</link>.</para>
      </listitem>
    </itemizedlist></para>

  <para>To learn how to install and configure a new server machine, see the <emphasis>OpenAFS Quick Beginnings</emphasis>.</para>

  <para>To learn how to administer the server processes themselves, see <link linkend="HDRWQ142">Monitoring and Controlling Server
  Processes</link>.</para>

  <para>To learn how to administer volumes, see <link linkend="HDRWQ174">Managing Volumes</link>.</para>

  <sect1 id="HDRWQ81">
    <title>Summary of Instructions</title>

    <para>This chapter explains how to perform the following tasks by using the indicated commands:</para>

    <informaltable frame="none">
      <tgroup cols="2">
        <colspec colwidth="70*" />

        <colspec colwidth="30*" />

        <tbody>
          <row>
            <entry>Install new binaries</entry>

            <entry><emphasis role="bold">bos install</emphasis></entry>
          </row>

          <row>
            <entry>Examine binary check-and-restart time</entry>

            <entry><emphasis role="bold">bos getrestart</emphasis></entry>
          </row>

          <row>
            <entry>Set binary check-and-restart time</entry>

            <entry><emphasis role="bold">bos setrestart</emphasis></entry>
          </row>

          <row>
            <entry>Examine compilation dates on binary files</entry>

            <entry><emphasis role="bold">bos getdate</emphasis></entry>
          </row>

          <row>
            <entry>Restart a process to use new binaries</entry>

            <entry><emphasis role="bold">bos restart</emphasis></entry>
          </row>

          <row>
            <entry>Revert to old version of binaries</entry>

            <entry><emphasis role="bold">bos uninstall</emphasis></entry>
          </row>

          <row>
            <entry>Remove obsolete <emphasis role="bold">.BAK</emphasis> and <emphasis role="bold">.OLD</emphasis> versions</entry>

            <entry><emphasis role="bold">bos prune</emphasis></entry>
          </row>

          <row>
            <entry>List partitions on a file server machine</entry>

            <entry><emphasis role="bold">vos listpart</emphasis></entry>
          </row>

          <row>
            <entry>Shutdown AFS server processes</entry>

            <entry><emphasis role="bold">bos shutdown</emphasis></entry>
          </row>

          <row>
            <entry>List volumes on a partition</entry>

            <entry><emphasis role="bold">vos listvldb</emphasis></entry>
          </row>

          <row>
            <entry>Move read/write volumes</entry>

            <entry><emphasis role="bold">vos move</emphasis></entry>
          </row>

          <row>
            <entry>List a cell's database server machines</entry>

            <entry><emphasis role="bold">bos listhosts</emphasis></entry>
          </row>

          <row>
            <entry>Add a database server machine to server <emphasis role="bold">CellServDB</emphasis> file</entry>

            <entry><emphasis role="bold">bos addhost</emphasis></entry>
          </row>

          <row>
            <entry>Remove a database server machine from server <emphasis role="bold">CellServDB</emphasis> file</entry>

            <entry><emphasis role="bold">bos removehost</emphasis></entry>
          </row>

          <row>
            <entry>Set authorization checking requirements</entry>

            <entry><emphasis role="bold">bos setauth</emphasis></entry>
          </row>

          <row>
            <entry>Prevent authentication for <emphasis role="bold">bos</emphasis>, <emphasis role="bold">pts</emphasis>, and
            <emphasis role="bold">vos</emphasis> commands</entry>

            <entry>Include <emphasis role="bold">-noauth</emphasis> flag</entry>
          </row>

          <row>
            <entry>Prevent authentication for kas commands</entry>

            <entry>Include <emphasis role="bold">-noauth</emphasis> flag on some commands or issue <emphasis
            role="bold">noauthentication</emphasis> while in interactive mode</entry>
          </row>

          <row>
            <entry>Display all VLDB server entries</entry>

            <entry><emphasis role="bold">vos listaddrs</emphasis></entry>
          </row>

          <row>
            <entry>Remove a VLDB server entry</entry>

            <entry><emphasis role="bold">vos changeaddr</emphasis></entry>
          </row>

          <row>
            <entry>Reboot a server machine remotely</entry>

            <entry><emphasis role="bold">bos exec</emphasis> <emphasis>reboot_command</emphasis></entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>
  </sect1>

  <sect1 id="HDRWQ83">
    <title>Local Disk Files on a Server Machine</title>

    <para>Several types of files must reside in the subdirectories of the <emphasis role="bold">/usr/afs</emphasis> directory on an
    AFS server machine's local disk. They include binaries, configuration files, the administrative database files (on database
    server machines), log files, and volume header files.</para>

    <para><emphasis role="bold">Note for Windows users:</emphasis> Some files described in this document possibly do not exist on
    machines that run a Windows operating system. Also, Windows uses a backslash (<emphasis role="bold">\</emphasis>) rather than a
    forward slash (<emphasis role="bold">/</emphasis>) to separate the elements in a pathname.</para>

    <indexterm>
      <primary>usr/afs/bin directory on server machines</primary>

      <secondary>contents listed</secondary>
    </indexterm>

    <indexterm>
      <primary>directory</primary>

      <secondary>/usr/afs/bin on server machines</secondary>
    </indexterm>

    <indexterm>
      <primary>server process binaries</primary>

      <secondary>in /usr/afs/bin</secondary>
    </indexterm>

    <sect2 id="HDRWQ84">
      <title>Binaries in the /usr/afs/bin Directory</title>

      <para>The <emphasis role="bold">/usr/afs/bin</emphasis> directory stores the AFS server process and command suite binaries
      appropriate for the machine's system (CPU and operating system) type. If a process has both a server portion and a client
      portion (as with the Update Server) or if it has separate components (as with the <emphasis role="bold">fs</emphasis>
      process), each component resides in a separate file.</para>

      <para>To ensure predictable system performance, all file server machines must run the same AFS build version of a given
      process. To maintain consistency easily, use the Update Server process to distribute binaries from a binary distribution
      machine of each system type, as described further in <link linkend="HDRWQ93">Binary Distribution Machines</link>.</para>

      <para>It is best to keep the binaries for all processes in the <emphasis role="bold">/usr/afs/bin</emphasis> directory, even
      if you do not run the process actively on the machine. It simplifies the process of reconfiguring machines (for example,
      adding database server functionality to an existing file server machine). Similarly, it is best to keep the command suite
      binaries in the directory, even if you do not often issue commands while working on the server machine. It enables you to
      issue commands during recovery from server and machine outages.</para>

      <para>The following lists the binary files in the <emphasis role="bold">/usr/afs/bin</emphasis> directory that are directly
      related to the AFS server processes or command suites. Other binaries (for example, for the <emphasis
      role="bold">klog</emphasis> command) sometimes appear in this directory on a particular file server machine's disk or in an
      AFS distribution. <variablelist>
          <indexterm>
            <primary>files</primary>

            <secondary>backup command binary</secondary>
          </indexterm>

          <indexterm>
            <primary>backup commands</primary>

            <secondary>binary in /usr/afs/bin</secondary>
          </indexterm>

          <varlistentry>
            <term><emphasis role="bold">backup</emphasis></term>

            <listitem>
              <para>The command suite for the AFS Backup System (the binary for the Backup Server is <emphasis
              role="bold">buserver</emphasis>).</para>

              <indexterm>
                <primary>files</primary>

                <secondary>bos command binary</secondary>
              </indexterm>

              <indexterm>
                <primary>bos commands</primary>

                <secondary>binary in /usr/afs/bin</secondary>
              </indexterm>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">bos</emphasis></term>

            <listitem>
              <para>The command suite for communicating with the Basic OverSeer (BOS) Server (the binary for the BOS Server is
              <emphasis role="bold">bosserver</emphasis>).</para>

              <indexterm>
                <primary>bosserver</primary>

                <secondary>binary in /usr/afs/bin</secondary>
              </indexterm>

              <indexterm>
                <primary>bosserver</primary>

                <secondary></secondary>

                <see>BOS Server</see>
              </indexterm>

              <indexterm>
                <primary>files</primary>

                <secondary>bosserver binary</secondary>
              </indexterm>

              <indexterm>
                <primary>programs</primary>

                <secondary>bosserver</secondary>
              </indexterm>

              <indexterm>
                <primary>processes</primary>

                <secondary>BOS Server, binary in /usr/afs/bin</secondary>
              </indexterm>

              <indexterm>
                <primary>BOS Server</primary>

                <secondary>binary in /usr/afs/bin</secondary>
              </indexterm>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">bosserver</emphasis></term>

            <listitem>
              <para>The binary for the Basic OverSeer (BOS) Server process.</para>

              <indexterm>
                <primary>buserver</primary>

                <secondary>binary in /usr/afs/bin</secondary>
              </indexterm>

              <indexterm>
                <primary>buserver</primary>

                <secondary></secondary>

                <see>Backup Server</see>
              </indexterm>

              <indexterm>
                <primary>files</primary>

                <secondary>buserver</secondary>
              </indexterm>

              <indexterm>
                <primary>programs</primary>

                <secondary>buserver</secondary>
              </indexterm>

              <indexterm>
                <primary>processes</primary>

                <secondary>Backup Server, binary in /usr/afs/bin</secondary>
              </indexterm>

              <indexterm>
                <primary>Backup Server</primary>

                <secondary>binary in /usr/afs/bin</secondary>
              </indexterm>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">buserver</emphasis></term>

            <listitem>
              <para>The binary for the Backup Server process.</para>

              <indexterm>
                <primary>fileserver</primary>

                <secondary>binary in /usr/afs/bin</secondary>
              </indexterm>

              <indexterm>
                <primary>fileserver</primary>

                <secondary></secondary>

                <see>File Server</see>
              </indexterm>

              <indexterm>
                <primary>files</primary>

                <secondary>fileserver</secondary>
              </indexterm>

              <indexterm>
                <primary>programs</primary>

                <secondary>fileserver</secondary>
              </indexterm>

              <indexterm>
                <primary>processes</primary>

                <secondary>File Server, binary in /usr/afs/bin</secondary>
              </indexterm>

              <indexterm>
                <primary>File Server</primary>

                <secondary>binary in /usr/afs/bin</secondary>
              </indexterm>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">fileserver</emphasis></term>

            <listitem>
              <para>The binary for the File Server component of the <emphasis role="bold">fs</emphasis> process.</para>

              <indexterm>
                <primary>files</primary>

                <secondary>kas command binary</secondary>
              </indexterm>

              <indexterm>
                <primary>kas commands</primary>

                <secondary>binary in /usr/afs/bin</secondary>
              </indexterm>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">kas</emphasis></term>

            <listitem>
              <para>The command suite for communicating with the Authentication Server (the binary for the Authentication Server is
              <emphasis role="bold">kaserver</emphasis>).</para>

              <indexterm>
                <primary>kaserver process</primary>

                <secondary>binary in /usr/afs/bin</secondary>
              </indexterm>

              <indexterm>
                <primary>kaserver process</primary>

                <secondary></secondary>

                <see>Authentication Server</see>
              </indexterm>

              <indexterm>
                <primary>files</primary>

                <secondary>kaserver binary file</secondary>
              </indexterm>

              <indexterm>
                <primary>programs</primary>

                <secondary>kaserver</secondary>
              </indexterm>

              <indexterm>
                <primary>processes</primary>

                <secondary>Authentication Server, binary in /usr/afs/bin</secondary>
              </indexterm>

              <indexterm>
                <primary>Authentication Server</primary>

                <secondary>binary in /usr/afs/bin</secondary>
              </indexterm>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">kaserver</emphasis></term>

            <listitem>
              <para>The binary for the Authentication Server process.</para>

              <indexterm>
                <primary>files</primary>

                <secondary>pts command binary</secondary>
              </indexterm>

              <indexterm>
                <primary>pts commands</primary>

                <secondary>binary in /usr/afs/bin</secondary>
              </indexterm>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">pts</emphasis></term>

            <listitem>
              <para>The command suite for communicating with the Protection Server process (the binary for the Protection Server is
              <emphasis role="bold">ptserver</emphasis>).</para>

              <indexterm>
                <primary>ptserver process</primary>

                <secondary>binary in /usr/afs/bin</secondary>
              </indexterm>

              <indexterm>
                <primary>ptserver process</primary>

                <secondary></secondary>

                <see>Protection Server</see>
              </indexterm>

              <indexterm>
                <primary>files</primary>

                <secondary>ptserver binary</secondary>
              </indexterm>

              <indexterm>
                <primary>programs</primary>

                <secondary>ptserver</secondary>
              </indexterm>

              <indexterm>
                <primary>processes</primary>

                <secondary>Protection Server, binary in /usr/afs/bin</secondary>
              </indexterm>

              <indexterm>
                <primary>Protection Server</primary>

                <secondary>binary in /usr/afs/bin</secondary>
              </indexterm>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">ptserver</emphasis></term>

            <listitem>
              <para>The binary for the Protection Server process.</para>

              <indexterm>
                <primary>Salvager</primary>

                <secondary>binary in /usr/afs/bin</secondary>
              </indexterm>

              <indexterm>
                <primary>Salvager</primary>

                <secondary></secondary>

                <see>Salvager</see>
              </indexterm>

              <indexterm>
                <primary>files</primary>

                <secondary>salvager</secondary>
              </indexterm>

              <indexterm>
                <primary>programs</primary>

                <secondary>salvager</secondary>
              </indexterm>

              <indexterm>
                <primary>processes</primary>

                <secondary>Salvager, binary in /usr/afs/bin</secondary>
              </indexterm>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">salvager</emphasis></term>

            <listitem>
              <para>The binary for the Salvager component of the <emphasis role="bold">fs</emphasis> process.</para>

              <indexterm>
                <primary>udebug</primary>

                <secondary>binary in /usr/afs/bin</secondary>
              </indexterm>

              <indexterm>
                <primary>files</primary>

                <secondary>udebug</secondary>
              </indexterm>

              <indexterm>
                <primary>commands</primary>

                <secondary>udebug</secondary>
              </indexterm>

              <indexterm>
                <primary>programs</primary>

                <secondary>udebug</secondary>
              </indexterm>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">udebug</emphasis></term>

            <listitem>
              <para>The binary for a program that reports the status of AFS's distributed database technology, Ubik.</para>

              <indexterm>
                <primary>upclient</primary>

                <secondary>binary in /usr/afs/bin</secondary>
              </indexterm>

              <indexterm>
                <primary>upclient</primary>

                <secondary></secondary>

                <see>Update Server</see>
              </indexterm>

              <indexterm>
                <primary>files</primary>

                <secondary>upclient</secondary>
              </indexterm>

              <indexterm>
                <primary>programs</primary>

                <secondary>upclient</secondary>
              </indexterm>

              <indexterm>
                <primary>processes</primary>

                <secondary>Update Server, binaries in /usr/afs/bin</secondary>
              </indexterm>

              <indexterm>
                <primary>Update Server</primary>

                <secondary>binaries in /usr/afs/bin</secondary>
              </indexterm>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">upclient</emphasis></term>

            <listitem>
              <para>The binary for the client portion of the Update Server process.</para>

              <indexterm>
                <primary>upserver</primary>

                <secondary>binary in /usr/afs/bin</secondary>
              </indexterm>

              <indexterm>
                <primary>upserver</primary>

                <secondary></secondary>

                <see>Update Server</see>
              </indexterm>

              <indexterm>
                <primary>files</primary>

                <secondary>upserver</secondary>
              </indexterm>

              <indexterm>
                <primary>programs</primary>

                <secondary>upserver</secondary>
              </indexterm>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">upserver</emphasis></term>

            <listitem>
              <para>The binary for the server portion of the Update Server process.</para>

              <indexterm>
                <primary>vlserver</primary>

                <secondary>binary in /usr/afs/bin</secondary>
              </indexterm>

              <indexterm>
                <primary>vlserver</primary>

                <secondary></secondary>

                <see>VL Server</see>
              </indexterm>

              <indexterm>
                <primary>files</primary>

                <secondary>vlserver</secondary>
              </indexterm>

              <indexterm>
                <primary>programs</primary>

                <secondary>vlserver</secondary>
              </indexterm>

              <indexterm>
                <primary>processes</primary>

                <secondary>VL Server, binary in /usr/afs/bin</secondary>
              </indexterm>

              <indexterm>
                <primary>VL Server</primary>

                <secondary>binary in /usr/afs/bin</secondary>
              </indexterm>

              <indexterm>
                <primary>Volume Location Server</primary>

                <secondary></secondary>

                <see>VL Server</see>
              </indexterm>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">vlserver</emphasis></term>

            <listitem>
              <para>The binary for the Volume Location (VL) Server process.</para>

              <indexterm>
                <primary>volserver</primary>

                <secondary>binary in /usr/afs/bin</secondary>
              </indexterm>

              <indexterm>
                <primary>volserver</primary>

                <secondary></secondary>

                <see>Volume Server</see>
              </indexterm>

              <indexterm>
                <primary>files</primary>

                <secondary>volserver</secondary>
              </indexterm>

              <indexterm>
                <primary>programs</primary>

                <secondary>volserver</secondary>
              </indexterm>

              <indexterm>
                <primary>processes</primary>

                <secondary>Volume Server, binary in /usr/afs/bin</secondary>
              </indexterm>

              <indexterm>
                <primary>Volume Server</primary>

                <secondary>binary in /usr/afs/bin</secondary>
              </indexterm>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">volserver</emphasis></term>

            <listitem>
              <para>The binary for the Volume Server component of the <emphasis role="bold">fs</emphasis> process.</para>

              <indexterm>
                <primary>files</primary>

                <secondary>vos command binary</secondary>
              </indexterm>

              <indexterm>
                <primary>vos commands</primary>

                <secondary>binary in /usr/afs/bin</secondary>
              </indexterm>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">vos</emphasis></term>

            <listitem>
              <para>The command suite for communicating with the Volume and VL Server processes (the binaries for the servers are
              <emphasis role="bold">volserver</emphasis> and <emphasis role="bold">vlserver</emphasis>, respectively).</para>
            </listitem>
          </varlistentry>
        </variablelist></para>

      <indexterm>
        <primary>usr/afs/etc directory on server machines</primary>

        <secondary>contents listed</secondary>
      </indexterm>

      <indexterm>
        <primary>directory</primary>

        <secondary>/usr/afs/etc</secondary>
      </indexterm>

      <indexterm>
        <primary>files</primary>

        <secondary>server configuration, in /usr/afs/etc directory</secondary>
      </indexterm>

      <indexterm>
        <primary>common configuration files (server)</primary>
      </indexterm>

      <indexterm>
        <primary>server machine</primary>

        <secondary>configuration files in /usr/afs/etc</secondary>
      </indexterm>
    </sect2>

    <sect2 id="HDRWQ85">
      <title>Common Configuration Files in the /usr/afs/etc Directory</title>

      <para>The directory <emphasis role="bold">/usr/afs/etc</emphasis> on every file server machine's local disk contains
      configuration files in ASCII and machine-independent binary format. For predictable AFS performance throughout a cell, all
      server machines must have the same version of each configuration file: <itemizedlist>
          <indexterm>
            <primary>Update Server</primary>

            <secondary>distributing server configuration files</secondary>
          </indexterm>

          <listitem>
            <para>Cells conventionally use the Update Server to distribute a common
            version of each file from the cell's system control machine to other server machines (for more on the system control
            machine, see <link linkend="HDRWQ94">The System Control Machine</link>). Run the Update Server's server portion on the
            system control machine, and the client portion on all other server machines. Update the files on the system control
            machine only, except as directed by instructions for dealing with emergencies.</para>
          </listitem>
        </itemizedlist></para>

      <para>Never directly edit any of the files in the <emphasis role="bold">/usr/afs/etc</emphasis> directory, except as directed
      by instructions for dealing with emergencies. In normal circumstances, use the appropriate <emphasis
      role="bold">bos</emphasis> commands to change the files. The following list includes pointers to instructions.</para>

      <para>The files in this directory include: <variablelist>
          <indexterm>
            <primary>CellServDB file (server)</primary>

            <secondary>about</secondary>
          </indexterm>

          <indexterm>
            <primary>files</primary>

            <secondary>CellServDB (server)</secondary>
          </indexterm>

          <varlistentry>
            <term><emphasis role="bold">CellServDB</emphasis></term>

            <listitem>
              <para>An ASCII file that names the cell's database server machines, which run the Authentication, Backup, Protection,
              and VL Server processes. You create the initial version of this file by issuing the <emphasis role="bold">bos
              setcellname</emphasis> command while installing your cell's first server machine. It is very important to update this
              file when you change the identity of your cell's database server machines.</para>

              <para>The server <emphasis role="bold">CellServDB</emphasis> file is not the same as the <emphasis
              role="bold">CellServDB</emphasis> file stored in the <emphasis role="bold">/usr/vice/etc</emphasis> directory on
              client machines. The client version lists the database server machines for every AFS cell that you choose to make
              accessible from the client machine. The server <emphasis role="bold">CellServDB</emphasis> file lists only the local
              cell's database server machines, because server processes never contact processes in other cells.</para>

              <para>For instructions on maintaining this file, see <link linkend="HDRWQ118">Maintaining the Server CellServDB
              File</link>.</para>

              <indexterm>
                <primary>KeyFile file</primary>

                <secondary>function of</secondary>
              </indexterm>

              <indexterm>
                <primary>files</primary>

                <secondary>KeyFile</secondary>
              </indexterm>

              <indexterm>
                <primary>server encryption key</primary>
              </indexterm>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">KeyFile</emphasis></term>

            <listitem>
              <para>A machine-independent, binary-format file that lists the server encryption keys the AFS server processes use to
              encrypt and decrypt tickets. The information in this file is the basis for secure communication in the cell, and so is
              extremely sensitive. The file is specially protected so that only privileged users can read or change it.</para>

              <para>For instructions on maintaining this file, see <link linkend="HDRWQ355">Managing Server Encryption
              Keys</link>.</para>

              <indexterm>
                <primary>ThisCell file (server)</primary>
              </indexterm>

              <indexterm>
                <primary>files</primary>

                <secondary>ThisCell (server)</secondary>
              </indexterm>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">ThisCell</emphasis></term>

            <listitem>
              <para>An ASCII file that consists of a single line defining the complete Internet domain-style name of the cell (such
              as <computeroutput>example.com</computeroutput>). You create this file with the <emphasis role="bold">bos
              setcellname</emphasis> command during the installation of your cell's first file server machine, as instructed in the
              <emphasis>OpenAFS Quick Beginnings</emphasis>.</para>

              <para>Note that changing this file is only one step in changing your cell's name. For discussion, see <link
              linkend="HDRWQ34">Choosing a Cell Name</link>.</para>

              <indexterm>
                <primary>UserList file</primary>
              </indexterm>

              <indexterm>
                <primary>files</primary>

                <secondary>UserList</secondary>
              </indexterm>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">UserList</emphasis></term>

            <listitem>
              <para>An ASCII file that lists the usernames of the system administrators authorized to issue privileged <emphasis
              role="bold">bos</emphasis>, <emphasis role="bold">vos</emphasis>, and <emphasis role="bold">backup</emphasis>
              commands. For instructions on maintaining the file, see <link linkend="HDRWQ592">Administering the UserList
              File</link>.</para>
            </listitem>
          </varlistentry>
        </variablelist></para>

      <indexterm>
        <primary>usr/afs/local directory on server machines</primary>

        <secondary>contents listed</secondary>
      </indexterm>

      <indexterm>
        <primary>directory</primary>

        <secondary>/usr/afs/local on server machines</secondary>
      </indexterm>

      <indexterm>
        <primary>local configuration files (server)</primary>
      </indexterm>

      <indexterm>
        <primary>file server machine</primary>

        <secondary>configuration files in /usr/afs/local</secondary>
      </indexterm>
    </sect2>

    <sect2 id="HDRWQ86">
      <title>Local Configuration Files in the /usr/afs/local Directory</title>

      <para>The directory <emphasis role="bold">/usr/afs/local</emphasis> contains configuration files that are different for each
      file server machine in a cell. Thus, they are not updated automatically from a central source like the files in <emphasis
      role="bold">/usr/afs/bin</emphasis> and <emphasis role="bold">/usr/afs/etc</emphasis> directories. The most important file is
      the <emphasis role="bold">BosConfig</emphasis> file; it defines which server processes are to run on that machine.</para>

      <para>As with the common configuration files in <emphasis role="bold">/usr/afs/etc</emphasis>, you must not edit these files
      directly. Use commands from the <emphasis role="bold">bos</emphasis> command suite where appropriate; some files never need to
      be altered.</para>

      <para>The files in this directory include the following: <variablelist>
          <indexterm>
            <primary>BosConfig file</primary>
          </indexterm>

          <indexterm>
            <primary>files</primary>

            <secondary>BosConfig</secondary>
          </indexterm>

          <varlistentry>
            <term><emphasis role="bold">BosConfig</emphasis></term>

            <listitem>
              <para>This file lists the server processes to run on the server machine, by defining which processes the BOS Server
              monitors and what it does if the process fails. It also defines the times at which the BOS Server automatically
              restarts processes for maintenance purposes.</para>

              <para>As you create server processes during a file server machine's installation, their entries are defined in this
              file automatically. The <emphasis>OpenAFS Quick Beginnings</emphasis> outlines the <emphasis
              role="bold">bos</emphasis> commands to use. For a more complete description of the file, and instructions for
              controlling process status by editing the file with commands from the <emphasis role="bold">bos</emphasis> suite, see
              <link linkend="HDRWQ142">Monitoring and Controlling Server Processes</link>.</para>

              <indexterm>
                <primary>NetInfo file (server version)</primary>
              </indexterm>

              <indexterm>
                <primary>files</primary>

                <secondary>NetInfo (server version)</secondary>
              </indexterm>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">NetInfo</emphasis></term>

            <listitem>
              <para>This optional ASCII file lists one or more of the network interface addresses on the server machine. If it
              exists when the File Server initializes, the File Server uses it as the basis for the list of interfaces that it
              registers in its Volume Location Database (VLDB) server entry. See <link linkend="HDRWQ138">Managing Server IP
              Addresses and VLDB Server Entries</link>.</para>

              <indexterm>
                <primary>NetRestrict file (server version)</primary>
              </indexterm>

              <indexterm>
                <primary>files</primary>

                <secondary>NetRestrict (server version)</secondary>
              </indexterm>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">NetRestrict</emphasis></term>

            <listitem>
              <para>This optional ASCII file lists one or more network interface addresses. If it exists when the File Server
              initializes, the File Server removes the specified addresses from the list of interfaces that it registers in its VLDB
              server entry. See <link linkend="HDRWQ138">Managing Server IP Addresses and VLDB Server Entries</link>.</para>

              <indexterm>
                <primary>NoAuth file</primary>
              </indexterm>

              <indexterm>
                <primary>files</primary>

                <secondary>NoAuth</secondary>
              </indexterm>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">NoAuth</emphasis></term>

            <listitem>
              <para>This zero-length file instructs all AFS server processes running on the machine not to perform authorization
              checking. Thus, they perform any action for any user, even <emphasis role="bold">anonymous</emphasis>. This very
              insecure state is useful only in rare instances, mainly during the installation of the machine.</para>

              <para>The file is created automatically when you start the initial <emphasis role="bold">bosserver</emphasis> process
              with the <emphasis role="bold">-noauth</emphasis> flag, or issue the <emphasis role="bold">bos setauth</emphasis>
              command to turn off authentication requirements. When you use the <emphasis role="bold">bos setauth</emphasis> command
              to turn on authentication, the BOS Server removes this file. For more information, see <link
              linkend="HDRWQ123">Managing Authentication and Authorization Requirements</link>.</para>

              <indexterm>
                <primary>SALVAGE.fs file</primary>
              </indexterm>

              <indexterm>
                <primary>files</primary>

                <secondary>SALVAGE.fs</secondary>
              </indexterm>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">SALVAGE.fs</emphasis></term>

            <listitem>
              <para>This zero-length file controls how the BOS Server handles a crash of the File Server component of the <emphasis
              role="bold">fs</emphasis> process. The BOS Server creates this file each time it starts or restarts the <emphasis
              role="bold">fs</emphasis> process. If the file is present when the File Server crashes, then the BOS Server runs the
              Salvager before restarting the File Server and Volume Server again. When the File Server exits normally, the BOS
              Server removes the file so that the Salvager does not run.</para>

              <para>Do not create or remove this file yourself; the BOS Server does so automatically. If necessary, you can salvage
              a volume or partition by using the <emphasis role="bold">bos salvage</emphasis> command; see <link
              linkend="HDRWQ232">Salvaging Volumes</link>.</para>

              <indexterm>
                <primary>salvage.lock file</primary>
              </indexterm>

              <indexterm>
                <primary>files</primary>

                <secondary>salvage.lock</secondary>
              </indexterm>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">salvage.lock</emphasis></term>

            <listitem>
              <para>This file guarantees that only one Salvager process runs on a file server machine at a time (the single process
              can fork multiple subprocesses to salvage multiple partitions in parallel). As the Salvager initiates (when invoked by
              the BOS Server or by issue of the <emphasis role="bold">bos salvage</emphasis> command), it creates this zero-length
              file and issues the <emphasis role="bold">flock</emphasis> system call on it. It removes the file when it completes
              the salvage operation. Because the Salvager must lock the file in order to run, only one Salvager can run at a
              time.</para>

              <indexterm>
                <primary>sysid file</primary>
              </indexterm>

              <indexterm>
                <primary>files</primary>

                <secondary>sysid</secondary>
              </indexterm>

              <indexterm>
                <primary>File Server</primary>

                <secondary>interfaces registered in VLDB</secondary>

                <tertiary>listed in sysid file</tertiary>
              </indexterm>

              <indexterm>
                <primary>VLDB</primary>

                <secondary>server machine interfaces registered</secondary>

                <tertiary>listed in sysid file</tertiary>
              </indexterm>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">sysid</emphasis></term>

            <listitem>
              <para>This file records the network interface addresses that the File Server (<emphasis
              role="bold">fileserver</emphasis> process) registers in its VLDB server entry. When the Cache Manager requests volume
              location information, the Volume Location (VL) Server provides all of the interfaces registered for each server
              machine that houses the volume. This enables the Cache Manager to make use of multiple addresses when accessing AFS
              data stored on a multihomed file server machine. For further information, see <link linkend="HDRWQ138">Managing Server
              IP Addresses and VLDB Server Entries</link>.</para>
            </listitem>
          </varlistentry>
        </variablelist></para>

      <indexterm>
        <primary>usr/afs/db directory on server machines</primary>

        <secondary>contents listed</secondary>
      </indexterm>

      <indexterm>
        <primary>directory</primary>

        <secondary>/usr/afs/db on server machines</secondary>
      </indexterm>

      <indexterm>
        <primary>database files</primary>
      </indexterm>

      <indexterm>
        <primary>replicated database files</primary>
      </indexterm>

      <indexterm>
        <primary>log files</primary>

        <secondary>for replicated databases</secondary>
      </indexterm>

      <indexterm>
        <primary>file server machine</primary>

        <secondary>database files in /usr/afs/db</secondary>
      </indexterm>
    </sect2>

    <sect2 id="HDRWQ87">
      <title>Replicated Database Files in the /usr/afs/db Directory</title>

      <para>The directory <emphasis role="bold">/usr/afs/db</emphasis> contains two types of files pertaining to the four replicated
      databases in the cell--the Authentication Database, Backup Database, Protection Database, and Volume Location Database (VLDB):
      <itemizedlist>
          <listitem>
            <para>A file that contains each database, with a <emphasis role="bold">.DB0</emphasis> extension.</para>
          </listitem>

          <listitem>
            <para>A log file for each database, with a <emphasis role="bold">.DBSYS1</emphasis> extension. The database server
            process logs each database operation in this file before performing it. If the operation is interrupted, the process
            consults this file to learn how to finish it.</para>
          </listitem>
        </itemizedlist></para>

      <para>Each database server process (Authentication, Backup, Protection, or VL Server) maintains its own database and log
      files. The database files are in binary format, so you must always access or alter them using commands from the <emphasis
      role="bold">kas</emphasis> suite (for the Authentication Database), <emphasis role="bold">backup</emphasis> suite (for the
      Backup Database), <emphasis role="bold">pts</emphasis> suite (for the Protection Database), or <emphasis
      role="bold">vos</emphasis> suite (for the VLDB).</para>

      <para>If a cell runs more than one database server machine, each database server process keeps its own copy of its database on
      its machine's hard disk. However, it is important that all the copies of a given database are the same. To synchronize them,
      the database server processes call on AFS's distributed database technology, Ubik, as described in <link
      linkend="HDRWQ102">Replicating the OpenAFS Administrative Databases</link>.</para>

      <para>The files listed here appear in this directory only on database server machines. On non-database server machines, this
      directory is empty. <variablelist>
          <indexterm>
            <primary>files</primary>

            <secondary>bdb.DB0</secondary>
          </indexterm>

          <indexterm>
            <primary>bdb.DB0 file</primary>
          </indexterm>

          <varlistentry>
            <term><emphasis role="bold">bdb.DB0</emphasis></term>

            <listitem>
              <para>The Backup Database file.</para>

              <indexterm>
                <primary>files</primary>

                <secondary>bdb.DBSYS1</secondary>
              </indexterm>

              <indexterm>
                <primary>bdb.DBSYS1 file</primary>
              </indexterm>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">bdb.DBSYS1</emphasis></term>

            <listitem>
              <para>The Backup Database log file.</para>

              <indexterm>
                <primary>files</primary>

                <secondary>kaserver.DB0</secondary>
              </indexterm>

              <indexterm>
                <primary>kaserver.DB0 file</primary>
              </indexterm>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">kaserver.DB0</emphasis></term>

            <listitem>
              <para>The Authentication Database file.</para>

              <indexterm>
                <primary>files</primary>

                <secondary>kaserver.DBSYS1</secondary>
              </indexterm>

              <indexterm>
                <primary>kaserver.DBSYS1 file</primary>
              </indexterm>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">kaserver.DBSYS1</emphasis></term>

            <listitem>
              <para>The Authentication Database log file.</para>

              <indexterm>
                <primary>files</primary>

                <secondary>prdb.DB0</secondary>
              </indexterm>

              <indexterm>
                <primary>prdb.DB0 file</primary>
              </indexterm>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">prdb.DB0</emphasis></term>

            <listitem>
              <para>The Protection Database file.</para>

              <indexterm>
                <primary>files</primary>

                <secondary>prdb.DBSYS1</secondary>
              </indexterm>

              <indexterm>
                <primary>prdb.DBSYS1 file</primary>
              </indexterm>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">prdb.DBSYS1</emphasis></term>

            <listitem>
              <para>The Protection Database log file.</para>

              <indexterm>
                <primary>files</primary>

                <secondary>vldb.DB0</secondary>
              </indexterm>

              <indexterm>
                <primary>vldb.DB0 file</primary>
              </indexterm>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">vldb.DB0</emphasis></term>

            <listitem>
              <para>The Volume Location Database file.</para>

              <indexterm>
                <primary>files</primary>

                <secondary>vldb.DBSYS1</secondary>
              </indexterm>

              <indexterm>
                <primary>vldb.DBSYS1 file</primary>
              </indexterm>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">vldb.DBSYS1</emphasis></term>

            <listitem>
              <para>The Volume Location Database log file.</para>
            </listitem>
          </varlistentry>
        </variablelist></para>

      <indexterm>
        <primary>usr/afs/logs directory on server machines</primary>

        <secondary>contents listed</secondary>
      </indexterm>

      <indexterm>
        <primary>directory</primary>

        <secondary>/usr/afs/logs on server machines</secondary>
      </indexterm>

      <indexterm>
        <primary>file server machine</primary>

        <secondary>core files in /usr/afs/logs</secondary>
      </indexterm>

      <indexterm>
        <primary>file server machine</primary>

        <secondary>log files in /usr/afs/logs</secondary>
      </indexterm>

      <indexterm>
        <primary>log files</primary>

        <secondary>for server processes</secondary>
      </indexterm>

      <indexterm>
        <primary>core files</primary>

        <secondary>for server processes</secondary>
      </indexterm>
    </sect2>

    <sect2 id="HDRWQ88">
      <title>Log Files in the /usr/afs/logs Directory</title>

      <para>The <emphasis role="bold">/usr/afs/logs</emphasis> directory contains log files from various server processes. The files
      detail interesting events that occur during normal operations. For instance, the Volume Server can record volume moves in the
      <emphasis role="bold">VolserLog</emphasis> file. Events are recorded at completion, so the server processes do not use these
      files to reconstruct failed operations unlike the ones in the <emphasis role="bold">/usr/afs/db</emphasis> directory.</para>

      <para>The information in log files can be very useful as you evaluate process failures and other problems. For instance, if
      you receive a timeout message when you try to access a volume, checking the <emphasis role="bold">FileLog</emphasis> file
      possibly provides an explanation, showing that the File Server was unable to attach the volume. To examine a log file
      remotely, use the <emphasis role="bold">bos getlog</emphasis> command as described in <link linkend="HDRWQ173">Displaying
      Server Process Log Files</link>.</para>

      <para>This directory also contains the core image files generated if a process being monitored by the BOS Server crashes. The
      BOS Server attempts to add an extension to the standard <emphasis role="bold">core</emphasis> name to indicate which process
      generated the core file (for example, naming a core file generated by the Protection Server <emphasis
      role="bold">core.ptserver</emphasis>). The BOS Server cannot always assign the correct extension if two processes fail at
      about the same time, so it is not guaranteed to be correct.</para>

      <para>The directory contains the following files: <variablelist>
          <indexterm>
            <primary>AuthLog file</primary>
          </indexterm>

          <indexterm>
            <primary>files</primary>

            <secondary>AuthLog</secondary>
          </indexterm>

          <varlistentry>
            <term><emphasis role="bold">AuthLog</emphasis></term>

            <listitem>
              <para>The Authentication Server's log file.</para>

              <indexterm>
                <primary>BackupLog file</primary>
              </indexterm>

              <indexterm>
                <primary>files</primary>

                <secondary>BackupLog</secondary>
              </indexterm>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">BackupLog</emphasis></term>

            <listitem>
              <para>The Backup Server's log file.</para>

              <indexterm>
                <primary>BosLog file</primary>
              </indexterm>

              <indexterm>
                <primary>files</primary>

                <secondary>BosLog</secondary>
              </indexterm>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">BosLog</emphasis></term>

            <listitem>
              <para>The BOS Server's log file.</para>

              <indexterm>
                <primary>files</primary>

                <secondary>FileLog</secondary>
              </indexterm>

              <indexterm>
                <primary>FileLog file</primary>
              </indexterm>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">FileLog</emphasis></term>

            <listitem>
              <para>The File Server's log file.</para>

              <indexterm>
                <primary>files</primary>

                <secondary>SalvageLog</secondary>
              </indexterm>

              <indexterm>
                <primary>SalvageLog file</primary>
              </indexterm>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">SalvageLog</emphasis></term>

            <listitem>
              <para>The Salvager's log file.</para>

              <indexterm>
                <primary>VLLog file</primary>
              </indexterm>

              <indexterm>
                <primary>files</primary>

                <secondary>VLLog</secondary>
              </indexterm>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">VLLog</emphasis></term>

            <listitem>
              <para>The Volume Location (VL) Server's log file.</para>

              <indexterm>
                <primary>VolserLog file</primary>
              </indexterm>

              <indexterm>
                <primary>files</primary>

                <secondary>VolserLog</secondary>
              </indexterm>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">VolserLog</emphasis></term>

            <listitem>
              <para>The Volume Server's log file.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">core.process</emphasis></term>

            <listitem>
              <para>If present, a core image file produced as an AFS server process on the machine crashed (probably the process
              named by process).</para>
            </listitem>
          </varlistentry>
        </variablelist></para>

      <note>
        <para>To prevent log files from growing unmanageably large, restart the server processes periodically, particularly the
        database server processes. To avoid restarting the processes, use the UNIX <emphasis role="bold">rm</emphasis> command to
        remove the file as the process runs; it re-creates it automatically.</para>
      </note>

      <indexterm>
        <primary>vicep directory on server machines</primary>

        <secondary>contents listed</secondary>
      </indexterm>

      <indexterm>
        <primary>directory</primary>

        <secondary>/vicep on server machines</secondary>
      </indexterm>

      <indexterm>
        <primary>volume header</primary>

        <secondary>in /vicep directories</secondary>
      </indexterm>

      <indexterm>
        <primary>partition</primary>

        <secondary>housing AFS volumes</secondary>
      </indexterm>

      <indexterm>
        <primary>file server machine</primary>

        <secondary>partitions, naming</secondary>
      </indexterm>
    </sect2>

    <sect2 id="HDRWQ89">
      <title>Volume Headers on Server Partitions</title>

      <para>A partition that houses AFS volumes must be mounted at a subdirectory of the machine's root ( / ) directory (not, for
      instance under the <emphasis role="bold">/usr</emphasis> directory). The file server machine's file system registry file
      (<emphasis role="bold">/etc/fstab</emphasis> or equivalent) must correctly map the directory name and the partition's device
      name. The directory name is of the form <emphasis role="bold">/vicep</emphasis>index, where each index is one or two lowercase
      letters. By convention, the first AFS partition on a machine is mounted at <emphasis role="bold">/vicepa</emphasis>, the
      second at <emphasis role="bold">/vicepb</emphasis>, and so on. If there are more than 26 partitions, continue with <emphasis
      role="bold">/vicepaa</emphasis>, <emphasis role="bold">/vicepab</emphasis> and so on. The <emphasis>OpenAFS Release
      Notes</emphasis> specifies the number of supported partitions per server machine.</para>

      <para>Do not store non-AFS files on AFS partitions. The File Server and Volume Server expect to have available all of the
      space on the partition.</para>

      <para>The <emphasis role="bold">/vicep</emphasis> directories contain two types of files: <variablelist>
          <indexterm>
            <primary>V.<emphasis>vol_ID</emphasis>.vol file</primary>
          </indexterm>

          <indexterm>
            <primary>files</primary>

            <secondary>V.<emphasis>vol_ID</emphasis>.vol</secondary>
          </indexterm>

          <varlistentry>
            <term><emphasis role="bold">Vvol_ID.vol</emphasis></term>

            <listitem>
              <para>Each such file is a volume header. The vol_ID corresponds to the volume ID number displayed in the output from
              the <emphasis role="bold">vos examine</emphasis>, <emphasis role="bold">vos listvldb</emphasis>, and <emphasis
              role="bold">vos listvol</emphasis> commands.</para>

              <indexterm>
                <primary>FORCESALVAGE file</primary>
              </indexterm>

              <indexterm>
                <primary>files</primary>

                <secondary>FORCESALVAGE</secondary>
              </indexterm>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><emphasis role="bold">FORCESALVAGE</emphasis></term>

            <listitem>
              <para>This zero-length file triggers the Salvager to salvage the entire partition. The AFS-modified version of the
              <emphasis role="bold">fsck</emphasis> program creates this file if it discovers corruption.</para>
            </listitem>
          </varlistentry>
        </variablelist></para>

      <note>
        <para>For most system types, it is important never to run the standard <emphasis role="bold">fsck</emphasis> program
        provided with the operating system on an AFS file server machine. It removes all AFS volume data from server partitions
        because it does not recognize their format.</para>
      </note>

      <indexterm>
        <primary>roles for server machine</primary>
      </indexterm>

      <indexterm>
        <primary>server machine</primary>

        <secondary>roles summarized</secondary>
      </indexterm>
    </sect2>
  </sect1>

  <sect1 id="HDRWQ90">
    <title>The Four Roles for File Server Machines</title>

    <para>In cells that have more than one server machine, not all server machines have to perform exactly the same functions. The
    are four possible <emphasis>roles</emphasis> a machine can assume, determined by which server processes it is running. A machine
    can assume more than one role by running all of the relevant processes. The following list summarizes the four roles, which are
    described more completely in subsequent sections. <itemizedlist>
        <listitem>
          <para>A <emphasis>simple file server</emphasis> machine runs only the processes that store and deliver AFS files to client
          machines. You can run as many simple file server machines as you need to satisfy your cell's performance and disk space
          requirements.</para>
        </listitem>

        <listitem>
          <para>A <emphasis>database server machine</emphasis> runs the four database server processes that maintain AFS's
          replicated administrative databases: the Authentication, Backup, Protection, and Volume Location (VL) Server
          processes.</para>
        </listitem>

        <listitem>
          <para>A <emphasis>binary distribution machine</emphasis> distributes the AFS server binaries for its system type to all
          other server machines of that system type.</para>
        </listitem>

        <listitem>
          <para>The single <emphasis>system control machine</emphasis> distributes common server configuration files to all other
          server machines in the cell.</para>
        </listitem>
      </itemizedlist></para>

    <para>If a cell has a single server machine, it assumes the simple file server and database server roles. The instructions in
    the <emphasis>OpenAFS Quick Beginnings</emphasis> also have you configure it as the system control machine and binary
    distribution machine for its system type, but it does not actually perform those functions until you install another server
    machine.</para>

    <para>It is best to keep the binaries for all of the AFS server processes in the <emphasis role="bold">/usr/afs/bin</emphasis>
    directory, even if not all processes are running. You can then change which roles a machine assumes simply by starting or
    stopping the processes that define the role.</para>

    <indexterm>
      <primary>simple file server machine</primary>
    </indexterm>

    <indexterm>
      <primary>server machine</primary>

      <secondary>simple file server role</secondary>
    </indexterm>

    <sect2 id="HDRWQ91">
      <title>Simple File Server Machines</title>

      <para>A <emphasis>simple file server machine</emphasis> runs only the server processes that store and deliver AFS files to
      client machines, monitor process status, and pick up binaries and configuration files from the cell's binary distribution and
      system control machines.</para>

      <para>In general, only cells with more than three server machines need to run simple file server machines. In cells with three
      or fewer machines, all of them are usually database server machines (to benefit from replicating the administrative
      databases); see <link linkend="HDRWQ92">Database Server Machines</link>.</para>

      <para>The following processes run on a simple file server machine: <itemizedlist>
          <listitem>
            <para>The BOS Server (<emphasis role="bold">bosserver</emphasis> process)</para>
          </listitem>

          <listitem>
            <para>The <emphasis role="bold">fs</emphasis> process, which combines the File Server, Volume Server, and Salvager
            processes so that they can coordinate their operations on the data in volumes and avoid the inconsistencies that can
            result from multiple simultaneous operations on the same data</para>
          </listitem>

          <listitem>
            <para>A client portion of the Update Server that picks up binary files from the binary distribution machine of its AFS
            system type (the <emphasis role="bold">upclientbin</emphasis> process)</para>
          </listitem>

          <listitem>
            <para>A client portion of the Update Server that picks up common configuration files from the system control machine
            (the <emphasis role="bold">upclientetc</emphasis> process)</para>
          </listitem>
        </itemizedlist></para>

      <indexterm>
        <primary>database server machine</primary>

        <secondary>defined</secondary>
      </indexterm>

      <indexterm>
        <primary>server machine</primary>

        <secondary>database server role</secondary>
      </indexterm>

      <indexterm>
        <primary>Backup Server</primary>

        <secondary>runs on database server machine</secondary>
      </indexterm>

      <indexterm>
        <primary>Authentication Server</primary>

        <secondary>runs on database server machine</secondary>
      </indexterm>

      <indexterm>
        <primary>Protection Server</primary>

        <secondary>runs on database server machine</secondary>
      </indexterm>

      <indexterm>
        <primary>VL Server</primary>

        <secondary>runs on database server machine</secondary>
      </indexterm>
    </sect2>

    <sect2 id="HDRWQ92">
      <title>Database Server Machines</title>

      <para>A <emphasis>database server machine</emphasis> runs the four processes that maintain the AFS replicated administrative
      databases: the Authentication Server, Backup Server, Protection Server, and Volume Location (VL) Server, which maintain the
      Authentication Database, Backup Database, Protection Database, and Volume Location Database (VLDB), respectively. To review
      the functions of these server processes and their databases, see <link linkend="HDRWQ17">AFS Server Processes and the Cache
      Manager</link>.</para>

      <para>If a cell has more than one server machine, it is best to run more than one database server machine, but more than three
      are rarely necessary. Replicating the databases in this way yields the same benefits as replicating volumes: increased
      availability and reliability of information. If one database server machine or process goes down, the information in the
      database is still available from others. The load of requests for database information is spread across multiple machines,
      preventing any one from becoming overloaded.</para>

      <para>Unlike replicated volumes, however, replicated databases do change frequently. Consistent system performance demands
      that all copies of the database always be identical, so it is not possible to record changes in only some of them. To
      synchronize the copies of a database, the database server processes use AFS's distributed database technology, Ubik. See <link
      linkend="HDRWQ102">Replicating the OpenAFS Administrative Databases</link>.</para>

      <para>It is critical that the AFS server processes on every server machine in a cell know which machines are the database
      server machines. The database server processes in particular must maintain constant contact with their peers in order to
      coordinate the copies of the database. The other server processes often need information from the databases. Every file server
      machine keeps a list of its cell's database server machines in its local <emphasis
      role="bold">/usr/afs/etc/CellServDB</emphasis> file. Cells that use the States edition of AFS can use the system control
      machine to distribute this file (see <link linkend="HDRWQ94">The System Control Machine</link>).</para>

      <para>The following processes define a database server machine: <itemizedlist>
          <listitem>
            <para>The Authentication Server (<emphasis role="bold">kaserver</emphasis> process)</para>
          </listitem>

          <listitem>
            <para>The Backup Server (<emphasis role="bold">buserver</emphasis> process)</para>
          </listitem>

          <listitem>
            <para>The Protection Server (<emphasis role="bold">ptserver</emphasis> process)</para>
          </listitem>

          <listitem>
            <para>The VL Server (<emphasis role="bold">vlserver</emphasis> process)</para>
          </listitem>
        </itemizedlist></para>

      <para>Database server machines can also run the processes that define a simple file server machine, as listed in <link
      linkend="HDRWQ91">Simple File Server Machines</link>. One database server machine can act as the cell's system control
      machine, and any database server machine can serve as the binary distribution machine for its system type; see <link
      linkend="HDRWQ94">The System Control Machine</link> and <link linkend="HDRWQ93">Binary Distribution Machines</link>.</para>

      <indexterm>
        <primary>binary distribution machine</primary>

        <secondary>defined</secondary>
      </indexterm>

      <indexterm>
        <primary>server machine</primary>

        <secondary>binary distribution role</secondary>
      </indexterm>

      <indexterm>
        <primary>Update Server</primary>

        <secondary>server portion</secondary>

        <tertiary>on binary distribution machine</tertiary>
      </indexterm>

      <indexterm>
        <primary>Update Server</primary>

        <secondary>client portion</secondary>

        <tertiary>for binaries</tertiary>
      </indexterm>
    </sect2>

    <sect2 id="HDRWQ93">
      <title>Binary Distribution Machines</title>

      <para>A <emphasis>binary distribution machine</emphasis> stores and distributes the binary files for the AFS processes and
      command suites to all other server machines of its system type. Each file server machine keeps its own copy of AFS server
      process binaries on its local disk, by convention in the <emphasis role="bold">/usr/afs/bin</emphasis> directory. For
      consistent system performance, however, all server machines must run the same version (build level) of a process. For
      instructions for checking a binary's build level, see <link linkend="HDRWQ117">Displaying A Binary File's Build Level</link>.
      The easiest way to keep the binaries consistent is to have a binary distribution machine of each system type distribute them
      to its system-type peers.</para>

      <para>The process that defines a binary distribution machine is the server portion of the Update Server (<emphasis
      role="bold">upserver</emphasis> process). The client portion of the Update Server (<emphasis
      role="bold">upclientbin</emphasis> process) runs on the other server machines of that system type and references the binary
      distribution machine.</para>

      <para>Binary distribution machines usually also run the processes that define a simple file server machine, as listed in <link
      linkend="HDRWQ91">Simple File Server Machines</link>. One binary distribution machine can act as the cell's system control
      machine, and any binary distribution machine can serve as a database server machine; see <link linkend="HDRWQ94">The System
      Control Machine</link> and <link linkend="HDRWQ92">Database Server Machines</link>.</para>

      <indexterm>
        <primary>system control machine</primary>
      </indexterm>

      <indexterm>
        <primary>configuration files</primary>

        <secondary>server machine, common</secondary>
      </indexterm>

      <indexterm>
        <primary>server machine</primary>

        <secondary>system control role</secondary>
      </indexterm>
    </sect2>

    <sect2 id="HDRWQ94">
      <title>The System Control Machine</title>

      <para>The <emphasis>system control machine</emphasis> stores and
      distributes system configuration files shared by all of the server machines in the cell. Each file server machine keeps its
      own copy of the configuration files on its local disk, by convention in the <emphasis role="bold">/usr/afs/etc</emphasis>
      directory. For consistent system performance, however, all server machines must use the same files. The easiest way to keep
      the files consistent is to have the system control machine distribute them. You make changes only to the copy stored on the
      system control machine, as directed by the instructions in this document.</para>

      <para>For a list of the configuration files stored in the <emphasis role="bold">/usr/afs/etc</emphasis> directory, see <link
      linkend="HDRWQ85">Common Configuration Files in the /usr/afs/etc Directory</link>.</para>

      <para>The <emphasis>OpenAFS Quick Beginnings</emphasis> configures a cell's first server machine as the system control
      machine. If you wish, you can reassign the role to a different machine that you install later, but you must then change the
      client portion of the Update Server (<emphasis role="bold">upclientetc</emphasis>) process running on all other server
      machines to refer to the new system control machine.</para>

      <para>The following processes define the system control machine: <itemizedlist>
          <indexterm>
            <primary>Update Server</primary>

            <secondary>server portion</secondary>

            <tertiary>on system control machine</tertiary>
          </indexterm>

          <indexterm>
            <primary>Update Server</primary>

            <secondary>client portion</secondary>

            <tertiary>for configuration files</tertiary>
          </indexterm>

          <listitem>
            <para>The server portion of the Update Server (<emphasis role="bold">upserver</emphasis>) process
            The client portion of the Update Server (<emphasis role="bold">upclientetc</emphasis>
            process) runs on the other server machines and references the system control machine.</para>
          </listitem>
        </itemizedlist></para>

      <para>The system control machine can also run the processes that define a simple file server machine, as listed in <link
      linkend="HDRWQ91">Simple File Server Machines</link>. It can also server as a database server machine, and by convention acts
      as the binary distribution machine for its system type. A single <emphasis role="bold">upserver</emphasis> process can
      distribute both configuration files and binaries. See <link linkend="HDRWQ92">Database Server Machines</link> and <link
      linkend="HDRWQ93">Binary Distribution Machines</link>.</para>

      <indexterm>
        <primary>determining</primary>

        <secondary>roles taken by server machine</secondary>
      </indexterm>

      <indexterm>
        <primary>identifying</primary>

        <secondary>roles taken by server machine</secondary>
      </indexterm>

      <indexterm>
        <primary>server machine</primary>

        <secondary>determining roles</secondary>
      </indexterm>

      <indexterm>
        <primary>roles for server machine</primary>

        <secondary>determining</secondary>
      </indexterm>

      <indexterm>
        <primary>database server machine</primary>

        <secondary>identifying with bos status</secondary>
      </indexterm>

      <indexterm>
        <primary>determining</primary>

        <secondary>identity of database server machines</secondary>
      </indexterm>

      <indexterm>
        <primary>identifying</primary>

        <secondary>database server machine</secondary>
      </indexterm>
    </sect2>

    <sect2 id="HDRWQ95">
      <title>To locate database server machines</title>

      <orderedlist>
        <listitem>
          <para>Issue the <emphasis role="bold">bos listhosts</emphasis> command. <programlisting>
   % <emphasis role="bold">bos listhosts</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
</programlisting></para>

          <para>The machines listed in the output are the cell's database server machines. For complete instructions and example
          output, see <link linkend="HDRWQ120">To display a cell's database server machines</link>.</para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">(Optional)</emphasis> Issue the <emphasis role="bold">bos status</emphasis> command to verify
          that a machine listed in the output of the <emphasis role="bold">bos listhosts</emphasis> command is actually running the
          processes that define it as a database server machine. For complete instructions, see <link linkend="HDRWQ158">Displaying
          Process Status and Information from the BosConfig File</link>. <programlisting>
   % <emphasis role="bold">bos status</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">buserver kaserver ptserver vlserver</emphasis>
</programlisting></para>

          <para>If the specified machine is a database server machine, the output from the <emphasis role="bold">bos
          status</emphasis> command includes the following lines:</para>

          <programlisting>
   Instance buserver, currently running normally.
   Instance kaserver, currently running normally.
   Instance ptserver, currently running normally.
   Instance vlserver, currently running normally.
</programlisting>
        </listitem>
      </orderedlist>

      <indexterm>
        <primary>system control machine</primary>

        <secondary>identifying with bos status</secondary>
      </indexterm>

      <indexterm>
        <primary>determining</primary>

        <secondary>identity of system control machine</secondary>
      </indexterm>

      <indexterm>
        <primary>identifying</primary>

        <secondary>system control machine</secondary>
      </indexterm>
    </sect2>

    <sect2 id="HDRWQ96">
      <title>To locate the system control machine</title>

      <orderedlist>
        <listitem>
          <para>Issue the <emphasis role="bold">bos status</emphasis> command for any server machine. Complete instructions appear
          in <link linkend="HDRWQ158">Displaying Process Status and Information from the BosConfig File</link>. <programlisting>
   % <emphasis role="bold">bos status</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">upserver upclientbin upclientetc</emphasis> <emphasis
                role="bold">-long</emphasis>
</programlisting></para>

          <para>The output you see depends on the machine you have contacted: a simple file server machine, the system control
          machine, or a binary distribution machine. See <link linkend="HDRWQ98">Interpreting the Output from the bos status
          Command</link>.</para>
        </listitem>
      </orderedlist>

      <indexterm>
        <primary>binary distribution machine</primary>

        <secondary>identifying with bos status</secondary>
      </indexterm>

      <indexterm>
        <primary>determining</primary>

        <secondary>identity of binary distribution machine</secondary>
      </indexterm>

      <indexterm>
        <primary>identifying</primary>

        <secondary>binary distribution machine</secondary>
      </indexterm>
    </sect2>

    <sect2 id="HDRWQ97">
      <title>To locate the binary distribution machine for a system type</title>

      <orderedlist>
        <listitem>
          <para>Issue the <emphasis role="bold">bos status</emphasis> command for a file server machine of the system type you are
          checking (to determine a machine's system type, issue the <emphasis role="bold">fs sysname</emphasis> or <emphasis
          role="bold">sys</emphasis> command as described in <link linkend="HDRWQ417">Displaying and Setting the System Type
          Name</link>. Complete instructions for the <emphasis role="bold">bos status</emphasis> command appear in <link
          linkend="HDRWQ158">Displaying Process Status and Information from the BosConfig File</link>. <programlisting>
   % <emphasis role="bold">bos status</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">upserver upclientbin upclientetc -long</emphasis>
</programlisting></para>

          <para>The output you see depends on the machine you have contacted: a simple file server machine, the system control
          machine, or a binary distribution machine. See <link linkend="HDRWQ98">Interpreting the Output from the bos status
          Command</link>.</para>
        </listitem>
      </orderedlist>

      <indexterm>
        <primary>simple file server machine</primary>

        <secondary>identifying with bos status</secondary>
      </indexterm>

      <indexterm>
        <primary>determining</primary>

        <secondary>identity of:</secondary>

        <tertiary>simple file server machines</tertiary>
      </indexterm>

      <indexterm>
        <primary>identifying</primary>

        <secondary>simple file server machine</secondary>
      </indexterm>
    </sect2>

    <sect2 id="HDRWQ98">
      <title>Interpreting the Output from the bos status Command</title>

      <para>Interpreting the output of the <emphasis role="bold">bos status</emphasis> command is most straightforward for a simple
      file server machine. There is no <emphasis role="bold">upserver</emphasis> process, so the output includes the following
      message:</para>

      <programlisting>
   bos: failed to get instance info for 'upserver' (no such entity)
</programlisting>

      <para>A simple file server machine runs the <emphasis role="bold">upclientbin</emphasis> process, so the output includes a
      message like the following. It indicates that <emphasis role="bold">fs7.example.com</emphasis> is the binary distribution machine
      for this system type.</para>

      <programlisting>
   Instance upclientbin, (type is simple) currently running normally.
   Process last started at Wed Mar 10  23:37:09 1999 (1 proc start)
   Command 1 is '/usr/afs/bin/upclient fs7.example.com -t 60 /usr/afs/bin'
</programlisting>

      <para>A simple file server machine also runs the <emphasis
      role="bold">upclientetc</emphasis> process, so the output includes a message like the following. It indicates that <emphasis
      role="bold">fs1.example.com</emphasis> is the system control machine.</para>

      <programlisting>
   Instance upclientetc, (type is simple) currently running normally.
   Process last started at Mon Mar 22  05:23:49 1999 (1 proc start)
   Command 1 is '/usr/afs/bin/upclient fs1.example.com -t 60 /usr/afs/etc'
</programlisting>

      <sect3 id="HDRWQ99">
        <title>The Output on the System Control Machine</title>

        <para>If you have issued the <emphasis role="bold">bos status</emphasis> command
        for the system control machine, the output includes an entry for the <emphasis role="bold">upserver</emphasis> process
        similar to the following:</para>

        <programlisting>
   Instance upserver, (type is simple) currently running normally.
   Process last started at Mon Mar 22 05:23:54 1999 (1 proc start)
   Command 1 is '/usr/afs/bin/upserver'
</programlisting>

        <para>If you are using the default configuration recommended in the <emphasis>OpenAFS Quick Beginnings</emphasis>, the
        system control machine is also the binary distribution machine for its system type, and a single <emphasis
        role="bold">upserver</emphasis> process distributes both kinds of updates. In that case, the output includes the following
        messages:</para>

        <programlisting>
   bos: failed to get instance info for 'upclientbin' (no such entity)
   bos: failed to get instance info for 'upclientetc' (no such entity)
</programlisting>

        <para>If the system control machine is not a binary distribution machine, the output includes an error message for the
        <emphasis role="bold">upclientetc</emphasis> process, but a complete a listing for the <emphasis
        role="bold">upclientbin</emphasis> process (in this case it refers to the machine <emphasis
        role="bold">fs5.example.com</emphasis> as the binary distribution machine):</para>

        <programlisting>
   Instance upclientbin, (type is simple) currently running normally.
   Process last started at Mon Mar 22  05:23:49 1999 (1 proc start)
   Command 1 is '/usr/afs/bin/upclient fs5.example.com -t 60 /usr/afs/bin'
   bos: failed to get instance info for 'upclientetc' (no such entity)
</programlisting>
      </sect3>

      <sect3 id="HDRWQ100">
        <title>The Output on a Binary Distribution Machine</title>

        <para>If you have issued the <emphasis role="bold">bos status</emphasis> command for a binary distribution machine, the
        output includes an entry for the <emphasis role="bold">upserver</emphasis> process similar to the following and error
        message for the <emphasis role="bold">upclientbin</emphasis> process:</para>

        <programlisting>
   Instance upserver, (type is simple) currently running normally.
   Process last started at Mon Apr 5 05:23:54 1999 (1 proc start)
   Command 1 is '/usr/afs/bin/upserver'
   bos: failed to get instance info for 'upclientbin' (no such entity)
</programlisting>

        <para>Unless this machine also happens to be the system control machine, a message like the following references the system
        control machine (in this case, <emphasis role="bold">fs3.example.com</emphasis>):</para>

        <programlisting>
   Instance upclientetc, (type is simple) currently running normally.
   Process last started at Mon Apr 5 05:23:49 1999 (1 proc start)
   Command 1 is '/usr/afs/bin/upclient fs3.example.com -t 60 /usr/afs/etc'
</programlisting>
      </sect3>
    </sect2>
  </sect1>

  <sect1 id="HDRWQ101">
    <title>Administering Database Server Machines</title>

    <para>This section explains how to administer database server machines. For installation instructions, see the <emphasis>OpenAFS
    Quick Beginnings</emphasis>.</para>

    <indexterm>
      <primary>distribution</primary>

      <secondary>of databases</secondary>
    </indexterm>

    <indexterm>
      <primary>database, distributed</primary>

      <secondary></secondary>

      <see>administrative database</see>
    </indexterm>

    <indexterm>
      <primary>distributed database</primary>

      <secondary></secondary>

      <see>administrative database</see>
    </indexterm>

    <indexterm>
      <primary>administrative database</primary>

      <secondary>about replicating</secondary>
    </indexterm>

    <indexterm>
      <primary>database server machine</primary>

      <secondary>maintaining</secondary>
    </indexterm>

    <indexterm>
      <primary>Ubik</primary>

      <secondary>operation described</secondary>
    </indexterm>

    <indexterm>
      <primary>synchronization site (Ubik)</primary>

      <secondary>defined</secondary>
    </indexterm>

    <indexterm>
      <primary>secondary site (Ubik)</primary>
    </indexterm>

    <indexterm>
      <primary>coordinator (Ubik)</primary>

      <secondary>defined</secondary>
    </indexterm>

    <indexterm>
      <primary>Ubik</primary>

      <secondary>automatic updates</secondary>
    </indexterm>

    <indexterm>
      <primary>automatic</primary>

      <secondary>update to admin. databases by Ubik</secondary>
    </indexterm>

    <sect2 id="HDRWQ102">
      <title>Replicating the OpenAFS Administrative Databases</title>

      <para>There are several benefits to replicating the AFS administrative databases (the Authentication, Backup, Protection, and
      Volume Location Databases), as discussed in <link linkend="HDRWQ52">Replicating the OpenAFS Administrative Databases</link>. For
      correct cell functioning, the copies of each database must be identical at all times. To keep the databases synchronized, AFS
      uses library of utilities called <emphasis>Ubik</emphasis>. Each database server process runs an associated lightweight Ubik
      process, and client-side programs call Ubik's client-side subroutines when they submit requests to read and change the
      databases.</para>

      <para>Ubik is designed to work with minimal administrator intervention, but there are several configuration requirements, as
      detailed in <link linkend="HDRWQ103">Configuring the Cell for Proper Ubik Operation</link>. The following brief overview of
      Ubik's operation is helpful for understanding the requirements. For more details, see <link linkend="HDRWQ104">How Ubik
      Operates Automatically</link>.</para>

      <para>Ubik is designed to distribute changes made in an AFS administrative database to all copies as quickly as possible. Only
      one copy of the database, the <emphasis>synchronization site</emphasis>, accepts change requests from clients; the lightweight
      Ubik process running there is the <emphasis>Ubik coordinator</emphasis>. To maintain maximum availability, there is a separate
      Ubik coordinator for each database, and the synchronization site for each of the four databases can be on a different machine.
      The synchronization site for a database can also move from machine to machine in response to process, machine, or network
      outages.</para>

      <para>The other copies of a database, and the Ubik processes that maintain them, are termed <emphasis>secondary</emphasis>.
      The secondary sites do not accept database changes directly from client-side programs, but only from the synchronization
      site.</para>

      <para>After the Ubik coordinator records a change in its copy of a database, it immediately sends the change to the secondary
      sites. During the brief distribution period, clients cannot access any of the copies of the database, even for reading. If the
      coordinator cannot reach a majority of the secondary sites, it halts the distribution and informs the client that the
      attempted change failed.</para>

      <para>To avoid distribution failures, the Ubik processes maintain constant contact by exchanging time-stamped messages. As
      long as a majority of the secondary sites respond to the coordinator's messages, there is a <emphasis>quorum</emphasis> of
      sites that are synchronized with the coordinator. If a process, machine, or network outage breaks the quorum, the Ubik
      processes attempt to elect a new coordinator in order to establish a new quorum among the highest possible number of sites.
      See <link linkend="HDRWQ106">A Flexible Coordinator Boosts Availability</link>.</para>

      <indexterm>
        <primary>Ubik</primary>

        <secondary>requirements summarized</secondary>
      </indexterm>

      <indexterm>
        <primary>database server process</primary>

        <secondary>need to run all on every database server machine</secondary>
      </indexterm>

      <indexterm>
        <primary>CellServDB file (server)</primary>

        <secondary>importance to Ubik operation</secondary>
      </indexterm>

      <sect3 id="HDRWQ103">
        <title>Configuring the Cell for Proper Ubik Operation</title>

        <para>This section describes how to configure your cell to maintain proper Ubik operation. <itemizedlist>
            <listitem>
              <para>Run all four database server processes--Authentication Server, Backup Server, Protection Server, and VL
              Server--on all database server machines.</para>

              <para>Both the client and server portions of Ubik expect that all the database server machines listed in the <emphasis
              role="bold">CellServDB</emphasis> file are running all of the database server processes. There is no mechanism for
              indicating that only some database server processes are running on a machine.</para>
            </listitem>

            <listitem>
              <para>Maintain correct information in the <emphasis role="bold">/usr/afs/etc/CellServDB</emphasis> file at all
              times.</para>

              <para>Ubik consults the <emphasis role="bold">/usr/afs/etc/CellServDB</emphasis> file to determine the sites with
              which to establish and maintain a quorum. Incorrect information can result in unsynchronized databases or election of
              a coordinator in each of several subgroups of machines, because the Ubik processes on various machines do not agree on
              which machines need to participate in the quorum.</para>

              <para>If you use the Update Server, it is simplest to maintain the <emphasis
              role="bold">/usr/afs/etc/CellServDB</emphasis> file on the system control machine, which distributes its copy to all
              other server machines. The <emphasis>OpenAFS Quick Beginnings</emphasis> explains how to configure the Update Server.
              </para>

              <para>The only reason to alter the file is when configuring or decommissioning a database server machine. Use the
              appropriate <emphasis role="bold">bos</emphasis> commands rather than editing the file by hand. For instructions, see
              <link linkend="HDRWQ118">Maintaining the Server CellServDB File</link>. The instructions in <link
              linkend="HDRWQ142">Monitoring and Controlling Server Processes</link> for stopping and starting processes remind you
              to alter the <emphasis role="bold">CellServDB</emphasis> file when appropriate, as do the instructions in the
              <emphasis>OpenAFS Quick Beginnings</emphasis> for installing or decommissioning a database server machine.</para>

              <para>(Client processes and the server processes that do not maintain databases also rely on correct information in
              the <emphasis role="bold">CellServDB</emphasis> file for proper operation, but their use of the information does not
              affect Ubik's operation. See <link linkend="HDRWQ118">Maintaining the Server CellServDB File</link> and <link
              linkend="HDRWQ406">Maintaining Knowledge of Database Server Machines</link>.)</para>

              <indexterm>
                <primary>clocks</primary>

                <secondary>need to synchronize for Ubik</secondary>
              </indexterm>
            </listitem>

            <listitem>
              <para>Keep the clocks synchronized on all machines in the cell, especially the database server machines.</para>

              <para>Keeping clocks synchronized is important because the Ubik processes at a database's sites timestamp the messages
              which they exchange to maintain constant contact. Timestamping the messages is necessary because in a networked
              environment it is not safe to assume that a message reaches its destination instantly. Ubik compares the timestamp on
              an incoming message with the current time. If the difference is too great, it is possible that an outage is preventing
              reliable communication between the Ubik sites, which can possibly result in unsynchronized databases. Ubik considers
              the message invalid, which can prompt it to attempt election of a different coordinator.</para>

              <para>Electing a new coordinator is appropriate if a timestamped message is expired due to actual interruption of
              communication, but not if a message appears expired only because the sender and recipient do not share the same time.
              For detailed examples of how unsynchronized clocks can destabilize Ubik operation, see <link linkend="HDRWQ105">How
              Ubik Uses Timestamped Messages</link>.</para>
            </listitem>
          </itemizedlist></para>

        <indexterm>
          <primary>Ubik</primary>

          <secondary>features summarized</secondary>
        </indexterm>

        <indexterm>
          <primary>process</primary>

          <secondary>lightweight Ubik</secondary>
        </indexterm>

        <indexterm>
          <primary>Ubik</primary>

          <secondary>server and client portions</secondary>
        </indexterm>
      </sect3>

      <sect3 id="HDRWQ104">
        <title>How Ubik Operates Automatically</title>

        <para>The following Ubik features help keep its maintenance requirements to a minimum: <itemizedlist>
            <listitem>
              <para>Ubik's server and client portions operate automatically.</para>

              <para>Each database server process runs a lightweight process to call on the server portion of the Ubik library. It is
              common to refer to this lightweight process itself as Ubik. Because it is lightweight, the Ubik process does not
              appear in process listings such as those generated by the UNIX <emphasis role="bold">ps</emphasis> command.
              Client-side programs that need to read and change the databases directly call the subroutines in the Ubik library's
              client portion, rather than running a separate lightweight process. Examples of such programs are the <emphasis
              role="bold">klog</emphasis> command and the commands in the <emphasis role="bold">pts</emphasis> suite.</para>
            </listitem>

            <listitem>
              <para>Ubik tracks database version numbers.</para>

              <para>As the coordinator records a change to a database, it increments the database's version number. The version
              number makes it easy for the coordinator to determine if a site has the most recent version or not. The version number
              speeds the return to normal functioning after election of a new coordinator or when communication is restored after an
              outage, because it makes it easy to determine which site has the most current database and which need to be
              updated.</para>
            </listitem>

            <listitem>
              <para>Ubik's use of timestamped messages guarantees that database copies are always synchronized during normal
              operation.</para>

              <para>Replicating a database to increase data availability is pointless if all copies of the database are not the
              same. Inconsistent performance can result if clients receive different information depending on which copy of the
              database they access. As previously noted, Ubik sites constantly track the status of their peers by exchanging
              timestamped messages. For a detailed description, see <link linkend="HDRWQ105">How Ubik Uses Timestamped
              Messages</link>.</para>
            </listitem>

            <listitem>
              <para>The ability to move the coordinator maximizes database availability.</para>

              <para>Suppose, for example, that in a cell with three database server machines a network partition separates the two
              secondary sites from the coordinator. The coordinator retires because it is no longer in contact with a majority of
              the sites listed in the <emphasis role="bold">CellServDB</emphasis> file. The two sites on the other side of the
              partition can elect a new coordinator among themselves, and it can then accept database changes from clients. If the
              coordinator cannot move in this way, the database has to be read-only until the network partition is repaired. For a
              detailed description of Ubik's election procedure, see <link linkend="HDRWQ106">A Flexible Coordinator Boosts
              Availability</link>.</para>
            </listitem>
          </itemizedlist></para>

        <indexterm>
          <primary>consistency guarantees</primary>

          <secondary>administrative databases</secondary>
        </indexterm>

        <indexterm>
          <primary>Ubik</primary>

          <secondary>consistency guarantees</secondary>
        </indexterm>

        <sect4 id="HDRWQ105">
          <title>How Ubik Uses Timestamped Messages</title>

          <para>Ubik synchronizes the copies of a database by maintaining constant contact between the synchronization site and the
          secondary sites. The Ubik coordinator frequently sends a time-stamped <emphasis>guarantee</emphasis> message to each of
          the secondary sites. When the secondary site receives the message, it concludes that it is in contact with the
          coordinator. It considers its copy of the database to be valid until time <emphasis>T</emphasis>, which is usually 60
          seconds from the time the coordinator sent the message. In response, the secondary site returns a
          <emphasis>vote</emphasis> message that acknowledges the coordinator as valid until a certain time X, which is usually 120
          seconds in the future.</para>

          <para>The coordinator sends guarantee messages more frequently than every <emphasis>T</emphasis> seconds, so that the
          expiration periods overlap. There is no danger of expiration unless a network partition or other outage actually
          interrupts communication. If the guarantee expires, the secondary site's copy of the database it not necessarily current.
          Nonetheless, the database server continues to service client requests. It is considered better for overall cell
          functioning that a secondary site remains accessible even if the information it is distributing is possibly out of date.
          Most of the AFS administrative databases do not change that frequently, in any case, and making a database inaccessible
          causes a timeout for clients that happen to access that copy.</para>

          <para>As previously mentioned, Ubik's use of timestamped messages makes it vital to synchronize the clocks on database
          server machines. There are two ways that skewed clocks can interrupt normal Ubik functioning, depending on which clock is
          ahead of the others.</para>

          <para>Suppose, for example, that the Ubik coordinator's clock is ahead of the secondary sites: the coordinator's clock
          says 9:35:30, but the secondary clocks say 9:31:30. The secondary sites send votes messages that acknowledge the
          coordinator as valid until 9:33:30. This is two minutes in the future according to the secondary clocks, but is already in
          the past from the coordinator's perspective. The coordinator concludes that it no longer has enough support to remain
          coordinator and forces election of a new coordinator. Election takes about three minutes, during which time no copy of the
          database accepts changes.</para>

          <para>The opposite possibility is that a secondary site's clock (14:50:00) is ahead of the coordinator's (14:46:30). When
          the coordinator sends a guarantee message good until 14:47:30), it has already expired according to the secondary clock.
          Believing that it is out of contact with the coordinator, the secondary site stops sending votes for the coordinator and
          tries get itself elected as coordinator. This is appropriate if the coordinator has actually failed, but is inappropriate
          when there is no actual outage.</para>

          <para>The attempt of a single secondary site to get elected as the new coordinator usually does not affect the performance
          of the other sites. As long as their clocks agree with the coordinator's, they ignore the other secondary site's request
          for votes and continue voting for the current coordinator. However, if enough of the secondary sites's clocks get ahead of
          the coordinator's, they can force election of a new coordinator even though the current one is actually working
          fine.</para>

          <indexterm>
            <primary>Ubik</primary>

            <secondary>election of coordinator</secondary>
          </indexterm>

          <indexterm>
            <primary>coordinator (Ubik)</primary>

            <secondary>election procedure described</secondary>
          </indexterm>

          <indexterm>
            <primary>election of Ubik coordinator</primary>
          </indexterm>

          <indexterm>
            <primary>flexible synchronization site (Ubik)</primary>
          </indexterm>

          <indexterm>
            <primary>synchronization site (Ubik)</primary>

            <secondary>flexibility</secondary>
          </indexterm>

          <indexterm>
            <primary>Ubik</primary>

            <secondary>majority defined</secondary>
          </indexterm>

          <indexterm>
            <primary>majority</primary>

            <secondary>defined for Ubik</secondary>
          </indexterm>

          <indexterm>
            <primary>outages</primary>

            <secondary>due to Ubik election</secondary>
          </indexterm>

          <indexterm>
            <primary>system outages</primary>

            <secondary>due to Ubik election</secondary>
          </indexterm>
        </sect4>

        <sect4 id="HDRWQ106">
          <title>A Flexible Coordinator Boosts Availability</title>

          <para>Ubik uses timestamped messages to determine when coordinator election is necessary, just as it does to keep the
          database copies synchronized. As long as the coordinator receives vote messages from a majority of the sites (it
          implicitly votes for itself), it is appropriate for it to continue as coordinator because it is successfully distributing
          database changes. A majority is defined as more than 50% of all database sites when there are an odd number of sites; with
          an even number of sites, the site with the lowest Internet address has an extra vote for breaking ties as necessary.If the
          coordinator is not receiving sufficient votes, it retires and the Ubik sites elect a new coordinator. This does not happen
          spontaneously, but only when the coordinator really fails or stops receiving a majority of the votes. The secondary sites
          have a built-in bias to continue voting for an existing coordinator, which prevents undue elections.</para>

          <para>The election of the new coordinator is by majority vote. The Ubik subprocesses have a bias to vote for the site with
          the lowest Internet address, which helps it gather the necessary majority quicker than if all the sites were competing to
          receive votes themselves. During the election (which normally lasts less than three minutes), clients can read information
          from the database, but cannot make any changes.</para>

          <para>Ubik's election procedure makes it possible for each database server process's coordinator to be on a different
          machine. For example, if the Ubik coordinators for all four processes start out on machine A and the Protection Server on
          machine A fails for some reason, then a different site (say machine B) must be elected as the new Protection Database Ubik
          coordinator. Machine B remains the coordinator for the Protection Database even after the Protection Server on machine A
          is working again. The failure of the Protection Server has no effect on the Authentication, Backup, or VL Servers, so
          their coordinators remain on machine A.</para>
        </sect4>
      </sect3>
    </sect2>

    <sect2 id="HDRWQ107">
      <title>Backing Up and Restoring the Administrative Databases</title>

      <para>The AFS administrative databases store information that is critical for AFS operation in your cell. If a database
      becomes corrupted due to a hardware failure or other problem on a database server machine, it likely to be difficult and
      time-consuming to recreate all of the information from scratch. To protect yourself against loss of data, back up the
      administrative databases to a permanent media, such as tape, on a regular basis. The recommended method is to use a standard
      local disk backup utility such as the UNIX <emphasis role="bold">tar</emphasis> command.</para>

      <para>When deciding how often to back up a database, consider the amount of data that you are willing to recreate by hand if
      it becomes necessary to restore the database from a backup copy. In most cells, the databases differ quite a bit in how often
      and how much they change. Changes to the Authentication Database are probably the least frequent, and consist mostly of
      changed user passwords. Protection Database and VLDB changes are probably more frequent, as users add or delete groups and
      change group memberships, and as you and other administrators create or move volumes. The number and frequency of changes is
      probably greatest in the Backup Database, particularly if you perform backups every day.</para>

      <para>The ease with which you can recapture lost changes also differs for the different databases: <itemizedlist>
          <listitem>
            <para>If regular users make a large proportion of the changes to the Authentication Database and Protection Database in
            your cell, then recovering them possibly requires a large amount of detective work and interviewing of users, assuming
            that they can even remember what changes they made at what time.</para>
          </listitem>

          <listitem>
            <para>Recovering lost changes to the VLDB is more straightforward, because you can use the <emphasis role="bold">vos
            syncserv</emphasis> and <emphasis role="bold">vos syncvldb</emphasis> commands to correct any discrepancies between the
            VLDB and the actual state of volumes on server machines. Running these commands can be time-consuming, however.</para>
          </listitem>

          <listitem>
            <para>The configuration information in the Backup Database (Tape Coordinator port offsets, volume sets and entries, the
            dump hierarchy, and so on) probably does not change that often, in which case it is not that hard to recover a few
            recent changes. In contrast, there are likely to be a large number of new dump records resulting from dump operations.
            You can recover these records by using the <emphasis role="bold">-dbadd</emphasis> argument to the <emphasis
            role="bold">backup scantape</emphasis> command, reading in information from the backup tapes themselves. This can take a
            long time and require numerous tape changes, however, depending on how much data you back up in your cell and how you
            append dumps. Furthermore, the <emphasis role="bold">backup scantape</emphasis> command is subject to several
            restrictions. The most basic is that it halts if it finds that an existing dump record in the database has the same dump
            ID number as a dump on the tape it is scanning. If you want to continue with the scanning operation, you must locate and
            remove the existing record from the database. For further discussion, see the <emphasis role="bold">backup
            scantape</emphasis> command's reference page in the <emphasis>OpenAFS Administration Reference</emphasis>.</para>
          </listitem>
        </itemizedlist></para>

      <para>These differences between the databases possibly suggest backing up the database at different frequencies, ranging from
      every few days or weekly for the Backup Database to every few weeks for the Authentication Database. On the other hand, it is
      probably simpler from a logistical standpoint to back them all up at the same time (and frequently), particularly if tape
      consumption is not a major concern. Also, it is not generally necessary to keep backup copies of the databases for a long
      time, so you can recycle the tapes fairly frequently.</para>

      <indexterm>
        <primary>administrative database</primary>

        <secondary>backing up</secondary>
      </indexterm>

      <indexterm>
        <primary>backing up</primary>

        <secondary>administrative databases</secondary>
      </indexterm>
    </sect2>

    <sect2 id="HDRWQ108">
      <title>To back up the administrative databases</title>

      <orderedlist>
        <listitem>
          <para>Log in as the local superuser <emphasis role="bold">root</emphasis> on a database server machine that is not the
          synchronization site. The machine with the highest IP address is normally the best choice, since it is least likely to
          become the synchronization site in an election.</para>
        </listitem>

        <listitem id="LIDBBK_SHUTDOWN">
          <para>Issue the <emphasis role="bold">bos shutdown</emphasis> command to shut down the
          relevant server process on the local machine. For a complete description of the command, see <link linkend="HDRWQ168">To
          stop processes temporarily</link>.</para>

          <para>For the <emphasis role="bold">-instance</emphasis> argument, specify one or more database server process names
          (<emphasis role="bold">buserver</emphasis> for the Backup Server, <emphasis role="bold">kaserver</emphasis> for the
          Authentication Server, <emphasis role="bold">ptserver</emphasis> for the Protection Server, or <emphasis
          role="bold">vlserver</emphasis> for the Volume Location Server. Include the <emphasis role="bold">-localauth</emphasis>
          flag because you are logged in as the local superuser <emphasis role="bold">root</emphasis> but do not necessarily have
          administrative tokens.</para>

          <programlisting>
   # <emphasis role="bold">bos shutdown</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">-instance</emphasis> &lt;<replaceable>instances</replaceable>&gt;+ <emphasis
              role="bold">-localauth</emphasis> [<emphasis role="bold">-wait</emphasis>]
</programlisting>
        </listitem>

        <listitem>
          <para>Use a local disk backup utility, such as the UNIX <emphasis role="bold">tar</emphasis> command, to transfer one or
          more database files to tape. If the local database server machine does not have a tape device attached, use a remote copy
          command to transfer the file to a machine with a tape device, then use the <emphasis role="bold">tar</emphasis> command
          there.</para>

          <para>The following command sequence backs up the complete contents of the <emphasis role="bold">/usr/afs/db</emphasis>
          directory</para>

          <programlisting>
   # <emphasis role="bold">cd /usr/afs/db</emphasis>
   # <emphasis role="bold">tar cvf</emphasis>  tape_device <emphasis role="bold">.</emphasis>
</programlisting>

          <para>To back up individual database files, substitute their names for the period in the preceding <emphasis
          role="bold">tar</emphasis> command: <itemizedlist>
              <listitem>
                <para><emphasis role="bold">bdb.DB0</emphasis> for the Backup Database</para>
              </listitem>

              <listitem>
                <para><emphasis role="bold">kaserver.DB0</emphasis> for the Authentication Database</para>
              </listitem>

              <listitem>
                <para><emphasis role="bold">prdb.DB0</emphasis> for the Protection Database</para>
              </listitem>

              <listitem>
                <para><emphasis role="bold">vldb.DB0</emphasis> for the VLDB</para>
              </listitem>
            </itemizedlist></para>
        </listitem>

        <listitem>
          <para>Issue the <emphasis role="bold">bos start</emphasis> command to restart the server processes on the local machine.
          For a complete description of the command, see <link linkend="HDRWQ166">To start processes by changing their status flags
          to Run</link>. Provide the same values for the <emphasis role="bold">-instance</emphasis> argument as in Step <link
          linkend="LIDBBK_SHUTDOWN">2</link>, and the <emphasis role="bold">-localauth</emphasis> flag for the same reason.
          <programlisting>
   # <emphasis role="bold">bos start</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">-instance</emphasis> &lt;<replaceable>server process name</replaceable>&gt;+ <emphasis
                role="bold">-localauth</emphasis>
</programlisting></para>
        </listitem>
      </orderedlist>

      <indexterm>
        <primary>administrative database</primary>

        <secondary>restoring</secondary>
      </indexterm>

      <indexterm>
        <primary>restoring</primary>

        <secondary>administrative databases</secondary>
      </indexterm>
    </sect2>

    <sect2 id="HDRWQ109">
      <title>To restore an administrative database</title>

      <orderedlist>
        <listitem>
          <para>Log in as the local superuser <emphasis role="bold">root</emphasis> on each database server machine in the
          cell.</para>
        </listitem>

        <listitem id="LIDBREST_SHUTDOWN">
          <para>Working on one of the machines, issue the <emphasis role="bold">bos
          shutdown</emphasis> command once for each database server machine, to shut down the relevant server process on all of
          them. For a complete description of the command, see <link linkend="HDRWQ168">To stop processes temporarily</link>.</para>

          <para>For the <emphasis role="bold">-instance</emphasis> argument, specify one or more database server process names
          (<emphasis role="bold">buserver</emphasis> for the Backup Server, <emphasis role="bold">kaserver</emphasis> for the
          Authentication Server, <emphasis role="bold">ptserver</emphasis> for the Protection Server, or <emphasis
          role="bold">vlserver</emphasis> for the Volume Location Server. Include the <emphasis role="bold">-localauth</emphasis>
          flag because you are logged in as the local superuser <emphasis role="bold">root</emphasis> but do not necessarily have
          administrative tokens.</para>

          <programlisting>
   # <emphasis role="bold">bos shutdown</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">-instance</emphasis> &lt;<replaceable>instances</replaceable>&gt;+ <emphasis
              role="bold">-localauth</emphasis> [<emphasis role="bold">-wait</emphasis>]
</programlisting>
        </listitem>

        <listitem>
          <para>Remove the database from each database server machine, by issuing the following commands on each one.
          <programlisting>
   # <emphasis role="bold">cd /usr/afs/db</emphasis>
</programlisting></para>

          <para>For the Backup Database:</para>

          <programlisting>
   # <emphasis role="bold">rm bdb.DB0</emphasis>
   # <emphasis role="bold">rm bdb.DBSYS1</emphasis>
</programlisting>

          <para>For the Authentication Database:</para>

          <programlisting>
   # <emphasis role="bold">rm kaserver.DB0</emphasis>
   # <emphasis role="bold">rm kaserver.DBSYS1</emphasis>
</programlisting>

          <para>For the Protection Database:</para>

          <programlisting>
   # <emphasis role="bold">rm prdb.DB0</emphasis>
   # <emphasis role="bold">rm prdb.DBSYS1</emphasis>
</programlisting>

          <para>For the VLDB:</para>

          <programlisting>
   # <emphasis role="bold">rm vldb.DB0</emphasis>
   # <emphasis role="bold">rm vldb.DBSYS1</emphasis>
</programlisting>
        </listitem>

        <listitem>
          <para>Using the local disk backup utility that you used to back up the database, copy the most recently backed-up version
          of it to the appropriate file on the database server machine with the lowest IP address. The following is an appropriate
          <emphasis role="bold">tar</emphasis> command if the synchronization site has a tape device attached: <programlisting>
   # <emphasis role="bold">cd /usr/afs/db</emphasis>
   # <emphasis role="bold">tar xvf</emphasis> tape_device  database_file
</programlisting></para>

          <para>where <emphasis>database_file</emphasis> is one of the following: <itemizedlist>
              <listitem>
                <para><emphasis role="bold">bdb.DB0</emphasis> for the Backup Database</para>
              </listitem>

              <listitem>
                <para><emphasis role="bold">kaserver.DB0</emphasis> for the Authentication Database</para>
              </listitem>

              <listitem>
                <para><emphasis role="bold">prdb.DB0</emphasis> for the Protection Database</para>
              </listitem>

              <listitem>
                <para><emphasis role="bold">vldb.DB0</emphasis> for the VLDB</para>
              </listitem>
            </itemizedlist></para>
        </listitem>

        <listitem>
          <para>Working on one of the machines, issue the <emphasis role="bold">bos start</emphasis> command to restart the server
          process on each of the database server machines in turn. Start with the machine with the lowest IP address, which becomes
          the synchronization site for the Backup Database. Wait for it to establish itself as the synchronization site before
          repeating the command to restart the process on the other database server machines. For a complete description of the
          command, see <link linkend="HDRWQ166">To start processes by changing their status flags to Run</link>. Provide the same
          values for the <emphasis role="bold">-instance</emphasis> argument as in Step <link linkend="LIDBREST_SHUTDOWN">2</link>,
          and the <emphasis role="bold">-localauth</emphasis> flag for the same reason. <programlisting>
   # <emphasis role="bold">bos start</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">-instance</emphasis>  &lt;<replaceable>server process name</replaceable>&gt;+  <emphasis
                role="bold">-localauth</emphasis>
</programlisting></para>
        </listitem>

        <listitem>
          <para>If the database has changed since you last backed it up, issue the appropriate commands from the instructions in the
          indicated sections to recreate the information in the restored database. If issuing <emphasis role="bold">pts</emphasis>
          commands, you must first obtain administrative tokens. The <emphasis role="bold">backup</emphasis> and <emphasis
          role="bold">vos</emphasis> commands accept the <emphasis role="bold">-localauth</emphasis> flag if you are logged in as
          the local superuser <emphasis role="bold">root</emphasis>, so you do not need administrative tokens. The Authentication
          Server always performs a separate authentication anyway, so you only need to include the <emphasis
          role="bold">-admin</emphasis> argument if issuing <emphasis role="bold">kas</emphasis> commands. <itemizedlist>
              <listitem>
                <para>To define or remove volume sets and volume entries in the Backup Database, see <link
                linkend="HDRWQ265">Defining and Displaying Volume Sets and Volume Entries</link>.</para>
              </listitem>

              <listitem>
                <para>To edit the dump hierarchy in the Backup Database, see <link linkend="HDRWQ267">Defining and Displaying the
                Dump Hierarchy</link>.</para>
              </listitem>

              <listitem>
                <para>To define or remove Tape Coordinator port offset entries in the Backup Database, see <link
                linkend="HDRWQ261">Configuring Tape Coordinator Machines and Tape Devices</link>.</para>
              </listitem>

              <listitem>
                <para>To restore dump records in the Backup Database, see <link linkend="HDRWQ305">To scan the contents of a
                tape</link>.</para>
              </listitem>

              <listitem>
                <para>To recreate Authentication Database entries or password changes for users, see the appropriate section of
                <link linkend="HDRWQ491">Administering User Accounts</link>.</para>
              </listitem>

              <listitem>
                <para>To recreate Protection Database entries or group membership information, see the appropriate section of <link
                linkend="HDRWQ531">Administering the Protection Database</link>.</para>
              </listitem>

              <listitem>
                <para>To synchronize the VLDB with volume headers, see <link linkend="HDRWQ227">Synchronizing the VLDB and Volume
                Headers</link>.</para>
              </listitem>
            </itemizedlist></para>
        </listitem>
      </orderedlist>

      <indexterm>
        <primary>installing</primary>

        <secondary>server process binaries, about</secondary>
      </indexterm>

      <indexterm>
        <primary>server process binaries</primary>

        <secondary>installing</secondary>
      </indexterm>

      <indexterm>
        <primary>BOS Server</primary>

        <secondary>maintainer of server process binaries</secondary>
      </indexterm>

      <indexterm>
        <primary>server process</primary>

        <secondary>binaries</secondary>

        <see>server process binaries</see>
      </indexterm>

      <indexterm>
        <primary>directories (server)</primary>

        <secondary>/usr/afs/bin</secondary>
      </indexterm>

      <indexterm>
        <primary>server machine</primary>

        <secondary>need for consistent version of software</secondary>
      </indexterm>
    </sect2>
  </sect1>

  <sect1 id="HDRWQ110">
    <title>Installing Server Process Software</title>

    <para>This section explains how to install new server process binaries on file server machines, how to revert to a previous
    version if the current version is not working properly, and how to install new disks to house AFS volumes on a file server
    machine.</para>

    <para>The most frequent reason to replace a server process's binaries is to upgrade AFS to a new version. In general,
    installation instructions accompany the updated software, but this chapter provides an additional reference.</para>

    <para>Each AFS server machine must store the server process binaries in a local disk directory, called <emphasis
    role="bold">/usr/afs/bin</emphasis> by convention. For predictable system performance, it is best that all server machines run
    the same build level, or at least the same version, of the server software. For instructions on checking AFS build level, see
    <link linkend="HDRWQ117">Displaying A Binary File's Build Level</link>.</para>

    <para>The Update Server makes it easy to distribute a consistent version of software to all server machines. You designate one
    server machine of each system type as the <emphasis>binary distribution machine</emphasis> by running the server portion of the
    Update Server (<emphasis role="bold">upserver</emphasis> process) on it. All other server machines of that system type run the
    client portion of the Update Server (<emphasis role="bold">upclientbin</emphasis> process) to retrieve updated software from the
    binary distribution machine. The <emphasis>OpenAFS Quick Beginnings</emphasis> explains how to install the appropriate
    processes. For more on binary distribution machines, see <link linkend="HDRWQ93">Binary Distribution Machines</link>.</para>

    <para>When you use the Update Server, you install new binaries on binary distribution machines only. If you install binaries
    directly on a machine that is running the <emphasis role="bold">upclientbin</emphasis> process, they are overwritten the next
    time the process compares the contents of the local <emphasis role="bold">/usr/afs/bin</emphasis> directory to the contents on
    the system control machine, by default within five minutes.</para>

    <para>The following instructions explain how to use the appropriate commands from the <emphasis role="bold">bos</emphasis> suite
    to install and uninstall server binaries.</para>

    <indexterm>
      <primary>installing</primary>

      <secondary>server binaries</secondary>
    </indexterm>

    <indexterm>
      <primary>server process binaries</primary>

      <secondary>installing</secondary>
    </indexterm>

    <indexterm>
      <primary>command suite</primary>

      <secondary>binaries</secondary>

      <tertiary>installing</tertiary>
    </indexterm>

    <indexterm>
      <primary>file server machine</primary>

      <secondary>installing command and process binaries</secondary>
    </indexterm>

    <indexterm>
      <primary>server process</primary>

      <secondary>restarting for changed binaries</secondary>
    </indexterm>

    <sect2 id="HDRWQ111">
      <title>Installing New Binaries</title>

      <para>An AFS server process does not automatically switch to a new process binary file as soon as it is installed in the
      <emphasis role="bold">/usr/afs/bin</emphasis> directory. The process continues to use the previous version of the binary file
      until it (the process) next restarts. By default, the BOS Server restarts processes for which there are new binary files every
      day at 5:00 a.m., as specified in the <emphasis role="bold">/usr/afs/local/BosConfig</emphasis> file. To display or change
      this <emphasis>binary restart time</emphasis>, use the <emphasis role="bold">bos getrestart</emphasis> and <emphasis
      role="bold">bos setrestart</emphasis> commands, as described in <link linkend="HDRWQ171">Setting the BOS Server's Restart
      Times</link>.</para>

      <para>You can force the server machine to start using new server process binaries immediately by issuing the <emphasis
      role="bold">bos restart</emphasis> command as described in the following instructions.</para>

      <para>You do not need to restart processes when you install new command suite binaries. The new binary is invoked
      automatically the next time a command from the suite is issued.</para>

      <indexterm>
        <primary>file extension</primary>

        <secondary>.BAK</secondary>
      </indexterm>

      <indexterm>
        <primary>file extension</primary>

        <secondary>.OLD</secondary>
      </indexterm>

      <indexterm>
        <primary>BAK version of binary file</primary>

        <secondary>created by bos install command</secondary>
      </indexterm>

      <indexterm>
        <primary>OLD version of binary file</primary>

        <secondary>created by bos install command</secondary>
      </indexterm>

      <indexterm>
        <primary>saving</primary>

        <secondary>previous version of server binaries</secondary>
      </indexterm>

      <para>When you use the <emphasis role="bold">bos install</emphasis> command, the BOS Server automatically saves the current
      version of a binary file by adding a <emphasis role="bold">.BAK</emphasis> extension to its name. It renames the current
      <emphasis role="bold">.BAK</emphasis> version, if any, to the <emphasis role="bold">.OLD</emphasis> version, if there is no
      <emphasis role="bold">.OLD</emphasis> version already. If there is a current <emphasis role="bold">.OLD</emphasis> version,
      the current <emphasis role="bold">.BAK</emphasis> version must be at least seven days old to replace it.</para>

      <para>It is best to store AFS binaries in the <emphasis role="bold">/usr/afs/bin</emphasis> directory, because that is the
      only directory the BOS Server automatically checks for new binaries. You can, however, use the <emphasis role="bold">bos
      install</emphasis> command's <emphasis role="bold">-dir</emphasis> argument to install non-AFS binaries into other directories
      on a server machine's local disk. See the command's reference page in the <emphasis>OpenAFS Administration
      Reference</emphasis> for further information.</para>

      <indexterm>
        <primary>bos commands</primary>

        <secondary>install</secondary>
      </indexterm>

      <indexterm>
        <primary>commands</primary>

        <secondary>bos install</secondary>
      </indexterm>
    </sect2>

    <sect2 id="Header_130">
      <title>To install new server binaries</title>

      <orderedlist>
        <listitem>
          <para>Verify that you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue
          the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To
          display the users in the UserList file</link>. <programlisting>
   % <emphasis role="bold">bos listusers</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
</programlisting></para>
        </listitem>

        <listitem>
          <para>Verify that the binaries are available in the source directory from which you are installing them. If the machine is
          also an AFS client, you can retrieve the binaries from a central directory in AFS. Otherwise, you can obtain them directly
          from the AFS distribution media, from a local disk directory where you previously installed them, or from a remote machine
          using a transfer utility such as the <emphasis role="bold">ftp</emphasis> command.</para>
        </listitem>

        <listitem id="LIWQ112">
          <para>Issue the <emphasis role="bold">bos install</emphasis> command for the binary distribution
          machine. (If you have forgotten which machine is performing that role, see <link linkend="HDRWQ97">To locate the binary
          distribution machine for a system type</link>.) <programlisting>
   % <emphasis role="bold">bos install</emphasis> &lt;<replaceable>machine name</replaceable>&gt; &lt;<replaceable>files to install</replaceable>&gt;+
</programlisting></para>

          <para>where <variablelist>
              <varlistentry>
                <term><emphasis role="bold">i</emphasis></term>

                <listitem>
                  <para>Is the shortest acceptable abbreviation of <emphasis role="bold">install</emphasis>.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">machine name</emphasis></term>

                <listitem>
                  <para>Names the binary distribution machine.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">files to install</emphasis></term>

                <listitem>
                  <para>Names each binary file to install into the local <emphasis role="bold">/usr/afs/bin</emphasis> directory.
                  Partial pathnames are interpreted relative to the current working directory. The last element in each pathname
                  (the filename itself) matches the name of the file it is replacing, such as <emphasis
                  role="bold">bosserver</emphasis> or <emphasis role="bold">volserver</emphasis> for server processes, <emphasis
                  role="bold">bos</emphasis> or <emphasis role="bold">vos</emphasis> for commands.</para>

                  <para>Each AFS server process other than the <emphasis role="bold">fs</emphasis> process uses a single binary
                  file. The <emphasis role="bold">fs</emphasis> process uses three binary files: <emphasis
                  role="bold">fileserver</emphasis>, <emphasis role="bold">volserver</emphasis>, and <emphasis
                  role="bold">salvager</emphasis>. Installing a new version of one component does not necessarily mean that you need
                  to replace all three.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </listitem>

        <listitem>
          <para>Repeat Step <link linkend="LIWQ112">3</link> for each binary distribution machine.</para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">(Optional)</emphasis> If you want to restart processes to use the new binaries immediately,
          wait until the <emphasis role="bold">upclientbin</emphasis> process retrieves them from the binary distribution machine.
          You can verify the timestamps on binary files by using the <emphasis role="bold">bos getdate</emphasis> command as
          described in <link linkend="HDRWQ115">Displaying Binary Version Dates</link>. When the binary files are available on each
          server machine, issue the <emphasis role="bold">bos restart</emphasis> command, for which complete instructions appear in
          <link linkend="HDRWQ170">Stopping and Immediately Restarting Processes</link>.</para>

          <para>If you are working on an AFS client machine, it is a wise precaution to have a copy of the <emphasis
          role="bold">bos</emphasis> command suite binaries on the local disk before restarting server processes. In the
          conventional configuration, the <emphasis role="bold">/usr/afsws/bin</emphasis> directory that houses the <emphasis
          role="bold">bos</emphasis> command binary on client machines is a symbolic link into AFS, which conserves local disk
          space. However, restarting certain processes (particularly the database server processes) can make the AFS filespace
          inaccessible, particularly if a problem arises during the restart. Having a local copy of the <emphasis
          role="bold">bos</emphasis> binary enables you to uninstall or reinstall process binaries or restart processes even in this
          case. Use the <emphasis role="bold">cp</emphasis> command to copy the <emphasis role="bold">bos</emphasis> command binary
          from the <emphasis role="bold">/usr/afsws/bin</emphasis> directory to a local directory such as <emphasis
          role="bold">/tmp</emphasis>.</para>

          <para>Restarting a process causes a service outage. It is best to perform the restart at times of low system usage if
          possible.</para>

          <programlisting>
   % <emphasis role="bold">bos restart</emphasis> &lt;<replaceable>machine name</replaceable>&gt; &lt;<replaceable>instances</replaceable>&gt;+
</programlisting>
        </listitem>
      </orderedlist>

      <indexterm>
        <primary>uninstalling</primary>

        <secondary>server process and command suite binaries</secondary>
      </indexterm>

      <indexterm>
        <primary>reverting</primary>

        <secondary>to old version of server process and command binaries</secondary>
      </indexterm>

      <indexterm>
        <primary>server process binaries</primary>

        <secondary>uninstalling</secondary>
      </indexterm>

      <indexterm>
        <primary>server process binaries</primary>

        <secondary>reverting to old version</secondary>
      </indexterm>

      <indexterm>
        <primary>command suite</primary>

        <secondary>binaries</secondary>

        <tertiary>uninstalling</tertiary>
      </indexterm>

      <indexterm>
        <primary>server machine</primary>

        <secondary>uninstalling command &amp; process binaries</secondary>
      </indexterm>

      <indexterm>
        <primary>BAK version of binary file</primary>

        <secondary>used by bos uninstall command</secondary>
      </indexterm>

      <indexterm>
        <primary>OLD version of binary file</primary>

        <secondary>used by bos uninstall command</secondary>
      </indexterm>
    </sect2>

    <sect2 id="HDRWQ113">
      <title>Reverting to the Previous Version of Binaries</title>

      <para>In rare cases, installing a new binary can cause problems serious enough to require reverting to the previous version.
      Just as with installing binaries, consistent system performance requires reverting every server machine back to the same
      version. Issue the <emphasis role="bold">bos uninstall</emphasis> command described here on each binary distribution
      machine.</para>

      <para>When you use the <emphasis role="bold">bos uninstall</emphasis> command, the BOS Server discards the current version of
      a binary file and promotes the <emphasis role="bold">.BAK</emphasis> version of the file by removing the extension. It renames
      the current <emphasis role="bold">.OLD</emphasis> version, if any, to <emphasis role="bold">.BAK</emphasis>.</para>

      <para>If there is no current <emphasis role="bold">.BAK</emphasis> version, the <emphasis role="bold">bos uninstall</emphasis>
      command operation fails and generates an error message. If a <emphasis role="bold">.OLD</emphasis> version still exists, issue
      the <emphasis role="bold">mv</emphasis> command to rename it to <emphasis role="bold">.BAK</emphasis> before reissuing the
      <emphasis role="bold">bos uninstall</emphasis> command.</para>

      <para>Just as when you install new binaries, the server processes do not start using a reverted version immediately.
      Presumably you are reverting because the current binaries do not work, so the following instructions have you restart the
      relevant processes.</para>

      <indexterm>
        <primary>bos commands</primary>

        <secondary>uninstall</secondary>
      </indexterm>

      <indexterm>
        <primary>commands</primary>

        <secondary>bos install</secondary>
      </indexterm>
    </sect2>

    <sect2 id="Header_132">
      <title>To revert to the previous version of binaries</title>

      <orderedlist>
        <listitem>
          <para>Verify that you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue
          the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To
          display the users in the UserList file</link>. <programlisting>
   % <emphasis role="bold">bos listusers</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
</programlisting></para>
        </listitem>

        <listitem>
          <para>Verify that the <emphasis role="bold">.BAK</emphasis> version of each relevant binary is available in the <emphasis
          role="bold">/usr/afs/bin</emphasis> directory on each binary distribution machine. If necessary, you can use the <emphasis
          role="bold">bos getdate</emphasis> command as described in <link linkend="HDRWQ115">Displaying Binary Version
          Dates</link>. If necessary, rename the <emphasis role="bold">.OLD</emphasis> version to <emphasis
          role="bold">.BAK</emphasis></para>
        </listitem>

        <listitem id="LIWQ114">
          <para>Issue the <emphasis role="bold">bos uninstall</emphasis> command for a binary distribution
          machine. (If you have forgotten which machine is performing that role, see <link linkend="HDRWQ97">To locate the binary
          distribution machine for a system type</link>.) <programlisting>
   % <emphasis role="bold">bos uninstall</emphasis> &lt;<replaceable>machine name</replaceable>&gt; &lt;<replaceable>files to uninstall</replaceable>&gt;+
</programlisting></para>

          <para>where <variablelist>
              <varlistentry>
                <term><emphasis role="bold">u</emphasis></term>

                <listitem>
                  <para>Is the shortest acceptable abbreviation of <emphasis role="bold">uninstall</emphasis>.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">machine name</emphasis></term>

                <listitem>
                  <para>Names the binary distribution machine.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">files to uninstall</emphasis></term>

                <listitem>
                  <para>Names each binary file in the <emphasis role="bold">/usr/afs/bin</emphasis> directory to replace with its
                  <emphasis role="bold">.BAK</emphasis> version. The file name alone is sufficient, because the <emphasis
                  role="bold">/usr/afs/bin</emphasis> directory is assumed.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </listitem>

        <listitem>
          <para>Repeat Step <link linkend="LIWQ114">3</link> for each binary distribution machine.</para>
        </listitem>

        <listitem>
          <para>Wait until the <emphasis role="bold">upclientbin</emphasis> process on each server machine retrieves the reverted
          from the binary distribution machine. You can verify the timestamps on binary files by using the <emphasis role="bold">bos
          getdate</emphasis> command as described in <link linkend="HDRWQ115">Displaying Binary Version Dates</link>. When the
          binary files are available on each server machine, issue the <emphasis role="bold">bos restart</emphasis> command, for
          which complete instructions appear in <link linkend="HDRWQ170">Stopping and Immediately Restarting
          Processes</link>.</para>

          <para>If you are working on an AFS client machine, it is a wise precaution to have a copy of the <emphasis
          role="bold">bos</emphasis> command suite binaries on the local disk before restarting server processes. In the
          conventional configuration, the <emphasis role="bold">/usr/afsws/bin</emphasis> directory that houses the <emphasis
          role="bold">bos</emphasis> command binary on client machines is a symbolic link into AFS, which conserves local disk
          space. However, restarting certain processes (particularly the database server processes) can make the AFS filespace
          inaccessible, particularly if a problem arises during the restart. Having a local copy of the <emphasis
          role="bold">bos</emphasis> binary enables you to uninstall or reinstall process binaries or restart processes even in this
          case. Use the <emphasis role="bold">cp</emphasis> command to copy the <emphasis role="bold">bos</emphasis> command binary
          from the <emphasis role="bold">/usr/afsws/bin</emphasis> directory to a local directory such as <emphasis
          role="bold">/tmp</emphasis>.</para>

          <programlisting>
   % <emphasis role="bold">bos restart</emphasis> &lt;<replaceable>machine name</replaceable>&gt; &lt;<replaceable>instances</replaceable>&gt;+
</programlisting>
        </listitem>
      </orderedlist>

      <indexterm>
        <primary>server process binaries</primary>

        <secondary>displaying time stamp</secondary>
      </indexterm>

      <indexterm>
        <primary>command suite</primary>

        <secondary>binaries</secondary>

        <tertiary>displaying time stamp</tertiary>
      </indexterm>

      <indexterm>
        <primary>time stamp</primary>

        <secondary>on binary file, listing</secondary>
      </indexterm>

      <indexterm>
        <primary>date</primary>

        <secondary>on binary file, listing</secondary>
      </indexterm>

      <indexterm>
        <primary>compilation</primary>

        <secondary>date of, listing on binary file</secondary>
      </indexterm>

      <indexterm>
        <primary>displaying</primary>

        <secondary>time stamp on binary file</secondary>
      </indexterm>
    </sect2>

    <sect2 id="HDRWQ115">
      <title>Displaying Binary Version Dates</title>

      <para>You can check the compilation dates for all three versions of a binary file in the <emphasis
      role="bold">/usr/afs/bin</emphasis> directory--the current, <emphasis role="bold">.BAK</emphasis> and .<emphasis
      role="bold">OLD</emphasis> versions. This is useful for verifying that new binaries have been copied to a file server machine
      from its binary distribution machine before restarting a server process to use the new binaries.</para>

      <para>To check dates on binaries in a directory other than <emphasis role="bold">/usr/afs/bin</emphasis>, add the <emphasis
      role="bold">-dir</emphasis> argument. See the <emphasis>OpenAFS Administration Reference</emphasis>.</para>

      <indexterm>
        <primary>bos commands</primary>

        <secondary>getdate</secondary>
      </indexterm>

      <indexterm>
        <primary>commands</primary>

        <secondary>bos getdate</secondary>
      </indexterm>
    </sect2>

    <sect2 id="Header_134">
      <title>To display binary version dates</title>

      <orderedlist>
        <listitem>
          <para>Issue the <emphasis role="bold">bos getdate</emphasis> command. <programlisting>
   % <emphasis role="bold">bos getdate</emphasis> &lt;<replaceable>machine name</replaceable>&gt; &lt;<replaceable>files to check</replaceable>&gt;+
</programlisting></para>

          <para>where <variablelist>
              <varlistentry>
                <term><emphasis role="bold">getd</emphasis></term>

                <listitem>
                  <para>Is the shortest acceptable abbreviation of <emphasis role="bold">getdate</emphasis>.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">machine name</emphasis></term>

                <listitem>
                  <para>Name the file server machine for which to display binary dates.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">files to check</emphasis></term>

                <listitem>
                  <para>Names each binary file to display.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </listitem>
      </orderedlist>

      <indexterm>
        <primary>BAK version of binary file</primary>

        <secondary>removing obsolete</secondary>
      </indexterm>

      <indexterm>
        <primary>OLD version of binary file</primary>

        <secondary>removing obsolete</secondary>
      </indexterm>

      <indexterm>
        <primary>removing</primary>

        <secondary>obsolete .BAK and .OLD version of binaries</secondary>
      </indexterm>

      <indexterm>
        <primary>server process binaries</primary>

        <secondary>removing obsolete</secondary>
      </indexterm>

      <indexterm>
        <primary>command suite</primary>

        <secondary>binaries</secondary>

        <tertiary>removing obsolete</tertiary>
      </indexterm>

      <indexterm>
        <primary>removing</primary>

        <secondary>core files from /usr/afs/logs</secondary>
      </indexterm>

      <indexterm>
        <primary>core files</primary>

        <secondary>removing from /usr/afs/logs directory</secondary>
      </indexterm>

      <indexterm>
        <primary>usr/afs/bin directory</primary>

        <secondary>removing obsolete .BAK and .OLD files</secondary>
      </indexterm>
    </sect2>

    <sect2 id="HDRWQ116">
      <title>Removing Obsolete Binary Files</title>

      <para>When processes with new binaries have been running without problems for a number of days, it is generally safe to remove
      the <emphasis role="bold">.BAK</emphasis> and <emphasis role="bold">.OLD</emphasis> versions from the <emphasis
      role="bold">/usr/afs/bin</emphasis> directory, both to reduce clutter and to free space on the file server machine's local
      disk.</para>

      <para>You can use the <emphasis role="bold">bos prune</emphasis> command's flags to remove the following types of files:
      <itemizedlist>
          <listitem>
            <para>To remove files in the <emphasis role="bold">/usr/afs/bin</emphasis> directory with a <emphasis
            role="bold">.BAK</emphasis> extension, use the <emphasis role="bold">-bak</emphasis> flag.</para>
          </listitem>

          <listitem>
            <para>To remove files in the <emphasis role="bold">/usr/afs/bin</emphasis> directory with a <emphasis
            role="bold">.OLD</emphasis> extension, use the <emphasis role="bold">-old</emphasis> flag.</para>
          </listitem>

          <listitem>
            <para>To remove files in the <emphasis role="bold">/usr/afs/logs</emphasis> directory called <emphasis
            role="bold">core</emphasis>, with any extension, use the <emphasis role="bold">-core</emphasis> flag.</para>
          </listitem>

          <listitem>
            <para>To remove all three types of files, use the <emphasis role="bold">-all</emphasis> flag.</para>
          </listitem>
        </itemizedlist></para>

      <indexterm>
        <primary>commands</primary>

        <secondary>bos prune</secondary>
      </indexterm>

      <indexterm>
        <primary>bos commands</primary>

        <secondary>prune</secondary>
      </indexterm>
    </sect2>

    <sect2 id="Header_136">
      <title>To remove obsolete binaries</title>

      <orderedlist>
        <listitem>
          <para>Verify that you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue
          the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To
          display the users in the UserList file</link>. <programlisting>
   % <emphasis role="bold">bos listusers</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
</programlisting></para>
        </listitem>

        <listitem>
          <para>Issue the <emphasis role="bold">bos prune</emphasis> command with one or more of its flags. <programlisting>
   % <emphasis role="bold">bos prune</emphasis> &lt;<replaceable>machine name</replaceable>&gt; [<emphasis role="bold">-bak</emphasis>] [<emphasis
                role="bold">-old</emphasis>] [<emphasis role="bold">-core</emphasis>] [<emphasis role="bold">-all</emphasis>]
</programlisting></para>

          <para>where <variablelist>
              <varlistentry>
                <term><emphasis role="bold">p</emphasis></term>

                <listitem>
                  <para>Is the shortest acceptable abbreviation of <emphasis role="bold">prune</emphasis>.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">machine name</emphasis></term>

                <listitem>
                  <para>Names the file server machine on which to remove obsolete files.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-bak</emphasis></term>

                <listitem>
                  <para>Removes all the files with a <emphasis role="bold">.BAK</emphasis> extension from the <emphasis
                  role="bold">/usr/afs/bin</emphasis> directory. Do not combine this flag with the <emphasis
                  role="bold">-all</emphasis> flag.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-old</emphasis></term>

                <listitem>
                  <para>Removes all the files a .<emphasis role="bold">OLD</emphasis> extension from the <emphasis
                  role="bold">/usr/afs/bin</emphasis> directory. Do not combine this flag with the <emphasis
                  role="bold">-all</emphasis> flag.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-core</emphasis></term>

                <listitem>
                  <para>Removes all core files from the <emphasis role="bold">/usr/afs/logs</emphasis> directory. Do not combine
                  this flag with the <emphasis role="bold">-all</emphasis> flag</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-all</emphasis></term>

                <listitem>
                  <para>Combines the effect of the other three flags. Do not combine it with the other three flags.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </listitem>
      </orderedlist>
    </sect2>

    <sect2 id="HDRWQ117">
      <title>Displaying A Binary File's Build Level</title>

      <para>For the most consistent performance on a server machine, and cell-wide, it is best for all server processes to come from
      the same AFS distribution. Every AFS binary includes an ASCII string that specifies its version, or <emphasis>build
      level</emphasis>. To display it, use the <emphasis role="bold">strings</emphasis> and <emphasis role="bold">grep</emphasis>
      commands, which are included in most UNIX distributions.</para>

      <indexterm>
        <primary>commands</primary>

        <secondary>which</secondary>
      </indexterm>

      <indexterm>
        <primary>commands</primary>

        <secondary>strings</secondary>
      </indexterm>

      <indexterm>
        <primary>strings command</primary>
      </indexterm>

      <indexterm>
        <primary>which command</primary>
      </indexterm>
    </sect2>

    <sect2 id="Header_138">
      <title>To display an AFS binary's build level</title>

      <orderedlist>
        <listitem>
          <para>Change to the directory that houses the binary file . If you are not sure where the binary resides, issue the
          <emphasis role="bold">which</emphasis> command. <programlisting>
   % <emphasis role="bold">which</emphasis> binary_file
   /bin_dir_path/binary_file
   % <emphasis role="bold">cd</emphasis> bin_dir_path
</programlisting></para>
        </listitem>

        <listitem>
          <para>Issue the <emphasis role="bold">strings</emphasis> command to extract all ASCII strings from the binary file. Pipe
          the output to the <emphasis role="bold">grep</emphasis> command to locate the relevant line. <programlisting>
   % <emphasis role="bold">strings ./</emphasis>binary_file <emphasis role="bold">| grep Base</emphasis>
</programlisting></para>

          <para>The output reports the AFS build level in a format like the following:</para>

          <programlisting>
   @(#)Base configuration afsversion  build_level
</programlisting>

          <para>For example, the following string indicates the binary is from AFS M.m build 3.0:</para>

          <programlisting>
   @(#)Base configuration afsM.m 3.0
</programlisting>
        </listitem>
      </orderedlist>

      <indexterm>
        <primary>CellServDB file (server)</primary>

        <secondary>maintaining</secondary>
      </indexterm>

      <indexterm>
        <primary>files</primary>

        <secondary>CellServDB (server)</secondary>
      </indexterm>

      <indexterm>
        <primary>database server process</primary>

        <secondary>use of CellServDB file</secondary>
      </indexterm>

      <indexterm>
        <primary>Ubik</primary>

        <secondary>use of CellServDB file</secondary>
      </indexterm>

      <indexterm>
        <primary>server process</primary>

        <secondary>use of CellServDB file</secondary>
      </indexterm>
    </sect2>
  </sect1>

  <sect1 id="HDRWQ118">
    <title>Maintaining the Server CellServDB File</title>

    <para>Every file server machine maintains a list of its home cell's database server machines in the local disk file <emphasis
    role="bold">/usr/afs/etc/CellServDB</emphasis> on its local disk. Both database server processes and non-database server
    processes consult the file: <itemizedlist>
        <listitem>
          <para>The database server processes (the Authentication, Backup, Protection, and Volume Location Servers) maintain
          constant contact with their peers in order to keep their copies of the replicated administrative databases
          synchronized.</para>

          <para>As detailed in <link linkend="HDRWQ102">Replicating the OpenAFS Administrative Databases</link>, the database server
          processes use the Ubik utility to synchronize the information in the databases they maintain. The Ubik coordinator at the
          synchronization site for each database maintains the single read/write copy of the database and distributes changes to the
          secondary sites as necessary. It must maintain contact with a majority of the secondary sites to remain the coordinator,
          and consults the <emphasis role="bold">CellServDB</emphasis> file to learn how many peers it has and on which machines
          they are running.</para>

          <para>If the coordinator loses contact with the majority of its peers, they all cooperate to elect a new coordinator by
          majority vote. During the election, all of the Ubik processes consult the <emphasis role="bold">CellServDB</emphasis> file
          to learn where to send their votes, and what number constitutes a majority.</para>
        </listitem>

        <listitem>
          <para>The non-database server processes must know which machines are running the database server processes in order to
          retrieve information from the databases. For example, the first time that a user accesses an AFS file, the File Server
          that houses it contacts the Protection Server to obtain a list of the user's group memberships (the list is called a
          current protection subgroup, or CPS). The File Server uses the CPS as it determines if the access control list (ACL)
          protecting the file grants the required permissions to the user (for more details, see <link linkend="HDRWQ534">About the
          Protection Database</link>).</para>
        </listitem>
      </itemizedlist></para>

    <indexterm>
      <primary>CellServDB file (server)</primary>

      <secondary>effect of wrong information in</secondary>
    </indexterm>

    <para>The consequences of missing or incorrect information in the <emphasis role="bold">CellServDB</emphasis> file are as
    follows: <itemizedlist>
        <listitem>
          <para>If the file does not list a machine, then it is effectively not a database server machine even if the database
          server processes are running. The Ubik coordinator does not send it database updates or include it in the count that
          establishes a majority. It does not participate in Ubik elections, and so refuses to distribute database information to
          any client machines that happen to contact it (which they can do if their <emphasis
          role="bold">/usr/vice/etc/CellServDB</emphasis> file lists it). Users of the client machine must wait for a timeout before
          they can contact a correctly functioning database server machine.</para>
        </listitem>

        <listitem>
          <para>If the file lists a machine that is not running the database server processes, the consequences can be serious. The
          Ubik coordinator cannot send it database updates, but includes it in the count that establishes a majority. If valid
          secondary sites go down and stop sending their votes to the coordinator, it can wrongly appear that the coordinator no
          longer has the majority it needs. The resulting election of a new coordinator causes a service outage during which
          information from the database becomes unavailable. Furthermore, the lack of a vote from the incorrectly listed site can
          disturb the election, if it makes the other sites believe that a majority of sites are not voting for the new
          coordinator.</para>

          <para>A more minor consequence is that non-database server processes attempt to contact the database server processes on
          the machine. They experience a timeout delay because the processes are not running.</para>
        </listitem>
      </itemizedlist></para>

    <para>Note that the <emphasis role="bold">/usr/afs/etc/CellServDB</emphasis> file on a server machine is not the same as the
    <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file on client machine. The client version includes entries for
    foreign cells as well as the local cell. However, it is important to update both versions of the file whenever you change your
    cell's database server machines. A server machine that is also a client needs to have both files, and you need to update them
    both. For more information on maintaining the client version of the <emphasis role="bold">CellServDB</emphasis> file, see <link
    linkend="HDRWQ406">Maintaining Knowledge of Database Server Machines</link>.</para>

    <indexterm>
      <primary>system control machine</primary>

      <secondary>CellServDB file, distributing to server machines</secondary>
    </indexterm>

    <indexterm>
      <primary>distribution</primary>

      <secondary>of CellServDB file (server)</secondary>
    </indexterm>

    <indexterm>
      <primary>Update Server</primary>

      <secondary>CellServDB file (server), distributing</secondary>
    </indexterm>

    <sect2 id="HDRWQ119">
      <title>Distributing the Server CellServDB File</title>

      <para>To avoid the negative consequences of incorrect information in the <emphasis
      role="bold">/usr/afs/etc/CellServDB</emphasis> file, you must update it on all of your cell's server machines every time you
      add or remove a database server machine. The <emphasis>OpenAFS Quick Beginnings</emphasis> provides complete instructions for
      installing or removing a database server machine and for updating the <emphasis role="bold">CellServDB</emphasis> file in that
      context. This section explains how to distribute the file to your server machines and how to make other cells aware of the
      changes if you participate in the AFS global name space.</para>

      <para>If you use the Update Server to distribute the central copy of the server
      <emphasis role="bold">CellServDB</emphasis> file stored on the cell's system control machine. 
      For instructions on configuring the Update Server, see the <emphasis>OpenAFS Quick Beginnings</emphasis>.</para>

      <para>To avoid formatting errors that can cause errors, always use the <emphasis role="bold">bos addhost</emphasis> and
      <emphasis role="bold">bos removehost</emphasis> commands, rather than editing the file directly. You must also restart the
      database server processes running on the machine, to initiate a coordinator election among the new set of database server
      machines. This step is included in the instructions that appear in <link linkend="HDRWQ121">To add a database server machine
      to the CellServDB file</link> and <link linkend="HDRWQ122">To remove a database server machine from the CellServDB
      file</link>. For instructions on displaying the contents of the file, see <link linkend="HDRWQ120">To display a cell's
      database server machines</link>.</para>

      <para>If you make your cell accessible to foreign users as part of the AFS global name space, you also need to inform other
      cells when you change your cell's database server machines. The AFS Support group maintains a <emphasis
      role="bold">CellServDB</emphasis> file that lists all cells that participate in the AFS global name space, and can change your
      cell's entry at your request. For further details, see <link linkend="HDRWQ38">Making Your Cell Visible to
      Others</link>.</para>

      <para>Another way to advertise your cell's database server machines is to maintain a copy of the file at the conventional
      location in your AFS filespace, <emphasis role="bold">/afs/</emphasis><emphasis>cellname</emphasis><emphasis
      role="bold">/service/etc/CellServDB.local</emphasis>. For further discussion, see <link linkend="HDRWQ43">The Third
      Level</link>.</para>

      <indexterm>
        <primary>bos commands</primary>

        <secondary>listhosts</secondary>
      </indexterm>

      <indexterm>
        <primary>commands</primary>

        <secondary>bos listhosts</secondary>
      </indexterm>

      <indexterm>
        <primary>CellServDB file (server)</primary>

        <secondary>displaying</secondary>
      </indexterm>

      <indexterm>
        <primary>displaying</primary>

        <secondary>CellServDB file (server)</secondary>
      </indexterm>

      <indexterm>
        <primary>database server machine</primary>

        <secondary>displaying list in server CellServDB file</secondary>
      </indexterm>

      <indexterm>
        <primary>displaying</primary>

        <secondary>database server machines in server CellServDB file</secondary>
      </indexterm>
    </sect2>

    <sect2 id="HDRWQ120">
      <title>To display a cell's database server machines</title>

      <orderedlist>
        <listitem>
          <para>Issue the <emphasis role="bold">bos listhosts</emphasis> command. If you have maintained the file properly, the
          output is the same on every server machine, but the <emphasis>machine name</emphasis> argument enables you to check
          various machines if you wish. <programlisting>
   % <emphasis role="bold">bos listhosts</emphasis> &lt;<replaceable>machine name</replaceable>&gt; [&lt;<replaceable>cell name</replaceable>&gt;]
</programlisting></para>

          <para>where <variablelist>
              <varlistentry>
                <term><emphasis role="bold">listh</emphasis></term>

                <listitem>
                  <para>Is the shortest acceptable abbreviation of <emphasis role="bold">listhosts</emphasis>.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">machine name</emphasis></term>

                <listitem>
                  <para>Specifies the server machine from which to display the <emphasis
                  role="bold">/usr/afs/etc/CellServDB</emphasis> file.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">cell name</emphasis></term>

                <listitem>
                  <para>Specifies the complete Internet domain name of a foreign cell. You must already know the name of at least
                  one server machine in the cell, to provide as the <emphasis role="bold">machine name</emphasis> argument.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </listitem>
      </orderedlist>

      <para>The output lists the machines in the order they appear in the <emphasis role="bold">CellServDB</emphasis> file on the
      specified server machine. It assigns each one a <computeroutput>Host</computeroutput> index number, as in the following
      example. There is no implied relationship between the index and a machine's IP address, name, or role as Ubik coordinator or
      secondary site.</para>

      <programlisting>
   % <emphasis role="bold">bos listhosts fs1.example.com</emphasis>
   Cell name is example.com
       Host 1 is fs1.example.com
       Host 2 is fs7.example.com
       Host 3 is fs4.example.com
</programlisting>

      <para>The output lists machines by name rather than IP address as long as the naming service (such as the Domain Name Service
      or local host table) is functioning properly. To display IP addresses, login to a server machine as the local superuser
      <emphasis role="bold">root</emphasis> and use a text editor or display command, such as the <emphasis
      role="bold">cat</emphasis> command, to view the <emphasis role="bold">/usr/afs/etc/CellServDB</emphasis> file.</para>

      <indexterm>
        <primary>adding</primary>

        <secondary>database server machine</secondary>

        <tertiary>to server CellServDB file</tertiary>
      </indexterm>

      <indexterm>
        <primary>database server machine</primary>

        <secondary>adding</secondary>

        <tertiary>to server CellServDB file</tertiary>
      </indexterm>

      <indexterm>
        <primary>CellServDB file (server)</primary>

        <secondary>adding database server machine</secondary>
      </indexterm>

      <indexterm>
        <primary>adding</primary>

        <secondary>CellServDB file (server) entry for database server machine</secondary>
      </indexterm>

      <indexterm>
        <primary>database server machine</primary>

        <secondary>CellServDB file (server) entry</secondary>

        <tertiary>adding</tertiary>
      </indexterm>

      <indexterm>
        <primary>database server process</primary>

        <secondary>restarting after adding entry to server CellServDB file</secondary>
      </indexterm>

      <indexterm>
        <primary>Protection Server</primary>

        <secondary>restarting after adding entry to server CellServDB file</secondary>
      </indexterm>

      <indexterm>
        <primary>Authentication Server</primary>

        <secondary>restarting after adding entry to server CellServDB file</secondary>
      </indexterm>

      <indexterm>
        <primary>VL Server</primary>

        <secondary>restarting after adding entry to server CellServDB file</secondary>
      </indexterm>

      <indexterm>
        <primary>Backup Server</primary>

        <secondary>restarting after adding entry to server CellServDB file</secondary>
      </indexterm>

      <indexterm>
        <primary>bos commands</primary>

        <secondary>addhost</secondary>
      </indexterm>

      <indexterm>
        <primary>commands</primary>

        <secondary>bos addhost</secondary>
      </indexterm>
    </sect2>

    <sect2 id="HDRWQ121">
      <title>To add a database server machine to the CellServDB file</title>

      <orderedlist>
        <listitem>
          <para>Verify that you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue
          the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To
          display the users in the UserList file</link>. <programlisting>
   % <emphasis role="bold">bos listusers</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
</programlisting></para>
        </listitem>

        <listitem>
          <para>Issue the <emphasis role="bold">bos addhost</emphasis> command to add each new database server machine to the
          <emphasis role="bold">CellServDB</emphasis> file. Specify the system control
          machine as <emphasis>machine name</emphasis>. (If you have forgotten which machine is the system control machine, see
          <link linkend="HDRWQ99">The Output on the System Control Machine</link>.)
<programlisting>
   % <emphasis role="bold">bos addhost</emphasis>  &lt;<replaceable>machine name</replaceable>&gt;  &lt;<replaceable>host name</replaceable>&gt;+
</programlisting></para>

          <para>where <variablelist>
              <varlistentry>
                <term><emphasis role="bold">addh</emphasis></term>

                <listitem>
                  <para>Is the shortest acceptable abbreviation of <emphasis role="bold">addhost</emphasis>.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">machine name</emphasis></term>

                <listitem>
                  <para>Names the system control machine</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">host name</emphasis></term>

                <listitem>
                  <para>Specifies the fully qualified hostname of each database server machine to add to the <emphasis
                  role="bold">CellServDB</emphasis> file (for example: <emphasis role="bold">fs4.example.com</emphasis>). The BOS Server
                  uses the <emphasis role="bold">gethostbyname()</emphasis> routine to obtain each machine's IP address and records
                  both the name and address automatically.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </listitem>

        <listitem>
          <para>Restart the Authentication Server, Backup Server, Protection Server, and VL Server on every database server machine,
          so that the new set of machines participate in the election of a new Ubik coordinator. The instruction uses the
          conventional names for the processes; make the appropriate substitution if you use different process names. For complete
          syntax, see <link linkend="HDRWQ170">Stopping and Immediately Restarting Processes</link>.</para>

          <para><emphasis role="bold">Important:</emphasis> Repeat the following command in quick succession on all of the database
          server machines.</para>

          <programlisting>
   % <emphasis role="bold">bos restart</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">buserver kaserver ptserver vlserver</emphasis>
</programlisting>
        </listitem>

        <listitem>
          <para>Edit the <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file on each of your cell's client machines. For
          instructions, see <link linkend="HDRWQ406">Maintaining Knowledge of Database Server Machines</link>.</para>
        </listitem>

        <listitem>
          <para>If you participate in the AFS global name space, please have one of your cell's designated site contacts register
          the changes you have made with the AFS Product Support group.</para>

          <para>If you maintain a central copy of your cell's server <emphasis role="bold">CellServDB</emphasis> file in the
          conventional location (<emphasis role="bold">/afs/</emphasis><emphasis>cellname</emphasis><emphasis
          role="bold">/service/etc/CellServDB.local</emphasis>), edit the file to reflect the change.</para>
        </listitem>
      </orderedlist>

      <indexterm>
        <primary>removing</primary>

        <secondary>database server machine</secondary>

        <tertiary>from server CellServDB file</tertiary>
      </indexterm>

      <indexterm>
        <primary>database server machine</primary>

        <secondary>removing</secondary>

        <tertiary>from server CellServDB file</tertiary>
      </indexterm>

      <indexterm>
        <primary>CellServDB file (server)</primary>

        <secondary>removing database server machine</secondary>
      </indexterm>

      <indexterm>
        <primary>database server machine</primary>

        <secondary>CellServDB file (server) entry</secondary>

        <tertiary>removing</tertiary>
      </indexterm>

      <indexterm>
        <primary>database server process</primary>

        <secondary>restarting after removing entry from server CellServDB file</secondary>
      </indexterm>

      <indexterm>
        <primary>Protection Server</primary>

        <secondary>restarting after removing entry from server CellServDB file</secondary>
      </indexterm>

      <indexterm>
        <primary>Authentication Server</primary>

        <secondary>restarting after removing entry from server CellServDB file</secondary>
      </indexterm>

      <indexterm>
        <primary>VL Server</primary>

        <secondary>restarting after removing entry from server CellServDB file</secondary>
      </indexterm>

      <indexterm>
        <primary>Backup Server</primary>

        <secondary>restarting after removing entry from server CellServDB file</secondary>
      </indexterm>

      <indexterm>
        <primary>bos commands</primary>

        <secondary>removehost</secondary>
      </indexterm>

      <indexterm>
        <primary>commands</primary>

        <secondary>bos removehost</secondary>
      </indexterm>
    </sect2>

    <sect2 id="HDRWQ122">
      <title>To remove a database server machine from the CellServDB file</title>

      <orderedlist>
        <listitem>
          <para>Verify that you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue
          the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To
          display the users in the UserList file</link>. <programlisting>
   % <emphasis role="bold">bos listusers</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
</programlisting></para>
        </listitem>

        <listitem>
          <para>Issue the <emphasis role="bold">bos removehost</emphasis> command to remove each database server machine from the
          <emphasis role="bold">CellServDB</emphasis> file. Specify the system control
          machine as <emphasis>machine name</emphasis>. (If you have forgotten which machine is the system control machine, see
          <link linkend="HDRWQ99">The Output on the System Control Machine</link>.)
<programlisting>
   % <emphasis role="bold">bos removehost</emphasis> &lt;<replaceable>machine name</replaceable>&gt;  &lt;<replaceable>host name</replaceable>&gt;+
</programlisting></para>

          <para>where <variablelist>
              <varlistentry>
                <term><emphasis role="bold">removeh</emphasis></term>

                <listitem>
                  <para>Is the shortest acceptable abbreviation of <emphasis role="bold">removehost</emphasis>.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">machine name</emphasis></term>

                <listitem>
                  <para>Names the system control machine.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">host name</emphasis></term>

                <listitem>
                  <para>Specifies the fully qualified hostname of each database server machine to remove from the <emphasis
                  role="bold">CellServDB</emphasis> file (for example: <emphasis role="bold">fs4.example.com</emphasis>).</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </listitem>

        <listitem>
          <para>Restart the Authentication Server, Backup Server, Protection Server, and VL Server on every database server machine,
          so that the new set of machines participate in the election of a new Ubik coordinator. The instruction uses the
          conventional names for the processes; make the appropriate substitution if you use different process names. For complete
          syntax, see <link linkend="HDRWQ170">Stopping and Immediately Restarting Processes</link>.</para>

          <para><emphasis role="bold">Important:</emphasis> Repeat the following command in quick succession on all of the database
          server machines.</para>

          <programlisting>
   % <emphasis role="bold">bos restart</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">buserver kaserver ptserver vlserver</emphasis>
</programlisting>
        </listitem>

        <listitem>
          <para>Edit the <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file on each of your cell's client machines. For
          instructions, see <link linkend="HDRWQ406">Maintaining Knowledge of Database Server Machines</link>.</para>
        </listitem>

        <listitem>
          <para>If you participate in the AFS global name space, please have one of your cell's designated site contacts register
          the changes you have made with the AFS Product Support group.</para>

          <para>If you maintain a central copy of your cell's server <emphasis role="bold">CellServDB</emphasis> file in the
          conventional location (<emphasis role="bold">/afs/</emphasis><emphasis>cellname</emphasis><emphasis
          role="bold">/service/etc/CellServDB.local</emphasis>), edit the file to reflect the change.</para>
        </listitem>
      </orderedlist>
    </sect2>
  </sect1>

  <sect1 id="HDRWQ123">
    <title>Managing Authentication and Authorization Requirements</title>

    <para>This section describes how the AFS server processes guarantee that only properly authorized users perform privileged
    commands, by checking authorization checking and mutually authenticating with their clients. It explains how you can control
    authorization checking requirements on a per-machine or per-cell basis, and how to bypass mutual authentication when issuing
    commands.</para>

    <indexterm>
      <primary>authorization checking</primary>

      <secondary>compared to authentication</secondary>
    </indexterm>

    <indexterm>
      <primary>authentication</primary>

      <secondary>compared to authorization checking</secondary>
    </indexterm>

    <indexterm>
      <primary>privileged commands</primary>
    </indexterm>

    <indexterm>
      <primary>commands</primary>

      <secondary>privileged, defined</secondary>
    </indexterm>

    <indexterm>
      <primary>anonymous user</primary>

      <secondary>identity assigned to unauthenticated user</secondary>
    </indexterm>

    <indexterm>
      <primary>authorization checking</primary>

      <secondary>defined</secondary>
    </indexterm>

    <sect2 id="HDRWQ124">
      <title>Authentication versus Authorization</title>

      <para>Many AFS commands are <emphasis>privileged</emphasis> in that the AFS server process invoked by the command performs it
      only for a properly authorized user. The server process performs the following two tests to determine if someone is properly
      authorized: <itemizedlist>
          <listitem>
            <para>In the <emphasis>authentication</emphasis> test, the server process mutually authenticates with the command
            interpreter, Cache Manager, or other client process that is acting on behalf of a user or application. The goal of this
            test is to determine who is issuing the command. The server process verifies that the issuer really is who he or she
            claims to be, by examining the server ticket and other components of the issuer's token. (Secondarily, it allows the
            client process to verify that the server process is genuine.) If the issuer has no token or otherwise fails the test,
            the server process assigns him or her the identity <emphasis role="bold">anonymous</emphasis>, a completely unprivileged
            user. For a more complete description of mutual authentication, see <link linkend="HDRWQ75">A More Detailed Look at
            Mutual Authentication</link>.</para>

            <para>Many individual commands enable you to bypass the authentication test by assuming the <emphasis
            role="bold">anonymous</emphasis> identity without even attempting to mutually authenticate. Note, however, that this is
            futile if the command is privileged and the server process is still performing the <emphasis>authorization</emphasis>
            test, because in that case the process refuses to execute privileged commands for the <emphasis
            role="bold">anonymous</emphasis> user.</para>
          </listitem>

          <listitem>
            <para>In the authorization test, the server process determines if the issuer is authorized to use the command by
            consulting a list of privileged users. The goal of this test is to determine what the issuer is allowed to do. Different
            server processes consult different lists of users, as described in <link linkend="HDRWQ581">Managing Administrative
            Privilege</link>. The server process refuses to execute any privileged command for an unauthorized issuer. If a command
            has no privilege requirements, the server process skips this step and executes and immediately.</para>

            <note>
              <para>Never place the <emphasis role="bold">anonymous</emphasis> user or the <emphasis
              role="bold">system:anyuser</emphasis> group on a privilege list; it makes authorization checking meaningless.</para>

              <para>You can use the <emphasis role="bold">bos setauth</emphasis> command to control whether the server processes on
              a server machine check for authorization. Other server machines are not affected. Keep in mind that turning off
              authorization checking is a grave security risk, because the server processes on that machine perform any action for
              any user.</para>
            </note>
          </listitem>
        </itemizedlist></para>

      <indexterm>
        <primary>controlling</primary>

        <secondary>authorization checking for entire cell</secondary>
      </indexterm>

      <indexterm>
        <primary>authorization checking</primary>

        <secondary>controlling cell-wide</secondary>
      </indexterm>

      <indexterm>
        <primary>restarting</primary>

        <secondary>server process</secondary>

        <tertiary>when changing authorization checking</tertiary>
      </indexterm>

      <indexterm>
        <primary>authorization checking</primary>

        <secondary>and restarting processes</secondary>
      </indexterm>
    </sect2>

    <sect2 id="HDRWQ125">
      <title>Controlling Authorization Checking on a Server Machine</title>

      <para>Disabling authorization checking is a serious breach of security because it means that the AFS server processes on a
      file server machine performs any action for any user, even the <emphasis role="bold">anonymous</emphasis> user.</para>

      <para>The only time it is common to disable authorization checking is when installing a new file server machine (see the IBM
      AFS Quick Beginnings). It is necessary then because it is not possible to configure all of the necessary security mechanisms
      before performing other actions that normally make use of them. For greatest security, work at the console of the machine you
      are installing and enable authorization checking as soon as possible.</para>

      <para>During normal operation, the only reason to disable authorization checking is if an error occurs with the server
      encryption keys, leaving the servers unable to authenticate users properly. For instructions on handling key-related
      emergencies, see <link linkend="HDRWQ370">Handling Server Encryption Key Emergencies</link>.</para>

      <para>You control authorization checking on each file server machine separately; turning it on or off on one machine does not
      affect the others. Because client machines generally choose a server process at random, it is hard to predict what
      authorization checking conditions prevail for a given command unless you make the requirement the same on all machines. To
      turn authorization checking on or off for the entire cell, you must repeat the appropriate command on every file server
      machine.</para>

      <para>The server processes constantly monitor the directory <emphasis role="bold">/usr/afs/local</emphasis> on their local
      disks to determine if they need to check for authorization. If the file called <emphasis role="bold">NoAuth</emphasis> appears
      in that directory, then the servers do not check for authorization. When it is not present (the usual case), they perform
      authorization checking.</para>

      <para>Control the presence of the <emphasis role="bold">NoAuth</emphasis> file through the BOS Server. When you disable
      authorization checking with the <emphasis role="bold">bos setauth</emphasis> command (or, during installation, by putting the
      <emphasis role="bold">-noauth</emphasis> flag on the command that starts up the BOS Server), the BOS Server creates the
      zero-length <emphasis role="bold">NoAuth</emphasis> file. When you reenable authorization checking, the BOS Server removes the
      file.</para>

      <indexterm>
        <primary>bos commands</primary>

        <secondary>setauth</secondary>
      </indexterm>

      <indexterm>
        <primary>commands</primary>

        <secondary>bos setauth</secondary>
      </indexterm>

      <indexterm>
        <primary>authorization checking</primary>

        <secondary>disabling</secondary>
      </indexterm>

      <indexterm>
        <primary>turning off authorization checking</primary>
      </indexterm>

      <indexterm>
        <primary>disabling</primary>

        <secondary>authorization checking</secondary>
      </indexterm>
    </sect2>

    <sect2 id="HDRWQ126">
      <title>To disable authorization checking on a server machine</title>

      <orderedlist>
        <listitem>
          <para>Verify that you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue
          the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To
          display the users in the UserList file</link>. <programlisting>
   % <emphasis role="bold">bos listusers</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
</programlisting></para>
        </listitem>

        <listitem>
          <para>Issue the <emphasis role="bold">bos setauth</emphasis> command to disable authorization checking. <programlisting>
   % <emphasis role="bold">bos setauth</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">off</emphasis>
</programlisting></para>

          <para>where <variablelist>
              <varlistentry>
                <term><emphasis role="bold">seta</emphasis></term>

                <listitem>
                  <para>Is the shortest acceptable abbreviation of <emphasis role="bold">setauth</emphasis>.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">machine name</emphasis></term>

                <listitem>
                  <para>Specifies the file server machine on which server processes do not check for authorization.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </listitem>
      </orderedlist>

      <indexterm>
        <primary>authorization checking</primary>

        <secondary>enabling</secondary>
      </indexterm>

      <indexterm>
        <primary>enabling authorization checking</primary>
      </indexterm>

      <indexterm>
        <primary>turning on authorization checking</primary>
      </indexterm>
    </sect2>

    <sect2 id="HDRWQ127">
      <title>To enable authorization checking on a server machine</title>

      <orderedlist>
        <listitem>
          <para>Reenable authorization checking. (No privilege is required because the machine is not currently checking for
          authorization.) For detailed syntax information, see the preceding section. <programlisting>
   % <emphasis role="bold">bos setauth</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">on</emphasis>
</programlisting></para>
        </listitem>
      </orderedlist>

      <indexterm>
        <primary>mutual authentication</primary>

        <secondary>preventing</secondary>
      </indexterm>

      <indexterm>
        <primary>preventing</primary>

        <secondary>mutual authentication</secondary>
      </indexterm>
    </sect2>

    <sect2 id="HDRWQ128">
      <title>Bypassing Mutual Authentication for an Individual Command</title>

      <para>Several of the server processes allow any user (not just system administrators) to disable mutual authentication when
      issuing a command. The server process treats the issuer as the unauthenticated user <emphasis
      role="bold">anonymous</emphasis>.</para>

      <para>The facilities for preventing mutual authentication are provided for use in emergencies (such as the key emergency
      discussed in <link linkend="HDRWQ370">Handling Server Encryption Key Emergencies</link>). During normal circumstances,
      authorization checking is turned on, making it useless to prevent authentication: the server processes refuse to perform
      privileged commands for the user <emphasis role="bold">anonymous</emphasis>.</para>

      <para>It can be useful to prevent authentication when authorization checking is turned off. The very act of trying to
      authenticate can cause problems if the server cannot understand a particular encryption key, as is likely to happen in a key
      emergency.</para>

      <indexterm>
        <primary>bos commands</primary>

        <secondary>mutual authentication, bypassing</secondary>
      </indexterm>

      <indexterm>
        <primary>kas commands</primary>

        <secondary>mutual authentication, bypassing</secondary>
      </indexterm>

      <indexterm>
        <primary>pts commands</primary>

        <secondary>mutual authentication, bypassing</secondary>
      </indexterm>

      <indexterm>
        <primary>vos commands</primary>

        <secondary>mutual authentication, bypassing</secondary>
      </indexterm>

      <indexterm>
        <primary>kas commands</primary>

        <secondary>interactive</secondary>
      </indexterm>

      <indexterm>
        <primary>commands</primary>

        <secondary>kas interactive</secondary>
      </indexterm>

      <indexterm>
        <primary>entering</primary>

        <secondary>kas interactive mode</secondary>
      </indexterm>

      <indexterm>
        <primary>interactive mode (kas commands)</primary>
      </indexterm>
    </sect2>

    <sect2 id="HDRWQ129">
      <title>To bypass mutual authentication for bos, kas, pts, and vos commands</title>

      <para>Provide the <emphasis role="bold">-noauth</emphasis> flag which is available on many of the commands in the suites. To
      verify that a command accepts the flag, issue the <emphasis role="bold">help</emphasis> command in its suite, or consult the
      command's reference page in the <emphasis>OpenAFS Administration Reference</emphasis> (the reference page also specifies the
      shortest acceptable abbreviation for the flag on each command). The suites' <emphasis role="bold">apropos</emphasis> and
      <emphasis role="bold">help</emphasis> commands do not themselves accept the flag.</para>

      <para>You can bypass mutual authentication for all <emphasis role="bold">kas</emphasis> commands issued during an interactive
      session by including the <emphasis role="bold">-noauth</emphasis> flag on the <emphasis role="bold">kas interactive</emphasis>
      command. If you have already entered interactive mode with an authenticated identity, issue the <emphasis role="bold">(kas)
      noauthentication</emphasis> command to assume the <emphasis role="bold">anonymous</emphasis> identity.</para>

      <indexterm>
        <primary>fs commands</primary>

        <secondary>mutual authentication, bypassing</secondary>
      </indexterm>
    </sect2>

    <sect2 id="Header_151">
      <title>To bypass mutual authentication for fs commands</title>

      <para>This is not possible, except by issuing the <emphasis role="bold">unlog</emphasis> command to discard your tokens before
      issuing the <emphasis role="bold">fs</emphasis> command.</para>
    </sect2>
  </sect1>

  <sect1 id="HDRWQ130">
    <title>Adding or Removing Disks and Partitions</title>

    <para>AFS makes it very easy to add storage space to your cell, just by adding disks to existing file server machines. This
    section explains how to install or remove a disk used to store AFS volumes. (Another way to add storage space is to install
    additional server machines, as instructed in the <emphasis>OpenAFS Quick Beginnings</emphasis>.)</para>

    <para>Both adding and removing a disk cause at least a brief file system outage, because you must restart the <emphasis
    role="bold">fs</emphasis> process to have it recognize the new set of server partitions. Some operating systems require that you
    shut the machine off before adding or removing a disk, in which case you must shut down all of the AFS server processes first.
    Otherwise, the AFS-related aspects of adding or removing a disk are not complicated, so the duration of the outage depends
    mostly on how long it takes to install or remove the disk itself.</para>

    <para>The following instructions for installing a new disk completely prepare it to house AFS volumes. You can then use the
    <emphasis role="bold">vos create</emphasis> command to create new volumes, or the <emphasis role="bold">vos move</emphasis>
    command to move existing ones from other partitions. For instructions, see <link linkend="HDRWQ185">Creating Read/write
    Volumes</link> and <link linkend="HDRWQ226">Moving Volumes</link>. The instructions for removing a disk are basically the
    reverse of the installation instructions, but include extra steps that protect against data loss.</para>

    <para>A server machines can house 256 AFS server partitions, each one mounted at a directory with a name of the form <emphasis
    role="bold">/vicep</emphasis><emphasis>index</emphasis>, where <emphasis>index</emphasis> is one or two lowercase letters. By
    convention, the first partition on a machine is mounted at <emphasis role="bold">/vicepa</emphasis>, the second at <emphasis
    role="bold">/vicepb</emphasis>, and so on to the twenty-sixth at <emphasis role="bold">/vicepz</emphasis>. Additional partitions
    are mounted at <emphasis role="bold">/vicepaa</emphasis> through <emphasis role="bold">/vicepaz</emphasis> and so on up to
    <emphasis role="bold">/vicepiv</emphasis>. Using the letters consecutively is not required, but is simpler.</para>

    <para>Mount each <emphasis role="bold">/vicep</emphasis> directory directly under the local file system's root directory (
    <emphasis role="bold">/</emphasis> ), not as a subdirectory of any other directory; for example, <emphasis
    role="bold">/usr/vicepa</emphasis> is not an acceptable location. You must also map the directory to the partition's device name
    in the file server machine's file systems registry file (<emphasis role="bold">/etc/fstab</emphasis> or equivalent).</para>

    <para>These instructions assume that the machine's AFS initialization file includes the following command to restart the BOS
    Server after each reboot. The BOS Server starts the other AFS server processes listed in the local <emphasis
    role="bold">/usr/afs/local/BosConfig</emphasis> file. For information on the <emphasis role="bold">bosserver</emphasis>
    command's optional arguments, see its reference page in the <emphasis>OpenAFS Administration Reference</emphasis>.</para>

    <programlisting>
   /usr/afs/bin/bosserver
</programlisting>

    <indexterm>
      <primary>adding</primary>

      <secondary>disk to file server machine</secondary>
    </indexterm>

    <indexterm>
      <primary>installing</primary>

      <secondary>disk on file server machine</secondary>
    </indexterm>

    <indexterm>
      <primary>disk</primary>

      <secondary>file server machine</secondary>

      <tertiary>adding/installing</tertiary>
    </indexterm>

    <indexterm>
      <primary>file server machine</primary>

      <secondary>disk</secondary>

      <tertiary>adding/installing</tertiary>
    </indexterm>

    <indexterm>
      <primary>mounting</primary>

      <secondary>disk on file server machine</secondary>
    </indexterm>

    <indexterm>
      <primary>commands</primary>

      <secondary>vos listpart</secondary>
    </indexterm>

    <indexterm>
      <primary>vos commands</primary>

      <secondary>listpart</secondary>
    </indexterm>

    <sect2 id="HDRWQ131">
      <title>To add and mount a new disk to house AFS volumes</title>

      <orderedlist>
        <listitem>
          <para>Become the local superuser <emphasis role="bold">root</emphasis> on the machine, if you are not already, by issuing
          the <emphasis role="bold">su</emphasis> command. <programlisting>
   % <emphasis role="bold">su root</emphasis>
   Password: <replaceable>root_password</replaceable>
</programlisting></para>
        </listitem>

        <listitem>
          <para>Decide how many AFS partitions to divide the new disk into and the names of the directories at which to mount them
          (the introduction to this section describes the naming conventions). To display the names of the existing server
          partitions on the machine, issue the <emphasis role="bold">vos listpart</emphasis> command. Include the <emphasis
          role="bold">-localauth</emphasis> flag because you are logged in as the local superuser <emphasis
          role="bold">root</emphasis> but do not necessarily have administrative tokens. <programlisting>
   # <emphasis role="bold">vos listpart</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">-localauth</emphasis>
</programlisting></para>

          <para>where <variablelist>
              <varlistentry>
                <term><emphasis role="bold">listp</emphasis></term>

                <listitem>
                  <para>Is the shortest acceptable abbreviation of <emphasis role="bold">listpart</emphasis>.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">machine name</emphasis></term>

                <listitem>
                  <para>Names the local file server machine.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-localauth</emphasis></term>

                <listitem>
                  <para>Constructs a server ticket using a key from the local <emphasis role="bold">/usr/afs/etc/KeyFile</emphasis>
                  file. The <emphasis role="bold">bos</emphasis> command interpreter presents it to the BOS Server during mutual
                  authentication.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </listitem>

        <listitem>
          <para>Create each directory at which to mount a partition. <programlisting>
   # <emphasis role="bold">mkdir /vicep</emphasis><replaceable>x</replaceable>[<replaceable>x</replaceable>]
</programlisting></para>

          <indexterm>
            <primary>files</primary>

            <secondary>file systems registry (fstab)</secondary>
          </indexterm>

          <indexterm>
            <primary>file systems registry file</primary>

            <secondary>adding new disk to file server machine</secondary>
          </indexterm>

          <indexterm>
            <primary>etc/fstab file</primary>

            <secondary></secondary>

            <see>file systems registry file</see>
          </indexterm>

          <indexterm>
            <primary>fstab file</primary>

            <secondary></secondary>

            <see>file systems registry file</see>
          </indexterm>
        </listitem>

        <listitem id="LIWQ132">
          <para>Using a text editor, create an entry in the machine's file systems registry file (<emphasis
          role="bold">/etc/fstab</emphasis> or equivalent) for each new disk partition, mapping its device name to the directory you
          created in the previous step. Refer to existing entries in the file to learn the proper format, which varies for different
          operating systems.</para>
        </listitem>

        <listitem id="LIWQ133">
          <para>If the operating system requires that you shut off the machine to install a new disk, issue
          the <emphasis role="bold">bos shutdown</emphasis> command to shut down all AFS server processes other than the BOS Server
          (it terminates safely when you shut off the machine). Include the <emphasis role="bold">-localauth</emphasis> flag because
          you are logged in as the local superuser <emphasis role="bold">root</emphasis> but do not necessarily have administrative
          tokens. For a complete description of the command, see <link linkend="HDRWQ168">To stop processes temporarily</link>.
          <programlisting>
   # <emphasis role="bold">bos shutdown</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">-localauth</emphasis> [<emphasis
                role="bold">-wait</emphasis>]
</programlisting></para>
        </listitem>

        <listitem id="LIWQ134">
          <para>If necessary, shut off the machine. Install and format the new disk according to the
          instructions provided by the disk and operating system vendors. If necessary, edit the disk's partition table to reflect
          the changes you made to the files system registry file in step <link linkend="LIWQ132">4</link>; consult the operating
          system documentation for instructions.</para>
        </listitem>

        <listitem>
          <para>If you shut off the machine down in step <link linkend="LIWQ134">6</link>, turn it on. Otherwise, issue the
          <emphasis role="bold">bos restart</emphasis> command to restart the <emphasis role="bold">fs</emphasis> process, forcing
          it to recognize the new set of server partitions. Include the <emphasis role="bold">-localauth</emphasis> flag because you
          are logged in as the local superuser <emphasis role="bold">root</emphasis> but do not necessarily have administrative
          tokens. For complete instructions for the <emphasis role="bold">bos restart</emphasis> command, see <link
          linkend="HDRWQ170">Stopping and Immediately Restarting Processes</link>. <programlisting>
   # <emphasis role="bold">bos restart</emphasis> &lt;<replaceable>machine name</replaceable>&gt;  <emphasis role="bold">fs -localauth</emphasis>
</programlisting></para>
        </listitem>

        <listitem>
          <para>Issue the <emphasis role="bold">bos status</emphasis> command to verify that all server processes are running
          correctly. For more detailed instructions, see <link linkend="HDRWQ158">Displaying Process Status and Information from the
          BosConfig File</link>. <programlisting>
   # <emphasis role="bold">bos status</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
</programlisting></para>
        </listitem>
      </orderedlist>

      <indexterm>
        <primary>removing</primary>

        <secondary>disk from file server machine</secondary>
      </indexterm>

      <indexterm>
        <primary>disk</primary>

        <secondary>file server machine</secondary>

        <tertiary>removing</tertiary>
      </indexterm>

      <indexterm>
        <primary>file server machine</primary>

        <secondary>disk</secondary>

        <tertiary>removing</tertiary>
      </indexterm>

      <indexterm>
        <primary>unmounting</primary>

        <secondary>file server machine disk</secondary>
      </indexterm>

      <indexterm>
        <primary>vos commands</primary>

        <secondary>move</secondary>

        <tertiary>when removing file server machine disk</tertiary>
      </indexterm>
    </sect2>

    <sect2 id="HDRWQ135">
      <title>To unmount and remove a disk housing AFS volumes</title>

      <orderedlist>
        <listitem>
          <para>Verify that you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue
          the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To
          display the users in the UserList file</link>. <programlisting>
   % <emphasis role="bold">bos listusers</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
</programlisting></para>
        </listitem>

        <listitem>
          <para>Issue the <emphasis role="bold">vos listvol</emphasis> command to list the volumes housed on each partition of each
          disk you are about to remove, in preparation for removing them or moving them to other partitions. For detailed
          instructions, see <link linkend="HDRWQ219">Displaying Volume Headers</link>. <programlisting>
   % <emphasis role="bold">vos listvol</emphasis> &lt;<replaceable>machine name</replaceable>&gt; [&lt;<replaceable>partition name</replaceable>&gt;]
</programlisting></para>
        </listitem>

        <listitem>
          <para>Move any volume you wish to retain in the file system to another partition. You can move only read/write volumes.
          For more detailed instructions, and for instructions on moving read-only and backup volumes, see <link
          linkend="HDRWQ226">Moving Volumes</link>. <programlisting>
   % <emphasis role="bold">vos move</emphasis>  &lt;<replaceable>volume name or ID</replaceable>&gt;  \
        &lt;<replaceable>machine name on source</replaceable>&gt; &lt;<replaceable>partition name on source</replaceable>&gt;  \
        &lt;<replaceable>machine name on destination</replaceable>&gt; &lt;<replaceable>partition name on destination</replaceable>&gt;
</programlisting></para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">(Optional)</emphasis> If there are any volumes you do not wish to retain, back them up using
          the <emphasis role="bold">vos dump</emphasis> command or the AFS Backup System. See <link linkend="HDRWQ240">Dumping and
          Restoring Volumes</link> or <link linkend="HDRWQ296">Backing Up Data</link>, respectively.</para>
        </listitem>

        <listitem>
          <para>Become the local superuser <emphasis role="bold">root</emphasis> on the machine, if you are not already, by issuing
          the <emphasis role="bold">su</emphasis> command. <programlisting>
   % <emphasis role="bold">su root</emphasis>
   Password: <replaceable>root_password</replaceable>
</programlisting></para>

          <indexterm>
            <primary>umount command</primary>
          </indexterm>

          <indexterm>
            <primary>commands</primary>

            <secondary>umount</secondary>
          </indexterm>
        </listitem>

        <listitem>
          <para>Issue the <emphasis role="bold">umount</emphasis> command, repeating it for each partition on the disk to be
          removed. <programlisting>
   # <emphasis role="bold">cd /</emphasis>
   # <emphasis role="bold">umount /dev/</emphasis>&lt;<replaceable>partition_block_device_name</replaceable>&gt;
</programlisting></para>

          <indexterm>
            <primary>file systems registry file</primary>

            <secondary>removing disk from file server machine</secondary>
          </indexterm>
        </listitem>

        <listitem id="LIWQ136">
          <para>Using a text editor, remove or comment out each partition's entry from the machine's file
          systems registry file (<emphasis role="bold">/etc/fstab</emphasis> or equivalent).</para>
        </listitem>

        <listitem>
          <para>Remove the <emphasis role="bold">/vicep</emphasis> directory associated with each partition. <programlisting>
   # <emphasis role="bold">rmdir /vicep</emphasis>xx
</programlisting></para>
        </listitem>

        <listitem>
          <para>If the operating system requires that you shut off the machine to remove a disk, issue the <emphasis role="bold">bos
          shutdown</emphasis> command to shut down all AFS server processes other than the BOS Server (it terminates safely when you
          shut off the machine). Include the <emphasis role="bold">-localauth</emphasis> flag because you are logged in as the local
          superuser <emphasis role="bold">root</emphasis> but do not necessarily have administrative tokens. For a complete
          description of the command, see <link linkend="HDRWQ168">To stop processes temporarily</link>. <programlisting>
   # <emphasis role="bold">bos shutdown</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">-localauth</emphasis> [<emphasis
                role="bold">-wait</emphasis>]
</programlisting></para>
        </listitem>

        <listitem id="LIWQ137">
          <para>If necessary, shut off the machine. Remove the disk according to the instructions provided by
          the disk and operating system vendors. If necessary, edit the disk's partition table to reflect the changes you made to
          the files system registry file in step <link linkend="LIWQ136">7</link>; consult the operating system documentation for
          instructions.</para>
        </listitem>

        <listitem>
          <para>If you shut off the machine down in step <link linkend="LIWQ137">10</link>, turn it on. Otherwise, issue the
          <emphasis role="bold">bos restart</emphasis> command to restart the <emphasis role="bold">fs</emphasis> process, forcing
          it to recognize the new set of server partitions. Include the <emphasis role="bold">-localauth</emphasis> flag because you
          are logged in as the local superuser <emphasis role="bold">root</emphasis> but do not necessarily have administrative
          tokens. For complete instructions for the <emphasis role="bold">bos restart</emphasis> command, see <link
          linkend="HDRWQ170">Stopping and Immediately Restarting Processes</link>. <programlisting>
   # <emphasis role="bold">bos restart</emphasis> &lt;<replaceable>machine name</replaceable>&gt;  <emphasis role="bold">fs -localauth</emphasis>
</programlisting></para>
        </listitem>

        <listitem>
          <para>Issue the <emphasis role="bold">bos status</emphasis> command to verify that all server processes are running
          correctly. For more detailed instructions, see <link linkend="HDRWQ158">Displaying Process Status and Information from the
          BosConfig File</link>. <programlisting>
   # <emphasis role="bold">bos status</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
</programlisting></para>
        </listitem>
      </orderedlist>

      <indexterm>
        <primary>File Server</primary>

        <secondary>use of NetInfo file</secondary>
      </indexterm>

      <indexterm>
        <primary>File Server</primary>

        <secondary>use of NetRestrict file</secondary>
      </indexterm>

      <indexterm>
        <primary>File Server</primary>

        <secondary>use of sysid file</secondary>
      </indexterm>

      <indexterm>
        <primary>Ubik</primary>

        <secondary>use of NetInfo and NetRestrict files</secondary>
      </indexterm>

      <indexterm>
        <primary>database server machine</primary>

        <secondary>use of NetInfo and NetRestrict files</secondary>
      </indexterm>

      <indexterm>
        <primary>File Server</primary>

        <secondary>interfaces registered in VLDB server entry</secondary>
      </indexterm>

      <indexterm>
        <primary>setting</primary>

        <secondary>server machine interfaces registered in VLDB</secondary>
      </indexterm>

      <indexterm>
        <primary>controlling</primary>

        <secondary>server machine interfaces registered in VLDB</secondary>
      </indexterm>

      <indexterm>
        <primary>displaying</primary>

        <secondary>server entries from VLDB</secondary>
      </indexterm>

      <indexterm>
        <primary>displaying</primary>

        <secondary>VLDB server entries</secondary>
      </indexterm>

      <indexterm>
        <primary>server entry in VLDB</primary>
      </indexterm>
    </sect2>
  </sect1>

  <sect1 id="HDRWQ138">
    <title>Managing Server IP Addresses and VLDB Server Entries</title>

    <para>The AFS support for multihomed file server machines is largely automatic. The File Server process records the IP addresses
    of its file server machine's network interfaces in the local <emphasis role="bold">/usr/afs/local/sysid</emphasis> file and also
    registers them in a <emphasis>server entry</emphasis> in the Volume Location Database (VLDB). The <emphasis
    role="bold">sysid</emphasis> file and server entry are identified by the same unique number, which creates an association
    between them.</para>

    <para>When the Cache Manager requests volume location information, the Volume Location (VL) Server provides all of the
    interfaces registered for each server machine that houses the volume. This enables the Cache Manager to make use of multiple
    addresses when accessing AFS data stored on a multihomed file server machine.</para>

    <para>If you wish, you can control which interfaces the File Server registers in its VLDB server entry by creating two files in
    the local <emphasis role="bold">/usr/afs/local</emphasis> directory: <emphasis role="bold">NetInfo</emphasis> and <emphasis
    role="bold">NetRestrict</emphasis>. Each time the File Server restarts, it builds a list of the local machine's interfaces by
    reading the <emphasis role="bold">NetInfo</emphasis> file, if it exists. If you do not create the file, the File Server uses the
    list of network interfaces configured with the operating system. It then removes from the list any addresses that appear in the
    <emphasis role="bold">NetRestrict</emphasis> file, if it exists. The File Server records the resulting list in the <emphasis
    role="bold">sysid</emphasis> file and registers the interfaces in the VLDB server entry that has the same unique
    identifier.</para>

    <para>On database server machines, the <emphasis role="bold">NetInfo</emphasis> and <emphasis role="bold">NetRestrict</emphasis>
    files also determine which interfaces the Ubik database synchronization library uses when communicating with the database server
    processes running on other database server machines.</para>

    <para>There is a maximum number of IP addresses in each server entry, as documented in the <emphasis>OpenAFS Release
    Notes</emphasis>. If a multihomed file server machine has more interfaces than the maximum, AFS simply ignores the excess ones.
    It is probably appropriate for such machines to use the <emphasis role="bold">NetInfo</emphasis> and <emphasis
    role="bold">NetRestrict</emphasis> files to control which interfaces are registered.</para>

    <para>If for some reason the <emphasis role="bold">sysid</emphasis> file no longer exists, the File Server creates a new one
    with a new unique identifier. When the File Server registers the contents of the new file, the Volume Location (VL) Server
    normally recognizes automatically that the new file corresponds to an existing server entry, and overwrites the existing server
    entry with the new file contents and identifier. However, it is best not to remove the <emphasis role="bold">sysid</emphasis>
    file if that can be avoided.</para>

    <para>Similarly, it is important not to copy the <emphasis role="bold">sysid</emphasis> file from one file server machine to
    another. If you commonly copy the contents of the <emphasis role="bold">/usr/afs</emphasis> directory from an existing machine
    as part of installing a new file server machine, be sure to remove the <emphasis role="bold">sysid</emphasis> file from the
    <emphasis role="bold">/usr/afs/local</emphasis> directory on the new machine before starting the File Server.</para>

    <para>There are certain cases where the VL Server cannot determine whether it is appropriate to overwrite an existing server
    entry with a new <emphasis role="bold">sysid</emphasis> file's contents and identifier. It then refuses to allow the File Server
    to register the interfaces, which prevents the File Server from starting. This can happen if, for example, a new <emphasis
    role="bold">sysid</emphasis> file includes two interfaces that currently are registered by themselves in separate server
    entries. In such cases, error messages in the <emphasis role="bold">/usr/afs/log/VLLog</emphasis> file on the VL Server machine
    and in the <emphasis role="bold">/usr/afs/log/FileLog</emphasis> file on the file server machine indicate that you need to use
    the <emphasis role="bold">vos changeaddr</emphasis> command to resolve the problem. Contact the AFS Product Support group for
    instructions and assistance.</para>

    <para>Except in this type of rare error case, the only appropriate use of the <emphasis role="bold">vos changeaddr</emphasis>
    command is to remove a VLDB server entry completely when you remove a file server machine from service. The VLDB can accommodate
    a maximum number of server entries, as specified in the <emphasis>OpenAFS Release Notes</emphasis>. Removing obsolete entries
    makes it possible to allocate server entries for new file server machines as required. See the instructions that follow.</para>

    <para>Do not use the <emphasis role="bold">vos changeaddr</emphasis> command to change the list of interfaces registered in a
    VLDB server entry. To change a file server machine's IP addresses and server entry, see the instructions that follow.</para>

    <indexterm>
      <primary>NetInfo file (server version)</primary>

      <secondary>creating/editing</secondary>
    </indexterm>

    <indexterm>
      <primary>creating</primary>

      <secondary>NetInfo file (server version)</secondary>
    </indexterm>

    <indexterm>
      <primary>editing</primary>

      <secondary>NetInfo file (server version)</secondary>
    </indexterm>

    <sect2 id="Header_156">
      <title>To create or edit the server NetInfo file</title>

      <orderedlist>
        <listitem>
          <para>Become the local superuser <emphasis role="bold">root</emphasis> on the machine, if you are not already, by issuing
          the <emphasis role="bold">su</emphasis> command. <programlisting>
   % <emphasis role="bold">su root</emphasis>
   Password: <replaceable>root_password</replaceable>
</programlisting></para>
        </listitem>

        <listitem>
          <para>Using a text editor, open the <emphasis role="bold">/usr/afs/local/NetInfo</emphasis> file. Place one IP address in
          dotted decimal format (for example, <computeroutput>192.12.107.33</computeroutput>) on each line. The order of entries is
          not significant.</para>
        </listitem>

        <listitem>
          <para>If you want the File Server to start using the revised list immediately, use the <emphasis role="bold">bos
          restart</emphasis> command to restart the <emphasis role="bold">fs</emphasis> process. For instructions, see <link
          linkend="HDRWQ170">Stopping and Immediately Restarting Processes</link>.</para>
        </listitem>
      </orderedlist>

      <indexterm>
        <primary>NetRestrict file (server version)</primary>

        <secondary>creating/editing</secondary>
      </indexterm>

      <indexterm>
        <primary>creating</primary>

        <secondary>NetRestrict file (server version)</secondary>
      </indexterm>

      <indexterm>
        <primary>editing</primary>

        <secondary>NetRestrict file (server version)</secondary>
      </indexterm>
    </sect2>

    <sect2 id="Header_157">
      <title>To create or edit the server NetRestrict file</title>

      <orderedlist>
        <listitem>
          <para>Become the local superuser <emphasis role="bold">root</emphasis> on the machine, if you are not already, by issuing
          the <emphasis role="bold">su</emphasis> command. <programlisting>
   % <emphasis role="bold">su root</emphasis>
   Password: <replaceable>root_password</replaceable>
</programlisting></para>
        </listitem>

        <listitem>
          <para>Using a text editor, open the <emphasis role="bold">/usr/afs/local/NetRestrict</emphasis> file. Place one IP address
          in dotted decimal format on each line. The order of the addresses is not significant. Use a slash (<emphasis
          role="bold">/</emphasis>) followed by a subnet length to represent all possible addresses in a range. For example, the entry
          <computeroutput>192.12.105.0/24</computeroutput> indicates that the Cache Manager does not register any of the addresses in
          the 192.12.105 subnet.</para>
        </listitem>

        <listitem>
          <para>If you want the File Server to start using the revised list immediately, use the <emphasis role="bold">bos
          restart</emphasis> command to restart the <emphasis role="bold">fs</emphasis> process. For instructions, see <link
          linkend="HDRWQ170">Stopping and Immediately Restarting Processes</link>.</para>
        </listitem>
      </orderedlist>

      <indexterm>
        <primary>vos commands</primary>

        <secondary>listaddrs</secondary>
      </indexterm>

      <indexterm>
        <primary>commands</primary>

        <secondary>vos listaddrs</secondary>
      </indexterm>
    </sect2>

    <sect2 id="Header_158">
      <title>To display all server entries from the VLDB</title>

      <orderedlist>
        <listitem>
          <para>Issue the <emphasis role="bold">vos listaddrs</emphasis> command to display all server entries from the VLDB.
          <programlisting>
   % <emphasis role="bold">vos listaddrs</emphasis>
</programlisting></para>

          <para>where <emphasis role="bold">lista</emphasis> is the shortest acceptable abbreviation of <emphasis
          role="bold">listaddrs</emphasis>.</para>

          <para>The output displays all server entries from the VLDB, each on its own line. If a file server machine is multihomed,
          all of its registered addresses appear on the line. The first one is the one reported as a volume's site in the output
          from the <emphasis role="bold">vos examine</emphasis> and <emphasis role="bold">vos listvldb</emphasis> commands.</para>

          <para>VLDB server entries record IP addresses, and the command interpreter has the local name service (either a process
          like the Domain Name Service or a local host table) translate them to hostnames before displaying them. If an IP address
          appears in the output, it is not possible to translate it.</para>

          <para>The existence of an entry does not necessarily indicate that the machine that is still an active file server
          machine. To remove obsolete server entries, see the following instructions.</para>
        </listitem>
      </orderedlist>

      <indexterm>
        <primary>vos commands</primary>

        <secondary>changeaddr</secondary>
      </indexterm>

      <indexterm>
        <primary>commands</primary>

        <secondary>vos changeaddr</secondary>
      </indexterm>
    </sect2>

    <sect2 id="Header_159">
      <title>To remove obsolete server entries from the VLDB</title>

      <orderedlist>
        <listitem>
          <para>Verify that you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue
          the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To
          display the users in the UserList file</link>. <programlisting>
   % <emphasis role="bold">bos listusers</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
</programlisting></para>
        </listitem>

        <listitem>
          <para>Issue the <emphasis role="bold">vos changeaddr</emphasis> command to remove a server entry from the VLDB.
          <programlisting>
   % <emphasis role="bold">vos changeaddr</emphasis> &lt;<replaceable>original IP address</replaceable>&gt; <emphasis role="bold">-remove</emphasis>
</programlisting></para>

          <para>where <variablelist>
              <varlistentry>
                <term><emphasis role="bold">ch</emphasis></term>

                <listitem>
                  <para>Is the shortest acceptable abbreviation of <emphasis role="bold">changeaddr</emphasis>.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">original IP address</emphasis></term>

                <listitem>
                  <para>Specifies one of the IP addresses currently registered for the file server machine in the VLDB. Any of a
                  multihomed file server machine's addresses are acceptable to identify it.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">-remove</emphasis></term>

                <listitem>
                  <para>Removes the server entry.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </listitem>
      </orderedlist>
    </sect2>

    <sect2 id="Header_160">
      <title>To change a server machine's IP addresses</title>

      <orderedlist>
        <listitem>
          <para>Verify that you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue
          the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To
          display the users in the UserList file</link>. <programlisting>
   % <emphasis role="bold">bos listusers</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
</programlisting></para>
        </listitem>

        <listitem>
          <para>If the machine is the system control machine or a binary distribution machine, and you are also changing its
          hostname, redefine all relevant <emphasis role="bold">upclient</emphasis> processes on other server machines to refer to
          the new hostname. Use the <emphasis role="bold">bos delete</emphasis> and <emphasis role="bold">bos create</emphasis>
          commands as instructed in <link linkend="HDRWQ161">Creating and Removing Processes</link>.</para>
        </listitem>

        <listitem>
          <para>If the machine is a database server machine, edit its entry in the <emphasis
          role="bold">/usr/afs/etc/CellServDB</emphasis> file on every server machine in the cell to list one of the new IP
          addresses. You can edit the file on the system control machine and wait the
          required time (by default, five minutes) for the Update Server to distribute the changed file to all server
          machines.</para>
        </listitem>

        <listitem>
          <para>If the machine is a database server machine, issue the <emphasis role="bold">bos shutdown</emphasis> command to stop
          all server processes. If the machine is also a file server, the volumes on it are inaccessible during this time. For a
          complete description of the command, see <link linkend="HDRWQ168">To stop processes temporarily</link>. <programlisting>
   % <emphasis role="bold">bos shutdown</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
</programlisting></para>
        </listitem>

        <listitem>
          <para>Use the utilities provided with the operating system to change one or more of the machine's IP addresses.</para>
        </listitem>

        <listitem>
          <para>If appropriate, edit the <emphasis role="bold">/usr/afs/local/NetInfo</emphasis> file, the <emphasis
          role="bold">/usr/afs/local/NetRestrict</emphasis> file, or both, to reflect the changed addresses. Instructions appear
          earlier in this section.</para>
        </listitem>

        <listitem>
          <para>If the machine is a database server machine, issue the <emphasis role="bold">bos restart</emphasis> command to
          restart all server processes on the machine. For complete instructions for the <emphasis role="bold">bos
          restart</emphasis> command, see <link linkend="HDRWQ170">Stopping and Immediately Restarting Processes</link>.
          <programlisting>
   % <emphasis role="bold">bos restart</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">-all</emphasis>
</programlisting></para>

          <para>At the same time, issue the <emphasis role="bold">bos restart</emphasis> command on all other database server
          machines in the cell to restart the database server processes only (the Authentication, Backup, Protection, and Volume
          Location Servers). Issue the commands in quick succession so that all of the database server processes vote in the quorum
          election.</para>

          <programlisting>
   % <emphasis role="bold">bos restart</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">kaserver buserver ptserver vlserver</emphasis>
</programlisting>

          <para>If you are changing IP addresses on every database server machine in the cell, you must also issue the <emphasis
          role="bold">bos restart</emphasis> command on every file server machine in the cell to restart the <emphasis
          role="bold">fs</emphasis> process.</para>
        </listitem>

        <listitem>
          <para>If the machine is not a database server machine, issue the <emphasis role="bold">bos restart</emphasis> command to
          restart the <emphasis role="bold">fs</emphasis> process (if the machine is a database server, you already restarted the
          process in the previous step). The File Server automatically compiles a new list of interfaces, records them in the
          <emphasis role="bold">/usr/afs/local/sysid</emphasis> file, and registers them in its VLDB server entry. <programlisting>
   % <emphasis role="bold">bos restart</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">fs</emphasis>
</programlisting></para>
        </listitem>

        <listitem>
          <para>If the machine is a database server machine, edit its entry in the <emphasis
          role="bold">/usr/vice/etc/CellServDB</emphasis> file on every client machine in the cell to list one of the new IP
          addresses. Instructions appear in <link linkend="HDRWQ406">Maintaining Knowledge of Database Server
          Machines</link>.</para>
        </listitem>

        <listitem>
          <para>If there are machine entries in the Protection Database for the machine's previous IP addresses, use the <emphasis
          role="bold">pts rename</emphasis> command to change them to the new addresses. For instructions, see <link
          linkend="HDRWQ556">Changing a Protection Database Entry's Name</link>.</para>
        </listitem>
      </orderedlist>

      <indexterm>
        <primary>rebooting</primary>

        <secondary>server machine, instructions</secondary>
      </indexterm>

      <indexterm>
        <primary>server machine</primary>

        <secondary>rebooting</secondary>
      </indexterm>

      <indexterm>
        <primary>BOS Server</primary>

        <secondary>role in reboot of server machine</secondary>
      </indexterm>
    </sect2>
  </sect1>

  <sect1 id="HDRWQ139">
    <title>Rebooting a Server Machine</title>

    <para>You can reboot a server machine either by typing the appropriate commands at its console or by issuing the <emphasis
    role="bold">bos exec</emphasis> command on a remote machine. Remote rebooting can be more convenient, because you do not need to
    leave your present location, but you cannot track the progress of the reboot as you can at the console. Remote rebooting is
    possible because the server machine's operating system recognizes the BOS Server, which executes the <emphasis role="bold">bos
    exec</emphasis> command, as the local superuser <emphasis role="bold">root</emphasis>.</para>

    <para>Rebooting server machines is part of routine maintenance in some cells, and some instructions in the AFS documentation
    include it as a step. It is certainly not intended to be the standard method for recovering from AFS-related problems, however,
    but only a last resort when the machine is unresponsive and you have tried all other reasonable options.</para>

    <para>Rebooting causes a service outage. If the machine stores volumes, they are all inaccessible until the reboot completes and
    the File Server reattaches them. If the machine is a database server machine, information from the databases can become
    unavailable during the reelection of the synchronization site for each database server process; the VL Server outage generally
    has the greatest impact, because the Cache Manager must be able to access the VLDB to fetch AFS data.</para>

    <para>By convention, a server machine's AFS initialization file includes the following command to restart the BOS Server after
    each reboot. It starts the other AFS server processes listed in the local <emphasis
    role="bold">/usr/afs/local/BosConfig</emphasis> file. These instructions assume that the initialization file includes the
    command.</para>

    <programlisting>
   /usr/afs/bin/bosserver
</programlisting>

    <sect2 id="HDRWQ140">
      <title>To reboot a file server machine from its console</title>

      <orderedlist>
        <listitem>
          <para>Become the local superuser <emphasis role="bold">root</emphasis> on the machine, if you are not already, by issuing
          the <emphasis role="bold">su</emphasis> command. <programlisting>
   % <emphasis role="bold">su root</emphasis>
   Password: <replaceable>root_password</replaceable>
</programlisting></para>
        </listitem>

        <listitem>
          <para>Issue the <emphasis role="bold">bos shutdown</emphasis> command to shut down all AFS server processes other than the
          BOS Server, which terminates safely when you reboot the machine. Include the <emphasis role="bold">-localauth</emphasis>
          flag because you are logged in as the local superuser <emphasis role="bold">root</emphasis> but do not necessarily have
          administrative tokens. For a complete description of the command, see <link linkend="HDRWQ168">To stop processes
          temporarily</link>. <programlisting>
   # <emphasis role="bold">bos shutdown</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">-localauth</emphasis> [<emphasis
                role="bold">-wait</emphasis>]
</programlisting></para>
        </listitem>

        <listitem>
          <para>Reboot the machine. On many system types, the appropriate command is <emphasis role="bold">shutdown</emphasis>, but
          the appropriate options vary; consult your UNIX administrator's guide. <programlisting>
    # <emphasis role="bold">shutdown</emphasis>
</programlisting></para>
        </listitem>
      </orderedlist>

      <indexterm>
        <primary>commands</primary>

        <secondary>bos exec</secondary>
      </indexterm>

      <indexterm>
        <primary>bos commands</primary>

        <secondary>exec</secondary>
      </indexterm>
    </sect2>

    <sect2 id="HDRWQ141">
      <title>To reboot a file server machine remotely</title>

      <orderedlist>
        <listitem>
          <para>Verify that you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file on the machine you are
          rebooting. If necessary, issue the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in
          <link linkend="HDRWQ593">To display the users in the UserList file</link>. <programlisting>
   % <emphasis role="bold">bos listusers</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
</programlisting></para>
        </listitem>

        <listitem>
          <para>Issue the <emphasis role="bold">bos shutdown</emphasis> to halt AFS server processes other than the BOS Server,
          which terminates safely when you turn off the machine. For a complete description of the command, see <link
          linkend="HDRWQ168">To stop processes temporarily</link>. <programlisting>
   % <emphasis role="bold">bos shutdown</emphasis> &lt;<replaceable>machine name</replaceable>&gt;  [<emphasis role="bold">-wait</emphasis>]
</programlisting></para>
        </listitem>

        <listitem>
          <para>Issue the <emphasis role="bold">bos exec</emphasis> command to reboot the machine remotely. <programlisting>
   % <emphasis role="bold">bos exec</emphasis> &lt;<replaceable>machine name</replaceable>&gt; reboot_command
</programlisting></para>

          <para>where <variablelist>
              <varlistentry>
                <term><emphasis role="bold">machine name</emphasis></term>

                <listitem>
                  <para>Names the file server machine to reboot.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">reboot_command</emphasis></term>

                <listitem>
                  <para>Is the rebooting command for the machine's operating system. The <emphasis role="bold">shutdown</emphasis>
                  command is appropriate on many system types, but consult your operating system documentation.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </listitem>
      </orderedlist>
    </sect2>
  </sect1>
</chapter>