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