doc/html/AdminReference/auarf093.htm

   1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 4//EN">
   2 <HTML><HEAD>
   3 <TITLE>Administration Reference</TITLE>
   4 <!-- Begin Header Records  ========================================== -->
   5 <!-- /tmp/idwt3672/auarf000.scr converted by idb2h R4.2 (359) ID      -->
   6 <!-- Workbench Version (AIX) on 3 Oct 2000 at 16:18:30                -->
   7 <META HTTP-EQUIV="updated" CONTENT="Tue, 03 Oct 2000 16:18:29">
   8 <META HTTP-EQUIV="review" CONTENT="Wed, 03 Oct 2001 16:18:29">
   9 <META HTTP-EQUIV="expires" CONTENT="Thu, 03 Oct 2002 16:18:29">
  10 </HEAD><BODY>
  11 <!-- (C) IBM Corporation 2000. All Rights Reserved    -->
  12 <BODY bgcolor="ffffff">
  13 <!-- End Header Records  ============================================ -->
  14 <A NAME="Top_Of_Page"></A>
  15 <H1>Administration Reference</H1>
  16 <HR><P ALIGN="center"> <A HREF="../index.htm"><IMG SRC="../books.gif" BORDER="0" ALT="[Return to Library]"></A> <A HREF="auarf002.htm#ToC"><IMG SRC="../toc.gif" BORDER="0" ALT="[Contents]"></A> <A HREF="auarf092.htm"><IMG SRC="../prev.gif" BORDER="0" ALT="[Previous Topic]"></A> <A HREF="#Bot_Of_Page"><IMG SRC="../bot.gif" BORDER="0" ALT="[Bottom of Topic]"></A> <A HREF="auarf094.htm"><IMG SRC="../next.gif" BORDER="0" ALT="[Next Topic]"></A> <A HREF="auarf284.htm#HDRINDEX"><IMG SRC="../index.gif" BORDER="0" ALT="[Index]"></A> <P>
  17 <P>
  18 <H2><A NAME="HDRBOS_INTRO" HREF="auarf002.htm#ToC_107">bos</A></H2>
  19 <A NAME="IDX4435"></A>
  20 <A NAME="IDX4436"></A>
  21 <A NAME="IDX4437"></A>
  22 <A NAME="IDX4438"></A>
  23 <A NAME="IDX4439"></A>
  24 <A NAME="IDX4440"></A>
  25 <A NAME="IDX4441"></A>
  26 <P><STRONG>Purpose</STRONG>
  27 <P>Introduction to the <B>bos</B> command suite
  28 <P><STRONG>Description</STRONG>
  29 <P>The commands in the <B>bos</B> command suite are the administrative
  30 interface to the Basic OverSeer (BOS) Server, which runs on every file server
  31 machine to monitor the other server processes on it. If a process
  32 fails, the BOS Server can restart it automatically, taking into account
  33 interdependencies between it and other processes. The BOS Server frees
  34 system administrators from constantly monitoring the status of server machines
  35 and processes.
  36 <P>There are several categories of commands in the <B>bos</B> command
  37 suite:
  38 <UL>
  39 <P><LI>Commands to administer server process binary files: <B>bos
  40 getdate</B>, <B>bos install</B>, <B>bos prune</B>, and <B>bos
  41 uninstall</B>
  42 <P><LI>Commands to maintain system configuration files: <B>bos
  43 addhost</B>, <B>bos addkey</B>, <B>bos adduser</B>, <B>bos
  44 listhosts</B>, <B>bos listkeys</B>, <B>bos listusers</B>, <B>bos
  45 removehost</B>, <B>bos removekey</B>, <B>bos removeuser</B>, and
  46 <B>bos setcellname</B>
  47 <P><LI>Commands to start and stop processes: <B>bos create</B>,
  48 <B>bos delete</B>, <B>bos restart</B>, <B>bos shutdown</B>,
  49 <B>bos start</B>, <B>bos startup</B>, and <B>bos stop</B>
  50 <P><LI>Commands to set and verify server process and server machine status:
  51 <B>bos getlog</B>, <B>bos getrestart</B>, <B>bos setauth</B>,
  52 <B>bos setrestart</B>, and <B>bos status</B>
  53 <P><LI>A command to restore file system consistency: <B>bos salvage</B>
  54 <P><LI>Commands to obtain help: <B>bos apropos</B> and <B>bos
  55 help</B>
  56 </UL>
  57 <P>The BOS Server and the <B>bos</B> commands use and maintain the
  58 following configuration and log files:
  59 <UL>
  60 <P><LI>The <B>/usr/afs/etc/CellServDB</B> file lists the local cell's
  61 database server machines. These machines run the Authentication,
  62 Backup, Protection and Volume Location (VL) Server processes, which maintain
  63 databases of administrative information. The database server processes
  64 consult the file to learn about their peers, whereas the other server
  65 processes consult it to learn where to access database information as
  66 needed. To administer the <B>CellServDB</B> file, use the following
  67 commands: <B>bos addhost</B>, <B>bos listhosts</B>, <B>bos
  68 removehost</B>, and <B>bos setcellname</B>.
  69 <P><LI>The <B>/usr/afs/etc/KeyFile</B> file lists the server encryption keys
  70 that the server processes use to decrypt tickets presented by client processes
  71 and one another. To administer the <B>KeyFile</B> file, use the
  72 following commands: <B>bos addkey</B>, <B>bos listkeys</B>, and
  73 <B>bos removekey</B>.
  74 <P><LI>The <B>/usr/afs/etc/ThisCell</B> file defines the cell to which the
  75 server machine belongs for the purposes of server-to-server
  76 communication. Administer it with the <B>bos setcellname</B>
  77 command. There is also a <B>/usr/vice/etc/ThisCell</B> file that
  78 defines the machine's cell membership with respect to the AFS command
  79 suites and Cache Manager access to AFS data.
  80 <P><LI>The <B>/usr/afs/etc/UserList</B> file lists the user name of each
  81 administrator authorized to issue privileged <B>bos</B> and <B>vos</B>
  82 commands. To administer the <B>UserList</B> file, use the following
  83 commands: <B>bos adduser</B>, <B>bos listusers</B>, and <B>bos
  84 removeuser</B>.
  85 <P><LI>The <B>/usr/afs/local/BosConfig</B> file defines which AFS server
  86 processes run on the server machine, and whether the BOS Server restarts them
  87 automatically if they fail. It also defines when all processes restart
  88 automatically (by default once per week), and when the BOS Server restarts
  89 processes that have new binary files (by default once per day). To
  90 administer the <B>BosConfig</B> file, use the following commands:
  91 <B>bos create</B>, <B>bos delete</B>, <B>bos getrestart</B>,
  92 <B>bos setrestart</B>, <B>bos start</B>, and <B>bos
  93 stop</B>.
  94 <P><LI>The <B>/usr/afs/log/BosLog</B> file records important operations the
  95 BOS Server performs and error conditions it encounters.
  96 </UL>
  97 <P>For more details, see the reference page for each file.
  98 <P><STRONG>Options</STRONG>
  99 <P>The following arguments and flags are available on many commands in the
 100 <B>bos</B> suite. The reference page for each command also lists
 101 them, but they are described here in greater detail.
 102 <A NAME="IDX4442"></A>
 103 <A NAME="IDX4443"></A>
 104 <A NAME="IDX4444"></A>
 105 <DL>
 106 <P><DT><B>-cell &lt;<VAR>cell name</VAR>>
 107 </B><DD>Names the cell in which to run the command. It is acceptable to
 108 abbreviate the cell name to the shortest form that distinguishes it from the
 109 other entries in the <B>/usr/vice/etc/CellServDB</B> file on the local
 110 machine. If the <B>-cell</B> argument is omitted, the command
 111 interpreter determines the name of the local cell by reading the following in
 112 order:
 113 <OL TYPE=1>
 114 <P><LI>The value of the AFSCELL environment variable
 115 <P><LI>The local <B>/usr/vice/etc/ThisCell</B> file
 116 </OL>
 117 <P>
 118 <P>Do not combine the <B>-cell</B> and <B>-localauth</B>
 119 options. A command on which the <B>-localauth</B> flag is included
 120 always runs in the local cell (as defined in the server machine's local
 121 <B>/usr/afs/etc/ThisCell</B> file), whereas a command on which the
 122 <B>-cell</B> argument is included runs in the specified foreign
 123 cell.
 124 <A NAME="IDX4445"></A>
 125 <P><DT><B>-help
 126 </B><DD>Prints a command's online help message on the standard output
 127 stream. Do not combine this flag with any of the command's other
 128 options; when it is provided, the command interpreter ignores all other
 129 options, and only prints the help message.
 130 <P><DT><B>
 131 <A NAME="IDX4446"></A>
 132 <B>-localauth</B>
 133 </B><DD>Constructs a server ticket using the server encryption key with the
 134 highest key version number in the local <B>/usr/afs/etc/KeyFile</B>
 135 file. The <B>bos</B> command interpreter presents the ticket, which
 136 never expires, to the BOS Server during mutual authentication.
 137 <P>Use this flag only when issuing a command on a server machine; client
 138 machines do not usually have a <B>/usr/afs/etc/KeyFile</B> file.
 139 The issuer of a command that includes this flag must be logged on to the
 140 server machine as the local superuser <B>root</B>. The flag is
 141 useful for commands invoked by an unattended application program, such as a
 142 process controlled by the UNIX <B>cron</B> utility or by a cron entry in
 143 the machine's <B>/usr/afs/local/BosConfig</B> file. It is also
 144 useful if an administrator is unable to authenticate to AFS but is logged in
 145 as the local superuser <B>root</B>.
 146 <P>Do not combine the <B>-cell</B> and <B>-localauth</B>
 147 options. A command on which the <B>-localauth</B> flag is included
 148 always runs in the local cell (as defined in the server machine's local
 149 <B>/usr/afs/etc/ThisCell</B> file), whereas a command on which the
 150 <B>-cell</B> argument is included runs in the specified foreign
 151 cell. Also, do not combine the <B>-localauth</B> and
 152 <B>-noauth</B> flags.
 153 <P><DT><B>
 154 <A NAME="IDX4447"></A>
 155 <B>-noauth</B>
 156 </B><DD>Establishes an unauthenticated connection to the BOS Server, in which the
 157 BOS Server treats the issuer as the unprivileged user
 158 <B>anonymous</B>. It is useful only when authorization checking is
 159 disabled on the server machine (during the installation of a file server
 160 machine or when the <B>bos setauth</B> command has been used during other
 161 unusual circumstances). In normal circumstances, the BOS Server allows
 162 only privileged users to issue commands that change the status of a server or
 163 configuration file, and refuses to perform such an action even if the
 164 <B>-noauth</B> flag is provided. Do not combine the
 165 <B>-noauth</B> and <B>-localauth</B> flags.
 166 <P><DT><B><B>-server</B> &lt;<VAR>machine name</VAR>>
 167 <A NAME="IDX4448"></A>
 168 </B><DD>Indicates the AFS server machine on which to run the command.
 169 Identify the machine by its IP address in dotted decimal format, its
 170 fully-qualified host name (for example, <B>fs1.abc.com</B>),
 171 or by an abbreviated form of its host name that distinguishes it from other
 172 machines. Successful use of an abbreviated form depends on the
 173 availability of a name service (such as the Domain Name Service or a local
 174 host table) at the time the command is issued.
 175 <P>For the commands that alter the administrative files shared by all server
 176 machines in the cell (the <B>bos addhost</B>, <B>bos addkey</B>,
 177 <B>bos adduser</B>, <B>bos removehost</B>, <B>bos removekey</B>,
 178 and <B>bos removeuser</B> commands), the appropriate machine depends on
 179 whether the cell uses the United States or international version of AFS:
 180 <UL>
 181 <P><LI>If the cell runs the United States edition of AFS and (as recommended)
 182 uses the Update Server to distribute the contents of the
 183 <B>/usr/afs/etc</B> directory, provide the name of the system control
 184 machine. After issuing the command, allow up to five minutes for the
 185 Update Server to distribute the changed file to the other AFS server machines
 186 in the cell. If the specified machine is not the system control machine
 187 but is running an <B>upclientetc</B> process that refers to the system
 188 control machine, then the change will be overwritten when the process next
 189 brings over the relevant file from the system control machine.
 190 <P><LI>If the cell runs the international edition of AFS, do not use the Update
 191 Server to distribute the contents of the <B>/usr/afs/etc</B>
 192 directory. Instead, repeatedly issue the command, naming each of the
 193 cell's server machines in turn. To avoid possible inconsistency
 194 problems, finish issuing the commands within a fairly short time.
 195 </UL>
 196 </DL>
 197 <P><STRONG>Privilege Required</STRONG>
 198 <A NAME="IDX4449"></A>
 199 <A NAME="IDX4450"></A>
 200 <P>To issue any <B>bos</B> command that changes a configuration file or
 201 alters process status, the issuer must be listed in the
 202 <B>/usr/afs/etc/UserList</B> file on the server machine named by the
 203 <B>-server</B> argument. Alternatively, if the
 204 <B>-localauth</B> flag is included the issuer must be logged on as the
 205 local superuser <B>root</B>.
 206 <P>To issue a <B>bos</B> command that only displays information (other
 207 than the <B>bos listkeys</B> command), no privilege is required.
 208 <P><STRONG>Related Information</STRONG>
 209 <P><A HREF="auarf016.htm#HDRBOSCONFIG">BosConfig</A>
 210 <P><A HREF="auarf019.htm#HDRCLI_CSDB">CellServDB (client version)</A>
 211 <P><A HREF="auarf020.htm#HDRSV_CSDB">CellServDB (server version)</A>
 212 <P><A HREF="auarf023.htm#HDRKEYFILE">KeyFile</A>
 213 <P><A HREF="auarf032.htm#HDRCLI_THISCELL">ThisCell (client version)</A>
 214 <P><A HREF="auarf033.htm#HDRSV_THISCELL">ThisCell (server version)</A>
 215 <P><A HREF="auarf035.htm#HDRUSERLIST">UserList</A>
 216 <P><A HREF="auarf094.htm#HDRBOS_ADDHOST">bos addhost</A>
 217 <P><A HREF="auarf095.htm#HDRBOS_ADDKEY">bos addkey</A>
 218 <P><A HREF="auarf096.htm#HDRBOS_ADDUSER">bos adduser</A>
 219 <P><A HREF="auarf097.htm#HDRBOS_APROPOS">bos apropos</A>
 220 <P><A HREF="auarf098.htm#HDRBOS_CREATE">bos create</A>
 221 <P><A HREF="auarf099.htm#HDRBOS_DELETE">bos delete</A>
 222 <P><A HREF="auarf100.htm#HDRBOS_EXEC">bos exec</A>
 223 <P><A HREF="auarf101.htm#HDRBOS_GETDATE">bos getdate</A>
 224 <P><A HREF="auarf102.htm#HDRBOS_GETLOG">bos getlog</A>
 225 <P><A HREF="auarf103.htm#HDRBOS_GETRESTART">bos getrestart</A>
 226 <P><A HREF="auarf104.htm#HDRBOS_HELP">bos help</A>
 227 <P><A HREF="auarf105.htm#HDRBOS_INSTALL">bos install</A>
 228 <P><A HREF="auarf106.htm#HDRBOS_LISTHOSTS">bos listhosts</A>
 229 <P><A HREF="auarf107.htm#HDRBOS_LISTKEYS">bos listkeys</A>
 230 <P><A HREF="auarf108.htm#HDRBOS_LISTUSERS">bos listusers</A>
 231 <P><A HREF="auarf109.htm#HDRBOS_PRUNE">bos prune</A>
 232 <P><A HREF="auarf110.htm#HDRBOS_REMOVEHOST">bos removehost</A>
 233 <P><A HREF="auarf111.htm#HDRBOS_REMOVEKEY">bos removekey</A>
 234 <P><A HREF="auarf112.htm#HDRBOS_REMOVEUSER">bos removeuser</A>
 235 <P><A HREF="auarf113.htm#HDRBOS_RESTART">bos restart</A>
 236 <P><A HREF="auarf114.htm#HDRBOS_SALVAGE">bos salvage</A>
 237 <P><A HREF="auarf115.htm#HDRBOS_SETAUTH">bos setauth</A>
 238 <P><A HREF="auarf116.htm#HDRBOS_SETCELLNAME">bos setcellname</A>
 239 <P><A HREF="auarf117.htm#HDRBOS_SETRESTART">bos setrestart</A>
 240 <P><A HREF="auarf118.htm#HDRBOS_SHUTDOWN">bos shutdown</A>
 241 <P><A HREF="auarf119.htm#HDRBOS_START">bos start</A>
 242 <P><A HREF="auarf120.htm#HDRBOS_STARTUP">bos startup</A>
 243 <P><A HREF="auarf121.htm#HDRBOS_STATUS">bos status</A>
 244 <P><A HREF="auarf122.htm#HDRBOS_STOP">bos stop</A>
 245 <P><A HREF="auarf123.htm#HDRBOS_UNINSTALL">bos uninstall</A>
 246 <P>
 247 <HR><P ALIGN="center"> <A HREF="../index.htm"><IMG SRC="../books.gif" BORDER="0" ALT="[Return to Library]"></A> <A HREF="auarf002.htm#ToC"><IMG SRC="../toc.gif" BORDER="0" ALT="[Contents]"></A> <A HREF="auarf092.htm"><IMG SRC="../prev.gif" BORDER="0" ALT="[Previous Topic]"></A> <A HREF="#Top_Of_Page"><IMG SRC="../top.gif" BORDER="0" ALT="[Top of Topic]"></A> <A HREF="auarf094.htm"><IMG SRC="../next.gif" BORDER="0" ALT="[Next Topic]"></A> <A HREF="auarf284.htm#HDRINDEX"><IMG SRC="../index.gif" BORDER="0" ALT="[Index]"></A> <P>
 248 <!-- Begin Footer Records  ========================================== -->
 249 <P><HR><B>
 250 <br>&#169; <A HREF="http://www.ibm.com/">IBM Corporation 2000.</A>  All Rights Reserved
 251 </B>
 252 <!-- End Footer Records  ============================================ -->
 253 <A NAME="Bot_Of_Page"></A>
 254 </BODY></HTML>