Don't fail to build documentation if kindlegen doesn't exist

[openafs.git] / doc / xml / AdminGuide / auagd009.xml

<?xml version="1.0" encoding="UTF-8"?>
<chapter id="HDRWQ142">
  <title>Monitoring and Controlling Server Processes</title>

  <para>
  <indexterm>
    <primary>monitoring</primary>

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

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

    <secondary>monitoring server processes</secondary>
  </indexterm>

  One of your most important responsibilities as a system administrator is ensuring that the processes on file server machines
  are running correctly. The BOS Server, which runs on every file server machine, relieves you of much of the responsibility by
  constantly monitoring the other AFS server processes on its machine. It can automatically restart processes that have failed,
  ordering the restarts to take interdependencies into account.</para>

  <para>Because different file server machines run different combinations of processes, you must define which processes the BOS
  Server on each file server machine is to monitor (to learn how, see <link linkend="HDRWQ154">Controlling and Checking Process
  Status</link>).</para>

  <para>It is sometimes necessary to take direct control of server process status before performing routine maintenance or
  correcting problems that the BOS Server cannot correct (such as problems with database replication or mutual authentication). At
  those times, you control process status through the BOS Server by issuing <emphasis role="bold">bos</emphasis> commands.</para>

  <sect1 id="HDRWQ143">
    <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">
        <tbody>
          <row>
            <entry>Examine process status</entry>

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

          <row>
            <entry>Examine information from the <emphasis role="bold">BosConfig file</emphasis> file</entry>

            <entry><emphasis role="bold">bos status</emphasis> with <emphasis role="bold">-long</emphasis> flag</entry>
          </row>

          <row>
            <entry>Create a process instance</entry>

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

          <row>
            <entry>Stop a process</entry>

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

          <row>
            <entry>Start a stopped process</entry>

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

          <row>
            <entry>Stop a process temporarily</entry>

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

          <row>
            <entry>Start a temporarily stopped process</entry>

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

          <row>
            <entry>Stop and immediately restart a process</entry>

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

          <row>
            <entry>Stop and immediately restart all processes</entry>

            <entry><emphasis role="bold">bos restart</emphasis> with <emphasis role="bold">-bosserver</emphasis> flag</entry>
          </row>

          <row>
            <entry>Examine BOS Server's restart times</entry>

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

          <row>
            <entry>Set BOS Server's restart times</entry>

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

          <row>
            <entry>Examine a log file</entry>

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

          <row>
            <entry>Execute a command remotely</entry>

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

  <sect1 id="HDRWQ145">
    <title>Brief Descriptions of the AFS Server Processes</title>

    <para>This section briefly describes the different server processes that can run on an AFS server machine. In cells with
    multiple server machines, not all processes necessarily run on all machines.</para>

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

      <secondary>different names for</secondary>
    </indexterm>

    <para>An AFS server process is referred to in one of three ways, depending on the context: <itemizedlist>
        <listitem>
          <para>The output from the <emphasis role="bold">bos status</emphasis> command refers to a process by the name assigned
          when the <emphasis role="bold">bos create</emphasis> command creates its entry in the <emphasis
          role="bold">/usr/afs/local/BosConfig</emphasis> file. The name can differ from machine to machine, but it is easiest to
          maintain the cell if you assign the same name on all machines. The <emphasis>OpenAFS Quick Beginnings</emphasis> and the
          reference page for the <emphasis role="bold">bos create</emphasis> command list the conventional names. Examples are
          <emphasis role="bold">bosserver</emphasis>, <emphasis role="bold">kaserver</emphasis>, and <emphasis
          role="bold">vlserver</emphasis>.</para>
        </listitem>

        <listitem>
          <para>The process listing produced by the standard <emphasis role="bold">ps</emphasis> command generally matches the
          process's binary file. Examples of process binary files are <emphasis role="bold">/usr/afs/bin/bosserver</emphasis>,
          <emphasis role="bold">/usr/afs/bin/kaserver</emphasis>, and <emphasis role="bold">/usr/afs/bin/vlserver</emphasis>.</para>
        </listitem>

        <listitem>
          <para>In most contexts, including most references in the documentation, a process is referred to as (for example) the
          <emphasis role="bold">Basic OverSeer (BOS) Server</emphasis>, the <emphasis role="bold">Authentication Server</emphasis>,
          or the <emphasis role="bold">Volume Location Server</emphasis>.</para>
        </listitem>
      </itemizedlist></para>

    <para>The following sections specify each name for the process as well as some of the administrative tasks in which you use the
    process. For a more general description of the servers, see <link linkend="HDRWQ17">AFS Server Processes and the Cache
    Manager</link>.</para>

    <sect2 id="HDRWQ146">
      <title>The bosserver Process: the Basic OverSeer Server</title>

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

        <secondary>as bosserver process</secondary>
      </indexterm>

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

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

      <para>The <emphasis role="bold">bosserver</emphasis> process, which runs on every AFS server machine, is the Basic OverSeer
      (BOS) Server responsible for monitoring the other AFS server processes running on its machine. If a process fails, the BOS
      Server can restart it automatically, without human intervention. It takes interdependencies into account when restarting a
      process that has multiple component processes (such as the <emphasis role="bold">fs</emphasis> process described in <link
      linkend="HDRWQ148">The fs Collection of Processes: the File Server, Volume Server and Salvager</link>).</para>

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

      <para>Because the BOS Server does not monitor or restart itself, it does not appear in the output from the <emphasis
      role="bold">bos status</emphasis> command. It appears in the <emphasis role="bold">ps</emphasis> command's output as
      <computeroutput>/usr/afs/bin/bosserver</computeroutput>.</para>

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

        <secondary>when to contact</secondary>
      </indexterm>

      <indexterm>
        <primary>contacting processes</primary>

        <secondary>BOS Server</secondary>
      </indexterm>

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

        <secondary>summary of functions</secondary>
      </indexterm>

      <para>As a system administrator, you contact the BOS Server when you issue <emphasis role="bold">bos</emphasis> commands to
      perform the following kinds of tasks. <itemizedlist>
          <listitem>
            <para>Defining the processes for the BOS Server to monitor by creating entries in the <emphasis
            role="bold">/usr/afs/local/BosConfig</emphasis> file as described in <link linkend="HDRWQ154">Controlling and Checking
            Process Status</link></para>
          </listitem>

          <listitem>
            <para>Stopping and starting processes on the file server machines according to subsequent instructions in this
            chapter</para>
          </listitem>

          <listitem>
            <para>Defining your cell's database server machines in the <emphasis role="bold">/usr/afs/etc/CellServDB</emphasis> file
            as described in <link linkend="HDRWQ118">Maintaining the Server CellServDB File</link></para>
          </listitem>

          <listitem>
            <para>Defining AFS server encryption keys in the <emphasis role="bold">/usr/afs/etc/KeyFile</emphasis> file as described
            in <link linkend="HDRWQ355">Managing Server Encryption Keys</link>.</para>
          </listitem>

          <listitem>
            <para>Granting system administrator privileges with respect to BOS Server, Volume Server, and Backup Server operations,
            by adding a user to the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file as described in <link
            linkend="HDRWQ592">Administering the UserList File</link></para>
          </listitem>

          <listitem>
            <para>Setting authorization checking requirements on a server machine as described in <link linkend="HDRWQ123">Managing
            Authentication and Authorization Requirements</link></para>
          </listitem>
        </itemizedlist></para>
    </sect2>

    <sect2 id="HDRWQ147">
      <title>The buserver Process: the Backup Server</title>

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

        <secondary>as buserver process</secondary>
      </indexterm>

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

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

      <para>The <emphasis role="bold">buserver</emphasis> process, which runs on database server machines, is the Backup Server. It
      maintains information about Backup System configuration and operations in the Backup Database.</para>

      <para>The process appears as <computeroutput>buserver</computeroutput> in the <emphasis role="bold">bos status</emphasis>
      command's output, if the conventional name is assigned. It appears in the <emphasis role="bold">ps</emphasis> command's output
      as <computeroutput>/usr/afs/bin/buserver</computeroutput>.</para>

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

        <secondary>when to contact</secondary>
      </indexterm>

      <indexterm>
        <primary>contacting processes</primary>

        <secondary>Backup Server</secondary>
      </indexterm>

      <para>As a system administrator, you contact the Backup Server when you issue any <emphasis role="bold">backup</emphasis>
      command that manipulates information in the Backup Database, including those that change Backup System configuration
      information, that dump data from volumes to permanent storage, or that restore data to AFS. See <link
      linkend="HDRWQ248">Configuring the AFS Backup System</link> and <link linkend="HDRWQ283">Backing Up and Restoring AFS
      Data</link>.</para>
    </sect2>

    <sect2 id="HDRWQ148">
      <title>The fs Collection of Processes: the File Server, Volume Server and Salvager</title>

      <indexterm>
        <primary>fs process</primary>
      </indexterm>

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

        <secondary>fs</secondary>
      </indexterm>

      <para>The <emphasis role="bold">fs</emphasis> process, which runs on every file server machine, combines three component
      processes: File Server, Volume Server and Salvager. The three components perform independent functions, but are controlled as
      a single process for the following reasons. <itemizedlist>
          <listitem>
            <para>They all operate on the same data, namely files and directories stored in AFS volumes. Combining them as a single
            process enables them to coordinate their actions, never attempting simultaneous operations on the same data that can
            possibly corrupt it.</para>
          </listitem>

          <listitem>
            <para>It enables the BOS Server to stop and restart the processes in the required order. When the File Server fails, the
            BOS Server stops the Volume Server and runs the Salvager to correct any corruption that resulted from the failure. (The
            Salvager runs only in this special circumstance or when you invoke it yourself by issuing the <emphasis role="bold">bos
            salvage</emphasis> command as instructed in <link linkend="HDRWQ232">Salvaging Volumes</link>.) If only the Volume
            Server fails, the BOS Server can restart it without affecting the File Server or Salvager.</para>
          </listitem>
        </itemizedlist></para>

      <para>The File Server component handles AFS data at the level of files and directories, manipulating file system elements as
      requested by application programs and the standard operating system commands. Its main duty is to deliver requested files to
      client machines and store them again on the server machine when the client is finished. It also maintains status and
      protection information about each file and directory. It runs continuously during normal operation.</para>

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

        <secondary>as part of fs process</secondary>
      </indexterm>

      <para>The Volume Server component handles AFS data at the level of complete volumes rather than files and directories. In
      response to <emphasis role="bold">vos</emphasis> commands, it creates, removes, moves, dumps and restores entire volumes,
      among other actions. It runs continuously during normal operation.</para>

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

        <secondary>as part of fs process</secondary>
      </indexterm>

      <para>The Salvager component runs only after the failure of one of the other two processes. It checks the file system for
      internal consistency and repairs any errors it finds.</para>

      <indexterm>
        <primary>Salvager</primary>

        <secondary>as part of fs process</secondary>
      </indexterm>

      <indexterm>
        <primary>file system</primary>

        <secondary>salvager</secondary>

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

      <para>The process appears as <computeroutput>fs</computeroutput> in the <emphasis role="bold">bos status</emphasis> command's
      output, if the conventional name is assigned. An auxiliary message reports the status of the File Server or Salvager
      component. See <link linkend="HDRWQ158">Displaying Process Status and Information from the BosConfig File</link>.</para>

      <para>The component processes of the <emphasis role="bold">fs</emphasis> process appear individually in the <emphasis
      role="bold">ps</emphasis> command's output, as follows. There is no entry for the <computeroutput>fs</computeroutput> process
      itself. <itemizedlist>
          <listitem>
            <para><computeroutput>/usr/afs/bin/fileserver</computeroutput></para>
          </listitem>

          <listitem>
            <para><computeroutput>/usr/afs/bin/volserver</computeroutput></para>
          </listitem>

          <listitem>
            <para><computeroutput>/usr/afs/bin/salvager</computeroutput></para>
          </listitem>
        </itemizedlist></para>

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

        <secondary>when to contact</secondary>
      </indexterm>

      <indexterm>
        <primary>contacting processes</primary>

        <secondary>File Server</secondary>
      </indexterm>

      <para>The Cache Manager contacts the File Server component on your behalf whenever you access data or status information in an
      AFS file or directory or issue file manipulation commands such as the UNIX <emphasis role="bold">cp</emphasis> and <emphasis
      role="bold">ls</emphasis> commands. You can contact the File Server directly by issuing <emphasis role="bold">fs</emphasis>
      commands that perform the following functions <itemizedlist>
          <listitem>
            <para>Administering the ACL of any directory in the file system as described in <link linkend="HDRWQ562">Managing Access
            Control Lists</link></para>
          </listitem>

          <listitem>
            <para>Installing new partitions for housing AFS volumes, in which case you must restart the <emphasis
            role="bold">fs</emphasis> process for it to recognize the new partition; for instructions, see <link
            linkend="HDRWQ130">Adding or Removing Disks and Partitions</link></para>
          </listitem>

          <listitem>
            <para>Creating and deleting volume mount points in the AFS filespace as described in <link linkend="HDRWQ208">Mounting
            Volumes</link></para>
          </listitem>

          <listitem>
            <para>Setting volume quota and displaying information about the space used and available in a volume or partition as
            described in <link linkend="HDRWQ234">Setting and Displaying Volume Quota and Current Size</link></para>
          </listitem>
        </itemizedlist></para>

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

        <secondary>when to contact</secondary>
      </indexterm>

      <indexterm>
        <primary>contacting processes</primary>

        <secondary>Volume Server</secondary>
      </indexterm>

      <para>You contact the Volume Server component when you issue <emphasis role="bold">vos</emphasis> commands that manipulate
      volumes in any way--creating, removing, replicating, moving, renaming, converting to different formats, and salvaging. For
      instructions, see <link linkend="HDRWQ174">Managing Volumes</link>.</para>

      <para>The Salvager normally runs automatically in case of a failure. You can also start it with the <emphasis role="bold">bos
      salvage</emphasis> command as described in <link linkend="HDRWQ232">Salvaging Volumes</link>.</para>

      <indexterm>
        <primary>Salvager</primary>

        <secondary>when to contact</secondary>
      </indexterm>

      <indexterm>
        <primary>contacting processes</primary>

        <secondary>Salvager</secondary>
      </indexterm>
    </sect2>

    <sect2 id="HDRWQ149">
      <title>The kaserver Process: the Authentication Server</title>

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

        <secondary>as kaserver process</secondary>
      </indexterm>

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

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

      <para>The <emphasis role="bold">kaserver</emphasis> process, which runs on database server machines, is the Authentication
      Server responsible for several aspects of AFS security. It verifies AFS user identity by requiring a password. It maintains
      all AFS server encryption keys and user passwords in the Authentication Database. The Authentication Server's Ticket Granting
      Service (TGS) module creates the shared secrets that AFS client and server processes use when establishing secure
      connections.</para>

      <para>The process appears as <computeroutput>kaserver</computeroutput> in the <emphasis role="bold">bos status</emphasis>
      command's output, if the conventional name is assigned. The <emphasis role="bold">ka</emphasis> string stands for
      <emphasis>Kerberos Authentication</emphasis>, reflecting the fact that AFS's authentication protocols are based on Kerberos,
      which was originally developed at the Massachusetts Institute of Technology's Project Athena.</para>

      <para>It appears in the <emphasis role="bold">ps</emphasis> command's output as
      <computeroutput>/usr/afs/bin/kaserver</computeroutput>.</para>

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

        <secondary>when to contact</secondary>
      </indexterm>

      <indexterm>
        <primary>contacting processes</primary>

        <secondary>Authentication Server</secondary>
      </indexterm>

      <para>As a system administrator, you contact the Authentication Server when you issue <emphasis role="bold">kas</emphasis>
      commands to perform the following kinds of tasks. <itemizedlist>
          <listitem>
            <para>Setting a user's password. Users normally change their own passwords, so you probably perform this task only
            creating a new user account as described in <link linkend="HDRWQ502">Creating AFS User Accounts</link> and <link
            linkend="HDRWQ516">Changing AFS Passwords</link>.</para>
          </listitem>

          <listitem>
            <para>Setting the AFS server encryption key in the Authentication Database, which the TGS uses to seal server tickets;
            see <link linkend="HDRWQ355">Managing Server Encryption Keys</link>.</para>
          </listitem>

          <listitem>
            <para>Granting or revoking system administrator privileges with respect to the Authentication Server as described in
            <link linkend="HDRWQ589">Granting Privilege for kas Commands: the ADMIN Flag</link>.</para>
          </listitem>
        </itemizedlist></para>
    </sect2>

    <sect2 id="HDRWQ150">
      <title>The ptserver Process: the Protection Server</title>

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

        <secondary>as ptserver process</secondary>
      </indexterm>

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

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

      <para>The <emphasis role="bold">ptserver</emphasis> process, which runs on database server machines, is the Protection Server.
      Its main responsibility is maintaining the Protection Database which contains user, machine, and group entries. The Protection
      Server allocates AFS IDs and maintains the mapping between them and names. The File Server consults the Protection Server when
      verifying that a user is authorized to perform a requested action.</para>

      <para>The process appears as <computeroutput>ptserver</computeroutput> in the <emphasis role="bold">bos status</emphasis>
      command's output, if the conventional name is assigned. It appears in the <emphasis role="bold">ps</emphasis> command's output
      as <computeroutput>/usr/afs/bin/ptserver</computeroutput>.</para>

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

        <secondary>when to contact</secondary>
      </indexterm>

      <indexterm>
        <primary>contacting processes</primary>

        <secondary>Protection Server</secondary>
      </indexterm>

      <para>As a system administrator, you contact the Protection Server when you issue <emphasis role="bold">pts</emphasis>
      commands to perform the following kinds of tasks. <itemizedlist>
          <listitem>
            <para>Creating a new user, machine, or group entry in the Protection Database as described in <link
            linkend="HDRWQ531">Administering the Protection Database</link></para>
          </listitem>

          <listitem>
            <para>Adding or removing group members or otherwise manipulating Protection Database entries as described in <link
            linkend="HDRWQ531">Administering the Protection Database</link></para>
          </listitem>

          <listitem>
            <para>Granting or revoking system administrator privilege by changing the membership of the <emphasis
            role="bold">system:administrators</emphasis> group as described in <link linkend="HDRWQ586">Administering the
            system:administrators Group</link></para>
          </listitem>
        </itemizedlist></para>
    </sect2>

    <sect2 id="HDRWQ151">
      <title>The runntp Process</title>

      <indexterm>
        <primary>runntp process</primary>
      </indexterm>

      <indexterm>
        <primary>ntpd</primary>

        <secondary>invoked by runntp process</secondary>
      </indexterm>

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

        <secondary>runntp</secondary>
      </indexterm>

      <para>The <emphasis role="bold">runntp</emphasis> process, which runs on every server machine, is a controller program for the
      Network Time Protocol Daemon (NTPD), which synchronizes the hardware clocks on server machines. You need to run the <emphasis
      role="bold">runntp</emphasis> process if you are not already running NTP or another time synchronization protocol on your
      server machines.</para>

      <para>The clocks on database server machines need to be synchronized because AFS's distributed database technology (Ubik)
      works properly only when the clocks agree within a narrow range of variation (see <link linkend="HDRWQ103">Configuring the
      Cell for Proper Ubik Operation</link>). The clocks on file server machines need to be correct not only because the File Server
      sets modification time stamps on files, but because in the conventional configuration they serve as the time source for AFS
      client machines.</para>

      <para>The process appears as <computeroutput>runntp</computeroutput> in the <emphasis role="bold">bos status</emphasis>
      command's output, if the conventional name is assigned. It appears in the output from the <emphasis role="bold">ps</emphasis>
      command as <computeroutput>/usr/afs/bin/runntp</computeroutput>. The <emphasis role="bold">ps</emphasis> command's output also
      includes an entry called <computeroutput>ntpd</computeroutput>; its exact form depends on the arguments you provide to the
      <emphasis role="bold">runntp</emphasis> command.</para>

      <indexterm>
        <primary>ntpd</primary>

        <secondary>when to contact</secondary>
      </indexterm>

      <indexterm>
        <primary>contacting processes</primary>

        <secondary>NTPD</secondary>
      </indexterm>

      <para>As a system administrator, you do not contact the NTPD directly once you have installed it according to the instructions
      in the <emphasis>OpenAFS Quick Beginnings</emphasis>.</para>
    </sect2>

    <sect2 id="HDRWQ152">
      <title>The upserver and upclient Processes: the Update Server</title>

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

        <secondary>as upserver and upclient processes</secondary>
      </indexterm>

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

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

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

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

      <para>The Update Server has two separate parts, each of which runs on a different type of server machine. The <emphasis
      role="bold">upserver</emphasis> process is the server portion of the Update Server. Its function depends on which edition of
      AFS you use: <itemizedlist>
          <listitem>
            <para>With both the United States and international editions, it runs on the binary distribution machine of each system
            type you use as a server machine, distributing the contents of each one's <emphasis role="bold">/usr/afs/bin</emphasis>
            directory to the other server machines of that type. This guarantees that all machines have the same version of AFS
            binaries. (For a list of the binaries, see <link linkend="HDRWQ84">Binaries in the /usr/afs/bin
            Directory</link>.)</para>
          </listitem>

          <listitem>
            <para>In you use the United States edition of AFS, it also runs on the cell's system control machine, distributing the
            contents of its <emphasis role="bold">/usr/afs/etc</emphasis> directory to all the other server machines in order to
            synchronize the configuration files stored in that directory. (For a list of the configuration files, see <link
            linkend="HDRWQ85">Common Configuration Files in the /usr/afs/etc Directory</link>.)</para>
          </listitem>
        </itemizedlist></para>

      <para>The <emphasis role="bold">upclient</emphasis> process is the client portion of the Update Server, and like the server
      portion its function depends on the AFS edition in use. <itemizedlist>
          <listitem>
            <para>It runs on every server machine that is not a binary distribution machine, referencing the binary distribution
            machine of its system type as the source for updates to the binaries in the <emphasis
            role="bold">/usr/afs/bin</emphasis> directory. The conventional process name to assign is <emphasis
            role="bold">upclientbin</emphasis>.</para>
          </listitem>

          <listitem>
            <para>If you use the United States edition of AFS, another instance of the process runs on every server machine except
            the system control machine. It references the system control machine as the source for updates to the common
            configuration files in the <emphasis role="bold">/usr/afs/etc</emphasis> directory. The conventional process name to
            assign is <emphasis role="bold">upclientetc</emphasis>.</para>
          </listitem>
        </itemizedlist></para>

      <para>In output from the <emphasis role="bold">bos status</emphasis> command, the server portion appears as
      <computeroutput>upserver</computeroutput> and the client portions as <computeroutput>upclientbin</computeroutput> and
      <computeroutput>upclientetc</computeroutput>, if the conventional names are assigned. In the output from the <emphasis
      role="bold">ps</emphasis> command, the server portion appears as <computeroutput>/usr/afs/bin/upserver</computeroutput> and
      the client portions as /usr/afs/bin/upclient.</para>

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

        <secondary>when to contact</secondary>
      </indexterm>

      <indexterm>
        <primary>contacting processes</primary>

        <secondary>Update Server</secondary>
      </indexterm>

      <para>You do not contact the Update Server directly once you have installed it. It operates automatically whenever you use
      <emphasis role="bold">bos</emphasis> commands to change the files that it distributes.</para>
    </sect2>

    <sect2 id="HDRWQ153">
      <title>The vlserver Process: the Volume Location Server</title>

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

        <secondary>as vlserver process</secondary>
      </indexterm>

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

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

      <para>The <emphasis role="bold">vlserver</emphasis> process, which runs on database server machines, is the Volume Location
      (VL) Server that automatically tracks which file server machines house each volume, making its location transparent to client
      applications.</para>

      <para>The process appears as <computeroutput>vlserver</computeroutput> in the <emphasis role="bold">bos status</emphasis>
      command's output, if the conventional name is assigned. It appears in the <emphasis role="bold">ps</emphasis> command's output
      as <computeroutput>/usr/afs/bin/vlserver</computeroutput>.</para>

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

        <secondary>when to contact</secondary>
      </indexterm>

      <indexterm>
        <primary>contacting processes</primary>

        <secondary>VL Server</secondary>
      </indexterm>

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

        <secondary>summary of functions</secondary>
      </indexterm>

      <para>As a system administrator, you contact the VL Server when you issue any <emphasis role="bold">vos</emphasis> command
      that changes the status of a volume (it records the status changes in the VLDB).</para>
    </sect2>
  </sect1>

  <sect1 id="HDRWQ154">
    <title>Controlling and Checking Process Status</title>

    <para>To define the AFS server processes that run on a server machine, use the <emphasis role="bold">bos create</emphasis>
    command to create entries for them in the local <emphasis role="bold">/usr/afs/local/BosConfig</emphasis> file. The BOS Server
    monitors the processes listed in the <emphasis role="bold">BosConfig</emphasis> file that are marked with the
    <computeroutput>Run</computeroutput> status flag, and automatically attempts to restart them if they fail. After creating
    process entries, you use other commands from the <emphasis role="bold">bos</emphasis> suite to stop and start processes or
    change the status flag as desired.</para>

    <para>Never edit the <emphasis role="bold">BosConfig</emphasis> file directly rather than using <emphasis
    role="bold">bos</emphasis> commands. Similarly, it is not a good practice to run server processes without listing them in the
    <emphasis role="bold">BosConfig</emphasis> file, or to stop them using process termination commands such as the UNIX <emphasis
    role="bold">kill</emphasis> command.</para>

    <sect2 id="Header_176">
      <title>The Information in the BosConfig File</title>

      <indexterm>
        <primary>BosConfig file</primary>

        <secondary>information</secondary>
      </indexterm>

      <indexterm>
        <primary>files</primary>

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

      <para>A process's entry in the <emphasis role="bold">BosConfig</emphasis> file includes the following information:
      <itemizedlist>
          <listitem>
            <para>The process's name. The recommended conventional names are defined in both the <emphasis>OpenAFS Quick
            Beginnings</emphasis> and <link linkend="HDRWQ161">Creating and Removing Processes</link>. The name of a simple process
            usually matches the name of its binary file (for example, <emphasis role="bold">ptserver</emphasis> for the Protection
            Server).</para>
          </listitem>

          <listitem>
            <para>Its type, which is one of the following: <variablelist>
                <indexterm>
                  <primary>simple-type server process</primary>

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

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

                  <secondary>simple type, defined</secondary>
                </indexterm>

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

                  <listitem>
                    <para>A process that runs independently of any other on the server machine. If several simple processes fail at
                    the same time, the BOS Server can restart them in any order. All standard AFS processes except the <emphasis
                    role="bold">fs</emphasis> process are simple.</para>
                  </listitem>
                </varlistentry>

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

                  <listitem>
                    <indexterm>
                      <primary>fs-type server process</primary>

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

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

                      <secondary>fs type, defined</secondary>
                    </indexterm>

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

                      <secondary>as part of fs process</secondary>
                    </indexterm>

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

                      <secondary>as part of fs process</secondary>
                    </indexterm>

                    <indexterm>
                      <primary>Salvager</primary>

                      <secondary>as part of fs process</secondary>
                    </indexterm>

                    <para>A process type reserved for the server process for which the conventional name is also <emphasis
                    role="bold">fs</emphasis>. This process combines three components: the File Server, the Volume Server, and the
                    Salvager.</para>

                    <indexterm>
                      <primary>cron-type server process</primary>

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

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

                      <secondary>cron type, defined</secondary>
                    </indexterm>
                  </listitem>
                </varlistentry>

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

                  <listitem>
                    <para>A process that runs at a defined time rather than continuously. There are no standard processes of this
                    type.</para>
                  </listitem>
                </varlistentry>
              </variablelist></para>

            <indexterm>
              <primary>status flag for process in BosConfig file</primary>

              <secondary>Run and Not Run, meaning of</secondary>
            </indexterm>

            <indexterm>
              <primary>Run status flag in BosConfig file</primary>

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

            <indexterm>
              <primary>NotRun status flag in BosConfig file</primary>

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

            <indexterm>
              <primary>process</primary>

              <secondary>status flag in BosConfig file</secondary>
            </indexterm>
          </listitem>

          <listitem>
            <para>Its status flag, which tells the BOS Server whether it performs the following two actions with respect to the
            process: <itemizedlist>
                <listitem>
                  <para>Start the process during BOS Server initialization</para>
                </listitem>

                <listitem>
                  <para>Restart the process if it (the process) fails</para>
                </listitem>
              </itemizedlist></para>

            <para>The two possible values are <computeroutput>Run</computeroutput> (which directs the BOS Server to perform these
            actions) and <computeroutput>NotRun</computeroutput> (which directs the BOS Server to ignore the process). The BOS
            Server itself never changes the setting of this flag, even if the process fails repeatedly. Also, this flag is for
            internal use only; it does not appear in the <emphasis role="bold">bos status</emphasis> command's output.</para>
          </listitem>

          <listitem>
            <para>Its command parameters, which are the commands that the BOS Server runs to start the process. <itemizedlist>
                <indexterm>
                  <primary>command parameters</primary>

                  <secondary>in BosConfig file</secondary>
                </indexterm>

                <listitem>
                  <para>A simple processes has one: the complete pathname to its binary file</para>
                </listitem>

                <listitem>
                  <para>The <emphasis role="bold">fs</emphasis> process has three: the complete pathnames to each of the three
                  component processes (<emphasis role="bold">/usr/afs/bin/fileserver</emphasis>, <emphasis
                  role="bold">/usr/afs/bin/volserver</emphasis>, and <emphasis role="bold">/usr/afs/bin/salvager</emphasis>)</para>
                </listitem>

                <listitem>
                  <para>A cron process has two: the first the complete pathname to its binary file, the second the time at which the
                  BOS Server runs it</para>
                </listitem>
              </itemizedlist></para>
          </listitem>
        </itemizedlist></para>

      <para>In addition to process definitions, the <emphasis role="bold">BosConfig</emphasis> file also records automatic restart
      times for processes that have new binaries, and for all server processes including the BOS Server. See <link
      linkend="HDRWQ171">Setting the BOS Server's Restart Times</link>.</para>
    </sect2>

    <sect2 id="HDRWQ155">
      <title>How the BOS Server Uses the Information in the BosConfig File</title>

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

        <secondary>use of BosConfig file</secondary>
      </indexterm>

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

        <secondary>memory state</secondary>
      </indexterm>

      <indexterm>
        <primary>memory state of BOS Server</primary>
      </indexterm>

      <para>Whenever the BOS Server starts or restarts, it reads the <emphasis role="bold">BosConfig</emphasis> file to learn which
      processes it is to start and monitor. It transfers the information into kernel memory and does not read the <emphasis
      role="bold">BosConfig</emphasis> file again until it next restarts. This implies that the BOS Server's memory state can change
      independently of the <emphasis role="bold">BosConfig</emphasis> file. You can, for example, stop a process but leave its
      status flag in the <emphasis role="bold">BosConfig</emphasis> file as <computeroutput>Run</computeroutput>, or start a process
      even though its status flag in the <emphasis role="bold">BosConfig</emphasis> file is
      <computeroutput>NotRun</computeroutput>.</para>
    </sect2>

    <sect2 id="HDRWQ156">
      <title>About Starting and Stopping the Database Server Processes</title>

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

        <secondary>about starting and stopping</secondary>
      </indexterm>

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

        <secondary>about starting and stopping</secondary>
      </indexterm>

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

        <secondary>about starting and stopping</secondary>
      </indexterm>

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

        <secondary>about starting and stopping</secondary>
      </indexterm>

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

        <secondary>about starting and stopping</secondary>
      </indexterm>

      <indexterm>
        <primary>starting</primary>

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

      <indexterm>
        <primary>stopping</primary>

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

      <para>When you start or stop a database server process (Authentication Server, Backup Server, Protection Server, or Volume
      Location Server) for more than a short time, you must follow the instructions in the <emphasis>OpenAFS Quick
      Beginnings</emphasis> for installing or removing a database server machine. Here is a summary of the tasks you must perform to
      preserve correct AFS functioning. <itemizedlist>
          <listitem>
            <para>Start or stop all four database server processes on that machine. All AFS server processes and the Cache Manager
            processes expect all four database server processes to be running on each machine listed in the <emphasis
            role="bold">CellServDB</emphasis> file. There is no way to indicate in the file that a machine is running only some of
            the database server processes.</para>
          </listitem>

          <listitem>
            <para>Add or remove the machine in the <emphasis role="bold">/usr/afs/etc/CellServDB</emphasis> file on all server
            machines and the <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file on all client machines.</para>
          </listitem>

          <listitem>
            <para>Restart the database server processes on the other database server machines to force an election of a new Ubik
            coordinator for each one.</para>
          </listitem>
        </itemizedlist></para>
    </sect2>

    <sect2 id="HDRWQ157">
      <title>About Starting and Stopping the Update Server</title>

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

        <secondary>about starting and stopping</secondary>
      </indexterm>

      <para>In the conventional cell configuration, one server machine of each system type acts as a binary distribution machine,
      running the server portion of the Update Server (<emphasis role="bold">upserver</emphasis> process) to distribute the contents
      of its <emphasis role="bold">/usr/afs/bin</emphasis> directory. The other server machines of its system type run an instance
      of the Update Server client portion (by convention called <emphasis role="bold">upclientbin</emphasis>) that references the
      binary distribution machine.</para>

      <para>If you run the United States edition of AFS, it is conventional for the first server machine you install to act as the
      system control machine, running the server portion of the Update Server (<emphasis role="bold">upserver</emphasis> process) to
      distribute the contents of its <emphasis role="bold">/usr/afs/etc</emphasis> directory. All other server machines run an
      instance of the Update Server client portion (by convention called <emphasis role="bold">upclientetc</emphasis>) that
      references the system control machine.</para>

      <note>
        <para>If you are using the international edition of AFS, do not use the Update Server to distribute the contents of the
        <emphasis role="bold">/usr/afs/etc</emphasis> directory (you do not run a system control machine). Ignore all references to
        the process in this chapter.</para>
      </note>

      <para>It is simplest not to move binary distribution or system control responsibilities to a different machine unless you
      completely decommission a machine that is currently serving in one of those roles. Running the Update Server usually imposes
      very little processing load. If you must move the functionality, perform the following related tasks. <itemizedlist>
          <listitem>
            <para>If you replace the system control machine, you must stop the <emphasis role="bold">upclientetc</emphasis> process
            on every other server machine and define a new one that references the new system control machine.</para>
          </listitem>

          <listitem>
            <para>If you replace a binary distribution machine, you must stop the <emphasis role="bold">upclientbin</emphasis>
            process on every other server machine of its system type and define a new one that references the new binary
            distribution machine (unless you are no longer running any server machines of that system type).</para>
          </listitem>
        </itemizedlist></para>
    </sect2>
  </sect1>

  <sect1 id="HDRWQ158">
    <title>Displaying Process Status and Information from the BosConfig File</title>

    <para>To display the status of the AFS server processes on a server machine, issue the <emphasis role="bold">bos
    status</emphasis> command. Adding the <emphasis role="bold">-long</emphasis> flag displays most of the information from each
    process's entry in the <emphasis role="bold">BosConfig</emphasis> file, including its type and command parameters. It also
    displays a warning message if the mode bits on files and subdirectories in the <emphasis role="bold">/usr/afs</emphasis>
    directory do not match the expected values.</para>

    <sect2 id="HDRWQ159">
      <title>To display the status of server processes and their BosConfig entries</title>

      <indexterm>
        <primary>displaying</primary>

        <secondary>server process status</secondary>
      </indexterm>

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

        <secondary>displaying status</secondary>
      </indexterm>

      <indexterm>
        <primary>status</primary>

        <secondary>displaying for server process</secondary>
      </indexterm>

      <indexterm>
        <primary>displaying</primary>

        <secondary>entries from BosConfig file</secondary>
      </indexterm>

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

        <secondary>displaying entry in BosConfig</secondary>
      </indexterm>

      <indexterm>
        <primary>BosConfig file</primary>

        <secondary>displaying entries</secondary>
      </indexterm>

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

        <secondary>status</secondary>
      </indexterm>

      <indexterm>
        <primary>commands</primary>

        <secondary>bos status</secondary>
      </indexterm>

      <orderedlist>
        <listitem>
          <para>Issue the <emphasis role="bold">bos status</emphasis> command. <programlisting>
   % <emphasis role="bold">bos status</emphasis> &lt;<replaceable>machine name</replaceable>&gt;  [&lt;<replaceable>server process name</replaceable>&gt;+]  [<emphasis
                role="bold">-long</emphasis>]
</programlisting></para>

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

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

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

                <listitem>
                  <para>Specifies the file server machine for which to display process status.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">server process name</emphasis></term>

                <listitem>
                  <para>Names each process for which to display status, using the name assigned when its entry was defined with the
                  <emphasis role="bold">bos create</emphasis> command. Omit this argument to display the status of all server
                  processes.</para>
                </listitem>
              </varlistentry>

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

                <listitem>
                  <para>Displays, in addition to status, information from the process's entry in the <emphasis
                  role="bold">BosConfig</emphasis> file: its type, its status flag, its command parameters, the associated notifier
                  program, and so on.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </listitem>
      </orderedlist>

      <para>The output includes an entry for each process and uses one of the following strings to indicate the process's status:
      <itemizedlist>
          <listitem>
            <para><computeroutput>currently running normally</computeroutput> indicates that the process is running and its status
            flag in the <emphasis role="bold">BosConfig</emphasis> file is <computeroutput>Run</computeroutput>. For cron entries,
            this message indicates that the command is still scheduled to run, not necessarily that it is actually running when the
            <emphasis role="bold">bos status</emphasis> command was issued.</para>
          </listitem>

          <listitem>
            <para><computeroutput>temporarily enabled</computeroutput> indicates that the process is running but that its status
            flag in the <emphasis role="bold">BosConfig</emphasis> file is <computeroutput>NotRun</computeroutput>. The most common
            reason is that a system administrator has used the <emphasis role="bold">bos startup</emphasis> command to start the
            process.</para>
          </listitem>

          <listitem>
            <para><computeroutput>temporarily disabled</computeroutput> indicates that the process is not running even though its
            status flag in the <emphasis role="bold">BosConfig</emphasis> file is <computeroutput>Run</computeroutput>. The most
            common reasons are either that a system administrator has used the <emphasis role="bold">bos shutdown</emphasis> command
            to stop the process or that the BOS Server ceased trying to restart the process after numerous failed attempts. In the
            latter case, a supplementary message appears: <computeroutput>stopped for too many errors</computeroutput>.</para>
          </listitem>

          <listitem>
            <para>disabled indicates that the process is not running and that its status flag in the <emphasis
            role="bold">BosConfig</emphasis> file is <computeroutput>NotRun</computeroutput>. The BOS Server is not monitoring the
            process. Only a system administrator can set the flag this way; the BOS Server never does.</para>
          </listitem>
        </itemizedlist></para>

      <para>The output for the <emphasis role="bold">fs</emphasis> process always includes a message marked
      <computeroutput>Auxiliary status</computeroutput>, which can be one of the following: <itemizedlist>
          <listitem>
            <para><computeroutput>file server running</computeroutput> indicates that the File Server and Volume Server components
            of the File Server process are running normally.</para>
          </listitem>

          <listitem>
            <para><computeroutput>salvaging file system</computeroutput> indicates that the Salvager is running, which usually
            implies that the File Server and Volume Server are temporarily disabled. The BOS Server restarts them as soon as the
            Salvager is finished.</para>
          </listitem>
        </itemizedlist></para>

      <para>The output for a cron process also includes an <computeroutput>Auxiliary status</computeroutput> message to report when
      the command is scheduled to run next; see the example that follows.</para>

      <para>The output for any process can include the supplementary message <computeroutput>has core file</computeroutput> to
      indicate that at some point the process failed and generated a core file in the <emphasis role="bold">/usr/afs/logs</emphasis>
      directory. In most cases, the BOS Server is able to restart the process and it is running.</para>

      <para>The following example includes a user-defined cron entry called <emphasis role="bold">backupusers</emphasis>:</para>

      <programlisting>
   % <emphasis role="bold">bos status fs3.abc.com</emphasis>
   Instance kaserver, currently running normally.
   Instance ptserver, currently running normally.
   Instance vlserver, has core file, currently running normally.
   Instance buserver, currently running normally.
   Instance fs, currently running normally.
       Auxiliary status is: file server running.
   Instance upserver, currently running normally.
   Instance runntp, currently running normally.
   Instance backupusers, currently running normally.
       Auxiliary status is: run next at Mon Jun 7 02:00:00 1999.
</programlisting>

      <para>If you include the <emphasis role="bold">-long</emphasis> flag to the <emphasis role="bold">bos status</emphasis>
      command, a process's entry in the output includes the following additional information from the <emphasis
      role="bold">BosConfig</emphasis> file: <itemizedlist>
          <listitem>
            <para>The process's type (<computeroutput>simple</computeroutput>, <computeroutput>fs</computeroutput>, or
            <computeroutput>cron</computeroutput>).</para>
          </listitem>

          <listitem>
            <para>The day and time the process last started or restarted.</para>
          </listitem>

          <listitem>
            <para>The number of <computeroutput>proc starts</computeroutput>, which is how many times the BOS Server has started or
            restarted the process since it started itself.</para>
          </listitem>

          <listitem>
            <para>The <computeroutput>Last exit</computeroutput> time when the process (or one of the component processes in the
            <emphasis role="bold">fs</emphasis> process) last terminated. This line does not appear if the process has not
            terminated since the BOS Server started.</para>
          </listitem>

          <listitem>
            <para>The <computeroutput>Last error exit</computeroutput> time when the process (or one of the component processes in
            the <emphasis role="bold">fs</emphasis> process) last failed due to an error. A further explanation such as
            <computeroutput>due to shutdown request</computeroutput> sometimes appears. This line does not appear if the process has
            not failed since the BOS Server started.</para>
          </listitem>

          <listitem>
            <para>Each command that the BOS Server invokes to start the process, as specified by the <emphasis
            role="bold">-cmd</emphasis> argument to the <emphasis role="bold">bos create</emphasis> command.</para>
          </listitem>

          <listitem>
            <para>The pathname of the notifier program that the BOS Server invokes when the process terminates (if any), as
            specified by the <emphasis role="bold">-notifier</emphasis> argument to the <emphasis role="bold">bos create</emphasis>
            command.</para>
          </listitem>
        </itemizedlist></para>

      <para>In addition, if the BOS Server has found that the mode bits on certain files and directories under <emphasis
      role="bold">/usr/afs</emphasis> deviate from what it expects, it prints the following warning message:</para>

      <programlisting>
   Bosserver process reports inappropriate access on server directories
</programlisting>

      <para>The expected protections for the directories and files in the <emphasis role="bold">/usr/afs</emphasis> directory are as
      follows. A question mark indicates that the BOS Server does not check the mode bit. See the <emphasis>OpenAFS Quick
      Beginnings</emphasis> for more information about setting the protections on these files and directories.</para>

      <informaltable frame="none">
        <tgroup cols="2">
          <tbody>
            <row>
              <entry><emphasis role="bold">/usr/afs</emphasis></entry>

              <entry><computeroutput>drwxr?xr-x</computeroutput></entry>
            </row>

            <row>
              <entry><emphasis role="bold">/usr/afs/backup</emphasis></entry>

              <entry><computeroutput>drwx???---</computeroutput></entry>
            </row>

            <row>
              <entry><emphasis role="bold">/usr/afs/bin</emphasis></entry>

              <entry><computeroutput>drwxr?xr-x</computeroutput></entry>
            </row>

            <row>
              <entry><emphasis role="bold">/usr/afs/db</emphasis></entry>

              <entry><computeroutput>drwx???---</computeroutput></entry>
            </row>

            <row>
              <entry><emphasis role="bold">/usr/afs/etc</emphasis></entry>

              <entry><computeroutput>drwxr?xr-x</computeroutput></entry>
            </row>

            <row>
              <entry><emphasis role="bold">/usr/afs/etc/KeyFile</emphasis></entry>

              <entry><computeroutput>-rw????---</computeroutput></entry>
            </row>

            <row>
              <entry><emphasis role="bold">/usr/afs/etc/UserList</emphasis></entry>

              <entry><computeroutput>-rw?????--</computeroutput></entry>
            </row>

            <row>
              <entry><emphasis role="bold">/usr/afs/local</emphasis></entry>

              <entry><computeroutput>drwx???---</computeroutput></entry>
            </row>

            <row>
              <entry><emphasis role="bold">/usr/afs/logs</emphasis></entry>

              <entry><computeroutput>drwxr?xr-x</computeroutput></entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>

      <para>The following illustrates the extended output for the <emphasis role="bold">fs</emphasis> process running on the machine
      <emphasis role="bold">fs3.abc.com</emphasis>:</para>

      <programlisting>
   % <emphasis role="bold">bos status fs3.abc.com fs -long</emphasis>
   Instance fs, (type is fs), currently running normally.
       Auxiliary status is file server running
   Process last started at Mon May 3 8:29:19 1999 (3 proc starts)
   Last exit at Mon May 3 8:29:19 1999
   Last error exit at Mon May 3 8:29:19 1999, due to shutdown request
   Command 1 is '/usr/afs/bin/fileserver'
   Command 2 is '/usr/afs/bin/volserver'
   Command 3 is '/usr/afs/bin/salvager'
</programlisting>
    </sect2>
  </sect1>

  <sect1 id="HDRWQ161">
    <title>Creating and Removing Processes</title>

    <indexterm>
      <primary>initializing</primary>

      <secondary>server process</secondary>
    </indexterm>

    <indexterm>
      <primary>creating</primary>

      <secondary>server process</secondary>
    </indexterm>

    <indexterm>
      <primary>defining</primary>

      <secondary>server process in BosConfig file</secondary>
    </indexterm>

    <indexterm>
      <primary>starting</primary>

      <secondary>server process</secondary>
    </indexterm>

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

      <secondary>creating</secondary>
    </indexterm>

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

      <secondary>starting</secondary>
    </indexterm>

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

      <secondary>stopping permanently</secondary>
    </indexterm>

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

      <secondary>removing from BosConfig file</secondary>
    </indexterm>

    <para>To start a new AFS server process on a server machine, issue the <emphasis role="bold">bos create</emphasis> command,
    which creates an entry in the <emphasis role="bold">/usr/afs/local/BosConfig</emphasis> file, sets the process's status flag to
    <computeroutput>Run</computeroutput> both in the file and in the BOS Server's memory, and starts it running immediately. The
    binary file for the new process must already be installed, by convention in the <emphasis role="bold">/usr/afs/bin</emphasis>
    directory (see <link linkend="HDRWQ111">Installing New Binaries</link>).</para>

    <para>To stop a process permanently, first issue the <emphasis role="bold">bos stop</emphasis> command, which changes the
    process's status flag to <computeroutput>NotRun</computeroutput> in both the <emphasis role="bold">BosConfig</emphasis> file and
    the BOS Server's memory; it is marked as <computeroutput>disabled</computeroutput> in the output from the <emphasis
    role="bold">bos status</emphasis> command. If desired, issue the <emphasis role="bold">bos delete</emphasis> command to remove
    the process's entry from the <emphasis role="bold">BosConfig</emphasis> file; the process no longer appears in the <emphasis
    role="bold">bos status</emphasis> command's output.</para>

    <note>
      <para>If you are starting or stopping a database server process in the manner described in this section, follow the complete
      instructions in the <emphasis>OpenAFS Quick Beginnings</emphasis> for creating or removing a database server machine. If you
      run one database server process on a given machine, you must run them all; for more information, see <link
      linkend="HDRWQ156">About Starting and Stopping the Database Server Processes</link>. Similarly, if you are stopping the
      <emphasis role="bold">upserver</emphasis> process on the system control machine or a binary distribution machine, you must
      complete the additional tasks described in <link linkend="HDRWQ157">About Starting and Stopping the Update
      Server</link>.</para>
    </note>

    <sect2 id="HDRWQ162">
      <title>To create and start a new process</title>

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

        <secondary>creating and starting</secondary>
      </indexterm>

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

        <secondary>defining in BosConfig file</secondary>
      </indexterm>

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

        <secondary>defining in BosConfig file</secondary>
      </indexterm>

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

        <secondary>defining in BosConfig file</secondary>
      </indexterm>

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

        <secondary>defining in BosConfig file</secondary>
      </indexterm>

      <indexterm>
        <primary>BosConfig file</primary>

        <secondary>creating server process entry</secondary>
      </indexterm>

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

        <secondary>create</secondary>
      </indexterm>

      <indexterm>
        <primary>commands</primary>

        <secondary>bos create</secondary>
      </indexterm>

      <orderedlist>
        <listitem>
          <para>Verify that you are authenticated as a user 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><emphasis role="bold">(Optional)</emphasis> Verify that the process's binaries are installed in the <emphasis
          role="bold">/usr/afs/bin</emphasis> directory on this machine. If necessary, login at the console or telnet to the machine
          and list the contents of the <emphasis role="bold">/usr/afs/bin</emphasis> directory.</para>

          <para>If the binaries are not present, install them on the binary distribution machine of the appropriate system type, and
          wait for the Update Server to copy them to this machine. For instructions, see <link linkend="HDRWQ111">Installing New
          Binaries</link>.</para>

          <programlisting>
   % <emphasis role="bold">ls /usr/afs/bin</emphasis>
</programlisting>
        </listitem>

        <listitem>
          <para>Issue the <emphasis role="bold">bos create</emphasis> command to create an entry in the
          <emphasis role="bold">BosConfig</emphasis> file and start the process. <programlisting>
   % <emphasis role="bold">bos create</emphasis> &lt;<replaceable>machine name</replaceable>&gt; &lt;<replaceable>server process name</replaceable>&gt;   \
             &lt;<replaceable>server type</replaceable>&gt; &lt;<replaceable>command lines</replaceable>&gt;+ [ <emphasis
                role="bold">-notifier</emphasis> &lt;<replaceable>Notifier program</replaceable>&gt;]
</programlisting></para>

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

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

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

                <listitem>
                  <para>Specifies the file server machine on which to create the process.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">server process name</emphasis></term>

                <listitem>
                  <para>Names the process to create and start. For simple processes, the conventional value is the name of the
                  process's binary file. It is best to use the same name on every server machine that runs the process. The
                  following is a list of the conventional names for simple and fs-type processes (there are no standard cron
                  processes). <itemizedlist>
                      <listitem>
                        <para><emphasis role="bold">buserver</emphasis> for the Backup Server</para>
                      </listitem>

                      <listitem>
                        <para><emphasis role="bold">fs</emphasis> for the process that combines the File Server, Volume Server, and
                        Salvager</para>
                      </listitem>

                      <listitem>
                        <para><emphasis role="bold">kaserver</emphasis> for the Authentication Server</para>
                      </listitem>

                      <listitem>
                        <para><emphasis role="bold">ptserver</emphasis> for the Protection Server</para>
                      </listitem>

                      <listitem>
                        <para><emphasis role="bold">runntp</emphasis> for the controller process for the Network Time Protocol
                        Daemon</para>
                      </listitem>

                      <listitem>
                        <para><emphasis role="bold">upclientbin</emphasis> for the client portion of the Update Server that
                        references the binary distribution machine of this machine's system type</para>
                      </listitem>

                      <listitem>
                        <para><emphasis role="bold">upclientetc</emphasis> for the client portion of the Update Server that
                        references the system control machine</para>
                      </listitem>

                      <listitem>
                        <para><emphasis role="bold">vlserver</emphasis> for the Volume Location (VL) Server</para>
                      </listitem>
                    </itemizedlist></para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">server type</emphasis></term>

                <listitem>
                  <para>Defines the process's type. Choose one of the following values: <itemizedlist>
                      <listitem>
                        <para><emphasis role="bold">cron</emphasis> for a cron process</para>
                      </listitem>

                      <listitem>
                        <para><emphasis role="bold">fs</emphasis> for the process named <emphasis role="bold">fs</emphasis></para>
                      </listitem>

                      <listitem>
                        <para><emphasis role="bold">simple</emphasis> for all other processes listed as acceptable values for the
                        server process name argument</para>
                      </listitem>
                    </itemizedlist></para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">command lines</emphasis></term>

                <listitem>
                  <para>Specifies each command the BOS Server runs to start the process. Specify no more than six commands (which
                  can include the command's options, in which case the entire string is surrounded by double quotes); any additional
                  commands are ignored.</para>

                  <para>For a simple process, provide the complete pathname of the process's binary file on the local disk (for
                  example, <emphasis role="bold">/usr/afs/bin/ptserver</emphasis> for the Protection Server). If including any of
                  the initialization command's options, surround the entire command in double quotes (<emphasis role="bold">"
                  "</emphasis>). The <emphasis role="bold">upclient</emphasis> process has a required argument, and the commands for
                  all other processes take optional arguments.</para>

                  <indexterm>
                    <primary>simple process</primary>

                    <secondary>creating with bos create command</secondary>
                  </indexterm>

                  <para>For the <emphasis role="bold">fs</emphasis> process, provide the complete pathname of the local disk binary
                  file for each of the component processes: <emphasis role="bold">fileserver</emphasis>, <emphasis
                  role="bold">volserver</emphasis>, and <emphasis role="bold">salvager</emphasis>, in that order. The standard
                  binary directory is <emphasis role="bold">/usr/afs/bin</emphasis>. If including any of an initialization command's
                  options, surround the entire command in double quotes (<emphasis role="bold">" "</emphasis>).</para>

                  <indexterm>
                    <primary>fs process</primary>

                    <secondary>creating</secondary>
                  </indexterm>

                  <indexterm>
                    <primary>cron process</primary>

                    <secondary>creating with bos create command</secondary>
                  </indexterm>

                  <para>For a <emphasis role="bold">cron</emphasis> process, provide two parameters: <itemizedlist>
                      <listitem>
                        <para>The complete local disk pathname of either an executable file or a command from one of the AFS suites
                        (complete with all of the necessary arguments). Surround this parameter with double quotes (<emphasis
                        role="bold">" "</emphasis>) if it contains spaces.</para>
                      </listitem>

                      <listitem>
                        <para>A specification of when the BOS Server executes the file or command indicated by the first parameter.
                        There are three acceptable values: <itemizedlist>
                            <listitem>
                              <para>The string <emphasis role="bold">now</emphasis>, which directs the BOS Server to execute the
                              file or command immediately and only once. It is usually simpler to issue the command directly or
                              issue the <emphasis role="bold">bos exec</emphasis> command.</para>
                            </listitem>

                            <listitem>
                              <para>A time of day. The BOS Server executes the file or command daily at the indicated time. Separate
                              the hours and minutes with a colon (<emphasis>hh</emphasis>:<emphasis>MM</emphasis>), and use either
                              24-hour format, or a value in the range from <emphasis role="bold">1:00</emphasis> through <emphasis
                              role="bold">12:59</emphasis> with the addition of <emphasis role="bold">am</emphasis> or <emphasis
                              role="bold">pm</emphasis>. For example, both <emphasis role="bold">14:30</emphasis> and <emphasis
                              role="bold">"2:30 pm"</emphasis> indicate 2:30 in the afternoon. Surround this parameter with double
                              quotes (<emphasis role="bold">" "</emphasis>) if it contains a space.</para>
                            </listitem>

                            <listitem>
                              <para>A day of the week and time of day, separated by a space and surrounded with double quotes
                              (<emphasis role="bold">" "</emphasis>). The BOS Server executes the file or command weekly at the
                              indicated day and time. For the day, provide either the whole name or the first three letters, all in
                              lowercase letters (<emphasis role="bold">sunday</emphasis> or <emphasis role="bold">sun</emphasis>,
                              <emphasis role="bold">thursday</emphasis> or <emphasis role="bold">thu</emphasis>, and so on). For the
                              time, use the same format as when specifying the time alone.</para>
                            </listitem>
                          </itemizedlist></para>
                      </listitem>
                    </itemizedlist></para>
                </listitem>
              </varlistentry>

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

                <listitem>
                  <para>Specifies the pathname of a program that the BOS Server runs when the process terminates. For more
                  information on notifier programs, see the <emphasis role="bold">bos create</emphasis> command reference page in
                  the <emphasis>OpenAFS Administration Reference</emphasis>.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </listitem>
      </orderedlist>

      <para>The following example defines and starts the Protection Server on the machine <emphasis
      role="bold">db2.abc.com</emphasis>:</para>

      <programlisting>
   % <emphasis role="bold">bos create db2.abc.com ptserver simple /usr/afs/bin/ptserver</emphasis>
</programlisting>

      <para>The following example defines and starts the <emphasis role="bold">fs</emphasis> process on the machine <emphasis
      role="bold">fs6.abc.com</emphasis>.</para>

      <programlisting>
   % <emphasis role="bold">bos create fs6.abc.com fs fs /usr/afs/bin/fileserver</emphasis>   \
        <emphasis role="bold">/usr/afs/bin/volserver /usr/afs/bin/salvager</emphasis>
</programlisting>

      <para>The following example defines and starts a cron process called <emphasis role="bold">backupuser</emphasis> process on
      the machine <emphasis role="bold">fs3.abc.com</emphasis>, scheduling it to run each day at 3:00 a.m.</para>

      <programlisting>
   % <emphasis role="bold">bos create fs3.abc.com backupuser cron  "/usr/afs/bin/vos backupsys -prefix user -local" 3:00</emphasis>
</programlisting>
    </sect2>

    <sect2 id="Header_184">
      <title>To stop a process and remove it from the BosConfig file</title>

      <indexterm>
        <primary>removing</primary>

        <secondary>server process from BosConfig file</secondary>
      </indexterm>

      <indexterm>
        <primary>BosConfig file</primary>

        <secondary>removing server process entry</secondary>
      </indexterm>

      <indexterm>
        <primary>stopping</primary>

        <secondary>server process</secondary>

        <tertiary>permanently</tertiary>
      </indexterm>

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

        <secondary>removing from BosConfig file</secondary>
      </indexterm>

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

        <secondary>stopping permanently</secondary>
      </indexterm>

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

        <secondary>delete</secondary>
      </indexterm>

      <indexterm>
        <primary>commands</primary>

        <secondary>bos delete</secondary>
      </indexterm>

      <orderedlist>
        <listitem>
          <para>Verify that you are authenticated as a user 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 id="LIPROC-STOP">
          <para>Issue the <emphasis role="bold">bos stop</emphasis> command to change each process's
          status flag in the <emphasis role="bold">BosConfig</emphasis> file to <computeroutput>NotRun</computeroutput> and to stop
          it. You must issue this command even for cron processes that you wish to remove from the <emphasis
          role="bold">BosConfig</emphasis> file, even though they do not run continuously. For a detailed description of this
          command, see <link linkend="HDRWQ165">To stop a process by changing its status to
          <computeroutput>NotRun</computeroutput></link>. <programlisting>
   % <emphasis role="bold">bos stop</emphasis> &lt;<replaceable>machine name</replaceable>&gt; &lt;<replaceable>server process name</replaceable>&gt;+ [<emphasis
                role="bold">-wait</emphasis>]
</programlisting></para>
        </listitem>

        <listitem>
          <para>Issue the <emphasis role="bold">bos delete</emphasis> command to remove each process from
          the <emphasis role="bold">BosConfig</emphasis> file. <programlisting>
   % <emphasis role="bold">bos delete</emphasis> &lt;<replaceable>machine name</replaceable>&gt; &lt;<replaceable>server process name</replaceable>&gt;+
</programlisting></para>

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

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

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

                <listitem>
                  <para>Specifies the server machine on which to remove processes from the <emphasis
                  role="bold">BosConfig</emphasis> file.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">server process name</emphasis></term>

                <listitem>
                  <para>Names each process entry to remove from the <emphasis role="bold">BosConfig</emphasis> file. Provide the
                  same names as in Step <link linkend="LIPROC-STOP">2</link>.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </listitem>
      </orderedlist>
    </sect2>
  </sect1>

  <sect1 id="HDRWQ164">
    <title>Stopping and Starting Processes Permanently</title>

    <indexterm>
      <primary>starting</primary>

      <secondary>server process</secondary>
    </indexterm>

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

      <secondary>starting up</secondary>
    </indexterm>

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

      <secondary>stopping permanently</secondary>
    </indexterm>

    <indexterm>
      <primary>stopping</primary>

      <secondary>server process</secondary>

      <tertiary>permanently</tertiary>
    </indexterm>

    <para>To stop a process so that the BOS Server no longer attempts to monitor it, issue the <emphasis role="bold">bos
    stop</emphasis> command. The process's status flag is set to <computeroutput>NotRun</computeroutput> in both the BOS Server's
    memory and in the <emphasis role="bold">BosConfig</emphasis> file. The process does not run again until you issue the <emphasis
    role="bold">bos start</emphasis> command, which sets its status flag back to <computeroutput>Run</computeroutput> in both the
    BOS Server's memory and in the <emphasis role="bold">BosConfig</emphasis> file. (You can also use the <emphasis role="bold">bos
    startup</emphasis> command to start the process again without changing its status flag in the <emphasis
    role="bold">BosConfig</emphasis> file; see <link linkend="HDRWQ167">Stopping and Starting Processes Temporarily</link>.)</para>

    <para>There is no entry for the BOS Server in the <emphasis role="bold">BosConfig</emphasis> file, so the <emphasis
    role="bold">bos stop</emphasis> and <emphasis role="bold">bos start</emphasis> commands do not control it. To stop and
    immediately restart the BOS Server along with all other processes, use the <emphasis role="bold">-bosserver</emphasis> flag to
    the <emphasis role="bold">bos restart</emphasis> command as described in <link linkend="HDRWQ170">Stopping and Immediately
    Restarting Processes</link>.</para>

    <note>
      <para>If you are starting or stopping a database server process in the manner described in this section, follow the complete
      instructions in the <emphasis>OpenAFS Quick Beginnings</emphasis> for creating or removing a database server machine. If you
      run one database server process on a given machine, you must run them all; for more information, see <link
      linkend="HDRWQ156">About Starting and Stopping the Database Server Processes</link>. Similarly, if you are stopping the
      <emphasis role="bold">upserver</emphasis> process on the system control machine or a binary distribution machine, you must
      complete the additional tasks described in <link linkend="HDRWQ157">About Starting and Stopping the Update
      Server</link>.</para>
    </note>

    <sect2 id="HDRWQ165">
      <title>To stop a process by changing its status to NotRun</title>

      <indexterm>
        <primary>Run status flag in BosConfig file</primary>

        <secondary>changing to NotRun</secondary>
      </indexterm>

      <indexterm>
        <primary>status flag in BosConfig file</primary>

        <secondary>changing Run to NotRun</secondary>
      </indexterm>

      <indexterm>
        <primary>BosConfig file</primary>

        <secondary>changing status flag from Run to NotRun</secondary>
      </indexterm>

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

        <secondary>stopping permanently</secondary>
      </indexterm>

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

        <secondary>stop</secondary>
      </indexterm>

      <indexterm>
        <primary>commands</primary>

        <secondary>bos stop</secondary>
      </indexterm>

      <orderedlist>
        <listitem>
          <para>Verify that you are authenticated as a user 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 stop</emphasis> command to stop each process and set its status flag to
          <computeroutput>NotRun</computeroutput> in the <emphasis role="bold">BosConfig</emphasis> file and the BOS Server's
          memory. <programlisting>
   % <emphasis role="bold">bos stop</emphasis> &lt;<replaceable>machine name</replaceable>&gt; &lt;<replaceable>server process name</replaceable>&gt;+ [<emphasis
                role="bold">-wait</emphasis>]
</programlisting></para>

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

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

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

                <listitem>
                  <para>Specifies the server machine on which to stop the process.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">server process name</emphasis></term>

                <listitem>
                  <para>Names each process to stop, using the name assigned when its entry was defined with the <emphasis
                  role="bold">bos create</emphasis> command.</para>
                </listitem>
              </varlistentry>

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

                <listitem>
                  <para>Delays the return of the command shell prompt until all specified processes have stopped. If you omit the
                  flag, the prompt returns almost immediately, even if all processes are not yet stopped.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </listitem>
      </orderedlist>
    </sect2>

    <sect2 id="HDRWQ166">
      <title>To start processes by changing their status flags to Run</title>

      <indexterm>
        <primary>NotRun status flag in BosConfig file</primary>

        <secondary>changing to Run</secondary>
      </indexterm>

      <indexterm>
        <primary>status flag in BosConfig file</primary>

        <secondary>changing NotRun to Run</secondary>
      </indexterm>

      <indexterm>
        <primary>BosConfig file</primary>

        <secondary>changing status flag from NotRun to Run</secondary>
      </indexterm>

      <indexterm>
        <primary>commands</primary>

        <secondary>bos start</secondary>
      </indexterm>

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

        <secondary>start</secondary>
      </indexterm>

      <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 start</emphasis> command to change each process's
          status flag to <computeroutput>Run</computeroutput> in both the <emphasis role="bold">BosConfig</emphasis> file and the
          BOS Server's memory and to start it. <programlisting>
   %  <emphasis role="bold">bos start</emphasis> &lt;<replaceable>machine name</replaceable>&gt; &lt;<replaceable>server process name</replaceable>&gt;+
</programlisting></para>

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

                <listitem>
                  <para>Must be typed in full.</para>
                </listitem>
              </varlistentry>

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

                <listitem>
                  <para>Specifies the server machine on which to start running each process.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">server process name</emphasis></term>

                <listitem>
                  <para>Specifies each process to start on machine name. Use the name assigned to the process at creation.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </listitem>
      </orderedlist>
    </sect2>
  </sect1>

  <sect1 id="HDRWQ167">
    <title>Stopping and Starting Processes Temporarily</title>

    <para>It is sometimes necessary to halt a process temporarily (for example, to make slight configuration changes or to perform
    maintenance). The commands described in this section change a process's status in the BOS Server's memory only; the effect is
    immediate and lasts until you change the memory state again (or until the BOS Server restarts, at which time it starts the
    process according to its entry in the <emphasis role="bold">BosConfig</emphasis> file).</para>

    <para>To stop a process temporarily by changing its status flag in BOS Server memory to <computeroutput>NotRun</computeroutput>,
    use the <emphasis role="bold">bos shutdown</emphasis> command. To restart a stopped process by changing its status flag in the
    BOS Server's memory to <computeroutput>Run</computeroutput>, use the <emphasis role="bold">bos startup</emphasis> command. The
    process starts regardless of its status flag in the <emphasis role="bold">BosConfig</emphasis> file. You can also use the
    <emphasis role="bold">bos startup</emphasis> command to start all processes marked with status flag
    <computeroutput>Run</computeroutput> in the <emphasis role="bold">BosConfig</emphasis> file, as described in the following
    instructions.</para>

    <para>Because the <emphasis role="bold">bos startup</emphasis> command starts a process without changing it status flag in the
    <emphasis role="bold">BosConfig</emphasis> file, it is useful for testing a server process without enabling it permanently. To
    stop and start processes by changing their status flags in the <emphasis role="bold">BosConfig</emphasis> file, see <link
    linkend="HDRWQ164">Stopping and Starting Processes Permanently</link>; to stop and immediately restart a process, see <link
    linkend="HDRWQ170">Stopping and Immediately Restarting Processes</link>.</para>

    <note>
      <para>Do not temporarily stop a database server process on all machines at once. Doing so makes the database completely
      unavailable.</para>
    </note>

    <indexterm>
      <primary>commands</primary>

      <secondary>bos shutdown</secondary>
    </indexterm>

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

      <secondary>shutdown</secondary>
    </indexterm>

    <sect2 id="HDRWQ168">
      <title>To stop processes temporarily</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 shutdown</emphasis> command to stop each process by
          changing its status flag in the BOS Server's memory to <computeroutput>NotRun</computeroutput>. <programlisting>
   % <emphasis role="bold">bos shutdown</emphasis> &lt;<replaceable>machine name</replaceable>&gt; [&lt;<replaceable>instances</replaceable>&gt;+] [<emphasis
                role="bold">-wait</emphasis>]
</programlisting></para>

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

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

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

                <listitem>
                  <para>Specifies the server machine on which to stop processes temporarily.</para>
                </listitem>
              </varlistentry>

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

                <listitem>
                  <para>Specifies each process to stop temporarily. Use the name assigned to the process at creation.</para>
                </listitem>
              </varlistentry>

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

                <listitem>
                  <para>Delays the return of the command shell prompt until all specified processes have actually stopped. If you
                  omit the flag, the prompt returns almost immediately, even if all processes are not yet stopped.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </listitem>
      </orderedlist>

      <indexterm>
        <primary>commands</primary>

        <secondary>bos startup</secondary>
      </indexterm>

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

        <secondary>startup</secondary>
      </indexterm>
    </sect2>

    <sect2 id="Header_190">
      <title>To start all stopped processes that have status flag Run in the BosConfig 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 startup</emphasis> command to start each process on a machine that has status
          flag <computeroutput>Run</computeroutput> in the <emphasis role="bold">BosConfig</emphasis> file by changing its status
          flag in the BOS Server's memory from <computeroutput>NotRun</computeroutput> to <computeroutput>Run</computeroutput>.
          <programlisting>
   % <emphasis role="bold">bos startup</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
</programlisting></para>

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

                <listitem>
                  <para>Must be typed in full.</para>
                </listitem>
              </varlistentry>

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

                <listitem>
                  <para>Specifies the server machine on which you wish to start all processes that have status flag
                  <computeroutput>Run</computeroutput> in the <emphasis role="bold">BosConfig</emphasis> file.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </listitem>
      </orderedlist>
    </sect2>

    <sect2 id="Header_191">
      <title>To start specific processes</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 startup</emphasis> command to start specific processes by changing their status
          flags in the BOS Server's memory to <computeroutput>Run</computeroutput> without changing their status flags in the
          <emphasis role="bold">BosConfig</emphasis> file. <programlisting>
   % <emphasis role="bold">bos startup</emphasis> &lt;<replaceable>machine name</replaceable>&gt; &lt;<replaceable>instances</replaceable>&gt;+
</programlisting></para>

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

                <listitem>
                  <para>Must be typed in full.</para>
                </listitem>
              </varlistentry>

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

                <listitem>
                  <para>Names the server machine on which to start processes.</para>
                </listitem>
              </varlistentry>

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

                <listitem>
                  <para>Specifies each process to start. Use the name assigned to the process at creation.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </listitem>
      </orderedlist>
    </sect2>
  </sect1>

  <sect1 id="HDRWQ170">
    <title>Stopping and Immediately Restarting Processes</title>

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

      <secondary>restarting immediately after stopping</secondary>
    </indexterm>

    <indexterm>
      <primary>stopping</primary>

      <secondary>server process and immediately restarting</secondary>
    </indexterm>

    <para>Although by default the BOS Server checks each day for new installed binary files and restarts the associated processes,
    it is sometimes desirable to stop and restart processes immediately. The <emphasis role="bold">bos restart</emphasis> command
    provides this functionality, starting a completely new instance of each affected process: <itemizedlist>
        <listitem>
          <para>To stop and restart the BOS Server, which then restarts all processes marked with the
          <computeroutput>Run</computeroutput> status flag in the <emphasis role="bold">BosConfig</emphasis> file, include the
          <emphasis role="bold">-bosserver</emphasis> flag.</para>
        </listitem>

        <listitem>
          <para>To stop and restart all processes marked with the <computeroutput>Run</computeroutput> status flag in the <emphasis
          role="bold">BosConfig</emphasis> file, include the <emphasis role="bold">-all</emphasis> flag. The BOS Server does not
          restart</para>
        </listitem>

        <listitem>
          <para>To stop and restart specific processes regardless of the setting of their status flags in the <emphasis
          role="bold">BosConfig</emphasis> file, specify the name of each process to restart.</para>
        </listitem>
      </itemizedlist></para>

    <para>Restarting processes causes a service outage. It is usually best to schedule restarts for periods of low usage. The BOS
    Server automatically restarts all processes once a week, to reduce the potential for the <emphasis>core leaks</emphasis> that
    can develop as any process runs for an extended time; see <link linkend="HDRWQ171">Setting the BOS Server's Restart
    Times</link>.</para>

    <indexterm>
      <primary>outages</primary>

      <secondary>due to server process restart</secondary>
    </indexterm>

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

      <secondary>due to server process restart</secondary>
    </indexterm>

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

        <secondary>restarting by restarting BOS Server</secondary>
      </indexterm> <indexterm>
        <primary>restarting</primary>

        <secondary>server process</secondary>

        <tertiary>including BOS Server</tertiary>
      </indexterm> <indexterm>
        <primary>bos commands</primary>

        <secondary>restart</secondary>

        <tertiary>with -bosserver flag</tertiary>
      </indexterm> <indexterm>
        <primary>bos commands</primary>

        <secondary>restart</secondary>

        <tertiary>including BOS Server</tertiary>
      </indexterm> <indexterm>
        <primary>commands</primary>

        <secondary>bos restart</secondary>

        <tertiary>including BOS Server</tertiary>
      </indexterm></para>

    <sect2 id="Header_193">
      <title>To stop and restart all processes including the BOS Server</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 restart</emphasis> command with the <emphasis role="bold">-bosserver</emphasis>
          flag to stop and restart the BOS Server, which restarts every process marked with status flag
          <computeroutput>Run</computeroutput> in the <emphasis role="bold">BosConfig</emphasis> file. <programlisting>
   % <emphasis role="bold">bos restart</emphasis> &lt;<replaceable>machine name</replaceable>&gt;  <emphasis role="bold">-bosserver</emphasis>
</programlisting></para>

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

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

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

                <listitem>
                  <para>Specifies the server machine on which to restart all processes.</para>
                </listitem>
              </varlistentry>

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

                <listitem>
                  <para>Stops the BOS Server and all processes running on the machine. A new BOS Server instance starts; it then
                  starts new instances of all processes marked with status flag <computeroutput>Run</computeroutput> in the
                  <emphasis role="bold">BosConfig</emphasis> file.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </listitem>
      </orderedlist>

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

        <secondary>restart</secondary>

        <tertiary>excluding BOS Server</tertiary>
      </indexterm>

      <indexterm>
        <primary>commands</primary>

        <secondary>bos restart</secondary>

        <tertiary>excluding BOS Server</tertiary>
      </indexterm>

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

        <secondary>restarting</secondary>

        <tertiary>except BOS Server</tertiary>
      </indexterm>

      <indexterm>
        <primary>restarting</primary>

        <secondary>server process</secondary>

        <tertiary>except BOS Server</tertiary>
      </indexterm>
    </sect2>

    <sect2 id="Header_194">
      <title>To stop and immediately restart all processes except the BOS Server</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 restart</emphasis> command with the <emphasis role="bold">-all</emphasis> flag
          to stop and immediately restart every process marked with status flag <computeroutput>Run</computeroutput> in the
          <emphasis role="bold">BosConfig</emphasis> file. The BOS Server does not restart. <programlisting>
   % <emphasis role="bold">bos restart</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">-all</emphasis>
</programlisting></para>

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

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

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

                <listitem>
                  <para>Specifies the server machine on which to stop and restart processes.</para>
                </listitem>
              </varlistentry>

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

                <listitem>
                  <para>Stops and immediately restarts all processes marked with status flag <computeroutput>Run</computeroutput> in
                  the <emphasis role="bold">BosConfig</emphasis> file.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </listitem>
      </orderedlist>

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

        <secondary>restart</secondary>

        <tertiary>selected processes</tertiary>
      </indexterm>

      <indexterm>
        <primary>commands</primary>

        <secondary>bos restart</secondary>

        <tertiary>selected processes</tertiary>
      </indexterm>

      <indexterm>
        <primary>restarting</primary>

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

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

        <secondary>restarting specific processes</secondary>
      </indexterm>
    </sect2>

    <sect2 id="Header_195">
      <title>To stop and immediately restart specific processes</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 restart</emphasis> command to stop and immediately restart one or more specified
          processes, regardless of their status flag setting in the <emphasis role="bold">BosConfig</emphasis> file.
          <programlisting>
   % <emphasis role="bold">bos restart</emphasis> &lt;<replaceable>machine name</replaceable>&gt; &lt;<replaceable>instances</replaceable>&gt;+
</programlisting></para>

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

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

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

                <listitem>
                  <para>Names the server machine on which to restart the specified processes.</para>
                </listitem>
              </varlistentry>

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

                <listitem>
                  <para>Specifies each process to stop and immediately restart. Use the name assigned to the process at
                  creation.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </listitem>
      </orderedlist>
    </sect2>
  </sect1>

  <sect1 id="HDRWQ171">
    <title>Setting the BOS Server's Restart Times</title>

    <indexterm>
      <primary>core leak</primary>

      <secondary>preventing with scheduled restarts</secondary>
    </indexterm>

    <indexterm>
      <primary>preventing</primary>

      <secondary>core leaks, with scheduled BOS Server restarts</secondary>
    </indexterm>

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

      <secondary>restart times, displaying and setting</secondary>
    </indexterm>

    <indexterm>
      <primary>automatic</primary>

      <secondary>process restarts by BOS Server</secondary>
    </indexterm>

    <indexterm>
      <primary>weekly restart of BOS Server (automatic)</primary>

      <secondary>displaying and setting time</secondary>
    </indexterm>

    <indexterm>
      <primary>restart time for BOS Server (automatic)</primary>

      <secondary>displaying and setting time</secondary>
    </indexterm>

    <indexterm>
      <primary>restart times for BOS Server</primary>

      <secondary>displaying and setting</secondary>
    </indexterm>

    <indexterm>
      <primary>daily restart for new binaries</primary>

      <secondary>displaying and setting time</secondary>
    </indexterm>

    <indexterm>
      <primary>restart times for BOS Server</primary>

      <secondary>setting</secondary>
    </indexterm>

    <para>The BOS Server by default has general restarts disabled. If you wish, it may be configured so that it
    restarts once a week, and the new instance restarts all processes marked with status flag
    <computeroutput>Run</computeroutput> in the local <emphasis role="bold">/usr/afs/local/BosConfig</emphasis> file (this is
    equivalent to issuing the <emphasis role="bold">bos restart</emphasis> command with the <emphasis
    role="bold">-bosserver</emphasis> flag). Historically, the default restart time was Sunday at 4:00 a.m - sites which have
    been upgraded from earlier versions of OpenAFS may find that this value is still present. The weekly restart was designed to
    minimize core leaks, which can develop as a process continues to allocate virtual memory but does not free it again. It is
    believed that these leaks have been fixed in OpenAFS.</para>

    <para>The BOS Server also by default checks once a day for any newly installed binary files. If it finds that the modification
    time stamp on a process's binary file in the <emphasis role="bold">/usr/afs/bin</emphasis> directory is more recent than the
    time at which the process last started, it restarts the process so that a new instance starts using the new binary file. The
    default binary-checking time is 5:00 a.m.</para>

    <para>Because restarts can cause outages during which the file system is inaccessible, the default times for restarts are in the
    early morning when usage is likely to be lowest. Restarting a database server process on any database server machine usually
    makes the entire system unavailable to everyone for a brief time, whereas restarting other types of processes inconveniences
    only users interacting with that process on that machine. The longest outages typically result from restarting the <emphasis
    role="bold">fs</emphasis> process, because the File Server must reattach all volumes.</para>

    <indexterm>
      <primary>outages</primary>

      <secondary>due to automatic server restart</secondary>
    </indexterm>

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

      <secondary>due to automatic server restart</secondary>
    </indexterm>

    <indexterm>
      <primary>BosConfig file</primary>

      <secondary>restart times defined</secondary>
    </indexterm>

    <para>The <emphasis role="bold">BosConfig</emphasis> file on each file server machine records the two restart times. To display
    the current setting, issue the <emphasis role="bold">bos getrestart</emphasis> command. To reset a time, use the <emphasis
    role="bold">bos setrestart</emphasis> command.</para>

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

      <secondary>getrestart</secondary>
    </indexterm>

    <indexterm>
      <primary>commands</primary>

      <secondary>bos getrestart</secondary>
    </indexterm>

    <indexterm>
      <primary>displaying</primary>

      <secondary>BOS Server's automatic restart times</secondary>
    </indexterm>

    <sect2 id="Header_197">
      <title>To display the BOS Server restart times</title>

      <orderedlist>
        <listitem>
          <para>Issue the <emphasis role="bold">bos getrestart</emphasis> command to display the automatic restart times.
          <programlisting>
   % <emphasis role="bold">bos getrestart</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
</programlisting></para>

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

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

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

                <listitem>
                  <para>Specifies the server machine for which to display the restart times.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </listitem>
      </orderedlist>

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

        <secondary>setrestart</secondary>
      </indexterm>

      <indexterm>
        <primary>commands</primary>

        <secondary>bos setrestart</secondary>
      </indexterm>

      <indexterm>
        <primary>setting</primary>

        <secondary>BOS Server's automatic restart times</secondary>
      </indexterm>
    </sect2>

    <sect2 id="HDRWQ172">
      <title>To set the general or binary restart time</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 setrestart</emphasis> command with the <emphasis role="bold">-general</emphasis>
          flag to set the general restart time or the <emphasis role="bold">-newbinary</emphasis> flag to set the binary restart
          time. The command accepts only one of the flags at a time. <programlisting>
   % <emphasis role="bold">bos setrestart</emphasis> &lt;<replaceable>machine name</replaceable>&gt; "&lt;<replaceable>time to restart server</replaceable>&gt;" [<emphasis
                role="bold">-general</emphasis>]  [<emphasis role="bold">-newbinary</emphasis>]
</programlisting></para>

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

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

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

                <listitem>
                  <para>Specifies the server machine.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">time to restart server</emphasis></term>

                <listitem>
                  <para>Sets when the BOS Server restarts itself (if combined with the <emphasis role="bold">-general</emphasis>
                  flag) or any process with a new binary file (if combined with the <emphasis role="bold">-newbinary</emphasis>
                  flag). Provide one of the following types of values: <itemizedlist>
                      <listitem>
                        <para>The string <emphasis role="bold">never</emphasis>, which directs the BOS Server never to perform the
                        indicated type of restart.</para>
                      </listitem>

                      <listitem>
                        <para>A time of day (the conventional type of value for the binary restart time). Separate the hours and
                        minutes with a colon (<emphasis>hh</emphasis>:<emphasis>MM</emphasis>), and use either 24-hour format, or a
                        value in the range from <emphasis role="bold">1:00</emphasis> through <emphasis role="bold">12:59</emphasis>
                        with the addition of <emphasis role="bold">am</emphasis> or <emphasis role="bold">pm</emphasis>. For
                        example, both <emphasis role="bold">14:30</emphasis> and <emphasis role="bold">"2:30 pm"</emphasis> indicate
                        2:30 in the afternoon. Surround this parameter with double quotes (<emphasis role="bold">" "</emphasis>) if
                        it contains a space.</para>
                      </listitem>

                      <listitem>
                        <para>A day of the week and time of day, separated by a space and surrounded with double quotes (<emphasis
                        role="bold">" "</emphasis>). This is the conventional type of value for the general restart. For the day,
                        provide either the whole name or the first three letters, all in lowercase letters (<emphasis
                        role="bold">sunday</emphasis> or <emphasis role="bold">sun</emphasis>, <emphasis
                        role="bold">thursday</emphasis> or <emphasis role="bold">thu</emphasis>, and so on). For the time, use the
                        same format as when specifying the time alone.</para>
                      </listitem>
                    </itemizedlist></para>

                  <para>If desired, precede a time or day and time definition with the string <emphasis role="bold">every</emphasis>
                  or <emphasis role="bold">at</emphasis>. These words do not change the meaning, but possibly make the output of the
                  <emphasis role="bold">bos getrestart</emphasis> command easier to understand.</para>

                  <note>
                    <para>If the specified time is within one hour of the current time, the BOS Server does not perform the restart
                    until the next eligible time (the next day for a time or next week for a day and time).</para>
                  </note>
                </listitem>
              </varlistentry>

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

                <listitem>
                  <para>Sets the general restart time when the BOS Server restarts itself.</para>
                </listitem>
              </varlistentry>

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

                <listitem>
                  <para>Sets the restart time for processes with new binary files.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </listitem>
      </orderedlist>
    </sect2>
  </sect1>

  <sect1 id="HDRWQ173">
    <title>Displaying Server Process Log Files</title>

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

      <secondary>displaying log files</secondary>
    </indexterm>

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

      <secondary>displaying log files</secondary>
    </indexterm>

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

      <secondary>displaying</secondary>
    </indexterm>

    <indexterm>
      <primary>displaying</primary>

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

    <indexterm>
      <primary>files</primary>

      <secondary>displaying log files</secondary>
    </indexterm>

    <indexterm>
      <primary>FileLog file</primary>

      <secondary>displaying</secondary>
    </indexterm>

    <indexterm>
      <primary>SalvageLog file</primary>

      <secondary>displaying</secondary>
    </indexterm>

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

      <secondary>displaying</secondary>
    </indexterm>

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

      <secondary>displaying</secondary>
    </indexterm>

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

      <secondary>displaying</secondary>
    </indexterm>

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

      <secondary>displaying</secondary>
    </indexterm>

    <indexterm>
      <primary>AuthLog file</primary>

      <secondary>displaying</secondary>
    </indexterm>

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

      <secondary>displaying log file</secondary>
    </indexterm>

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

      <secondary>displaying log file</secondary>
    </indexterm>

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

      <secondary>displaying log file</secondary>
    </indexterm>

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

      <secondary>displaying log file</secondary>
    </indexterm>

    <indexterm>
      <primary>Salvager</primary>

      <secondary>displaying log file</secondary>
    </indexterm>

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

      <secondary>displaying log file</secondary>
    </indexterm>

    <para>The <emphasis role="bold">/usr/afs/logs</emphasis> directory on each file server machine contains log files that detail
    interesting events that occur during normal operation of some AFS server processes. The self-explanatory information in the log
    files can help you evaluate process failures and other problems. To display a log file remotely, issue the <emphasis
    role="bold">bos getlog</emphasis> command. You can also establish a connection to the server machine and use a text editor or
    other file display program (such as the <emphasis role="bold">cat</emphasis> command).</para>

    <note>
      <para>Log files can grow unmanageably large if you do not periodically shutdown and restart the database server processes (for
      example, if you disable the general restart time). In this case it is a good policy periodically to issue the UNIX <emphasis
      role="bold">rm</emphasis> command to delete the current log file. The server process automatically creates a new one as
      needed.</para>
    </note>

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

      <secondary>getlog</secondary>
    </indexterm>

    <indexterm>
      <primary>commands</primary>

      <secondary>bos getlog</secondary>
    </indexterm>

    <sect2 id="Header_200">
      <title>To examine a server process log 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 getlog</emphasis> command to display a log file. <programlisting>
   % <emphasis role="bold">bos getlog</emphasis>  &lt;<replaceable>machine name</replaceable>&gt;  &lt;<replaceable>log file to examine</replaceable>&gt;
</programlisting></para>

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

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

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

                <listitem>
                  <para>Specifies the server machine from which to display the log file.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term><emphasis role="bold">log file to examine</emphasis></term>

                <listitem>
                  <para>Names the log file to be displayed. Provide one of the following file names to display the indicated log
                  file from the <emphasis role="bold">/usr/afs/logs</emphasis> directory. <itemizedlist>
                      <listitem>
                        <para><emphasis role="bold">AuthLog</emphasis> for the Authentication Server log file</para>
                      </listitem>

                      <listitem>
                        <para><emphasis role="bold">BackupLog</emphasis> for the Backup Server log file</para>
                      </listitem>

                      <listitem>
                        <para><emphasis role="bold">BosLog</emphasis> for the BOS Server log file</para>
                      </listitem>

                      <listitem>
                        <para><emphasis role="bold">FileLog</emphasis> for the File Server log file</para>
                      </listitem>

                      <listitem>
                        <para><emphasis role="bold">SalvageLog</emphasis> for the Salvager log file</para>
                      </listitem>

                      <listitem>
                        <para><emphasis role="bold">VLLog</emphasis> for the Volume Location (VL) Server log file</para>
                      </listitem>

                      <listitem>
                        <para><emphasis role="bold">VolserLog</emphasis> for the Volume Server log file</para>
                      </listitem>
                    </itemizedlist></para>

                  <para>You can provide a full or relative pathname to display a file from another directory. Relative pathnames are
                  interpreted relative to the <emphasis role="bold">/usr/afs/logs</emphasis> directory.</para>
                </listitem>
              </varlistentry>
            </variablelist></para>
        </listitem>
      </orderedlist>
    </sect2>
  </sect1>
</chapter>