0e1c10c80fb0860d435a36d92ba755b6cc6a8df6
[openafs.git] / doc / xml / AdminGuide / auagd008.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <chapter id="HDRWQ80">
3   <title>Administering Server Machines</title>
4
5   <indexterm>
6     <primary>server machine</primary>
7
8     <secondary>administering</secondary>
9   </indexterm>
10
11   <indexterm>
12     <primary>administering</primary>
13
14     <secondary>server machine</secondary>
15   </indexterm>
16
17   <para>This chapter describes how to administer an AFS server machine. It describes the following configuration information and
18   administrative tasks: <itemizedlist>
19       <listitem>
20         <para>The binary and configuration files that must reside in the subdirectories of the <emphasis
21         role="bold">/usr/afs</emphasis> directory on every server machine's local disk; see <link linkend="HDRWQ83">Local Disk Files
22         on a Server Machine</link>.</para>
23       </listitem>
24
25       <listitem>
26         <para>The various <emphasis>roles</emphasis> or functions that an AFS server machine can perform, and how to determine which
27         machines are taking a role; see <link linkend="HDRWQ90">The Four Roles for File Server Machines</link>.</para>
28       </listitem>
29
30       <listitem>
31         <para>How to maintain database server machines; see <link linkend="HDRWQ101">Administering Database Server
32         Machines</link>.</para>
33       </listitem>
34
35       <listitem>
36         <para>How to maintain the list of database server machines in the <emphasis role="bold">/usr/afs/etc/CellServDB</emphasis>
37         file; see <link linkend="HDRWQ118">Maintaining the Server CellServDB File</link>.</para>
38       </listitem>
39
40       <listitem>
41         <para>How to control authorization checking on a server machine; see <link linkend="HDRWQ123">Managing Authentication and
42         Authorization Requirements</link>.</para>
43       </listitem>
44
45       <listitem>
46         <para>How to install new disks or partitions on a file server machine; see <link linkend="HDRWQ130">Adding or Removing Disks
47         and Partitions</link>.</para>
48       </listitem>
49
50       <listitem>
51         <para>How to change a server machine's IP addresses and manager VLDB server entries; see <link linkend="HDRWQ138">Managing
52         Server IP Addresses and VLDB Server Entries</link>.</para>
53       </listitem>
54
55       <listitem>
56         <para>How to reboot a file server machine; see <link linkend="HDRWQ139">Rebooting a Server Machine</link>.</para>
57       </listitem>
58     </itemizedlist></para>
59
60   <para>To learn how to install and configure a new server machine, see the <emphasis>OpenAFS Quick Beginnings</emphasis>.</para>
61
62   <para>To learn how to administer the server processes themselves, see <link linkend="HDRWQ142">Monitoring and Controlling Server
63   Processes</link>.</para>
64
65   <para>To learn how to administer volumes, see <link linkend="HDRWQ174">Managing Volumes</link>.</para>
66
67   <sect1 id="HDRWQ81">
68     <title>Summary of Instructions</title>
69
70     <para>This chapter explains how to perform the following tasks by using the indicated commands:</para>
71
72     <informaltable frame="none">
73       <tgroup cols="2">
74         <colspec colwidth="70*" />
75
76         <colspec colwidth="30*" />
77
78         <tbody>
79           <row>
80             <entry>Install new binaries</entry>
81
82             <entry><emphasis role="bold">bos install</emphasis></entry>
83           </row>
84
85           <row>
86             <entry>Examine binary check-and-restart time</entry>
87
88             <entry><emphasis role="bold">bos getrestart</emphasis></entry>
89           </row>
90
91           <row>
92             <entry>Set binary check-and-restart time</entry>
93
94             <entry><emphasis role="bold">bos setrestart</emphasis></entry>
95           </row>
96
97           <row>
98             <entry>Examine compilation dates on binary files</entry>
99
100             <entry><emphasis role="bold">bos getdate</emphasis></entry>
101           </row>
102
103           <row>
104             <entry>Restart a process to use new binaries</entry>
105
106             <entry><emphasis role="bold">bos restart</emphasis></entry>
107           </row>
108
109           <row>
110             <entry>Revert to old version of binaries</entry>
111
112             <entry><emphasis role="bold">bos uninstall</emphasis></entry>
113           </row>
114
115           <row>
116             <entry>Remove obsolete <emphasis role="bold">.BAK</emphasis> and <emphasis role="bold">.OLD</emphasis> versions</entry>
117
118             <entry><emphasis role="bold">bos prune</emphasis></entry>
119           </row>
120
121           <row>
122             <entry>List partitions on a file server machine</entry>
123
124             <entry><emphasis role="bold">vos listpart</emphasis></entry>
125           </row>
126
127           <row>
128             <entry>Shutdown AFS server processes</entry>
129
130             <entry><emphasis role="bold">bos shutdown</emphasis></entry>
131           </row>
132
133           <row>
134             <entry>List volumes on a partition</entry>
135
136             <entry><emphasis role="bold">vos listvldb</emphasis></entry>
137           </row>
138
139           <row>
140             <entry>Move read/write volumes</entry>
141
142             <entry><emphasis role="bold">vos move</emphasis></entry>
143           </row>
144
145           <row>
146             <entry>List a cell's database server machines</entry>
147
148             <entry><emphasis role="bold">bos listhosts</emphasis></entry>
149           </row>
150
151           <row>
152             <entry>Add a database server machine to server <emphasis role="bold">CellServDB</emphasis> file</entry>
153
154             <entry><emphasis role="bold">bos addhost</emphasis></entry>
155           </row>
156
157           <row>
158             <entry>Remove a database server machine from server <emphasis role="bold">CellServDB</emphasis> file</entry>
159
160             <entry><emphasis role="bold">bos removehost</emphasis></entry>
161           </row>
162
163           <row>
164             <entry>Set authorization checking requirements</entry>
165
166             <entry><emphasis role="bold">bos setauth</emphasis></entry>
167           </row>
168
169           <row>
170             <entry>Prevent authentication for <emphasis role="bold">bos</emphasis>, <emphasis role="bold">pts</emphasis>, and
171             <emphasis role="bold">vos</emphasis> commands</entry>
172
173             <entry>Include <emphasis role="bold">-noauth</emphasis> flag</entry>
174           </row>
175
176           <row>
177             <entry>Prevent authentication for kas commands</entry>
178
179             <entry>Include <emphasis role="bold">-noauth</emphasis> flag on some commands or issue <emphasis
180             role="bold">noauthentication</emphasis> while in interactive mode</entry>
181           </row>
182
183           <row>
184             <entry>Display all VLDB server entries</entry>
185
186             <entry><emphasis role="bold">vos listaddrs</emphasis></entry>
187           </row>
188
189           <row>
190             <entry>Remove a VLDB server entry</entry>
191
192             <entry><emphasis role="bold">vos changeaddr</emphasis></entry>
193           </row>
194
195           <row>
196             <entry>Reboot a server machine remotely</entry>
197
198             <entry><emphasis role="bold">bos exec</emphasis> <emphasis>reboot_command</emphasis></entry>
199           </row>
200         </tbody>
201       </tgroup>
202     </informaltable>
203   </sect1>
204
205   <sect1 id="HDRWQ83">
206     <title>Local Disk Files on a Server Machine</title>
207
208     <para>Several types of files must reside in the subdirectories of the <emphasis role="bold">/usr/afs</emphasis> directory on an
209     AFS server machine's local disk. They include binaries, configuration files, the administrative database files (on database
210     server machines), log files, and volume header files.</para>
211
212     <para><emphasis role="bold">Note for Windows users:</emphasis> Some files described in this document possibly do not exist on
213     machines that run a Windows operating system. Also, Windows uses a backslash (<emphasis role="bold">\</emphasis>) rather than a
214     forward slash (<emphasis role="bold">/</emphasis>) to separate the elements in a pathname.</para>
215
216     <indexterm>
217       <primary>usr/afs/bin directory on server machines</primary>
218
219       <secondary>contents listed</secondary>
220     </indexterm>
221
222     <indexterm>
223       <primary>directory</primary>
224
225       <secondary>/usr/afs/bin on server machines</secondary>
226     </indexterm>
227
228     <indexterm>
229       <primary>server process binaries</primary>
230
231       <secondary>in /usr/afs/bin</secondary>
232     </indexterm>
233
234     <sect2 id="HDRWQ84">
235       <title>Binaries in the /usr/afs/bin Directory</title>
236
237       <para>The <emphasis role="bold">/usr/afs/bin</emphasis> directory stores the AFS server process and command suite binaries
238       appropriate for the machine's system (CPU and operating system) type. If a process has both a server portion and a client
239       portion (as with the Update Server) or if it has separate components (as with the <emphasis role="bold">fs</emphasis>
240       process), each component resides in a separate file.</para>
241
242       <para>To ensure predictable system performance, all file server machines must run the same AFS build version of a given
243       process. To maintain consistency easily, use the Update Server process to distribute binaries from a binary distribution
244       machine of each system type, as described further in <link linkend="HDRWQ93">Binary Distribution Machines</link>.</para>
245
246       <para>It is best to keep the binaries for all processes in the <emphasis role="bold">/usr/afs/bin</emphasis> directory, even
247       if you do not run the process actively on the machine. It simplifies the process of reconfiguring machines (for example,
248       adding database server functionality to an existing file server machine). Similarly, it is best to keep the command suite
249       binaries in the directory, even if you do not often issue commands while working on the server machine. It enables you to
250       issue commands during recovery from server and machine outages.</para>
251
252       <para>The following lists the binary files in the <emphasis role="bold">/usr/afs/bin</emphasis> directory that are directly
253       related to the AFS server processes or command suites. Other binaries (for example, for the <emphasis
254       role="bold">klog</emphasis> command) sometimes appear in this directory on a particular file server machine's disk or in an
255       AFS distribution. <variablelist>
256           <indexterm>
257             <primary>files</primary>
258
259             <secondary>backup command binary</secondary>
260           </indexterm>
261
262           <indexterm>
263             <primary>backup commands</primary>
264
265             <secondary>binary in /usr/afs/bin</secondary>
266           </indexterm>
267
268           <varlistentry>
269             <term><emphasis role="bold">backup</emphasis></term>
270
271             <listitem>
272               <para>The command suite for the AFS Backup System (the binary for the Backup Server is <emphasis
273               role="bold">buserver</emphasis>).</para>
274
275               <indexterm>
276                 <primary>files</primary>
277
278                 <secondary>bos command binary</secondary>
279               </indexterm>
280
281               <indexterm>
282                 <primary>bos commands</primary>
283
284                 <secondary>binary in /usr/afs/bin</secondary>
285               </indexterm>
286             </listitem>
287           </varlistentry>
288
289           <varlistentry>
290             <term><emphasis role="bold">bos</emphasis></term>
291
292             <listitem>
293               <para>The command suite for communicating with the Basic OverSeer (BOS) Server (the binary for the BOS Server is
294               <emphasis role="bold">bosserver</emphasis>).</para>
295
296               <indexterm>
297                 <primary>bosserver</primary>
298
299                 <secondary>binary in /usr/afs/bin</secondary>
300               </indexterm>
301
302               <indexterm>
303                 <primary>bosserver</primary>
304
305                 <secondary></secondary>
306
307                 <see>BOS Server</see>
308               </indexterm>
309
310               <indexterm>
311                 <primary>files</primary>
312
313                 <secondary>bosserver binary</secondary>
314               </indexterm>
315
316               <indexterm>
317                 <primary>programs</primary>
318
319                 <secondary>bosserver</secondary>
320               </indexterm>
321
322               <indexterm>
323                 <primary>processes</primary>
324
325                 <secondary>BOS Server, binary in /usr/afs/bin</secondary>
326               </indexterm>
327
328               <indexterm>
329                 <primary>BOS Server</primary>
330
331                 <secondary>binary in /usr/afs/bin</secondary>
332               </indexterm>
333             </listitem>
334           </varlistentry>
335
336           <varlistentry>
337             <term><emphasis role="bold">bosserver</emphasis></term>
338
339             <listitem>
340               <para>The binary for the Basic OverSeer (BOS) Server process.</para>
341
342               <indexterm>
343                 <primary>buserver</primary>
344
345                 <secondary>binary in /usr/afs/bin</secondary>
346               </indexterm>
347
348               <indexterm>
349                 <primary>buserver</primary>
350
351                 <secondary></secondary>
352
353                 <see>Backup Server</see>
354               </indexterm>
355
356               <indexterm>
357                 <primary>files</primary>
358
359                 <secondary>buserver</secondary>
360               </indexterm>
361
362               <indexterm>
363                 <primary>programs</primary>
364
365                 <secondary>buserver</secondary>
366               </indexterm>
367
368               <indexterm>
369                 <primary>processes</primary>
370
371                 <secondary>Backup Server, binary in /usr/afs/bin</secondary>
372               </indexterm>
373
374               <indexterm>
375                 <primary>Backup Server</primary>
376
377                 <secondary>binary in /usr/afs/bin</secondary>
378               </indexterm>
379             </listitem>
380           </varlistentry>
381
382           <varlistentry>
383             <term><emphasis role="bold">buserver</emphasis></term>
384
385             <listitem>
386               <para>The binary for the Backup Server process.</para>
387
388               <indexterm>
389                 <primary>fileserver</primary>
390
391                 <secondary>binary in /usr/afs/bin</secondary>
392               </indexterm>
393
394               <indexterm>
395                 <primary>fileserver</primary>
396
397                 <secondary></secondary>
398
399                 <see>File Server</see>
400               </indexterm>
401
402               <indexterm>
403                 <primary>files</primary>
404
405                 <secondary>fileserver</secondary>
406               </indexterm>
407
408               <indexterm>
409                 <primary>programs</primary>
410
411                 <secondary>fileserver</secondary>
412               </indexterm>
413
414               <indexterm>
415                 <primary>processes</primary>
416
417                 <secondary>File Server, binary in /usr/afs/bin</secondary>
418               </indexterm>
419
420               <indexterm>
421                 <primary>File Server</primary>
422
423                 <secondary>binary in /usr/afs/bin</secondary>
424               </indexterm>
425             </listitem>
426           </varlistentry>
427
428           <varlistentry>
429             <term><emphasis role="bold">fileserver</emphasis></term>
430
431             <listitem>
432               <para>The binary for the File Server component of the <emphasis role="bold">fs</emphasis> process.</para>
433
434               <indexterm>
435                 <primary>files</primary>
436
437                 <secondary>kas command binary</secondary>
438               </indexterm>
439
440               <indexterm>
441                 <primary>kas commands</primary>
442
443                 <secondary>binary in /usr/afs/bin</secondary>
444               </indexterm>
445             </listitem>
446           </varlistentry>
447
448           <varlistentry>
449             <term><emphasis role="bold">kas</emphasis></term>
450
451             <listitem>
452               <para>The command suite for communicating with the Authentication Server (the binary for the Authentication Server is
453               <emphasis role="bold">kaserver</emphasis>).</para>
454
455               <indexterm>
456                 <primary>kaserver process</primary>
457
458                 <secondary>binary in /usr/afs/bin</secondary>
459               </indexterm>
460
461               <indexterm>
462                 <primary>kaserver process</primary>
463
464                 <secondary></secondary>
465
466                 <see>Authentication Server</see>
467               </indexterm>
468
469               <indexterm>
470                 <primary>files</primary>
471
472                 <secondary>kaserver binary file</secondary>
473               </indexterm>
474
475               <indexterm>
476                 <primary>programs</primary>
477
478                 <secondary>kaserver</secondary>
479               </indexterm>
480
481               <indexterm>
482                 <primary>processes</primary>
483
484                 <secondary>Authentication Server, binary in /usr/afs/bin</secondary>
485               </indexterm>
486
487               <indexterm>
488                 <primary>Authentication Server</primary>
489
490                 <secondary>binary in /usr/afs/bin</secondary>
491               </indexterm>
492             </listitem>
493           </varlistentry>
494
495           <varlistentry>
496             <term><emphasis role="bold">kaserver</emphasis></term>
497
498             <listitem>
499               <para>The binary for the Authentication Server process.</para>
500
501               <indexterm>
502                 <primary>ntpd</primary>
503
504                 <secondary>binary in /usr/afs/bin</secondary>
505               </indexterm>
506
507               <indexterm>
508                 <primary>files</primary>
509
510                 <secondary>ntpd</secondary>
511               </indexterm>
512
513               <indexterm>
514                 <primary>programs</primary>
515
516                 <secondary>ntpd</secondary>
517               </indexterm>
518
519               <indexterm>
520                 <primary>processes</primary>
521
522                 <secondary>NTPD, binary in /usr/afs/bin</secondary>
523               </indexterm>
524
525               <indexterm>
526                 <primary>NTPD</primary>
527               </indexterm>
528
529               <indexterm>
530                 <primary>Network Time Protocol Daemon</primary>
531
532                 <secondary></secondary>
533
534                 <see>NTPD</see>
535               </indexterm>
536             </listitem>
537           </varlistentry>
538
539           <varlistentry>
540             <term><emphasis role="bold">ntpd</emphasis></term>
541
542             <listitem>
543               <para>The binary for the Network Time Protocol Daemon (NTPD). AFS redistributes this binary and uses the <emphasis
544               role="bold">runntp</emphasis> program to configure and initialize the NTPD process.</para>
545
546               <indexterm>
547                 <primary>ntpdc</primary>
548
549                 <secondary>binary in /usr/afs/bin</secondary>
550               </indexterm>
551
552               <indexterm>
553                 <primary>files</primary>
554
555                 <secondary>ntpdc</secondary>
556               </indexterm>
557
558               <indexterm>
559                 <primary>programs</primary>
560
561                 <secondary>ntpdc</secondary>
562               </indexterm>
563             </listitem>
564           </varlistentry>
565
566           <varlistentry>
567             <term><emphasis role="bold">ntpdc</emphasis></term>
568
569             <listitem>
570               <para>A debugging utility furnished with the <emphasis role="bold">ntpd</emphasis> program.</para>
571
572               <indexterm>
573                 <primary>files</primary>
574
575                 <secondary>pts command binary</secondary>
576               </indexterm>
577
578               <indexterm>
579                 <primary>pts commands</primary>
580
581                 <secondary>binary in /usr/afs/bin</secondary>
582               </indexterm>
583             </listitem>
584           </varlistentry>
585
586           <varlistentry>
587             <term><emphasis role="bold">pts</emphasis></term>
588
589             <listitem>
590               <para>The command suite for communicating with the Protection Server process (the binary for the Protection Server is
591               <emphasis role="bold">ptserver</emphasis>).</para>
592
593               <indexterm>
594                 <primary>ptserver process</primary>
595
596                 <secondary>binary in /usr/afs/bin</secondary>
597               </indexterm>
598
599               <indexterm>
600                 <primary>ptserver process</primary>
601
602                 <secondary></secondary>
603
604                 <see>Protection Server</see>
605               </indexterm>
606
607               <indexterm>
608                 <primary>files</primary>
609
610                 <secondary>ptserver binary</secondary>
611               </indexterm>
612
613               <indexterm>
614                 <primary>programs</primary>
615
616                 <secondary>ptserver</secondary>
617               </indexterm>
618
619               <indexterm>
620                 <primary>processes</primary>
621
622                 <secondary>Protection Server, binary in /usr/afs/bin</secondary>
623               </indexterm>
624
625               <indexterm>
626                 <primary>Protection Server</primary>
627
628                 <secondary>binary in /usr/afs/bin</secondary>
629               </indexterm>
630             </listitem>
631           </varlistentry>
632
633           <varlistentry>
634             <term><emphasis role="bold">ptserver</emphasis></term>
635
636             <listitem>
637               <para>The binary for the Protection Server process.</para>
638
639               <indexterm>
640                 <primary>runntp</primary>
641
642                 <secondary>binary in /usr/afs/bin</secondary>
643               </indexterm>
644
645               <indexterm>
646                 <primary>runntp</primary>
647
648                 <secondary></secondary>
649
650                 <see>NTPD</see>
651               </indexterm>
652
653               <indexterm>
654                 <primary>files</primary>
655
656                 <secondary>runntp</secondary>
657               </indexterm>
658
659               <indexterm>
660                 <primary>programs</primary>
661
662                 <secondary>runntp</secondary>
663               </indexterm>
664             </listitem>
665           </varlistentry>
666
667           <varlistentry>
668             <term><emphasis role="bold">runntp</emphasis></term>
669
670             <listitem>
671               <para>The binary for the program used to configure NTPD most appropriately for use with AFS.</para>
672
673               <indexterm>
674                 <primary>Salvager</primary>
675
676                 <secondary>binary in /usr/afs/bin</secondary>
677               </indexterm>
678
679               <indexterm>
680                 <primary>Salvager</primary>
681
682                 <secondary></secondary>
683
684                 <see>Salvager</see>
685               </indexterm>
686
687               <indexterm>
688                 <primary>files</primary>
689
690                 <secondary>salvager</secondary>
691               </indexterm>
692
693               <indexterm>
694                 <primary>programs</primary>
695
696                 <secondary>salvager</secondary>
697               </indexterm>
698
699               <indexterm>
700                 <primary>processes</primary>
701
702                 <secondary>Salvager, binary in /usr/afs/bin</secondary>
703               </indexterm>
704             </listitem>
705           </varlistentry>
706
707           <varlistentry>
708             <term><emphasis role="bold">salvager</emphasis></term>
709
710             <listitem>
711               <para>The binary for the Salvager component of the <emphasis role="bold">fs</emphasis> process.</para>
712
713               <indexterm>
714                 <primary>udebug</primary>
715
716                 <secondary>binary in /usr/afs/bin</secondary>
717               </indexterm>
718
719               <indexterm>
720                 <primary>files</primary>
721
722                 <secondary>udebug</secondary>
723               </indexterm>
724
725               <indexterm>
726                 <primary>commands</primary>
727
728                 <secondary>udebug</secondary>
729               </indexterm>
730
731               <indexterm>
732                 <primary>programs</primary>
733
734                 <secondary>udebug</secondary>
735               </indexterm>
736             </listitem>
737           </varlistentry>
738
739           <varlistentry>
740             <term><emphasis role="bold">udebug</emphasis></term>
741
742             <listitem>
743               <para>The binary for a program that reports the status of AFS's distributed database technology, Ubik.</para>
744
745               <indexterm>
746                 <primary>upclient</primary>
747
748                 <secondary>binary in /usr/afs/bin</secondary>
749               </indexterm>
750
751               <indexterm>
752                 <primary>upclient</primary>
753
754                 <secondary></secondary>
755
756                 <see>Update Server</see>
757               </indexterm>
758
759               <indexterm>
760                 <primary>files</primary>
761
762                 <secondary>upclient</secondary>
763               </indexterm>
764
765               <indexterm>
766                 <primary>programs</primary>
767
768                 <secondary>upclient</secondary>
769               </indexterm>
770
771               <indexterm>
772                 <primary>processes</primary>
773
774                 <secondary>Update Server, binaries in /usr/afs/bin</secondary>
775               </indexterm>
776
777               <indexterm>
778                 <primary>Update Server</primary>
779
780                 <secondary>binaries in /usr/afs/bin</secondary>
781               </indexterm>
782             </listitem>
783           </varlistentry>
784
785           <varlistentry>
786             <term><emphasis role="bold">upclient</emphasis></term>
787
788             <listitem>
789               <para>The binary for the client portion of the Update Server process.</para>
790
791               <indexterm>
792                 <primary>upserver</primary>
793
794                 <secondary>binary in /usr/afs/bin</secondary>
795               </indexterm>
796
797               <indexterm>
798                 <primary>upserver</primary>
799
800                 <secondary></secondary>
801
802                 <see>Update Server</see>
803               </indexterm>
804
805               <indexterm>
806                 <primary>files</primary>
807
808                 <secondary>upserver</secondary>
809               </indexterm>
810
811               <indexterm>
812                 <primary>programs</primary>
813
814                 <secondary>upserver</secondary>
815               </indexterm>
816             </listitem>
817           </varlistentry>
818
819           <varlistentry>
820             <term><emphasis role="bold">upserver</emphasis></term>
821
822             <listitem>
823               <para>The binary for the server portion of the Update Server process.</para>
824
825               <indexterm>
826                 <primary>vlserver</primary>
827
828                 <secondary>binary in /usr/afs/bin</secondary>
829               </indexterm>
830
831               <indexterm>
832                 <primary>vlserver</primary>
833
834                 <secondary></secondary>
835
836                 <see>VL Server</see>
837               </indexterm>
838
839               <indexterm>
840                 <primary>files</primary>
841
842                 <secondary>vlserver</secondary>
843               </indexterm>
844
845               <indexterm>
846                 <primary>programs</primary>
847
848                 <secondary>vlserver</secondary>
849               </indexterm>
850
851               <indexterm>
852                 <primary>processes</primary>
853
854                 <secondary>VL Server, binary in /usr/afs/bin</secondary>
855               </indexterm>
856
857               <indexterm>
858                 <primary>VL Server</primary>
859
860                 <secondary>binary in /usr/afs/bin</secondary>
861               </indexterm>
862
863               <indexterm>
864                 <primary>Volume Location Server</primary>
865
866                 <secondary></secondary>
867
868                 <see>VL Server</see>
869               </indexterm>
870             </listitem>
871           </varlistentry>
872
873           <varlistentry>
874             <term><emphasis role="bold">vlserver</emphasis></term>
875
876             <listitem>
877               <para>The binary for the Volume Location (VL) Server process.</para>
878
879               <indexterm>
880                 <primary>volserver</primary>
881
882                 <secondary>binary in /usr/afs/bin</secondary>
883               </indexterm>
884
885               <indexterm>
886                 <primary>volserver</primary>
887
888                 <secondary></secondary>
889
890                 <see>Volume Server</see>
891               </indexterm>
892
893               <indexterm>
894                 <primary>files</primary>
895
896                 <secondary>volserver</secondary>
897               </indexterm>
898
899               <indexterm>
900                 <primary>programs</primary>
901
902                 <secondary>volserver</secondary>
903               </indexterm>
904
905               <indexterm>
906                 <primary>processes</primary>
907
908                 <secondary>Volume Server, binary in /usr/afs/bin</secondary>
909               </indexterm>
910
911               <indexterm>
912                 <primary>Volume Server</primary>
913
914                 <secondary>binary in /usr/afs/bin</secondary>
915               </indexterm>
916             </listitem>
917           </varlistentry>
918
919           <varlistentry>
920             <term><emphasis role="bold">volserver</emphasis></term>
921
922             <listitem>
923               <para>The binary for the Volume Server component of the <emphasis role="bold">fs</emphasis> process.</para>
924
925               <indexterm>
926                 <primary>files</primary>
927
928                 <secondary>vos command binary</secondary>
929               </indexterm>
930
931               <indexterm>
932                 <primary>vos commands</primary>
933
934                 <secondary>binary in /usr/afs/bin</secondary>
935               </indexterm>
936             </listitem>
937           </varlistentry>
938
939           <varlistentry>
940             <term><emphasis role="bold">vos</emphasis></term>
941
942             <listitem>
943               <para>The command suite for communicating with the Volume and VL Server processes (the binaries for the servers are
944               <emphasis role="bold">volserver</emphasis> and <emphasis role="bold">vlserver</emphasis>, respectively).</para>
945             </listitem>
946           </varlistentry>
947         </variablelist></para>
948
949       <indexterm>
950         <primary>usr/afs/etc directory on server machines</primary>
951
952         <secondary>contents listed</secondary>
953       </indexterm>
954
955       <indexterm>
956         <primary>directory</primary>
957
958         <secondary>/usr/afs/etc</secondary>
959       </indexterm>
960
961       <indexterm>
962         <primary>files</primary>
963
964         <secondary>server configuration, in /usr/afs/etc directory</secondary>
965       </indexterm>
966
967       <indexterm>
968         <primary>common configuration files (server)</primary>
969       </indexterm>
970
971       <indexterm>
972         <primary>server machine</primary>
973
974         <secondary>configuration files in /usr/afs/etc</secondary>
975       </indexterm>
976     </sect2>
977
978     <sect2 id="HDRWQ85">
979       <title>Common Configuration Files in the /usr/afs/etc Directory</title>
980
981       <para>The directory <emphasis role="bold">/usr/afs/etc</emphasis> on every file server machine's local disk contains
982       configuration files in ASCII and machine-independent binary format. For predictable AFS performance throughout a cell, all
983       server machines must have the same version of each configuration file: <itemizedlist>
984           <indexterm>
985             <primary>Update Server</primary>
986
987             <secondary>distributing server configuration files</secondary>
988           </indexterm>
989
990           <listitem>
991             <para>Cells that run the United States edition of AFS conventionally use the Update Server to distribute a common
992             version of each file from the cell's system control machine to other server machines (for more on the system control
993             machine, see <link linkend="HDRWQ94">The System Control Machine</link>). Run the Update Server's server portion on the
994             system control machine, and the client portion on all other server machines. Update the files on the system control
995             machine only, except as directed by instructions for dealing with emergencies.</para>
996           </listitem>
997
998           <listitem>
999             <para>Cells that run the international edition of AFS must not use the Update Server to distribute the contents of the
1000             <emphasis role="bold">/usr/afs/etc</emphasis> directory. Due to United States government regulations, the data
1001             encryption routines that AFS uses to protect the files in this directory as they cross the network are not available to
1002             the Update Server in the international edition of AFS. You must instead update the files on each server machine
1003             individually, taking extra care to issue exactly the same <emphasis role="bold">bos</emphasis> command for each machine.
1004             The necessary data encryption routines are available to the <emphasis role="bold">bos</emphasis> commands, so
1005             information is safe as it crosses the network from the machine where the <emphasis role="bold">bos</emphasis> command is
1006             issued to the server machines.</para>
1007           </listitem>
1008         </itemizedlist></para>
1009
1010       <para>Never directly edit any of the files in the <emphasis role="bold">/usr/afs/etc</emphasis> directory, except as directed
1011       by instructions for dealing with emergencies. In normal circumstances, use the appropriate <emphasis
1012       role="bold">bos</emphasis> commands to change the files. The following list includes pointers to instructions.</para>
1013
1014       <para>The files in this directory include: <variablelist>
1015           <indexterm>
1016             <primary>CellServDB file (server)</primary>
1017
1018             <secondary>about</secondary>
1019           </indexterm>
1020
1021           <indexterm>
1022             <primary>files</primary>
1023
1024             <secondary>CellServDB (server)</secondary>
1025           </indexterm>
1026
1027           <varlistentry>
1028             <term><emphasis role="bold">CellServDB</emphasis></term>
1029
1030             <listitem>
1031               <para>An ASCII file that names the cell's database server machines, which run the Authentication, Backup, Protection,
1032               and VL Server processes. You create the initial version of this file by issuing the <emphasis role="bold">bos
1033               setcellname</emphasis> command while installing your cell's first server machine. It is very important to update this
1034               file when you change the identity of your cell's database server machines.</para>
1035
1036               <para>The server <emphasis role="bold">CellServDB</emphasis> file is not the same as the <emphasis
1037               role="bold">CellServDB</emphasis> file stored in the <emphasis role="bold">/usr/vice/etc</emphasis> directory on
1038               client machines. The client version lists the database server machines for every AFS cell that you choose to make
1039               accessible from the client machine. The server <emphasis role="bold">CellServDB</emphasis> file lists only the local
1040               cell's database server machines, because server processes never contact processes in other cells.</para>
1041
1042               <para>For instructions on maintaining this file, see <link linkend="HDRWQ118">Maintaining the Server CellServDB
1043               File</link>.</para>
1044
1045               <indexterm>
1046                 <primary>KeyFile file</primary>
1047
1048                 <secondary>function of</secondary>
1049               </indexterm>
1050
1051               <indexterm>
1052                 <primary>files</primary>
1053
1054                 <secondary>KeyFile</secondary>
1055               </indexterm>
1056
1057               <indexterm>
1058                 <primary>server encryption key</primary>
1059               </indexterm>
1060             </listitem>
1061           </varlistentry>
1062
1063           <varlistentry>
1064             <term><emphasis role="bold">KeyFile</emphasis></term>
1065
1066             <listitem>
1067               <para>A machine-independent, binary-format file that lists the server encryption keys the AFS server processes use to
1068               encrypt and decrypt tickets. The information in this file is the basis for secure communication in the cell, and so is
1069               extremely sensitive. The file is specially protected so that only privileged users can read or change it.</para>
1070
1071               <para>For instructions on maintaining this file, see <link linkend="HDRWQ355">Managing Server Encryption
1072               Keys</link>.</para>
1073
1074               <indexterm>
1075                 <primary>ThisCell file (server)</primary>
1076               </indexterm>
1077
1078               <indexterm>
1079                 <primary>files</primary>
1080
1081                 <secondary>ThisCell (server)</secondary>
1082               </indexterm>
1083             </listitem>
1084           </varlistentry>
1085
1086           <varlistentry>
1087             <term><emphasis role="bold">ThisCell</emphasis></term>
1088
1089             <listitem>
1090               <para>An ASCII file that consists of a single line defining the complete Internet domain-style name of the cell (such
1091               as <computeroutput>abc.com</computeroutput>). You create this file with the <emphasis role="bold">bos
1092               setcellname</emphasis> command during the installation of your cell's first file server machine, as instructed in the
1093               <emphasis>OpenAFS Quick Beginnings</emphasis>.</para>
1094
1095               <para>Note that changing this file is only one step in changing your cell's name. For discussion, see <link
1096               linkend="HDRWQ34">Choosing a Cell Name</link>.</para>
1097
1098               <indexterm>
1099                 <primary>UserList file</primary>
1100               </indexterm>
1101
1102               <indexterm>
1103                 <primary>files</primary>
1104
1105                 <secondary>UserList</secondary>
1106               </indexterm>
1107             </listitem>
1108           </varlistentry>
1109
1110           <varlistentry>
1111             <term><emphasis role="bold">UserList</emphasis></term>
1112
1113             <listitem>
1114               <para>An ASCII file that lists the usernames of the system administrators authorized to issue privileged <emphasis
1115               role="bold">bos</emphasis>, <emphasis role="bold">vos</emphasis>, and <emphasis role="bold">backup</emphasis>
1116               commands. For instructions on maintaining the file, see <link linkend="HDRWQ592">Administering the UserList
1117               File</link>.</para>
1118             </listitem>
1119           </varlistentry>
1120         </variablelist></para>
1121
1122       <indexterm>
1123         <primary>usr/afs/local directory on server machines</primary>
1124
1125         <secondary>contents listed</secondary>
1126       </indexterm>
1127
1128       <indexterm>
1129         <primary>directory</primary>
1130
1131         <secondary>/usr/afs/local on server machines</secondary>
1132       </indexterm>
1133
1134       <indexterm>
1135         <primary>local configuration files (server)</primary>
1136       </indexterm>
1137
1138       <indexterm>
1139         <primary>file server machine</primary>
1140
1141         <secondary>configuration files in /usr/afs/local</secondary>
1142       </indexterm>
1143     </sect2>
1144
1145     <sect2 id="HDRWQ86">
1146       <title>Local Configuration Files in the /usr/afs/local Directory</title>
1147
1148       <para>The directory <emphasis role="bold">/usr/afs/local</emphasis> contains configuration files that are different for each
1149       file server machine in a cell. Thus, they are not updated automatically from a central source like the files in <emphasis
1150       role="bold">/usr/afs/bin</emphasis> and <emphasis role="bold">/usr/afs/etc</emphasis> directories. The most important file is
1151       the <emphasis role="bold">BosConfig</emphasis> file; it defines which server processes are to run on that machine.</para>
1152
1153       <para>As with the common configuration files in <emphasis role="bold">/usr/afs/etc</emphasis>, you must not edit these files
1154       directly. Use commands from the <emphasis role="bold">bos</emphasis> command suite where appropriate; some files never need to
1155       be altered.</para>
1156
1157       <para>The files in this directory include the following: <variablelist>
1158           <indexterm>
1159             <primary>BosConfig file</primary>
1160           </indexterm>
1161
1162           <indexterm>
1163             <primary>files</primary>
1164
1165             <secondary>BosConfig</secondary>
1166           </indexterm>
1167
1168           <varlistentry>
1169             <term><emphasis role="bold">BosConfig</emphasis></term>
1170
1171             <listitem>
1172               <para>This file lists the server processes to run on the server machine, by defining which processes the BOS Server
1173               monitors and what it does if the process fails. It also defines the times at which the BOS Server automatically
1174               restarts processes for maintenance purposes.</para>
1175
1176               <para>As you create server processes during a file server machine's installation, their entries are defined in this
1177               file automatically. The <emphasis>OpenAFS Quick Beginnings</emphasis> outlines the <emphasis
1178               role="bold">bos</emphasis> commands to use. For a more complete description of the file, and instructions for
1179               controlling process status by editing the file with commands from the <emphasis role="bold">bos</emphasis> suite, see
1180               <link linkend="HDRWQ142">Monitoring and Controlling Server Processes</link>.</para>
1181
1182               <indexterm>
1183                 <primary>NetInfo file (server version)</primary>
1184               </indexterm>
1185
1186               <indexterm>
1187                 <primary>files</primary>
1188
1189                 <secondary>NetInfo (server version)</secondary>
1190               </indexterm>
1191             </listitem>
1192           </varlistentry>
1193
1194           <varlistentry>
1195             <term><emphasis role="bold">NetInfo</emphasis></term>
1196
1197             <listitem>
1198               <para>This optional ASCII file lists one or more of the network interface addresses on the server machine. If it
1199               exists when the File Server initializes, the File Server uses it as the basis for the list of interfaces that it
1200               registers in its Volume Location Database (VLDB) server entry. See <link linkend="HDRWQ138">Managing Server IP
1201               Addresses and VLDB Server Entries</link>.</para>
1202
1203               <indexterm>
1204                 <primary>NetRestrict file (server version)</primary>
1205               </indexterm>
1206
1207               <indexterm>
1208                 <primary>files</primary>
1209
1210                 <secondary>NetRestrict (server version)</secondary>
1211               </indexterm>
1212             </listitem>
1213           </varlistentry>
1214
1215           <varlistentry>
1216             <term><emphasis role="bold">NetRestrict</emphasis></term>
1217
1218             <listitem>
1219               <para>This optional ASCII file lists one or more network interface addresses. If it exists when the File Server
1220               initializes, the File Server removes the specified addresses from the list of interfaces that it registers in its VLDB
1221               server entry. See <link linkend="HDRWQ138">Managing Server IP Addresses and VLDB Server Entries</link>.</para>
1222
1223               <indexterm>
1224                 <primary>NoAuth file</primary>
1225               </indexterm>
1226
1227               <indexterm>
1228                 <primary>files</primary>
1229
1230                 <secondary>NoAuth</secondary>
1231               </indexterm>
1232             </listitem>
1233           </varlistentry>
1234
1235           <varlistentry>
1236             <term><emphasis role="bold">NoAuth</emphasis></term>
1237
1238             <listitem>
1239               <para>This zero-length file instructs all AFS server processes running on the machine not to perform authorization
1240               checking. Thus, they perform any action for any user, even <emphasis role="bold">anonymous</emphasis>. This very
1241               insecure state is useful only in rare instances, mainly during the installation of the machine.</para>
1242
1243               <para>The file is created automatically when you start the initial <emphasis role="bold">bosserver</emphasis> process
1244               with the <emphasis role="bold">-noauth</emphasis> flag, or issue the <emphasis role="bold">bos setauth</emphasis>
1245               command to turn off authentication requirements. When you use the <emphasis role="bold">bos setauth</emphasis> command
1246               to turn on authentication, the BOS Server removes this file. For more information, see <link
1247               linkend="HDRWQ123">Managing Authentication and Authorization Requirements</link>.</para>
1248
1249               <indexterm>
1250                 <primary>SALVAGE.fs file</primary>
1251               </indexterm>
1252
1253               <indexterm>
1254                 <primary>files</primary>
1255
1256                 <secondary>SALVAGE.fs</secondary>
1257               </indexterm>
1258             </listitem>
1259           </varlistentry>
1260
1261           <varlistentry>
1262             <term><emphasis role="bold">SALVAGE.fs</emphasis></term>
1263
1264             <listitem>
1265               <para>This zero-length file controls how the BOS Server handles a crash of the File Server component of the <emphasis
1266               role="bold">fs</emphasis> process. The BOS Server creates this file each time it starts or restarts the <emphasis
1267               role="bold">fs</emphasis> process. If the file is present when the File Server crashes, then the BOS Server runs the
1268               Salvager before restarting the File Server and Volume Server again. When the File Server exits normally, the BOS
1269               Server removes the file so that the Salvager does not run.</para>
1270
1271               <para>Do not create or remove this file yourself; the BOS Server does so automatically. If necessary, you can salvage
1272               a volume or partition by using the <emphasis role="bold">bos salvage</emphasis> command; see <link
1273               linkend="HDRWQ232">Salvaging Volumes</link>.</para>
1274
1275               <indexterm>
1276                 <primary>salvage.lock file</primary>
1277               </indexterm>
1278
1279               <indexterm>
1280                 <primary>files</primary>
1281
1282                 <secondary>salvage.lock</secondary>
1283               </indexterm>
1284             </listitem>
1285           </varlistentry>
1286
1287           <varlistentry>
1288             <term><emphasis role="bold">salvage.lock</emphasis></term>
1289
1290             <listitem>
1291               <para>This file guarantees that only one Salvager process runs on a file server machine at a time (the single process
1292               can fork multiple subprocesses to salvage multiple partitions in parallel). As the Salvager initiates (when invoked by
1293               the BOS Server or by issue of the <emphasis role="bold">bos salvage</emphasis> command), it creates this zero-length
1294               file and issues the <emphasis role="bold">flock</emphasis> system call on it. It removes the file when it completes
1295               the salvage operation. Because the Salvager must lock the file in order to run, only one Salvager can run at a
1296               time.</para>
1297
1298               <indexterm>
1299                 <primary>sysid file</primary>
1300               </indexterm>
1301
1302               <indexterm>
1303                 <primary>files</primary>
1304
1305                 <secondary>sysid</secondary>
1306               </indexterm>
1307
1308               <indexterm>
1309                 <primary>File Server</primary>
1310
1311                 <secondary>interfaces registered in VLDB</secondary>
1312
1313                 <tertiary>listed in sysid file</tertiary>
1314               </indexterm>
1315
1316               <indexterm>
1317                 <primary>VLDB</primary>
1318
1319                 <secondary>server machine interfaces registered</secondary>
1320
1321                 <tertiary>listed in sysid file</tertiary>
1322               </indexterm>
1323             </listitem>
1324           </varlistentry>
1325
1326           <varlistentry>
1327             <term><emphasis role="bold">sysid</emphasis></term>
1328
1329             <listitem>
1330               <para>This file records the network interface addresses that the File Server (<emphasis
1331               role="bold">fileserver</emphasis> process) registers in its VLDB server entry. When the Cache Manager requests volume
1332               location information, the Volume Location (VL) Server provides all of the interfaces registered for each server
1333               machine that houses the volume. This enables the Cache Manager to make use of multiple addresses when accessing AFS
1334               data stored on a multihomed file server machine. For further information, see <link linkend="HDRWQ138">Managing Server
1335               IP Addresses and VLDB Server Entries</link>.</para>
1336             </listitem>
1337           </varlistentry>
1338         </variablelist></para>
1339
1340       <indexterm>
1341         <primary>usr/afs/db directory on server machines</primary>
1342
1343         <secondary>contents listed</secondary>
1344       </indexterm>
1345
1346       <indexterm>
1347         <primary>directory</primary>
1348
1349         <secondary>/usr/afs/db on server machines</secondary>
1350       </indexterm>
1351
1352       <indexterm>
1353         <primary>database files</primary>
1354       </indexterm>
1355
1356       <indexterm>
1357         <primary>replicated database files</primary>
1358       </indexterm>
1359
1360       <indexterm>
1361         <primary>log files</primary>
1362
1363         <secondary>for replicated databases</secondary>
1364       </indexterm>
1365
1366       <indexterm>
1367         <primary>file server machine</primary>
1368
1369         <secondary>database files in /usr/afs/db</secondary>
1370       </indexterm>
1371     </sect2>
1372
1373     <sect2 id="HDRWQ87">
1374       <title>Replicated Database Files in the /usr/afs/db Directory</title>
1375
1376       <para>The directory <emphasis role="bold">/usr/afs/db</emphasis> contains two types of files pertaining to the four replicated
1377       databases in the cell--the Authentication Database, Backup Database, Protection Database, and Volume Location Database (VLDB):
1378       <itemizedlist>
1379           <listitem>
1380             <para>A file that contains each database, with a <emphasis role="bold">.DB0</emphasis> extension.</para>
1381           </listitem>
1382
1383           <listitem>
1384             <para>A log file for each database, with a <emphasis role="bold">.DBSYS1</emphasis> extension. The database server
1385             process logs each database operation in this file before performing it. If the operation is interrupted, the process
1386             consults this file to learn how to finish it.</para>
1387           </listitem>
1388         </itemizedlist></para>
1389
1390       <para>Each database server process (Authentication, Backup, Protection, or VL Server) maintains its own database and log
1391       files. The database files are in binary format, so you must always access or alter them using commands from the <emphasis
1392       role="bold">kas</emphasis> suite (for the Authentication Database), <emphasis role="bold">backup</emphasis> suite (for the
1393       Backup Database), <emphasis role="bold">pts</emphasis> suite (for the Protection Database), or <emphasis
1394       role="bold">vos</emphasis> suite (for the VLDB).</para>
1395
1396       <para>If a cell runs more than one database server machine, each database server process keeps its own copy of its database on
1397       its machine's hard disk. However, it is important that all the copies of a given database are the same. To synchronize them,
1398       the database server processes call on AFS's distributed database technology, Ubik, as described in <link
1399       linkend="HDRWQ102">Replicating the OpenAFS Administrative Databases</link>.</para>
1400
1401       <para>The files listed here appear in this directory only on database server machines. On non-database server machines, this
1402       directory is empty. <variablelist>
1403           <indexterm>
1404             <primary>files</primary>
1405
1406             <secondary>bdb.DB0</secondary>
1407           </indexterm>
1408
1409           <indexterm>
1410             <primary>bdb.DB0 file</primary>
1411           </indexterm>
1412
1413           <varlistentry>
1414             <term><emphasis role="bold">bdb.DB0</emphasis></term>
1415
1416             <listitem>
1417               <para>The Backup Database file.</para>
1418
1419               <indexterm>
1420                 <primary>files</primary>
1421
1422                 <secondary>bdb.DBSYS1</secondary>
1423               </indexterm>
1424
1425               <indexterm>
1426                 <primary>bdb.DBSYS1 file</primary>
1427               </indexterm>
1428             </listitem>
1429           </varlistentry>
1430
1431           <varlistentry>
1432             <term><emphasis role="bold">bdb.DBSYS1</emphasis></term>
1433
1434             <listitem>
1435               <para>The Backup Database log file.</para>
1436
1437               <indexterm>
1438                 <primary>files</primary>
1439
1440                 <secondary>kaserver.DB0</secondary>
1441               </indexterm>
1442
1443               <indexterm>
1444                 <primary>kaserver.DB0 file</primary>
1445               </indexterm>
1446             </listitem>
1447           </varlistentry>
1448
1449           <varlistentry>
1450             <term><emphasis role="bold">kaserver.DB0</emphasis></term>
1451
1452             <listitem>
1453               <para>The Authentication Database file.</para>
1454
1455               <indexterm>
1456                 <primary>files</primary>
1457
1458                 <secondary>kaserver.DBSYS1</secondary>
1459               </indexterm>
1460
1461               <indexterm>
1462                 <primary>kaserver.DBSYS1 file</primary>
1463               </indexterm>
1464             </listitem>
1465           </varlistentry>
1466
1467           <varlistentry>
1468             <term><emphasis role="bold">kaserver.DBSYS1</emphasis></term>
1469
1470             <listitem>
1471               <para>The Authentication Database log file.</para>
1472
1473               <indexterm>
1474                 <primary>files</primary>
1475
1476                 <secondary>prdb.DB0</secondary>
1477               </indexterm>
1478
1479               <indexterm>
1480                 <primary>prdb.DB0 file</primary>
1481               </indexterm>
1482             </listitem>
1483           </varlistentry>
1484
1485           <varlistentry>
1486             <term><emphasis role="bold">prdb.DB0</emphasis></term>
1487
1488             <listitem>
1489               <para>The Protection Database file.</para>
1490
1491               <indexterm>
1492                 <primary>files</primary>
1493
1494                 <secondary>prdb.DBSYS1</secondary>
1495               </indexterm>
1496
1497               <indexterm>
1498                 <primary>prdb.DBSYS1 file</primary>
1499               </indexterm>
1500             </listitem>
1501           </varlistentry>
1502
1503           <varlistentry>
1504             <term><emphasis role="bold">prdb.DBSYS1</emphasis></term>
1505
1506             <listitem>
1507               <para>The Protection Database log file.</para>
1508
1509               <indexterm>
1510                 <primary>files</primary>
1511
1512                 <secondary>vldb.DB0</secondary>
1513               </indexterm>
1514
1515               <indexterm>
1516                 <primary>vldb.DB0 file</primary>
1517               </indexterm>
1518             </listitem>
1519           </varlistentry>
1520
1521           <varlistentry>
1522             <term><emphasis role="bold">vldb.DB0</emphasis></term>
1523
1524             <listitem>
1525               <para>The Volume Location Database file.</para>
1526
1527               <indexterm>
1528                 <primary>files</primary>
1529
1530                 <secondary>vldb.DBSYS1</secondary>
1531               </indexterm>
1532
1533               <indexterm>
1534                 <primary>vldb.DBSYS1 file</primary>
1535               </indexterm>
1536             </listitem>
1537           </varlistentry>
1538
1539           <varlistentry>
1540             <term><emphasis role="bold">vldb.DBSYS1</emphasis></term>
1541
1542             <listitem>
1543               <para>The Volume Location Database log file.</para>
1544             </listitem>
1545           </varlistentry>
1546         </variablelist></para>
1547
1548       <indexterm>
1549         <primary>usr/afs/logs directory on server machines</primary>
1550
1551         <secondary>contents listed</secondary>
1552       </indexterm>
1553
1554       <indexterm>
1555         <primary>directory</primary>
1556
1557         <secondary>/usr/afs/logs on server machines</secondary>
1558       </indexterm>
1559
1560       <indexterm>
1561         <primary>file server machine</primary>
1562
1563         <secondary>core files in /usr/afs/logs</secondary>
1564       </indexterm>
1565
1566       <indexterm>
1567         <primary>file server machine</primary>
1568
1569         <secondary>log files in /usr/afs/logs</secondary>
1570       </indexterm>
1571
1572       <indexterm>
1573         <primary>log files</primary>
1574
1575         <secondary>for server processes</secondary>
1576       </indexterm>
1577
1578       <indexterm>
1579         <primary>core files</primary>
1580
1581         <secondary>for server processes</secondary>
1582       </indexterm>
1583     </sect2>
1584
1585     <sect2 id="HDRWQ88">
1586       <title>Log Files in the /usr/afs/logs Directory</title>
1587
1588       <para>The <emphasis role="bold">/usr/afs/logs</emphasis> directory contains log files from various server processes. The files
1589       detail interesting events that occur during normal operations. For instance, the Volume Server can record volume moves in the
1590       <emphasis role="bold">VolserLog</emphasis> file. Events are recorded at completion, so the server processes do not use these
1591       files to reconstruct failed operations unlike the ones in the <emphasis role="bold">/usr/afs/db</emphasis> directory.</para>
1592
1593       <para>The information in log files can be very useful as you evaluate process failures and other problems. For instance, if
1594       you receive a timeout message when you try to access a volume, checking the <emphasis role="bold">FileLog</emphasis> file
1595       possibly provides an explanation, showing that the File Server was unable to attach the volume. To examine a log file
1596       remotely, use the <emphasis role="bold">bos getlog</emphasis> command as described in <link linkend="HDRWQ173">Displaying
1597       Server Process Log Files</link>.</para>
1598
1599       <para>This directory also contains the core image files generated if a process being monitored by the BOS Server crashes. The
1600       BOS Server attempts to add an extension to the standard <emphasis role="bold">core</emphasis> name to indicate which process
1601       generated the core file (for example, naming a core file generated by the Protection Server <emphasis
1602       role="bold">core.ptserver</emphasis>). The BOS Server cannot always assign the correct extension if two processes fail at
1603       about the same time, so it is not guaranteed to be correct.</para>
1604
1605       <para>The directory contains the following files: <variablelist>
1606           <indexterm>
1607             <primary>AuthLog file</primary>
1608           </indexterm>
1609
1610           <indexterm>
1611             <primary>files</primary>
1612
1613             <secondary>AuthLog</secondary>
1614           </indexterm>
1615
1616           <varlistentry>
1617             <term><emphasis role="bold">AuthLog</emphasis></term>
1618
1619             <listitem>
1620               <para>The Authentication Server's log file.</para>
1621
1622               <indexterm>
1623                 <primary>BackupLog file</primary>
1624               </indexterm>
1625
1626               <indexterm>
1627                 <primary>files</primary>
1628
1629                 <secondary>BackupLog</secondary>
1630               </indexterm>
1631             </listitem>
1632           </varlistentry>
1633
1634           <varlistentry>
1635             <term><emphasis role="bold">BackupLog</emphasis></term>
1636
1637             <listitem>
1638               <para>The Backup Server's log file.</para>
1639
1640               <indexterm>
1641                 <primary>BosLog file</primary>
1642               </indexterm>
1643
1644               <indexterm>
1645                 <primary>files</primary>
1646
1647                 <secondary>BosLog</secondary>
1648               </indexterm>
1649             </listitem>
1650           </varlistentry>
1651
1652           <varlistentry>
1653             <term><emphasis role="bold">BosLog</emphasis></term>
1654
1655             <listitem>
1656               <para>The BOS Server's log file.</para>
1657
1658               <indexterm>
1659                 <primary>files</primary>
1660
1661                 <secondary>FileLog</secondary>
1662               </indexterm>
1663
1664               <indexterm>
1665                 <primary>FileLog file</primary>
1666               </indexterm>
1667             </listitem>
1668           </varlistentry>
1669
1670           <varlistentry>
1671             <term><emphasis role="bold">FileLog</emphasis></term>
1672
1673             <listitem>
1674               <para>The File Server's log file.</para>
1675
1676               <indexterm>
1677                 <primary>files</primary>
1678
1679                 <secondary>SalvageLog</secondary>
1680               </indexterm>
1681
1682               <indexterm>
1683                 <primary>SalvageLog file</primary>
1684               </indexterm>
1685             </listitem>
1686           </varlistentry>
1687
1688           <varlistentry>
1689             <term><emphasis role="bold">SalvageLog</emphasis></term>
1690
1691             <listitem>
1692               <para>The Salvager's log file.</para>
1693
1694               <indexterm>
1695                 <primary>VLLog file</primary>
1696               </indexterm>
1697
1698               <indexterm>
1699                 <primary>files</primary>
1700
1701                 <secondary>VLLog</secondary>
1702               </indexterm>
1703             </listitem>
1704           </varlistentry>
1705
1706           <varlistentry>
1707             <term><emphasis role="bold">VLLog</emphasis></term>
1708
1709             <listitem>
1710               <para>The Volume Location (VL) Server's log file.</para>
1711
1712               <indexterm>
1713                 <primary>VolserLog file</primary>
1714               </indexterm>
1715
1716               <indexterm>
1717                 <primary>files</primary>
1718
1719                 <secondary>VolserLog</secondary>
1720               </indexterm>
1721             </listitem>
1722           </varlistentry>
1723
1724           <varlistentry>
1725             <term><emphasis role="bold">VolserLog</emphasis></term>
1726
1727             <listitem>
1728               <para>The Volume Server's log file.</para>
1729             </listitem>
1730           </varlistentry>
1731
1732           <varlistentry>
1733             <term><emphasis role="bold">core.process</emphasis></term>
1734
1735             <listitem>
1736               <para>If present, a core image file produced as an AFS server process on the machine crashed (probably the process
1737               named by process).</para>
1738             </listitem>
1739           </varlistentry>
1740         </variablelist></para>
1741
1742       <note>
1743         <para>To prevent log files from growing unmanageably large, restart the server processes periodically, particularly the
1744         database server processes. To avoid restarting the processes, use the UNIX <emphasis role="bold">rm</emphasis> command to
1745         remove the file as the process runs; it re-creates it automatically.</para>
1746       </note>
1747
1748       <indexterm>
1749         <primary>vicep directory on server machines</primary>
1750
1751         <secondary>contents listed</secondary>
1752       </indexterm>
1753
1754       <indexterm>
1755         <primary>directory</primary>
1756
1757         <secondary>/vicep on server machines</secondary>
1758       </indexterm>
1759
1760       <indexterm>
1761         <primary>volume header</primary>
1762
1763         <secondary>in /vicep directories</secondary>
1764       </indexterm>
1765
1766       <indexterm>
1767         <primary>partition</primary>
1768
1769         <secondary>housing AFS volumes</secondary>
1770       </indexterm>
1771
1772       <indexterm>
1773         <primary>file server machine</primary>
1774
1775         <secondary>partitions, naming</secondary>
1776       </indexterm>
1777     </sect2>
1778
1779     <sect2 id="HDRWQ89">
1780       <title>Volume Headers on Server Partitions</title>
1781
1782       <para>A partition that houses AFS volumes must be mounted at a subdirectory of the machine's root ( / ) directory (not, for
1783       instance under the <emphasis role="bold">/usr</emphasis> directory). The file server machine's file system registry file
1784       (<emphasis role="bold">/etc/fstab</emphasis> or equivalent) must correctly map the directory name and the partition's device
1785       name. The directory name is of the form <emphasis role="bold">/vicep</emphasis>index, where each index is one or two lowercase
1786       letters. By convention, the first AFS partition on a machine is mounted at <emphasis role="bold">/vicepa</emphasis>, the
1787       second at <emphasis role="bold">/vicepb</emphasis>, and so on. If there are more than 26 partitions, continue with <emphasis
1788       role="bold">/vicepaa</emphasis>, <emphasis role="bold">/vicepab</emphasis> and so on. The <emphasis>OpenAFS Release
1789       Notes</emphasis> specifies the number of supported partitions per server machine.</para>
1790
1791       <para>Do not store non-AFS files on AFS partitions. The File Server and Volume Server expect to have available all of the
1792       space on the partition.</para>
1793
1794       <para>The <emphasis role="bold">/vicep</emphasis> directories contain two types of files: <variablelist>
1795           <indexterm>
1796             <primary>V.<emphasis>vol_ID</emphasis>.vol file</primary>
1797           </indexterm>
1798
1799           <indexterm>
1800             <primary>files</primary>
1801
1802             <secondary>V.<emphasis>vol_ID</emphasis>.vol</secondary>
1803           </indexterm>
1804
1805           <varlistentry>
1806             <term><emphasis role="bold">Vvol_ID.vol</emphasis></term>
1807
1808             <listitem>
1809               <para>Each such file is a volume header. The vol_ID corresponds to the volume ID number displayed in the output from
1810               the <emphasis role="bold">vos examine</emphasis>, <emphasis role="bold">vos listvldb</emphasis>, and <emphasis
1811               role="bold">vos listvol</emphasis> commands.</para>
1812
1813               <indexterm>
1814                 <primary>FORCESALVAGE file</primary>
1815               </indexterm>
1816
1817               <indexterm>
1818                 <primary>files</primary>
1819
1820                 <secondary>FORCESALVAGE</secondary>
1821               </indexterm>
1822             </listitem>
1823           </varlistentry>
1824
1825           <varlistentry>
1826             <term><emphasis role="bold">FORCESALVAGE</emphasis></term>
1827
1828             <listitem>
1829               <para>This zero-length file triggers the Salvager to salvage the entire partition. The AFS-modified version of the
1830               <emphasis role="bold">fsck</emphasis> program creates this file if it discovers corruption.</para>
1831             </listitem>
1832           </varlistentry>
1833         </variablelist></para>
1834
1835       <note>
1836         <para>For most system types, it is important never to run the standard <emphasis role="bold">fsck</emphasis> program
1837         provided with the operating system on an AFS file server machine. It removes all AFS volume data from server partitions
1838         because it does not recognize their format.</para>
1839       </note>
1840
1841       <indexterm>
1842         <primary>roles for server machine</primary>
1843       </indexterm>
1844
1845       <indexterm>
1846         <primary>server machine</primary>
1847
1848         <secondary>roles summarized</secondary>
1849       </indexterm>
1850     </sect2>
1851   </sect1>
1852
1853   <sect1 id="HDRWQ90">
1854     <title>The Four Roles for File Server Machines</title>
1855
1856     <para>In cells that have more than one server machine, not all server machines have to perform exactly the same functions. The
1857     are four possible <emphasis>roles</emphasis> a machine can assume, determined by which server processes it is running. A machine
1858     can assume more than one role by running all of the relevant processes. The following list summarizes the four roles, which are
1859     described more completely in subsequent sections. <itemizedlist>
1860         <listitem>
1861           <para>A <emphasis>simple file server</emphasis> machine runs only the processes that store and deliver AFS files to client
1862           machines. You can run as many simple file server machines as you need to satisfy your cell's performance and disk space
1863           requirements.</para>
1864         </listitem>
1865
1866         <listitem>
1867           <para>A <emphasis>database server machine</emphasis> runs the four database server processes that maintain AFS's
1868           replicated administrative databases: the Authentication, Backup, Protection, and Volume Location (VL) Server
1869           processes.</para>
1870         </listitem>
1871
1872         <listitem>
1873           <para>A <emphasis>binary distribution machine</emphasis> distributes the AFS server binaries for its system type to all
1874           other server machines of that system type.</para>
1875         </listitem>
1876
1877         <listitem>
1878           <para>The single <emphasis>system control machine</emphasis> distributes common server configuration files to all other
1879           server machines in the cell, in a cell that runs the United States edition of AFS (cells that use the international
1880           edition of AFS must not use the system control machine for this purpose). The machine conventionally also serves as the
1881           time synchronization source for the cell, adjusting its clock according to a time source outside the cell.</para>
1882         </listitem>
1883       </itemizedlist></para>
1884
1885     <para>If a cell has a single server machine, it assumes the simple file server and database server roles. The instructions in
1886     the <emphasis>OpenAFS Quick Beginnings</emphasis> also have you configure it as the system control machine and binary
1887     distribution machine for its system type, but it does not actually perform those functions until you install another server
1888     machine.</para>
1889
1890     <para>It is best to keep the binaries for all of the AFS server processes in the <emphasis role="bold">/usr/afs/bin</emphasis>
1891     directory, even if not all processes are running. You can then change which roles a machine assumes simply by starting or
1892     stopping the processes that define the role.</para>
1893
1894     <indexterm>
1895       <primary>simple file server machine</primary>
1896     </indexterm>
1897
1898     <indexterm>
1899       <primary>server machine</primary>
1900
1901       <secondary>simple file server role</secondary>
1902     </indexterm>
1903
1904     <sect2 id="HDRWQ91">
1905       <title>Simple File Server Machines</title>
1906
1907       <para>A <emphasis>simple file server machine</emphasis> runs only the server processes that store and deliver AFS files to
1908       client machines, monitor process status, and pick up binaries and configuration files from the cell's binary distribution and
1909       system control machines.</para>
1910
1911       <para>In general, only cells with more than three server machines need to run simple file server machines. In cells with three
1912       or fewer machines, all of them are usually database server machines (to benefit from replicating the administrative
1913       databases); see <link linkend="HDRWQ92">Database Server Machines</link>.</para>
1914
1915       <para>The following processes run on a simple file server machine: <itemizedlist>
1916           <listitem>
1917             <para>The BOS Server (<emphasis role="bold">bosserver</emphasis> process)</para>
1918           </listitem>
1919
1920           <listitem>
1921             <para>The <emphasis role="bold">fs</emphasis> process, which combines the File Server, Volume Server, and Salvager
1922             processes so that they can coordinate their operations on the data in volumes and avoid the inconsistencies that can
1923             result from multiple simultaneous operations on the same data</para>
1924           </listitem>
1925
1926           <listitem>
1927             <para>The NTP coordinator (<emphasis role="bold">runntp</emphasis> process), which helps keep the machine's clock
1928             synchronized with the clocks on the other server machines in the cell</para>
1929           </listitem>
1930
1931           <listitem>
1932             <para>A client portion of the Update Server that picks up binary files from the binary distribution machine of its AFS
1933             system type (the <emphasis role="bold">upclientbin</emphasis> process)</para>
1934           </listitem>
1935
1936           <listitem>
1937             <para>A client portion of the Update Server that picks up common configuration files from the system control machine, in
1938             cells running the United States edition of AFS (the <emphasis role="bold">upclientetc</emphasis> process)</para>
1939           </listitem>
1940         </itemizedlist></para>
1941
1942       <indexterm>
1943         <primary>database server machine</primary>
1944
1945         <secondary>defined</secondary>
1946       </indexterm>
1947
1948       <indexterm>
1949         <primary>server machine</primary>
1950
1951         <secondary>database server role</secondary>
1952       </indexterm>
1953
1954       <indexterm>
1955         <primary>Backup Server</primary>
1956
1957         <secondary>runs on database server machine</secondary>
1958       </indexterm>
1959
1960       <indexterm>
1961         <primary>Authentication Server</primary>
1962
1963         <secondary>runs on database server machine</secondary>
1964       </indexterm>
1965
1966       <indexterm>
1967         <primary>Protection Server</primary>
1968
1969         <secondary>runs on database server machine</secondary>
1970       </indexterm>
1971
1972       <indexterm>
1973         <primary>VL Server</primary>
1974
1975         <secondary>runs on database server machine</secondary>
1976       </indexterm>
1977     </sect2>
1978
1979     <sect2 id="HDRWQ92">
1980       <title>Database Server Machines</title>
1981
1982       <para>A <emphasis>database server machine</emphasis> runs the four processes that maintain the AFS replicated administrative
1983       databases: the Authentication Server, Backup Server, Protection Server, and Volume Location (VL) Server, which maintain the
1984       Authentication Database, Backup Database, Protection Database, and Volume Location Database (VLDB), respectively. To review
1985       the functions of these server processes and their databases, see <link linkend="HDRWQ17">AFS Server Processes and the Cache
1986       Manager</link>.</para>
1987
1988       <para>If a cell has more than one server machine, it is best to run more than one database server machine, but more than three
1989       are rarely necessary. Replicating the databases in this way yields the same benefits as replicating volumes: increased
1990       availability and reliability of information. If one database server machine or process goes down, the information in the
1991       database is still available from others. The load of requests for database information is spread across multiple machines,
1992       preventing any one from becoming overloaded.</para>
1993
1994       <para>Unlike replicated volumes, however, replicated databases do change frequently. Consistent system performance demands
1995       that all copies of the database always be identical, so it is not possible to record changes in only some of them. To
1996       synchronize the copies of a database, the database server processes use AFS's distributed database technology, Ubik. See <link
1997       linkend="HDRWQ102">Replicating the OpenAFS Administrative Databases</link>.</para>
1998
1999       <para>It is critical that the AFS server processes on every server machine in a cell know which machines are the database
2000       server machines. The database server processes in particular must maintain constant contact with their peers in order to
2001       coordinate the copies of the database. The other server processes often need information from the databases. Every file server
2002       machine keeps a list of its cell's database server machines in its local <emphasis
2003       role="bold">/usr/afs/etc/CellServDB</emphasis> file. Cells that use the States edition of AFS can use the system control
2004       machine to distribute this file (see <link linkend="HDRWQ94">The System Control Machine</link>).</para>
2005
2006       <para>The following processes define a database server machine: <itemizedlist>
2007           <listitem>
2008             <para>The Authentication Server (<emphasis role="bold">kaserver</emphasis> process)</para>
2009           </listitem>
2010
2011           <listitem>
2012             <para>The Backup Server (<emphasis role="bold">buserver</emphasis> process)</para>
2013           </listitem>
2014
2015           <listitem>
2016             <para>The Protection Server (<emphasis role="bold">ptserver</emphasis> process)</para>
2017           </listitem>
2018
2019           <listitem>
2020             <para>The VL Server (<emphasis role="bold">vlserver</emphasis> process)</para>
2021           </listitem>
2022         </itemizedlist></para>
2023
2024       <para>Database server machines can also run the processes that define a simple file server machine, as listed in <link
2025       linkend="HDRWQ91">Simple File Server Machines</link>. One database server machine can act as the cell's system control
2026       machine, and any database server machine can serve as the binary distribution machine for its system type; see <link
2027       linkend="HDRWQ94">The System Control Machine</link> and <link linkend="HDRWQ93">Binary Distribution Machines</link>.</para>
2028
2029       <indexterm>
2030         <primary>binary distribution machine</primary>
2031
2032         <secondary>defined</secondary>
2033       </indexterm>
2034
2035       <indexterm>
2036         <primary>server machine</primary>
2037
2038         <secondary>binary distribution role</secondary>
2039       </indexterm>
2040
2041       <indexterm>
2042         <primary>Update Server</primary>
2043
2044         <secondary>server portion</secondary>
2045
2046         <tertiary>on binary distribution machine</tertiary>
2047       </indexterm>
2048
2049       <indexterm>
2050         <primary>Update Server</primary>
2051
2052         <secondary>client portion</secondary>
2053
2054         <tertiary>for binaries</tertiary>
2055       </indexterm>
2056     </sect2>
2057
2058     <sect2 id="HDRWQ93">
2059       <title>Binary Distribution Machines</title>
2060
2061       <para>A <emphasis>binary distribution machine</emphasis> stores and distributes the binary files for the AFS processes and
2062       command suites to all other server machines of its system type. Each file server machine keeps its own copy of AFS server
2063       process binaries on its local disk, by convention in the <emphasis role="bold">/usr/afs/bin</emphasis> directory. For
2064       consistent system performance, however, all server machines must run the same version (build level) of a process. For
2065       instructions for checking a binary's build level, see <link linkend="HDRWQ117">Displaying A Binary File's Build Level</link>.
2066       The easiest way to keep the binaries consistent is to have a binary distribution machine of each system type distribute them
2067       to its system-type peers.</para>
2068
2069       <para>The process that defines a binary distribution machine is the server portion of the Update Server (<emphasis
2070       role="bold">upserver</emphasis> process). The client portion of the Update Server (<emphasis
2071       role="bold">upclientbin</emphasis> process) runs on the other server machines of that system type and references the binary
2072       distribution machine.</para>
2073
2074       <para>Binary distribution machines usually also run the processes that define a simple file server machine, as listed in <link
2075       linkend="HDRWQ91">Simple File Server Machines</link>. One binary distribution machine can act as the cell's system control
2076       machine, and any binary distribution machine can serve as a database server machine; see <link linkend="HDRWQ94">The System
2077       Control Machine</link> and <link linkend="HDRWQ92">Database Server Machines</link>.</para>
2078
2079       <indexterm>
2080         <primary>system control machine</primary>
2081       </indexterm>
2082
2083       <indexterm>
2084         <primary>configuration files</primary>
2085
2086         <secondary>server machine, common</secondary>
2087       </indexterm>
2088
2089       <indexterm>
2090         <primary>server machine</primary>
2091
2092         <secondary>system control role</secondary>
2093       </indexterm>
2094     </sect2>
2095
2096     <sect2 id="HDRWQ94">
2097       <title>The System Control Machine</title>
2098
2099       <para>In cells that run the United States edition of AFS, the <emphasis>system control machine</emphasis> stores and
2100       distributes system configuration files shared by all of the server machines in the cell. Each file server machine keeps its
2101       own copy of the configuration files on its local disk, by convention in the <emphasis role="bold">/usr/afs/etc</emphasis>
2102       directory. For consistent system performance, however, all server machines must use the same files. The easiest way to keep
2103       the files consistent is to have the system control machine distribute them. You make changes only to the copy stored on the
2104       system control machine, as directed by the instructions in this document. The United States edition of AFS is available to
2105       cells in the United States and Canada and to selected institutions in other countries, as determined by United States
2106       government regulations.</para>
2107
2108       <para>Cells that run the international version of AFS do not use the system control machine to distribute system configuration
2109       files. Some of the files contain information that is too sensitive to cross the network unencrypted, and United States
2110       government regulations forbid the export of the necessary encryption routines in the form that the Update Server uses. You
2111       must instead update the configuration files on each file server machine individually. The <emphasis role="bold">bos</emphasis>
2112       commands that you use to update the files encrypt the information using an exportable form of the encryption routines.</para>
2113
2114       <para>For a list of the configuration files stored in the <emphasis role="bold">/usr/afs/etc</emphasis> directory, see <link
2115       linkend="HDRWQ85">Common Configuration Files in the /usr/afs/etc Directory</link>.</para>
2116
2117       <para>The <emphasis>OpenAFS Quick Beginnings</emphasis> configures a cell's first server machine as the system control
2118       machine. If you wish, you can reassign the role to a different machine that you install later, but you must then change the
2119       client portion of the Update Server (<emphasis role="bold">upclientetc</emphasis>) process running on all other server
2120       machines to refer to the new system control machine.</para>
2121
2122       <para>The following processes define the system control machine: <itemizedlist>
2123           <indexterm>
2124             <primary>Update Server</primary>
2125
2126             <secondary>server portion</secondary>
2127
2128             <tertiary>on system control machine</tertiary>
2129           </indexterm>
2130
2131           <indexterm>
2132             <primary>Update Server</primary>
2133
2134             <secondary>client portion</secondary>
2135
2136             <tertiary>for configuration files</tertiary>
2137           </indexterm>
2138
2139           <listitem>
2140             <para>The server portion of the Update Server (<emphasis role="bold">upserver</emphasis>) process, in cells using the
2141             United States edition of AFS. The client portion of the Update Server (<emphasis role="bold">upclientetc</emphasis>
2142             process) runs on the other server machines and references the system control machine.</para>
2143           </listitem>
2144
2145           <listitem>
2146             <para>The NTP coordinator (<emphasis role="bold">runntp</emphasis> process) which points to a time source outside the
2147             cell, if the cell uses NTPD to synchronize its clocks. The <emphasis role="bold">runntp</emphasis> process on other
2148             machines reference the system control machine as their main time source.</para>
2149           </listitem>
2150         </itemizedlist></para>
2151
2152       <para>The system control machine can also run the processes that define a simple file server machine, as listed in <link
2153       linkend="HDRWQ91">Simple File Server Machines</link>. It can also server as a database server machine, and by convention acts
2154       as the binary distribution machine for its system type. A single <emphasis role="bold">upserver</emphasis> process can
2155       distribute both configuration files and binaries. See <link linkend="HDRWQ92">Database Server Machines</link> and <link
2156       linkend="HDRWQ93">Binary Distribution Machines</link>.</para>
2157
2158       <indexterm>
2159         <primary>determining</primary>
2160
2161         <secondary>roles taken by server machine</secondary>
2162       </indexterm>
2163
2164       <indexterm>
2165         <primary>identifying</primary>
2166
2167         <secondary>roles taken by server machine</secondary>
2168       </indexterm>
2169
2170       <indexterm>
2171         <primary>server machine</primary>
2172
2173         <secondary>determining roles</secondary>
2174       </indexterm>
2175
2176       <indexterm>
2177         <primary>roles for server machine</primary>
2178
2179         <secondary>determining</secondary>
2180       </indexterm>
2181
2182       <indexterm>
2183         <primary>database server machine</primary>
2184
2185         <secondary>identifying with bos status</secondary>
2186       </indexterm>
2187
2188       <indexterm>
2189         <primary>determining</primary>
2190
2191         <secondary>identity of database server machines</secondary>
2192       </indexterm>
2193
2194       <indexterm>
2195         <primary>identifying</primary>
2196
2197         <secondary>database server machine</secondary>
2198       </indexterm>
2199     </sect2>
2200
2201     <sect2 id="HDRWQ95">
2202       <title>To locate database server machines</title>
2203
2204       <orderedlist>
2205         <listitem>
2206           <para>Issue the <emphasis role="bold">bos listhosts</emphasis> command. <programlisting>
2207    % <emphasis role="bold">bos listhosts</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
2208 </programlisting></para>
2209
2210           <para>The machines listed in the output are the cell's database server machines. For complete instructions and example
2211           output, see <link linkend="HDRWQ120">To display a cell's database server machines</link>.</para>
2212         </listitem>
2213
2214         <listitem>
2215           <para><emphasis role="bold">(Optional)</emphasis> Issue the <emphasis role="bold">bos status</emphasis> command to verify
2216           that a machine listed in the output of the <emphasis role="bold">bos listhosts</emphasis> command is actually running the
2217           processes that define it as a database server machine. For complete instructions, see <link linkend="HDRWQ158">Displaying
2218           Process Status and Information from the BosConfig File</link>. <programlisting>
2219    % <emphasis role="bold">bos status</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">buserver kaserver ptserver vlserver</emphasis>
2220 </programlisting></para>
2221
2222           <para>If the specified machine is a database server machine, the output from the <emphasis role="bold">bos
2223           status</emphasis> command includes the following lines:</para>
2224
2225           <programlisting>
2226    Instance buserver, currently running normally.
2227    Instance kaserver, currently running normally.
2228    Instance ptserver, currently running normally.
2229    Instance vlserver, currently running normally.
2230 </programlisting>
2231         </listitem>
2232       </orderedlist>
2233
2234       <indexterm>
2235         <primary>system control machine</primary>
2236
2237         <secondary>identifying with bos status</secondary>
2238       </indexterm>
2239
2240       <indexterm>
2241         <primary>determining</primary>
2242
2243         <secondary>identity of system control machine</secondary>
2244       </indexterm>
2245
2246       <indexterm>
2247         <primary>identifying</primary>
2248
2249         <secondary>system control machine</secondary>
2250       </indexterm>
2251     </sect2>
2252
2253     <sect2 id="HDRWQ96">
2254       <title>To locate the system control machine</title>
2255
2256       <orderedlist>
2257         <listitem>
2258           <para>Issue the <emphasis role="bold">bos status</emphasis> command for any server machine. Complete instructions appear
2259           in <link linkend="HDRWQ158">Displaying Process Status and Information from the BosConfig File</link>. <programlisting>
2260    % <emphasis role="bold">bos status</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">upserver upclientbin upclientetc</emphasis> <emphasis
2261                 role="bold">-long</emphasis>
2262 </programlisting></para>
2263
2264           <para>The output you see depends on the machine you have contacted: a simple file server machine, the system control
2265           machine, or a binary distribution machine. See <link linkend="HDRWQ98">Interpreting the Output from the bos status
2266           Command</link>.</para>
2267         </listitem>
2268       </orderedlist>
2269
2270       <indexterm>
2271         <primary>binary distribution machine</primary>
2272
2273         <secondary>identifying with bos status</secondary>
2274       </indexterm>
2275
2276       <indexterm>
2277         <primary>determining</primary>
2278
2279         <secondary>identity of binary distribution machine</secondary>
2280       </indexterm>
2281
2282       <indexterm>
2283         <primary>identifying</primary>
2284
2285         <secondary>binary distribution machine</secondary>
2286       </indexterm>
2287     </sect2>
2288
2289     <sect2 id="HDRWQ97">
2290       <title>To locate the binary distribution machine for a system type</title>
2291
2292       <orderedlist>
2293         <listitem>
2294           <para>Issue the <emphasis role="bold">bos status</emphasis> command for a file server machine of the system type you are
2295           checking (to determine a machine's system type, issue the <emphasis role="bold">fs sysname</emphasis> or <emphasis
2296           role="bold">sys</emphasis> command as described in <link linkend="HDRWQ417">Displaying and Setting the System Type
2297           Name</link>. Complete instructions for the <emphasis role="bold">bos status</emphasis> command appear in <link
2298           linkend="HDRWQ158">Displaying Process Status and Information from the BosConfig File</link>. <programlisting>
2299    % <emphasis role="bold">bos status</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">upserver upclientbin upclientetc -long</emphasis>
2300 </programlisting></para>
2301
2302           <para>The output you see depends on the machine you have contacted: a simple file server machine, the system control
2303           machine, or a binary distribution machine. See <link linkend="HDRWQ98">Interpreting the Output from the bos status
2304           Command</link>.</para>
2305         </listitem>
2306       </orderedlist>
2307
2308       <indexterm>
2309         <primary>simple file server machine</primary>
2310
2311         <secondary>identifying with bos status</secondary>
2312       </indexterm>
2313
2314       <indexterm>
2315         <primary>determining</primary>
2316
2317         <secondary>identity of:</secondary>
2318
2319         <tertiary>simple file server machines</tertiary>
2320       </indexterm>
2321
2322       <indexterm>
2323         <primary>identifying</primary>
2324
2325         <secondary>simple file server machine</secondary>
2326       </indexterm>
2327     </sect2>
2328
2329     <sect2 id="HDRWQ98">
2330       <title>Interpreting the Output from the bos status Command</title>
2331
2332       <para>Interpreting the output of the <emphasis role="bold">bos status</emphasis> command is most straightforward for a simple
2333       file server machine. There is no <emphasis role="bold">upserver</emphasis> process, so the output includes the following
2334       message:</para>
2335
2336       <programlisting>
2337    bos: failed to get instance info for 'upserver' (no such entity)
2338 </programlisting>
2339
2340       <para>A simple file server machine runs the <emphasis role="bold">upclientbin</emphasis> process, so the output includes a
2341       message like the following. It indicates that <emphasis role="bold">fs7.abc.com</emphasis> is the binary distribution machine
2342       for this system type.</para>
2343
2344       <programlisting>
2345    Instance upclientbin, (type is simple) currently running normally.
2346    Process last started at Wed Mar 10  23:37:09 1999 (1 proc start)
2347    Command 1 is '/usr/afs/bin/upclient fs7.abc.com -t 60 /usr/afs/bin'
2348 </programlisting>
2349
2350       <para>If you run the United States edition of AFS, a simple file server machine also runs the <emphasis
2351       role="bold">upclientetc</emphasis> process, so the output includes a message like the following. It indicates that <emphasis
2352       role="bold">fs1.abc.com</emphasis> is the system control machine.</para>
2353
2354       <programlisting>
2355    Instance upclientetc, (type is simple) currently running normally.
2356    Process last started at Mon Mar 22  05:23:49 1999 (1 proc start)
2357    Command 1 is '/usr/afs/bin/upclient fs1.abc.com -t 60 /usr/afs/etc'
2358 </programlisting>
2359
2360       <sect3 id="HDRWQ99">
2361         <title>The Output on the System Control Machine</title>
2362
2363         <para>If you run the United States edition of AFS and have issued the <emphasis role="bold">bos status</emphasis> command
2364         for the system control machine, the output includes an entry for the <emphasis role="bold">upserver</emphasis> process
2365         similar to the following:</para>
2366
2367         <programlisting>
2368    Instance upserver, (type is simple) currently running normally.
2369    Process last started at Mon Mar 22 05:23:54 1999 (1 proc start)
2370    Command 1 is '/usr/afs/bin/upserver'
2371 </programlisting>
2372
2373         <para>If you are using the default configuration recommended in the <emphasis>OpenAFS Quick Beginnings</emphasis>, the
2374         system control machine is also the binary distribution machine for its system type, and a single <emphasis
2375         role="bold">upserver</emphasis> process distributes both kinds of updates. In that case, the output includes the following
2376         messages:</para>
2377
2378         <programlisting>
2379    bos: failed to get instance info for 'upclientbin' (no such entity)
2380    bos: failed to get instance info for 'upclientetc' (no such entity)
2381 </programlisting>
2382
2383         <para>If the system control machine is not a binary distribution machine, the output includes an error message for the
2384         <emphasis role="bold">upclientetc</emphasis> process, but a complete a listing for the <emphasis
2385         role="bold">upclientbin</emphasis> process (in this case it refers to the machine <emphasis
2386         role="bold">fs5.abc.com</emphasis> as the binary distribution machine):</para>
2387
2388         <programlisting>
2389    Instance upclientbin, (type is simple) currently running normally.
2390    Process last started at Mon Mar 22  05:23:49 1999 (1 proc start)
2391    Command 1 is '/usr/afs/bin/upclient fs5.abc.com -t 60 /usr/afs/bin'
2392    bos: failed to get instance info for 'upclientetc' (no such entity)
2393 </programlisting>
2394       </sect3>
2395
2396       <sect3 id="HDRWQ100">
2397         <title>The Output on a Binary Distribution Machine</title>
2398
2399         <para>If you have issued the <emphasis role="bold">bos status</emphasis> command for a binary distribution machine, the
2400         output includes an entry for the <emphasis role="bold">upserver</emphasis> process similar to the following and error
2401         message for the <emphasis role="bold">upclientbin</emphasis> process:</para>
2402
2403         <programlisting>
2404    Instance upserver, (type is simple) currently running normally.
2405    Process last started at Mon Apr 5 05:23:54 1999 (1 proc start)
2406    Command 1 is '/usr/afs/bin/upserver'
2407    bos: failed to get instance info for 'upclientbin' (no such entity)
2408 </programlisting>
2409
2410         <para>Unless this machine also happens to be the system control machine, a message like the following references the system
2411         control machine (in this case, <emphasis role="bold">fs3.abc.com</emphasis>):</para>
2412
2413         <programlisting>
2414    Instance upclientetc, (type is simple) currently running normally.
2415    Process last started at Mon Apr 5 05:23:49 1999 (1 proc start)
2416    Command 1 is '/usr/afs/bin/upclient fs3.abc.com -t 60 /usr/afs/etc'
2417 </programlisting>
2418       </sect3>
2419     </sect2>
2420   </sect1>
2421
2422   <sect1 id="HDRWQ101">
2423     <title>Administering Database Server Machines</title>
2424
2425     <para>This section explains how to administer database server machines. For installation instructions, see the <emphasis>OpenAFS
2426     Quick Beginnings</emphasis>.</para>
2427
2428     <indexterm>
2429       <primary>distribution</primary>
2430
2431       <secondary>of databases</secondary>
2432     </indexterm>
2433
2434     <indexterm>
2435       <primary>database, distributed</primary>
2436
2437       <secondary></secondary>
2438
2439       <see>administrative database</see>
2440     </indexterm>
2441
2442     <indexterm>
2443       <primary>distributed database</primary>
2444
2445       <secondary></secondary>
2446
2447       <see>administrative database</see>
2448     </indexterm>
2449
2450     <indexterm>
2451       <primary>administrative database</primary>
2452
2453       <secondary>about replicating</secondary>
2454     </indexterm>
2455
2456     <indexterm>
2457       <primary>database server machine</primary>
2458
2459       <secondary>maintaining</secondary>
2460     </indexterm>
2461
2462     <indexterm>
2463       <primary>Ubik</primary>
2464
2465       <secondary>operation described</secondary>
2466     </indexterm>
2467
2468     <indexterm>
2469       <primary>synchronization site (Ubik)</primary>
2470
2471       <secondary>defined</secondary>
2472     </indexterm>
2473
2474     <indexterm>
2475       <primary>secondary site (Ubik)</primary>
2476     </indexterm>
2477
2478     <indexterm>
2479       <primary>coordinator (Ubik)</primary>
2480
2481       <secondary>defined</secondary>
2482     </indexterm>
2483
2484     <indexterm>
2485       <primary>Ubik</primary>
2486
2487       <secondary>automatic updates</secondary>
2488     </indexterm>
2489
2490     <indexterm>
2491       <primary>automatic</primary>
2492
2493       <secondary>update to admin. databases by Ubik</secondary>
2494     </indexterm>
2495
2496     <sect2 id="HDRWQ102">
2497       <title>Replicating the OpenAFS Administrative Databases</title>
2498
2499       <para>There are several benefits to replicating the AFS administrative databases (the Authentication, Backup, Protection, and
2500       Volume Location Databases), as discussed in <link linkend="HDRWQ52">Replicating the OpenAFS Administrative Databases</link>. For
2501       correct cell functioning, the copies of each database must be identical at all times. To keep the databases synchronized, AFS
2502       uses library of utilities called <emphasis>Ubik</emphasis>. Each database server process runs an associated lightweight Ubik
2503       process, and client-side programs call Ubik's client-side subroutines when they submit requests to read and change the
2504       databases.</para>
2505
2506       <para>Ubik is designed to work with minimal administrator intervention, but there are several configuration requirements, as
2507       detailed in <link linkend="HDRWQ103">Configuring the Cell for Proper Ubik Operation</link>. The following brief overview of
2508       Ubik's operation is helpful for understanding the requirements. For more details, see <link linkend="HDRWQ104">How Ubik
2509       Operates Automatically</link>.</para>
2510
2511       <para>Ubik is designed to distribute changes made in an AFS administrative database to all copies as quickly as possible. Only
2512       one copy of the database, the <emphasis>synchronization site</emphasis>, accepts change requests from clients; the lightweight
2513       Ubik process running there is the <emphasis>Ubik coordinator</emphasis>. To maintain maximum availability, there is a separate
2514       Ubik coordinator for each database, and the synchronization site for each of the four databases can be on a different machine.
2515       The synchronization site for a database can also move from machine to machine in response to process, machine, or network
2516       outages.</para>
2517
2518       <para>The other copies of a database, and the Ubik processes that maintain them, are termed <emphasis>secondary</emphasis>.
2519       The secondary sites do not accept database changes directly from client-side programs, but only from the synchronization
2520       site.</para>
2521
2522       <para>After the Ubik coordinator records a change in its copy of a database, it immediately sends the change to the secondary
2523       sites. During the brief distribution period, clients cannot access any of the copies of the database, even for reading. If the
2524       coordinator cannot reach a majority of the secondary sites, it halts the distribution and informs the client that the
2525       attempted change failed.</para>
2526
2527       <para>To avoid distribution failures, the Ubik processes maintain constant contact by exchanging time-stamped messages. As
2528       long as a majority of the secondary sites respond to the coordinator's messages, there is a <emphasis>quorum</emphasis> of
2529       sites that are synchronized with the coordinator. If a process, machine, or network outage breaks the quorum, the Ubik
2530       processes attempt to elect a new coordinator in order to establish a new quorum among the highest possible number of sites.
2531       See <link linkend="HDRWQ106">A Flexible Coordinator Boosts Availability</link>.</para>
2532
2533       <indexterm>
2534         <primary>Ubik</primary>
2535
2536         <secondary>requirements summarized</secondary>
2537       </indexterm>
2538
2539       <indexterm>
2540         <primary>database server process</primary>
2541
2542         <secondary>need to run all on every database server machine</secondary>
2543       </indexterm>
2544
2545       <indexterm>
2546         <primary>CellServDB file (server)</primary>
2547
2548         <secondary>importance to Ubik operation</secondary>
2549       </indexterm>
2550
2551       <sect3 id="HDRWQ103">
2552         <title>Configuring the Cell for Proper Ubik Operation</title>
2553
2554         <para>This section describes how to configure your cell to maintain proper Ubik operation. <itemizedlist>
2555             <listitem>
2556               <para>Run all four database server processes--Authentication Server, Backup Server, Protection Server, and VL
2557               Server--on all database server machines.</para>
2558
2559               <para>Both the client and server portions of Ubik expect that all the database server machines listed in the <emphasis
2560               role="bold">CellServDB</emphasis> file are running all of the database server processes. There is no mechanism for
2561               indicating that only some database server processes are running on a machine.</para>
2562             </listitem>
2563
2564             <listitem>
2565               <para>Maintain correct information in the <emphasis role="bold">/usr/afs/etc/CellServDB</emphasis> file at all
2566               times.</para>
2567
2568               <para>Ubik consults the <emphasis role="bold">/usr/afs/etc/CellServDB</emphasis> file to determine the sites with
2569               which to establish and maintain a quorum. Incorrect information can result in unsynchronized databases or election of
2570               a coordinator in each of several subgroups of machines, because the Ubik processes on various machines do not agree on
2571               which machines need to participate in the quorum.</para>
2572
2573               <para>If you run the United States version of AFS and use the Update Server, it is simplest to maintain the <emphasis
2574               role="bold">/usr/afs/etc/CellServDB</emphasis> file on the system control machine, which distributes its copy to all
2575               other server machines. The <emphasis>OpenAFS Quick Beginnings</emphasis> explains how to configure the Update Server.
2576               If you run the international version of AFS, you must update the file on each machine individually.</para>
2577
2578               <para>The only reason to alter the file is when configuring or decommissioning a database server machine. Use the
2579               appropriate <emphasis role="bold">bos</emphasis> commands rather than editing the file by hand. For instructions, see
2580               <link linkend="HDRWQ118">Maintaining the Server CellServDB File</link>. The instructions in <link
2581               linkend="HDRWQ142">Monitoring and Controlling Server Processes</link> for stopping and starting processes remind you
2582               to alter the <emphasis role="bold">CellServDB</emphasis> file when appropriate, as do the instructions in the
2583               <emphasis>OpenAFS Quick Beginnings</emphasis> for installing or decommissioning a database server machine.</para>
2584
2585               <para>(Client processes and the server processes that do not maintain databases also rely on correct information in
2586               the <emphasis role="bold">CellServDB</emphasis> file for proper operation, but their use of the information does not
2587               affect Ubik's operation. See <link linkend="HDRWQ118">Maintaining the Server CellServDB File</link> and <link
2588               linkend="HDRWQ406">Maintaining Knowledge of Database Server Machines</link>.)</para>
2589
2590               <indexterm>
2591                 <primary>clocks</primary>
2592
2593                 <secondary>need to synchronize for Ubik</secondary>
2594               </indexterm>
2595             </listitem>
2596
2597             <listitem>
2598               <para>Keep the clocks synchronized on all machines in the cell, especially the database server machines.</para>
2599
2600               <para>In the conventional configuration specified in the <emphasis>OpenAFS Quick Beginnings</emphasis>, you run the
2601               <emphasis role="bold">runntp</emphasis> process to supervise the local Network Time Protocol Daemon (NTPD) on every
2602               AFS server machine. The NTPD on the system control machine synchronizes its clock with a reliable source outside the
2603               cell and broadcasts the time to the NTPDs on the other server machines. You can choose to run a different time
2604               synchronization protocol if you wish.</para>
2605
2606               <para>Keeping clocks synchronized is important because the Ubik processes at a database's sites timestamp the messages
2607               which they exchange to maintain constant contact. Timestamping the messages is necessary because in a networked
2608               environment it is not safe to assume that a message reaches its destination instantly. Ubik compares the timestamp on
2609               an incoming message with the current time. If the difference is too great, it is possible that an outage is preventing
2610               reliable communication between the Ubik sites, which can possibly result in unsynchronized databases. Ubik considers
2611               the message invalid, which can prompt it to attempt election of a different coordinator.</para>
2612
2613               <para>Electing a new coordinator is appropriate if a timestamped message is expired due to actual interruption of
2614               communication, but not if a message appears expired only because the sender and recipient do not share the same time.
2615               For detailed examples of how unsynchronized clocks can destabilize Ubik operation, see <link linkend="HDRWQ105">How
2616               Ubik Uses Timestamped Messages</link>.</para>
2617             </listitem>
2618           </itemizedlist></para>
2619
2620         <indexterm>
2621           <primary>Ubik</primary>
2622
2623           <secondary>features summarized</secondary>
2624         </indexterm>
2625
2626         <indexterm>
2627           <primary>process</primary>
2628
2629           <secondary>lightweight Ubik</secondary>
2630         </indexterm>
2631
2632         <indexterm>
2633           <primary>Ubik</primary>
2634
2635           <secondary>server and client portions</secondary>
2636         </indexterm>
2637       </sect3>
2638
2639       <sect3 id="HDRWQ104">
2640         <title>How Ubik Operates Automatically</title>
2641
2642         <para>The following Ubik features help keep its maintenance requirements to a minimum: <itemizedlist>
2643             <listitem>
2644               <para>Ubik's server and client portions operate automatically.</para>
2645
2646               <para>Each database server process runs a lightweight process to call on the server portion of the Ubik library. It is
2647               common to refer to this lightweight process itself as Ubik. Because it is lightweight, the Ubik process does not
2648               appear in process listings such as those generated by the UNIX <emphasis role="bold">ps</emphasis> command.
2649               Client-side programs that need to read and change the databases directly call the subroutines in the Ubik library's
2650               client portion, rather than running a separate lightweight process. Examples of such programs are the <emphasis
2651               role="bold">klog</emphasis> command and the commands in the <emphasis role="bold">pts</emphasis> suite.</para>
2652             </listitem>
2653
2654             <listitem>
2655               <para>Ubik tracks database version numbers.</para>
2656
2657               <para>As the coordinator records a change to a database, it increments the database's version number. The version
2658               number makes it easy for the coordinator to determine if a site has the most recent version or not. The version number
2659               speeds the return to normal functioning after election of a new coordinator or when communication is restored after an
2660               outage, because it makes it easy to determine which site has the most current database and which need to be
2661               updated.</para>
2662             </listitem>
2663
2664             <listitem>
2665               <para>Ubik's use of timestamped messages guarantees that database copies are always synchronized during normal
2666               operation.</para>
2667
2668               <para>Replicating a database to increase data availability is pointless if all copies of the database are not the
2669               same. Inconsistent performance can result if clients receive different information depending on which copy of the
2670               database they access. As previously noted, Ubik sites constantly track the status of their peers by exchanging
2671               timestamped messages. For a detailed description, see <link linkend="HDRWQ105">How Ubik Uses Timestamped
2672               Messages</link>.</para>
2673             </listitem>
2674
2675             <listitem>
2676               <para>The ability to move the coordinator maximizes database availability.</para>
2677
2678               <para>Suppose, for example, that in a cell with three database server machines a network partition separates the two
2679               secondary sites from the coordinator. The coordinator retires because it is no longer in contact with a majority of
2680               the sites listed in the <emphasis role="bold">CellServDB</emphasis> file. The two sites on the other side of the
2681               partition can elect a new coordinator among themselves, and it can then accept database changes from clients. If the
2682               coordinator cannot move in this way, the database has to be read-only until the network partition is repaired. For a
2683               detailed description of Ubik's election procedure, see <link linkend="HDRWQ106">A Flexible Coordinator Boosts
2684               Availability</link>.</para>
2685             </listitem>
2686           </itemizedlist></para>
2687
2688         <indexterm>
2689           <primary>consistency guarantees</primary>
2690
2691           <secondary>administrative databases</secondary>
2692         </indexterm>
2693
2694         <indexterm>
2695           <primary>Ubik</primary>
2696
2697           <secondary>consistency guarantees</secondary>
2698         </indexterm>
2699
2700         <sect4 id="HDRWQ105">
2701           <title>How Ubik Uses Timestamped Messages</title>
2702
2703           <para>Ubik synchronizes the copies of a database by maintaining constant contact between the synchronization site and the
2704           secondary sites. The Ubik coordinator frequently sends a time-stamped <emphasis>guarantee</emphasis> message to each of
2705           the secondary sites. When the secondary site receives the message, it concludes that it is in contact with the
2706           coordinator. It considers its copy of the database to be valid until time <emphasis>T</emphasis>, which is usually 60
2707           seconds from the time the coordinator sent the message. In response, the secondary site returns a
2708           <emphasis>vote</emphasis> message that acknowledges the coordinator as valid until a certain time X, which is usually 120
2709           seconds in the future.</para>
2710
2711           <para>The coordinator sends guarantee messages more frequently than every <emphasis>T</emphasis> seconds, so that the
2712           expiration periods overlap. There is no danger of expiration unless a network partition or other outage actually
2713           interrupts communication. If the guarantee expires, the secondary site's copy of the database it not necessarily current.
2714           Nonetheless, the database server continues to service client requests. It is considered better for overall cell
2715           functioning that a secondary site remains accessible even if the information it is distributing is possibly out of date.
2716           Most of the AFS administrative databases do not change that frequently, in any case, and making a database inaccessible
2717           causes a timeout for clients that happen to access that copy.</para>
2718
2719           <para>As previously mentioned, Ubik's use of timestamped messages makes it vital to synchronize the clocks on database
2720           server machines. There are two ways that skewed clocks can interrupt normal Ubik functioning, depending on which clock is
2721           ahead of the others.</para>
2722
2723           <para>Suppose, for example, that the Ubik coordinator's clock is ahead of the secondary sites: the coordinator's clock
2724           says 9:35:30, but the secondary clocks say 9:31:30. The secondary sites send votes messages that acknowledge the
2725           coordinator as valid until 9:33:30. This is two minutes in the future according to the secondary clocks, but is already in
2726           the past from the coordinator's perspective. The coordinator concludes that it no longer has enough support to remain
2727           coordinator and forces election of a new coordinator. Election takes about three minutes, during which time no copy of the
2728           database accepts changes.</para>
2729
2730           <para>The opposite possibility is that a secondary site's clock (14:50:00) is ahead of the coordinator's (14:46:30). When
2731           the coordinator sends a guarantee message good until 14:47:30), it has already expired according to the secondary clock.
2732           Believing that it is out of contact with the coordinator, the secondary site stops sending votes for the coordinator and
2733           tries get itself elected as coordinator. This is appropriate if the coordinator has actually failed, but is inappropriate
2734           when there is no actual outage.</para>
2735
2736           <para>The attempt of a single secondary site to get elected as the new coordinator usually does not affect the performance
2737           of the other sites. As long as their clocks agree with the coordinator's, they ignore the other secondary site's request
2738           for votes and continue voting for the current coordinator. However, if enough of the secondary sites's clocks get ahead of
2739           the coordinator's, they can force election of a new coordinator even though the current one is actually working
2740           fine.</para>
2741
2742           <indexterm>
2743             <primary>Ubik</primary>
2744
2745             <secondary>election of coordinator</secondary>
2746           </indexterm>
2747
2748           <indexterm>
2749             <primary>coordinator (Ubik)</primary>
2750
2751             <secondary>election procedure described</secondary>
2752           </indexterm>
2753
2754           <indexterm>
2755             <primary>election of Ubik coordinator</primary>
2756           </indexterm>
2757
2758           <indexterm>
2759             <primary>flexible synchronization site (Ubik)</primary>
2760           </indexterm>
2761
2762           <indexterm>
2763             <primary>synchronization site (Ubik)</primary>
2764
2765             <secondary>flexibility</secondary>
2766           </indexterm>
2767
2768           <indexterm>
2769             <primary>Ubik</primary>
2770
2771             <secondary>majority defined</secondary>
2772           </indexterm>
2773
2774           <indexterm>
2775             <primary>majority</primary>
2776
2777             <secondary>defined for Ubik</secondary>
2778           </indexterm>
2779
2780           <indexterm>
2781             <primary>outages</primary>
2782
2783             <secondary>due to Ubik election</secondary>
2784           </indexterm>
2785
2786           <indexterm>
2787             <primary>system outages</primary>
2788
2789             <secondary>due to Ubik election</secondary>
2790           </indexterm>
2791         </sect4>
2792
2793         <sect4 id="HDRWQ106">
2794           <title>A Flexible Coordinator Boosts Availability</title>
2795
2796           <para>Ubik uses timestamped messages to determine when coordinator election is necessary, just as it does to keep the
2797           database copies synchronized. As long as the coordinator receives vote messages from a majority of the sites (it
2798           implicitly votes for itself), it is appropriate for it to continue as coordinator because it is successfully distributing
2799           database changes. A majority is defined as more than 50% of all database sites when there are an odd number of sites; with
2800           an even number of sites, the site with the lowest Internet address has an extra vote for breaking ties as necessary.If the
2801           coordinator is not receiving sufficient votes, it retires and the Ubik sites elect a new coordinator. This does not happen
2802           spontaneously, but only when the coordinator really fails or stops receiving a majority of the votes. The secondary sites
2803           have a built-in bias to continue voting for an existing coordinator, which prevents undue elections.</para>
2804
2805           <para>The election of the new coordinator is by majority vote. The Ubik subprocesses have a bias to vote for the site with
2806           the lowest Internet address, which helps it gather the necessary majority quicker than if all the sites were competing to
2807           receive votes themselves. During the election (which normally lasts less than three minutes), clients can read information
2808           from the database, but cannot make any changes.</para>
2809
2810           <para>Ubik's election procedure makes it possible for each database server process's coordinator to be on a different
2811           machine. For example, if the Ubik coordinators for all four processes start out on machine A and the Protection Server on
2812           machine A fails for some reason, then a different site (say machine B) must be elected as the new Protection Database Ubik
2813           coordinator. Machine B remains the coordinator for the Protection Database even after the Protection Server on machine A
2814           is working again. The failure of the Protection Server has no effect on the Authentication, Backup, or VL Servers, so
2815           their coordinators remain on machine A.</para>
2816         </sect4>
2817       </sect3>
2818     </sect2>
2819
2820     <sect2 id="HDRWQ107">
2821       <title>Backing Up and Restoring the Administrative Databases</title>
2822
2823       <para>The AFS administrative databases store information that is critical for AFS operation in your cell. If a database
2824       becomes corrupted due to a hardware failure or other problem on a database server machine, it likely to be difficult and
2825       time-consuming to recreate all of the information from scratch. To protect yourself against loss of data, back up the
2826       administrative databases to a permanent media, such as tape, on a regular basis. The recommended method is to use a standard
2827       local disk backup utility such as the UNIX <emphasis role="bold">tar</emphasis> command.</para>
2828
2829       <para>When deciding how often to back up a database, consider the amount of data that you are willing to recreate by hand if
2830       it becomes necessary to restore the database from a backup copy. In most cells, the databases differ quite a bit in how often
2831       and how much they change. Changes to the Authentication Database are probably the least frequent, and consist mostly of
2832       changed user passwords. Protection Database and VLDB changes are probably more frequent, as users add or delete groups and
2833       change group memberships, and as you and other administrators create or move volumes. The number and frequency of changes is
2834       probably greatest in the Backup Database, particularly if you perform backups every day.</para>
2835
2836       <para>The ease with which you can recapture lost changes also differs for the different databases: <itemizedlist>
2837           <listitem>
2838             <para>If regular users make a large proportion of the changes to the Authentication Database and Protection Database in
2839             your cell, then recovering them possibly requires a large amount of detective work and interviewing of users, assuming
2840             that they can even remember what changes they made at what time.</para>
2841           </listitem>
2842
2843           <listitem>
2844             <para>Recovering lost changes to the VLDB is more straightforward, because you can use the <emphasis role="bold">vos
2845             syncserv</emphasis> and <emphasis role="bold">vos syncvldb</emphasis> commands to correct any discrepancies between the
2846             VLDB and the actual state of volumes on server machines. Running these commands can be time-consuming, however.</para>
2847           </listitem>
2848
2849           <listitem>
2850             <para>The configuration information in the Backup Database (Tape Coordinator port offsets, volume sets and entries, the
2851             dump hierarchy, and so on) probably does not change that often, in which case it is not that hard to recover a few
2852             recent changes. In contrast, there are likely to be a large number of new dump records resulting from dump operations.
2853             You can recover these records by using the <emphasis role="bold">-dbadd</emphasis> argument to the <emphasis
2854             role="bold">backup scantape</emphasis> command, reading in information from the backup tapes themselves. This can take a
2855             long time and require numerous tape changes, however, depending on how much data you back up in your cell and how you
2856             append dumps. Furthermore, the <emphasis role="bold">backup scantape</emphasis> command is subject to several
2857             restrictions. The most basic is that it halts if it finds that an existing dump record in the database has the same dump
2858             ID number as a dump on the tape it is scanning. If you want to continue with the scanning operation, you must locate and
2859             remove the existing record from the database. For further discussion, see the <emphasis role="bold">backup
2860             scantape</emphasis> command's reference page in the <emphasis>OpenAFS Administration Reference</emphasis>.</para>
2861           </listitem>
2862         </itemizedlist></para>
2863
2864       <para>These differences between the databases possibly suggest backing up the database at different frequencies, ranging from
2865       every few days or weekly for the Backup Database to every few weeks for the Authentication Database. On the other hand, it is
2866       probably simpler from a logistical standpoint to back them all up at the same time (and frequently), particularly if tape
2867       consumption is not a major concern. Also, it is not generally necessary to keep backup copies of the databases for a long
2868       time, so you can recycle the tapes fairly frequently.</para>
2869
2870       <indexterm>
2871         <primary>administrative database</primary>
2872
2873         <secondary>backing up</secondary>
2874       </indexterm>
2875
2876       <indexterm>
2877         <primary>backing up</primary>
2878
2879         <secondary>administrative databases</secondary>
2880       </indexterm>
2881     </sect2>
2882
2883     <sect2 id="HDRWQ108">
2884       <title>To back up the administrative databases</title>
2885
2886       <orderedlist>
2887         <listitem>
2888           <para>Log in as the local superuser <emphasis role="bold">root</emphasis> on a database server machine that is not the
2889           synchronization site. The machine with the highest IP address is normally the best choice, since it is least likely to
2890           become the synchronization site in an election.</para>
2891         </listitem>
2892
2893         <listitem>
2894           <para><anchor id="LIDBBK_SHUTDOWN" />Issue the <emphasis role="bold">bos shutdown</emphasis> command to shut down the
2895           relevant server process on the local machine. For a complete description of the command, see <link linkend="HDRWQ168">To
2896           stop processes temporarily</link>.</para>
2897
2898           <para>For the <emphasis role="bold">-instance</emphasis> argument, specify one or more database server process names
2899           (<emphasis role="bold">buserver</emphasis> for the Backup Server, <emphasis role="bold">kaserver</emphasis> for the
2900           Authentication Server, <emphasis role="bold">ptserver</emphasis> for the Protection Server, or <emphasis
2901           role="bold">vlserver</emphasis> for the Volume Location Server. Include the <emphasis role="bold">-localauth</emphasis>
2902           flag because you are logged in as the local superuser <emphasis role="bold">root</emphasis> but do not necessarily have
2903           administrative tokens.</para>
2904
2905           <programlisting>
2906    # <emphasis role="bold">bos shutdown</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">-instance</emphasis> &lt;<replaceable>instances</replaceable>&gt;+ <emphasis
2907               role="bold">-localauth</emphasis> [<emphasis role="bold">-wait</emphasis>]
2908 </programlisting>
2909         </listitem>
2910
2911         <listitem>
2912           <para>Use a local disk backup utility, such as the UNIX <emphasis role="bold">tar</emphasis> command, to transfer one or
2913           more database files to tape. If the local database server machine does not have a tape device attached, use a remote copy
2914           command to transfer the file to a machine with a tape device, then use the <emphasis role="bold">tar</emphasis> command
2915           there.</para>
2916
2917           <para>The following command sequence backs up the complete contents of the <emphasis role="bold">/usr/afs/db</emphasis>
2918           directory</para>
2919
2920           <programlisting>
2921    # <emphasis role="bold">cd /usr/afs/db</emphasis>
2922    # <emphasis role="bold">tar cvf</emphasis>  tape_device <emphasis role="bold">.</emphasis>
2923 </programlisting>
2924
2925           <para>To back up individual database files, substitute their names for the period in the preceding <emphasis
2926           role="bold">tar</emphasis> command: <itemizedlist>
2927               <listitem>
2928                 <para><emphasis role="bold">bdb.DB0</emphasis> for the Backup Database</para>
2929               </listitem>
2930
2931               <listitem>
2932                 <para><emphasis role="bold">kaserver.DB0</emphasis> for the Authentication Database</para>
2933               </listitem>
2934
2935               <listitem>
2936                 <para><emphasis role="bold">prdb.DB0</emphasis> for the Protection Database</para>
2937               </listitem>
2938
2939               <listitem>
2940                 <para><emphasis role="bold">vldb.DB0</emphasis> for the VLDB</para>
2941               </listitem>
2942             </itemizedlist></para>
2943         </listitem>
2944
2945         <listitem>
2946           <para>Issue the <emphasis role="bold">bos start</emphasis> command to restart the server processes on the local machine.
2947           For a complete description of the command, see <link linkend="HDRWQ166">To start processes by changing their status flags
2948           to Run</link>. Provide the same values for the <emphasis role="bold">-instance</emphasis> argument as in Step <link
2949           linkend="LIDBBK_SHUTDOWN">2</link>, and the <emphasis role="bold">-localauth</emphasis> flag for the same reason.
2950           <programlisting>
2951    # <emphasis role="bold">bos start</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">-instance</emphasis> &lt;<replaceable>server process name</replaceable>&gt;+ <emphasis
2952                 role="bold">-localauth</emphasis>
2953 </programlisting></para>
2954         </listitem>
2955       </orderedlist>
2956
2957       <indexterm>
2958         <primary>administrative database</primary>
2959
2960         <secondary>restoring</secondary>
2961       </indexterm>
2962
2963       <indexterm>
2964         <primary>restoring</primary>
2965
2966         <secondary>administrative databases</secondary>
2967       </indexterm>
2968     </sect2>
2969
2970     <sect2 id="HDRWQ109">
2971       <title>To restore an administrative database</title>
2972
2973       <orderedlist>
2974         <listitem>
2975           <para>Log in as the local superuser <emphasis role="bold">root</emphasis> on each database server machine in the
2976           cell.</para>
2977         </listitem>
2978
2979         <listitem>
2980           <para><anchor id="LIDBREST_SHUTDOWN" />Working on one of the machines, issue the <emphasis role="bold">bos
2981           shutdown</emphasis> command once for each database server machine, to shut down the relevant server process on all of
2982           them. For a complete description of the command, see <link linkend="HDRWQ168">To stop processes temporarily</link>.</para>
2983
2984           <para>For the <emphasis role="bold">-instance</emphasis> argument, specify one or more database server process names
2985           (<emphasis role="bold">buserver</emphasis> for the Backup Server, <emphasis role="bold">kaserver</emphasis> for the
2986           Authentication Server, <emphasis role="bold">ptserver</emphasis> for the Protection Server, or <emphasis
2987           role="bold">vlserver</emphasis> for the Volume Location Server. Include the <emphasis role="bold">-localauth</emphasis>
2988           flag because you are logged in as the local superuser <emphasis role="bold">root</emphasis> but do not necessarily have
2989           administrative tokens.</para>
2990
2991           <programlisting>
2992    # <emphasis role="bold">bos shutdown</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">-instance</emphasis> &lt;<replaceable>instances</replaceable>&gt;+ <emphasis
2993               role="bold">-localauth</emphasis> [<emphasis role="bold">-wait</emphasis>]
2994 </programlisting>
2995         </listitem>
2996
2997         <listitem>
2998           <para>Remove the database from each database server machine, by issuing the following commands on each one.
2999           <programlisting>
3000    # <emphasis role="bold">cd /usr/afs/db</emphasis>
3001 </programlisting></para>
3002
3003           <para>For the Backup Database:</para>
3004
3005           <programlisting>
3006    # <emphasis role="bold">rm bdb.DB0</emphasis>
3007    # <emphasis role="bold">rm bdb.DBSYS1</emphasis>
3008 </programlisting>
3009
3010           <para>For the Authentication Database:</para>
3011
3012           <programlisting>
3013    # <emphasis role="bold">rm kaserver.DB0</emphasis>
3014    # <emphasis role="bold">rm kaserver.DBSYS1</emphasis>
3015 </programlisting>
3016
3017           <para>For the Protection Database:</para>
3018
3019           <programlisting>
3020    # <emphasis role="bold">rm prdb.DB0</emphasis>
3021    # <emphasis role="bold">rm prdb.DBSYS1</emphasis>
3022 </programlisting>
3023
3024           <para>For the VLDB:</para>
3025
3026           <programlisting>
3027    # <emphasis role="bold">rm vldb.DB0</emphasis>
3028    # <emphasis role="bold">rm vldb.DBSYS1</emphasis>
3029 </programlisting>
3030         </listitem>
3031
3032         <listitem>
3033           <para>Using the local disk backup utility that you used to back up the database, copy the most recently backed-up version
3034           of it to the appropriate file on the database server machine with the lowest IP address. The following is an appropriate
3035           <emphasis role="bold">tar</emphasis> command if the synchronization site has a tape device attached: <programlisting>
3036    # <emphasis role="bold">cd /usr/afs/db</emphasis>
3037    # <emphasis role="bold">tar xvf</emphasis> tape_device  database_file
3038 </programlisting></para>
3039
3040           <para>where <emphasis>database_file</emphasis> is one of the following: <itemizedlist>
3041               <listitem>
3042                 <para><emphasis role="bold">bdb.DB0</emphasis> for the Backup Database</para>
3043               </listitem>
3044
3045               <listitem>
3046                 <para><emphasis role="bold">kaserver.DB0</emphasis> for the Authentication Database</para>
3047               </listitem>
3048
3049               <listitem>
3050                 <para><emphasis role="bold">prdb.DB0</emphasis> for the Protection Database</para>
3051               </listitem>
3052
3053               <listitem>
3054                 <para><emphasis role="bold">vldb.DB0</emphasis> for the VLDB</para>
3055               </listitem>
3056             </itemizedlist></para>
3057         </listitem>
3058
3059         <listitem>
3060           <para>Working on one of the machines, issue the <emphasis role="bold">bos start</emphasis> command to restart the server
3061           process on each of the database server machines in turn. Start with the machine with the lowest IP address, which becomes
3062           the synchronization site for the Backup Database. Wait for it to establish itself as the synchronization site before
3063           repeating the command to restart the process on the other database server machines. For a complete description of the
3064           command, see <link linkend="HDRWQ166">To start processes by changing their status flags to Run</link>. Provide the same
3065           values for the <emphasis role="bold">-instance</emphasis> argument as in Step <link linkend="LIDBREST_SHUTDOWN">2</link>,
3066           and the <emphasis role="bold">-localauth</emphasis> flag for the same reason. <programlisting>
3067    # <emphasis role="bold">bos start</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">-instance</emphasis>  &lt;<replaceable>server process name</replaceable>&gt;+  <emphasis
3068                 role="bold">-localauth</emphasis>
3069 </programlisting></para>
3070         </listitem>
3071
3072         <listitem>
3073           <para>If the database has changed since you last backed it up, issue the appropriate commands from the instructions in the
3074           indicated sections to recreate the information in the restored database. If issuing <emphasis role="bold">pts</emphasis>
3075           commands, you must first obtain administrative tokens. The <emphasis role="bold">backup</emphasis> and <emphasis
3076           role="bold">vos</emphasis> commands accept the <emphasis role="bold">-localauth</emphasis> flag if you are logged in as
3077           the local superuser <emphasis role="bold">root</emphasis>, so you do not need administrative tokens. The Authentication
3078           Server always performs a separate authentication anyway, so you only need to include the <emphasis
3079           role="bold">-admin</emphasis> argument if issuing <emphasis role="bold">kas</emphasis> commands. <itemizedlist>
3080               <listitem>
3081                 <para>To define or remove volume sets and volume entries in the Backup Database, see <link
3082                 linkend="HDRWQ265">Defining and Displaying Volume Sets and Volume Entries</link>.</para>
3083               </listitem>
3084
3085               <listitem>
3086                 <para>To edit the dump hierarchy in the Backup Database, see <link linkend="HDRWQ267">Defining and Displaying the
3087                 Dump Hierarchy</link>.</para>
3088               </listitem>
3089
3090               <listitem>
3091                 <para>To define or remove Tape Coordinator port offset entries in the Backup Database, see <link
3092                 linkend="HDRWQ261">Configuring Tape Coordinator Machines and Tape Devices</link>.</para>
3093               </listitem>
3094
3095               <listitem>
3096                 <para>To restore dump records in the Backup Database, see <link linkend="HDRWQ305">To scan the contents of a
3097                 tape</link>.</para>
3098               </listitem>
3099
3100               <listitem>
3101                 <para>To recreate Authentication Database entries or password changes for users, see the appropriate section of
3102                 <link linkend="HDRWQ491">Administering User Accounts</link>.</para>
3103               </listitem>
3104
3105               <listitem>
3106                 <para>To recreate Protection Database entries or group membership information, see the appropriate section of <link
3107                 linkend="HDRWQ531">Administering the Protection Database</link>.</para>
3108               </listitem>
3109
3110               <listitem>
3111                 <para>To synchronize the VLDB with volume headers, see <link linkend="HDRWQ227">Synchronizing the VLDB and Volume
3112                 Headers</link>.</para>
3113               </listitem>
3114             </itemizedlist></para>
3115         </listitem>
3116       </orderedlist>
3117
3118       <indexterm>
3119         <primary>installing</primary>
3120
3121         <secondary>server process binaries, about</secondary>
3122       </indexterm>
3123
3124       <indexterm>
3125         <primary>server process binaries</primary>
3126
3127         <secondary>installing</secondary>
3128       </indexterm>
3129
3130       <indexterm>
3131         <primary>BOS Server</primary>
3132
3133         <secondary>maintainer of server process binaries</secondary>
3134       </indexterm>
3135
3136       <indexterm>
3137         <primary>server process</primary>
3138
3139         <secondary>binaries</secondary>
3140
3141         <see>server process binaries</see>
3142       </indexterm>
3143
3144       <indexterm>
3145         <primary>directories (server)</primary>
3146
3147         <secondary>/usr/afs/bin</secondary>
3148       </indexterm>
3149
3150       <indexterm>
3151         <primary>server machine</primary>
3152
3153         <secondary>need for consistent version of software</secondary>
3154       </indexterm>
3155     </sect2>
3156   </sect1>
3157
3158   <sect1 id="HDRWQ110">
3159     <title>Installing Server Process Software</title>
3160
3161     <para>This section explains how to install new server process binaries on file server machines, how to revert to a previous
3162     version if the current version is not working properly, and how to install new disks to house AFS volumes on a file server
3163     machine.</para>
3164
3165     <para>The most frequent reason to replace a server process's binaries is to upgrade AFS to a new version. In general,
3166     installation instructions accompany the updated software, but this chapter provides an additional reference.</para>
3167
3168     <para>Each AFS server machine must store the server process binaries in a local disk directory, called <emphasis
3169     role="bold">/usr/afs/bin</emphasis> by convention. For predictable system performance, it is best that all server machines run
3170     the same build level, or at least the same version, of the server software. For instructions on checking AFS build level, see
3171     <link linkend="HDRWQ117">Displaying A Binary File's Build Level</link>.</para>
3172
3173     <para>The Update Server makes it easy to distribute a consistent version of software to all server machines. You designate one
3174     server machine of each system type as the <emphasis>binary distribution machine</emphasis> by running the server portion of the
3175     Update Server (<emphasis role="bold">upserver</emphasis> process) on it. All other server machines of that system type run the
3176     client portion of the Update Server (<emphasis role="bold">upclientbin</emphasis> process) to retrieve updated software from the
3177     binary distribution machine. The <emphasis>OpenAFS Quick Beginnings</emphasis> explains how to install the appropriate
3178     processes. For more on binary distribution machines, see <link linkend="HDRWQ93">Binary Distribution Machines</link>.</para>
3179
3180     <para>When you use the Update Server, you install new binaries on binary distribution machines only. If you install binaries
3181     directly on a machine that is running the <emphasis role="bold">upclientbin</emphasis> process, they are overwritten the next
3182     time the process compares the contents of the local <emphasis role="bold">/usr/afs/bin</emphasis> directory to the contents on
3183     the system control machine, by default within five minutes.</para>
3184
3185     <para>The following instructions explain how to use the appropriate commands from the <emphasis role="bold">bos</emphasis> suite
3186     to install and uninstall server binaries.</para>
3187
3188     <indexterm>
3189       <primary>installing</primary>
3190
3191       <secondary>server binaries</secondary>
3192     </indexterm>
3193
3194     <indexterm>
3195       <primary>server process binaries</primary>
3196
3197       <secondary>installing</secondary>
3198     </indexterm>
3199
3200     <indexterm>
3201       <primary>command suite</primary>
3202
3203       <secondary>binaries</secondary>
3204
3205       <tertiary>installing</tertiary>
3206     </indexterm>
3207
3208     <indexterm>
3209       <primary>file server machine</primary>
3210
3211       <secondary>installing command and process binaries</secondary>
3212     </indexterm>
3213
3214     <indexterm>
3215       <primary>server process</primary>
3216
3217       <secondary>restarting for changed binaries</secondary>
3218     </indexterm>
3219
3220     <sect2 id="HDRWQ111">
3221       <title>Installing New Binaries</title>
3222
3223       <para>An AFS server process does not automatically switch to a new process binary file as soon as it is installed in the
3224       <emphasis role="bold">/usr/afs/bin</emphasis> directory. The process continues to use the previous version of the binary file
3225       until it (the process) next restarts. By default, the BOS Server restarts processes for which there are new binary files every
3226       day at 5:00 a.m., as specified in the <emphasis role="bold">/usr/afs/local/BosConfig</emphasis> file. To display or change
3227       this <emphasis>binary restart time</emphasis>, use the <emphasis role="bold">bos getrestart</emphasis> and <emphasis
3228       role="bold">bos setrestart</emphasis> commands, as described in <link linkend="HDRWQ171">Setting the BOS Server's Restart
3229       Times</link>.</para>
3230
3231       <para>You can force the server machine to start using new server process binaries immediately by issuing the <emphasis
3232       role="bold">bos restart</emphasis> command as described in the following instructions.</para>
3233
3234       <para>You do not need to restart processes when you install new command suite binaries. The new binary is invoked
3235       automatically the next time a command from the suite is issued.</para>
3236
3237       <indexterm>
3238         <primary>file extension</primary>
3239
3240         <secondary>.BAK</secondary>
3241       </indexterm>
3242
3243       <indexterm>
3244         <primary>file extension</primary>
3245
3246         <secondary>.OLD</secondary>
3247       </indexterm>
3248
3249       <indexterm>
3250         <primary>BAK version of binary file</primary>
3251
3252         <secondary>created by bos install command</secondary>
3253       </indexterm>
3254
3255       <indexterm>
3256         <primary>OLD version of binary file</primary>
3257
3258         <secondary>created by bos install command</secondary>
3259       </indexterm>
3260
3261       <indexterm>
3262         <primary>saving</primary>
3263
3264         <secondary>previous version of server binaries</secondary>
3265       </indexterm>
3266
3267       <para>When you use the <emphasis role="bold">bos install</emphasis> command, the BOS Server automatically saves the current
3268       version of a binary file by adding a <emphasis role="bold">.BAK</emphasis> extension to its name. It renames the current
3269       <emphasis role="bold">.BAK</emphasis> version, if any, to the <emphasis role="bold">.OLD</emphasis> version, if there is no
3270       <emphasis role="bold">.OLD</emphasis> version already. If there is a current <emphasis role="bold">.OLD</emphasis> version,
3271       the current <emphasis role="bold">.BAK</emphasis> version must be at least seven days old to replace it.</para>
3272
3273       <para>It is best to store AFS binaries in the <emphasis role="bold">/usr/afs/bin</emphasis> directory, because that is the
3274       only directory the BOS Server automatically checks for new binaries. You can, however, use the <emphasis role="bold">bos
3275       install</emphasis> command's <emphasis role="bold">-dir</emphasis> argument to install non-AFS binaries into other directories
3276       on a server machine's local disk. See the command's reference page in the <emphasis>OpenAFS Administration
3277       Reference</emphasis> for further information.</para>
3278
3279       <indexterm>
3280         <primary>bos commands</primary>
3281
3282         <secondary>install</secondary>
3283       </indexterm>
3284
3285       <indexterm>
3286         <primary>commands</primary>
3287
3288         <secondary>bos install</secondary>
3289       </indexterm>
3290     </sect2>
3291
3292     <sect2 id="Header_130">
3293       <title>To install new server binaries</title>
3294
3295       <orderedlist>
3296         <listitem>
3297           <para>Verify that you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue
3298           the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To
3299           display the users in the UserList file</link>. <programlisting>
3300    % <emphasis role="bold">bos listusers</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
3301 </programlisting></para>
3302         </listitem>
3303
3304         <listitem>
3305           <para>Verify that the binaries are available in the source directory from which you are installing them. If the machine is
3306           also an AFS client, you can retrieve the binaries from a central directory in AFS. Otherwise, you can obtain them directly
3307           from the AFS distribution media, from a local disk directory where you previously installed them, or from a remote machine
3308           using a transfer utility such as the <emphasis role="bold">ftp</emphasis> command.</para>
3309         </listitem>
3310
3311         <listitem>
3312           <para><anchor id="LIWQ112" />Issue the <emphasis role="bold">bos install</emphasis> command for the binary distribution
3313           machine. (If you have forgotten which machine is performing that role, see <link linkend="HDRWQ97">To locate the binary
3314           distribution machine for a system type</link>.) <programlisting>
3315    % <emphasis role="bold">bos install</emphasis> &lt;<replaceable>machine name</replaceable>&gt; &lt;<replaceable>files to install</replaceable>&gt;+
3316 </programlisting></para>
3317
3318           <para>where <variablelist>
3319               <varlistentry>
3320                 <term><emphasis role="bold">i</emphasis></term>
3321
3322                 <listitem>
3323                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">install</emphasis>.</para>
3324                 </listitem>
3325               </varlistentry>
3326
3327               <varlistentry>
3328                 <term><emphasis role="bold">machine name</emphasis></term>
3329
3330                 <listitem>
3331                   <para>Names the binary distribution machine.</para>
3332                 </listitem>
3333               </varlistentry>
3334
3335               <varlistentry>
3336                 <term><emphasis role="bold">files to install</emphasis></term>
3337
3338                 <listitem>
3339                   <para>Names each binary file to install into the local <emphasis role="bold">/usr/afs/bin</emphasis> directory.
3340                   Partial pathnames are interpreted relative to the current working directory. The last element in each pathname
3341                   (the filename itself) matches the name of the file it is replacing, such as <emphasis
3342                   role="bold">bosserver</emphasis> or <emphasis role="bold">volserver</emphasis> for server processes, <emphasis
3343                   role="bold">bos</emphasis> or <emphasis role="bold">vos</emphasis> for commands.</para>
3344
3345                   <para>Each AFS server process other than the <emphasis role="bold">fs</emphasis> process uses a single binary
3346                   file. The <emphasis role="bold">fs</emphasis> process uses three binary files: <emphasis
3347                   role="bold">fileserver</emphasis>, <emphasis role="bold">volserver</emphasis>, and <emphasis
3348                   role="bold">salvager</emphasis>. Installing a new version of one component does not necessarily mean that you need
3349                   to replace all three.</para>
3350                 </listitem>
3351               </varlistentry>
3352             </variablelist></para>
3353         </listitem>
3354
3355         <listitem>
3356           <para>Repeat Step <link linkend="LIWQ112">3</link> for each binary distribution machine.</para>
3357         </listitem>
3358
3359         <listitem>
3360           <para><emphasis role="bold">(Optional)</emphasis> If you want to restart processes to use the new binaries immediately,
3361           wait until the <emphasis role="bold">upclientbin</emphasis> process retrieves them from the binary distribution machine.
3362           You can verify the timestamps on binary files by using the <emphasis role="bold">bos getdate</emphasis> command as
3363           described in <link linkend="HDRWQ115">Displaying Binary Version Dates</link>. When the binary files are available on each
3364           server machine, issue the <emphasis role="bold">bos restart</emphasis> command, for which complete instructions appear in
3365           <link linkend="HDRWQ170">Stopping and Immediately Restarting Processes</link>.</para>
3366
3367           <para>If you are working on an AFS client machine, it is a wise precaution to have a copy of the <emphasis
3368           role="bold">bos</emphasis> command suite binaries on the local disk before restarting server processes. In the
3369           conventional configuration, the <emphasis role="bold">/usr/afsws/bin</emphasis> directory that houses the <emphasis
3370           role="bold">bos</emphasis> command binary on client machines is a symbolic link into AFS, which conserves local disk
3371           space. However, restarting certain processes (particularly the database server processes) can make the AFS filespace
3372           inaccessible, particularly if a problem arises during the restart. Having a local copy of the <emphasis
3373           role="bold">bos</emphasis> binary enables you to uninstall or reinstall process binaries or restart processes even in this
3374           case. Use the <emphasis role="bold">cp</emphasis> command to copy the <emphasis role="bold">bos</emphasis> command binary
3375           from the <emphasis role="bold">/usr/afsws/bin</emphasis> directory to a local directory such as <emphasis
3376           role="bold">/tmp</emphasis>.</para>
3377
3378           <para>Restarting a process causes a service outage. It is best to perform the restart at times of low system usage if
3379           possible.</para>
3380
3381           <programlisting>
3382    % <emphasis role="bold">bos restart</emphasis> &lt;<replaceable>machine name</replaceable>&gt; &lt;<replaceable>instances</replaceable>&gt;+
3383 </programlisting>
3384         </listitem>
3385       </orderedlist>
3386
3387       <indexterm>
3388         <primary>uninstalling</primary>
3389
3390         <secondary>server process and command suite binaries</secondary>
3391       </indexterm>
3392
3393       <indexterm>
3394         <primary>reverting</primary>
3395
3396         <secondary>to old version of server process and command binaries</secondary>
3397       </indexterm>
3398
3399       <indexterm>
3400         <primary>server process binaries</primary>
3401
3402         <secondary>uninstalling</secondary>
3403       </indexterm>
3404
3405       <indexterm>
3406         <primary>server process binaries</primary>
3407
3408         <secondary>reverting to old version</secondary>
3409       </indexterm>
3410
3411       <indexterm>
3412         <primary>command suite</primary>
3413
3414         <secondary>binaries</secondary>
3415
3416         <tertiary>uninstalling</tertiary>
3417       </indexterm>
3418
3419       <indexterm>
3420         <primary>server machine</primary>
3421
3422         <secondary>uninstalling command &amp; process binaries</secondary>
3423       </indexterm>
3424
3425       <indexterm>
3426         <primary>BAK version of binary file</primary>
3427
3428         <secondary>used by bos uninstall command</secondary>
3429       </indexterm>
3430
3431       <indexterm>
3432         <primary>OLD version of binary file</primary>
3433
3434         <secondary>used by bos uninstall command</secondary>
3435       </indexterm>
3436     </sect2>
3437
3438     <sect2 id="HDRWQ113">
3439       <title>Reverting to the Previous Version of Binaries</title>
3440
3441       <para>In rare cases, installing a new binary can cause problems serious enough to require reverting to the previous version.
3442       Just as with installing binaries, consistent system performance requires reverting every server machine back to the same
3443       version. Issue the <emphasis role="bold">bos uninstall</emphasis> command described here on each binary distribution
3444       machine.</para>
3445
3446       <para>When you use the <emphasis role="bold">bos uninstall</emphasis> command, the BOS Server discards the current version of
3447       a binary file and promotes the <emphasis role="bold">.BAK</emphasis> version of the file by removing the extension. It renames
3448       the current <emphasis role="bold">.OLD</emphasis> version, if any, to <emphasis role="bold">.BAK</emphasis>.</para>
3449
3450       <para>If there is no current <emphasis role="bold">.BAK</emphasis> version, the <emphasis role="bold">bos uninstall</emphasis>
3451       command operation fails and generates an error message. If a <emphasis role="bold">.OLD</emphasis> version still exists, issue
3452       the <emphasis role="bold">mv</emphasis> command to rename it to <emphasis role="bold">.BAK</emphasis> before reissuing the
3453       <emphasis role="bold">bos uninstall</emphasis> command.</para>
3454
3455       <para>Just as when you install new binaries, the server processes do not start using a reverted version immediately.
3456       Presumably you are reverting because the current binaries do not work, so the following instructions have you restart the
3457       relevant processes.</para>
3458
3459       <indexterm>
3460         <primary>bos commands</primary>
3461
3462         <secondary>uninstall</secondary>
3463       </indexterm>
3464
3465       <indexterm>
3466         <primary>commands</primary>
3467
3468         <secondary>bos install</secondary>
3469       </indexterm>
3470     </sect2>
3471
3472     <sect2 id="Header_132">
3473       <title>To revert to the previous version of binaries</title>
3474
3475       <orderedlist>
3476         <listitem>
3477           <para>Verify that you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue
3478           the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To
3479           display the users in the UserList file</link>. <programlisting>
3480    % <emphasis role="bold">bos listusers</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
3481 </programlisting></para>
3482         </listitem>
3483
3484         <listitem>
3485           <para>Verify that the <emphasis role="bold">.BAK</emphasis> version of each relevant binary is available in the <emphasis
3486           role="bold">/usr/afs/bin</emphasis> directory on each binary distribution machine. If necessary, you can use the <emphasis
3487           role="bold">bos getdate</emphasis> command as described in <link linkend="HDRWQ115">Displaying Binary Version
3488           Dates</link>. If necessary, rename the <emphasis role="bold">.OLD</emphasis> version to <emphasis
3489           role="bold">.BAK</emphasis></para>
3490         </listitem>
3491
3492         <listitem>
3493           <para><anchor id="LIWQ114" />Issue the <emphasis role="bold">bos uninstall</emphasis> command for a binary distribution
3494           machine. (If you have forgotten which machine is performing that role, see <link linkend="HDRWQ97">To locate the binary
3495           distribution machine for a system type</link>.) <programlisting>
3496    % <emphasis role="bold">bos uninstall</emphasis> &lt;<replaceable>machine name</replaceable>&gt; &lt;<replaceable>files to uninstall</replaceable>&gt;+
3497 </programlisting></para>
3498
3499           <para>where <variablelist>
3500               <varlistentry>
3501                 <term><emphasis role="bold">u</emphasis></term>
3502
3503                 <listitem>
3504                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">uninstall</emphasis>.</para>
3505                 </listitem>
3506               </varlistentry>
3507
3508               <varlistentry>
3509                 <term><emphasis role="bold">machine name</emphasis></term>
3510
3511                 <listitem>
3512                   <para>Names the binary distribution machine.</para>
3513                 </listitem>
3514               </varlistentry>
3515
3516               <varlistentry>
3517                 <term><emphasis role="bold">files to uninstall</emphasis></term>
3518
3519                 <listitem>
3520                   <para>Names each binary file in the <emphasis role="bold">/usr/afs/bin</emphasis> directory to replace with its
3521                   <emphasis role="bold">.BAK</emphasis> version. The file name alone is sufficient, because the <emphasis
3522                   role="bold">/usr/afs/bin</emphasis> directory is assumed.</para>
3523                 </listitem>
3524               </varlistentry>
3525             </variablelist></para>
3526         </listitem>
3527
3528         <listitem>
3529           <para>Repeat Step <link linkend="LIWQ114">3</link> for each binary distribution machine.</para>
3530         </listitem>
3531
3532         <listitem>
3533           <para>Wait until the <emphasis role="bold">upclientbin</emphasis> process on each server machine retrieves the reverted
3534           from the binary distribution machine. You can verify the timestamps on binary files by using the <emphasis role="bold">bos
3535           getdate</emphasis> command as described in <link linkend="HDRWQ115">Displaying Binary Version Dates</link>. When the
3536           binary files are available on each server machine, issue the <emphasis role="bold">bos restart</emphasis> command, for
3537           which complete instructions appear in <link linkend="HDRWQ170">Stopping and Immediately Restarting
3538           Processes</link>.</para>
3539
3540           <para>If you are working on an AFS client machine, it is a wise precaution to have a copy of the <emphasis
3541           role="bold">bos</emphasis> command suite binaries on the local disk before restarting server processes. In the
3542           conventional configuration, the <emphasis role="bold">/usr/afsws/bin</emphasis> directory that houses the <emphasis
3543           role="bold">bos</emphasis> command binary on client machines is a symbolic link into AFS, which conserves local disk
3544           space. However, restarting certain processes (particularly the database server processes) can make the AFS filespace
3545           inaccessible, particularly if a problem arises during the restart. Having a local copy of the <emphasis
3546           role="bold">bos</emphasis> binary enables you to uninstall or reinstall process binaries or restart processes even in this
3547           case. Use the <emphasis role="bold">cp</emphasis> command to copy the <emphasis role="bold">bos</emphasis> command binary
3548           from the <emphasis role="bold">/usr/afsws/bin</emphasis> directory to a local directory such as <emphasis
3549           role="bold">/tmp</emphasis>.</para>
3550
3551           <programlisting>
3552    % <emphasis role="bold">bos restart</emphasis> &lt;<replaceable>machine name</replaceable>&gt; &lt;<replaceable>instances</replaceable>&gt;+
3553 </programlisting>
3554         </listitem>
3555       </orderedlist>
3556
3557       <indexterm>
3558         <primary>server process binaries</primary>
3559
3560         <secondary>displaying time stamp</secondary>
3561       </indexterm>
3562
3563       <indexterm>
3564         <primary>command suite</primary>
3565
3566         <secondary>binaries</secondary>
3567
3568         <tertiary>displaying time stamp</tertiary>
3569       </indexterm>
3570
3571       <indexterm>
3572         <primary>time stamp</primary>
3573
3574         <secondary>on binary file, listing</secondary>
3575       </indexterm>
3576
3577       <indexterm>
3578         <primary>date</primary>
3579
3580         <secondary>on binary file, listing</secondary>
3581       </indexterm>
3582
3583       <indexterm>
3584         <primary>compilation</primary>
3585
3586         <secondary>date of, listing on binary file</secondary>
3587       </indexterm>
3588
3589       <indexterm>
3590         <primary>displaying</primary>
3591
3592         <secondary>time stamp on binary file</secondary>
3593       </indexterm>
3594     </sect2>
3595
3596     <sect2 id="HDRWQ115">
3597       <title>Displaying Binary Version Dates</title>
3598
3599       <para>You can check the compilation dates for all three versions of a binary file in the <emphasis
3600       role="bold">/usr/afs/bin</emphasis> directory--the current, <emphasis role="bold">.BAK</emphasis> and .<emphasis
3601       role="bold">OLD</emphasis> versions. This is useful for verifying that new binaries have been copied to a file server machine
3602       from its binary distribution machine before restarting a server process to use the new binaries.</para>
3603
3604       <para>To check dates on binaries in a directory other than <emphasis role="bold">/usr/afs/bin</emphasis>, add the <emphasis
3605       role="bold">-dir</emphasis> argument. See the <emphasis>OpenAFS Administration Reference</emphasis>.</para>
3606
3607       <indexterm>
3608         <primary>bos commands</primary>
3609
3610         <secondary>getdate</secondary>
3611       </indexterm>
3612
3613       <indexterm>
3614         <primary>commands</primary>
3615
3616         <secondary>bos getdate</secondary>
3617       </indexterm>
3618     </sect2>
3619
3620     <sect2 id="Header_134">
3621       <title>To display binary version dates</title>
3622
3623       <orderedlist>
3624         <listitem>
3625           <para>Issue the <emphasis role="bold">bos getdate</emphasis> command. <programlisting>
3626    % <emphasis role="bold">bos getdate</emphasis> &lt;<replaceable>machine name</replaceable>&gt; &lt;<replaceable>files to check</replaceable>&gt;+
3627 </programlisting></para>
3628
3629           <para>where <variablelist>
3630               <varlistentry>
3631                 <term><emphasis role="bold">getd</emphasis></term>
3632
3633                 <listitem>
3634                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">getdate</emphasis>.</para>
3635                 </listitem>
3636               </varlistentry>
3637
3638               <varlistentry>
3639                 <term><emphasis role="bold">machine name</emphasis></term>
3640
3641                 <listitem>
3642                   <para>Name the file server machine for which to display binary dates.</para>
3643                 </listitem>
3644               </varlistentry>
3645
3646               <varlistentry>
3647                 <term><emphasis role="bold">files to check</emphasis></term>
3648
3649                 <listitem>
3650                   <para>Names each binary file to display.</para>
3651                 </listitem>
3652               </varlistentry>
3653             </variablelist></para>
3654         </listitem>
3655       </orderedlist>
3656
3657       <indexterm>
3658         <primary>BAK version of binary file</primary>
3659
3660         <secondary>removing obsolete</secondary>
3661       </indexterm>
3662
3663       <indexterm>
3664         <primary>OLD version of binary file</primary>
3665
3666         <secondary>removing obsolete</secondary>
3667       </indexterm>
3668
3669       <indexterm>
3670         <primary>removing</primary>
3671
3672         <secondary>obsolete .BAK and .OLD version of binaries</secondary>
3673       </indexterm>
3674
3675       <indexterm>
3676         <primary>server process binaries</primary>
3677
3678         <secondary>removing obsolete</secondary>
3679       </indexterm>
3680
3681       <indexterm>
3682         <primary>command suite</primary>
3683
3684         <secondary>binaries</secondary>
3685
3686         <tertiary>removing obsolete</tertiary>
3687       </indexterm>
3688
3689       <indexterm>
3690         <primary>removing</primary>
3691
3692         <secondary>core files from /usr/afs/logs</secondary>
3693       </indexterm>
3694
3695       <indexterm>
3696         <primary>core files</primary>
3697
3698         <secondary>removing from /usr/afs/logs directory</secondary>
3699       </indexterm>
3700
3701       <indexterm>
3702         <primary>usr/afs/bin directory</primary>
3703
3704         <secondary>removing obsolete .BAK and .OLD files</secondary>
3705       </indexterm>
3706     </sect2>
3707
3708     <sect2 id="HDRWQ116">
3709       <title>Removing Obsolete Binary Files</title>
3710
3711       <para>When processes with new binaries have been running without problems for a number of days, it is generally safe to remove
3712       the <emphasis role="bold">.BAK</emphasis> and <emphasis role="bold">.OLD</emphasis> versions from the <emphasis
3713       role="bold">/usr/afs/bin</emphasis> directory, both to reduce clutter and to free space on the file server machine's local
3714       disk.</para>
3715
3716       <para>You can use the <emphasis role="bold">bos prune</emphasis> command's flags to remove the following types of files:
3717       <itemizedlist>
3718           <listitem>
3719             <para>To remove files in the <emphasis role="bold">/usr/afs/bin</emphasis> directory with a <emphasis
3720             role="bold">.BAK</emphasis> extension, use the <emphasis role="bold">-bak</emphasis> flag.</para>
3721           </listitem>
3722
3723           <listitem>
3724             <para>To remove files in the <emphasis role="bold">/usr/afs/bin</emphasis> directory with a <emphasis
3725             role="bold">.OLD</emphasis> extension, use the <emphasis role="bold">-old</emphasis> flag.</para>
3726           </listitem>
3727
3728           <listitem>
3729             <para>To remove files in the <emphasis role="bold">/usr/afs/logs</emphasis> directory called <emphasis
3730             role="bold">core</emphasis>, with any extension, use the <emphasis role="bold">-core</emphasis> flag.</para>
3731           </listitem>
3732
3733           <listitem>
3734             <para>To remove all three types of files, use the <emphasis role="bold">-all</emphasis> flag.</para>
3735           </listitem>
3736         </itemizedlist></para>
3737
3738       <indexterm>
3739         <primary>commands</primary>
3740
3741         <secondary>bos prune</secondary>
3742       </indexterm>
3743
3744       <indexterm>
3745         <primary>bos commands</primary>
3746
3747         <secondary>prune</secondary>
3748       </indexterm>
3749     </sect2>
3750
3751     <sect2 id="Header_136">
3752       <title>To remove obsolete binaries</title>
3753
3754       <orderedlist>
3755         <listitem>
3756           <para>Verify that you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue
3757           the <emphasis role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To
3758           display the users in the UserList file</link>. <programlisting>
3759    % <emphasis role="bold">bos listusers</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
3760 </programlisting></para>
3761         </listitem>
3762
3763         <listitem>
3764           <para>Issue the <emphasis role="bold">bos prune</emphasis> command with one or more of its flags. <programlisting>
3765    % <emphasis role="bold">bos prune</emphasis> &lt;<replaceable>machine name</replaceable>&gt; [<emphasis role="bold">-bak</emphasis>] [<emphasis
3766                 role="bold">-old</emphasis>] [<emphasis role="bold">-core</emphasis>] [<emphasis role="bold">-all</emphasis>]
3767 </programlisting></para>
3768
3769           <para>where <variablelist>
3770               <varlistentry>
3771                 <term><emphasis role="bold">p</emphasis></term>
3772
3773                 <listitem>
3774                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">prune</emphasis