src/WINNT/doc/install/Documentation/en_US/html/SysAdminGd/auagd009.htm

   1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 3//EN">
   2 <HTML><HEAD>
   3 <TITLE>Administration Guide</TITLE>
   4 <!-- Begin Header Records  ========================================== -->
   5 <!-- /tmp/idwt3191/auagd000.scr converted by idb2h R4.2 (359) ID      -->
   6 <!-- Workbench Version (AIX) on 5 Nov 1999 at 14:06:34                -->
   7 <META HTTP-EQUIV="updated" CONTENT="Fri, 05 Nov 1999 14:06:34">
   8 <META HTTP-EQUIV="review" CONTENT="Sun, 05 Nov 2000 14:06:34">
   9 <META HTTP-EQUIV="expires" CONTENT="Mon, 05 Nov 2001 14:06:34">
  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 Guide</H1>
  16 <HR><P ALIGN="center"> <A HREF="../index.htm"><IMG SRC="../books.gif" BORDER="0" ALT="[Return to Library]"></A> <A HREF="auagd002.htm#ToC"><IMG SRC="../toc.gif" BORDER="0" ALT="[Contents]"></A> <A HREF="auagd008.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="auagd010.htm"><IMG SRC="../next.gif" BORDER="0" ALT="[Next Topic]"></A> <A HREF="auagd026.htm#HDRINDEX"><IMG SRC="../index.gif" BORDER="0" ALT="[Index]"></A> <P>
  17 <HR><H1><A NAME="HDRWQ176" HREF="auagd002.htm#ToC_164">Monitoring and Controlling Server Processes</A></H1>
  18 <A NAME="IDX6247"></A>
  19 <A NAME="IDX6248"></A>
  20 <P>One of your most important responsibilities as a system administrator is
  21 ensuring that the processes on file server machines are running
  22 correctly. The BOS Server, which runs on every file server machine,
  23 relieves you of much of the responsibility by constantly monitoring the other
  24 AFS server processes on its machine. It can automatically restart
  25 processes that have failed, ordering the restarts to take interdependencies
  26 into account.
  27 <P>Because different file server machines run different combinations of
  28 processes, you must define which processes the BOS Server on each file server
  29 machine is to monitor (to learn how, see <A HREF="#HDRWQ200">Controlling and Checking Process Status</A>).
  30 <P>It is sometimes necessary to take direct control of server process status
  31 before performing routine maintenance or correcting problems that the BOS
  32 Server cannot correct (such as problems with database replication or mutual
  33 authentication). At those times, you control process status through the
  34 BOS Server by issuing <B>bos</B> commands.
  35 <HR><H2><A NAME="HDRWQ177" HREF="auagd002.htm#ToC_165">Summary of Instructions</A></H2>
  36 <P>This chapter explains how to perform the following tasks by
  37 using the indicated commands&#58;
  38 <BR>
  39 <TABLE WIDTH="100%">
  40 <TR>
  41 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="58%">Examine process status
  42 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="42%"><B>bos status</B>
  43 </TD></TR><TR>
  44 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="58%">Examine information from the <B>BosConfig file</B> file
  45 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="42%"><B>bos status</B> with <B>-long</B> flag
  46 </TD></TR><TR>
  47 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="58%">Create a process instance
  48 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="42%"><B>bos create</B>
  49 </TD></TR><TR>
  50 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="58%">Stop a process
  51 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="42%"><B>bos stop</B>
  52 </TD></TR><TR>
  53 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="58%">Start a stopped process
  54 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="42%"><B>bos start</B>
  55 </TD></TR><TR>
  56 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="58%">Stop a process temporarily
  57 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="42%"><B>bos shutdown</B>
  58 </TD></TR><TR>
  59 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="58%">Start a temporarily stopped process
  60 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="42%"><B>bos startup</B>
  61 </TD></TR><TR>
  62 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="58%">Stop and immediately restart a process
  63 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="42%"><B>bos restart</B>
  64 </TD></TR><TR>
  65 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="58%">Stop and immediately restart all processes
  66 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="42%"><B>bos restart</B> with <B>-bosserver</B> flag
  67 </TD></TR><TR>
  68 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="58%">Examine BOS Server&#39;s restart times
  69 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="42%"><B>bos getrestart</B>
  70 </TD></TR><TR>
  71 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="58%">Set BOS Server&#39;s restart times
  72 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="42%"><B>bos setrestart</B>
  73 </TD></TR><TR>
  74 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="58%">Examine a log file
  75 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="42%"><B>bos getlog</B>
  76 </TD></TR><TR>
  77 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="58%">Execute a command remotely
  78 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="42%"><B>bos exec</B>
  79 </TD></TR></TABLE>
  80 <HR><H2><A NAME="HDRWQ191" HREF="auagd002.htm#ToC_166">Brief Descriptions of the AFS Server Processes</A></H2>
  81 <P>This section briefly describes the different server
  82 processes that can run on an AFS server machine. In cells with multiple
  83 server machines, not all processes necessarily run on all machines.
  84 <P>An AFS server process is referred to in one of three ways, depending on the
  85 context&#58;
  86 <A NAME="IDX6249"></A>
  87 <UL>
  88 <P><LI>The output from the <B>bos status</B> command refers to a process by
  89 the name assigned when the <B>bos create</B> command creates its entry in
  90 the <B>/usr/afs/local/BosConfig</B> file. The name can differ from
  91 machine to machine, but it is easiest to maintain the cell if you assign the
  92 same name on all machines. The <I>AFS Quick Beginnings</I> and the
  93 reference page for the <B>bos create</B> command list the conventional
  94 names. Examples are <B>bosserver</B>, <B>kaserver</B>, and
  95 <B>vlserver</B>.
  96 <P><LI>The process listing produced by the standard <B>ps</B> command
  97 generally matches the process&#39;s binary file. Examples of process
  98 binary files are <B>/usr/afs/bin/bosserver</B>,
  99 <B>/usr/afs/bin/kaserver</B>, and <B>/usr/afs/bin/vlserver</B>.
 100 <P><LI>In most contexts, including most references in the documentation, a
 101 process is referred to as (for example) the <B>Basic OverSeer (BOS)
 102 Server</B>, the <B>Authentication Server</B>, or the <B>Volume
 103 Location Server</B>.
 104 </UL>
 105 <P>The following sections specify each name for the process as well as some of
 106 the administrative tasks in which you use the process. For a more
 107 general description of the servers, see <A HREF="auagd006.htm#HDRWQ17">AFS Server Processes and the Cache Manager</A>.
 108 <P><H3><A NAME="HDRWQ192" HREF="auagd002.htm#ToC_167">The bosserver Process&#58; the Basic OverSeer Server</A></H3>
 109 <A NAME="IDX6250"></A>
 110 <A NAME="IDX6251"></A>
 111 <P>The <B>bosserver</B> process, which runs on every AFS server machine,
 112 is the Basic OverSeer (BOS) Server responsible for monitoring the other AFS
 113 server processes running on its machine. If a process fails, the BOS
 114 Server can restart it automatically, without human intervention. It
 115 takes interdependencies into account when restarting a process that has
 116 multiple component processes (such as the <B>fs</B> process described in <A HREF="#HDRWQ194">The fs Collection of Processes&#58; the File Server, Volume Server and Salvager</A>).
 117 <A NAME="IDX6252"></A>
 118 <P>Because the BOS Server does not monitor or restart itself, it does not
 119 appear in the output from the <B>bos status</B> command. It appears
 120 in the <B>ps</B> command&#39;s output as
 121 <TT>/usr/afs/bin/bosserver</TT>.
 122 <A NAME="IDX6253"></A>
 123 <A NAME="IDX6254"></A>
 124 <P>As a system administrator, you contact the BOS Server when you issue
 125 <B>bos</B> commands to perform the following kinds of tasks.
 126 <A NAME="IDX6255"></A>
 127 <UL>
 128 <P><LI>Defining the processes for the BOS Server to monitor by creating entries
 129 in the <B>/usr/afs/local/BosConfig</B> file as described in <A HREF="#HDRWQ200">Controlling and Checking Process Status</A>
 130 <P><LI>Stopping and starting processes on the file server machines according to
 131 subsequent instructions in this chapter
 132 <P><LI>Defining your cell&#39;s database server machines in the
 133 <B>/usr/afs/etc/CellServDB</B> file as described in <A HREF="auagd008.htm#HDRWQ152">Maintaining the Server CellServDB File</A>
 134 <P><LI>Defining AFS server encryption keys in the <B>/usr/afs/etc/KeyFile</B>
 135 file as described in <A HREF="auagd014.htm#HDRWQ477">Managing Server Encryption Keys</A>.
 136 <P><LI>Granting system administrator privileges with respect to BOS Server,
 137 Volume Server, and Backup Server operations, by adding a user to the
 138 <B>/usr/afs/etc/UserList</B> file as described in <A HREF="auagd021.htm#HDRWQ814">Administering the UserList File</A>
 139 <P><LI>Setting authorization checking requirements on a server machine as
 140 described in <A HREF="auagd008.htm#HDRWQ157">Managing Authentication and Authorization Requirements</A>
 141 </UL>
 142 <P><H3><A NAME="HDRWQ193" HREF="auagd002.htm#ToC_168">The buserver Process&#58; the Backup Server</A></H3>
 143 <A NAME="IDX6256"></A>
 144 <A NAME="IDX6257"></A>
 145 <P>The <B>buserver</B> process, which runs on database server machines, is
 146 the Backup Server. It maintains information about Backup System
 147 configuration and operations in the Backup Database.
 148 <P>The process appears as <TT>buserver</TT> in the <B>bos status</B>
 149 command&#39;s output, if the conventional name is assigned. It appears
 150 in the <B>ps</B> command&#39;s output as
 151 <TT>/usr/afs/bin/buserver</TT>.
 152 <A NAME="IDX6258"></A>
 153 <A NAME="IDX6259"></A>
 154 <P>As a system administrator, you contact the Backup Server when you issue any
 155 <B>backup</B> command that manipulates information in the Backup Database,
 156 including those that change Backup System configuration information, that dump
 157 data from volumes to permanent storage, or that restore data to AFS.
 158 See <A HREF="auagd011.htm#HDRWQ333">Configuring the AFS Backup System</A> and <A HREF="auagd012.htm#HDRWQ382">Backing Up and Restoring AFS Data</A>.
 159 <P><H3><A NAME="HDRWQ194" HREF="auagd002.htm#ToC_169">The fs Collection of Processes&#58; the File Server, Volume Server and Salvager</A></H3>
 160 <A NAME="IDX6260"></A>
 161 <A NAME="IDX6261"></A>
 162 <P>The <B>fs</B> process, which runs on every file server machine,
 163 combines three component processes&#58; File Server, Volume Server and
 164 Salvager. The three components perform independent functions, but are
 165 controlled as a single process for the following reasons.
 166 <UL>
 167 <P><LI>They all operate on the same data, namely files and directories stored in
 168 AFS volumes. Combining them as a single process enables them to
 169 coordinate their actions, never attempting simultaneous operations on the same
 170 data that can possibly corrupt it.
 171 <P><LI>It enables the BOS Server to stop and restart the processes in the
 172 required order. When the File Server fails, the BOS Server stops the
 173 Volume Server and runs the Salvager to correct any corruption that resulted
 174 from the failure. (The Salvager runs only in this special circumstance
 175 or when you invoke it yourself by issuing the <B>bos salvage</B> command
 176 as instructed in <A HREF="auagd010.htm#HDRWQ317">Salvaging Volumes</A>.) If only the Volume Server fails, the BOS Server can
 177 restart it without affecting the File Server or Salvager.
 178 </UL>
 179 <P>The File Server component handles AFS data at the level of files and
 180 directories, manipulating file system elements as requested by application
 181 programs and the standard operating system commands. Its main duty is
 182 to deliver requested files to client machines and store them again on the
 183 server machine when the client is finished. It also maintains status
 184 and protection information about each file and directory. It runs
 185 continuously during normal operation.
 186 <A NAME="IDX6262"></A>
 187 <P>The Volume Server component handles AFS data at the level of complete
 188 volumes rather than files and directories. In response to
 189 <B>vos</B> commands, it creates, removes, moves, dumps and restores entire
 190 volumes, among other actions. It runs continuously during normal
 191 operation.
 192 <A NAME="IDX6263"></A>
 193 <P>The Salvager component runs only after the failure of one of the other two
 194 processes. It checks the file system for internal consistency and
 195 repairs any errors it finds.
 196 <A NAME="IDX6264"></A>
 197 <A NAME="IDX6265"></A>
 198 <P>The process appears as <TT>fs</TT> in the <B>bos status</B>
 199 command&#39;s output, if the conventional name is assigned. An
 200 auxiliary message reports the status of the File Server or Salvager
 201 component. See <A HREF="#HDRWQ204">Displaying Process Status and Information from the BosConfig File</A>.
 202 <P>The component processes of the <B>fs</B> process appear individually in
 203 the <B>ps</B> command&#39;s output, as follows. There is no entry
 204 for the <TT>fs</TT> process itself.
 205 <UL>
 206 <P><LI><TT>/usr/afs/bin/fileserver</TT>
 207 <P><LI><TT>/usr/afs/bin/volserver</TT>
 208 <P><LI><TT>/usr/afs/bin/salvager</TT>
 209 </UL>
 210 <P>The Cache Manager contacts the File Server component on your behalf
 211 whenever you access data or status information in an AFS file or directory or
 212 issue file manipulation commands such as the UNIX <B>cp</B> and
 213 <B>ls</B> commands. You can contact the File Server directly by
 214 issuing <B>fs</B> commands that perform the following functions
 215 <A NAME="IDX6266"></A>
 216 <A NAME="IDX6267"></A>
 217 <UL>
 218 <P><LI>Administering the ACL of any directory in the file system as described in <A HREF="auagd020.htm#HDRWQ772">Managing Access Control Lists</A>
 219 <P><LI>Installing new partitions for housing AFS volumes, in which case you must
 220 restart the <B>fs</B> process for it to recognize the new partition;
 221 for instructions, see <A HREF="auagd008.htm#HDRWQ164">Adding or Removing Disks and Partitions</A>
 222 <P><LI>Creating and deleting volume mount points in the AFS filespace as
 223 described in <A HREF="auagd010.htm#HDRWQ293">Mounting Volumes</A>
 224 <P><LI>Setting volume quota and displaying information about the space used and
 225 available in a volume or partition as described in <A HREF="auagd010.htm#HDRWQ319">Setting and Displaying Volume Quota and Current Size</A>
 226 </UL>
 227 <A NAME="IDX6268"></A>
 228 <A NAME="IDX6269"></A>
 229 <P>You contact the Volume Server component when you issue <B>vos</B>
 230 commands that manipulate volumes in any way--creating, removing,
 231 replicating, moving, renaming, converting to different formats, and
 232 salvaging. For instructions, see <A HREF="auagd010.htm#HDRWQ228">Managing Volumes</A>.
 233 <P>The Salvager normally runs automatically in case of a failure. You
 234 can also start it with the <B>bos salvage</B> command as described in <A HREF="auagd010.htm#HDRWQ317">Salvaging Volumes</A>.
 235 <A NAME="IDX6270"></A>
 236 <A NAME="IDX6271"></A>
 237 <P><H3><A NAME="HDRWQ195" HREF="auagd002.htm#ToC_170">The kaserver Process&#58; the Authentication Server</A></H3>
 238 <A NAME="IDX6272"></A>
 239 <A NAME="IDX6273"></A>
 240 <P>The <B>kaserver</B> process, which runs on database server machines, is
 241 the Authentication Server responsible for several aspects of AFS
 242 security. It verifies AFS user identity by requiring a password.
 243 It maintains all AFS server encryption keys and user passwords in the
 244 Authentication Database. The Authentication Server&#39;s Ticket
 245 Granting Service (TGS) module creates the shared secrets that AFS client and
 246 server processes use when establishing secure connections.
 247 <P>The process appears as <TT>kaserver</TT> in the <B>bos status</B>
 248 command&#39;s output, if the conventional name is assigned. The
 249 <B>ka</B> string stands for <I>Kerberos Authentication</I>, reflecting
 250 the fact that AFS&#39;s authentication protocols are based on Kerberos, which
 251 was originally developed at the Massachusetts Institute of Technology&#39;s
 252 Project Athena.
 253 <P>It appears in the <B>ps</B> command&#39;s output as
 254 <TT>/usr/afs/bin/kaserver</TT>.
 255 <A NAME="IDX6274"></A>
 256 <A NAME="IDX6275"></A>
 257 <P>As a system administrator, you contact the Authentication Server when you
 258 issue <B>kas</B> commands to perform the following kinds of tasks.
 259 <UL>
 260 <P><LI>Setting a user&#39;s password. Users normally change their own
 261 passwords, so you probably perform this task only creating a new user account
 262 as described in <A HREF="auagd018.htm#HDRWQ692">Creating AFS User Accounts</A> and <A HREF="auagd018.htm#HDRWQ706">Changing AFS Passwords</A>.
 263 <P><LI>Setting the AFS server encryption key in the Authentication Database,
 264 which the TGS uses to seal server tickets; see <A HREF="auagd014.htm#HDRWQ477">Managing Server Encryption Keys</A>.
 265 <P><LI>Granting or revoking system administrator privileges with respect to the
 266 Authentication Server as described in <A HREF="auagd021.htm#HDRWQ811">Granting Privilege for kas Commands&#58;  the ADMIN Flag</A>.
 267 </UL>
 268 <P><H3><A NAME="HDRWQ196" HREF="auagd002.htm#ToC_171">The ptserver Process&#58; the Protection Server</A></H3>
 269 <A NAME="IDX6276"></A>
 270 <A NAME="IDX6277"></A>
 271 <P>The <B>ptserver</B> process, which runs on database server machines, is
 272 the Protection Server. Its main responsibility is maintaining the
 273 Protection Database which contains user, machine, and group entries.
 274 The Protection Server allocates AFS IDs and maintains the mapping between them
 275 and names. The File Server consults the Protection Server when
 276 verifying that a user is authorized to perform a requested action.
 277 <P>The process appears as <TT>ptserver</TT> in the <B>bos status</B>
 278 command&#39;s output, if the conventional name is assigned. It appears
 279 in the <B>ps</B> command&#39;s output as
 280 <TT>/usr/afs/bin/ptserver</TT>.
 281 <A NAME="IDX6278"></A>
 282 <A NAME="IDX6279"></A>
 283 <P>As a system administrator, you contact the Protection Server when you issue
 284 <B>pts</B> commands to perform the following kinds of tasks.
 285 <UL>
 286 <P><LI>Creating a new user, machine, or group entry in the Protection Database as
 287 described in <A HREF="auagd019.htm#HDRWQ721">Administering the Protection Database</A>
 288 <P><LI>Adding or removing group members or otherwise manipulating Protection
 289 Database entries as described in <A HREF="auagd019.htm#HDRWQ721">Administering the Protection Database</A>
 290 <P><LI>Granting or revoking system administrator privilege by changing the
 291 membership of the <B>system&#58;administrators</B> group as described in
 292 <A HREF="auagd021.htm#HDRWQ808">Administering the system&#58;administrators Group</A>
 293 </UL>
 294 <P><H3><A NAME="HDRWQ197" HREF="auagd002.htm#ToC_172">The runntp Process</A></H3>
 295 <A NAME="IDX6280"></A>
 296 <A NAME="IDX6281"></A>
 297 <A NAME="IDX6282"></A>
 298 <P>The <B>runntp</B> process, which runs on every server machine, is a
 299 controller program for the Network Time Protocol Daemon (NTPD), which
 300 synchronizes the hardware clocks on server machines. You need to run
 301 the <B>runntp</B> process if you are not already running NTP or another
 302 time synchronization protocol on your server machines.
 303 <P>The clocks on database server machines need to be synchronized because
 304 AFS&#39;s distributed database technology (Ubik) works properly only when the
 305 clocks agree within a narrow range of variation (see <A HREF="auagd008.htm#HDRWQ137">Configuring the Cell for Proper Ubik Operation</A>). The clocks on file server machines need to be
 306 correct not only because the File Server sets modification time stamps on
 307 files, but because in the conventional configuration they serve as the time
 308 source for AFS client machines.
 309 <P>The process appears as <TT>runntp</TT> in the <B>bos status</B>
 310 command&#39;s output, if the conventional name is assigned. It appears
 311 in the output from the <B>ps</B> command as
 312 <TT>/usr/afs/bin/runntp</TT>. The <B>ps</B> command&#39;s output
 313 also includes an entry called <TT>ntpd</TT>; its exact form depends on
 314 the arguments you provide to the <B>runntp</B> command.
 315 <A NAME="IDX6283"></A>
 316 <A NAME="IDX6284"></A>
 317 <P>As a system administrator, you do not contact the NTPD directly once you
 318 have installed it according to the instructions in the <I>AFS Quick
 319 Beginnings</I>.
 320 <P><H3><A NAME="HDRWQ198" HREF="auagd002.htm#ToC_173">The upserver and upclient Processes&#58; the Update Server</A></H3>
 321 <A NAME="IDX6285"></A>
 322 <A NAME="IDX6286"></A>
 323 <A NAME="IDX6287"></A>
 324 <P>The Update Server has two separate parts, each of which runs on a different
 325 type of server machine. The <B>upserver</B> process is the server
 326 portion of the Update Server. Its function depends on which edition of
 327 AFS you use&#58;
 328 <UL>
 329 <P><LI>With both the United States and international editions, it runs on the
 330 binary distribution machine of each system type you use as a server machine,
 331 distributing the contents of each one&#39;s <B>/usr/afs/bin</B> directory
 332 to the other server machines of that type. This guarantees that all
 333 machines have the same version of AFS binaries. (For a list of the
 334 binaries, see <A HREF="auagd008.htm#HDRWQ118">Binaries in the /usr/afs/bin Directory</A>.)
 335 <P><LI>In you use the United States edition of AFS, it also runs on the
 336 cell&#39;s system control machine, distributing the contents of its
 337 <B>/usr/afs/etc</B> directory to all the other server machines in order to
 338 synchronize the configuration files stored in that directory. (For a
 339 list of the configuration files, see <A HREF="auagd008.htm#HDRWQ119">Common Configuration Files in the /usr/afs/etc Directory</A>.)
 340 </UL>
 341 <P>The <B>upclient</B> process is the client portion of the Update Server,
 342 and like the server portion its function depends on the AFS edition in
 343 use.
 344 <UL>
 345 <P><LI>It runs on every server machine that is not a binary distribution machine,
 346 referencing the binary distribution machine of its system type as the source
 347 for updates to the binaries in the <B>/usr/afs/bin</B> directory.
 348 The conventional process name to assign is <B>upclientbin</B>.
 349 <P><LI>If you use the United States edition of AFS, another instance of the
 350 process runs on every server machine except the system control machine.
 351 It references the system control machine as the source for updates to the
 352 common configuration files in the <B>/usr/afs/etc</B> directory.
 353 The conventional process name to assign is <B>upclientetc</B>.
 354 </UL>
 355 <P>In output from the <B>bos status</B> command, the server portion
 356 appears as <TT>upserver</TT> and the client portions as
 357 <TT>upclientbin</TT> and <TT>upclientetc</TT>, if the conventional names
 358 are assigned. In the output from the <B>ps</B> command, the server
 359 portion appears as <TT>/usr/afs/bin/upserver</TT> and the client portions as
 360 <TT>/usr/afs/bin/upclient</TT>.
 361 <A NAME="IDX6288"></A>
 362 <A NAME="IDX6289"></A>
 363 <P>You do not contact the Update Server directly once you have installed
 364 it. It operates automatically whenever you use <B>bos</B> commands
 365 to change the files that it distributes.
 366 <P><H3><A NAME="HDRWQ199" HREF="auagd002.htm#ToC_174">The vlserver Process&#58; the Volume Location Server</A></H3>
 367 <A NAME="IDX6290"></A>
 368 <A NAME="IDX6291"></A>
 369 <P>The <B>vlserver</B> process, which runs on database server machines, is
 370 the Volume Location (VL) Server that automatically tracks which file server
 371 machines house each volume, making its location transparent to client
 372 applications.
 373 <P>The process appears as <TT>vlserver</TT> in the <B>bos status</B>
 374 command&#39;s output, if the conventional name is assigned. It appears
 375 in the <B>ps</B> command&#39;s output as
 376 <TT>/usr/afs/bin/vlserver</TT>.
 377 <A NAME="IDX6292"></A>
 378 <A NAME="IDX6293"></A>
 379 <A NAME="IDX6294"></A>
 380 <P>As a system administrator, you contact the VL Server when you issue any
 381 <B>vos</B> command that changes the status of a volume (it records the
 382 status changes in the VLDB).
 383 <HR><H2><A NAME="HDRWQ200" HREF="auagd002.htm#ToC_175">Controlling and Checking Process Status</A></H2>
 384 <P>To define the AFS server processes that run on a server
 385 machine, use the <B>bos create</B> command to create entries for them in
 386 the local <B>/usr/afs/local/BosConfig</B> file. The BOS Server
 387 monitors the processes listed in the <B>BosConfig</B> file that are marked
 388 with the <TT>Run</TT> status flag, and automatically attempts to restart
 389 them if they fail. After creating process entries, you use other
 390 commands from the <B>bos</B> suite to stop and start processes or change
 391 the status flag as desired.
 392 <P>Never edit the <B>BosConfig</B> file directly rather than using
 393 <B>bos</B> commands. Similarly, it is not a good practice to run
 394 server processes without listing them in the <B>BosConfig</B> file, or to
 395 stop them using process termination commands such as the UNIX <B>kill</B>
 396 command.
 397 <P><H3><A NAME="Header_176" HREF="auagd002.htm#ToC_176">The Information in the BosConfig File</A></H3>
 398 <A NAME="IDX6295"></A>
 399 <A NAME="IDX6296"></A>
 400 <P>A process&#39;s entry in the <B>BosConfig</B> file includes the
 401 following information&#58;
 402 <UL>
 403 <P><LI>The process&#39;s name. The recommended conventional names are
 404 defined in both the <I>AFS Quick Beginnings</I> and <A HREF="#HDRWQ215">Creating and Removing Processes</A>. The name of a simple process usually matches the
 405 name of its binary file (for example, <B>ptserver</B> for the Protection
 406 Server).
 407 <P><LI>Its type, which is one of the following&#58;
 408 <DL>
 409 <A NAME="IDX6297"></A>
 410 <A NAME="IDX6298"></A>
 411 <P><DT><B>simple
 412 </B><DD>A process that runs independently of any other on the server
 413 machine. If several simple processes fail at the same time, the BOS
 414 Server can restart them in any order. All standard AFS processes except
 415 the <B>fs</B> process are simple.
 416 <P><DT><B>fs
 417 <A NAME="IDX6299"></A>
 418 <A NAME="IDX6300"></A>
 419 <A NAME="IDX6301"></A>
 420 <A NAME="IDX6302"></A>
 421 <A NAME="IDX6303"></A>
 422 </B><DD>A process type reserved for the server process for which the conventional
 423 name is also <B>fs</B>. This process combines three
 424 components&#58; the File Server, the Volume Server, and the Salvager.
 425 <A NAME="IDX6304"></A>
 426 <A NAME="IDX6305"></A>
 427 <P><DT><B>cron
 428 </B><DD>A process that runs at a defined time rather than continuously.
 429 There are no standard processes of this type.
 430 </DL>
 431 <A NAME="IDX6306"></A>
 432 <A NAME="IDX6307"></A>
 433 <A NAME="IDX6308"></A>
 434 <A NAME="IDX6309"></A>
 435 <P><LI>Its status flag, which tells the BOS Server whether it performs the
 436 following two actions with respect to the process&#58;
 437 <UL>
 438 <P><LI>Start the process during BOS Server initialization
 439 <P><LI>Restart the process if it (the process) fails
 440 </UL>The two possible values are <TT>Run</TT> (which directs the BOS Server
 441 to perform these actions) and <TT>NotRun</TT> (which directs the BOS Server
 442 to ignore the process). The BOS Server itself never changes the setting
 443 of this flag, even if the process fails repeatedly. Also, this flag is
 444 for internal use only; it does not appear in the <B>bos status</B>
 445 command&#39;s output.
 446 <P><LI>Its command parameters, which are the commands that the BOS Server runs to
 447 start the process.
 448 <A NAME="IDX6310"></A>
 449 <UL>
 450 <P><LI>A simple processes has one&#58; the complete pathname to its binary file
 451 <P><LI>The <B>fs</B> process has three&#58; the complete pathnames to each
 452 of the three component processes (<B>/usr/afs/bin/fileserver</B>,
 453 <B>/usr/afs/bin/volserver</B>, and <B>/usr/afs/bin/salvager</B>)
 454 <P><LI>A cron process has two&#58; the first the complete pathname to its
 455 binary file, the second the time at which the BOS Server runs it
 456 </UL>
 457 </UL>
 458 <P>In addition to process definitions, the <B>BosConfig</B> file also
 459 records automatic restart times for processes that have new binaries, and for
 460 all server processes including the BOS Server. See <A HREF="#HDRWQ225">Setting the BOS Server&#39;s Restart Times</A>.
 461 <P><H3><A NAME="HDRWQ201" HREF="auagd002.htm#ToC_177">How the BOS Server Uses the Information in the BosConfig File</A></H3>
 462 <A NAME="IDX6311"></A>
 463 <A NAME="IDX6312"></A>
 464 <A NAME="IDX6313"></A>
 465 <P>Whenever the BOS Server starts or restarts, it reads the
 466 <B>BosConfig</B> file to learn which processes it is to start and
 467 monitor. It transfers the information into kernel memory and does not
 468 read the <B>BosConfig</B> file again until it next restarts. This
 469 implies that the BOS Server&#39;s memory state can change independently of
 470 the <B>BosConfig</B> file. You can, for example, stop a process but
 471 leave its status flag in the <B>BosConfig</B> file as <TT>Run</TT>, or
 472 start a process even though its status flag in the <B>BosConfig</B> file
 473 is <TT>NotRun</TT>.
 474 <P><H3><A NAME="HDRWQ202" HREF="auagd002.htm#ToC_178">About Starting and Stopping the Database Server Processes</A></H3>
 475 <A NAME="IDX6314"></A>
 476 <A NAME="IDX6315"></A>
 477 <A NAME="IDX6316"></A>
 478 <A NAME="IDX6317"></A>
 479 <A NAME="IDX6318"></A>
 480 <A NAME="IDX6319"></A>
 481 <A NAME="IDX6320"></A>
 482 <P>When you start or stop a database server process (Authentication Server,
 483 Backup Server, Protection Server, or Volume Location Server) for more than a
 484 short time, you must follow the instructions in the <I>AFS Quick
 485 Beginnings</I> for installing or removing a database server machine.
 486 Here is a summary of the tasks you must perform to preserve correct AFS
 487 functioning.
 488 <UL>
 489 <P><LI>Start or stop all four database server processes on that machine.
 490 All AFS server processes and the Cache Manager processes expect all four
 491 database server processes to be running on each machine listed in the
 492 <B>CellServDB</B> file. There is no way to indicate in the file
 493 that a machine is running only some of the database server processes.
 494 <P><LI>Add or remove the machine in the <B>/usr/afs/etc/CellServDB</B> file
 495 on all server machines and the <B>/usr/vice/etc/CellServDB</B> file on all
 496 client machines.
 497 <P><LI>Restart the database server processes on the other database server
 498 machines to force an election of a new Ubik coordinator for each one.
 499 </UL>
 500 <P><H3><A NAME="HDRWQ203" HREF="auagd002.htm#ToC_179">About Starting and Stopping the Update Server</A></H3>
 501 <A NAME="IDX6321"></A>
 502 <P>In the conventional cell configuration, one server machine of each system
 503 type acts as a binary distribution machine, running the server portion of the
 504 Update Server (<B>upserver</B> process) to distribute the contents of its
 505 <B>/usr/afs/bin</B> directory. The other server machines of its
 506 system type run an instance of the Update Server client portion (by convention
 507 called <B>upclientbin</B>) that references the binary distribution
 508 machine.
 509 <P>If you run the United States edition of AFS, it is conventional for the
 510 first server machine you install to act as the system control machine, running
 511 the server portion of the Update Server (<B>upserver</B> process) to
 512 distribute the contents of its <B>/usr/afs/etc</B> directory. All
 513 other server machines run an instance of the Update Server client portion (by
 514 convention called <B>upclientetc</B>) that references the system control
 515 machine.
 516 <P>
 517 <TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">If you are using the international edition of AFS, do not use the Update
 518 Server to distribute the contents of the <B>/usr/afs/etc</B> directory
 519 (you do not run a system control machine). Ignore all references to the
 520 process in this chapter.
 521 </TD></TR></TABLE>
 522 <P>It is simplest not to move binary distribution or system control
 523 responsibilities to a different machine unless you completely decommission a
 524 machine that is currently serving in one of those roles. Running the
 525 Update Server usually imposes very little processing load. If you must
 526 move the functionality, perform the following related tasks.
 527 <UL>
 528 <P><LI>If you replace the system control machine, you must stop the
 529 <B>upclientetc</B> process on every other server machine and define a new
 530 one that references the new system control machine.
 531 <P><LI>If you replace a binary distribution machine, you must stop the
 532 <B>upclientbin</B> process on every other server machine of its system
 533 type and define a new one that references the new binary distribution machine
 534 (unless you are no longer running any server machines of that system
 535 type).
 536 </UL>
 537 <HR><H2><A NAME="HDRWQ204" HREF="auagd002.htm#ToC_180">Displaying Process Status and Information from the BosConfig File</A></H2>
 538 <P>To display the status of the AFS server processes on a
 539 server machine, issue the <B>bos status</B> command. Adding the
 540 <B>-long</B> flag displays most of the information from each
 541 process&#39;s entry in the <B>BosConfig</B> file, including its type and
 542 command parameters. It also displays a warning message if the mode bits
 543 on files and subdirectories in the <B>/usr/afs</B> directory do not match
 544 the expected values.
 545 <P><H3><A NAME="HDRWQ205" HREF="auagd002.htm#ToC_181">To display the status of server processes and their BosConfig entries</A></H3>
 546 <A NAME="IDX6322"></A>
 547 <A NAME="IDX6323"></A>
 548 <A NAME="IDX6324"></A>
 549 <A NAME="IDX6325"></A>
 550 <A NAME="IDX6326"></A>
 551 <A NAME="IDX6327"></A>
 552 <A NAME="IDX6328"></A>
 553 <A NAME="IDX6329"></A>
 554 <OL TYPE=1>
 555 <P><LI>Issue the <B>bos status</B> command.
 556 <PRE>   % <B>bos status</B> &lt;<VAR>machine&nbsp;name</VAR>>  [&lt;<VAR>server&nbsp;process&nbsp;name</VAR>><SUP>+</SUP>]  [<B>-long</B>]
 557 </PRE>
 558 <P>where
 559 <DL>
 560 <P><DT><B>stat
 561 </B><DD>Is the shortest acceptable abbreviation of <B>status</B>.
 562 <P><DT><B><VAR>machine name</VAR>
 563 </B><DD>Specifies the file server machine for which to display process
 564 status.
 565 <P><DT><B><VAR>server process name</VAR>
 566 </B><DD>Names each process for which to display status, using the name assigned
 567 when its entry was defined with the <B>bos create</B> command. Omit
 568 this argument to display the status of all server processes.
 569 <P><DT><B>-long
 570 </B><DD>Displays, in addition to status, information from the process&#39;s entry
 571 in the <B>BosConfig</B> file&#58; its type, its status flag, its command
 572 parameters, the associated notifier program, and so on.
 573 </DL>
 574 </OL>
 575 <P>The output includes an entry for each process and uses one of the following
 576 strings to indicate the process&#39;s status&#58;
 577 <UL>
 578 <P><LI><TT>currently running normally</TT> indicates that the process is
 579 running and its status flag in the <B>BosConfig</B> file is
 580 <TT>Run</TT>. For cron entries, this message indicates that the
 581 command is still scheduled to run, not necessarily that it is actually running
 582 when the <B>bos status</B> command was issued.
 583 <P><LI><TT>temporarily enabled</TT> indicates that the process is running but
 584 that its status flag in the <B>BosConfig</B> file is
 585 <TT>NotRun</TT>. The most common reason is that a system
 586 administrator has used the <B>bos startup</B> command to start the
 587 process.
 588 <P><LI><TT>temporarily disabled</TT> indicates that the process is not running
 589 even though its status flag in the <B>BosConfig</B> file is
 590 <TT>Run</TT>. The most common reasons are either that a system
 591 administrator has used the <B>bos shutdown</B> command to stop the process
 592 or that the BOS Server ceased trying to restart the process after numerous
 593 failed attempts. In the latter case, a supplementary message
 594 appears&#58; <TT>stopped for too many errors</TT>.
 595 <P><LI><TT>disabled</TT> indicates that the process is not running and that its
 596 status flag in the <B>BosConfig</B> file is <TT>NotRun</TT>. The
 597 BOS Server is not monitoring the process. Only a system administrator
 598 can set the flag this way; the BOS Server never does.
 599 </UL>
 600 <P>The output for the <B>fs</B> process always includes a message marked
 601 <TT>Auxiliary status</TT>, which can be one of the following&#58;
 602 <UL>
 603 <P><LI><TT>file server running</TT> indicates that the File Server and Volume
 604 Server components of the File Server process are running normally.
 605 <P><LI><TT>salvaging file system</TT> indicates that the Salvager is running,
 606 which usually implies that the File Server and Volume Server are temporarily
 607 disabled. The BOS Server restarts them as soon as the Salvager is
 608 finished.
 609 </UL>
 610 <P>The output for a cron process also includes an <TT>Auxiliary status</TT>
 611 message to report when the command is scheduled to run next; see the
 612 example that follows.
 613 <P>The output for any process can include the supplementary message <TT>has
 614 core file</TT> to indicate that at some point the process failed and
 615 generated a core file in the <B>/usr/afs/logs</B> directory. In
 616 most cases, the BOS Server is able to restart the process and it is
 617 running.
 618 <P>The following example includes a user-defined cron entry called
 619 <B>backupusers</B>&#58;
 620 <PRE>   % <B>bos status fs3.abc.com</B>
 621    Instance kaserver, currently running normally.
 622    Instance ptserver, currently running normally.
 623    Instance vlserver, has core file, currently running normally.
 624    Instance buserver, currently running normally.
 625    Instance fs, currently running normally.
 626        Auxiliary status is&#58; file server running.
 627    Instance upserver, currently running normally.
 628    Instance runntp, currently running normally.
 629    Instance backupusers, currently running normally.
 630        Auxiliary status is&#58; run next at Mon Jun 7 02&#58;00&#58;00 1999.
 631 </PRE>
 632 <P>If you include the <B>-long</B> flag to the <B>bos status</B>
 633 command, a process&#39;s entry in the output includes the following
 634 additional information from the <B>BosConfig</B> file&#58;
 635 <UL>
 636 <P><LI>The process&#39;s type (<TT>simple</TT>, <TT>fs</TT>, or
 637 <TT>cron</TT>).
 638 <P><LI>The day and time the process last started or restarted.
 639 <P><LI>The number of <TT>proc starts</TT>, which is how many times the BOS
 640 Server has started or restarted the process since it started itself.
 641 <P><LI>The <TT>Last exit</TT> time when the process (or one of the component
 642 processes in the <B>fs</B> process) last terminated. This line does
 643 not appear if the process has not terminated since the BOS Server
 644 started.
 645 <P><LI>The <TT>Last error exit</TT> time when the process (or one of the
 646 component processes in the <B>fs</B> process) last failed due to an
 647 error. A further explanation such as <TT>due to shutdown request</TT>
 648 sometimes appears. This line does not appear if the process has not
 649 failed since the BOS Server started.
 650 <P><LI>Each command that the BOS Server invokes to start the process, as
 651 specified by the <B>-cmd</B> argument to the <B>bos create</B>
 652 command.
 653 <P><LI>The pathname of the notifier program that the BOS Server invokes when the
 654 process terminates (if any), as specified by the <B>-notifier</B> argument
 655 to the <B>bos create</B> command.
 656 </UL>
 657 <P>In addition, if the BOS Server has found that the mode bits on certain
 658 files and directories under <B>/usr/afs</B> deviate from what it expects,
 659 it prints the following warning message&#58;
 660 <PRE>   Bosserver process reports inappropriate access on server directories
 661 </PRE>
 662 <P>The expected protections for the directories and files in the
 663 <B>/usr/afs</B> directory are as follows. A question mark indicates
 664 that the BOS Server does not check the mode bit. See the <I>AFS Quick
 665 Beginnings</I> for more information about setting the protections on these
 666 files and directories.
 667 <BR>
 668 <TABLE WIDTH="100%">
 669 <TR>
 670 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="50%"><B>/usr/afs</B>
 671 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="50%"><TT>drwxr</TT>?<TT>xr-x</TT>
 672 </TD></TR><TR>
 673 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="50%"><B>/usr/afs/backup</B>
 674 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="50%"><TT>drwx</TT>???<TT>---</TT>
 675 </TD></TR><TR>
 676 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="50%"><B>/usr/afs/bin</B>
 677 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="50%"><TT>drwxr</TT>?<TT>xr-x</TT>
 678 </TD></TR><TR>
 679 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="50%"><B>/usr/afs/db</B>
 680 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="50%"><TT>drwx</TT>???<TT>---</TT>
 681 </TD></TR><TR>
 682 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="50%"><B>/usr/afs/etc</B>
 683 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="50%"><TT>drwxr</TT>?<TT>xr-x</TT>
 684 </TD></TR><TR>
 685 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="50%"><B>/usr/afs/etc/KeyFile</B>
 686 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="50%"><TT>-rw</TT>????<TT>---</TT>
 687 </TD></TR><TR>
 688 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="50%"><B>/usr/afs/etc/UserList</B>
 689 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="50%"><TT>-rw</TT>?????<TT>--</TT>
 690 </TD></TR><TR>
 691 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="50%"><B>/usr/afs/local</B>
 692 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="50%"><TT>drwx</TT>???<TT>---</TT>
 693 </TD></TR><TR>
 694 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="50%"><B>/usr/afs/logs</B>
 695 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="50%"><TT>drwxr</TT>?<TT>xr-x</TT>
 696 </TD></TR></TABLE>
 697 <P>The following illustrates the extended output for the <B>fs</B> process
 698 running on the machine <B>fs3.abc.com</B>&#58;
 699 <PRE>   % <B>bos status fs3.abc.com fs -long</B>
 700    Instance fs, (type is fs), currently running normally.
 701        Auxiliary status is file server running
 702    Process last started at Mon May 3 8&#58;29&#58;19 1999 (3 proc starts)
 703    Last exit at Mon May 3 8&#58;29&#58;19 1999
 704    Last error exit at Mon May 3 8&#58;29&#58;19 1999, due to shutdown request
 705    Command 1 is &#39;/usr/afs/bin/fileserver&#39;
 706    Command 2 is &#39;/usr/afs/bin/volserver&#39;
 707    Command 3 is &#39;/usr/afs/bin/salvager&#39;
 708 </PRE>
 709 <HR><H2><A NAME="HDRWQ215" HREF="auagd002.htm#ToC_182">Creating and Removing Processes</A></H2>
 710 <A NAME="IDX6330"></A>
 711 <A NAME="IDX6331"></A>
 712 <A NAME="IDX6332"></A>
 713 <A NAME="IDX6333"></A>
 714 <A NAME="IDX6334"></A>
 715 <A NAME="IDX6335"></A>
 716 <A NAME="IDX6336"></A>
 717 <A NAME="IDX6337"></A>
 718 <P>To start a new AFS server process on a server machine, issue the <B>bos
 719 create</B> command, which creates an entry in the
 720 <B>/usr/afs/local/BosConfig</B> file, sets the process&#39;s status flag
 721 to <TT>Run</TT> both in the file and in the BOS Server&#39;s memory, and
 722 starts it running immediately. The binary file for the new process must
 723 already be installed, by convention in the <B>/usr/afs/bin</B> directory
 724 (see <A HREF="auagd008.htm#HDRWQ145">Installing New Binaries</A>).
 725 <P>To stop a process permanently, first issue the <B>bos stop</B> command,
 726 which changes the process&#39;s status flag to <TT>NotRun</TT> in both the
 727 <B>BosConfig</B> file and the BOS Server&#39;s memory; it is marked
 728 as <TT>disabled</TT> in the output from the <B>bos status</B>
 729 command. If desired, issue the <B>bos delete</B> command to remove
 730 the process&#39;s entry from the <B>BosConfig</B> file; the process
 731 no longer appears in the <B>bos status</B> command&#39;s output.
 732 <P>
 733 <TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">If you are starting or stopping a database server process in the manner
 734 described in this section, follow the complete instructions in the <I>AFS
 735 Quick Beginnings</I> for creating or removing a database server
 736 machine. If you run one database server process on a given machine, you
 737 must run them all; for more information, see <A HREF="#HDRWQ202">About Starting and Stopping the Database Server Processes</A>. Similarly, if you are stopping the
 738 <B>upserver</B> process on the system control machine or a binary
 739 distribution machine, you must complete the additional tasks described in <A HREF="#HDRWQ203">About Starting and Stopping the Update Server</A>.
 740 </TD></TR></TABLE>
 741 <P><H3><A NAME="HDRWQ216" HREF="auagd002.htm#ToC_183">To create and start a new process</A></H3>
 742 <A NAME="IDX6338"></A>
 743 <A NAME="IDX6339"></A>
 744 <A NAME="IDX6340"></A>
 745 <A NAME="IDX6341"></A>
 746 <A NAME="IDX6342"></A>
 747 <A NAME="IDX6343"></A>
 748 <A NAME="IDX6344"></A>
 749 <A NAME="IDX6345"></A>
 750 <OL TYPE=1>
 751 <P><LI>Verify that you are authenticated as a user listed in the
 752 <B>/usr/afs/etc/UserList</B> file. If necessary, issue the <B>bos
 753 listusers</B> command, which is fully described in <A HREF="auagd021.htm#HDRWQ815">To display the users in the UserList file</A>.
 754 <PRE>   % <B>bos listusers</B> &lt;<VAR>machine name</VAR>>
 755 </PRE>
 756 <P><LI><B>(Optional)</B> Verify that the process&#39;s binaries are
 757 installed in the <B>/usr/afs/bin</B> directory on this machine. If
 758 necessary, login at the console or telnet to the machine and list the contents
 759 of the <B>/usr/afs/bin</B> directory.
 760 <P>If the binaries are not present, install them on the binary distribution
 761 machine of the appropriate system type, and wait for the Update Server to copy
 762 them to this machine. For instructions, see <A HREF="auagd008.htm#HDRWQ145">Installing New Binaries</A>.
 763 <PRE>   % <B>ls /usr/afs/bin</B>
 764 </PRE>
 765 <P><LI><A NAME="LIWQ217"></A>Issue the <B>bos create</B> command to create an entry in
 766 the <B>BosConfig</B> file and start the process.
 767 <PRE>   % <B>bos create</B> &lt;<VAR>machine&nbsp;name</VAR>> &lt;<VAR>server&nbsp;process&nbsp;name</VAR>>   \
 768              &lt;<VAR>server&nbsp;type</VAR>> &lt;<VAR>command&nbsp;lines</VAR>><SUP>+</SUP> [ <B>-notifier</B> &lt;<VAR>Notifier&nbsp;program</VAR>>]
 769 </PRE>
 770 <P>where
 771 <DL>
 772 <P><DT><B>cr
 773 </B><DD>Is the shortest acceptable abbreviation of <B>create</B>.
 774 <P><DT><B><VAR>machine name</VAR>
 775 </B><DD>Specifies the file server machine on which to create the process.
 776 <P><DT><B><VAR>server process name</VAR>
 777 </B><DD>Names the process to create and start. For simple processes, the
 778 conventional value is the name of the process&#39;s binary file. It is
 779 best to use the same name on every server machine that runs the
 780 process. The following is a list of the conventional names for simple
 781 and fs-type processes (there are no standard cron processes).
 782 <UL>
 783 <P><LI><B>buserver</B> for the Backup Server
 784 <P><LI><B>fs</B> for the process that combines the File Server, Volume
 785 Server, and Salvager
 786 <P><LI><B>kaserver</B> for the Authentication Server
 787 <P><LI><B>ptserver</B> for the Protection Server
 788 <P><LI><B>runntp</B> for the controller process for the Network Time Protocol
 789 Daemon
 790 <P><LI><B>upclientbin</B> for the client portion of the Update Server that
 791 references the binary distribution machine of this machine&#39;s system type
 792 <P><LI><B>upclientetc</B> for the client portion of the Update Server that
 793 references the system control machine
 794 <P><LI><B>vlserver</B> for the Volume Location (VL) Server
 795 </UL>
 796 <P><DT><B><VAR>server type</VAR>
 797 </B><DD>Defines the process&#39;s type. Choose one of the following
 798 values&#58;
 799 <UL>
 800 <P><LI><B>cron</B> for a cron process
 801 <P><LI><B>fs</B> for the process named <B>fs</B>
 802 <P><LI><B>simple</B> for all other processes listed as acceptable values for
 803 the <VAR>server&nbsp;process&nbsp;name</VAR> argument
 804 </UL>
 805 <P><DT><B><VAR>command lines</VAR>
 806 </B><DD>Specifies each command the BOS Server runs to start the process.
 807 Specify no more than six commands (which can include the command&#39;s
 808 options, in which case the entire string is surrounded by double quotes);
 809 any additional commands are ignored.
 810 <P>For a simple process, provide the complete pathname of the process&#39;s
 811 binary file on the local disk (for example, <B>/usr/afs/bin/ptserver</B>
 812 for the Protection Server). If including any of the initialization
 813 command&#39;s options, surround the entire command in double quotes (<B>"
 814 "</B>). The <B>upclient</B> process has a required argument, and
 815 the commands for all other processes take optional arguments.
 816 <A NAME="IDX6346"></A>
 817 <P>For the <B>fs</B> process, provide the complete pathname of the local
 818 disk binary file for each of the component processes&#58;
 819 <B>fileserver</B>, <B>volserver</B>, and <B>salvager</B>, in that
 820 order. The standard binary directory is <B>/usr/afs/bin</B>.
 821 If including any of an initialization command&#39;s options, surround the
 822 entire command in double quotes (<B>" "</B>).
 823 <A NAME="IDX6347"></A>
 824 <P>For a <B>cron</B> process, provide two parameters&#58;
 825 <A NAME="IDX6348"></A>
 826 <UL>
 827 <P><LI>The complete local disk pathname of either an executable file or a command
 828 from one of the AFS suites (complete with all of the necessary
 829 arguments). Surround this parameter with double quotes (<B>" "</B>)
 830 if it contains spaces.
 831 <P><LI>A specification of when the BOS Server executes the file or command
 832 indicated by the first parameter. There are three acceptable
 833 values&#58;
 834 <UL>
 835 <P><LI>The string <B>now</B>, which directs the BOS Server to execute the
 836 file or command immediately and only once. It is usually simpler to
 837 issue the command directly or issue the <B>bos exec</B> command.
 838 <P><LI>A time of day. The BOS Server executes the file or command daily at
 839 the indicated time. Separate the hours and minutes with a colon
 840 (<I>hh</I>&#58;<I>MM</I>), and use either 24-hour format, or a value
 841 in the range from <B>1&#58;00</B> through <B>12&#58;59</B> with
 842 the addition of <B>am</B> or <B>pm</B>. For example, both
 843 <B>14&#58;30</B> and <B>"2&#58;30 pm"</B> indicate 2&#58;30 in
 844 the afternoon. Surround this parameter with double quotes (<B>"
 845 "</B>) if it contains a space.
 846 <P><LI>A day of the week and time of day, separated by a space and surrounded
 847 with double quotes (<B>" "</B>). The BOS Server executes the file
 848 or command weekly at the indicated day and time. For the day, provide
 849 either the whole name or the first three letters, all in lowercase letters
 850 (<B>sunday</B> or <B>sun</B>, <B>thursday</B> or <B>thu</B>,
 851 and so on). For the time, use the same format as when specifying the
 852 time alone.
 853 </UL>
 854 </UL>
 855 <P><DT><B>-notifier
 856 </B><DD>Specifies the pathname of a program that the BOS Server runs when the
 857 process terminates. For more information on notifier programs, see the
 858 <B>bos create</B> command reference page in the <I>AFS Administration
 859 Reference</I>.
 860 </DL>
 861 </OL>
 862 <P>The following example defines and starts the Protection Server on the
 863 machine <B>db2.abc.com</B>&#58;
 864 <PRE>
 865    % <B>bos create db2.abc.com ptserver simple /usr/afs/bin/ptserver</B>
 866
 867 </PRE>
 868 <P>The following example defines and starts the <B>fs</B> process on the
 869 machine <B>fs6.abc.com</B>.
 870 <PRE>
 871    % <B>bos create fs6.abc.com fs fs /usr/afs/bin/fileserver </B>  \
 872         <B>/usr/afs/bin/volserver /usr/afs/bin/salvager</B>
 873
 874 </PRE>
 875 <P>The following example defines and starts a cron process called
 876 <B>backupuser</B> process on the machine
 877 <B>fs3.abc.com</B>, scheduling it to run each day at
 878 3&#58;00 a.m.
 879 <PRE>   % <B>bos create fs3.abc.com backupuser cron  "/usr/afs/bin/vos backupsys -prefix user -local" 3&#58;00</B>
 880 </PRE>
 881 <P><H3><A NAME="Header_184" HREF="auagd002.htm#ToC_184">To stop a process and remove it from the BosConfig file</A></H3>
 882 <A NAME="IDX6349"></A>
 883 <A NAME="IDX6350"></A>
 884 <A NAME="IDX6351"></A>
 885 <A NAME="IDX6352"></A>
 886 <A NAME="IDX6353"></A>
 887 <A NAME="IDX6354"></A>
 888 <A NAME="IDX6355"></A>
 889 <OL TYPE=1>
 890 <P><LI>Verify that you are authenticated as a user listed in the
 891 <B>/usr/afs/etc/UserList</B> file. If necessary, issue the <B>bos
 892 listusers</B> command, which is fully described in <A HREF="auagd021.htm#HDRWQ815">To display the users in the UserList file</A>.
 893 <PRE>   % <B>bos listusers</B> &lt;<VAR>machine name</VAR>>
 894 </PRE>
 895 <P><LI><A NAME="LIPROC-STOP"></A>Issue the <B>bos stop</B> command to change each
 896 process&#39;s status flag in the <B>BosConfig</B> file to
 897 <TT>NotRun</TT> and to stop it. You must issue this command even for
 898 cron processes that you wish to remove from the <B>BosConfig</B> file,
 899 even though they do not run continuously. For a detailed description of
 900 this command, see <A HREF="#HDRWQ219">To stop a process by changing its status to NotRun</A>.
 901 <PRE>
 902    % <B>bos stop</B> &lt;<VAR>machine&nbsp;name</VAR>> &lt;<VAR>server&nbsp;process&nbsp;name</VAR>><SUP>+</SUP> [<B>-wait</B>]
 903
 904 </PRE>
 905 <P><LI><A NAME="LIPROC-DEL"></A>Issue the <B>bos delete</B> command to remove each
 906 process from the <B>BosConfig</B> file.
 907 <PRE>   % <B>bos delete</B> &lt;<VAR>machine&nbsp;name</VAR>> &lt;<VAR>server&nbsp;process&nbsp;name</VAR>><SUP>+</SUP>
 908 </PRE>
 909 <P>where
 910 <DL>
 911 <P><DT><B>d
 912 </B><DD>Is the shortest acceptable abbreviation of <B>delete</B>.
 913 <P><DT><B><VAR>machine name</VAR>
 914 </B><DD>Specifies the server machine on which to remove processes from the
 915 <B>BosConfig</B> file.
 916 <P><DT><B><VAR>server process name</VAR>
 917 </B><DD>Names each process entry to remove from the <B>BosConfig</B>
 918 file. Provide the same names as in Step <A HREF="#LIPROC-STOP">2</A>.
 919 </DL>
 920 </OL>
 921 <HR><H2><A NAME="HDRWQ218" HREF="auagd002.htm#ToC_185">Stopping and Starting Processes Permanently</A></H2>
 922 <A NAME="IDX6356"></A>
 923 <A NAME="IDX6357"></A>
 924 <A NAME="IDX6358"></A>
 925 <A NAME="IDX6359"></A>
 926 <P>To stop a process so that the BOS Server no longer attempts to monitor it,
 927 issue the <B>bos stop</B> command. The process&#39;s status flag
 928 is set to <TT>NotRun</TT> in both the BOS Server&#39;s memory and in the
 929 <B>BosConfig</B> file. The process does not run again until you
 930 issue the <B>bos start</B> command, which sets its status flag back to
 931 <TT>Run</TT> in both the BOS Server&#39;s memory and in the
 932 <B>BosConfig</B> file. (You can also use the <B>bos startup</B>
 933 command to start the process again without changing its status flag in the
 934 <B>BosConfig</B> file; see <A HREF="#HDRWQ221">Stopping and Starting Processes Temporarily</A>.)
 935 <P>There is no entry for the BOS Server in the <B>BosConfig</B> file, so
 936 the <B>bos stop</B> and <B>bos start</B> commands do not control
 937 it. To stop and immediately restart the BOS Server along with all other
 938 processes, use the <B>-bosserver</B> flag to the <B>bos restart</B>
 939 command as described in <A HREF="#HDRWQ224">Stopping and Immediately Restarting Processes</A>.
 940 <P>
 941 <TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">If you are starting or stopping a database server process in the manner
 942 described in this section, follow the complete instructions in the <I>AFS
 943 Quick Beginnings</I> for creating or removing a database server
 944 machine. If you run one database server process on a given machine, you
 945 must run them all; for more information, see <A HREF="#HDRWQ202">About Starting and Stopping the Database Server Processes</A>. Similarly, if you are stopping the
 946 <B>upserver</B> process on the system control machine or a binary
 947 distribution machine, you must complete the additional tasks described in <A HREF="#HDRWQ203">About Starting and Stopping the Update Server</A>.
 948 </TD></TR></TABLE>
 949 <P><H3><A NAME="HDRWQ219" HREF="auagd002.htm#ToC_186">To stop a process by changing its status to NotRun</A></H3>
 950 <A NAME="IDX6360"></A>
 951 <A NAME="IDX6361"></A>
 952 <A NAME="IDX6362"></A>
 953 <A NAME="IDX6363"></A>
 954 <A NAME="IDX6364"></A>
 955 <A NAME="IDX6365"></A>
 956 <OL TYPE=1>
 957 <P><LI>Verify that you are authenticated as a user listed in the
 958 <B>/usr/afs/etc/UserList</B> file. If necessary, issue the <B>bos
 959 listusers</B> command, which is fully described in <A HREF="auagd021.htm#HDRWQ815">To display the users in the UserList file</A>.
 960 <PRE>   % <B>bos listusers</B> &lt;<VAR>machine name</VAR>>
 961 </PRE>
 962 <P><LI>Issue the <B>bos stop</B> command to stop each process and set its
 963 status flag to <TT>NotRun</TT> in the <B>BosConfig</B> file and the BOS
 964 Server&#39;s memory.
 965 <PRE>   % <B>bos stop</B> &lt;<VAR>machine&nbsp;name</VAR>> &lt;<VAR>server&nbsp;process&nbsp;name</VAR>><SUP>+</SUP> [<B>-wait</B>]
 966 </PRE>
 967 <P>where
 968 <DL>
 969 <P><DT><B>sto
 970 </B><DD>Is the shortest acceptable abbreviation of <B>stop</B>.
 971 <P><DT><B><VAR>machine name</VAR>
 972 </B><DD>Specifies the server machine on which to stop the process.
 973 <P><DT><B><VAR>server process name</VAR>
 974 </B><DD>Names each process to stop, using the name assigned when its entry was
 975 defined with the <B>bos create</B> command.
 976 <P><DT><B>-wait
 977 </B><DD>Delays the return of the command shell prompt until all specified
 978 processes have stopped. If you omit the flag, the prompt returns almost
 979 immediately, even if all processes are not yet stopped.
 980 </DL>
 981 </OL>
 982 <P><H3><A NAME="HDRWQ220" HREF="auagd002.htm#ToC_187">To start processes by changing their status flags to Run</A></H3>
 983 <A NAME="IDX6366"></A>
 984 <A NAME="IDX6367"></A>
 985 <A NAME="IDX6368"></A>
 986 <A NAME="IDX6369"></A>
 987 <A NAME="IDX6370"></A>
 988 <OL TYPE=1>
 989 <P><LI>Verify that you are listed in the <B>/usr/afs/etc/UserList</B>
 990 file. If necessary, issue the <B>bos listusers</B> command, which
 991 is fully described in <A HREF="auagd021.htm#HDRWQ815">To display the users in the UserList file</A>.
 992 <PRE>   % <B>bos listusers</B> &lt;<VAR>machine name</VAR>>
 993 </PRE>
 994 <P><LI><A NAME="LIPROC-START"></A>Issue the <B>bos start</B> command to change each
 995 process&#39;s status flag to <TT>Run</TT> in both the <B>BosConfig</B>
 996 file and the BOS Server&#39;s memory and to start it.
 997 <PRE>   %  <B>bos start</B> &lt;<VAR>machine&nbsp;name</VAR>> &lt;<VAR>server&nbsp;process&nbsp;name</VAR>><SUP>+</SUP>
 998 </PRE>
 999 <P>where
1000 <DL>
1001 <P><DT><B>start
1002 </B><DD>Must be typed in full.
1003 <P><DT><B><VAR>machine name</VAR>
1004 </B><DD>Specifies the server machine on which to start running each
1005 process.
1006 <P><DT><B><VAR>server process name</VAR>
1007 </B><DD>Specifies each process to start on <VAR>machine name</VAR>. Use the
1008 name assigned to the process at creation.
1009 </DL>
1010 </OL>
1011 <HR><H2><A NAME="HDRWQ221" HREF="auagd002.htm#ToC_188">Stopping and Starting Processes Temporarily</A></H2>
1012 <P>It is sometimes necessary to halt a process temporarily (for
1013 example, to make slight configuration changes or to perform
1014 maintenance). The commands described in this section change a
1015 process&#39;s status in the BOS Server&#39;s memory only; the effect is
1016 immediate and lasts until you change the memory state again (or until the BOS
1017 Server restarts, at which time it starts the process according to its entry in
1018 the <B>BosConfig</B> file).
1019 <P>To stop a process temporarily by changing its status flag in BOS Server
1020 memory to <TT>NotRun</TT>, use the <B>bos shutdown</B> command.
1021 To restart a stopped process by changing its status flag in the BOS
1022 Server&#39;s memory to <TT>Run</TT>, use the <B>bos startup</B>
1023 command. The process starts regardless of its status flag in the
1024 <B>BosConfig</B> file. You can also use the <B>bos startup</B>
1025 command to start all processes marked with status flag <TT>Run</TT> in the
1026 <B>BosConfig</B> file, as described in the following instructions.
1027 <P>Because the <B>bos startup</B> command starts a process without
1028 changing it status flag in the <B>BosConfig</B> file, it is useful for
1029 testing a server process without enabling it permanently. To stop and
1030 start processes by changing their status flags in the <B>BosConfig</B>
1031 file, see <A HREF="#HDRWQ218">Stopping and Starting Processes Permanently</A>; to stop and immediately restart a process, see <A HREF="#HDRWQ224">Stopping and Immediately Restarting Processes</A>.
1032 <TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">Do not temporarily stop a database server process on all machines at
1033 once. Doing so makes the database completely unavailable.
1034 </TD></TR></TABLE>
1035 <A NAME="IDX6371"></A>
1036 <A NAME="IDX6372"></A>
1037 <P><H3><A NAME="HDRWQ222" HREF="auagd002.htm#ToC_189">To stop processes temporarily</A></H3>
1038 <OL TYPE=1>
1039 <P><LI>Verify that you are listed in the <B>/usr/afs/etc/UserList</B>
1040 file. If necessary, issue the <B>bos listusers</B> command, which
1041 is fully described in <A HREF="auagd021.htm#HDRWQ815">To display the users in the UserList file</A>.
1042 <PRE>   % <B>bos listusers</B> &lt;<VAR>machine name</VAR>>
1043 </PRE>
1044 <P><LI><A NAME="LIWQ223"></A>Issue the <B>bos shutdown</B> command to stop each process
1045 by changing its status flag in the BOS Server&#39;s memory to
1046 <TT>NotRun</TT>.
1047 <PRE>   % <B>bos shutdown</B> &lt;<VAR>machine&nbsp;name</VAR>> [&lt;<VAR>instances</VAR>><SUP>+</SUP>] [<B>-wait</B>]
1048 </PRE>
1049 <P>where
1050 <DL>
1051 <P><DT><B>sh
1052 </B><DD>Is the shortest acceptable abbreviation of <B>shutdown</B>.
1053 <P><DT><B><VAR>machine name</VAR>
1054 </B><DD>Specifies the server machine on which to stop processes
1055 temporarily.
1056 <P><DT><B><VAR>instances</VAR>
1057 </B><DD>Specifies each process to stop temporarily. Use the name assigned
1058 to the process at creation.
1059 <P><DT><B>-wait
1060 </B><DD>Delays the return of the command shell prompt until all specified
1061 processes have actually stopped. If you omit the flag, the prompt
1062 returns almost immediately, even if all processes are not yet stopped.
1063 </DL>
1064 </OL>
1065 <A NAME="IDX6373"></A>
1066 <A NAME="IDX6374"></A>
1067 <P><H3><A NAME="Header_190" HREF="auagd002.htm#ToC_190">To start all stopped processes that have status flag Run in the BosConfig file</A></H3>
1068 <OL TYPE=1>
1069 <P><LI>Verify that you are listed in the <B>/usr/afs/etc/UserList</B>
1070 file. If necessary, issue the <B>bos listusers</B> command, which
1071 is fully described in <A HREF="auagd021.htm#HDRWQ815">To display the users in the UserList file</A>.
1072 <PRE>   % <B>bos listusers</B> &lt;<VAR>machine name</VAR>>
1073 </PRE>
1074 <P><LI>Issue the <B>bos startup</B> command to start each process on a
1075 machine that has status flag <TT>Run</TT> in the <B>BosConfig</B> file
1076 by changing its status flag in the BOS Server&#39;s memory from
1077 <TT>NotRun</TT> to <TT>Run</TT>.
1078 <PRE>   % <B>bos startup</B> &lt;<VAR>machine&nbsp;name</VAR>>
1079 </PRE>
1080 <P>where
1081 <DL>
1082 <P><DT><B>startup
1083 </B><DD>Must be typed in full.
1084 <P><DT><B><VAR>machine name</VAR>
1085 </B><DD>Specifies the server machine on which you wish to start all processes that
1086 have status flag <TT>Run</TT> in the <B>BosConfig</B> file.
1087 </DL>
1088 </OL>
1089 <P><H3><A NAME="Header_191" HREF="auagd002.htm#ToC_191">To start specific  processes</A></H3>
1090 <OL TYPE=1>
1091 <P><LI>Verify that you are listed in the <B>/usr/afs/etc/UserList</B>
1092 file. If necessary, issue the <B>bos listusers</B> command, which
1093 is fully described in <A HREF="auagd021.htm#HDRWQ815">To display the users in the UserList file</A>.
1094 <PRE>   % <B>bos listusers</B> &lt;<VAR>machine name</VAR>>
1095 </PRE>
1096 <P><LI>Issue the <B>bos startup</B> command to start specific processes by
1097 changing their status flags in the BOS Server&#39;s memory to <TT>Run</TT>
1098 without changing their status flags in the <B>BosConfig</B> file.
1099 <PRE>   % <B>bos startup</B> &lt;<VAR>machine&nbsp;name</VAR>> &lt;<VAR>instances</VAR>><SUP>+</SUP>
1100 </PRE>
1101 <P>where
1102 <DL>
1103 <P><DT><B>startup
1104 </B><DD>Must be typed in full.
1105 <P><DT><B><VAR>machine name</VAR>
1106 </B><DD>Names the server machine on which to start processes.
1107 <P><DT><B><VAR>instances</VAR>
1108 </B><DD>Specifies each process to start. Use the name assigned to the
1109 process at creation.
1110 </DL>
1111 </OL>
1112 <HR><H2><A NAME="HDRWQ224" HREF="auagd002.htm#ToC_192">Stopping and Immediately Restarting Processes</A></H2>
1113 <A NAME="IDX6375"></A>
1114 <A NAME="IDX6376"></A>
1115 <P>Although by default the BOS Server checks each day for new installed binary
1116 files and restarts the associated processes, it is sometimes desirable to stop
1117 and restart processes immediately. The <B>bos restart</B> command
1118 provides this functionality, starting a completely new instance of each
1119 affected process&#58;
1120 <UL>
1121 <P><LI>To stop and restart the BOS Server, which then restarts all processes
1122 marked with the <TT>Run</TT> status flag in the <B>BosConfig</B> file,
1123 include the <B>-bosserver</B> flag.
1124 <P><LI>To stop and restart all processes marked with the <TT>Run</TT> status
1125 flag in the <B>BosConfig</B> file, include the <B>-all</B>
1126 flag. The BOS Server does not restart
1127 <P><LI>To stop and restart specific processes regardless of the setting of their
1128 status flags in the <B>BosConfig</B> file, specify the name of each
1129 process to restart.
1130 </UL>
1131 <P>Restarting processes causes a service outage. It is usually best to
1132 schedule restarts for periods of low usage. The BOS Server
1133 automatically restarts all processes once a week, to reduce the potential for
1134 the core leaks that can develop as any process runs for an extended time;
1135 see <A HREF="#HDRWQ225">Setting the BOS Server&#39;s Restart Times</A>.
1136 <A NAME="IDX6377"></A>
1137 <A NAME="IDX6378"></A>
1138 <P>
1139 <A NAME="IDX6379"></A>
1140 <A NAME="IDX6380"></A>
1141 <A NAME="IDX6381"></A>
1142 <A NAME="IDX6382"></A>
1143 <A NAME="IDX6383"></A>
1144 <P><H3><A NAME="Header_193" HREF="auagd002.htm#ToC_193">To stop and restart all processes including the BOS Server</A></H3>
1145 <OL TYPE=1>
1146 <P><LI>Verify that you are listed in the <B>/usr/afs/etc/UserList</B>
1147 file. If necessary, issue the <B>bos listusers</B> command, which
1148 is fully described in <A HREF="auagd021.htm#HDRWQ815">To display the users in the UserList file</A>.
1149 <PRE>   % <B>bos listusers</B> &lt;<VAR>machine name</VAR>>
1150 </PRE>
1151 <P><LI>Issue the <B>bos restart</B> command with the <B>-bosserver</B>
1152 flag to stop and restart the BOS Server, which restarts every process marked
1153 with status flag <TT>Run</TT> in the <B>BosConfig</B> file.
1154 <PRE>   % <B>bos restart</B> &lt;<VAR>machine&nbsp;name</VAR>>  <B>-bosserver</B>
1155 </PRE>
1156 <P>where
1157 <DL>
1158 <P><DT><B>res
1159 </B><DD>Is the shortest acceptable abbreviation of <B>restart</B>.
1160 <P><DT><B><VAR>machine name</VAR>
1161 </B><DD>Specifies the server machine on which to restart all processes.
1162 <P><DT><B>-bosserver
1163 </B><DD>Stops the BOS Server and all processes running on the machine. A
1164 new BOS Server instance starts; it then starts new instances of all
1165 processes marked with status flag <TT>Run</TT> in the <B>BosConfig</B>
1166 file.
1167 </DL>
1168 </OL>
1169 <A NAME="IDX6384"></A>
1170 <A NAME="IDX6385"></A>
1171 <A NAME="IDX6386"></A>
1172 <A NAME="IDX6387"></A>
1173 <P><H3><A NAME="Header_194" HREF="auagd002.htm#ToC_194">To stop and immediately restart all processes except the BOS Server</A></H3>
1174 <OL TYPE=1>
1175 <P><LI>Verify that you are listed in the <B>/usr/afs/etc/UserList</B>
1176 file. If necessary, issue the <B>bos listusers</B> command, which
1177 is fully described in <A HREF="auagd021.htm#HDRWQ815">To display the users in the UserList file</A>.
1178 <PRE>   % <B>bos listusers</B> &lt;<VAR>machine name</VAR>>
1179 </PRE>
1180 <P><LI>Issue the <B>bos restart</B> command with the <B>-all</B> flag to
1181 stop and immediately restart every process marked with status flag
1182 <TT>Run</TT> in the <B>BosConfig</B> file. The BOS Server does
1183 not restart.
1184 <PRE>   % <B>bos restart</B> &lt;<VAR>machine&nbsp;name</VAR>> <B>-all</B>
1185 </PRE>
1186 <P>where
1187 <DL>
1188 <P><DT><B>res
1189 </B><DD>Is the shortest acceptable abbreviation of <B>restart</B>.
1190 <P><DT><B><VAR>machine name</VAR>
1191 </B><DD>Specifies the server machine on which to stop and restart
1192 processes.
1193 <P><DT><B>-all
1194 </B><DD>Stops and immediately restarts all processes marked with status flag
1195 <TT>Run</TT> in the <B>BosConfig</B> file.
1196 </DL>
1197 </OL>
1198 <A NAME="IDX6388"></A>
1199 <A NAME="IDX6389"></A>
1200 <A NAME="IDX6390"></A>
1201 <A NAME="IDX6391"></A>
1202 <P><H3><A NAME="Header_195" HREF="auagd002.htm#ToC_195">To stop and immediately restart specific processes</A></H3>
1203 <OL TYPE=1>
1204 <P><LI>Verify that you are listed in the <B>/usr/afs/etc/UserList</B>
1205 file. If necessary, issue the <B>bos listusers</B> command, which
1206 is fully described in <A HREF="auagd021.htm#HDRWQ815">To display the users in the UserList file</A>.
1207 <PRE>   % <B>bos listusers</B> &lt;<VAR>machine name</VAR>>
1208 </PRE>
1209 <P><LI>Issue the <B>bos restart</B> command to stop and immediately restart
1210 one or more specified processes, regardless of their status flag setting in
1211 the <B>BosConfig</B> file.
1212 <PRE>   % <B>bos restart</B> &lt;<VAR>machine&nbsp;name</VAR>> &lt;<VAR>instances</VAR>><SUP>+</SUP>
1213 </PRE>
1214 <P>where
1215 <DL>
1216 <P><DT><B>res
1217 </B><DD>Is the shortest acceptable abbreviation of <B>restart</B>.
1218 <P><DT><B><VAR>machine name</VAR>
1219 </B><DD>Names the server machine on which to restart the specified
1220 processes.
1221 <P><DT><B><VAR>instances</VAR>
1222 </B><DD>Specifies each process to stop and immediately restart. Use the
1223 name assigned to the process at creation.
1224 </DL>
1225 </OL>
1226 <HR><H2><A NAME="HDRWQ225" HREF="auagd002.htm#ToC_196">Setting the BOS Server&#39;s Restart Times</A></H2>
1227 <A NAME="IDX6392"></A>
1228 <A NAME="IDX6393"></A>
1229 <A NAME="IDX6394"></A>
1230 <A NAME="IDX6395"></A>
1231 <A NAME="IDX6396"></A>
1232 <A NAME="IDX6397"></A>
1233 <A NAME="IDX6398"></A>
1234 <A NAME="IDX6399"></A>
1235 <A NAME="IDX6400"></A>
1236 <P>The BOS Server by default restarts once a week, and the new instance
1237 restarts all processes marked with status flag <TT>Run</TT> in the local
1238 <B>/usr/afs/local/BosConfig</B> file (this is equivalent to issuing the
1239 <B>bos restart</B> command with the <B>-bosserver</B> flag).
1240 The default restart time is Sunday at 4&#58;00 a.m. The weekly
1241 restart is designed to minimize <I>core leaks</I>, which can develop as a
1242 process continues to allocate virtual memory but does not free it
1243 again. When the memory is completely exhausted, the machine can no
1244 longer function correctly.
1245 <P>The BOS Server also by default checks once a day for any newly installed
1246 binary files. If it finds that the modification time stamp on a
1247 process&#39;s binary file in the <B>/usr/afs/bin</B> directory is more
1248 recent than the time at which the process last started, it restarts the
1249 process so that a new instance starts using the new binary file. The
1250 default binary-checking time is 5&#58;00 a.m.
1251 <P>Because restarts can cause outages during which the file system is
1252 inaccessible, the default times for restarts are in the early morning when
1253 usage is likely to be lowest. Restarting a database server process on
1254 any database server machine usually makes the entire system unavailable to
1255 everyone for a brief time, whereas restarting other types of processes
1256 inconveniences only users interacting with that process on that
1257 machine. The longest outages typically result from restarting the
1258 <B>fs</B> process, because the File Server must reattach all
1259 volumes.
1260 <A NAME="IDX6401"></A>
1261 <A NAME="IDX6402"></A>
1262 <A NAME="IDX6403"></A>
1263 <P>The <B>BosConfig</B> file on each file server machine records the two
1264 restart times. To display the current setting, issue the <B>bos
1265 getrestart</B> command. To reset a time, use the <B>bos
1266 setrestart</B> command.
1267 <A NAME="IDX6404"></A>
1268 <A NAME="IDX6405"></A>
1269 <A NAME="IDX6406"></A>
1270 <P><H3><A NAME="Header_197" HREF="auagd002.htm#ToC_197">To display the BOS Server restart times</A></H3>
1271 <OL TYPE=1>
1272 <P><LI>Issue the <B>bos getrestart</B> command to display the automatic
1273 restart times.
1274 <PRE>   % <B>bos getrestart</B> &lt;<VAR>machine&nbsp;name</VAR>>
1275 </PRE>
1276 <P>where
1277 <DL>
1278 <P><DT><B>getr
1279 </B><DD>Is the shortest acceptable abbreviation of <B>getrestart</B>.
1280 <P><DT><B><VAR>machine name</VAR>
1281 </B><DD>Specifies the server machine for which to display the restart
1282 times.
1283 </DL>
1284 </OL>
1285 <A NAME="IDX6407"></A>
1286 <A NAME="IDX6408"></A>
1287 <A NAME="IDX6409"></A>
1288 <P><H3><A NAME="HDRWQ226" HREF="auagd002.htm#ToC_198">To set the general or binary restart time</A></H3>
1289 <OL TYPE=1>
1290 <P><LI>Verify that you are listed in the <B>/usr/afs/etc/UserList</B>
1291 file. If necessary, issue the <B>bos listusers</B> command, which
1292 is fully described in <A HREF="auagd021.htm#HDRWQ815">To display the users in the UserList file</A>.
1293 <PRE>   % <B>bos listusers</B> &lt;<VAR>machine name</VAR>>
1294 </PRE>
1295 <P><LI>Issue the <B>bos setrestart</B> command with the <B>-general</B>
1296 flag to set the general restart time or the <B>-newbinary</B> flag to set
1297 the binary restart time. The command accepts only one of the flags at a
1298 time.
1299 <PRE>   % <B>bos setrestart</B> &lt;<VAR>machine&nbsp;name</VAR>> "&lt;<VAR>time&nbsp;to&nbsp;restart&nbsp;server</VAR>>" [<B>-general</B>]  [<B>-newbinary</B>]
1300 </PRE>
1301 <P>where
1302 <DL>
1303 <P><DT><B>setr
1304 </B><DD>Is the shortest acceptable abbreviation of <B>setrestart</B>.
1305 <P><DT><B><VAR>machine name</VAR>
1306 </B><DD>Specifies the server machine.
1307 <P><DT><B><VAR>time to restart server</VAR>
1308 </B><DD>Sets when the BOS Server restarts itself (if combined with the
1309 <B>-general</B> flag) or any process with a new binary file (if combined
1310 with the <B>-newbinary</B> flag). Provide one of the following
1311 types of values&#58;
1312 <UL>
1313 <P><LI>The string <B>never</B>, which directs the BOS Server never to perform
1314 the indicated type of restart.
1315 <P><LI>A time of day (the conventional type of value for the binary restart
1316 time). Separate the hours and minutes with a colon
1317 (<I>hh</I>&#58;<I>MM</I>), and use either 24-hour format, or a value
1318 in the range from <B>1&#58;00</B> through <B>12&#58;59</B> with
1319 the addition of <B>am</B> or <B>pm</B>. For example, both
1320 <B>14&#58;30</B> and <B>"2&#58;30 pm"</B> indicate 2&#58;30 in
1321 the afternoon. Surround this parameter with double quotes (<B>"
1322 "</B>) if it contains a space.
1323 <P><LI>A day of the week and time of day, separated by a space and surrounded
1324 with double quotes (<B>" "</B>). This is the conventional type of
1325 value for the general restart. For the day, provide either the whole
1326 name or the first three letters, all in lowercase letters (<B>sunday</B>
1327 or <B>sun</B>, <B>thursday</B> or <B>thu</B>, and so on).
1328 For the time, use the same format as when specifying the time alone.
1329 </UL>
1330 <P>If desired, precede a time or day and time definition with the string
1331 <B>every</B> or <B>at</B>. These words do not change the
1332 meaning, but possibly make the output of the <B>bos getrestart</B> command
1333 easier to understand.
1334 <TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">If the specified time is within one hour of the current time, the BOS Server
1335 does not perform the restart until the next eligible time (the next day for a
1336 time or next week for a day and time).
1337 </TD></TR></TABLE>
1338 <P><DT><B>-general
1339 </B><DD>Sets the general restart time when the BOS Server restarts itself.
1340 <P><DT><B>-newbinary
1341 </B><DD>Sets the restart time for processes with new binary files.
1342 </DL>
1343 </OL>
1344 <HR><H2><A NAME="HDRWQ227" HREF="auagd002.htm#ToC_199">Displaying Server Process Log Files</A></H2>
1345 <A NAME="IDX6410"></A>
1346 <A NAME="IDX6411"></A>
1347 <A NAME="IDX6412"></A>
1348 <A NAME="IDX6413"></A>
1349 <A NAME="IDX6414"></A>
1350 <A NAME="IDX6415"></A>
1351 <A NAME="IDX6416"></A>
1352 <A NAME="IDX6417"></A>
1353 <A NAME="IDX6418"></A>
1354 <A NAME="IDX6419"></A>
1355 <A NAME="IDX6420"></A>
1356 <A NAME="IDX6421"></A>
1357 <A NAME="IDX6422"></A>
1358 <A NAME="IDX6423"></A>
1359 <A NAME="IDX6424"></A>
1360 <A NAME="IDX6425"></A>
1361 <A NAME="IDX6426"></A>
1362 <A NAME="IDX6427"></A>
1363 <P>The <B>/usr/afs/logs</B> directory on each file server machine contains
1364 log files that detail interesting events that occur during normal operation of
1365 some AFS server processes. The self-explanatory information in the log
1366 files can help you evaluate process failures and other problems. To
1367 display a log file remotely, issue the <B>bos getlog</B> command.
1368 You can also establish a connection to the server machine and use a text
1369 editor or other file display program (such as the <B>cat</B>
1370 command).
1371 <TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">Log files can grow unmanageably large if you do not periodically shutdown and
1372 restart the database server processes (for example, if you disable the general
1373 restart time). In this case it is a good policy periodically to issue
1374 the UNIX <B>rm</B> command to delete the current log file. The
1375 server process automatically creates a new one as needed.
1376 </TD></TR></TABLE>
1377 <A NAME="IDX6428"></A>
1378 <A NAME="IDX6429"></A>
1379 <P><H3><A NAME="Header_200" HREF="auagd002.htm#ToC_200">To examine a server process log file</A></H3>
1380 <OL TYPE=1>
1381 <P><LI>Verify that you are listed in the <B>/usr/afs/etc/UserList</B>
1382 file. If necessary, issue the <B>bos listusers</B> command, which
1383 is fully described in <A HREF="auagd021.htm#HDRWQ815">To display the users in the UserList file</A>.
1384 <PRE>   % <B>bos listusers</B> &lt;<VAR>machine name</VAR>>
1385 </PRE>
1386 <P><LI>Issue the <B>bos getlog</B> command to display a log file.
1387 <PRE>   % <B>bos getlog</B>  &lt;<VAR>machine&nbsp;name</VAR>>  &lt;<VAR>log&nbsp;file&nbsp;to&nbsp;examine</VAR>>
1388 </PRE>
1389 <P>where
1390 <DL>
1391 <P><DT><B>getl
1392 </B><DD>Is the shortest acceptable abbreviation of <B>getlog</B>.
1393 <P><DT><B><VAR>machine name</VAR>
1394 </B><DD>Specifies the server machine from which to display the log file.
1395 <P><DT><B><VAR>log file to examine</VAR>
1396 </B><DD>Names the log file to be displayed. Provide one of the following
1397 file names to display the indicated log file from the <B>/usr/afs/logs</B>
1398 directory.
1399 <UL>
1400 <P><LI><B>AuthLog</B> for the Authentication Server log file
1401 <P><LI><B>BackupLog</B> for the Backup Server log file
1402 <P><LI><B>BosLog</B> for the BOS Server log file
1403 <P><LI><B>FileLog</B> for the File Server log file
1404 <P><LI><B>SalvageLog</B> for the Salvager log file
1405 <P><LI><B>VLLog</B> for the Volume Location (VL) Server log file
1406 <P><LI><B>VolserLog</B> for the Volume Server log file
1407 </UL>
1408 <P>You can provide a full or relative pathname to display a file from another
1409 directory. Relative pathnames are interpreted relative to the
1410 <B>/usr/afs/logs</B> directory.
1411 </DL>
1412 </OL>
1413 <HR><P ALIGN="center"> <A HREF="../index.htm"><IMG SRC="../books.gif" BORDER="0" ALT="[Return to Library]"></A> <A HREF="auagd002.htm#ToC"><IMG SRC="../toc.gif" BORDER="0" ALT="[Contents]"></A> <A HREF="auagd008.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="auagd010.htm"><IMG SRC="../next.gif" BORDER="0" ALT="[Next Topic]"></A> <A HREF="auagd026.htm#HDRINDEX"><IMG SRC="../index.gif" BORDER="0" ALT="[Index]"></A> <P>
1414 <!-- Begin Footer Records  ========================================== -->
1415 <P><HR><B>
1416 <br>&#169; <A HREF="http://www.ibm.com/">IBM Corporation 2000.</A>  All Rights Reserved
1417 </B>
1418 <!-- End Footer Records  ============================================ -->
1419 <A NAME="Bot_Of_Page"></A>
1420 </BODY></HTML>