doc/xml/AdminReference/sect5/BosConfig.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <refentry id="BosConfig5">
   3   <refmeta>
   4     <refentrytitle>BosConfig</refentrytitle>
   5     <manvolnum>5</manvolnum>
   6   </refmeta>
   7   <refnamediv>
   8     <refname>BosConfig</refname>
   9     <refpurpose>Defines server processes for the BOS Server to monitor</refpurpose>
  10   </refnamediv>
  11   <refsect1>
  12     <title>Description</title>
  13     <para>The <replaceable>BosConfig</replaceable> file lists the processes that the Basic OverSeer (BOS)
  14     Server monitors on its server machine, and thus defines which AFS server
  15     processes run on the machine. It specifies how the BOS Server reacts when
  16     a process fails, and also defines the times at which the BOS Server
  17     automatically restarts processes as part of performance maintenance.  The
  18     file must reside in the <replaceable>/usr/afs/local</replaceable> directory on each AFS server
  19     machine.</para>
  20
  21     <para>A server process entry in the <replaceable>BosConfig</replaceable> file records the following
  22     information:</para>
  23
  24     <itemizedlist>
  25       <listitem>
  26         <para>The <emphasis>entry type</emphasis>, which is one of the following:</para>
  27
  28         <variablelist>
  29           <varlistentry>
  30             <term>cron</term>
  31             <listitem>
  32               <para>Designates a server process that runs periodically instead of
  33               continuously. The BOS Server starts a cron process only at specified
  34               times, not whenever it fails. All standard AFS process entries except
  35               <computeroutput>fs</computeroutput> are simple (there are no standard cron processes).</para>
  36
  37             </listitem>
  38           </varlistentry>
  39           <varlistentry>
  40             <term>fs</term>
  41             <listitem>
  42               <para>Designates a group of interdependent server processes. If one of the
  43               processes fails, the BOS Server must coordinate its restart with the
  44               restart of the other processes in the group, possibly by stopping them
  45               first.</para>
  46
  47               <para>There is only one standard entry of this type, for which the conventional
  48               name is <computeroutput>fs</computeroutput>. It combines three server processes: the File Server
  49               (<emphasis role="bold">fileserver</emphasis> process), the Volume Server (<emphasis role="bold">volserver</emphasis> process), and the
  50               Salvager (<emphasis role="bold">salvager</emphasis> process). These processes all operate on the same
  51               data--the AFS data stored on an AFS server machine's <replaceable>/vicep</replaceable> partitions
  52               and mounted in the AFS filespace--but in different ways. Grouping the
  53               processes prevents them from attempting to access the same data
  54               simultaneously, which can cause corruption.</para>
  55
  56               <para>During normal operation, the Salvager process is not active. If the File
  57               Server process fails, however, the BOS Server stops the Volume Server
  58               process and runs the Salvager process to correct any corruption that
  59               resulted from the failure. (The administrator can also issue the <emphasis role="bold">bos
  60               salvage</emphasis> command to invoke the Salvager process.) If the Volume Server
  61               fails, the BOS Server can restart it without stopping the File Server or
  62               running the Salvager.</para>
  63
  64             </listitem>
  65           </varlistentry>
  66           <varlistentry>
  67             <term>simple</term>
  68             <listitem>
  69               <para>Designates a server process that runs independently of any other on the
  70               server machine. If a simple process fails, the BOS Server does not have to
  71               coordinate its restart with any other process.</para>
  72
  73             </listitem>
  74           </varlistentry>
  75         </variablelist>
  76       </listitem>
  77       <listitem>
  78         <para>The <emphasis>entry name</emphasis>. The conventional name for an entry in the <replaceable>BosConfig</replaceable>
  79         file and the associated process matches the binary filename. When issuing
  80         any <emphasis role="bold">bos</emphasis> command that takes the <emphasis role="bold">-instance</emphasis> argument, identify each
  81         process by the name used in the <replaceable>BosConfig</replaceable> file. For a list of the
  82         names, see the <emphasis role="bold">bos create</emphasis> reference page.</para>
  83
  84       </listitem>
  85       <listitem>
  86         <para>The process's <emphasis>status flag</emphasis>, which determines whether the BOS Server
  87         attempts to start the process in two cases: each time the BOS Server
  88         itself restarts, and when the process fails. The <replaceable>BosConfig</replaceable> file
  89         currently uses a binary notation to indicate whether the BOS Server
  90         attempts to restart the process as necessary or does not monitor it at
  91         all. For the sake of clarity, the AFS documentation refers to the flags as
  92         <computeroutput>Run</computeroutput> and <computeroutput>NotRun</computeroutput> instead.  Only a system administrator, not the BOS
  93         Server, can change the flag.</para>
  94
  95       </listitem>
  96       <listitem>
  97         <para>One or more <emphasis>command parameters</emphasis> which the BOS Server invokes to start
  98         the process or processes associated with the entry:</para>
  99
 100         <itemizedlist>
 101           <listitem>
 102             <para>A <computeroutput>cron</computeroutput> entry has two command parameters, the first the complete
 103             pathname to the program, and the second the time at which the BOS Server
 104             invokes the program.</para>
 105
 106           </listitem>
 107           <listitem>
 108             <para>The <computeroutput>fs</computeroutput> entry has three command parameters, each the complete pathname
 109             to the <emphasis role="bold">fileserver</emphasis>, <emphasis role="bold">volserver</emphasis>, and <emphasis role="bold">salvager</emphasis> programs, in that
 110             order.</para>
 111
 112           </listitem>
 113           <listitem>
 114             <para>A <computeroutput>simple</computeroutput> entry has only one command parameter, the complete pathname to
 115             the program.</para>
 116
 117           </listitem>
 118         </itemizedlist>
 119       </listitem>
 120     </itemizedlist>
 121     <para>In addition to server process entries, the <replaceable>BosConfig</replaceable> file specifies the
 122     times at which the BOS Server performs two types of automatic process
 123     restarts:</para>
 124
 125     <itemizedlist>
 126       <listitem>
 127         <para>The <emphasis>general restart</emphasis> time at which the BOS Server restarts itself and
 128         then each process for which the entry in the <replaceable>BosConfig</replaceable> file has status
 129         flag <computeroutput>Run</computeroutput>. The default setting is Sunday at 4:00 a.m.</para>
 130
 131       </listitem>
 132       <listitem>
 133         <para>The <emphasis>binary restart</emphasis> time at which the BOS Server restarts any server
 134         process for which the time stamp on the binary file in the <replaceable>/usr/afs/bin</replaceable>
 135         directory is later than the last restart time for the process. The default
 136         is 5:00 a.m.</para>
 137
 138       </listitem>
 139     </itemizedlist>
 140     <para>Although the <replaceable>BosConfig</replaceable> file is in ASCII format, do not use a text
 141     editor to alter it. Its format is subject to change and incorrectly
 142     formatted entries can prevent server startup in ways that are difficult to
 143     diagnose. Instead always use the appropriate commands from the <emphasis role="bold">bos</emphasis>
 144     command suite:</para>
 145
 146     <itemizedlist>
 147       <listitem>
 148         <para>The <emphasis role="bold">bos create</emphasis> command to create an entry in the file and start the
 149         associated process.</para>
 150
 151       </listitem>
 152       <listitem>
 153         <para>The <emphasis role="bold">bos delete</emphasis> command to remove an entry from the file after the <emphasis role="bold">bos
 154         stop</emphasis> command is used to stop the associated process.</para>
 155
 156       </listitem>
 157       <listitem>
 158         <para>The <emphasis role="bold">bos getrestart</emphasis> command to display the times at which the BOS Server
 159         performs automatic restarts.</para>
 160
 161       </listitem>
 162       <listitem>
 163         <para>The <emphasis role="bold">bos setrestart</emphasis> command to set the times at which the BOS Server
 164         performs automatic process restarts.</para>
 165
 166       </listitem>
 167       <listitem>
 168         <para>The <emphasis role="bold">bos start</emphasis> command to change an entry's status flag to <computeroutput>Run</computeroutput> and
 169         start the associated process.</para>
 170
 171       </listitem>
 172       <listitem>
 173         <para>The <emphasis role="bold">bos status</emphasis> command to display all processes listed in the file.</para>
 174
 175       </listitem>
 176       <listitem>
 177         <para>The <emphasis role="bold">bos stop</emphasis> command to change an entry's status flag to <computeroutput>NotRun</computeroutput> and
 178         stop the associated process.</para>
 179
 180       </listitem>
 181     </itemizedlist>
 182     <para>There are also bos commands that start and stop processes without changing
 183     entries in the <replaceable>BosConfig</replaceable> file. The BOS Server reads the <replaceable>BosConfig</replaceable>
 184     file only when it starts, transferring the information into its
 185     memory. Thus a process's status as represented in the BOS Server's memory
 186     can diverge from its status in the <replaceable>BosConfig</replaceable> file. The following
 187     commands change a process's status in the BOS Server's memory only:</para>
 188
 189     <itemizedlist>
 190       <listitem>
 191         <para>The <emphasis role="bold">bos restart</emphasis> command restarts a specified set of processes, all
 192         processes, or all processes other than the BOS Server.</para>
 193
 194       </listitem>
 195       <listitem>
 196         <para>The <emphasis role="bold">bos shutdown</emphasis> command stops a process.</para>
 197
 198       </listitem>
 199       <listitem>
 200         <para>The <emphasis role="bold">bos startup</emphasis> command starts a process.</para>
 201
 202       </listitem>
 203     </itemizedlist>
 204   </refsect1>
 205   <refsect1>
 206     <title>See Also</title>
 207     <para><link linkend="bos_create8">bos_create(8)</link>,
 208     <link linkend="bos_delete8">bos_delete(8)</link>,
 209     <link linkend="bos_getrestart8">bos_getrestart(8)</link>,
 210     <link linkend="bos_restart8">bos_restart(8)</link>,
 211     <link linkend="bos_setrestart8">bos_setrestart(8)</link>,
 212     <link linkend="bos_shutdown8">bos_shutdown(8)</link>,
 213     <link linkend="bos_start8">bos_start(8)</link>,
 214     <link linkend="bos_startup8">bos_startup(8)</link>,
 215     <link linkend="bos_status8">bos_status(8)</link>,
 216     <link linkend="bos_stop8">bos_stop(8)</link>,
 217     <link linkend="bos_salvage8">bos_salvage(8)</link>,
 218     <link linkend="fileserver8">fileserver(8)</link>,
 219     <link linkend="salvager8">salvager(8)</link>,
 220     <link linkend="volserver8">volserver(8)</link></para>
 221
 222   </refsect1>
 223   <refsect1>
 224     <title>Copyright</title>
 225     <para>IBM Corporation 2000. &lt;http://www.ibm.com/&gt; All Rights Reserved.</para>
 226
 227     <para>This documentation is covered by the IBM Public License Version 1.0.  It was
 228     converted from HTML to POD by software written by Chas Williams and Russ
 229     Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.</para>
 230
 231   </refsect1>
 232 </refentry>