doc/xml/AdminGuide/auagd009.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <chapter id="HDRWQ142">
   3   <title>Monitoring and Controlling Server Processes</title>
   4
   5   <para>
   6   <indexterm>
   7     <primary>monitoring</primary>
   8
   9     <secondary>server processes</secondary>
  10   </indexterm>
  11
  12   <indexterm>
  13     <primary>BOS Server</primary>
  14
  15     <secondary>monitoring server processes</secondary>
  16   </indexterm>
  17
  18   One of your most important responsibilities as a system administrator is ensuring that the processes on file server machines
  19   are running correctly. The BOS Server, which runs on every file server machine, relieves you of much of the responsibility by
  20   constantly monitoring the other AFS server processes on its machine. It can automatically restart processes that have failed,
  21   ordering the restarts to take interdependencies into account.</para>
  22
  23   <para>Because different file server machines run different combinations of processes, you must define which processes the BOS
  24   Server on each file server machine is to monitor (to learn how, see <link linkend="HDRWQ154">Controlling and Checking Process
  25   Status</link>).</para>
  26
  27   <para>It is sometimes necessary to take direct control of server process status before performing routine maintenance or
  28   correcting problems that the BOS Server cannot correct (such as problems with database replication or mutual authentication). At
  29   those times, you control process status through the BOS Server by issuing <emphasis role="bold">bos</emphasis> commands.</para>
  30
  31   <sect1 id="HDRWQ143">
  32     <title>Summary of Instructions</title>
  33
  34     <para>This chapter explains how to perform the following tasks by using the indicated commands:</para>
  35
  36     <informaltable frame="none">
  37       <tgroup cols="2">
  38         <tbody>
  39           <row>
  40             <entry>Examine process status</entry>
  41
  42             <entry><emphasis role="bold">bos status</emphasis></entry>
  43           </row>
  44
  45           <row>
  46             <entry>Examine information from the <emphasis role="bold">BosConfig file</emphasis> file</entry>
  47
  48             <entry><emphasis role="bold">bos status</emphasis> with <emphasis role="bold">-long</emphasis> flag</entry>
  49           </row>
  50
  51           <row>
  52             <entry>Create a process instance</entry>
  53
  54             <entry><emphasis role="bold">bos create</emphasis></entry>
  55           </row>
  56
  57           <row>
  58             <entry>Stop a process</entry>
  59
  60             <entry><emphasis role="bold">bos stop</emphasis></entry>
  61           </row>
  62
  63           <row>
  64             <entry>Start a stopped process</entry>
  65
  66             <entry><emphasis role="bold">bos start</emphasis></entry>
  67           </row>
  68
  69           <row>
  70             <entry>Stop a process temporarily</entry>
  71
  72             <entry><emphasis role="bold">bos shutdown</emphasis></entry>
  73           </row>
  74
  75           <row>
  76             <entry>Start a temporarily stopped process</entry>
  77
  78             <entry><emphasis role="bold">bos startup</emphasis></entry>
  79           </row>
  80
  81           <row>
  82             <entry>Stop and immediately restart a process</entry>
  83
  84             <entry><emphasis role="bold">bos restart</emphasis></entry>
  85           </row>
  86
  87           <row>
  88             <entry>Stop and immediately restart all processes</entry>
  89
  90             <entry><emphasis role="bold">bos restart</emphasis> with <emphasis role="bold">-bosserver</emphasis> flag</entry>
  91           </row>
  92
  93           <row>
  94             <entry>Examine BOS Server's restart times</entry>
  95
  96             <entry><emphasis role="bold">bos getrestart</emphasis></entry>
  97           </row>
  98
  99           <row>
 100             <entry>Set BOS Server's restart times</entry>
 101
 102             <entry><emphasis role="bold">bos setrestart</emphasis></entry>
 103           </row>
 104
 105           <row>
 106             <entry>Examine a log file</entry>
 107
 108             <entry><emphasis role="bold">bos getlog</emphasis></entry>
 109           </row>
 110
 111           <row>
 112             <entry>Execute a command remotely</entry>
 113
 114             <entry><emphasis role="bold">bos exec</emphasis></entry>
 115           </row>
 116         </tbody>
 117       </tgroup>
 118     </informaltable>
 119   </sect1>
 120
 121   <sect1 id="HDRWQ145">
 122     <title>Brief Descriptions of the AFS Server Processes</title>
 123
 124     <para>This section briefly describes the different server processes that can run on an AFS server machine. In cells with
 125     multiple server machines, not all processes necessarily run on all machines.</para>
 126
 127     <indexterm>
 128       <primary>server process</primary>
 129
 130       <secondary>different names for</secondary>
 131     </indexterm>
 132
 133     <para>An AFS server process is referred to in one of three ways, depending on the context: <itemizedlist>
 134         <listitem>
 135           <para>The output from the <emphasis role="bold">bos status</emphasis> command refers to a process by the name assigned
 136           when the <emphasis role="bold">bos create</emphasis> command creates its entry in the <emphasis
 137           role="bold">/usr/afs/local/BosConfig</emphasis> file. The name can differ from machine to machine, but it is easiest to
 138           maintain the cell if you assign the same name on all machines. The <emphasis>OpenAFS Quick Beginnings</emphasis> and the
 139           reference page for the <emphasis role="bold">bos create</emphasis> command list the conventional names. Examples are
 140           <emphasis role="bold">bosserver</emphasis>, <emphasis role="bold">kaserver</emphasis>, and <emphasis
 141           role="bold">vlserver</emphasis>.</para>
 142         </listitem>
 143
 144         <listitem>
 145           <para>The process listing produced by the standard <emphasis role="bold">ps</emphasis> command generally matches the
 146           process's binary file. Examples of process binary files are <emphasis role="bold">/usr/afs/bin/bosserver</emphasis>,
 147           <emphasis role="bold">/usr/afs/bin/kaserver</emphasis>, and <emphasis role="bold">/usr/afs/bin/vlserver</emphasis>.</para>
 148         </listitem>
 149
 150         <listitem>
 151           <para>In most contexts, including most references in the documentation, a process is referred to as (for example) the
 152           <emphasis role="bold">Basic OverSeer (BOS) Server</emphasis>, the <emphasis role="bold">Authentication Server</emphasis>,
 153           or the <emphasis role="bold">Volume Location Server</emphasis>.</para>
 154         </listitem>
 155       </itemizedlist></para>
 156
 157     <para>The following sections specify each name for the process as well as some of the administrative tasks in which you use the
 158     process. For a more general description of the servers, see <link linkend="HDRWQ17">AFS Server Processes and the Cache
 159     Manager</link>.</para>
 160
 161     <sect2 id="HDRWQ146">
 162       <title>The bosserver Process: the Basic OverSeer Server</title>
 163
 164       <indexterm>
 165         <primary>BOS Server</primary>
 166
 167         <secondary>as bosserver process</secondary>
 168       </indexterm>
 169
 170       <indexterm>
 171         <primary>server process</primary>
 172
 173         <secondary>bosserver</secondary>
 174       </indexterm>
 175
 176       <para>The <emphasis role="bold">bosserver</emphasis> process, which runs on every AFS server machine, is the Basic OverSeer
 177       (BOS) Server responsible for monitoring the other AFS server processes running on its machine. If a process fails, the BOS
 178       Server can restart it automatically, without human intervention. It takes interdependencies into account when restarting a
 179       process that has multiple component processes (such as the <emphasis role="bold">fs</emphasis> process described in <link
 180       linkend="HDRWQ148">The fs Collection of Processes: the File Server, Volume Server and Salvager</link>).</para>
 181
 182       <indexterm>
 183         <primary>usr/afs/bin/bosserver</primary>
 184       </indexterm>
 185
 186       <para>Because the BOS Server does not monitor or restart itself, it does not appear in the output from the <emphasis
 187       role="bold">bos status</emphasis> command. It appears in the <emphasis role="bold">ps</emphasis> command's output as
 188       <computeroutput>/usr/afs/bin/bosserver</computeroutput>.</para>
 189
 190       <indexterm>
 191         <primary>BOS Server</primary>
 192
 193         <secondary>when to contact</secondary>
 194       </indexterm>
 195
 196       <indexterm>
 197         <primary>contacting processes</primary>
 198
 199         <secondary>BOS Server</secondary>
 200       </indexterm>
 201
 202       <indexterm>
 203         <primary>bos commands</primary>
 204
 205         <secondary>summary of functions</secondary>
 206       </indexterm>
 207
 208       <para>As a system administrator, you contact the BOS Server when you issue <emphasis role="bold">bos</emphasis> commands to
 209       perform the following kinds of tasks. <itemizedlist>
 210           <listitem>
 211             <para>Defining the processes for the BOS Server to monitor by creating entries in the <emphasis
 212             role="bold">/usr/afs/local/BosConfig</emphasis> file as described in <link linkend="HDRWQ154">Controlling and Checking
 213             Process Status</link></para>
 214           </listitem>
 215
 216           <listitem>
 217             <para>Stopping and starting processes on the file server machines according to subsequent instructions in this
 218             chapter</para>
 219           </listitem>
 220
 221           <listitem>
 222             <para>Defining your cell's database server machines in the <emphasis role="bold">/usr/afs/etc/CellServDB</emphasis> file
 223             as described in <link linkend="HDRWQ118">Maintaining the Server CellServDB File</link></para>
 224           </listitem>
 225
 226           <listitem>
 227             <para>Defining AFS server encryption keys in the <emphasis role="bold">/usr/afs/etc/KeyFile</emphasis> file as described
 228             in <link linkend="HDRWQ355">Managing Server Encryption Keys</link>.</para>
 229           </listitem>
 230
 231           <listitem>
 232             <para>Granting system administrator privileges with respect to BOS Server, Volume Server, and Backup Server operations,
 233             by adding a user to the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file as described in <link
 234             linkend="HDRWQ592">Administering the UserList File</link></para>
 235           </listitem>
 236
 237           <listitem>
 238             <para>Setting authorization checking requirements on a server machine as described in <link linkend="HDRWQ123">Managing
 239             Authentication and Authorization Requirements</link></para>
 240           </listitem>
 241         </itemizedlist></para>
 242     </sect2>
 243
 244     <sect2 id="HDRWQ147">
 245       <title>The buserver Process: the Backup Server</title>
 246
 247       <indexterm>
 248         <primary>Backup Server</primary>
 249
 250         <secondary>as buserver process</secondary>
 251       </indexterm>
 252
 253       <indexterm>
 254         <primary>server process</primary>
 255
 256         <secondary>buserver</secondary>
 257       </indexterm>
 258
 259       <para>The <emphasis role="bold">buserver</emphasis> process, which runs on database server machines, is the Backup Server. It
 260       maintains information about Backup System configuration and operations in the Backup Database.</para>
 261
 262       <para>The process appears as <computeroutput>buserver</computeroutput> in the <emphasis role="bold">bos status</emphasis>
 263       command's output, if the conventional name is assigned. It appears in the <emphasis role="bold">ps</emphasis> command's output
 264       as <computeroutput>/usr/afs/bin/buserver</computeroutput>.</para>
 265
 266       <indexterm>
 267         <primary>Backup Server</primary>
 268
 269         <secondary>when to contact</secondary>
 270       </indexterm>
 271
 272       <indexterm>
 273         <primary>contacting processes</primary>
 274
 275         <secondary>Backup Server</secondary>
 276       </indexterm>
 277
 278       <para>As a system administrator, you contact the Backup Server when you issue any <emphasis role="bold">backup</emphasis>
 279       command that manipulates information in the Backup Database, including those that change Backup System configuration
 280       information, that dump data from volumes to permanent storage, or that restore data to AFS. See <link
 281       linkend="HDRWQ248">Configuring the AFS Backup System</link> and <link linkend="HDRWQ283">Backing Up and Restoring AFS
 282       Data</link>.</para>
 283     </sect2>
 284
 285     <sect2 id="HDRWQ148">
 286       <title>The fs Collection of Processes: the File Server, Volume Server and Salvager</title>
 287
 288       <indexterm>
 289         <primary>fs process</primary>
 290       </indexterm>
 291
 292       <indexterm>
 293         <primary>server process</primary>
 294
 295         <secondary>fs</secondary>
 296       </indexterm>
 297
 298       <para>The <emphasis role="bold">fs</emphasis> process, which runs on every file server machine, combines three component
 299       processes: File Server, Volume Server and Salvager. The three components perform independent functions, but are controlled as
 300       a single process for the following reasons. <itemizedlist>
 301           <listitem>
 302             <para>They all operate on the same data, namely files and directories stored in AFS volumes. Combining them as a single
 303             process enables them to coordinate their actions, never attempting simultaneous operations on the same data that can
 304             possibly corrupt it.</para>
 305           </listitem>
 306
 307           <listitem>
 308             <para>It enables the BOS Server to stop and restart the processes in the required order. When the File Server fails, the
 309             BOS Server stops the Volume Server and runs the Salvager to correct any corruption that resulted from the failure. (The
 310             Salvager runs only in this special circumstance or when you invoke it yourself by issuing the <emphasis role="bold">bos
 311             salvage</emphasis> command as instructed in <link linkend="HDRWQ232">Salvaging Volumes</link>.) If only the Volume
 312             Server fails, the BOS Server can restart it without affecting the File Server or Salvager.</para>
 313           </listitem>
 314         </itemizedlist></para>
 315
 316       <para>The File Server component handles AFS data at the level of files and directories, manipulating file system elements as
 317       requested by application programs and the standard operating system commands. Its main duty is to deliver requested files to
 318       client machines and store them again on the server machine when the client is finished. It also maintains status and
 319       protection information about each file and directory. It runs continuously during normal operation.</para>
 320
 321       <indexterm>
 322         <primary>File Server</primary>
 323
 324         <secondary>as part of fs process</secondary>
 325       </indexterm>
 326
 327       <para>The Volume Server component handles AFS data at the level of complete volumes rather than files and directories. In
 328       response to <emphasis role="bold">vos</emphasis> commands, it creates, removes, moves, dumps and restores entire volumes,
 329       among other actions. It runs continuously during normal operation.</para>
 330
 331       <indexterm>
 332         <primary>Volume Server</primary>
 333
 334         <secondary>as part of fs process</secondary>
 335       </indexterm>
 336
 337       <para>The Salvager component runs only after the failure of one of the other two processes. It checks the file system for
 338       internal consistency and repairs any errors it finds.</para>
 339
 340       <indexterm>
 341         <primary>Salvager</primary>
 342
 343         <secondary>as part of fs process</secondary>
 344       </indexterm>
 345
 346       <indexterm>
 347         <primary>file system</primary>
 348
 349         <secondary>salvager</secondary>
 350
 351         <see>Salvager</see>
 352       </indexterm>
 353
 354       <para>The process appears as <computeroutput>fs</computeroutput> in the <emphasis role="bold">bos status</emphasis> command's
 355       output, if the conventional name is assigned. An auxiliary message reports the status of the File Server or Salvager
 356       component. See <link linkend="HDRWQ158">Displaying Process Status and Information from the BosConfig File</link>.</para>
 357
 358       <para>The component processes of the <emphasis role="bold">fs</emphasis> process appear individually in the <emphasis
 359       role="bold">ps</emphasis> command's output, as follows. There is no entry for the <computeroutput>fs</computeroutput> process
 360       itself. <itemizedlist>
 361           <listitem>
 362             <para><computeroutput>/usr/afs/bin/fileserver</computeroutput></para>
 363           </listitem>
 364
 365           <listitem>
 366             <para><computeroutput>/usr/afs/bin/volserver</computeroutput></para>
 367           </listitem>
 368
 369           <listitem>
 370             <para><computeroutput>/usr/afs/bin/salvager</computeroutput></para>
 371           </listitem>
 372         </itemizedlist></para>
 373
 374       <indexterm>
 375         <primary>File Server</primary>
 376
 377         <secondary>when to contact</secondary>
 378       </indexterm>
 379
 380       <indexterm>
 381         <primary>contacting processes</primary>
 382
 383         <secondary>File Server</secondary>
 384       </indexterm>
 385
 386       <para>The Cache Manager contacts the File Server component on your behalf whenever you access data or status information in an
 387       AFS file or directory or issue file manipulation commands such as the UNIX <emphasis role="bold">cp</emphasis> and <emphasis
 388       role="bold">ls</emphasis> commands. You can contact the File Server directly by issuing <emphasis role="bold">fs</emphasis>
 389       commands that perform the following functions <itemizedlist>
 390           <listitem>
 391             <para>Administering the ACL of any directory in the file system as described in <link linkend="HDRWQ562">Managing Access
 392             Control Lists</link></para>
 393           </listitem>
 394
 395           <listitem>
 396             <para>Installing new partitions for housing AFS volumes, in which case you must restart the <emphasis
 397             role="bold">fs</emphasis> process for it to recognize the new partition; for instructions, see <link
 398             linkend="HDRWQ130">Adding or Removing Disks and Partitions</link></para>
 399           </listitem>
 400
 401           <listitem>
 402             <para>Creating and deleting volume mount points in the AFS filespace as described in <link linkend="HDRWQ208">Mounting
 403             Volumes</link></para>
 404           </listitem>
 405
 406           <listitem>
 407             <para>Setting volume quota and displaying information about the space used and available in a volume or partition as
 408             described in <link linkend="HDRWQ234">Setting and Displaying Volume Quota and Current Size</link></para>
 409           </listitem>
 410         </itemizedlist></para>
 411
 412       <indexterm>
 413         <primary>Volume Server</primary>
 414
 415         <secondary>when to contact</secondary>
 416       </indexterm>
 417
 418       <indexterm>
 419         <primary>contacting processes</primary>
 420
 421         <secondary>Volume Server</secondary>
 422       </indexterm>
 423
 424       <para>You contact the Volume Server component when you issue <emphasis role="bold">vos</emphasis> commands that manipulate
 425       volumes in any way--creating, removing, replicating, moving, renaming, converting to different formats, and salvaging. For
 426       instructions, see <link linkend="HDRWQ174">Managing Volumes</link>.</para>
 427
 428       <para>The Salvager normally runs automatically in case of a failure. You can also start it with the <emphasis role="bold">bos
 429       salvage</emphasis> command as described in <link linkend="HDRWQ232">Salvaging Volumes</link>.</para>
 430
 431       <indexterm>
 432         <primary>Salvager</primary>
 433
 434         <secondary>when to contact</secondary>
 435       </indexterm>
 436
 437       <indexterm>
 438         <primary>contacting processes</primary>
 439
 440         <secondary>Salvager</secondary>
 441       </indexterm>
 442     </sect2>
 443
 444     <sect2 id="HDRWQ149">
 445       <title>The kaserver Process: the Authentication Server</title>
 446
 447       <indexterm>
 448         <primary>Authentication Server</primary>
 449
 450         <secondary>as kaserver process</secondary>
 451       </indexterm>
 452
 453       <indexterm>
 454         <primary>server process</primary>
 455
 456         <secondary>kaserver</secondary>
 457       </indexterm>
 458
 459       <para>The <emphasis role="bold">kaserver</emphasis> process, which runs on database server machines, is the Authentication
 460       Server responsible for several aspects of AFS security. It verifies AFS user identity by requiring a password. It maintains
 461       all AFS server encryption keys and user passwords in the Authentication Database. The Authentication Server's Ticket Granting
 462       Service (TGS) module creates the shared secrets that AFS client and server processes use when establishing secure
 463       connections.</para>
 464
 465       <para>The process appears as <computeroutput>kaserver</computeroutput> in the <emphasis role="bold">bos status</emphasis>
 466       command's output, if the conventional name is assigned. The <emphasis role="bold">ka</emphasis> string stands for
 467       <emphasis>Kerberos Authentication</emphasis>, reflecting the fact that AFS's authentication protocols are based on Kerberos,
 468       which was originally developed at the Massachusetts Institute of Technology's Project Athena.</para>
 469
 470       <para>It appears in the <emphasis role="bold">ps</emphasis> command's output as
 471       <computeroutput>/usr/afs/bin/kaserver</computeroutput>.</para>
 472
 473       <indexterm>
 474         <primary>Authentication Server</primary>
 475
 476         <secondary>when to contact</secondary>
 477       </indexterm>
 478
 479       <indexterm>
 480         <primary>contacting processes</primary>
 481
 482         <secondary>Authentication Server</secondary>
 483       </indexterm>
 484
 485       <para>As a system administrator, you contact the Authentication Server when you issue <emphasis role="bold">kas</emphasis>
 486       commands to perform the following kinds of tasks. <itemizedlist>
 487           <listitem>
 488             <para>Setting a user's password. Users normally change their own passwords, so you probably perform this task only
 489             creating a new user account as described in <link linkend="HDRWQ502">Creating AFS User Accounts</link> and <link
 490             linkend="HDRWQ516">Changing AFS Passwords</link>.</para>
 491           </listitem>
 492
 493           <listitem>
 494             <para>Setting the AFS server encryption key in the Authentication Database, which the TGS uses to seal server tickets;
 495             see <link linkend="HDRWQ355">Managing Server Encryption Keys</link>.</para>
 496           </listitem>
 497
 498           <listitem>
 499             <para>Granting or revoking system administrator privileges with respect to the Authentication Server as described in
 500             <link linkend="HDRWQ589">Granting Privilege for kas Commands: the ADMIN Flag</link>.</para>
 501           </listitem>
 502         </itemizedlist></para>
 503     </sect2>
 504
 505     <sect2 id="HDRWQ150">
 506       <title>The ptserver Process: the Protection Server</title>
 507
 508       <indexterm>
 509         <primary>Protection Server</primary>
 510
 511         <secondary>as ptserver process</secondary>
 512       </indexterm>
 513
 514       <indexterm>
 515         <primary>server process</primary>
 516
 517         <secondary>ptserver</secondary>
 518       </indexterm>
 519
 520       <para>The <emphasis role="bold">ptserver</emphasis> process, which runs on database server machines, is the Protection Server.
 521       Its main responsibility is maintaining the Protection Database which contains user, machine, and group entries. The Protection
 522       Server allocates AFS IDs and maintains the mapping between them and names. The File Server consults the Protection Server when
 523       verifying that a user is authorized to perform a requested action.</para>
 524
 525       <para>The process appears as <computeroutput>ptserver</computeroutput> in the <emphasis role="bold">bos status</emphasis>
 526       command's output, if the conventional name is assigned. It appears in the <emphasis role="bold">ps</emphasis> command's output
 527       as <computeroutput>/usr/afs/bin/ptserver</computeroutput>.</para>
 528
 529       <indexterm>
 530         <primary>Protection Server</primary>
 531
 532         <secondary>when to contact</secondary>
 533       </indexterm>
 534
 535       <indexterm>
 536         <primary>contacting processes</primary>
 537
 538         <secondary>Protection Server</secondary>
 539       </indexterm>
 540
 541       <para>As a system administrator, you contact the Protection Server when you issue <emphasis role="bold">pts</emphasis>
 542       commands to perform the following kinds of tasks. <itemizedlist>
 543           <listitem>
 544             <para>Creating a new user, machine, or group entry in the Protection Database as described in <link
 545             linkend="HDRWQ531">Administering the Protection Database</link></para>
 546           </listitem>
 547
 548           <listitem>
 549             <para>Adding or removing group members or otherwise manipulating Protection Database entries as described in <link
 550             linkend="HDRWQ531">Administering the Protection Database</link></para>
 551           </listitem>
 552
 553           <listitem>
 554             <para>Granting or revoking system administrator privilege by changing the membership of the <emphasis
 555             role="bold">system:administrators</emphasis> group as described in <link linkend="HDRWQ586">Administering the
 556             system:administrators Group</link></para>
 557           </listitem>
 558         </itemizedlist></para>
 559     </sect2>
 560
 561     <sect2 id="HDRWQ152">
 562       <title>The upserver and upclient Processes: the Update Server</title>
 563
 564       <indexterm>
 565         <primary>Update Server</primary>
 566
 567         <secondary>as upserver and upclient processes</secondary>
 568       </indexterm>
 569
 570       <indexterm>
 571         <primary>server process</primary>
 572
 573         <secondary>upserver</secondary>
 574       </indexterm>
 575
 576       <indexterm>
 577         <primary>server process</primary>
 578
 579         <secondary>upclient</secondary>
 580       </indexterm>
 581
 582       <para>The Update Server has two separate parts, each of which runs on a different type of server machine. The <emphasis
 583       role="bold">upserver</emphasis> process is the server portion of the Update Server. Its function depends on which edition of
 584       AFS you use: <itemizedlist>
 585           <listitem>
 586             <para>It runs on the binary distribution machine of each system
 587             type you use as a server machine, distributing the contents of each one's <emphasis role="bold">/usr/afs/bin</emphasis>
 588             directory to the other server machines of that type. This guarantees that all machines have the same version of AFS
 589             binaries. (For a list of the binaries, see <link linkend="HDRWQ84">Binaries in the /usr/afs/bin
 590             Directory</link>.)</para>
 591           </listitem>
 592
 593           <listitem>
 594             <para>It also runs on the cell's system control machine, distributing the
 595             contents of its <emphasis role="bold">/usr/afs/etc</emphasis> directory to all the other server machines in order to
 596             synchronize the configuration files stored in that directory. (For a list of the configuration files, see <link
 597             linkend="HDRWQ85">Common Configuration Files in the /usr/afs/etc Directory</link>.)</para>
 598           </listitem>
 599         </itemizedlist></para>
 600
 601       <para>The <emphasis role="bold">upclient</emphasis> process is the client portion of the Update Server, and like the server
 602       portion its function depends on the AFS edition in use. <itemizedlist>
 603           <listitem>
 604             <para>It runs on every server machine that is not a binary distribution machine, referencing the binary distribution
 605             machine of its system type as the source for updates to the binaries in the <emphasis
 606             role="bold">/usr/afs/bin</emphasis> directory. The conventional process name to assign is <emphasis
 607             role="bold">upclientbin</emphasis>.</para>
 608           </listitem>
 609
 610           <listitem>
 611             <para>Another instance of the process runs on every server machine except
 612             the system control machine. It references the system control machine as the source for updates to the common
 613             configuration files in the <emphasis role="bold">/usr/afs/etc</emphasis> directory. The conventional process name to
 614             assign is <emphasis role="bold">upclientetc</emphasis>.</para>
 615           </listitem>
 616         </itemizedlist></para>
 617
 618       <para>In output from the <emphasis role="bold">bos status</emphasis> command, the server portion appears as
 619       <computeroutput>upserver</computeroutput> and the client portions as <computeroutput>upclientbin</computeroutput> and
 620       <computeroutput>upclientetc</computeroutput>, if the conventional names are assigned. In the output from the <emphasis
 621       role="bold">ps</emphasis> command, the server portion appears as <computeroutput>/usr/afs/bin/upserver</computeroutput> and
 622       the client portions as /usr/afs/bin/upclient.</para>
 623
 624       <indexterm>
 625         <primary>Update Server</primary>
 626
 627         <secondary>when to contact</secondary>
 628       </indexterm>
 629
 630       <indexterm>
 631         <primary>contacting processes</primary>
 632
 633         <secondary>Update Server</secondary>
 634       </indexterm>
 635
 636       <para>You do not contact the Update Server directly once you have installed it. It operates automatically whenever you use
 637       <emphasis role="bold">bos</emphasis> commands to change the files that it distributes.</para>
 638     </sect2>
 639
 640     <sect2 id="HDRWQ153">
 641       <title>The vlserver Process: the Volume Location Server</title>
 642
 643       <indexterm>
 644         <primary>VL Server</primary>
 645
 646         <secondary>as vlserver process</secondary>
 647       </indexterm>
 648
 649       <indexterm>
 650         <primary>server process</primary>
 651
 652         <secondary>vlserver</secondary>
 653       </indexterm>
 654
 655       <para>The <emphasis role="bold">vlserver</emphasis> process, which runs on database server machines, is the Volume Location
 656       (VL) Server that automatically tracks which file server machines house each volume, making its location transparent to client
 657       applications.</para>
 658
 659       <para>The process appears as <computeroutput>vlserver</computeroutput> in the <emphasis role="bold">bos status</emphasis>
 660       command's output, if the conventional name is assigned. It appears in the <emphasis role="bold">ps</emphasis> command's output
 661       as <computeroutput>/usr/afs/bin/vlserver</computeroutput>.</para>
 662
 663       <indexterm>
 664         <primary>VL Server</primary>
 665
 666         <secondary>when to contact</secondary>
 667       </indexterm>
 668
 669       <indexterm>
 670         <primary>contacting processes</primary>
 671
 672         <secondary>VL Server</secondary>
 673       </indexterm>
 674
 675       <indexterm>
 676         <primary>vos commands</primary>
 677
 678         <secondary>summary of functions</secondary>
 679       </indexterm>
 680
 681       <para>As a system administrator, you contact the VL Server when you issue any <emphasis role="bold">vos</emphasis> command
 682       that changes the status of a volume (it records the status changes in the VLDB).</para>
 683     </sect2>
 684   </sect1>
 685
 686   <sect1 id="HDRWQ154">
 687     <title>Controlling and Checking Process Status</title>
 688
 689     <para>To define the AFS server processes that run on a server machine, use the <emphasis role="bold">bos create</emphasis>
 690     command to create entries for them in the local <emphasis role="bold">/usr/afs/local/BosConfig</emphasis> file. The BOS Server
 691     monitors the processes listed in the <emphasis role="bold">BosConfig</emphasis> file that are marked with the
 692     <computeroutput>Run</computeroutput> status flag, and automatically attempts to restart them if they fail. After creating
 693     process entries, you use other commands from the <emphasis role="bold">bos</emphasis> suite to stop and start processes or
 694     change the status flag as desired.</para>
 695
 696     <para>Never edit the <emphasis role="bold">BosConfig</emphasis> file directly rather than using <emphasis
 697     role="bold">bos</emphasis> commands. Similarly, it is not a good practice to run server processes without listing them in the
 698     <emphasis role="bold">BosConfig</emphasis> file, or to stop them using process termination commands such as the UNIX <emphasis
 699     role="bold">kill</emphasis> command.</para>
 700
 701     <sect2 id="Header_176">
 702       <title>The Information in the BosConfig File</title>
 703
 704       <indexterm>
 705         <primary>BosConfig file</primary>
 706
 707         <secondary>information</secondary>
 708       </indexterm>
 709
 710       <indexterm>
 711         <primary>files</primary>
 712
 713         <secondary>BosConfig</secondary>
 714       </indexterm>
 715
 716       <para>A process's entry in the <emphasis role="bold">BosConfig</emphasis> file includes the following information:
 717       <itemizedlist>
 718           <listitem>
 719             <para>The process's name. The recommended conventional names are defined in both the <emphasis>OpenAFS Quick
 720             Beginnings</emphasis> and <link linkend="HDRWQ161">Creating and Removing Processes</link>. The name of a simple process
 721             usually matches the name of its binary file (for example, <emphasis role="bold">ptserver</emphasis> for the Protection
 722             Server).</para>
 723           </listitem>
 724
 725           <listitem>
 726             <para>Its type, which is one of the following: <variablelist>
 727                 <indexterm>
 728                   <primary>simple-type server process</primary>
 729
 730                   <secondary>defined</secondary>
 731                 </indexterm>
 732
 733                 <indexterm>
 734                   <primary>server process</primary>
 735
 736                   <secondary>simple type, defined</secondary>
 737                 </indexterm>
 738
 739                 <varlistentry>
 740                   <term><emphasis role="bold">simple</emphasis></term>
 741
 742                   <listitem>
 743                     <para>A process that runs independently of any other on the server machine. If several simple processes fail at
 744                     the same time, the BOS Server can restart them in any order. All standard AFS processes except the <emphasis
 745                     role="bold">fs</emphasis> process are simple.</para>
 746                   </listitem>
 747                 </varlistentry>
 748
 749                 <varlistentry>
 750                   <term><emphasis role="bold">fs</emphasis></term>
 751
 752                   <listitem>
 753                     <indexterm>
 754                       <primary>fs-type server process</primary>
 755
 756                       <secondary>defined</secondary>
 757                     </indexterm>
 758
 759                     <indexterm>
 760                       <primary>server process</primary>
 761
 762                       <secondary>fs type, defined</secondary>
 763                     </indexterm>
 764
 765                     <indexterm>
 766                       <primary>File Server</primary>
 767
 768                       <secondary>as part of fs process</secondary>
 769                     </indexterm>
 770
 771                     <indexterm>
 772                       <primary>Volume Server</primary>
 773
 774                       <secondary>as part of fs process</secondary>
 775                     </indexterm>
 776
 777                     <indexterm>
 778                       <primary>Salvager</primary>
 779
 780                       <secondary>as part of fs process</secondary>
 781                     </indexterm>
 782
 783                     <para>A process type reserved for the server process for which the conventional name is also <emphasis
 784                     role="bold">fs</emphasis>. This process combines three components: the File Server, the Volume Server, and the
 785                     Salvager.</para>
 786
 787                     <indexterm>
 788                       <primary>cron-type server process</primary>
 789
 790                       <secondary>defined</secondary>
 791                     </indexterm>
 792
 793                     <indexterm>
 794                       <primary>server process</primary>
 795
 796                       <secondary>cron type, defined</secondary>
 797                     </indexterm>
 798                   </listitem>
 799                 </varlistentry>
 800
 801                 <varlistentry>
 802                   <term><emphasis role="bold">cron</emphasis></term>
 803
 804                   <listitem>
 805                     <para>A process that runs at a defined time rather than continuously. There are no standard processes of this
 806                     type.</para>
 807                   </listitem>
 808                 </varlistentry>
 809               </variablelist></para>
 810
 811             <indexterm>
 812               <primary>status flag for process in BosConfig file</primary>
 813
 814               <secondary>Run and Not Run, meaning of</secondary>
 815             </indexterm>
 816
 817             <indexterm>
 818               <primary>Run status flag in BosConfig file</primary>
 819
 820               <secondary>defined</secondary>
 821             </indexterm>
 822
 823             <indexterm>
 824               <primary>NotRun status flag in BosConfig file</primary>
 825
 826               <secondary>defined</secondary>
 827             </indexterm>
 828
 829             <indexterm>
 830               <primary>process</primary>
 831
 832               <secondary>status flag in BosConfig file</secondary>
 833             </indexterm>
 834           </listitem>
 835
 836           <listitem>
 837             <para>Its status flag, which tells the BOS Server whether it performs the following two actions with respect to the
 838             process: <itemizedlist>
 839                 <listitem>
 840                   <para>Start the process during BOS Server initialization</para>
 841                 </listitem>
 842
 843                 <listitem>
 844                   <para>Restart the process if it (the process) fails</para>
 845                 </listitem>
 846               </itemizedlist></para>
 847
 848             <para>The two possible values are <computeroutput>Run</computeroutput> (which directs the BOS Server to perform these
 849             actions) and <computeroutput>NotRun</computeroutput> (which directs the BOS Server to ignore the process). The BOS
 850             Server itself never changes the setting of this flag, even if the process fails repeatedly. Also, this flag is for
 851             internal use only; it does not appear in the <emphasis role="bold">bos status</emphasis> command's output.</para>
 852           </listitem>
 853
 854           <listitem>
 855             <para>Its command parameters, which are the commands that the BOS Server runs to start the process. <itemizedlist>
 856                 <indexterm>
 857                   <primary>command parameters</primary>
 858
 859                   <secondary>in BosConfig file</secondary>
 860                 </indexterm>
 861
 862                 <listitem>
 863                   <para>A simple processes has one: the complete pathname to its binary file</para>
 864                 </listitem>
 865
 866                 <listitem>
 867                   <para>The <emphasis role="bold">fs</emphasis> process has three: the complete pathnames to each of the three
 868                   component processes (<emphasis role="bold">/usr/afs/bin/fileserver</emphasis>, <emphasis
 869                   role="bold">/usr/afs/bin/volserver</emphasis>, and <emphasis role="bold">/usr/afs/bin/salvager</emphasis>)</para>
 870                 </listitem>
 871
 872                 <listitem>
 873                   <para>A cron process has two: the first the complete pathname to its binary file, the second the time at which the
 874                   BOS Server runs it</para>
 875                 </listitem>
 876               </itemizedlist></para>
 877           </listitem>
 878         </itemizedlist></para>
 879
 880       <para>In addition to process definitions, the <emphasis role="bold">BosConfig</emphasis> file also records automatic restart
 881       times for processes that have new binaries, and for all server processes including the BOS Server. See <link
 882       linkend="HDRWQ171">Setting the BOS Server's Restart Times</link>.</para>
 883     </sect2>
 884
 885     <sect2 id="HDRWQ155">
 886       <title>How the BOS Server Uses the Information in the BosConfig File</title>
 887
 888       <indexterm>
 889         <primary>BOS Server</primary>
 890
 891         <secondary>use of BosConfig file</secondary>
 892       </indexterm>
 893
 894       <indexterm>
 895         <primary>BOS Server</primary>
 896
 897         <secondary>memory state</secondary>
 898       </indexterm>
 899
 900       <indexterm>
 901         <primary>memory state of BOS Server</primary>
 902       </indexterm>
 903
 904       <para>Whenever the BOS Server starts or restarts, it reads the <emphasis role="bold">BosConfig</emphasis> file to learn which
 905       processes it is to start and monitor. It transfers the information into kernel memory and does not read the <emphasis
 906       role="bold">BosConfig</emphasis> file again until it next restarts. This implies that the BOS Server's memory state can change
 907       independently of the <emphasis role="bold">BosConfig</emphasis> file. You can, for example, stop a process but leave its
 908       status flag in the <emphasis role="bold">BosConfig</emphasis> file as <computeroutput>Run</computeroutput>, or start a process
 909       even though its status flag in the <emphasis role="bold">BosConfig</emphasis> file is
 910       <computeroutput>NotRun</computeroutput>.</para>
 911     </sect2>
 912
 913     <sect2 id="HDRWQ156">
 914       <title>About Starting and Stopping the Database Server Processes</title>
 915
 916       <indexterm>
 917         <primary>database server process</primary>
 918
 919         <secondary>about starting and stopping</secondary>
 920       </indexterm>
 921
 922       <indexterm>
 923         <primary>Authentication Server</primary>
 924
 925         <secondary>about starting and stopping</secondary>
 926       </indexterm>
 927
 928       <indexterm>
 929         <primary>Protection Server</primary>
 930
 931         <secondary>about starting and stopping</secondary>
 932       </indexterm>
 933
 934       <indexterm>
 935         <primary>VL Server</primary>
 936
 937         <secondary>about starting and stopping</secondary>
 938       </indexterm>
 939
 940       <indexterm>
 941         <primary>Backup Server</primary>
 942
 943         <secondary>about starting and stopping</secondary>
 944       </indexterm>
 945
 946       <indexterm>
 947         <primary>starting</primary>
 948
 949         <secondary>database server process, about</secondary>
 950       </indexterm>
 951
 952       <indexterm>
 953         <primary>stopping</primary>
 954
 955         <secondary>database server process, about</secondary>
 956       </indexterm>
 957
 958       <para>When you start or stop a database server process (Authentication Server, Backup Server, Protection Server, or Volume
 959       Location Server) for more than a short time, you must follow the instructions in the <emphasis>OpenAFS Quick
 960       Beginnings</emphasis> for installing or removing a database server machine. Here is a summary of the tasks you must perform to
 961       preserve correct AFS functioning. <itemizedlist>
 962           <listitem>
 963             <para>Start or stop all four database server processes on that machine. All AFS server processes and the Cache Manager
 964             processes expect all four database server processes to be running on each machine listed in the <emphasis
 965             role="bold">CellServDB</emphasis> file. There is no way to indicate in the file that a machine is running only some of
 966             the database server processes.</para>
 967           </listitem>
 968
 969           <listitem>
 970             <para>Add or remove the machine in the <emphasis role="bold">/usr/afs/etc/CellServDB</emphasis> file on all server
 971             machines and the <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file on all client machines.</para>
 972           </listitem>
 973
 974           <listitem>
 975             <para>Restart the database server processes on the other database server machines to force an election of a new Ubik
 976             coordinator for each one.</para>
 977           </listitem>
 978         </itemizedlist></para>
 979     </sect2>
 980
 981     <sect2 id="HDRWQ157">
 982       <title>About Starting and Stopping the Update Server</title>
 983
 984       <indexterm>
 985         <primary>Update Server</primary>
 986
 987         <secondary>about starting and stopping</secondary>
 988       </indexterm>
 989
 990       <para>In the conventional cell configuration, one server machine of each system type acts as a binary distribution machine,
 991       running the server portion of the Update Server (<emphasis role="bold">upserver</emphasis> process) to distribute the contents
 992       of its <emphasis role="bold">/usr/afs/bin</emphasis> directory. The other server machines of its system type run an instance
 993       of the Update Server client portion (by convention called <emphasis role="bold">upclientbin</emphasis>) that references the
 994       binary distribution machine.</para>
 995
 996       <para>It is conventional for the first server machine you install to act as the
 997       system control machine, running the server portion of the Update Server (<emphasis role="bold">upserver</emphasis> process) to
 998       distribute the contents of its <emphasis role="bold">/usr/afs/etc</emphasis> directory. All other server machines run an
 999       instance of the Update Server client portion (by convention called <emphasis role="bold">upclientetc</emphasis>) that
1000       references the system control machine.</para>
1001
1002       <para>It is simplest not to move binary distribution or system control responsibilities to a different machine unless you
1003       completely decommission a machine that is currently serving in one of those roles. Running the Update Server usually imposes
1004       very little processing load. If you must move the functionality, perform the following related tasks. <itemizedlist>
1005           <listitem>
1006             <para>If you replace the system control machine, you must stop the <emphasis role="bold">upclientetc</emphasis> process
1007             on every other server machine and define a new one that references the new system control machine.</para>
1008           </listitem>
1009
1010           <listitem>
1011             <para>If you replace a binary distribution machine, you must stop the <emphasis role="bold">upclientbin</emphasis>
1012             process on every other server machine of its system type and define a new one that references the new binary
1013             distribution machine (unless you are no longer running any server machines of that system type).</para>
1014           </listitem>
1015         </itemizedlist></para>
1016     </sect2>
1017   </sect1>
1018
1019   <sect1 id="HDRWQ158">
1020     <title>Displaying Process Status and Information from the BosConfig File</title>
1021
1022     <para>To display the status of the AFS server processes on a server machine, issue the <emphasis role="bold">bos
1023     status</emphasis> command. Adding the <emphasis role="bold">-long</emphasis> flag displays most of the information from each
1024     process's entry in the <emphasis role="bold">BosConfig</emphasis> file, including its type and command parameters. It also
1025     displays a warning message if the mode bits on files and subdirectories in the <emphasis role="bold">/usr/afs</emphasis>
1026     directory do not match the expected values.</para>
1027
1028     <sect2 id="HDRWQ159">
1029       <title>To display the status of server processes and their BosConfig entries</title>
1030
1031       <indexterm>
1032         <primary>displaying</primary>
1033
1034         <secondary>server process status</secondary>
1035       </indexterm>
1036
1037       <indexterm>
1038         <primary>server process</primary>
1039
1040         <secondary>displaying status</secondary>
1041       </indexterm>
1042
1043       <indexterm>
1044         <primary>status</primary>
1045
1046         <secondary>displaying for server process</secondary>
1047       </indexterm>
1048
1049       <indexterm>
1050         <primary>displaying</primary>
1051
1052         <secondary>entries from BosConfig file</secondary>
1053       </indexterm>
1054
1055       <indexterm>
1056         <primary>server process</primary>
1057
1058         <secondary>displaying entry in BosConfig</secondary>
1059       </indexterm>
1060
1061       <indexterm>
1062         <primary>BosConfig file</primary>
1063
1064         <secondary>displaying entries</secondary>
1065       </indexterm>
1066
1067       <indexterm>
1068         <primary>bos commands</primary>
1069
1070         <secondary>status</secondary>
1071       </indexterm>
1072
1073       <indexterm>
1074         <primary>commands</primary>
1075
1076         <secondary>bos status</secondary>
1077       </indexterm>
1078
1079       <orderedlist>
1080         <listitem>
1081           <para>Issue the <emphasis role="bold">bos status</emphasis> command. <programlisting>
1082    % <emphasis role="bold">bos status</emphasis> &lt;<replaceable>machine name</replaceable>&gt;  [&lt;<replaceable>server process name</replaceable>&gt;+]  [<emphasis
1083                 role="bold">-long</emphasis>]
1084 </programlisting></para>
1085
1086           <para>where <variablelist>
1087               <varlistentry>
1088                 <term><emphasis role="bold">stat</emphasis></term>
1089
1090                 <listitem>
1091                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">status</emphasis>.</para>
1092                 </listitem>
1093               </varlistentry>
1094
1095               <varlistentry>
1096                 <term><emphasis role="bold">machine name</emphasis></term>
1097
1098                 <listitem>
1099                   <para>Specifies the file server machine for which to display process status.</para>
1100                 </listitem>
1101               </varlistentry>
1102
1103               <varlistentry>
1104                 <term><emphasis role="bold">server process name</emphasis></term>
1105
1106                 <listitem>
1107                   <para>Names each process for which to display status, using the name assigned when its entry was defined with the
1108                   <emphasis role="bold">bos create</emphasis> command. Omit this argument to display the status of all server
1109                   processes.</para>
1110                 </listitem>
1111               </varlistentry>
1112
1113               <varlistentry>
1114                 <term><emphasis role="bold">-long</emphasis></term>
1115
1116                 <listitem>
1117                   <para>Displays, in addition to status, information from the process's entry in the <emphasis
1118                   role="bold">BosConfig</emphasis> file: its type, its status flag, its command parameters, the associated notifier
1119                   program, and so on.</para>
1120                 </listitem>
1121               </varlistentry>
1122             </variablelist></para>
1123         </listitem>
1124       </orderedlist>
1125
1126       <para>The output includes an entry for each process and uses one of the following strings to indicate the process's status:
1127       <itemizedlist>
1128           <listitem>
1129             <para><computeroutput>currently running normally</computeroutput> indicates that the process is running and its status
1130             flag in the <emphasis role="bold">BosConfig</emphasis> file is <computeroutput>Run</computeroutput>. For cron entries,
1131             this message indicates that the command is still scheduled to run, not necessarily that it is actually running when the
1132             <emphasis role="bold">bos status</emphasis> command was issued.</para>
1133           </listitem>
1134
1135           <listitem>
1136             <para><computeroutput>temporarily enabled</computeroutput> indicates that the process is running but that its status
1137             flag in the <emphasis role="bold">BosConfig</emphasis> file is <computeroutput>NotRun</computeroutput>. The most common
1138             reason is that a system administrator has used the <emphasis role="bold">bos startup</emphasis> command to start the
1139             process.</para>
1140           </listitem>
1141
1142           <listitem>
1143             <para><computeroutput>temporarily disabled</computeroutput> indicates that the process is not running even though its
1144             status flag in the <emphasis role="bold">BosConfig</emphasis> file is <computeroutput>Run</computeroutput>. The most
1145             common reasons are either that a system administrator has used the <emphasis role="bold">bos shutdown</emphasis> command
1146             to stop the process or that the BOS Server ceased trying to restart the process after numerous failed attempts. In the
1147             latter case, a supplementary message appears: <computeroutput>stopped for too many errors</computeroutput>.</para>
1148           </listitem>
1149
1150           <listitem>
1151             <para>disabled indicates that the process is not running and that its status flag in the <emphasis
1152             role="bold">BosConfig</emphasis> file is <computeroutput>NotRun</computeroutput>. The BOS Server is not monitoring the
1153             process. Only a system administrator can set the flag this way; the BOS Server never does.</para>
1154           </listitem>
1155         </itemizedlist></para>
1156
1157       <para>The output for the <emphasis role="bold">fs</emphasis> process always includes a message marked
1158       <computeroutput>Auxiliary status</computeroutput>, which can be one of the following: <itemizedlist>
1159           <listitem>
1160             <para><computeroutput>file server running</computeroutput> indicates that the File Server and Volume Server components
1161             of the File Server process are running normally.</para>
1162           </listitem>
1163
1164           <listitem>
1165             <para><computeroutput>salvaging file system</computeroutput> indicates that the Salvager is running, which usually
1166             implies that the File Server and Volume Server are temporarily disabled. The BOS Server restarts them as soon as the
1167             Salvager is finished.</para>
1168           </listitem>
1169         </itemizedlist></para>
1170
1171       <para>The output for a cron process also includes an <computeroutput>Auxiliary status</computeroutput> message to report when
1172       the command is scheduled to run next; see the example that follows.</para>
1173
1174       <para>The output for any process can include the supplementary message <computeroutput>has core file</computeroutput> to
1175       indicate that at some point the process failed and generated a core file in the <emphasis role="bold">/usr/afs/logs</emphasis>
1176       directory. In most cases, the BOS Server is able to restart the process and it is running.</para>
1177
1178       <para>The following example includes a user-defined cron entry called <emphasis role="bold">backupusers</emphasis>:</para>
1179
1180       <programlisting>
1181    % <emphasis role="bold">bos status fs3.example.com</emphasis>
1182    Instance kaserver, currently running normally.
1183    Instance ptserver, currently running normally.
1184    Instance vlserver, has core file, currently running normally.
1185    Instance buserver, currently running normally.
1186    Instance fs, currently running normally.
1187        Auxiliary status is: file server running.
1188    Instance upserver, currently running normally.
1189    Instance backupusers, currently running normally.
1190        Auxiliary status is: run next at Mon Jun 7 02:00:00 1999.
1191 </programlisting>
1192
1193       <para>If you include the <emphasis role="bold">-long</emphasis> flag to the <emphasis role="bold">bos status</emphasis>
1194       command, a process's entry in the output includes the following additional information from the <emphasis
1195       role="bold">BosConfig</emphasis> file: <itemizedlist>
1196           <listitem>
1197             <para>The process's type (<computeroutput>simple</computeroutput>, <computeroutput>fs</computeroutput>, or
1198             <computeroutput>cron</computeroutput>).</para>
1199           </listitem>
1200
1201           <listitem>
1202             <para>The day and time the process last started or restarted.</para>
1203           </listitem>
1204
1205           <listitem>
1206             <para>The number of <computeroutput>proc starts</computeroutput>, which is how many times the BOS Server has started or
1207             restarted the process since it started itself.</para>
1208           </listitem>
1209
1210           <listitem>
1211             <para>The <computeroutput>Last exit</computeroutput> time when the process (or one of the component processes in the
1212             <emphasis role="bold">fs</emphasis> process) last terminated. This line does not appear if the process has not
1213             terminated since the BOS Server started.</para>
1214           </listitem>
1215
1216           <listitem>
1217             <para>The <computeroutput>Last error exit</computeroutput> time when the process (or one of the component processes in
1218             the <emphasis role="bold">fs</emphasis> process) last failed due to an error. A further explanation such as
1219             <computeroutput>due to shutdown request</computeroutput> sometimes appears. This line does not appear if the process has
1220             not failed since the BOS Server started.</para>
1221           </listitem>
1222
1223           <listitem>
1224             <para>Each command that the BOS Server invokes to start the process, as specified by the <emphasis
1225             role="bold">-cmd</emphasis> argument to the <emphasis role="bold">bos create</emphasis> command.</para>
1226           </listitem>
1227
1228           <listitem>
1229             <para>The pathname of the notifier program that the BOS Server invokes when the process terminates (if any), as
1230             specified by the <emphasis role="bold">-notifier</emphasis> argument to the <emphasis role="bold">bos create</emphasis>
1231             command.</para>
1232           </listitem>
1233         </itemizedlist></para>
1234
1235       <para>In addition, if the BOS Server has found that the mode bits on certain files and directories under <emphasis
1236       role="bold">/usr/afs</emphasis> deviate from what it expects, it prints the following warning message:</para>
1237
1238       <programlisting>
1239    Bosserver process reports inappropriate access on server directories
1240 </programlisting>
1241
1242       <para>The expected protections for the directories and files in the <emphasis role="bold">/usr/afs</emphasis> directory are as
1243       follows. A question mark indicates that the BOS Server does not check the mode bit. See the <emphasis>OpenAFS Quick
1244       Beginnings</emphasis> for more information about setting the protections on these files and directories.</para>
1245
1246       <informaltable frame="none">
1247         <tgroup cols="2">
1248           <tbody>
1249             <row>
1250               <entry><emphasis role="bold">/usr/afs</emphasis></entry>
1251
1252               <entry><computeroutput>drwxr?xr-x</computeroutput></entry>
1253             </row>
1254
1255             <row>
1256               <entry><emphasis role="bold">/usr/afs/backup</emphasis></entry>
1257
1258               <entry><computeroutput>drwx???---</computeroutput></entry>
1259             </row>
1260
1261             <row>
1262               <entry><emphasis role="bold">/usr/afs/bin</emphasis></entry>
1263
1264               <entry><computeroutput>drwxr?xr-x</computeroutput></entry>
1265             </row>
1266
1267             <row>
1268               <entry><emphasis role="bold">/usr/afs/db</emphasis></entry>
1269
1270               <entry><computeroutput>drwx???---</computeroutput></entry>
1271             </row>
1272
1273             <row>
1274               <entry><emphasis role="bold">/usr/afs/etc</emphasis></entry>
1275
1276               <entry><computeroutput>drwxr?xr-x</computeroutput></entry>
1277             </row>
1278
1279             <row>
1280               <entry><emphasis role="bold">/usr/afs/etc/KeyFile</emphasis></entry>
1281
1282               <entry><computeroutput>-rw????---</computeroutput></entry>
1283             </row>
1284
1285             <row>
1286               <entry><emphasis role="bold">/usr/afs/etc/UserList</emphasis></entry>
1287
1288               <entry><computeroutput>-rw?????--</computeroutput></entry>
1289             </row>
1290
1291             <row>
1292               <entry><emphasis role="bold">/usr/afs/local</emphasis></entry>
1293
1294               <entry><computeroutput>drwx???---</computeroutput></entry>
1295             </row>
1296
1297             <row>
1298               <entry><emphasis role="bold">/usr/afs/logs</emphasis></entry>
1299
1300               <entry><computeroutput>drwxr?xr-x</computeroutput></entry>
1301             </row>
1302           </tbody>
1303         </tgroup>
1304       </informaltable>
1305
1306       <para>The following illustrates the extended output for the <emphasis role="bold">fs</emphasis> process running on the machine
1307       <emphasis role="bold">fs3.example.com</emphasis>:</para>
1308
1309       <programlisting>
1310    % <emphasis role="bold">bos status fs3.example.com fs -long</emphasis>
1311    Instance fs, (type is fs), currently running normally.
1312        Auxiliary status is file server running
1313    Process last started at Mon May 3 8:29:19 1999 (3 proc starts)
1314    Last exit at Mon May 3 8:29:19 1999
1315    Last error exit at Mon May 3 8:29:19 1999, due to shutdown request
1316    Command 1 is '/usr/afs/bin/fileserver'
1317    Command 2 is '/usr/afs/bin/volserver'
1318    Command 3 is '/usr/afs/bin/salvager'
1319 </programlisting>
1320     </sect2>
1321   </sect1>
1322
1323   <sect1 id="HDRWQ161">
1324     <title>Creating and Removing Processes</title>
1325
1326     <indexterm>
1327       <primary>initializing</primary>
1328
1329       <secondary>server process</secondary>
1330     </indexterm>
1331
1332     <indexterm>
1333       <primary>creating</primary>
1334
1335       <secondary>server process</secondary>
1336     </indexterm>
1337
1338     <indexterm>
1339       <primary>defining</primary>
1340
1341       <secondary>server process in BosConfig file</secondary>
1342     </indexterm>
1343
1344     <indexterm>
1345       <primary>starting</primary>
1346
1347       <secondary>server process</secondary>
1348     </indexterm>
1349
1350     <indexterm>
1351       <primary>server process</primary>
1352
1353       <secondary>creating</secondary>
1354     </indexterm>
1355
1356     <indexterm>
1357       <primary>server process</primary>
1358
1359       <secondary>starting</secondary>
1360     </indexterm>
1361
1362     <indexterm>
1363       <primary>server process</primary>
1364
1365       <secondary>stopping permanently</secondary>
1366     </indexterm>
1367
1368     <indexterm>
1369       <primary>server process</primary>
1370
1371       <secondary>removing from BosConfig file</secondary>
1372     </indexterm>
1373
1374     <para>To start a new AFS server process on a server machine, issue the <emphasis role="bold">bos create</emphasis> command,
1375     which creates an entry in the <emphasis role="bold">/usr/afs/local/BosConfig</emphasis> file, sets the process's status flag to
1376     <computeroutput>Run</computeroutput> both in the file and in the BOS Server's memory, and starts it running immediately. The
1377     binary file for the new process must already be installed, by convention in the <emphasis role="bold">/usr/afs/bin</emphasis>
1378     directory (see <link linkend="HDRWQ111">Installing New Binaries</link>).</para>
1379
1380     <para>To stop a process permanently, first issue the <emphasis role="bold">bos stop</emphasis> command, which changes the
1381     process's status flag to <computeroutput>NotRun</computeroutput> in both the <emphasis role="bold">BosConfig</emphasis> file and
1382     the BOS Server's memory; it is marked as <computeroutput>disabled</computeroutput> in the output from the <emphasis
1383     role="bold">bos status</emphasis> command. If desired, issue the <emphasis role="bold">bos delete</emphasis> command to remove
1384     the process's entry from the <emphasis role="bold">BosConfig</emphasis> file; the process no longer appears in the <emphasis
1385     role="bold">bos status</emphasis> command's output.</para>
1386
1387     <note>
1388       <para>If you are starting or stopping a database server process in the manner described in this section, follow the complete
1389       instructions in the <emphasis>OpenAFS Quick Beginnings</emphasis> for creating or removing a database server machine. If you
1390       run one database server process on a given machine, you must run them all; for more information, see <link
1391       linkend="HDRWQ156">About Starting and Stopping the Database Server Processes</link>. Similarly, if you are stopping the
1392       <emphasis role="bold">upserver</emphasis> process on the system control machine or a binary distribution machine, you must
1393       complete the additional tasks described in <link linkend="HDRWQ157">About Starting and Stopping the Update
1394       Server</link>.</para>
1395     </note>
1396
1397     <sect2 id="HDRWQ162">
1398       <title>To create and start a new process</title>
1399
1400       <indexterm>
1401         <primary>server process</primary>
1402
1403         <secondary>creating and starting</secondary>
1404       </indexterm>
1405
1406       <indexterm>
1407         <primary>server process</primary>
1408
1409         <secondary>defining in BosConfig file</secondary>
1410       </indexterm>
1411
1412       <indexterm>
1413         <primary>simple server process</primary>
1414
1415         <secondary>defining in BosConfig file</secondary>
1416       </indexterm>
1417
1418       <indexterm>
1419         <primary>cron server process</primary>
1420
1421         <secondary>defining in BosConfig file</secondary>
1422       </indexterm>
1423
1424       <indexterm>
1425         <primary>fs server process</primary>
1426
1427         <secondary>defining in BosConfig file</secondary>
1428       </indexterm>
1429
1430       <indexterm>
1431         <primary>BosConfig file</primary>
1432
1433         <secondary>creating server process entry</secondary>
1434       </indexterm>
1435
1436       <indexterm>
1437         <primary>bos commands</primary>
1438
1439         <secondary>create</secondary>
1440       </indexterm>
1441
1442       <indexterm>
1443         <primary>commands</primary>
1444
1445         <secondary>bos create</secondary>
1446       </indexterm>
1447
1448       <orderedlist>
1449         <listitem>
1450           <para>Verify that you are authenticated as a user listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis>
1451           file. If necessary, issue the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link
1452           linkend="HDRWQ593">To display the users in the UserList file</link>. <programlisting>
1453    % <emphasis role="bold">bos listusers</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
1454 </programlisting></para>
1455         </listitem>
1456
1457         <listitem>
1458           <para><emphasis role="bold">(Optional)</emphasis> Verify that the process's binaries are installed in the <emphasis
1459           role="bold">/usr/afs/bin</emphasis> directory on this machine. If necessary, login at the console or telnet to the machine
1460           and list the contents of the <emphasis role="bold">/usr/afs/bin</emphasis> directory.</para>
1461
1462           <para>If the binaries are not present, install them on the binary distribution machine of the appropriate system type, and
1463           wait for the Update Server to copy them to this machine. For instructions, see <link linkend="HDRWQ111">Installing New
1464           Binaries</link>.</para>
1465
1466           <programlisting>
1467    % <emphasis role="bold">ls /usr/afs/bin</emphasis>
1468 </programlisting>
1469         </listitem>
1470
1471         <listitem>
1472           <para>Issue the <emphasis role="bold">bos create</emphasis> command to create an entry in the
1473           <emphasis role="bold">BosConfig</emphasis> file and start the process. <programlisting>
1474    % <emphasis role="bold">bos create</emphasis> &lt;<replaceable>machine name</replaceable>&gt; &lt;<replaceable>server process name</replaceable>&gt;   \
1475              &lt;<replaceable>server type</replaceable>&gt; &lt;<replaceable>command lines</replaceable>&gt;+ [ <emphasis
1476                 role="bold">-notifier</emphasis> &lt;<replaceable>Notifier program</replaceable>&gt;]
1477 </programlisting></para>
1478
1479           <para>where <variablelist>
1480               <varlistentry>
1481                 <term><emphasis role="bold">cr</emphasis></term>
1482
1483                 <listitem>
1484                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">create</emphasis>.</para>
1485                 </listitem>
1486               </varlistentry>
1487
1488               <varlistentry>
1489                 <term><emphasis role="bold">machine name</emphasis></term>
1490
1491                 <listitem>
1492                   <para>Specifies the file server machine on which to create the process.</para>
1493                 </listitem>
1494               </varlistentry>
1495
1496               <varlistentry>
1497                 <term><emphasis role="bold">server process name</emphasis></term>
1498
1499                 <listitem>
1500                   <para>Names the process to create and start. For simple processes, the conventional value is the name of the
1501                   process's binary file. It is best to use the same name on every server machine that runs the process. The
1502                   following is a list of the conventional names for simple and fs-type processes (there are no standard cron
1503                   processes). <itemizedlist>
1504                       <listitem>
1505                         <para><emphasis role="bold">buserver</emphasis> for the Backup Server</para>
1506                       </listitem>
1507
1508                       <listitem>
1509                         <para><emphasis role="bold">fs</emphasis> for the process that combines the File Server, Volume Server, and
1510                         Salvager</para>
1511                       </listitem>
1512
1513                       <listitem>
1514                         <para><emphasis role="bold">kaserver</emphasis> for the Authentication Server</para>
1515                       </listitem>
1516
1517                       <listitem>
1518                         <para><emphasis role="bold">ptserver</emphasis> for the Protection Server</para>
1519                       </listitem>
1520
1521                       <listitem>
1522                         <para><emphasis role="bold">upclientbin</emphasis> for the client portion of the Update Server that
1523                         references the binary distribution machine of this machine's system type</para>
1524                       </listitem>
1525
1526                       <listitem>
1527                         <para><emphasis role="bold">upclientetc</emphasis> for the client portion of the Update Server that
1528                         references the system control machine</para>
1529                       </listitem>
1530
1531                       <listitem>
1532                         <para><emphasis role="bold">vlserver</emphasis> for the Volume Location (VL) Server</para>
1533                       </listitem>
1534                     </itemizedlist></para>
1535                 </listitem>
1536               </varlistentry>
1537
1538               <varlistentry>
1539                 <term><emphasis role="bold">server type</emphasis></term>
1540
1541                 <listitem>
1542                   <para>Defines the process's type. Choose one of the following values: <itemizedlist>
1543                       <listitem>
1544                         <para><emphasis role="bold">cron</emphasis> for a cron process</para>
1545                       </listitem>
1546
1547                       <listitem>
1548                         <para><emphasis role="bold">fs</emphasis> for the process named <emphasis role="bold">fs</emphasis></para>
1549                       </listitem>
1550
1551                       <listitem>
1552                         <para><emphasis role="bold">simple</emphasis> for all other processes listed as acceptable values for the
1553                         server process name argument</para>
1554                       </listitem>
1555                     </itemizedlist></para>
1556                 </listitem>
1557               </varlistentry>
1558
1559               <varlistentry>
1560                 <term><emphasis role="bold">command lines</emphasis></term>
1561
1562                 <listitem>
1563                   <para>Specifies each command the BOS Server runs to start the process. Specify no more than six commands (which
1564                   can include the command's options, in which case the entire string is surrounded by double quotes); any additional
1565                   commands are ignored.</para>
1566
1567                   <para>For a simple process, provide the complete pathname of the process's binary file on the local disk (for
1568                   example, <emphasis role="bold">/usr/afs/bin/ptserver</emphasis> for the Protection Server). If including any of
1569                   the initialization command's options, surround the entire command in double quotes (<emphasis role="bold">"
1570                   "</emphasis>). The <emphasis role="bold">upclient</emphasis> process has a required argument, and the commands for
1571                   all other processes take optional arguments.</para>
1572
1573                   <indexterm>
1574                     <primary>simple process</primary>
1575
1576                     <secondary>creating with bos create command</secondary>
1577                   </indexterm>
1578
1579                   <para>For the <emphasis role="bold">fs</emphasis> process, provide the complete pathname of the local disk binary
1580                   file for each of the component processes: <emphasis role="bold">fileserver</emphasis>, <emphasis
1581                   role="bold">volserver</emphasis>, and <emphasis role="bold">salvager</emphasis>, in that order. The standard
1582                   binary directory is <emphasis role="bold">/usr/afs/bin</emphasis>. If including any of an initialization command's
1583                   options, surround the entire command in double quotes (<emphasis role="bold">" "</emphasis>).</para>
1584
1585                   <indexterm>
1586                     <primary>fs process</primary>
1587
1588                     <secondary>creating</secondary>
1589                   </indexterm>
1590
1591                   <indexterm>
1592                     <primary>cron process</primary>
1593
1594                     <secondary>creating with bos create command</secondary>
1595                   </indexterm>
1596
1597                   <para>For a <emphasis role="bold">cron</emphasis> process, provide two parameters: <itemizedlist>
1598                       <listitem>
1599                         <para>The complete local disk pathname of either an executable file or a command from one of the AFS suites
1600                         (complete with all of the necessary arguments). Surround this parameter with double quotes (<emphasis
1601                         role="bold">" "</emphasis>) if it contains spaces.</para>
1602                       </listitem>
1603
1604                       <listitem>
1605                         <para>A specification of when the BOS Server executes the file or command indicated by the first parameter.
1606                         There are three acceptable values: <itemizedlist>
1607                             <listitem>
1608                               <para>The string <emphasis role="bold">now</emphasis>, which directs the BOS Server to execute the
1609                               file or command immediately and only once. It is usually simpler to issue the command directly or
1610                               issue the <emphasis role="bold">bos exec</emphasis> command.</para>
1611                             </listitem>
1612
1613                             <listitem>
1614                               <para>A time of day. The BOS Server executes the file or command daily at the indicated time. Separate
1615                               the hours and minutes with a colon (<emphasis>hh</emphasis>:<emphasis>MM</emphasis>), and use either
1616                               24-hour format, or a value in the range from <emphasis role="bold">1:00</emphasis> through <emphasis
1617                               role="bold">12:59</emphasis> with the addition of <emphasis role="bold">am</emphasis> or <emphasis
1618                               role="bold">pm</emphasis>. For example, both <emphasis role="bold">14:30</emphasis> and <emphasis
1619                               role="bold">"2:30 pm"</emphasis> indicate 2:30 in the afternoon. Surround this parameter with double
1620                               quotes (<emphasis role="bold">" "</emphasis>) if it contains a space.</para>
1621                             </listitem>
1622
1623                             <listitem>
1624                               <para>A day of the week and time of day, separated by a space and surrounded with double quotes
1625                               (<emphasis role="bold">" "</emphasis>). The BOS Server executes the file or command weekly at the
1626                               indicated day and time. For the day, provide either the whole name or the first three letters, all in
1627                               lowercase letters (<emphasis role="bold">sunday</emphasis> or <emphasis role="bold">sun</emphasis>,
1628                               <emphasis role="bold">thursday</emphasis> or <emphasis role="bold">thu</emphasis>, and so on). For the
1629                               time, use the same format as when specifying the time alone.</para>
1630                             </listitem>
1631                           </itemizedlist></para>
1632                       </listitem>
1633                     </itemizedlist></para>
1634                 </listitem>
1635               </varlistentry>
1636
1637               <varlistentry>
1638                 <term><emphasis role="bold">-notifier</emphasis></term>
1639
1640                 <listitem>
1641                   <para>Specifies the pathname of a program that the BOS Server runs when the process terminates. For more
1642                   information on notifier programs, see the <emphasis role="bold">bos create</emphasis> command reference page in
1643                   the <emphasis>OpenAFS Administration Reference</emphasis>.</para>
1644                 </listitem>
1645               </varlistentry>
1646             </variablelist></para>
1647         </listitem>
1648       </orderedlist>
1649
1650       <para>The following example defines and starts the Protection Server on the machine <emphasis
1651       role="bold">db2.example.com</emphasis>:</para>
1652
1653       <programlisting>
1654    % <emphasis role="bold">bos create db2.example.com ptserver simple /usr/afs/bin/ptserver</emphasis>
1655 </programlisting>
1656
1657       <para>The following example defines and starts the <emphasis role="bold">fs</emphasis> process on the machine <emphasis
1658       role="bold">fs6.example.com</emphasis>.</para>
1659
1660       <programlisting>
1661    % <emphasis role="bold">bos create fs6.example.com fs fs /usr/afs/bin/fileserver</emphasis>   \
1662         <emphasis role="bold">/usr/afs/bin/volserver /usr/afs/bin/salvager</emphasis>
1663 </programlisting>
1664
1665       <para>The following example defines and starts a cron process called <emphasis role="bold">backupuser</emphasis> process on
1666       the machine <emphasis role="bold">fs3.example.com</emphasis>, scheduling it to run each day at 3:00 a.m.</para>
1667
1668       <programlisting>
1669    % <emphasis role="bold">bos create fs3.example.com backupuser cron  "/usr/afs/bin/vos backupsys -prefix user -local" 3:00</emphasis>
1670 </programlisting>
1671     </sect2>
1672
1673     <sect2 id="Header_184">
1674       <title>To stop a process and remove it from the BosConfig file</title>
1675
1676       <indexterm>
1677         <primary>removing</primary>
1678
1679         <secondary>server process from BosConfig file</secondary>
1680       </indexterm>
1681
1682       <indexterm>
1683         <primary>BosConfig file</primary>
1684
1685         <secondary>removing server process entry</secondary>
1686       </indexterm>
1687
1688       <indexterm>
1689         <primary>stopping</primary>
1690
1691         <secondary>server process</secondary>
1692
1693         <tertiary>permanently</tertiary>
1694       </indexterm>
1695
1696       <indexterm>
1697         <primary>server process</primary>
1698
1699         <secondary>removing from BosConfig file</secondary>
1700       </indexterm>
1701
1702       <indexterm>
1703         <primary>server process</primary>
1704
1705         <secondary>stopping permanently</secondary>
1706       </indexterm>
1707
1708       <indexterm>
1709         <primary>bos commands</primary>
1710
1711         <secondary>delete</secondary>
1712       </indexterm>
1713
1714       <indexterm>
1715         <primary>commands</primary>
1716
1717         <secondary>bos delete</secondary>
1718       </indexterm>
1719
1720       <orderedlist>
1721         <listitem>
1722           <para>Verify that you are authenticated as a user listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis>
1723           file. If necessary, issue the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link
1724           linkend="HDRWQ593">To display the users in the UserList file</link>. <programlisting>
1725    % <emphasis role="bold">bos listusers</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
1726 </programlisting></para>
1727         </listitem>
1728
1729         <listitem id="LIPROC-STOP">
1730           <para>Issue the <emphasis role="bold">bos stop</emphasis> command to change each process's
1731           status flag in the <emphasis role="bold">BosConfig</emphasis> file to <computeroutput>NotRun</computeroutput> and to stop
1732           it. You must issue this command even for cron processes that you wish to remove from the <emphasis
1733           role="bold">BosConfig</emphasis> file, even though they do not run continuously. For a detailed description of this
1734           command, see <link linkend="HDRWQ165">To stop a process by changing its status to
1735           <computeroutput>NotRun</computeroutput></link>. <programlisting>
1736    % <emphasis role="bold">bos stop</emphasis> &lt;<replaceable>machine name</replaceable>&gt; &lt;<replaceable>server process name</replaceable>&gt;+ [<emphasis
1737                 role="bold">-wait</emphasis>]
1738 </programlisting></para>
1739         </listitem>
1740
1741         <listitem>
1742           <para>Issue the <emphasis role="bold">bos delete</emphasis> command to remove each process from
1743           the <emphasis role="bold">BosConfig</emphasis> file. <programlisting>
1744    % <emphasis role="bold">bos delete</emphasis> &lt;<replaceable>machine name</replaceable>&gt; &lt;<replaceable>server process name</replaceable>&gt;+
1745 </programlisting></para>
1746
1747           <para>where <variablelist>
1748               <varlistentry>
1749                 <term><emphasis role="bold">d</emphasis></term>
1750
1751                 <listitem>
1752                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">delete</emphasis>.</para>
1753                 </listitem>
1754               </varlistentry>
1755
1756               <varlistentry>
1757                 <term><emphasis role="bold">machine name</emphasis></term>
1758
1759                 <listitem>
1760                   <para>Specifies the server machine on which to remove processes from the <emphasis
1761                   role="bold">BosConfig</emphasis> file.</para>
1762                 </listitem>
1763               </varlistentry>
1764
1765               <varlistentry>
1766                 <term><emphasis role="bold">server process name</emphasis></term>
1767
1768                 <listitem>
1769                   <para>Names each process entry to remove from the <emphasis role="bold">BosConfig</emphasis> file. Provide the
1770                   same names as in Step <link linkend="LIPROC-STOP">2</link>.</para>
1771                 </listitem>
1772               </varlistentry>
1773             </variablelist></para>
1774         </listitem>
1775       </orderedlist>
1776     </sect2>
1777   </sect1>
1778
1779   <sect1 id="HDRWQ164">
1780     <title>Stopping and Starting Processes Permanently</title>
1781
1782     <indexterm>
1783       <primary>starting</primary>
1784
1785       <secondary>server process</secondary>
1786     </indexterm>
1787
1788     <indexterm>
1789       <primary>server process</primary>
1790
1791       <secondary>starting up</secondary>
1792     </indexterm>
1793
1794     <indexterm>
1795       <primary>server process</primary>
1796
1797       <secondary>stopping permanently</secondary>
1798     </indexterm>
1799
1800     <indexterm>
1801       <primary>stopping</primary>
1802
1803       <secondary>server process</secondary>
1804
1805       <tertiary>permanently</tertiary>
1806     </indexterm>
1807
1808     <para>To stop a process so that the BOS Server no longer attempts to monitor it, issue the <emphasis role="bold">bos
1809     stop</emphasis> command. The process's status flag is set to <computeroutput>NotRun</computeroutput> in both the BOS Server's
1810     memory and in the <emphasis role="bold">BosConfig</emphasis> file. The process does not run again until you issue the <emphasis
1811     role="bold">bos start</emphasis> command, which sets its status flag back to <computeroutput>Run</computeroutput> in both the
1812     BOS Server's memory and in the <emphasis role="bold">BosConfig</emphasis> file. (You can also use the <emphasis role="bold">bos
1813     startup</emphasis> command to start the process again without changing its status flag in the <emphasis
1814     role="bold">BosConfig</emphasis> file; see <link linkend="HDRWQ167">Stopping and Starting Processes Temporarily</link>.)</para>
1815
1816     <para>There is no entry for the BOS Server in the <emphasis role="bold">BosConfig</emphasis> file, so the <emphasis
1817     role="bold">bos stop</emphasis> and <emphasis role="bold">bos start</emphasis> commands do not control it. To stop and
1818     immediately restart the BOS Server along with all other processes, use the <emphasis role="bold">-bosserver</emphasis> flag to
1819     the <emphasis role="bold">bos restart</emphasis> command as described in <link linkend="HDRWQ170">Stopping and Immediately
1820     Restarting Processes</link>.</para>
1821
1822     <note>
1823       <para>If you are starting or stopping a database server process in the manner described in this section, follow the complete
1824       instructions in the <emphasis>OpenAFS Quick Beginnings</emphasis> for creating or removing a database server machine. If you
1825       run one database server process on a given machine, you must run them all; for more information, see <link
1826       linkend="HDRWQ156">About Starting and Stopping the Database Server Processes</link>. Similarly, if you are stopping the
1827       <emphasis role="bold">upserver</emphasis> process on the system control machine or a binary distribution machine, you must
1828       complete the additional tasks described in <link linkend="HDRWQ157">About Starting and Stopping the Update
1829       Server</link>.</para>
1830     </note>
1831
1832     <sect2 id="HDRWQ165">
1833       <title>To stop a process by changing its status to NotRun</title>
1834
1835       <indexterm>
1836         <primary>Run status flag in BosConfig file</primary>
1837
1838         <secondary>changing to NotRun</secondary>
1839       </indexterm>
1840
1841       <indexterm>
1842         <primary>status flag in BosConfig file</primary>
1843
1844         <secondary>changing Run to NotRun</secondary>
1845       </indexterm>
1846
1847       <indexterm>
1848         <primary>BosConfig file</primary>
1849
1850         <secondary>changing status flag from Run to NotRun</secondary>
1851       </indexterm>
1852
1853       <indexterm>
1854         <primary>server process</primary>
1855
1856         <secondary>stopping permanently</secondary>
1857       </indexterm>
1858
1859       <indexterm>
1860         <primary>bos commands</primary>
1861
1862         <secondary>stop</secondary>
1863       </indexterm>
1864
1865       <indexterm>
1866         <primary>commands</primary>
1867
1868         <secondary>bos stop</secondary>
1869       </indexterm>
1870
1871       <orderedlist>
1872         <listitem>
1873           <para>Verify that you are authenticated as a user listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis>
1874           file. If necessary, issue the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link
1875           linkend="HDRWQ593">To display the users in the UserList file</link>. <programlisting>
1876    % <emphasis role="bold">bos listusers</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
1877 </programlisting></para>
1878         </listitem>
1879
1880         <listitem>
1881           <para>Issue the <emphasis role="bold">bos stop</emphasis> command to stop each process and set its status flag to
1882           <computeroutput>NotRun</computeroutput> in the <emphasis role="bold">BosConfig</emphasis> file and the BOS Server's
1883           memory. <programlisting>
1884    % <emphasis role="bold">bos stop</emphasis> &lt;<replaceable>machine name</replaceable>&gt; &lt;<replaceable>server process name</replaceable>&gt;+ [<emphasis
1885                 role="bold">-wait</emphasis>]
1886 </programlisting></para>
1887
1888           <para>where <variablelist>
1889               <varlistentry>
1890                 <term><emphasis role="bold">sto</emphasis></term>
1891
1892                 <listitem>
1893                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">stop</emphasis>.</para>
1894                 </listitem>
1895               </varlistentry>
1896
1897               <varlistentry>
1898                 <term><emphasis role="bold">machine name</emphasis></term>
1899
1900                 <listitem>
1901                   <para>Specifies the server machine on which to stop the process.</para>
1902                 </listitem>
1903               </varlistentry>
1904
1905               <varlistentry>
1906                 <term><emphasis role="bold">server process name</emphasis></term>
1907
1908                 <listitem>
1909                   <para>Names each process to stop, using the name assigned when its entry was defined with the <emphasis
1910                   role="bold">bos create</emphasis> command.</para>
1911                 </listitem>
1912               </varlistentry>
1913
1914               <varlistentry>
1915                 <term><emphasis role="bold">-wait</emphasis></term>
1916
1917                 <listitem>
1918                   <para>Delays the return of the command shell prompt until all specified processes have stopped. If you omit the
1919                   flag, the prompt returns almost immediately, even if all processes are not yet stopped.</para>
1920                 </listitem>
1921               </varlistentry>
1922             </variablelist></para>
1923         </listitem>
1924       </orderedlist>
1925     </sect2>
1926
1927     <sect2 id="HDRWQ166">
1928       <title>To start processes by changing their status flags to Run</title>
1929
1930       <indexterm>
1931         <primary>NotRun status flag in BosConfig file</primary>
1932
1933         <secondary>changing to Run</secondary>
1934       </indexterm>
1935
1936       <indexterm>
1937         <primary>status flag in BosConfig file</primary>
1938
1939         <secondary>changing NotRun to Run</secondary>
1940       </indexterm>
1941
1942       <indexterm>
1943         <primary>BosConfig file</primary>
1944
1945         <secondary>changing status flag from NotRun to Run</secondary>
1946       </indexterm>
1947
1948       <indexterm>
1949         <primary>commands</primary>
1950
1951         <secondary>bos start</secondary>
1952       </indexterm>
1953
1954       <indexterm>
1955         <primary>bos commands</primary>
1956
1957         <secondary>start</secondary>
1958       </indexterm>
1959
1960       <orderedlist>
1961         <listitem>
1962           <para>Verify that you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue
1963           the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To
1964           display the users in the UserList file</link>. <programlisting>
1965    % <emphasis role="bold">bos listusers</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
1966 </programlisting></para>
1967         </listitem>
1968
1969         <listitem>
1970           <para>Issue the <emphasis role="bold">bos start</emphasis> command to change each process's
1971           status flag to <computeroutput>Run</computeroutput> in both the <emphasis role="bold">BosConfig</emphasis> file and the
1972           BOS Server's memory and to start it. <programlisting>
1973    %  <emphasis role="bold">bos start</emphasis> &lt;<replaceable>machine name</replaceable>&gt; &lt;<replaceable>server process name</replaceable>&gt;+
1974 </programlisting></para>
1975
1976           <para>where <variablelist>
1977               <varlistentry>
1978                 <term><emphasis role="bold">start</emphasis></term>
1979
1980                 <listitem>
1981                   <para>Must be typed in full.</para>
1982                 </listitem>
1983               </varlistentry>
1984
1985               <varlistentry>
1986                 <term><emphasis role="bold">machine name</emphasis></term>
1987
1988                 <listitem>
1989                   <para>Specifies the server machine on which to start running each process.</para>
1990                 </listitem>
1991               </varlistentry>
1992
1993               <varlistentry>
1994                 <term><emphasis role="bold">server process name</emphasis></term>
1995
1996                 <listitem>
1997                   <para>Specifies each process to start on machine name. Use the name assigned to the process at creation.</para>
1998                 </listitem>
1999               </varlistentry>
2000             </variablelist></para>
2001         </listitem>
2002       </orderedlist>
2003     </sect2>
2004   </sect1>
2005
2006   <sect1 id="HDRWQ167">
2007     <title>Stopping and Starting Processes Temporarily</title>
2008
2009     <para>It is sometimes necessary to halt a process temporarily (for example, to make slight configuration changes or to perform
2010     maintenance). The commands described in this section change a process's status in the BOS Server's memory only; the effect is
2011     immediate and lasts until you change the memory state again (or until the BOS Server restarts, at which time it starts the
2012     process according to its entry in the <emphasis role="bold">BosConfig</emphasis> file).</para>
2013
2014     <para>To stop a process temporarily by changing its status flag in BOS Server memory to <computeroutput>NotRun</computeroutput>,
2015     use the <emphasis role="bold">bos shutdown</emphasis> command. To restart a stopped process by changing its status flag in the
2016     BOS Server's memory to <computeroutput>Run</computeroutput>, use the <emphasis role="bold">bos startup</emphasis> command. The
2017     process starts regardless of its status flag in the <emphasis role="bold">BosConfig</emphasis> file. You can also use the
2018     <emphasis role="bold">bos startup</emphasis> command to start all processes marked with status flag
2019     <computeroutput>Run</computeroutput> in the <emphasis role="bold">BosConfig</emphasis> file, as described in the following
2020     instructions.</para>
2021
2022     <para>Because the <emphasis role="bold">bos startup</emphasis> command starts a process without changing it status flag in the
2023     <emphasis role="bold">BosConfig</emphasis> file, it is useful for testing a server process without enabling it permanently. To
2024     stop and start processes by changing their status flags in the <emphasis role="bold">BosConfig</emphasis> file, see <link
2025     linkend="HDRWQ164">Stopping and Starting Processes Permanently</link>; to stop and immediately restart a process, see <link
2026     linkend="HDRWQ170">Stopping and Immediately Restarting Processes</link>.</para>
2027
2028     <note>
2029       <para>Do not temporarily stop a database server process on all machines at once. Doing so makes the database completely
2030       unavailable.</para>
2031     </note>
2032
2033     <indexterm>
2034       <primary>commands</primary>
2035
2036       <secondary>bos shutdown</secondary>
2037     </indexterm>
2038
2039     <indexterm>
2040       <primary>bos commands</primary>
2041
2042       <secondary>shutdown</secondary>
2043     </indexterm>
2044
2045     <sect2 id="HDRWQ168">
2046       <title>To stop processes temporarily</title>
2047
2048       <orderedlist>
2049         <listitem>
2050           <para>Verify that you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue
2051           the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To
2052           display the users in the UserList file</link>. <programlisting>
2053    % <emphasis role="bold">bos listusers</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
2054 </programlisting></para>
2055         </listitem>
2056
2057         <listitem>
2058           <para>Issue the <emphasis role="bold">bos shutdown</emphasis> command to stop each process by
2059           changing its status flag in the BOS Server's memory to <computeroutput>NotRun</computeroutput>. <programlisting>
2060    % <emphasis role="bold">bos shutdown</emphasis> &lt;<replaceable>machine name</replaceable>&gt; [&lt;<replaceable>instances</replaceable>&gt;+] [<emphasis
2061                 role="bold">-wait</emphasis>]
2062 </programlisting></para>
2063
2064           <para>where <variablelist>
2065               <varlistentry>
2066                 <term><emphasis role="bold">sh</emphasis></term>
2067
2068                 <listitem>
2069                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">shutdown</emphasis>.</para>
2070                 </listitem>
2071               </varlistentry>
2072
2073               <varlistentry>
2074                 <term><emphasis role="bold">machine name</emphasis></term>
2075
2076                 <listitem>
2077                   <para>Specifies the server machine on which to stop processes temporarily.</para>
2078                 </listitem>
2079               </varlistentry>
2080
2081               <varlistentry>
2082                 <term><emphasis role="bold">instances</emphasis></term>
2083
2084                 <listitem>
2085                   <para>Specifies each process to stop temporarily. Use the name assigned to the process at creation.</para>
2086                 </listitem>
2087               </varlistentry>
2088
2089               <varlistentry>
2090                 <term><emphasis role="bold">-wait</emphasis></term>
2091
2092                 <listitem>
2093                   <para>Delays the return of the command shell prompt until all specified processes have actually stopped. If you
2094                   omit the flag, the prompt returns almost immediately, even if all processes are not yet stopped.</para>
2095                 </listitem>
2096               </varlistentry>
2097             </variablelist></para>
2098         </listitem>
2099       </orderedlist>
2100
2101       <indexterm>
2102         <primary>commands</primary>
2103
2104         <secondary>bos startup</secondary>
2105       </indexterm>
2106
2107       <indexterm>
2108         <primary>bos commands</primary>
2109
2110         <secondary>startup</secondary>
2111       </indexterm>
2112     </sect2>
2113
2114     <sect2 id="Header_190">
2115       <title>To start all stopped processes that have status flag Run in the BosConfig file</title>
2116
2117       <orderedlist>
2118         <listitem>
2119           <para>Verify that you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue
2120           the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To
2121           display the users in the UserList file</link>. <programlisting>
2122    % <emphasis role="bold">bos listusers</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
2123 </programlisting></para>
2124         </listitem>
2125
2126         <listitem>
2127           <para>Issue the <emphasis role="bold">bos startup</emphasis> command to start each process on a machine that has status
2128           flag <computeroutput>Run</computeroutput> in the <emphasis role="bold">BosConfig</emphasis> file by changing its status
2129           flag in the BOS Server's memory from <computeroutput>NotRun</computeroutput> to <computeroutput>Run</computeroutput>.
2130           <programlisting>
2131    % <emphasis role="bold">bos startup</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
2132 </programlisting></para>
2133
2134           <para>where <variablelist>
2135               <varlistentry>
2136                 <term><emphasis role="bold">startup</emphasis></term>
2137
2138                 <listitem>
2139                   <para>Must be typed in full.</para>
2140                 </listitem>
2141               </varlistentry>
2142
2143               <varlistentry>
2144                 <term><emphasis role="bold">machine name</emphasis></term>
2145
2146                 <listitem>
2147                   <para>Specifies the server machine on which you wish to start all processes that have status flag
2148                   <computeroutput>Run</computeroutput> in the <emphasis role="bold">BosConfig</emphasis> file.</para>
2149                 </listitem>
2150               </varlistentry>
2151             </variablelist></para>
2152         </listitem>
2153       </orderedlist>
2154     </sect2>
2155
2156     <sect2 id="Header_191">
2157       <title>To start specific processes</title>
2158
2159       <orderedlist>
2160         <listitem>
2161           <para>Verify that you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue
2162           the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To
2163           display the users in the UserList file</link>. <programlisting>
2164    % <emphasis role="bold">bos listusers</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
2165 </programlisting></para>
2166         </listitem>
2167
2168         <listitem>
2169           <para>Issue the <emphasis role="bold">bos startup</emphasis> command to start specific processes by changing their status
2170           flags in the BOS Server's memory to <computeroutput>Run</computeroutput> without changing their status flags in the
2171           <emphasis role="bold">BosConfig</emphasis> file. <programlisting>
2172    % <emphasis role="bold">bos startup</emphasis> &lt;<replaceable>machine name</replaceable>&gt; &lt;<replaceable>instances</replaceable>&gt;+
2173 </programlisting></para>
2174
2175           <para>where <variablelist>
2176               <varlistentry>
2177                 <term><emphasis role="bold">startup</emphasis></term>
2178
2179                 <listitem>
2180                   <para>Must be typed in full.</para>
2181                 </listitem>
2182               </varlistentry>
2183
2184               <varlistentry>
2185                 <term><emphasis role="bold">machine name</emphasis></term>
2186
2187                 <listitem>
2188                   <para>Names the server machine on which to start processes.</para>
2189                 </listitem>
2190               </varlistentry>
2191
2192               <varlistentry>
2193                 <term><emphasis role="bold">instances</emphasis></term>
2194
2195                 <listitem>
2196                   <para>Specifies each process to start. Use the name assigned to the process at creation.</para>
2197                 </listitem>
2198               </varlistentry>
2199             </variablelist></para>
2200         </listitem>
2201       </orderedlist>
2202     </sect2>
2203   </sect1>
2204
2205   <sect1 id="HDRWQ170">
2206     <title>Stopping and Immediately Restarting Processes</title>
2207
2208     <indexterm>
2209       <primary>server process</primary>
2210
2211       <secondary>restarting immediately after stopping</secondary>
2212     </indexterm>
2213
2214     <indexterm>
2215       <primary>stopping</primary>
2216
2217       <secondary>server process and immediately restarting</secondary>
2218     </indexterm>
2219
2220     <para>Although by default the BOS Server checks each day for new installed binary files and restarts the associated processes,
2221     it is sometimes desirable to stop and restart processes immediately. The <emphasis role="bold">bos restart</emphasis> command
2222     provides this functionality, starting a completely new instance of each affected process: <itemizedlist>
2223         <listitem>
2224           <para>To stop and restart the BOS Server, which then restarts all processes marked with the
2225           <computeroutput>Run</computeroutput> status flag in the <emphasis role="bold">BosConfig</emphasis> file, include the
2226           <emphasis role="bold">-bosserver</emphasis> flag.</para>
2227         </listitem>
2228
2229         <listitem>
2230           <para>To stop and restart all processes marked with the <computeroutput>Run</computeroutput> status flag in the <emphasis
2231           role="bold">BosConfig</emphasis> file, include the <emphasis role="bold">-all</emphasis> flag. The BOS Server does not
2232           restart</para>
2233         </listitem>
2234
2235         <listitem>
2236           <para>To stop and restart specific processes regardless of the setting of their status flags in the <emphasis
2237           role="bold">BosConfig</emphasis> file, specify the name of each process to restart.</para>
2238         </listitem>
2239       </itemizedlist></para>
2240
2241     <para>Restarting processes causes a service outage. It is usually best to schedule restarts for periods of low usage. The BOS
2242     Server automatically restarts all processes once a week, to reduce the potential for the <emphasis>core leaks</emphasis> that
2243     can develop as any process runs for an extended time; see <link linkend="HDRWQ171">Setting the BOS Server's Restart
2244     Times</link>.</para>
2245
2246     <indexterm>
2247       <primary>outages</primary>
2248
2249       <secondary>due to server process restart</secondary>
2250     </indexterm>
2251
2252     <indexterm>
2253       <primary>system outages</primary>
2254
2255       <secondary>due to server process restart</secondary>
2256     </indexterm>
2257
2258     <para><indexterm>
2259         <primary>server process</primary>
2260
2261         <secondary>restarting by restarting BOS Server</secondary>
2262       </indexterm> <indexterm>
2263         <primary>restarting</primary>
2264
2265         <secondary>server process</secondary>
2266
2267         <tertiary>including BOS Server</tertiary>
2268       </indexterm> <indexterm>
2269         <primary>bos commands</primary>
2270
2271         <secondary>restart</secondary>
2272
2273         <tertiary>with -bosserver flag</tertiary>
2274       </indexterm> <indexterm>
2275         <primary>bos commands</primary>
2276
2277         <secondary>restart</secondary>
2278
2279         <tertiary>including BOS Server</tertiary>
2280       </indexterm> <indexterm>
2281         <primary>commands</primary>
2282
2283         <secondary>bos restart</secondary>
2284
2285         <tertiary>including BOS Server</tertiary>
2286       </indexterm></para>
2287
2288     <sect2 id="Header_193">
2289       <title>To stop and restart all processes including the BOS Server</title>
2290
2291       <orderedlist>
2292         <listitem>
2293           <para>Verify that you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue
2294           the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To
2295           display the users in the UserList file</link>. <programlisting>
2296    % <emphasis role="bold">bos listusers</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
2297 </programlisting></para>
2298         </listitem>
2299
2300         <listitem>
2301           <para>Issue the <emphasis role="bold">bos restart</emphasis> command with the <emphasis role="bold">-bosserver</emphasis>
2302           flag to stop and restart the BOS Server, which restarts every process marked with status flag
2303           <computeroutput>Run</computeroutput> in the <emphasis role="bold">BosConfig</emphasis> file. <programlisting>
2304    % <emphasis role="bold">bos restart</emphasis> &lt;<replaceable>machine name</replaceable>&gt;  <emphasis role="bold">-bosserver</emphasis>
2305 </programlisting></para>
2306
2307           <para>where <variablelist>
2308               <varlistentry>
2309                 <term><emphasis role="bold">res</emphasis></term>
2310
2311                 <listitem>
2312                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">restart</emphasis>.</para>
2313                 </listitem>
2314               </varlistentry>
2315
2316               <varlistentry>
2317                 <term><emphasis role="bold">machine name</emphasis></term>
2318
2319                 <listitem>
2320                   <para>Specifies the server machine on which to restart all processes.</para>
2321                 </listitem>
2322               </varlistentry>
2323
2324               <varlistentry>
2325                 <term><emphasis role="bold">-bosserver</emphasis></term>
2326
2327                 <listitem>
2328                   <para>Stops the BOS Server and all processes running on the machine. A new BOS Server instance starts; it then
2329                   starts new instances of all processes marked with status flag <computeroutput>Run</computeroutput> in the
2330                   <emphasis role="bold">BosConfig</emphasis> file.</para>
2331                 </listitem>
2332               </varlistentry>
2333             </variablelist></para>
2334         </listitem>
2335       </orderedlist>
2336
2337       <indexterm>
2338         <primary>bos commands</primary>
2339
2340         <secondary>restart</secondary>
2341
2342         <tertiary>excluding BOS Server</tertiary>
2343       </indexterm>
2344
2345       <indexterm>
2346         <primary>commands</primary>
2347
2348         <secondary>bos restart</secondary>
2349
2350         <tertiary>excluding BOS Server</tertiary>
2351       </indexterm>
2352
2353       <indexterm>
2354         <primary>server process</primary>
2355
2356         <secondary>restarting</secondary>
2357
2358         <tertiary>except BOS Server</tertiary>
2359       </indexterm>
2360
2361       <indexterm>
2362         <primary>restarting</primary>
2363
2364         <secondary>server process</secondary>
2365
2366         <tertiary>except BOS Server</tertiary>
2367       </indexterm>
2368     </sect2>
2369
2370     <sect2 id="Header_194">
2371       <title>To stop and immediately restart all processes except the BOS Server</title>
2372
2373       <orderedlist>
2374         <listitem>
2375           <para>Verify that you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue
2376           the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To
2377           display the users in the UserList file</link>. <programlisting>
2378    % <emphasis role="bold">bos listusers</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
2379 </programlisting></para>
2380         </listitem>
2381
2382         <listitem>
2383           <para>Issue the <emphasis role="bold">bos restart</emphasis> command with the <emphasis role="bold">-all</emphasis> flag
2384           to stop and immediately restart every process marked with status flag <computeroutput>Run</computeroutput> in the
2385           <emphasis role="bold">BosConfig</emphasis> file. The BOS Server does not restart. <programlisting>
2386    % <emphasis role="bold">bos restart</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">-all</emphasis>
2387 </programlisting></para>
2388
2389           <para>where <variablelist>
2390               <varlistentry>
2391                 <term><emphasis role="bold">res</emphasis></term>
2392
2393                 <listitem>
2394                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">restart</emphasis>.</para>
2395                 </listitem>
2396               </varlistentry>
2397
2398               <varlistentry>
2399                 <term><emphasis role="bold">machine name</emphasis></term>
2400
2401                 <listitem>
2402                   <para>Specifies the server machine on which to stop and restart processes.</para>
2403                 </listitem>
2404               </varlistentry>
2405
2406               <varlistentry>
2407                 <term><emphasis role="bold">-all</emphasis></term>
2408
2409                 <listitem>
2410                   <para>Stops and immediately restarts all processes marked with status flag <computeroutput>Run</computeroutput> in
2411                   the <emphasis role="bold">BosConfig</emphasis> file.</para>
2412                 </listitem>
2413               </varlistentry>
2414             </variablelist></para>
2415         </listitem>
2416       </orderedlist>
2417
2418       <indexterm>
2419         <primary>bos commands</primary>
2420
2421         <secondary>restart</secondary>
2422
2423         <tertiary>selected processes</tertiary>
2424       </indexterm>
2425
2426       <indexterm>
2427         <primary>commands</primary>
2428
2429         <secondary>bos restart</secondary>
2430
2431         <tertiary>selected processes</tertiary>
2432       </indexterm>
2433
2434       <indexterm>
2435         <primary>restarting</primary>
2436
2437         <secondary>server processes</secondary>
2438       </indexterm>
2439
2440       <indexterm>
2441         <primary>server process</primary>
2442
2443         <secondary>restarting specific processes</secondary>
2444       </indexterm>
2445     </sect2>
2446
2447     <sect2 id="Header_195">
2448       <title>To stop and immediately restart specific processes</title>
2449
2450       <orderedlist>
2451         <listitem>
2452           <para>Verify that you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue
2453           the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To
2454           display the users in the UserList file</link>. <programlisting>
2455    % <emphasis role="bold">bos listusers</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
2456 </programlisting></para>
2457         </listitem>
2458
2459         <listitem>
2460           <para>Issue the <emphasis role="bold">bos restart</emphasis> command to stop and immediately restart one or more specified
2461           processes, regardless of their status flag setting in the <emphasis role="bold">BosConfig</emphasis> file.
2462           <programlisting>
2463    % <emphasis role="bold">bos restart</emphasis> &lt;<replaceable>machine name</replaceable>&gt; &lt;<replaceable>instances</replaceable>&gt;+
2464 </programlisting></para>
2465
2466           <para>where <variablelist>
2467               <varlistentry>
2468                 <term><emphasis role="bold">res</emphasis></term>
2469
2470                 <listitem>
2471                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">restart</emphasis>.</para>
2472                 </listitem>
2473               </varlistentry>
2474
2475               <varlistentry>
2476                 <term><emphasis role="bold">machine name</emphasis></term>
2477
2478                 <listitem>
2479                   <para>Names the server machine on which to restart the specified processes.</para>
2480                 </listitem>
2481               </varlistentry>
2482
2483               <varlistentry>
2484                 <term><emphasis role="bold">instances</emphasis></term>
2485
2486                 <listitem>
2487                   <para>Specifies each process to stop and immediately restart. Use the name assigned to the process at
2488                   creation.</para>
2489                 </listitem>
2490               </varlistentry>
2491             </variablelist></para>
2492         </listitem>
2493       </orderedlist>
2494     </sect2>
2495   </sect1>
2496
2497   <sect1 id="HDRWQ171">
2498     <title>Setting the BOS Server's Restart Times</title>
2499
2500     <indexterm>
2501       <primary>core leak</primary>
2502
2503       <secondary>preventing with scheduled restarts</secondary>
2504     </indexterm>
2505
2506     <indexterm>
2507       <primary>preventing</primary>
2508
2509       <secondary>core leaks, with scheduled BOS Server restarts</secondary>
2510     </indexterm>
2511
2512     <indexterm>
2513       <primary>BOS Server</primary>
2514
2515       <secondary>restart times, displaying and setting</secondary>
2516     </indexterm>
2517
2518     <indexterm>
2519       <primary>automatic</primary>
2520
2521       <secondary>process restarts by BOS Server</secondary>
2522     </indexterm>
2523
2524     <indexterm>
2525       <primary>weekly restart of BOS Server (automatic)</primary>
2526
2527       <secondary>displaying and setting time</secondary>
2528     </indexterm>
2529
2530     <indexterm>
2531       <primary>restart time for BOS Server (automatic)</primary>
2532
2533       <secondary>displaying and setting time</secondary>
2534     </indexterm>
2535
2536     <indexterm>
2537       <primary>restart times for BOS Server</primary>
2538
2539       <secondary>displaying and setting</secondary>
2540     </indexterm>
2541
2542     <indexterm>
2543       <primary>daily restart for new binaries</primary>
2544
2545       <secondary>displaying and setting time</secondary>
2546     </indexterm>
2547
2548     <indexterm>
2549       <primary>restart times for BOS Server</primary>
2550
2551       <secondary>setting</secondary>
2552     </indexterm>
2553
2554     <para>The BOS Server by default has general restarts disabled. If you wish, it may be configured so that it
2555     restarts once a week, and the new instance restarts all processes marked with status flag
2556     <computeroutput>Run</computeroutput> in the local <emphasis role="bold">/usr/afs/local/BosConfig</emphasis> file (this is
2557     equivalent to issuing the <emphasis role="bold">bos restart</emphasis> command with the <emphasis
2558     role="bold">-bosserver</emphasis> flag). Historically, the default restart time was Sunday at 4:00 a.m - sites which have
2559     been upgraded from earlier versions of OpenAFS may find that this value is still present. The weekly restart was designed to
2560     minimize core leaks, which can develop as a process continues to allocate virtual memory but does not free it again. It is
2561     believed that these leaks have been fixed in OpenAFS.</para>
2562
2563     <para>The BOS Server also by default checks once a day for any newly installed binary files. If it finds that the modification
2564     time stamp on a process's binary file in the <emphasis role="bold">/usr/afs/bin</emphasis> directory is more recent than the
2565     time at which the process last started, it restarts the process so that a new instance starts using the new binary file. The
2566     default binary-checking time is 5:00 a.m.</para>
2567
2568     <para>Because restarts can cause outages during which the file system is inaccessible, the default times for restarts are in the
2569     early morning when usage is likely to be lowest. Restarting a database server process on any database server machine usually
2570     makes the entire system unavailable to everyone for a brief time, whereas restarting other types of processes inconveniences
2571     only users interacting with that process on that machine. The longest outages typically result from restarting the <emphasis
2572     role="bold">fs</emphasis> process, because the File Server must reattach all volumes.</para>
2573
2574     <indexterm>
2575       <primary>outages</primary>
2576
2577       <secondary>due to automatic server restart</secondary>
2578     </indexterm>
2579
2580     <indexterm>
2581       <primary>system outages</primary>
2582
2583       <secondary>due to automatic server restart</secondary>
2584     </indexterm>
2585
2586     <indexterm>
2587       <primary>BosConfig file</primary>
2588
2589       <secondary>restart times defined</secondary>
2590     </indexterm>
2591
2592     <para>The <emphasis role="bold">BosConfig</emphasis> file on each file server machine records the two restart times. To display
2593     the current setting, issue the <emphasis role="bold">bos getrestart</emphasis> command. To reset a time, use the <emphasis
2594     role="bold">bos setrestart</emphasis> command.</para>
2595
2596     <indexterm>
2597       <primary>bos commands</primary>
2598
2599       <secondary>getrestart</secondary>
2600     </indexterm>
2601
2602     <indexterm>
2603       <primary>commands</primary>
2604
2605       <secondary>bos getrestart</secondary>
2606     </indexterm>
2607
2608     <indexterm>
2609       <primary>displaying</primary>
2610
2611       <secondary>BOS Server's automatic restart times</secondary>
2612     </indexterm>
2613
2614     <sect2 id="Header_197">
2615       <title>To display the BOS Server restart times</title>
2616
2617       <orderedlist>
2618         <listitem>
2619           <para>Issue the <emphasis role="bold">bos getrestart</emphasis> command to display the automatic restart times.
2620           <programlisting>
2621    % <emphasis role="bold">bos getrestart</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
2622 </programlisting></para>
2623
2624           <para>where <variablelist>
2625               <varlistentry>
2626                 <term><emphasis role="bold">getr</emphasis></term>
2627
2628                 <listitem>
2629                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">getrestart</emphasis>.</para>
2630                 </listitem>
2631               </varlistentry>
2632
2633               <varlistentry>
2634                 <term><emphasis role="bold">machine name</emphasis></term>
2635
2636                 <listitem>
2637                   <para>Specifies the server machine for which to display the restart times.</para>
2638                 </listitem>
2639               </varlistentry>
2640             </variablelist></para>
2641         </listitem>
2642       </orderedlist>
2643
2644       <indexterm>
2645         <primary>bos commands</primary>
2646
2647         <secondary>setrestart</secondary>
2648       </indexterm>
2649
2650       <indexterm>
2651         <primary>commands</primary>
2652
2653         <secondary>bos setrestart</secondary>
2654       </indexterm>
2655
2656       <indexterm>
2657         <primary>setting</primary>
2658
2659         <secondary>BOS Server's automatic restart times</secondary>
2660       </indexterm>
2661     </sect2>
2662
2663     <sect2 id="HDRWQ172">
2664       <title>To set the general or binary restart time</title>
2665
2666       <orderedlist>
2667         <listitem>
2668           <para>Verify that you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue
2669           the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To
2670           display the users in the UserList file</link>. <programlisting>
2671    % <emphasis role="bold">bos listusers</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
2672 </programlisting></para>
2673         </listitem>
2674
2675         <listitem>
2676           <para>Issue the <emphasis role="bold">bos setrestart</emphasis> command with the <emphasis role="bold">-general</emphasis>
2677           flag to set the general restart time or the <emphasis role="bold">-newbinary</emphasis> flag to set the binary restart
2678           time. The command accepts only one of the flags at a time. <programlisting>
2679    % <emphasis role="bold">bos setrestart</emphasis> &lt;<replaceable>machine name</replaceable>&gt; "&lt;<replaceable>time to restart server</replaceable>&gt;" [<emphasis
2680                 role="bold">-general</emphasis>]  [<emphasis role="bold">-newbinary</emphasis>]
2681 </programlisting></para>
2682
2683           <para>where <variablelist>
2684               <varlistentry>
2685                 <term><emphasis role="bold">setr</emphasis></term>
2686
2687                 <listitem>
2688                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">setrestart</emphasis>.</para>
2689                 </listitem>
2690               </varlistentry>
2691
2692               <varlistentry>
2693                 <term><emphasis role="bold">machine name</emphasis></term>
2694
2695                 <listitem>
2696                   <para>Specifies the server machine.</para>
2697                 </listitem>
2698               </varlistentry>
2699
2700               <varlistentry>
2701                 <term><emphasis role="bold">time to restart server</emphasis></term>
2702
2703                 <listitem>
2704                   <para>Sets when the BOS Server restarts itself (if combined with the <emphasis role="bold">-general</emphasis>
2705                   flag) or any process with a new binary file (if combined with the <emphasis role="bold">-newbinary</emphasis>
2706                   flag). Provide one of the following types of values: <itemizedlist>
2707                       <listitem>
2708                         <para>The string <emphasis role="bold">never</emphasis>, which directs the BOS Server never to perform the
2709                         indicated type of restart.</para>
2710                       </listitem>
2711
2712                       <listitem>
2713                         <para>A time of day (the conventional type of value for the binary restart time). Separate the hours and
2714                         minutes with a colon (<emphasis>hh</emphasis>:<emphasis>MM</emphasis>), and use either 24-hour format, or a
2715                         value in the range from <emphasis role="bold">1:00</emphasis> through <emphasis role="bold">12:59</emphasis>
2716                         with the addition of <emphasis role="bold">am</emphasis> or <emphasis role="bold">pm</emphasis>. For
2717                         example, both <emphasis role="bold">14:30</emphasis> and <emphasis role="bold">"2:30 pm"</emphasis> indicate
2718                         2:30 in the afternoon. Surround this parameter with double quotes (<emphasis role="bold">" "</emphasis>) if
2719                         it contains a space.</para>
2720                       </listitem>
2721
2722                       <listitem>
2723                         <para>A day of the week and time of day, separated by a space and surrounded with double quotes (<emphasis
2724                         role="bold">" "</emphasis>). This is the conventional type of value for the general restart. For the day,
2725                         provide either the whole name or the first three letters, all in lowercase letters (<emphasis
2726                         role="bold">sunday</emphasis> or <emphasis role="bold">sun</emphasis>, <emphasis
2727                         role="bold">thursday</emphasis> or <emphasis role="bold">thu</emphasis>, and so on). For the time, use the
2728                         same format as when specifying the time alone.</para>
2729                       </listitem>
2730                     </itemizedlist></para>
2731
2732                   <para>If desired, precede a time or day and time definition with the string <emphasis role="bold">every</emphasis>
2733                   or <emphasis role="bold">at</emphasis>. These words do not change the meaning, but possibly make the output of the
2734                   <emphasis role="bold">bos getrestart</emphasis> command easier to understand.</para>
2735
2736                   <note>
2737                     <para>If the specified time is within one hour of the current time, the BOS Server does not perform the restart
2738                     until the next eligible time (the next day for a time or next week for a day and time).</para>
2739                   </note>
2740                 </listitem>
2741               </varlistentry>
2742
2743               <varlistentry>
2744                 <term><emphasis role="bold">-general</emphasis></term>
2745
2746                 <listitem>
2747                   <para>Sets the general restart time when the BOS Server restarts itself.</para>
2748                 </listitem>
2749               </varlistentry>
2750
2751               <varlistentry>
2752                 <term><emphasis role="bold">-newbinary</emphasis></term>
2753
2754                 <listitem>
2755                   <para>Sets the restart time for processes with new binary files.</para>
2756                 </listitem>
2757               </varlistentry>
2758             </variablelist></para>
2759         </listitem>
2760       </orderedlist>
2761     </sect2>
2762   </sect1>
2763
2764   <sect1 id="HDRWQ173">
2765     <title>Displaying Server Process Log Files</title>
2766
2767     <indexterm>
2768       <primary>file server machine</primary>
2769
2770       <secondary>displaying log files</secondary>
2771     </indexterm>
2772
2773     <indexterm>
2774       <primary>server process</primary>
2775
2776       <secondary>displaying log files</secondary>
2777     </indexterm>
2778
2779     <indexterm>
2780       <primary>log files</primary>
2781
2782       <secondary>displaying</secondary>
2783     </indexterm>
2784
2785     <indexterm>
2786       <primary>displaying</primary>
2787
2788       <secondary>log files for server processes</secondary>
2789     </indexterm>
2790
2791     <indexterm>
2792       <primary>files</primary>
2793
2794       <secondary>displaying log files</secondary>
2795     </indexterm>
2796
2797     <indexterm>
2798       <primary>FileLog file</primary>
2799
2800       <secondary>displaying</secondary>
2801     </indexterm>
2802
2803     <indexterm>
2804       <primary>SalvageLog file</primary>
2805
2806       <secondary>displaying</secondary>
2807     </indexterm>
2808
2809     <indexterm>
2810       <primary>VLLog file</primary>
2811
2812       <secondary>displaying</secondary>
2813     </indexterm>
2814
2815     <indexterm>
2816       <primary>VolserLog file</primary>
2817
2818       <secondary>displaying</secondary>
2819     </indexterm>
2820
2821     <indexterm>
2822       <primary>BackupLog file</primary>
2823
2824       <secondary>displaying</secondary>
2825     </indexterm>
2826
2827     <indexterm>
2828       <primary>BosLog file</primary>
2829
2830       <secondary>displaying</secondary>
2831     </indexterm>
2832
2833     <indexterm>
2834       <primary>AuthLog file</primary>
2835
2836       <secondary>displaying</secondary>
2837     </indexterm>
2838
2839     <indexterm>
2840       <primary>Authentication Server</primary>
2841
2842       <secondary>displaying log file</secondary>
2843     </indexterm>
2844
2845     <indexterm>
2846       <primary>Backup Server</primary>
2847
2848       <secondary>displaying log file</secondary>
2849     </indexterm>
2850
2851     <indexterm>
2852       <primary>BOS Server</primary>
2853
2854       <secondary>displaying log file</secondary>
2855     </indexterm>
2856
2857     <indexterm>
2858       <primary>File Server</primary>
2859
2860       <secondary>displaying log file</secondary>
2861     </indexterm>
2862
2863     <indexterm>
2864       <primary>Salvager</primary>
2865
2866       <secondary>displaying log file</secondary>
2867     </indexterm>
2868
2869     <indexterm>
2870       <primary>Volume Server</primary>
2871
2872       <secondary>displaying log file</secondary>
2873     </indexterm>
2874
2875     <para>The <emphasis role="bold">/usr/afs/logs</emphasis> directory on each file server machine contains log files that detail
2876     interesting events that occur during normal operation of some AFS server processes. The self-explanatory information in the log
2877     files can help you evaluate process failures and other problems. To display a log file remotely, issue the <emphasis
2878     role="bold">bos getlog</emphasis> command. You can also establish a connection to the server machine and use a text editor or
2879     other file display program (such as the <emphasis role="bold">cat</emphasis> command).</para>
2880
2881     <note>
2882       <para>Log files can grow unmanageably large if you do not periodically shutdown and restart the database server processes (for
2883       example, if you disable the general restart time). In this case it is a good policy periodically to issue the UNIX <emphasis
2884       role="bold">rm</emphasis> command to delete the current log file. The server process automatically creates a new one as
2885       needed.</para>
2886     </note>
2887
2888     <indexterm>
2889       <primary>bos commands</primary>
2890
2891       <secondary>getlog</secondary>
2892     </indexterm>
2893
2894     <indexterm>
2895       <primary>commands</primary>
2896
2897       <secondary>bos getlog</secondary>
2898     </indexterm>
2899
2900     <sect2 id="Header_200">
2901       <title>To examine a server process log file</title>
2902
2903       <orderedlist>
2904         <listitem>
2905           <para>Verify that you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue
2906           the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To
2907           display the users in the UserList file</link>. <programlisting>
2908    % <emphasis role="bold">bos listusers</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
2909 </programlisting></para>
2910         </listitem>
2911
2912         <listitem>
2913           <para>Issue the <emphasis role="bold">bos getlog</emphasis> command to display a log file. <programlisting>
2914    % <emphasis role="bold">bos getlog</emphasis>  &lt;<replaceable>machine name</replaceable>&gt;  &lt;<replaceable>log file to examine</replaceable>&gt;
2915 </programlisting></para>
2916
2917           <para>where <variablelist>
2918               <varlistentry>
2919                 <term><emphasis role="bold">getl</emphasis></term>
2920
2921                 <listitem>
2922                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">getlog</emphasis>.</para>
2923                 </listitem>
2924               </varlistentry>
2925
2926               <varlistentry>
2927                 <term><emphasis role="bold">machine name</emphasis></term>
2928
2929                 <listitem>
2930                   <para>Specifies the server machine from which to display the log file.</para>
2931                 </listitem>
2932               </varlistentry>
2933
2934               <varlistentry>
2935                 <term><emphasis role="bold">log file to examine</emphasis></term>
2936
2937                 <listitem>
2938                   <para>Names the log file to be displayed. Provide one of the following file names to display the indicated log
2939                   file from the <emphasis role="bold">/usr/afs/logs</emphasis> directory. <itemizedlist>
2940                       <listitem>
2941                         <para><emphasis role="bold">AuthLog</emphasis> for the Authentication Server log file</para>
2942                       </listitem>
2943
2944                       <listitem>
2945                         <para><emphasis role="bold">BackupLog</emphasis> for the Backup Server log file</para>
2946                       </listitem>
2947
2948                       <listitem>
2949                         <para><emphasis role="bold">BosLog</emphasis> for the BOS Server log file</para>
2950                       </listitem>
2951
2952                       <listitem>
2953                         <para><emphasis role="bold">FileLog</emphasis> for the File Server log file</para>
2954                       </listitem>
2955
2956                       <listitem>
2957                         <para><emphasis role="bold">SalvageLog</emphasis> for the Salvager log file</para>
2958                       </listitem>
2959
2960                       <listitem>
2961                         <para><emphasis role="bold">VLLog</emphasis> for the Volume Location (VL) Server log file</para>
2962                       </listitem>
2963
2964                       <listitem>
2965                         <para><emphasis role="bold">VolserLog</emphasis> for the Volume Server log file</para>
2966                       </listitem>
2967                     </itemizedlist></para>
2968
2969                   <para>You can provide a full or relative pathname to display a file from another directory. Relative pathnames are
2970                   interpreted relative to the <emphasis role="bold">/usr/afs/logs</emphasis> directory.</para>
2971                 </listitem>
2972               </varlistentry>
2973             </variablelist></para>
2974         </listitem>
2975       </orderedlist>
2976     </sect2>
2977   </sect1>
2978 </chapter>