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