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