doc/xml/AdminReference/sect8/bos.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <refentry id="bos8">
   3   <refmeta>
   4     <refentrytitle>bos</refentrytitle>
   5     <manvolnum>8</manvolnum>
   6   </refmeta>
   7   <refnamediv>
   8     <refname>bos</refname>
   9     <refpurpose>Introduction to the bos command suite</refpurpose>
  10   </refnamediv>
  11   <refsect1>
  12     <title>Description</title>
  13     <para>The commands in the <emphasis role="bold">bos</emphasis> command suite are the administrative interface
  14     to the Basic OverSeer (BOS) Server, which runs on every file server
  15     machine to monitor the other server processes on it. If a process fails,
  16     the BOS Server can restart it automatically, taking into account
  17     interdependencies between it and other processes. The BOS Server frees
  18     system administrators from constantly monitoring the status of server
  19     machines and processes.</para>
  20
  21     <para>There are several categories of commands in the <emphasis role="bold">bos</emphasis> command suite:</para>
  22
  23     <itemizedlist>
  24       <listitem>
  25         <para>Commands to administer server process binary files: <emphasis role="bold">bos getdate</emphasis>, <emphasis role="bold">bos
  26         install</emphasis>, <emphasis role="bold">bos prune</emphasis>, and <emphasis role="bold">bos uninstall</emphasis>.</para>
  27
  28       </listitem>
  29       <listitem>
  30         <para>Commands to maintain system configuration files: <emphasis role="bold">bos addhost</emphasis>, <emphasis role="bold">bos
  31         addkey</emphasis>, <emphasis role="bold">bos adduser</emphasis>, <emphasis role="bold">bos listhosts</emphasis>, <emphasis role="bold">bos listkeys</emphasis>, <emphasis role="bold">bos
  32         listusers</emphasis>, <emphasis role="bold">bos removehost</emphasis>, <emphasis role="bold">bos removekey</emphasis>, <emphasis role="bold">bos removeuser</emphasis>, and
  33         <emphasis role="bold">bos setcellname</emphasis>.</para>
  34
  35       </listitem>
  36       <listitem>
  37         <para>Commands to start and stop processes: <emphasis role="bold">bos create</emphasis>, <emphasis role="bold">bos delete</emphasis>, <emphasis role="bold">bos
  38         restart</emphasis>, <emphasis role="bold">bos shutdown</emphasis>, <emphasis role="bold">bos start</emphasis>, <emphasis role="bold">bos startup</emphasis>, and <emphasis role="bold">bos stop</emphasis>.</para>
  39
  40       </listitem>
  41       <listitem>
  42         <para>Commands to set and verify server process and server machine status: <emphasis role="bold">bos
  43         getlog</emphasis>, <emphasis role="bold">bos getrestart</emphasis>, <emphasis role="bold">bos setauth</emphasis>, <emphasis role="bold">bos setrestart</emphasis>, and <emphasis role="bold">bos
  44         status</emphasis>.</para>
  45
  46       </listitem>
  47       <listitem>
  48         <para>A command to restore file system consistency: <emphasis role="bold">bos salvage</emphasis>.</para>
  49
  50       </listitem>
  51       <listitem>
  52         <para>Commands to obtain help: <emphasis role="bold">bos apropos</emphasis> and <emphasis role="bold">bos help</emphasis>.</para>
  53
  54       </listitem>
  55     </itemizedlist>
  56     <para>The BOS Server and the <emphasis role="bold">bos</emphasis> commands use and maintain the following
  57     configuration and log files:</para>
  58
  59     <itemizedlist>
  60       <listitem>
  61         <para>The <replaceable>/usr/afs/etc/CellServDB</replaceable> file lists the local cell's database server
  62         machines. These machines run the Authentication, Backup, Protection and
  63         Volume Location (VL) Server processes, which maintain databases of
  64         administrative information. The database server processes consult the file
  65         to learn about their peers, whereas the other server processes consult it
  66         to learn where to access database information as needed. To administer the
  67         <replaceable>CellServDB</replaceable> file, use the following commands: <emphasis role="bold">bos addhost</emphasis>, <emphasis role="bold">bos
  68         listhosts</emphasis>, <emphasis role="bold">bos removehost</emphasis>, and <emphasis role="bold">bos setcellname</emphasis>.</para>
  69
  70       </listitem>
  71       <listitem>
  72         <para>The <replaceable>/usr/afs/etc/KeyFile</replaceable> file lists the server encryption keys that the
  73         server processes use to decrypt tickets presented by client processes and
  74         one another. To administer the <replaceable>KeyFile</replaceable> file, use the following
  75         commands: <emphasis role="bold">bos addkey</emphasis>, <emphasis role="bold">bos listkeys</emphasis>, and <emphasis role="bold">bos removekey</emphasis>.</para>
  76
  77       </listitem>
  78       <listitem>
  79         <para>The <replaceable>/usr/afs/etc/ThisCell</replaceable> file defines the cell to which the server
  80         machine belongs for the purposes of server-to-server communication.
  81         Administer it with the <emphasis role="bold">bos setcellname</emphasis> command. There is also a
  82         <replaceable>/usr/vice/etc/ThisCell</replaceable> file that defines the machine's cell membership
  83         with respect to the AFS command suites and Cache Manager access to AFS
  84         data.</para>
  85
  86       </listitem>
  87       <listitem>
  88         <para>The <replaceable>/usr/afs/etc/UserList</replaceable> file lists the user name of each
  89         administrator authorized to issue privileged <emphasis role="bold">bos</emphasis> and <emphasis role="bold">vos</emphasis>
  90         commands. To administer the <replaceable>UserList</replaceable> file, use the following commands:
  91         <emphasis role="bold">bos adduser</emphasis>, <emphasis role="bold">bos listusers</emphasis>, and <emphasis role="bold">bos removeuser</emphasis>.</para>
  92
  93       </listitem>
  94       <listitem>
  95         <para>The <replaceable>/usr/afs/local/BosConfig</replaceable> file defines which AFS server processes
  96         run on the server machine, and whether the BOS Server restarts them
  97         automatically if they fail. It also defines when all processes restart
  98         automatically (by default once per week), and when the BOS Server restarts
  99         processes that have new binary files (by default once per day). To
 100         administer the <replaceable>BosConfig</replaceable> file, use the following commands: <emphasis role="bold">bos
 101         create</emphasis>, <emphasis role="bold">bos delete</emphasis>, <emphasis role="bold">bos getrestart</emphasis>, <emphasis role="bold">bos setrestart</emphasis>, <emphasis role="bold">bos
 102         start</emphasis>, and <emphasis role="bold">bos stop</emphasis>.</para>
 103
 104       </listitem>
 105       <listitem>
 106         <para>The <replaceable>/usr/afs/log/BosLog</replaceable> file records important operations the BOS
 107         Server performs and error conditions it encounters.</para>
 108
 109       </listitem>
 110     </itemizedlist>
 111     <para>For more details, see the reference page for each file.</para>
 112
 113   </refsect1>
 114   <refsect1>
 115     <title>Options</title>
 116     <para>The following arguments and flags are available on many commands in the
 117     <emphasis role="bold">bos</emphasis> suite. The reference page for each command also lists them, but
 118     they are described here in greater detail.</para>
 119
 120     <variablelist>
 121       <varlistentry>
 122         <term><emphasis role="bold">-cell</emphasis> &lt;<emphasis>cell name</emphasis>&gt;</term>
 123         <listitem>
 124           <para>Names the cell in which to run the command. It is acceptable to abbreviate
 125           the cell name to the shortest form that distinguishes it from the other
 126           entries in the <replaceable>/usr/vice/etc/CellServDB</replaceable> file on the local machine. If
 127           the <emphasis role="bold">-cell</emphasis> argument is omitted, the command interpreter determines the
 128           name of the local cell by reading the following in order:</para>
 129
 130           <itemizedlist>
 131             <listitem>
 132               <para>The value of the AFSCELL environment variable.</para>
 133
 134             </listitem>
 135             <listitem>
 136               <para>The local <replaceable>/usr/vice/etc/ThisCell</replaceable> file.</para>
 137
 138             </listitem>
 139           </itemizedlist>
 140           <para>Do not combine the <emphasis role="bold">-cell</emphasis> and <emphasis role="bold">-localauth</emphasis> options. A command on which
 141           the <emphasis role="bold">-localauth</emphasis> flag is included always runs in the local cell (as
 142           defined in the server machine's local <replaceable>/usr/afs/etc/ThisCell</replaceable> file),
 143           whereas a command on which the <emphasis role="bold">-cell</emphasis> argument is included runs in the
 144           specified foreign cell.</para>
 145
 146         </listitem>
 147       </varlistentry>
 148       <varlistentry>
 149         <term><emphasis role="bold">-help</emphasis></term>
 150         <listitem>
 151           <para>Prints a command's online help message on the standard output stream. Do
 152           not combine this flag with any of the command's other options; when it is
 153           provided, the command interpreter ignores all other options, and only
 154           prints the help message.</para>
 155
 156         </listitem>
 157       </varlistentry>
 158       <varlistentry>
 159         <term><emphasis role="bold">-localauth</emphasis></term>
 160         <listitem>
 161           <para>Constructs a server ticket using the server encryption key with the
 162           highest key version number in the local <replaceable>/usr/afs/etc/KeyFile</replaceable> file. The
 163           <emphasis role="bold">bos</emphasis> command interpreter presents the ticket, which never expires, to
 164           the BOS Server during mutual authentication.</para>
 165
 166           <para>Use this flag only when issuing a command on a server machine; client
 167           machines do not usually have a <replaceable>/usr/afs/etc/KeyFile</replaceable> file.  The issuer
 168           of a command that includes this flag must be logged on to the server
 169           machine as the local superuser <computeroutput>root</computeroutput>. The flag is useful for commands
 170           invoked by an unattended application program, such as a process controlled
 171           by the UNIX <emphasis role="bold">cron</emphasis> utility or by a cron entry in the machine's
 172           <replaceable>/usr/afs/local/BosConfig</replaceable> file. It is also useful if an administrator is
 173           unable to authenticate to AFS but is logged in as the local superuser
 174           <computeroutput>root</computeroutput>.</para>
 175
 176           <para>Do not combine the <emphasis role="bold">-cell</emphasis> and <emphasis role="bold">-localauth</emphasis> options. A command on which
 177           the <emphasis role="bold">-localauth</emphasis> flag is included always runs in the local cell (as
 178           defined in the server machine's local <replaceable>/usr/afs/etc/ThisCell</replaceable> file),
 179           whereas a command on which the <emphasis role="bold">-cell</emphasis> argument is included runs in the
 180           specified foreign cell. Also, do not combine the <emphasis role="bold">-localauth</emphasis> and
 181           <emphasis role="bold">-noauth</emphasis> flags.</para>
 182
 183         </listitem>
 184       </varlistentry>
 185       <varlistentry>
 186         <term><emphasis role="bold">-noauth</emphasis></term>
 187         <listitem>
 188           <para>Establishes an unauthenticated connection to the BOS Server, in which the
 189           BOS Server treats the issuer as the unprivileged user <computeroutput>anonymous</computeroutput>. It is
 190           useful only when authorization checking is disabled on the server machine
 191           (during the installation of a file server machine or when the <emphasis role="bold">bos
 192           setauth</emphasis> command has been used during other unusual circumstances). In
 193           normal circumstances, the BOS Server allows only privileged users to issue
 194           commands that change the status of a server or configuration file, and
 195           refuses to perform such an action even if the <emphasis role="bold">-noauth</emphasis> flag is
 196           provided. Do not combine the <emphasis role="bold">-noauth</emphasis> and <emphasis role="bold">-localauth</emphasis> flags.</para>
 197
 198         </listitem>
 199       </varlistentry>
 200       <varlistentry>
 201         <term><emphasis role="bold">-server</emphasis> &lt;<emphasis>machine name</emphasis>&gt;</term>
 202         <listitem>
 203           <para>Indicates the AFS server machine on which to run the command.  Identify
 204           the machine by its IP address in dotted decimal format, its
 205           fully-qualified host name (for example, <computeroutput>fs1.abc.com</computeroutput>), or by an
 206           abbreviated form of its host name that distinguishes it from other
 207           machines. Successful use of an abbreviated form depends on the
 208           availability of a name service (such as the Domain Name Service or a local
 209           host table) at the time the command is issued.</para>
 210
 211           <para>For the commands that alter the administrative files shared by all server
 212           machines in the cell (the <emphasis role="bold">bos addhost</emphasis>, <emphasis role="bold">bos addkey</emphasis>, <emphasis role="bold">bos adduser</emphasis>,
 213           <emphasis role="bold">bos removehost</emphasis>, <emphasis role="bold">bos removekey</emphasis>, and <emphasis role="bold">bos removeuser</emphasis> commands), the
 214           appropriate machine depends on whether the cell uses the United States or
 215           international version of AFS:</para>
 216
 217           <itemizedlist>
 218             <listitem>
 219               <para>If the cell (as recommended) uses the Update Server to distribute the
 220               contents of the <replaceable>/usr/afs/etc</replaceable> directory, provide the name of the system
 221               control machine. After issuing the command, allow up to five minutes for
 222               the Update Server to distribute the changed file to the other AFS server
 223               machines in the cell. If the specified machine is not the system control
 224               machine but is running an <emphasis role="bold">upclient</emphasis> process that refers to the system
 225               control machine, then the change will be overwritten when the process next
 226               brings over the relevant file from the system control machine.</para>
 227
 228             </listitem>
 229             <listitem>
 230               <para>Otherwise, repeatedly issue the command, naming each of the cell's server
 231               machines in turn. To avoid possible inconsistency problems, finish issuing
 232               the commands within a fairly short time.</para>
 233
 234             </listitem>
 235           </itemizedlist>
 236         </listitem>
 237       </varlistentry>
 238     </variablelist>
 239   </refsect1>
 240   <refsect1>
 241     <title>Privilege Required</title>
 242     <para>To issue any bos command that changes a configuration file or alters
 243     process status, the issuer must be listed in the <replaceable>/usr/afs/etc/UserList</replaceable>
 244     file on the server machine named by the <emphasis role="bold">-server</emphasis>
 245     argument. Alternatively, if the <emphasis role="bold">-localauth</emphasis> flag is included the issuer
 246     must be logged on as the local superuser <computeroutput>root</computeroutput>.</para>
 247
 248     <para>To issue a bos command that only displays information (other than the
 249     <emphasis role="bold">bos listkeys</emphasis> command), no privilege is required.</para>
 250
 251   </refsect1>
 252   <refsect1>
 253     <title>See Also</title>
 254     <para><link linkend="BosConfig5">BosConfig(5)</link>,
 255     <link linkend="CellServDB5">CellServDB(5)</link>,
 256     <link linkend="KeyFile5">KeyFile(5)</link>,
 257     <link linkend="ThisCell5">ThisCell(5)</link>,
 258     <link linkend="UserList5">UserList(5)</link>,
 259     <link linkend="bos_addhost8">bos_addhost(8)</link>,
 260     <link linkend="bos_addkey8">bos_addkey(8)</link>,
 261     <link linkend="bos_adduser8">bos_adduser(8)</link>,
 262     <link linkend="bos_apropos8">bos_apropos(8)</link>,
 263     <link linkend="bos_create8">bos_create(8)</link>,
 264     <link linkend="bos_delete8">bos_delete(8)</link>,
 265     <link linkend="bos_exec8">bos_exec(8)</link>,
 266     <link linkend="bos_getdate8">bos_getdate(8)</link>,
 267     <link linkend="bos_getlog8">bos_getlog(8)</link>,
 268     <link linkend="bos_getrestart8">bos_getrestart(8)</link>,
 269     <link linkend="bos_help8">bos_help(8)</link>,
 270     <link linkend="bos_install8">bos_install(8)</link>,
 271     <link linkend="bos_listhosts8">bos_listhosts(8)</link>,
 272     <link linkend="bos_listkeys8">bos_listkeys(8)</link>,
 273     <link linkend="bos_listusers8">bos_listusers(8)</link>,
 274     <link linkend="bos_prune8">bos_prune(8)</link>,
 275     <link linkend="bos_removehost8">bos_removehost(8)</link>,
 276     <link linkend="bos_removekey8">bos_removekey(8)</link>,
 277     <link linkend="bos_removeuser8">bos_removeuser(8)</link>,
 278     <link linkend="bos_restart8">bos_restart(8)</link>,
 279     <link linkend="bos_salvage8">bos_salvage(8)</link>,
 280     <link linkend="bos_setauth8">bos_setauth(8)</link>,
 281     <link linkend="bos_setcellname8">bos_setcellname(8)</link>,
 282     <link linkend="bos_setrestart8">bos_setrestart(8)</link>,
 283     <link linkend="bos_shutdown8">bos_shutdown(8)</link>,
 284     <link linkend="bos_start8">bos_start(8)</link>,
 285     <link linkend="bos_startup8">bos_startup(8)</link>,
 286     <link linkend="bos_status8">bos_status(8)</link>,
 287     <link linkend="bos_stop8">bos_stop(8)</link>,
 288     <link linkend="bos_uninstall8">bos_uninstall(8)</link></para>
 289
 290   </refsect1>
 291   <refsect1>
 292     <title>Copyright</title>
 293     <para>IBM Corporation 2000. &lt;http://www.ibm.com/&gt; All Rights Reserved.</para>
 294
 295     <para>This documentation is covered by the IBM Public License Version 1.0.  It was
 296     converted from HTML to POD by software written by Chas Williams and Russ
 297     Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.</para>
 298
 299   </refsect1>
 300 </refentry>