ec90747782294c5081d18fb9c50a4562033b0450
[openafs.git] / doc / xml / QuickStartUnix / auqbg006.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <chapter id="HDRWQ99">
3   <title>Installing Additional Server Machines</title>
4
5   <para>
6   <indexterm>
7     <primary>instructions</primary>
8
9     <secondary>file server machine after first</secondary>
10   </indexterm>
11
12   <indexterm>
13     <primary>installing</primary>
14
15     <secondary>file server machine after first</secondary>
16   </indexterm>
17
18   <indexterm>
19     <primary>server machine after first</primary>
20
21     <see>file server machine, additional</see>
22   </indexterm>
23
24   Instructions for the following procedures appear in the indicated section of this chapter. <itemizedlist>
25       <listitem>
26         <para><link linkend="HDRWQ100">Installing an Additional File Server Machine</link></para>
27       </listitem>
28
29       <listitem>
30         <para><link linkend="HDRWQ114">Installing Database Server Functionality</link></para>
31       </listitem>
32
33       <listitem>
34         <para><link linkend="HDRWQ125">Removing Database Server Functionality</link></para>
35       </listitem>
36     </itemizedlist></para>
37
38   <para>The instructions make the following assumptions. <itemizedlist>
39       <listitem>
40         <para>You have already installed your cell's first file server machine by following the instructions in <link
41         linkend="HDRWQ17">Installing the First AFS Machine</link></para>
42       </listitem>
43
44       <listitem>
45         <para>You are logged in as the local superuser <emphasis role="bold">root</emphasis></para>
46       </listitem>
47
48       <listitem>
49         <para>You are working at the console</para>
50       </listitem>
51
52       <listitem>
53         <para>A standard version of one of the operating systems supported by the current version of AFS is running on the
54         machine</para>
55       </listitem>
56
57       <listitem>
58         <para>You can access the data on the OpenAFS Binary Distribution for
59         your operating system, either on the local filesystem or via an NFS
60         mount of the distribution's contents.</para>
61       </listitem>
62     </itemizedlist>
63
64   <indexterm>
65     <primary>requirements</primary>
66
67     <secondary>file server machine (additional)</secondary>
68   </indexterm>
69   </para>
70
71   <sect1 id="HDRWQ100">
72     <title>Installing an Additional File Server Machine</title>
73
74     <para>The procedure for installing a new file server machine is similar to installing the first file server machine in your
75     cell. There are a few parts of the installation that differ depending on whether the machine is the same AFS system type as an
76     existing file server machine or is the first file server machine of its system type in your cell. The differences mostly concern
77     the source for the needed binaries and files, and what portions of the Update Server you install: <itemizedlist>
78         <listitem>
79           <para>On a new system type, you must load files and binaries from the 
80           OpenAFS distribution. You may install the server portion of the
81           Update Server to make this machine the binary distribution machine 
82           for its system type.</para>
83         </listitem>
84
85         <listitem>
86           <para>On an existing system type, you can copy files and binaries 
87           from a previously installed file server machine, rather
88           than from the OpenAFS distribution. You may install the client 
89           portion of the Update Server to accept updates of binaries, because a
90           previously installed machine of this type was installed as the binary 
91           distribution machine.</para>
92         </listitem>
93         <listitem>
94           <para>On some system types, distribtution of the appropriate binaries
95           may be acheived using the system's own package management system. In
96           these cases, it is recommended that this system is used, rather than
97           installing the binaries by hand.</para>
98         </listitem>
99       </itemizedlist></para>
100
101     <para>These instructions are brief; for more detailed information, refer to the corresponding steps in <link
102     linkend="HDRWQ17">Installing the First AFS Machine</link>. <indexterm>
103         <primary>overview</primary>
104
105         <secondary>installing server machine after first</secondary>
106       </indexterm></para>
107
108     <para>To install a new file server machine, perform the following procedures: <orderedlist>
109         <listitem>
110           <para>Copy needed binaries and files onto this machine's local disk,
111           as required.</para>
112         </listitem>
113
114         <listitem>
115           <para>Incorporate AFS modifications into the kernel</para>
116         </listitem>
117
118         <listitem>
119           <para>Configure partitions for storing volumes</para>
120         </listitem>
121
122         <listitem>
123           <para>Replace the standard <emphasis role="bold">fsck</emphasis> utility with the AFS-modified version on some system
124           types</para>
125         </listitem>
126
127         <listitem>
128           <para>Start the Basic OverSeer (BOS) Server</para>
129         </listitem>
130
131         <listitem>
132           <para>Start the appropriate portion of the Update Server, if 
133           required</para>
134         </listitem>
135
136         <listitem>
137           <para>Start the <emphasis role="bold">fs</emphasis> process, which incorporates three component processes: the File
138           Server, Volume Server, and Salvager</para>
139         </listitem>
140       </orderedlist></para>
141
142     <para>After completing the instructions in this section, you can install database server functionality on the machine according
143     to the instructions in <link linkend="HDRWQ114">Installing Database Server Functionality</link>. <indexterm>
144         <primary>usr/afs directory</primary>
145
146         <secondary>server machine after first</secondary>
147       </indexterm> <indexterm>
148         <primary>file server machine, additional</primary>
149
150         <secondary>/usr/afs directory</secondary>
151       </indexterm> <indexterm>
152         <primary>creating</primary>
153
154         <secondary>/usr/afs directory</secondary>
155
156         <tertiary>server machine after first</tertiary>
157       </indexterm> <indexterm>
158         <primary>usr/afs/bin directory</primary>
159
160         <secondary>server machine after first</secondary>
161       </indexterm> <indexterm>
162         <primary>file server machine, additional</primary>
163
164         <secondary>/usr/afs/bin directory</secondary>
165       </indexterm> <indexterm>
166         <primary>creating</primary>
167
168         <secondary>/usr/afs/bin directory</secondary>
169
170         <tertiary>server machine after first</tertiary>
171       </indexterm> <indexterm>
172         <primary>usr/vice/etc directory</primary>
173
174         <secondary>server machine after first</secondary>
175       </indexterm> <indexterm>
176         <primary>file server machine, additional</primary>
177
178         <secondary>/usr/vice/etc directory</secondary>
179       </indexterm> <indexterm>
180         <primary>creating</primary>
181
182         <secondary>/usr/vice/etc directory</secondary>
183
184         <tertiary>server machine after first</tertiary>
185       </indexterm></para>
186
187     <sect2 id="Header_99">
188       <title>Creating AFS Directories and Performing Platform-Specific Procedures</title>
189
190       <para>If your operating systems AFS distribution is supplied as packages,
191       such as .rpms or .debs, you should just install those packages as detailed
192       in the previous chapter.</para>
193       
194       <para>Create the <emphasis role="bold">/usr/afs</emphasis> and <emphasis role="bold">/usr/vice/etc</emphasis> directories on
195       the local disk. Subsequent instructions copy files from the AFS distribution into them, at the appropriate point for
196       each system type.</para>
197
198       <programlisting>
199    # <emphasis role="bold">mkdir /usr/afs</emphasis>
200    # <emphasis role="bold">mkdir /usr/afs/bin</emphasis>
201    # <emphasis role="bold">mkdir /usr/vice</emphasis>
202    # <emphasis role="bold">mkdir /usr/vice/etc</emphasis>
203    # <emphasis role="bold">mkdir /tmp/afsdist</emphasis>     
204 </programlisting>
205
206       <para>As on the first file server machine, the initial procedures in installing an additional file server machine vary a good
207       deal from platform to platform. For convenience, the following sections group together all of the procedures for a system
208       type. Most of the remaining procedures are the same on every system type, but differences are noted as appropriate. The
209       initial procedures are the following. <itemizedlist>
210           <listitem>
211             <para>Incorporate AFS modifications into the kernel, either by using a dynamic kernel loader program or by building a
212             new static kernel</para>
213           </listitem>
214
215           <listitem>
216             <para>Configure server partitions to house AFS volumes</para>
217           </listitem>
218
219           <listitem>
220             <para>Replace the operating system vendor's <emphasis role="bold">fsck</emphasis> program with a version that recognizes
221             AFS data <indexterm>
222                 <primary>file server machine, additional</primary>
223
224                 <secondary>AFS login</secondary>
225
226                 <see>first AFS machine</see>
227               </indexterm></para>
228           </listitem>
229
230           <listitem>
231             <para>If the machine is to remain an AFS client machine, modify the machine's authentication system so that users obtain
232             an AFS token as they log into the local file system. (For this procedure only, the instructions direct you to the
233             platform-specific section in <link linkend="HDRWQ17">Installing the First AFS Machine</link>.)</para>
234           </listitem>
235         </itemizedlist></para>
236
237       <para>To continue, proceed to the section for this system type: <itemizedlist>
238           <listitem>
239             <para><link linkend="HDRWQ101">Getting Started on AIX Systems</link></para>
240           </listitem>
241
242           <listitem>
243             <para><link linkend="HDRWQ106">Getting Started on Linux Systems</link></para>
244           </listitem>
245
246           <listitem>
247             <para><link linkend="HDRWQ107">Getting Started on Solaris Systems</link></para>
248           </listitem>
249         </itemizedlist></para>
250
251       <sect3 id="HDRWQ101">
252         <title>Getting Started on AIX Systems</title>
253
254         <para>Begin by running the AFS initialization script to call the AIX kernel extension facility, which dynamically loads AFS
255         modifications into the kernel. Then configure partitions and replace the AIX <emphasis role="bold">fsck</emphasis> program
256         with a version that correctly handles AFS volumes. <orderedlist>
257             <indexterm>
258               <primary>incorporating AFS kernel extensions</primary>
259
260               <secondary>server machine after first</secondary>
261
262               <tertiary>AIX</tertiary>
263             </indexterm>
264
265             <indexterm>
266               <primary>AFS kernel extensions</primary>
267
268               <secondary>on server machine after first</secondary>
269
270               <tertiary>AIX</tertiary>
271             </indexterm>
272
273             <indexterm>
274               <primary>file server machine, additional</primary>
275
276               <secondary>AFS kernel extensions</secondary>
277
278               <tertiary>on AIX</tertiary>
279             </indexterm>
280
281             <indexterm>
282               <primary>AIX</primary>
283
284               <secondary>AFS kernel extensions</secondary>
285
286               <tertiary>on add'l server machine</tertiary>
287             </indexterm>
288
289             <listitem>
290               <para>Unpack the distribution tarball. The examples below assume 
291               that you have unpacked the files into the 
292               <emphasis role="bold">/tmp/afsdist</emphasis> directory. If you 
293               pick a different location, substitute this in all of the following 
294               examples. Once you have unpacked the distribution, 
295               change directory as indicated.
296 <programlisting>
297    # <emphasis role="bold">cd /tmp/afsdist/rs_aix42/dest/root.client/usr/vice/etc</emphasis>
298 </programlisting></para>
299             </listitem>
300
301             <listitem>
302               <para>Copy the AFS kernel library files to the local <emphasis role="bold">/usr/vice/etc/dkload</emphasis> directory,
303               and the AFS initialization script to the <emphasis role="bold">/etc</emphasis> directory. <programlisting>
304    # <emphasis role="bold">cp -rp  dkload  /usr/vice/etc</emphasis>
305    # <emphasis role="bold">cp -p  rc.afs  /etc/rc.afs</emphasis>
306 </programlisting></para>
307             </listitem>
308
309             <listitem>
310               <para>Edit the <emphasis role="bold">/etc/rc.afs</emphasis> script, setting the <computeroutput>NFS</computeroutput>
311               variable as indicated.</para>
312
313               <para>If the machine is not to function as an NFS/AFS Translator, set the <computeroutput>NFS</computeroutput>
314               variable as follows.</para>
315
316               <programlisting>
317    NFS=$NFS_NONE
318 </programlisting>
319
320               <para>If the machine is to function as an NFS/AFS Translator and is running AIX 4.2.1 or higher, set the
321               <computeroutput>NFS</computeroutput> variable as follows. Note that NFS must already be loaded into the kernel, which
322               happens automatically on systems running AIX 4.1.1 and later, as long as the file <emphasis
323               role="bold">/etc/exports</emphasis> exists.</para>
324
325               <programlisting>
326    NFS=$NFS_IAUTH
327 </programlisting>
328             </listitem>
329
330             <listitem>
331               <para>Invoke the <emphasis role="bold">/etc/rc.afs</emphasis> script to load AFS modifications into the kernel. You
332               can ignore any error messages about the inability to start the BOS Server or the Cache Manager or AFS client.
333               <programlisting>
334    # <emphasis role="bold">/etc/rc.afs</emphasis>
335 </programlisting> <indexterm>
336                   <primary>configuring</primary>
337
338                   <secondary>AFS server partition on server machine after first</secondary>
339
340                   <tertiary>AIX</tertiary>
341                 </indexterm> <indexterm>
342                   <primary>AFS server partition</primary>
343
344                   <secondary>configuring on server machine after first</secondary>
345
346                   <tertiary>AIX</tertiary>
347                 </indexterm> <indexterm>
348                   <primary>file server machine, additional</primary>
349
350                   <secondary>AFS server partition</secondary>
351
352                   <tertiary>on AIX</tertiary>
353                 </indexterm> <indexterm>
354                   <primary>AIX</primary>
355
356                   <secondary>AFS server partition</secondary>
357
358                   <tertiary>on add'l server machine</tertiary>
359                 </indexterm></para>
360             </listitem>
361
362             <listitem>
363               <para>Create a directory called <emphasis role="bold">/vicep</emphasis><replaceable>xx</replaceable> for each AFS
364               server partition you are configuring (there must be at least one). Repeat the command for each partition.
365               <programlisting>
366    # <emphasis role="bold">mkdir /vicep</emphasis><replaceable>xx</replaceable>
367 </programlisting></para>
368             </listitem>
369
370             <listitem>
371               <para>Use the <emphasis role="bold">SMIT</emphasis> program to create a journaling file system on each partition to be
372               configured as an AFS server partition.</para>
373             </listitem>
374
375             <listitem>
376               <para>Mount each partition at one of the <emphasis role="bold">/vicep</emphasis><replaceable>xx</replaceable>
377               directories. Choose one of the following three methods: <itemizedlist>
378                   <listitem>
379                     <para>Use the <emphasis role="bold">SMIT</emphasis> program</para>
380                   </listitem>
381
382                   <listitem>
383                     <para>Use the <emphasis role="bold">mount -a</emphasis> command to mount all partitions at once</para>
384                   </listitem>
385
386                   <listitem>
387                     <para>Use the <emphasis role="bold">mount</emphasis> command on each partition in turn</para>
388                   </listitem>
389                 </itemizedlist></para>
390
391               <para>Also configure the partitions so that they are mounted automatically at each reboot. For more information, refer
392               to the AIX documentation. <indexterm>
393                   <primary>replacing fsck program</primary>
394
395                   <secondary>server machine after first</secondary>
396
397                   <tertiary>AIX</tertiary>
398                 </indexterm> <indexterm>
399                   <primary>fsck program</primary>
400
401                   <secondary>on server machine after first</secondary>
402
403                   <tertiary>AIX</tertiary>
404                 </indexterm> <indexterm>
405                   <primary>file server machine, additional</primary>
406
407                   <secondary>fsck program</secondary>
408
409                   <tertiary>on AIX</tertiary>
410                 </indexterm> <indexterm>
411                   <primary>AIX</primary>
412
413                   <secondary>fsck program</secondary>
414
415                   <tertiary>on add'l server machine</tertiary>
416                 </indexterm></para>
417             </listitem>
418
419             <listitem>
420               <para>On systems prior to AIX 5.1, move the AIX 
421               <emphasis role="bold">fsck</emphasis> program helper to a safe 
422               location and install the version from the AFS distribution in 
423               its place. Note that on AIX 5.1, and later, systems this step is
424               not required, and the <emphasis role="bold">v3fshelper</emphasis>
425               program is not shipped for these systems.</para>
426               
427               <para>The AFS binary distribution must still be available in the
428               <emphasis role="bold">/tmp/afsdist</emphasis> directory. 
429 <programlisting>
430    # <emphasis role="bold">cd /sbin/helpers</emphasis>
431    # <emphasis role="bold">mv v3fshelper v3fshelper.noafs</emphasis>
432    # <emphasis role="bold">cp -p /tmp/afsdist/rs_aix42/dest/root.server/etc/v3fshelper v3fshelper</emphasis>
433 </programlisting></para>
434             </listitem>
435
436             <listitem>
437               <para>If the machine is to remain an AFS client, incorporate AFS into its authentication system, following the
438               instructions in <link linkend="HDRWQ25">Enabling AFS Login on AIX Systems</link>.</para>
439             </listitem>
440
441             <listitem>
442               <para>Proceed to <link linkend="HDRWQ108">Starting Server Programs</link>.</para>
443             </listitem>
444           </orderedlist></para>
445       </sect3>
446
447       <sect3 id="HDRWQ106">
448         <title>Getting Started on Linux Systems</title>
449
450         <indexterm>
451           <primary>file server machine, additional</primary>
452
453           <secondary>fsck program</secondary>
454
455           <tertiary>on Linux</tertiary>
456         </indexterm>
457
458         <indexterm>
459           <primary>fsck program</primary>
460
461           <secondary>on server machine after first</secondary>
462
463           <tertiary>Linux</tertiary>
464         </indexterm>
465
466         <para>Begin by running the AFS initialization script to call the <emphasis role="bold">insmod</emphasis> program, which
467         dynamically loads AFS modifications into the kernel. Then create partitions for storing AFS volumes. You do not need to
468         replace the Linux <emphasis role="bold">fsck</emphasis> program.</para>
469         
470         <para> The procedure for starting up OpenAFS depends upon your distribution</para>
471           <orderedlist>
472             <listitem>
473               <para>For Fedora and RedHat Enterprise Linux systems (or their
474               derivateds), download and install the RPM set for your operating system
475               from the OpenAFS distribution site. You will need the
476               <emphasis role="bold">openafs</emphasis> and
477               <emphasis role="bold">openafs-server</emphasis> packages, along
478               with an <emphasis role="bold">openafs-kernel</emphasis> package
479               matching your current, running, kernel. If you wish to install
480               client functionality, you will also require the
481               <emphasis role="bold">openafs-client</emphasis> package.</para>
482              
483               <para>You can find the version of your current kernel by running
484 <programlisting>
485   # uname -r
486 <replaceable>2.6.20-1.2933.fc6</replaceable>
487 </programlisting></para>
488  
489               <para>Once downloaded, the packages may be installed with the
490               <emphasis role="bold">rpm</emphasis> command
491 <programlisting>
492   # rpm -U openafs-* openafs-client-* openafs-server-* openafs-kernel-*
493 </programlisting></para>
494             </listitem>
495             <listitem>
496             <indexterm>
497               <primary>incorporating AFS kernel extensions</primary>
498
499               <secondary>server machine after first</secondary>
500
501               <tertiary>Linux</tertiary>
502             </indexterm>
503
504             <indexterm>
505               <primary>AFS kernel extensions</primary>
506
507               <secondary>on server machine after first</secondary>
508
509               <tertiary>Linux</tertiary>
510             </indexterm>
511
512             <indexterm>
513               <primary>file server machine, additional</primary>
514
515               <secondary>AFS kernel extensions</secondary>
516
517               <tertiary>on Linux</tertiary>
518             </indexterm>
519
520             <indexterm>
521               <primary>Linux</primary>
522
523               <secondary>AFS kernel extensions</secondary>
524
525               <tertiary>on add'l server machine</tertiary>
526             </indexterm>
527               <para>For systems which are provided as a tarball, or built from
528               source, unpack the distribution tarball. The examples below assume
529               that you have unpacked the files into the
530               <emphasis role="bold">/tmp/afsdist</emphasis>directory. If you
531               pick a different location, substitute this in all of the following
532               examples. Once you have unpacked the distribution,
533               change directory as indicated.
534 <programlisting>
535   # <emphasis role="bold">cd /tmp/afsdist/linux/dest/root.client/usr/vice/etc</emphasis>
536 </programlisting></para>
537
538               <para>Copy the AFS kernel library files to the local <emphasis role="bold">/usr/vice/etc/modload</emphasis> directory.
539               The filenames for the libraries have the format <emphasis
540               role="bold">libafs-</emphasis><replaceable>version</replaceable><emphasis role="bold">.o</emphasis>, where
541               <replaceable>version</replaceable> indicates the kernel build level. The string <emphasis role="bold">.mp</emphasis>
542               in the <replaceable>version</replaceable> indicates that the file is appropriate for machines running a multiprocessor
543               kernel. <programlisting>
544    # <emphasis role="bold">cp -rp  modload  /usr/vice/etc</emphasis>
545 </programlisting></para>
546             
547               <para>Copy the AFS initialization script to the local directory for initialization files (by convention, <emphasis
548               role="bold">/etc/rc.d/init.d</emphasis> on Linux machines). Note the removal of the <emphasis
549               role="bold">.rc</emphasis> extension as you copy the script. <programlisting>
550    # <emphasis role="bold">cp -p   afs.rc  /etc/rc.d/init.d/afs</emphasis> 
551 </programlisting></para>
552             </listitem>
553             <listitem>
554                 <indexterm>
555                   <primary>configuring</primary>
556
557                   <secondary>AFS server partition on server machine after first</secondary>
558
559                   <tertiary>Linux</tertiary>
560                 </indexterm> <indexterm>
561                   <primary>AFS server partition</primary>
562
563                   <secondary>configuring on server machine after first</secondary>
564
565                   <tertiary>Linux</tertiary>
566                 </indexterm> <indexterm>
567                   <primary>file server machine, additional</primary>
568
569                   <secondary>AFS server partition</secondary>
570
571                   <tertiary>on Linux</tertiary>
572                 </indexterm> <indexterm>
573                   <primary>Linux</primary>
574
575                   <secondary>AFS server partition</secondary>
576
577                   <tertiary>on add'l server machine</tertiary>
578                 </indexterm>
579               <para>Create a directory called <emphasis role="bold">/vicep</emphasis><replaceable>xx</replaceable> for each AFS
580               server partition you are configuring (there must be at least one). Repeat the command for each partition.
581               <programlisting>
582    # <emphasis role="bold">mkdir /vicep</emphasis><replaceable>xx</replaceable>
583 </programlisting></para>
584             </listitem>
585
586             <listitem>
587               <para>Add a line with the following format to the file systems registry file, <emphasis
588               role="bold">/etc/fstab</emphasis>, for each directory just created. The entry maps the directory name to the disk
589               partition to be mounted on it. <programlisting>
590    /dev/<replaceable>disk</replaceable>  /vicep<replaceable>xx</replaceable>  ext2  defaults  0  2   
591 </programlisting></para>
592
593               <para>The following is an example for the first partition being configured.</para>
594
595               <programlisting>
596    /dev/sda8 /vicepa ext2 defaults 0 2
597 </programlisting>
598             </listitem>
599
600             <listitem>
601               <para>Create a file system on each partition that is to be mounted at a <emphasis
602               role="bold">/vicep</emphasis><replaceable>xx</replaceable> directory. The following command is probably appropriate,
603               but consult the Linux documentation for more information. <programlisting>
604    # <emphasis role="bold">mkfs -v /dev/</emphasis><replaceable>disk</replaceable>
605 </programlisting></para>
606             </listitem>
607
608             <listitem>
609               <para>Mount each partition by issuing either the <emphasis role="bold">mount -a</emphasis> command to mount all
610               partitions at once or the <emphasis role="bold">mount</emphasis> command to mount each partition in turn.</para>
611             </listitem>
612
613             <listitem>
614               <para>If the machine is to remain an AFS client, incorporate AFS into its authentication system, following the
615               instructions in <link linkend="HDRWQ44">Enabling AFS Login on Linux Systems</link>.</para>
616             </listitem>
617
618             <listitem>
619               <para>Proceed to <link linkend="HDRWQ108">Starting Server Programs</link>.</para>
620             </listitem>
621           </orderedlist>
622       </sect3>
623
624       <sect3 id="HDRWQ107">
625         <title>Getting Started on Solaris Systems</title>
626
627         <para>Begin by running the AFS initialization script to call the <emphasis role="bold">modload</emphasis> program, which
628         dynamically loads AFS modifications into the kernel. Then configure partitions and replace the Solaris <emphasis
629         role="bold">fsck</emphasis> program with a version that correctly handles AFS volumes. <orderedlist>
630             <indexterm>
631               <primary>incorporating AFS kernel extensions</primary>
632
633               <secondary>server machine after first</secondary>
634
635               <tertiary>Solaris</tertiary>
636             </indexterm>
637
638             <indexterm>
639               <primary>AFS kernel extensions</primary>
640
641               <secondary>on server machine after first</secondary>
642
643               <tertiary>Solaris</tertiary>
644             </indexterm>
645
646             <indexterm>
647               <primary>file server machine, additional</primary>
648
649               <secondary>AFS kernel extensions</secondary>
650
651               <tertiary>Solaris</tertiary>
652             </indexterm>
653
654             <indexterm>
655               <primary>Solaris</primary>
656
657               <secondary>AFS kernel extensions</secondary>
658
659               <tertiary>on add'l server machine</tertiary>
660             </indexterm>
661
662             <listitem>
663               <para>Unpack the OpenAFS Solaris distribution tarball. The examples
664               below assume that you have unpacked the files into the 
665               <emphasis role="bold">/tmp/afsdist</emphasis> directory. If you 
666               pick a diferent location, substitute this in all of the following
667               exmaples. Once you have unpacked the distribution, change directory
668               as indicated. 
669 <programlisting>
670    # <emphasis role="bold">cd  /tmp/afsdist/sun4x_56/dest/root.client/usr/vice/etc</emphasis>
671 </programlisting></para>
672             </listitem>
673
674             <listitem>
675               <para>Copy the AFS initialization script to the local directory for initialization files (by convention, <emphasis
676               role="bold">/etc/init.d</emphasis> on Solaris machines). Note the removal of the <emphasis role="bold">.rc</emphasis>
677               extension as you copy the script. <programlisting>
678    # <emphasis role="bold">cp -p  afs.rc  /etc/init.d/afs</emphasis>
679 </programlisting></para>
680             </listitem>
681
682             <listitem>
683               <para>Copy the appropriate AFS kernel library file to the local file <emphasis
684               role="bold">/kernel/fs/afs</emphasis>.</para>
685
686             <para>If the machine is running Solaris 11 on the x86_64 platform:</para>
687
688             <programlisting>
689    # <emphasis role="bold">cp -p modload/libafs64.o /kernel/drv/amd64/afs</emphasis>
690 </programlisting>
691
692             <para>If the machine is running Solaris 10 on the x86_64 platform:</para>
693
694             <programlisting>
695    # <emphasis role="bold">cp -p modload/libafs64.o /kernel/fs/amd64/afs</emphasis>
696 </programlisting>
697
698               <para>If the machine is running Solaris 2.6 or the 32-bit version of Solaris 7, its kernel supports NFS server
699               functionality, and the <emphasis role="bold">nfsd</emphasis> process is running:</para>
700
701               <programlisting>
702    # <emphasis role="bold">cp -p modload/libafs.o /kernel/fs/afs</emphasis>   
703 </programlisting>
704
705               <para>If the machine is running Solaris 2.6 or the 32-bit version of Solaris 7, and its kernel does not support NFS
706               server functionality or the <emphasis role="bold">nfsd</emphasis> process is not running:</para>
707
708               <programlisting>
709    # <emphasis role="bold">cp -p modload/libafs.nonfs.o /kernel/fs/afs</emphasis>   
710 </programlisting>
711
712               <para>If the machine is running the 64-bit version of Solaris 7, its kernel supports NFS server functionality, and the
713               <emphasis role="bold">nfsd</emphasis> process is running:</para>
714
715               <programlisting>
716    # <emphasis role="bold">cp -p modload/libafs64.o /kernel/fs/sparcv9/afs</emphasis>   
717 </programlisting>
718
719               <para>If the machine is running the 64-bit version of Solaris 7, and its kernel does not support NFS server
720               functionality or the <emphasis role="bold">nfsd</emphasis> process is not running:</para>
721
722               <programlisting>
723    # <emphasis role="bold">cp -p modload/libafs64.nonfs.o /kernel/fs/sparcv9/afs</emphasis>
724 </programlisting>
725             </listitem>
726
727             <listitem>
728               <para>Run the AFS initialization script to load AFS modifications into the kernel. You can ignore any error messages
729               about the inability to start the BOS Server or the Cache Manager or AFS client. <programlisting>
730    # <emphasis role="bold">/etc/init.d/afs start</emphasis>   
731 </programlisting></para>
732
733               <para>When an entry called <computeroutput>afs</computeroutput> does not already exist in the local <emphasis
734               role="bold">/etc/name_to_sysnum</emphasis> file, the script automatically creates it and reboots the machine to start
735               using the new version of the file. If this happens, log in again as the superuser <emphasis
736               role="bold">root</emphasis> after the reboot and run the initialization script again. This time the required entry
737               exists in the <emphasis role="bold">/etc/name_to_sysnum</emphasis> file, and the <emphasis
738               role="bold">modload</emphasis> program runs.</para>
739
740               <programlisting>
741    login: <emphasis role="bold">root</emphasis>
742    Password: <replaceable>root_password</replaceable>
743    # <emphasis role="bold">/etc/init.d/afs start</emphasis>
744 </programlisting>
745
746               <indexterm>
747                 <primary>replacing fsck program</primary>
748
749                 <secondary>server machine after first</secondary>
750
751                 <tertiary>Solaris</tertiary>
752               </indexterm>
753
754               <indexterm>
755                 <primary>fsck program</primary>
756
757                 <secondary>on server machine after first</secondary>
758
759                 <tertiary>Solaris</tertiary>
760               </indexterm>
761
762               <indexterm>
763                 <primary>file server machine, additional</primary>
764
765                 <secondary>fsck program</secondary>
766
767                 <tertiary>on Solaris</tertiary>
768               </indexterm>
769
770               <indexterm>
771                 <primary>Solaris</primary>
772
773                 <secondary>fsck program</secondary>
774
775                 <tertiary>on add'l server machine</tertiary>
776               </indexterm>
777             </listitem>
778
779             <listitem>
780               <para>Create the <emphasis role="bold">/usr/lib/fs/afs</emphasis> directory to house the AFS-modified <emphasis
781               role="bold">fsck</emphasis> program and related files. <programlisting>
782    # <emphasis role="bold">mkdir /usr/lib/fs/afs</emphasis>
783    # <emphasis role="bold">cd /usr/lib/fs/afs</emphasis>  
784 </programlisting></para>
785             </listitem>
786
787             <listitem>
788               <para>Copy the <emphasis role="bold">vfsck</emphasis> binary to the newly created directory, changing the name as you
789               do so. <programlisting>
790    # <emphasis role="bold">cp  /cdrom/sun4x_56/dest/root.server/etc/vfsck  fsck</emphasis>
791 </programlisting></para>
792             </listitem>
793
794             <listitem>
795               <para>Working in the <emphasis role="bold">/usr/lib/fs/afs</emphasis> directory, create the following links to Solaris
796               libraries: <programlisting>
797    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/clri</emphasis>  
798    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/df</emphasis>
799    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/edquota</emphasis>
800    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/ff</emphasis>
801    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/fsdb</emphasis>  
802    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/fsirand</emphasis>
803    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/fstyp</emphasis>
804    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/labelit</emphasis>
805    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/lockfs</emphasis>
806    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/mkfs</emphasis>  
807    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/mount</emphasis>
808    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/ncheck</emphasis>
809    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/newfs</emphasis>
810    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/quot</emphasis>
811    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/quota</emphasis>
812    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/quotaoff</emphasis>
813    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/quotaon</emphasis>
814    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/repquota</emphasis>
815    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/tunefs</emphasis>
816    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/ufsdump</emphasis>
817    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/ufsrestore</emphasis>
818    # <emphasis role="bold">ln -s /usr/lib/fs/ufs/volcopy</emphasis>
819 </programlisting></para>
820             </listitem>
821
822             <listitem>
823               <para>Append the following line to the end of the file <emphasis role="bold">/etc/dfs/fstypes</emphasis>.
824               <programlisting>
825    afs AFS Utilities
826 </programlisting></para>
827             </listitem>
828
829             <listitem>
830               <para>Edit the <emphasis role="bold">/sbin/mountall</emphasis> file, making two changes. <itemizedlist>
831                   <listitem>
832                     <para>Add an entry for AFS to the <computeroutput>case</computeroutput> statement for option 2, so that it reads
833                     as follows: <programlisting>
834    case "$2" in
835    ufs)    foptions="-o p"
836            ;;
837    afs)    foptions="-o p"
838            ;;
839    s5)     foptions="-y -t /var/tmp/tmp$$ -D"
840            ;;
841    *)      foptions="-y"
842            ;;
843 </programlisting></para>
844                   </listitem>
845
846                   <listitem>
847                     <para>Edit the file so that all AFS and UFS partitions are checked in parallel. Replace the following section of
848                     code: <programlisting>
849    # For  fsck purposes, we make a distinction between ufs and
850    # other file systems
851    #
852    if [ "$fstype" = "ufs" ]; then
853         ufs_fscklist="$ufs_fscklist $fsckdev"
854         saveentry $fstype "$OPTIONS" $special $mountp
855         continue
856    fi  
857 </programlisting></para>
858
859                     <para>with the following section of code:</para>
860
861                     <programlisting>
862    # For fsck purposes, we make a distinction between ufs/afs
863    # and other file systems.
864    #
865    if [ "$fstype" = "ufs" -o "$fstype" = "afs" ]; then
866         ufs_fscklist="$ufs_fscklist $fsckdev"
867         saveentry $fstype "$OPTIONS" $special $mountp
868         continue
869    fi
870 </programlisting>
871                   </listitem>
872                 </itemizedlist></para>
873
874               <indexterm>
875                 <primary>configuring</primary>
876
877                 <secondary>AFS server partition on server machine after first</secondary>
878
879                 <tertiary>Solaris</tertiary>
880               </indexterm>
881
882               <indexterm>
883                 <primary>AFS server partition</primary>
884
885                 <secondary>configuring on server machine after first</secondary>
886
887                 <tertiary>Solaris</tertiary>
888               </indexterm>
889
890               <indexterm>
891                 <primary>file server machine, additional</primary>
892
893                 <secondary>AFS server partition</secondary>
894
895                 <tertiary>on Solaris</tertiary>
896               </indexterm>
897
898               <indexterm>
899                 <primary>Solaris</primary>
900
901                 <secondary>AFS server partition</secondary>
902
903                 <tertiary>on add'l server machine</tertiary>
904               </indexterm>
905             </listitem>
906
907             <listitem>
908               <para>Create a directory called <emphasis role="bold">/vicep</emphasis><replaceable>xx</replaceable> for each AFS
909               server partition you are configuring (there must be at least one). Repeat the command for each partition.
910               <programlisting>
911    # <emphasis role="bold">mkdir /vicep</emphasis><replaceable>xx</replaceable>
912 </programlisting></para>
913             </listitem>
914
915             <listitem>
916               <para>Add a line with the following format to the file systems registry file, <emphasis
917               role="bold">/etc/vfstab</emphasis>, for each partition to be mounted on a directory created in the previous step. Note
918               the value <computeroutput>afs</computeroutput> in the fourth field, which tells Solaris to use the AFS-modified
919               <emphasis role="bold">fsck</emphasis> program on this partition. <programlisting>
920    /dev/dsk/<replaceable>disk</replaceable>   /dev/rdsk/<replaceable>disk</replaceable>   /vicep<replaceable>xx</replaceable>   afs   <replaceable>boot_order</replaceable>  yes  
921 </programlisting></para>
922
923               <para>The following is an example for the first partition being configured.</para>
924
925               <programlisting>
926    /dev/dsk/c0t6d0s1 /dev/rdsk/c0t6d0s1 /vicepa afs 3 yes
927 </programlisting>
928             </listitem>
929
930             <listitem>
931               <para>Create a file system on each partition that is to be mounted at a <emphasis
932               role="bold">/vicep</emphasis><replaceable>xx</replaceable> directory. The following command is probably appropriate,
933               but consult the Solaris documentation for more information. <programlisting>
934    # <emphasis role="bold">newfs -v /dev/rdsk/</emphasis><replaceable>disk</replaceable>
935 </programlisting></para>
936             </listitem>
937
938             <listitem>
939               <para>Issue the <emphasis role="bold">mountall</emphasis> command to mount all partitions at once.</para>
940             </listitem>
941
942             <listitem>
943               <para>If the machine is to remain an AFS client, incorporate AFS into its authentication system, following the
944               instructions in <link linkend="HDRWQ49">Enabling AFS Login and Editing the File Systems Clean-up Script on Solaris
945               Systems</link>.</para>
946             </listitem>
947
948             <listitem>
949               <para>Proceed to <link linkend="HDRWQ108">Starting Server Programs</link>.</para>
950             </listitem>
951           </orderedlist></para>
952
953         <indexterm>
954           <primary>file server machine, additional</primary>
955
956           <secondary>server functionality</secondary>
957         </indexterm>
958
959         <indexterm>
960           <primary>installing</primary>
961
962           <secondary>server functionality</secondary>
963
964           <tertiary>server machine after first</tertiary>
965         </indexterm>
966       </sect3>
967     </sect2>
968
969     <sect2 id="HDRWQ108">
970       <title>Starting Server Programs</title>
971
972       <para>In this section you initialize the BOS Server, the Update Server, and the <emphasis
973       role="bold">fs</emphasis> process. You begin by copying the necessary server files to the local disk. <orderedlist>
974           <indexterm>
975             <primary>copying</primary>
976
977             <secondary>server files to local disk</secondary>
978
979             <tertiary>server machine after first</tertiary>
980           </indexterm>
981
982           <indexterm>
983             <primary>Binary Distribution</primary>
984
985             <secondary>copying server files from</secondary>
986
987             <tertiary>server machine after first</tertiary>
988           </indexterm>
989
990           <indexterm>
991             <primary>file server machine, additional</primary>
992
993             <secondary>copying</secondary>
994
995             <tertiary>server files to local disk</tertiary>
996           </indexterm>
997
998           <listitem>
999             <para>Copy file server binaries to the local <emphasis role="bold">/usr/afs/bin</emphasis> directory. <itemizedlist>
1000                 <listitem>
1001                   <para>On a machine of an existing system type, you can either 
1002                   copy files from the OpenAFS binary distribution or use a 
1003                   remote file transfer protocol to copy files from an existing 
1004                   server machine of the same system type. To load from the 
1005                   binary distribution, see the instructions just following for 
1006                   a machine of a new system type. If using a remote file 
1007                   transfer protocol, copy the complete contents of the 
1008                   existing server machine's 
1009                   <emphasis role="bold">/usr/afs/bin</emphasis>
1010                   directory.</para>
1011                 </listitem>
1012
1013                 <listitem>
1014                   <para>If you are working from a tarball distribtion, rather
1015                   than one distributed in a packaged format, you must use the 
1016                   following instructions to copy files from 
1017                   the OpenAFS Binary Distribution.
1018                    <orderedlist>
1019                       <listitem>
1020                         <para>Unpack the distribution tarball. The examples 
1021                         below assume that you have unpacked the files into the 
1022                         <emphasis role="bold">/tmp/afsdist</emphasis> 
1023                         directory. If you pick a different location, substitute
1024                         this in all of the following examples.</para>
1025                       </listitem>
1026
1027                       <listitem>
1028                         <para>Copy files from the distribution to the local <emphasis role="bold">/usr/afs</emphasis> directory.
1029                         <programlisting>
1030    # <emphasis role="bold">cd /tmp/afsdist/</emphasis><replaceable>sysname</replaceable><emphasis role="bold">/root.server/usr/afs</emphasis>
1031    # <emphasis role="bold">cp -rp  *  /usr/afs</emphasis>
1032 </programlisting></para>
1033                       </listitem>
1034                     </orderedlist></para>
1035                 </listitem>
1036               </itemizedlist></para>
1037
1038             <indexterm>
1039               <primary>usr/afs/etc directory</primary>
1040
1041               <secondary>server machine after first</secondary>
1042             </indexterm>
1043
1044             <indexterm>
1045               <primary>file server machine, additional</primary>
1046
1047               <secondary>/usr/afs/etc directory</secondary>
1048             </indexterm>
1049
1050             <indexterm>
1051               <primary>creating</primary>
1052
1053               <secondary>/usr/afs/etc directory</secondary>
1054
1055               <tertiary>server machine after first</tertiary>
1056             </indexterm>
1057
1058             <indexterm>
1059               <primary>creating</primary>
1060
1061               <secondary>CellServDB file (server)</secondary>
1062
1063               <tertiary>server machine after first</tertiary>
1064             </indexterm>
1065
1066             <indexterm>
1067               <primary>UserList file</primary>
1068
1069               <secondary>server machine after first</secondary>
1070             </indexterm>
1071
1072             <indexterm>
1073               <primary>KeyFile file</primary>
1074
1075               <secondary>server machine after first</secondary>
1076             </indexterm>
1077
1078             <indexterm>
1079               <primary>CellServDB file (server)</primary>
1080
1081               <secondary>creating</secondary>
1082
1083               <tertiary>on server machine after first</tertiary>
1084             </indexterm>
1085
1086             <indexterm>
1087               <primary>database server machine</primary>
1088
1089               <secondary>entry in server CellServDB file</secondary>
1090
1091               <tertiary>on server machine after first</tertiary>
1092             </indexterm>
1093
1094             <indexterm>
1095               <primary>ThisCell file (server)</primary>
1096
1097               <secondary>server machine after first</secondary>
1098             </indexterm>
1099
1100             <indexterm>
1101               <primary>file server machine, additional</primary>
1102
1103               <secondary>cell membership, defining</secondary>
1104
1105               <tertiary>for server processes</tertiary>
1106             </indexterm>
1107
1108             <indexterm>
1109               <primary>setting</primary>
1110
1111               <secondary>cell name in server ThisCell file</secondary>
1112
1113               <tertiary>server machine after first</tertiary>
1114             </indexterm>
1115
1116             <indexterm>
1117               <primary>file server machine, additional</primary>
1118
1119               <secondary>ThisCell file (server)</secondary>
1120             </indexterm>
1121           </listitem>
1122
1123           <listitem>
1124             <para>Copy the contents of the 
1125             <emphasis role="bold">/usr/afs/etc</emphasis> directory from an 
1126             existing file server machine, using a remote file transfer protocol 
1127             such as <emphasis role="bold">sftp</emphasis> or 
1128             <emphasis role="bold">scp</emphasis>. If you use a system
1129             control machine, it is best to copy the contents of its 
1130             <emphasis role="bold">/usr/afs/etc</emphasis> directory. If you
1131             choose not to run a system control machine, copy the directory's 
1132             contents from any existing file server machine.
1133             <indexterm>
1134                 <primary>BOS Server</primary>
1135
1136                 <secondary>starting</secondary>
1137
1138                 <tertiary>server machine after first</tertiary>
1139               </indexterm> <indexterm>
1140                 <primary>starting</primary>
1141
1142                 <secondary>BOS Server</secondary>
1143
1144                 <tertiary>server machine after first</tertiary>
1145               </indexterm> <indexterm>
1146                 <primary>file server machine, additional</primary>
1147
1148                 <secondary>BOS Server</secondary>
1149               </indexterm> <indexterm>
1150                 <primary>authorization checking (disabling)</primary>
1151
1152                 <secondary>server machine after first</secondary>
1153               </indexterm> <indexterm>
1154                 <primary>disabling authorization checking</primary>
1155
1156                 <secondary>server machine after first</secondary>
1157               </indexterm> <indexterm>
1158                 <primary>file server machine, additional</primary>
1159
1160                 <secondary>authorization checking (disabling)</secondary>
1161               </indexterm></para>
1162           </listitem>
1163
1164           <listitem>
1165             <para>Change to the <emphasis role="bold">/usr/afs/bin</emphasis> directory and start the BOS Server (<emphasis
1166             role="bold">bosserver</emphasis> process). Include the <emphasis role="bold">-noauth</emphasis> flag to prevent the AFS
1167             processes from performing authorization checking. This is a grave compromise of security; finish the remaining
1168             instructions in this section in an uninterrupted pass. <programlisting>
1169    # <emphasis role="bold">cd /usr/afs/bin</emphasis>
1170    # <emphasis role="bold">./bosserver -noauth &amp;</emphasis>
1171 </programlisting> <indexterm>
1172                 <primary>BosConfig file</primary>
1173
1174                 <secondary>adding entries</secondary>
1175
1176                 <tertiary>server machine after first</tertiary>
1177               </indexterm> <indexterm>
1178                 <primary>adding</primary>
1179
1180                 <secondary>entries to BosConfig file</secondary>
1181
1182                 <tertiary>server machine after first</tertiary>
1183               </indexterm> <indexterm>
1184                 <primary>Update Server</primary>
1185
1186                 <secondary>starting client portion</secondary>
1187               </indexterm> <indexterm>
1188                 <primary>upclient process</primary>
1189               </indexterm> <indexterm>
1190                 <primary>starting</primary>
1191
1192                 <secondary>Update Server client portion</secondary>
1193               </indexterm> <indexterm>
1194                 <primary>file server machine, additional</primary>
1195
1196                 <secondary>Update Server client portion</secondary>
1197               </indexterm></para>
1198           </listitem>
1199
1200           <listitem id="LIWQ109">
1201             <para>If you run a system control machine, create the <emphasis
1202             role="bold">upclientetc</emphasis> process as an instance of the client portion of the Update Server. It accepts updates
1203             of the common configuration files stored in the system control machine's <emphasis role="bold">/usr/afs/etc</emphasis>
1204             directory from the <emphasis role="bold">upserver</emphasis> process (server portion of the Update Server) running on
1205             that machine. The cell's first file server machine was installed as the system control machine in <link
1206             linkend="HDRWQ61">Starting the Server Portion of the Update Server</link>. (If you do not run a system control machine,
1207             you must update the contents of the <emphasis role="bold">/usr/afs/etc</emphasis> directory on each file server machine,
1208             using the appropriate <emphasis role="bold">bos</emphasis> commands.)</para>
1209
1210             <para>By default, the Update Server performs updates every 300 seconds (five minutes). Use the <emphasis
1211             role="bold">-t</emphasis> argument to specify a different number of seconds. For the
1212             <replaceable>machine&nbsp;name</replaceable> argument, substitute the name of the machine you are installing. The
1213             command appears on multiple lines here only for legibility reasons.</para>
1214
1215             <programlisting>
1216    # <emphasis role="bold">./bos create</emphasis>  &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">upclientetc simple</emphasis>  \ 
1217          <emphasis role="bold">"/usr/afs/bin/upclient</emphasis>  &lt;<replaceable>system control machine</replaceable>&gt;  \  
1218          [<emphasis role="bold">-t</emphasis>  &lt;<replaceable>time</replaceable>&gt;]  <emphasis role="bold">/usr/afs/etc" -cell</emphasis>  &lt;<replaceable>cell name</replaceable>&gt;  <emphasis
1219                 role="bold">-noauth</emphasis>
1220 </programlisting>
1221
1222             <indexterm>
1223               <primary>Update Server</primary>
1224
1225               <secondary>starting server portion</secondary>
1226
1227               <tertiary>server machine after first</tertiary>
1228             </indexterm>
1229
1230             <indexterm>
1231               <primary>starting</primary>
1232
1233               <secondary>Update Server server portion</secondary>
1234
1235               <tertiary>server machine after first</tertiary>
1236             </indexterm>
1237
1238             <indexterm>
1239               <primary>file server machine, additional</primary>
1240
1241               <secondary>Update Server server portion</secondary>
1242             </indexterm>
1243           </listitem>
1244
1245           <listitem id="LIWQ110">
1246             <para>Create an instance of the Update 
1247             Server to handle distribution of the file server binaries
1248             stored in the <emphasis role="bold">/usr/afs/bin</emphasis> 
1249             directory. If your architecture using a package management system
1250             such as 'rpm' or 'apt' to maintain its binaries, note that
1251             distributing binaries via this system may interfere with your local
1252             package management tools.
1253             </para>
1254             
1255             <itemizedlist>
1256                 <listitem>
1257                   <para>If this is the first file server machine of its AFS system type, create the <emphasis
1258                   role="bold">upserver</emphasis> process as an instance of the server portion of the Update Server. It distributes
1259                   its copy of the file server process binaries to the other file server machines of this system type that you
1260                   install in future. Creating this process makes this machine the binary distribution machine for its type.
1261                   <programlisting>
1262    # <emphasis role="bold">./bos create</emphasis>  &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">upserver  simple</emphasis>  \ 
1263          <emphasis role="bold">"/usr/afs/bin/upserver -clear /usr/afs/bin"</emphasis>   \
1264          <emphasis role="bold">-cell</emphasis> &lt;<replaceable>cell name</replaceable>&gt;  <emphasis role="bold">-noauth</emphasis>
1265 </programlisting></para>
1266                 </listitem>
1267
1268                 <listitem>
1269                   <para>If this machine is an existing system type, create the <emphasis role="bold">upclientbin</emphasis> process
1270                   as an instance of the client portion of the Update Server. It accepts updates of the AFS binaries from the
1271                   <emphasis role="bold">upserver</emphasis> process running on the binary distribution machine for its system type.
1272                   For distribution to work properly, the <emphasis role="bold">upserver</emphasis> process must already by running
1273                   on that machine.</para>
1274
1275                   <para>Use the <emphasis role="bold">-clear</emphasis> argument to specify that the <emphasis
1276                   role="bold">upclientbin</emphasis> process requests unencrypted transfer of the binaries in the <emphasis
1277                   role="bold">/usr/afs/bin</emphasis> directory. Binaries are not sensitive and encrypting them is
1278                   time-consuming.</para>
1279
1280                   <para>By default, the Update Server performs updates every 300 seconds (five minutes). Use the <emphasis
1281                   role="bold">-t</emphasis> argument to specify an different number of seconds.</para>
1282
1283 <programlisting>
1284    # <emphasis role="bold">./bos create</emphasis>  &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">upclientbin simple</emphasis>  \ 
1285         <emphasis role="bold">"/usr/afs/bin/upclient</emphasis> &lt;<replaceable>binary distribution machine</replaceable>&gt;   \
1286         [<emphasis role="bold">-t</emphasis> &lt;<replaceable>time</replaceable>&gt;] <emphasis role="bold">-clear /usr/afs/bin" -cell</emphasis> &lt;<replaceable>cell name</replaceable>&gt;  <emphasis
1287                       role="bold">-noauth</emphasis>
1288 </programlisting>
1289                 </listitem>
1290               </itemizedlist>
1291
1292             <indexterm>
1293               <primary>File Server</primary>
1294
1295               <secondary>server machine after first</secondary>
1296             </indexterm>
1297
1298             <indexterm>
1299               <primary>starting</primary>
1300
1301               <secondary>File Server</secondary>
1302
1303               <tertiary>server machine after first</tertiary>
1304             </indexterm>
1305
1306             <indexterm>
1307               <primary>file server machine, additional</primary>
1308
1309               <secondary>File Server</secondary>
1310             </indexterm>
1311
1312             <indexterm>
1313               <primary>Volume Server</primary>
1314
1315               <secondary>server machine after first</secondary>
1316             </indexterm>
1317
1318             <indexterm>
1319               <primary>starting</primary>
1320
1321               <secondary>Volume Server</secondary>
1322
1323               <tertiary>server machine after first</tertiary>
1324             </indexterm>
1325
1326             <indexterm>
1327               <primary>file server machine, additional</primary>
1328
1329               <secondary>Volume Server</secondary>
1330             </indexterm>
1331
1332             <indexterm>
1333               <primary>Salvager (salvager process)</primary>
1334
1335               <secondary>server machine after first</secondary>
1336             </indexterm>
1337
1338             <indexterm>
1339               <primary>fs process</primary>
1340
1341               <secondary>server machine after first</secondary>
1342             </indexterm>
1343
1344             <indexterm>
1345               <primary>starting</primary>
1346
1347               <secondary>fs process</secondary>
1348
1349               <tertiary>server machine after first</tertiary>
1350             </indexterm>
1351
1352             <indexterm>
1353               <primary>file server machine, additional</primary>
1354
1355               <secondary>fs process</secondary>
1356             </indexterm>
1357           </listitem>
1358
1359           <listitem>
1360             <para>Issue the <emphasis role="bold">bos create</emphasis> command
1361             to start the <emphasis role="bold">fs</emphasis> process or the
1362             <emphasis role="bold">dafs</emphasis> process, depending on if you
1363             want to run the Demand-Attach File Server or not. See <link
1364             linkend="DAFS">Appendix C, The Demand-Attach File Server</link> for
1365             more information on whether you want to run it or not.
1366
1367             <itemizedlist>
1368               <listitem>
1369
1370             <para>If you do not want to run the Demand-Attach File Server, start the <emphasis role="bold">fs</emphasis> process, which binds together the File Server, Volume Server, and
1371             Salvager. <programlisting>
1372    # <emphasis role="bold">./bos create</emphasis>  &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">fs fs</emphasis>   \ 
1373          <emphasis role="bold">/usr/afs/bin/fileserver /usr/afs/bin/volserver</emphasis>  \ 
1374          <emphasis role="bold">/usr/afs/bin/salvager -cell</emphasis> &lt;<replaceable>cell name</replaceable>&gt;  <emphasis
1375                   role="bold">-noauth</emphasis>
1376 </programlisting></para>
1377           </listitem>
1378
1379           <listitem>
1380
1381             <para>If you want to run the Demand-Attach File Server, start the
1382             <emphasis role="bold">dafs</emphasis> process, which binds together
1383             the File Server, Volume Server, Salvage Server, and Salvager.
1384             <programlisting>
1385    # <emphasis role="bold">./bos create</emphasis>  &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">dafs dafs</emphasis>   \ 
1386          <emphasis role="bold">/usr/afs/bin/dafileserver /usr/afs/bin/davolserver</emphasis>  \ 
1387          <emphasis role="bold">/usr/afs/bin/salvageserver</emphasis>  \ 
1388          <emphasis role="bold">/usr/afs/bin/dasalvager -cell</emphasis> &lt;<replaceable>cell name</replaceable>&gt;  <emphasis
1389                   role="bold">-noauth</emphasis>
1390 </programlisting></para>
1391           </listitem>
1392
1393           </itemizedlist>
1394
1395           </para>
1396           </listitem>
1397         </orderedlist></para>
1398
1399       <indexterm>
1400         <primary>installing</primary>
1401
1402         <secondary>client functionality</secondary>
1403
1404         <tertiary>server machine after first</tertiary>
1405       </indexterm>
1406
1407       <indexterm>
1408         <primary>file server machine, additional</primary>
1409
1410         <secondary>client functionality</secondary>
1411       </indexterm>
1412     </sect2>
1413
1414     <sect2 id="HDRWQ111">
1415       <title>Installing Client Functionality</title>
1416
1417       <para>If you want this machine to be a client as well as a server, follow the instructions in this section. Otherwise, skip to
1418       <link linkend="HDRWQ112">Completing the Installation</link>.</para>
1419
1420       <para>Begin by loading the necessary client files to the local disk. Then create the necessary configuration files and start
1421       the Cache Manager. For more detailed explanation of the procedures involved, see the corresponding instructions in <link
1422       linkend="HDRWQ17">Installing the First AFS Machine</link> (in the sections following <link linkend="HDRWQ63">Overview:
1423       Installing Client Functionality</link>).</para>
1424
1425       <para>If another AFS machine of this machine's system type exists, the AFS binaries are probably already accessible in your
1426       AFS filespace (the conventional location is <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1427       role="bold">/</emphasis><replaceable>sysname</replaceable><emphasis role="bold">/usr/afsws</emphasis>). If not, or if this is
1428       the first AFS machine of its type, copy the AFS binaries for this system type into an AFS volume by following the instructions
1429       in <link linkend="HDRWQ83">Storing AFS Binaries in AFS</link>. Because this machine is not yet an AFS client, you must perform
1430       the procedure on an existing AFS machine. However, remember to perform the final step (linking the local directory <emphasis
1431       role="bold">/usr/afsws</emphasis> to the appropriate location in the AFS file tree) on this machine itself. If you also want
1432       to create AFS volumes to house UNIX system binaries for the new system type, see <link linkend="HDRWQ88">Storing System
1433       Binaries in AFS</link>. <indexterm>
1434           <primary>Binary Distribution</primary>
1435
1436           <secondary>copying client files from</secondary>
1437
1438           <tertiary>server machine after first</tertiary>
1439         </indexterm> <indexterm>
1440           <primary>file server machine, additional</primary>
1441
1442           <secondary>copying</secondary>
1443
1444           <tertiary>client files to local disk</tertiary>
1445         </indexterm> <indexterm>
1446           <primary>copying</primary>
1447
1448           <secondary>client files to local disk</secondary>
1449
1450           <tertiary>server machine after first</tertiary>
1451         </indexterm> <orderedlist>
1452           <listitem>
1453             <para>Copy client binaries and files to the local disk. <itemizedlist>
1454                 <listitem>
1455                   <para>On a machine of an existing system type, you can either 
1456                   load files from the OpenAFS Binary Distribution or use a 
1457                   remote file transfer protocol to copy files from an existing 
1458                   server machine of the same system type. To load from the
1459                   binary distribution, see the instructions just following 
1460                   for a machine of a new system type. If using a remote file 
1461                   transfer protocol, copy the complete contents of the existing 
1462                   client machine's 
1463                   <emphasis role="bold">/usr/vice/etc</emphasis> 
1464                   directory.</para>
1465                 </listitem>
1466
1467                 <listitem>
1468                   <para>On a machine of a new system type, you must use the 
1469                   following instructions to copy files from the OpenAFS
1470                   Binary Distribution. If your distribution is provided in
1471                   a packaged format, then simply installing the packages will
1472                   perform the necessary actions.
1473                     <orderedlist>
1474                       <listitem>
1475                         <para>Unpack the distribution tarball. The examples 
1476                         below assume that you have unpacked the files into the 
1477                         <emphasis role="bold">/tmp/afsdist</emphasis> 
1478                         directory. If you pick a different location, substitute
1479                         this in all of the following examples.</para>
1480                       </listitem>
1481
1482                       <listitem>
1483                         <para>Copy files to the local <emphasis role="bold">/usr/vice/etc</emphasis> directory.</para>
1484
1485                         <para>This step places a copy of the AFS initialization script (and related files, if applicable) into the
1486                         <emphasis role="bold">/usr/vice/etc</emphasis> directory. In the preceding instructions for incorporating
1487                         AFS into the kernel, you copied the script directly to the operating system's conventional location for
1488                         initialization files. When you incorporate AFS into the machine's startup sequence in a later step, you can
1489                         choose to link the two files.</para>
1490
1491                         <para>On some system types that use a dynamic kernel loader program, you previously copied AFS library files
1492                         into a subdirectory of the <emphasis role="bold">/usr/vice/etc</emphasis> directory. On other system types,
1493                         you copied the appropriate AFS library file directly to the directory where the operating system accesses
1494                         it. The following commands do not copy or recopy the AFS library files into the <emphasis
1495                         role="bold">/usr/vice/etc</emphasis> directory, because on some system types the library files consume a
1496                         large amount of space. If you want to copy them, add the <emphasis role="bold">-r</emphasis> flag to the
1497                         first <emphasis role="bold">cp</emphasis> command and skip the second <emphasis role="bold">cp</emphasis>
1498                         command.</para>
1499
1500                         <programlisting>
1501    # <emphasis role="bold">cd /tmp/afsdist/</emphasis><replaceable>sysname</replaceable><emphasis role="bold">/root.client/usr/vice/etc</emphasis>
1502    # <emphasis role="bold">cp -p  *  /usr/vice/etc</emphasis>
1503    # <emphasis role="bold">cp -rp  C  /usr/vice/etc</emphasis>
1504 </programlisting>
1505                       </listitem>
1506                     </orderedlist></para>
1507                 </listitem>
1508               </itemizedlist></para>
1509
1510             <indexterm>
1511               <primary>cell name</primary>
1512
1513               <secondary>setting in client ThisCell file</secondary>
1514
1515               <tertiary>server machine after first</tertiary>
1516             </indexterm>
1517
1518             <indexterm>
1519               <primary>cell name</primary>
1520
1521               <secondary>setting in server ThisCell file</secondary>
1522
1523               <tertiary>server machine after first</tertiary>
1524             </indexterm>
1525
1526             <indexterm>
1527               <primary>setting</primary>
1528
1529               <secondary>cell name in client ThisCell file</secondary>
1530
1531               <tertiary>server machine after first</tertiary>
1532             </indexterm>
1533
1534             <indexterm>
1535               <primary>file server machine, additional</primary>
1536
1537               <secondary>ThisCell file (client)</secondary>
1538             </indexterm>
1539
1540             <indexterm>
1541               <primary>file server machine, additional</primary>
1542
1543               <secondary>cell membership, defining</secondary>
1544
1545               <tertiary>for client processes</tertiary>
1546             </indexterm>
1547
1548             <indexterm>
1549               <primary>ThisCell file (client)</primary>
1550
1551               <secondary>server machine after first</secondary>
1552             </indexterm>
1553           </listitem>
1554
1555           <listitem>
1556             <para>Change to the <emphasis role="bold">/usr/vice/etc</emphasis> directory and create the <emphasis
1557             role="bold">ThisCell</emphasis> file as a copy of the <emphasis role="bold">/usr/afs/etc/ThisCell</emphasis> file. You
1558             must first remove the symbolic link to the <emphasis role="bold">/usr/afs/etc/ThisCell</emphasis> file that the BOS
1559             Server created automatically in <link linkend="HDRWQ108">Starting Server Programs</link>. <programlisting>
1560    # <emphasis role="bold">cd  /usr/vice/etc</emphasis>
1561    # <emphasis role="bold">rm  ThisCell</emphasis>
1562    # <emphasis role="bold">cp  /usr/afs/etc/ThisCell  ThisCell</emphasis>
1563 </programlisting></para>
1564           </listitem>
1565
1566           <listitem>
1567             <para>Remove the symbolic link to the <emphasis role="bold">/usr/afs/etc/CellServDB</emphasis> file. <programlisting>
1568    # <emphasis role="bold">rm  CellServDB</emphasis>
1569 </programlisting> <indexterm>
1570                 <primary>database server machine</primary>
1571
1572                 <secondary>entry in client CellServDB file</secondary>
1573
1574                 <tertiary>on server machine after first</tertiary>
1575               </indexterm> <indexterm>
1576                 <primary>CellServDB file (client)</primary>
1577
1578                 <secondary>creating</secondary>
1579
1580                 <tertiary>on server machine after first</tertiary>
1581               </indexterm> <indexterm>
1582                 <primary>creating</primary>
1583
1584                 <secondary>CellServDB file (client)</secondary>
1585
1586                 <tertiary>server machine after first</tertiary>
1587               </indexterm></para>
1588           </listitem>
1589
1590           <listitem>
1591             <para>Create the 
1592             <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file. 
1593             Use a network file transfer program such as 
1594             <emphasis role="bold">sftp</emphasis> or 
1595             <emphasis role="bold">scp</emphasis> to copy it from 
1596             one of the following sources, which are listed in
1597             decreasing order of preference: 
1598               <itemizedlist>
1599                 <listitem>
1600                   <para>Your cell's central <emphasis role="bold">CellServDB</emphasis> source file (the conventional location is
1601                   <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1602                   role="bold">/common/etc/CellServDB</emphasis>)</para>
1603                 </listitem>
1604
1605                 <listitem>
1606                   <para>The global <emphasis role="bold">CellServDB</emphasis> 
1607                   file maintained at grand.central.org</para>
1608                 </listitem>
1609
1610                 <listitem>
1611                   <para>An existing client machine in your cell</para>
1612                 </listitem>
1613
1614                 <listitem>
1615                   <para>The <emphasis role="bold">CellServDB.sample</emphasis> 
1616                   file included in the 
1617                   <replaceable>sysname</replaceable><emphasis role="bold">/root.client/usr/vice/etc</emphasis> 
1618                   directory of each OpenAFS distribution; add an entry for the 
1619                   local cell by following the instructions in 
1620                   <link linkend="HDRWQ66">Creating the Client CellServDB File</link>
1621                   </para>
1622                 </listitem>
1623               </itemizedlist>
1624             </para>
1625
1626             <indexterm>
1627               <primary>cache</primary>
1628
1629               <secondary>configuring</secondary>
1630
1631               <tertiary>server machine after first</tertiary>
1632             </indexterm>
1633
1634             <indexterm>
1635               <primary>configuring</primary>
1636
1637               <secondary>cache</secondary>
1638
1639               <tertiary>server machine after first</tertiary>
1640             </indexterm>
1641
1642             <indexterm>
1643               <primary>setting</primary>
1644
1645               <secondary>cache size and location</secondary>
1646
1647               <tertiary>server machine after first</tertiary>
1648             </indexterm>
1649
1650             <indexterm>
1651               <primary>file server machine, additional</primary>
1652
1653               <secondary>cache size and location</secondary>
1654             </indexterm>
1655           </listitem>
1656
1657           <listitem>
1658             <para>Create the <emphasis role="bold">cacheinfo</emphasis> file for either a disk cache or a memory cache. For a
1659             discussion of the appropriate values to record in the file, see <link linkend="HDRWQ67">Configuring the
1660             Cache</link>.</para>
1661
1662             <para>To configure a disk cache, issue the following commands. If you are devoting a partition exclusively to caching,
1663             as recommended, you must also configure it, make a file system on it, and mount it at the directory created in this
1664             step.</para>
1665
1666             <programlisting>
1667    # <emphasis role="bold">mkdir /usr/vice/cache</emphasis>
1668    # <emphasis role="bold">echo "/afs:/usr/vice/cache:</emphasis><replaceable>#blocks</replaceable><emphasis role="bold">" &gt; cacheinfo</emphasis>   
1669 </programlisting>
1670
1671             <para>To configure a memory cache:</para>
1672
1673             <programlisting>
1674    # <emphasis role="bold">echo "/afs:/usr/vice/cache:</emphasis><replaceable>#blocks</replaceable><emphasis role="bold">" &gt; cacheinfo</emphasis>
1675 </programlisting>
1676
1677             <indexterm>
1678               <primary>Cache Manager</primary>
1679
1680               <secondary>server machine after first</secondary>
1681             </indexterm>
1682
1683             <indexterm>
1684               <primary>configuring</primary>
1685
1686               <secondary>Cache Manager</secondary>
1687
1688               <tertiary>server machine after first</tertiary>
1689             </indexterm>
1690
1691             <indexterm>
1692               <primary>file server machine, additional</primary>
1693
1694               <secondary>Cache Manager</secondary>
1695             </indexterm>
1696
1697             <indexterm>
1698               <primary>afs (/afs) directory</primary>
1699
1700               <secondary>creating</secondary>
1701
1702               <tertiary>server machine after first</tertiary>
1703             </indexterm>
1704
1705             <indexterm>
1706               <primary>AFS initialization script</primary>
1707
1708               <secondary>setting afsd parameters</secondary>
1709
1710               <tertiary>server machine after first</tertiary>
1711             </indexterm>
1712
1713             <indexterm>
1714               <primary>file server machine, additional</primary>
1715
1716               <secondary>afsd command parameters</secondary>
1717             </indexterm>
1718           </listitem>
1719
1720           <listitem>
1721             <para>Create the local directory on which to mount the AFS filespace, by convention <emphasis
1722             role="bold">/afs</emphasis>. If the directory already exists, verify that it is empty. <programlisting>
1723    # <emphasis role="bold">mkdir /afs</emphasis>
1724 </programlisting></para>
1725           </listitem>
1726
1727           <listitem>
1728             <para>On AIX systems, add the following line to the <emphasis role="bold">/etc/vfs</emphasis> file. It enables AIX to
1729             unmount AFS correctly during shutdown. <programlisting>
1730    afs     4     none     none
1731 </programlisting></para>
1732           </listitem>
1733
1734           <listitem>
1735             <para>On non-packaged Linux systems, copy the <emphasis role="bold">afsd</emphasis> options file from the <emphasis
1736             role="bold">/usr/vice/etc</emphasis> directory to the <emphasis role="bold">/etc/sysconfig</emphasis> directory,
1737             removing the <emphasis role="bold">.conf</emphasis> extension as you do so. <programlisting>
1738    # <emphasis role="bold">cp /usr/vice/etc/afs.conf /etc/sysconfig/afs</emphasis>
1739 </programlisting></para>
1740           </listitem>
1741
1742           <listitem>
1743             <para>Edit the machine's AFS initialization script or <emphasis role="bold">afsd</emphasis> options file to set
1744             appropriate values for <emphasis role="bold">afsd</emphasis> command parameters. The script resides in the indicated
1745             location on each system type: <itemizedlist>
1746                 <listitem>
1747                   <para>On AIX systems, <emphasis role="bold">/etc/rc.afs</emphasis></para>
1748                 </listitem>
1749
1750                 <listitem>
1751                   <para>On Fedora and RHEL systems, 
1752                   <emphasis role="bold">/etc/sysconfig/openafs</emphasis>. 
1753                   Note that this file has a different format from a standard 
1754                   afsd options file.</para>
1755                 </listitem>
1756                 
1757                 <listitem>
1758                   <para>On non-packaged Linux systems, <emphasis role="bold">/etc/sysconfig/afs</emphasis> (the <emphasis
1759                   role="bold">afsd</emphasis> options file)</para>
1760                 </listitem>
1761                 
1762
1763                 <listitem>
1764                   <para>On Solaris systems, <emphasis role="bold">/etc/init.d/afs</emphasis></para>
1765                 </listitem>
1766               </itemizedlist></para>
1767
1768             <para>Use one of the methods described in <link linkend="HDRWQ70">Configuring the Cache Manager</link> to add the
1769             following flags to the <emphasis role="bold">afsd</emphasis> command line. If you intend for the machine to remain an
1770             AFS client, also set any performance-related arguments you wish. <itemizedlist>
1771                 <!-- nosetime is now the default
1772                 <listitem>
1773                   <para>Add the <emphasis role="bold">-nosettime</emphasis> flag, because this is a file server machine that is also
1774                   a client.</para>
1775                 </listitem> -->
1776
1777                 <listitem>
1778                   <para>Add the <emphasis role="bold">-memcache</emphasis> flag if the machine is to use a memory cache.</para>
1779                 </listitem>
1780
1781                 <listitem>
1782                   <para>Add the <emphasis role="bold">-verbose</emphasis> flag to display a trace of the Cache Manager's
1783                   initialization on the standard output stream.</para>
1784                 </listitem>
1785                 <listitem>
1786                   <para>Add the <emphasis role="bold">--dynroot</emphasis> or
1787                   <emphasis role="bold">--afsdb</emphasis> options if you
1788                   wish to have a synthetic AFS root, as discussed in
1789                   <link linkend="HDRWQ91">Enabling Access to Foreign Cells</link>
1790                   </para>
1791                 </listitem>
1792               </itemizedlist></para>
1793           </listitem>
1794
1795           <listitem>
1796             <para>If appropriate, follow the instructions in <link linkend="HDRWQ83">Storing AFS Binaries in AFS</link> to copy the
1797             AFS binaries for this system type into an AFS volume. See the introduction to this section for further
1798             discussion.</para>
1799           </listitem>
1800         </orderedlist></para>
1801     </sect2>
1802
1803     <sect2 id="HDRWQ112">
1804       <title>Completing the Installation</title>
1805
1806       <para>At this point you run the machine's AFS initialization script to verify that it correctly loads AFS modifications into
1807       the kernel and starts the BOS Server, which starts the other server processes. If you have installed client files, the script
1808       also starts the Cache Manager. If the script works correctly, perform the steps that incorporate it into the machine's startup
1809       and shutdown sequence. If there are problems during the initialization, attempt to resolve them. The AFS Product Support group
1810       can provide assistance if necessary.</para>
1811
1812       <para>If the machine is configured as a client using a disk cache, it can take a while for the <emphasis
1813       role="bold">afsd</emphasis> program to create all of the <emphasis role="bold">V</emphasis><replaceable>n</replaceable> files
1814       in the cache directory. Messages on the console trace the initialization process. <orderedlist>
1815           <listitem>
1816             <para>Issue the <emphasis role="bold">bos shutdown</emphasis> command to shut down the AFS server processes other than
1817             the BOS Server. Include the <emphasis role="bold">-wait</emphasis> flag to delay return of the command shell prompt
1818             until all processes shut down completely. <programlisting>
1819    # <emphasis role="bold">/usr/afs/bin/bos shutdown</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis
1820                   role="bold">-wait</emphasis>
1821 </programlisting></para>
1822           </listitem>
1823
1824           <listitem>
1825             <para>Issue the <emphasis role="bold">ps</emphasis> command to learn the BOS Server's process ID number (PID), and then
1826             the <emphasis role="bold">kill</emphasis> command to stop the <emphasis role="bold">bosserver</emphasis> process.
1827             <programlisting>
1828    # <emphasis role="bold">ps</emphasis> <replaceable>appropriate_ps_options</replaceable> <emphasis role="bold">| grep bosserver</emphasis>
1829    # <emphasis role="bold">kill</emphasis> <replaceable>bosserver_PID</replaceable>
1830 </programlisting> <indexterm>
1831                 <primary>AFS initialization script</primary>
1832
1833                 <secondary>adding to machine startup sequence</secondary>
1834
1835                 <tertiary>server machine after first</tertiary>
1836               </indexterm> <indexterm>
1837                 <primary>AFS initialization script</primary>
1838
1839                 <secondary>running</secondary>
1840
1841                 <tertiary>server machine after first</tertiary>
1842               </indexterm> <indexterm>
1843                 <primary>file server machine, additional</primary>
1844
1845                 <secondary>AFS initialization script</secondary>
1846               </indexterm> <indexterm>
1847                 <primary>running AFS init. script</primary>
1848
1849                 <secondary>server machine after first</secondary>
1850               </indexterm> <indexterm>
1851                 <primary>installing</primary>
1852
1853                 <secondary>AFS initialization script</secondary>
1854
1855                 <tertiary>server machine after first</tertiary>
1856               </indexterm> <indexterm>
1857                 <primary>AIX</primary>
1858
1859                 <secondary>AFS initialization script</secondary>
1860
1861                 <tertiary>on add'l server machine</tertiary>
1862               </indexterm></para>
1863           </listitem>
1864
1865           <listitem>
1866             <para>Run the AFS initialization script by issuing the appropriate commands for this system type.</para>
1867
1868             <para><emphasis role="bold">On AIX systems:</emphasis> <orderedlist>
1869                 <listitem>
1870                   <para>Reboot the machine and log in again as the local superuser <emphasis role="bold">root</emphasis>.
1871                   <programlisting>
1872    # <emphasis role="bold">cd /</emphasis>
1873    # <emphasis role="bold">shutdown -r now</emphasis>
1874    login: <emphasis role="bold">root</emphasis>
1875    Password: <replaceable>root_password</replaceable>
1876 </programlisting></para>
1877                 </listitem>
1878
1879                 <listitem>
1880                   <para>Run the AFS initialization script. <programlisting>
1881    # <emphasis role="bold">/etc/rc.afs</emphasis>
1882 </programlisting></para>
1883                 </listitem>
1884
1885                 <listitem>
1886                   <para>Edit the AIX initialization file, <emphasis role="bold">/etc/inittab</emphasis>, adding the following line
1887                   to invoke the AFS initialization script. Place it just after the line that starts NFS daemons. <programlisting>
1888    rcafs:2:wait:/etc/rc.afs &gt; /dev/console 2&gt;&amp;1 # Start AFS services
1889 </programlisting></para>
1890                 </listitem>
1891
1892                 <listitem>
1893                   <para><emphasis role="bold">(Optional)</emphasis> There are now copies of the AFS initialization file in both the
1894                   <emphasis role="bold">/usr/vice/etc</emphasis> and <emphasis role="bold">/etc</emphasis> directories. If you want
1895                   to avoid potential confusion by guaranteeing that they are always the same, create a link between them. You can
1896                   always retrieve the original script from the AFS CD-ROM if necessary. <programlisting>
1897    # <emphasis role="bold">cd  /usr/vice/etc</emphasis>
1898    # <emphasis role="bold">rm  rc.afs</emphasis>
1899    # <emphasis role="bold">ln -s  /etc/rc.afs</emphasis>
1900 </programlisting></para>
1901                 </listitem>
1902
1903                 <listitem>
1904                   <para>Proceed to Step <link linkend="LIWQ113">4</link>.</para>
1905                 </listitem>
1906               </orderedlist></para>
1907
1908             <indexterm>
1909               <primary>Linux</primary>
1910
1911               <secondary>AFS initialization script</secondary>
1912
1913               <tertiary>on add'l server machine</tertiary>
1914             </indexterm>
1915
1916             <para><emphasis role="bold">On Fedora or RHEL Linux systems:</emphasis> 
1917               <orderedlist>
1918                 <listitem>
1919                   <para>Reboot the machine and log in again as the local superuser <emphasis role="bold">root</emphasis>.
1920  <programlisting>
1921    # <emphasis role="bold">cd /</emphasis>
1922    # <emphasis role="bold">shutdown -r now</emphasis>
1923    login: <emphasis role="bold">root</emphasis>
1924    Password: <replaceable>root_password</replaceable>
1925 </programlisting></para>
1926                 </listitem>
1927
1928                 <listitem>
1929                   <para>Run the OpenAFS initialization scripts. <programlisting>
1930    # <emphasis role="bold">/etc/rc.d/init.d/openafs-client  start</emphasis>
1931    # <emphasis role="bold">/etc/rc.d/init.d/openafs-server  start</emphasis>
1932 </programlisting></para>
1933                 </listitem>
1934
1935                 <listitem>
1936                   <para>Issue the <emphasis role="bold">chkconfig</emphasis> 
1937                   command to activate the 
1938                   <emphasis role="bold">openafs-client</emphasis> and 
1939                   <emphasis role="bold">openafs-server</emphasis> configuration 
1940                   variables. Based on the instruction in the AFS initialization 
1941                   files that begins with the string 
1942                   <computeroutput>#chkconfig</computeroutput>, the command 
1943                   automatically creates the symbolic links that incorporate the 
1944                   script into the Linux startup and shutdown sequence. 
1945 <programlisting>
1946    # <emphasis role="bold">/sbin/chkconfig  --add openafs-client</emphasis>
1947    # <emphasis role="bold">/sbin/chkconfig  --add openafs-server</emphasis>
1948 </programlisting></para>
1949                 </listitem>
1950               </orderedlist>
1951             </para>
1952             <para><emphasis role="bold">On Linux systems:</emphasis> <orderedlist>
1953                 <listitem>
1954                   <para>Reboot the machine and log in again as the local superuser <emphasis role="bold">root</emphasis>.
1955                   <programlisting>
1956    # <emphasis role="bold">cd /</emphasis>
1957    # <emphasis role="bold">shutdown -r now</emphasis>
1958    login: <emphasis role="bold">root</emphasis>
1959    Password: <replaceable>root_password</replaceable>
1960 </programlisting></para>
1961                 </listitem>
1962
1963                 <listitem>
1964                   <para>Run the OpenAFS initialization script. <programlisting>
1965    # <emphasis role="bold">/etc/rc.d/init.d/afs  start</emphasis>
1966 </programlisting></para>
1967                 </listitem>
1968
1969                 <listitem>
1970                   <para>Issue the <emphasis role="bold">chkconfig</emphasis> command to activate the <emphasis
1971                   role="bold">afs</emphasis> configuration variable. Based on the instruction in the AFS initialization file that
1972                   begins with the string <computeroutput>#chkconfig</computeroutput>, the command automatically creates the symbolic
1973                   links that incorporate the script into the Linux startup and shutdown sequence. <programlisting>
1974    # <emphasis role="bold">/sbin/chkconfig  --add afs</emphasis>
1975 </programlisting></para>
1976                 </listitem>
1977
1978                 <listitem>
1979                   <para><emphasis role="bold">(Optional)</emphasis> There are now copies of the AFS initialization file in both the
1980                   <emphasis role="bold">/usr/vice/etc</emphasis> and <emphasis role="bold">/etc/rc.d/init.d</emphasis> directories,
1981                   and copies of the <emphasis role="bold">afsd</emphasis> options file in both the <emphasis
1982                   role="bold">/usr/vice/etc</emphasis> and <emphasis role="bold">/etc/sysconfig</emphasis> directories. If you want
1983                   to avoid potential confusion by guaranteeing that the two copies of each file are always the same, create a link
1984                   between them. You can always retrieve the original script or options file from the AFS CD-ROM if necessary.
1985                   <programlisting>
1986    # <emphasis role="bold">cd /usr/vice/etc</emphasis>
1987    # <emphasis role="bold">rm afs.rc afs.conf</emphasis>
1988    # <emphasis role="bold">ln -s  /etc/rc.d/init.d/afs  afs.rc</emphasis>
1989    # <emphasis role="bold">ln -s  /etc/sysconfig/afs  afs.conf</emphasis>
1990 </programlisting></para>
1991                 </listitem>
1992
1993                 <listitem>
1994                   <para>Proceed to Step <link linkend="LIWQ113">4</link>.</para>
1995                 </listitem>
1996               </orderedlist></para>
1997
1998             <indexterm>
1999               <primary>Solaris</primary>
2000
2001               <secondary>AFS initialization script</secondary>
2002
2003               <tertiary>on add'l server machine</tertiary>
2004             </indexterm>
2005
2006             <para><emphasis role="bold">On Solaris systems:</emphasis> <orderedlist>
2007                 <listitem>
2008                   <para>Reboot the machine and log in again as the local superuser <emphasis role="bold">root</emphasis>.
2009                   <programlisting>
2010    # <emphasis role="bold">cd /</emphasis>
2011    # <emphasis role="bold">shutdown -i6 -g0 -y</emphasis>
2012    login: <emphasis role="bold">root</emphasis>
2013    Password: <replaceable>root_password</replaceable>
2014 </programlisting></para>
2015                 </listitem>
2016
2017                 <listitem>
2018                   <para>Run the AFS initialization script. <programlisting>
2019    # <emphasis role="bold">/etc/init.d/afs  start</emphasis>
2020 </programlisting></para>
2021                 </listitem>
2022
2023                 <listitem>
2024                   <para>Change to the <emphasis role="bold">/etc/init.d</emphasis> directory and issue the <emphasis role="bold">ln
2025                   -s</emphasis> command to create symbolic links that incorporate the AFS initialization script into the Solaris
2026                   startup and shutdown sequence. <programlisting>
2027    # <emphasis role="bold">cd /etc/init.d</emphasis>
2028    # <emphasis role="bold">ln -s ../init.d/afs /etc/rc3.d/S99afs</emphasis>
2029    # <emphasis role="bold">ln -s ../init.d/afs /etc/rc0.d/K66afs</emphasis>
2030 </programlisting></para>
2031                 </listitem>
2032
2033                 <listitem>
2034                   <para><emphasis role="bold">(Optional)</emphasis> There are now copies of the AFS initialization file in both the
2035                   <emphasis role="bold">/usr/vice/etc</emphasis> and <emphasis role="bold">/etc/init.d</emphasis> directories. If
2036                   you want to avoid potential confusion by guaranteeing that they are always the same, create a link between them.
2037                   You can always retrieve the original script from the OpenAFS Binary Distribution if necessary. <programlisting>
2038    # <emphasis role="bold">cd /usr/vice/etc</emphasis>
2039    # <emphasis role="bold">rm afs.rc</emphasis>
2040    # <emphasis role="bold">ln -s  /etc/init.d/afs  afs.rc</emphasis>
2041 </programlisting></para>
2042                 </listitem>
2043               </orderedlist></para>
2044           </listitem>
2045
2046           <listitem id="LIWQ113">
2047             <para>Verify that <emphasis role="bold">/usr/afs</emphasis> and its subdirectories on the new
2048             file server machine meet the ownership and mode bit requirements outlined in <link linkend="HDRWQ96">Protecting
2049             Sensitive AFS Directories</link>. If necessary, use the <emphasis role="bold">chmod</emphasis> command to correct the
2050             mode bits.</para>
2051           </listitem>
2052
2053           <listitem>
2054             <para>To configure this machine as a database server machine, proceed to <link linkend="HDRWQ114">Installing Database
2055             Server Functionality</link>.</para>
2056           </listitem>
2057         </orderedlist></para>
2058
2059       <indexterm>
2060         <primary>database server machine</primary>
2061
2062         <secondary>requirements for installation</secondary>
2063       </indexterm>
2064
2065       <indexterm>
2066         <primary>requirements</primary>
2067
2068         <secondary>database server machine</secondary>
2069       </indexterm>
2070     </sect2>
2071   </sect1>
2072
2073   <sect1 id="HDRWQ114">
2074     <title>Installing Database Server Functionality</title>
2075
2076     <para>This section explains how to install database server functionality. Database server machines have two defining
2077     characteristics. First, they run the Protection Server, and Volume Location (VL) Server processes. They
2078     also run the Backup Server if the cell uses the AFS Backup System, as is assumed in these instructions. Second, they appear in
2079     the <emphasis role="bold">CellServDB</emphasis> file of every machine in the cell (and of client machines in foreign cells, if
2080     they are to access files in this cell).</para>
2081
2082     <para>Note the following requirements for database server machines. <itemizedlist>
2083         <listitem>
2084           <para>In the conventional configuration, database server machines also serve as file server machines (run the File Server,
2085           Volume Server and Salvager processes). If you choose not to run file server functionality on a database server machine,
2086           then the kernel does not have to incorporate AFS modifications, but the local <emphasis role="bold">/usr/afs</emphasis>
2087           directory must house most of the standard files and subdirectories. In particular, the <emphasis
2088           role="bold">/usr/afs/etc/KeyFile</emphasis> file must contain the same keys as all other server machines in the cell. If
2089           you run a system control machine, run the <emphasis role="bold">upclientetc</emphasis> process on every database server
2090           machine other than the system control machine; if you do not run a system control machine, use the <emphasis
2091           role="bold">bos addkey</emphasis> command as instructed in the chapter in the <emphasis>OpenAFS Administration
2092           Guide</emphasis> about maintaining server encryption keys.</para>
2093
2094           <para>The instructions in this section assume that the machine on which you are installing database server functionality
2095           is already a file server machine. Contact the OpenAFS mailing list to learn how to install database server
2096           functionality on a non-file server machine.</para>
2097         </listitem>
2098
2099         <listitem>
2100           <para>During the installation of database server functionality, you must restart all of the database server machines to
2101           force the election of a new Ubik coordinator (synchronization site) for each database server process. This can cause a
2102           system outage, which usually lasts less than 5 minutes.</para>
2103         </listitem>
2104
2105         <listitem>
2106           <para>Updating the kernel memory list of database server machines on each client machine is generally the most
2107           time-consuming part of installing a new database server machine. It is, however, crucial for correct functioning in your
2108           cell. Incorrect knowledge of your cell's database server machines can prevent your users from authenticating, accessing
2109           files, and issuing AFS commands.</para>
2110
2111           <para>You update a client's kernel memory list by changing the <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis>
2112           file and then either rebooting or issuing the <emphasis role="bold">fs newcell</emphasis> command. For instructions, see
2113           the chapter in the <emphasis>OpenAFS Administration Guide</emphasis> about administering client machines.</para>
2114
2115           <para>The point at which you update your clients' knowledge of database server machines depends on which of the database
2116           server machines has the lowest IP address. The following instructions indicate the appropriate place to update your client
2117           machines in either case. <itemizedlist>
2118               <listitem>
2119                 <para>If the new database server machine has a lower IP address than any existing database server machine, update
2120                 the <emphasis role="bold">CellServDB</emphasis> file on every client machine before restarting the database server
2121                 processes. If you do not, users can become unable to update (write to) any of the AFS databases. This is because the
2122                 machine with the lowest IP address is usually elected as the Ubik coordinator, and only the Coordinator accepts
2123                 database writes. On client machines that do not have the new list of database server machines, the Cache Manager
2124                 cannot locate the new coordinator. (Be aware that if clients contact the new coordinator before it is actually in
2125                 service, they experience a timeout before contacting another database server machine. This is a minor, and
2126                 temporary, problem compared to being unable to write to the database.)</para>
2127               </listitem>
2128
2129               <listitem>
2130                 <para>If the new database server machine does not have the lowest IP address of any database server machine, then it
2131                 is better to update clients after restarting the database server processes. Client machines do not start using the
2132                 new database server machine until you update their kernel memory list, but that does not usually cause timeouts or
2133                 update problems (because the new machine is not likely to become the coordinator).</para>
2134               </listitem>
2135             </itemizedlist></para>
2136         </listitem>
2137       </itemizedlist></para>
2138
2139     <indexterm>
2140       <primary>overview</primary>
2141
2142       <secondary>installing additional database server machine</secondary>
2143     </indexterm>
2144
2145     <sect2 id="Header_110">
2146       <title>Summary of Procedures</title>
2147
2148       <para>To install a database server machine, perform the following procedures. <orderedlist>
2149           <listitem>
2150             <para>Install the <emphasis role="bold">bos</emphasis> suite of commands locally, as a precaution</para>
2151           </listitem>
2152
2153           <listitem>
2154             <para>Add the new machine to the <emphasis role="bold">/usr/afs/etc/CellServDB</emphasis> file on existing file server
2155             machines</para>
2156           </listitem>
2157
2158           <listitem>
2159             <para>Update your cell's central <emphasis role="bold">CellServDB</emphasis> source file and the file you make available
2160             to foreign cells</para>
2161           </listitem>
2162
2163           <listitem>
2164             <para>Update every client machine's <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file and kernel memory
2165             list of database server machines</para>
2166           </listitem>
2167
2168           <listitem>
2169             <para>Start the database server processes (Backup Server, Protection Server, and Volume Location
2170             Server)</para>
2171           </listitem>
2172
2173           <listitem>
2174             <para>Restart the database server processes on every database server machine</para>
2175           </listitem>
2176
2177           <listitem>
2178             <para>If required, request that grand.central.org add details of 
2179             your new database server machine to the global CellServDB</para>
2180           </listitem>
2181           
2182           <listitem>
2183             <para>If required, add details of your new database server to the
2184             AFS database location records in your site's DNS</para>
2185           </listitem>
2186           
2187         </orderedlist></para>
2188
2189       <indexterm>
2190         <primary>database server machine</primary>
2191
2192         <secondary>installing</secondary>
2193
2194         <tertiary>additional</tertiary>
2195       </indexterm>
2196
2197       <indexterm>
2198         <primary>instructions</primary>
2199
2200         <secondary>database server machine, installing additional</secondary>
2201       </indexterm>
2202
2203       <indexterm>
2204         <primary>installing</primary>
2205
2206         <secondary>database server machine</secondary>
2207
2208         <tertiary>additional</tertiary>
2209       </indexterm>
2210     </sect2>
2211
2212     <sect2 id="Header_111">
2213       <title>Instructions</title>
2214
2215       <note>
2216         <para>It is assumed that your PATH environment variable includes the directory that houses the AFS command binaries. If not,
2217         you possibly need to precede the command names with the appropriate pathname.</para>
2218       </note>
2219
2220       <orderedlist>
2221         <listitem>
2222           <para>You can perform the following instructions on either a server or client machine. Login as an AFS administrator who
2223           is listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file on all server machines. 
2224 <programlisting> 
2225    % <emphasis role="bold">kinit</emphasis> <replaceable>admin_user</replaceable>
2226    Password: <replaceable>admin_password</replaceable>
2227    % <emphasis role="bold">aklog</emphasis>
2228 </programlisting>
2229           </para>
2230         </listitem>
2231
2232         <listitem>
2233           <para>If you are working on a client machine configured in the conventional manner, the <emphasis
2234           role="bold">bos</emphasis> command suite resides in the <emphasis role="bold">/usr/afsws/bin</emphasis> directory, a
2235           symbolic link to an AFS directory. An error during installation can potentially block access to AFS, in which case it is
2236           helpful to have a copy of the <emphasis role="bold">bos</emphasis> binary on the local disk. This step is not necessary if
2237           you are working on a server machine, where the binary resides in the local <emphasis role="bold">/usr/afs/bin</emphasis>
2238           directory. <programlisting>
2239    % <emphasis role="bold">cp  /usr/afsws/bin/bos   /tmp</emphasis>
2240 </programlisting> <indexterm>
2241               <primary>bos commands</primary>
2242
2243               <secondary>addhost</secondary>
2244             </indexterm> <indexterm>
2245               <primary>commands</primary>
2246
2247               <secondary>bos addhost</secondary>
2248             </indexterm> <indexterm>
2249               <primary>database server machine</primary>
2250
2251               <secondary>entry in server CellServDB file</secondary>
2252
2253               <tertiary>for new db-server machine</tertiary>
2254             </indexterm> <indexterm>
2255               <primary>CellServDB file (server)</primary>
2256
2257               <secondary>adding entry for new db-server machine</secondary>
2258             </indexterm> <indexterm>
2259               <primary>adding</primary>
2260
2261               <secondary>new db-server machine to CellServDB files</secondary>
2262             </indexterm></para>
2263         </listitem>
2264
2265         <listitem id="LIWQ115">
2266           <para>Issue the <emphasis role="bold">bos addhost</emphasis> command to add the new database server
2267           machine to the <emphasis role="bold">/usr/afs/etc/CellServDB</emphasis> file on existing server machines (as well as the
2268           new database server machine itself).</para>
2269
2270           <para>Substitute the new database server machine's fully-qualified hostname for the <replaceable>host name</replaceable>
2271           argument. If you run a system control machine, substitute its fully-qualified hostname for the
2272           <replaceable>machine&nbsp;name</replaceable> argument. If you do not run a system control machine, repeat the <emphasis
2273           role="bold">bos addhost</emphasis> command once for each server machine in your cell (including the new database server
2274           machine itself), by substituting each one's fully-qualified hostname for the <replaceable>machine&nbsp;name</replaceable>
2275           argument in turn.</para>
2276
2277           <programlisting>
2278    % <emphasis role="bold">bos addhost</emphasis> &lt;<replaceable>machine name</replaceable>&gt;  &lt;<replaceable>host name</replaceable>&gt;   
2279 </programlisting>
2280
2281           <para>If you run a system control machine, wait for the Update Server to distribute the new <emphasis
2282           role="bold">CellServDB</emphasis> file, which takes up to five minutes by default. If you are issuing individual <emphasis
2283           role="bold">bos addhost</emphasis> commands, attempt to issue all of them within five minutes.</para>
2284
2285           <note>
2286             <para>It is best to maintain a one-to-one mapping between hostnames and IP addresses on a multihomed database server
2287             machine (the conventional configuration for any AFS machine). The BOS Server uses the <emphasis
2288             role="bold">gethostbyname(&nbsp;)</emphasis> routine to obtain the IP address associated with the <replaceable>host
2289             name</replaceable> argument. If there is more than one address, the BOS Server records in the <emphasis
2290             role="bold">CellServDB</emphasis> entry the one that appears first in the list of addresses returned by the routine. The
2291             routine possibly returns addresses in a different order on different machines, which can create inconsistency.</para>
2292           </note>
2293         </listitem>
2294
2295         <listitem>
2296           <para><emphasis role="bold">(Optional)</emphasis> Issue the <emphasis role="bold">bos listhosts</emphasis> command on each
2297           server machine to verify that the new database server machine appears in its <emphasis role="bold">CellServDB</emphasis>
2298           file. <programlisting>
2299    % <emphasis role="bold">bos listhosts</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
2300 </programlisting></para>
2301         </listitem>
2302
2303         <listitem id="LIWQ116">
2304           <para>Add the new database server machine to your cell's central <emphasis
2305           role="bold">CellServDB</emphasis> source file, if you use one. The standard location is <emphasis
2306           role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
2307           role="bold">/common/etc/CellServDB</emphasis>.</para>
2308
2309           <para>If you are willing to make your cell accessible to users in foreign cells, add the new database server machine to
2310           the file that lists your cell's database server machines. The conventional location is <emphasis
2311           role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
2312           role="bold">/service/etc/CellServDB.local</emphasis>. <indexterm>
2313               <primary>database server machine</primary>
2314
2315               <secondary>entry in client CellServDB file</secondary>
2316
2317               <tertiary>for new db-server machine</tertiary>
2318             </indexterm> <indexterm>
2319               <primary>CellServDB file (client)</primary>
2320
2321               <secondary>adding entry</secondary>
2322
2323               <tertiary>for new db-server machine</tertiary>
2324             </indexterm> <indexterm>
2325               <primary>client machine</primary>
2326
2327               <secondary>CellServDB file</secondary>
2328
2329               <tertiary>adding entry</tertiary>
2330             </indexterm></para>
2331         </listitem>
2332
2333         <listitem id="LIWQ117">
2334           <para>If this machine's IP address is lower than any existing database server machine's, update
2335           every client machine's <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file and kernel memory list to include
2336           this machine. (If this machine's IP address is not the lowest, it is acceptable to wait until Step <link
2337           linkend="LIWQ123">12</link>.)</para>
2338
2339           <para>There are several ways to update the <emphasis role="bold">CellServDB</emphasis> file on client machines, as
2340           detailed in the chapter of the <emphasis>OpenAFS Administration Guide</emphasis> about administering client machines. One
2341           option is to copy over the central update source (which you updated in Step <link linkend="LIWQ116">5</link>).
2342           To update the machine's kernel memory list, you can
2343           either reboot after changing the <emphasis role="bold">CellServDB</emphasis> file or issue the <emphasis role="bold">fs
2344           newcell</emphasis> command. 
2345             <indexterm>
2346               <primary>database server machine</primary>
2347
2348               <secondary>starting database server processes</secondary>
2349             </indexterm> <indexterm>
2350               <primary>BosConfig file</primary>
2351
2352               <secondary>adding entries</secondary>
2353
2354               <tertiary>database server machine</tertiary>
2355             </indexterm> <indexterm>
2356               <primary>adding</primary>
2357
2358               <secondary>entries to BosConfig file</secondary>
2359
2360               <tertiary>database server machine</tertiary>
2361             </indexterm></para>
2362         </listitem>
2363         
2364         <listitem>
2365           <para>If you are running a cell which still relies upon
2366           <emphasis role="bold">kaserver</emphasis> see 
2367           <link linkend="KAS010">Starting the Authentication Service</link>
2368           for an additional installation step.</para>
2369         </listitem>
2370
2371         <listitem id="LIWQ119">
2372           <indexterm>
2373             <primary>Backup Server</primary>
2374             <secondary>starting</secondary>
2375             <tertiary>new db-server machine</tertiary>
2376           </indexterm> <indexterm>
2377             <primary>starting</primary>
2378             <secondary>Backup Server</secondary>
2379             <tertiary>new db-server machine</tertiary>
2380           </indexterm>
2381
2382           <para>Start the Backup Server (the <emphasis role="bold">buserver</emphasis> process). You must
2383           perform other configuration procedures before actually using the AFS Backup System, as detailed in the <emphasis>OpenAFS
2384           Administration Guide</emphasis>. <programlisting>
2385    % <emphasis role="bold">bos create</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">buserver simple /usr/afs/bin/buserver</emphasis>
2386 </programlisting> <indexterm>
2387               <primary>Protection Server</primary>
2388
2389               <secondary>starting</secondary>
2390
2391               <tertiary>new db-server machine</tertiary>
2392             </indexterm> <indexterm>
2393               <primary>starting</primary>
2394
2395               <secondary>Protection Server</secondary>
2396
2397               <tertiary>new db-server machine</tertiary>
2398             </indexterm></para>
2399         </listitem>
2400
2401         <listitem id="LIWQ120">
2402           <para>Start the Protection Server (the <emphasis role="bold">ptserver</emphasis> process).
2403           <programlisting>
2404    % <emphasis role="bold">bos create</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">ptserver simple /usr/afs/bin/ptserver</emphasis>
2405 </programlisting> <indexterm>
2406               <primary>VL Server (vlserver process)</primary>
2407
2408               <secondary>starting</secondary>
2409
2410               <tertiary>new db-server machine</tertiary>
2411             </indexterm> <indexterm>
2412               <primary>starting</primary>
2413
2414               <secondary>VL Server</secondary>
2415
2416               <tertiary>new db-server machine</tertiary>
2417             </indexterm></para>
2418         </listitem>
2419
2420         <listitem id="LIWQ121">
2421           <para>Start the Volume Location (VL) Server (the <emphasis role="bold">vlserver</emphasis>
2422           process). <programlisting>
2423    % <emphasis role="bold">bos create</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">vlserver simple /usr/afs/bin/vlserver</emphasis>
2424 </programlisting> <indexterm>
2425               <primary>commands</primary>
2426
2427               <secondary>bos restart</secondary>
2428
2429               <tertiary>on new db-server machine</tertiary>
2430             </indexterm> <indexterm>
2431               <primary>bos commands</primary>
2432
2433               <secondary>restart</secondary>
2434
2435               <tertiary>on new db-server machine</tertiary>
2436             </indexterm> <indexterm>
2437               <primary>restarting server process</primary>
2438
2439               <secondary>on new db-server machine</secondary>
2440             </indexterm> <indexterm>
2441               <primary>server process</primary>
2442
2443               <secondary>restarting</secondary>
2444
2445               <tertiary>on new db-server machine</tertiary>
2446             </indexterm></para>
2447         </listitem>
2448
2449         <listitem id="LIWQ122">
2450           <para>Issue the <emphasis role="bold">bos restart</emphasis> command on every database server
2451           machine in the cell, including the new machine. The command restarts the Authentication, Backup, Protection, and VL
2452           Servers, which forces an election of a new Ubik coordinator for each process. The new machine votes in the election and is
2453           considered as a potential new coordinator.</para>
2454
2455           <para>A cell-wide service outage is possible during the election of a new coordinator for the VL Server, but it normally
2456           lasts less than five minutes. Such an outage is particularly likely if you are installing your cell's second database
2457           server machine. Messages tracing the progress of the election appear on the console.</para>
2458
2459           <para>Repeat this command on each of your cell's database server machines in quick succession. Begin with the machine with
2460           the lowest IP address.</para>
2461
2462           <programlisting>
2463    %  <emphasis role="bold">bos restart</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">kaserver buserver ptserver vlserver</emphasis>    
2464 </programlisting>
2465
2466           <para>If an error occurs, restart all server processes on the database server machines again by using one of the following
2467           methods: <itemizedlist>
2468               <listitem>
2469                 <para>Issue the <emphasis role="bold">bos restart</emphasis> command with the <emphasis
2470                 role="bold">-bosserver</emphasis> flag for each database server machine</para>
2471               </listitem>
2472
2473               <listitem>
2474                 <para>Reboot each database server machine, either using the <emphasis role="bold">bos exec</emphasis> command or at
2475                 its console</para>
2476               </listitem>
2477             </itemizedlist></para>
2478         </listitem>
2479
2480         <listitem id="LIWQ123">
2481           <para>If you did not update the <emphasis role="bold">CellServDB</emphasis> file on client machines
2482           in Step <link linkend="LIWQ117">6</link>, do so now.</para>
2483         </listitem>
2484
2485         <listitem id="LIWQ124">
2486           <para>If you wish to participate in the AFS
2487           global name space, send the new database server machine's name and 
2488           IP address to grand.central.org. Do so, by emailing an updated
2489           <emphasis role="bold">CellServDB</emphasis> fragment for your cell
2490           to cellservdb@grand.central.org</para>
2491           <para>More details on the registration procedures for the
2492           CellServDB maintained by grand.central.org are available from
2493           <ulink url="http://grand.central.org/csdb.html">
2494           http://grand.central.org/csdb.html</ulink></para>
2495         </listitem>
2496       </orderedlist>
2497
2498       <indexterm>
2499         <primary>database server machine</primary>
2500
2501         <secondary>removing from service</secondary>
2502       </indexterm>
2503
2504       <indexterm>
2505         <primary>instructions</primary>
2506
2507         <secondary>database server machine, removing</secondary>
2508       </indexterm>
2509
2510       <indexterm>
2511         <primary>removing</primary>
2512
2513         <secondary>database server machine from service</secondary>
2514       </indexterm>
2515
2516       <indexterm>
2517         <primary>overview</primary>
2518
2519         <secondary>removing database server machine</secondary>
2520       </indexterm>
2521     </sect2>
2522   </sect1>
2523
2524   <sect1 id="HDRWQ125">
2525     <title>Removing Database Server Functionality</title>
2526
2527     <para>Removing database server machine functionality is nearly the reverse of installing it.</para>
2528
2529     <sect2 id="Header_113">
2530       <title>Summary of Procedures</title>
2531
2532       <para>To decommission a database server machine, perform the following procedures. <orderedlist>
2533           <listitem>
2534             <para>Install the <emphasis role="bold">bos</emphasis> suite of commands locally, as a precaution</para>
2535           </listitem>
2536
2537           <listitem>
2538             <para>If you participate in the global AFS namespace, notify
2539             grand.central.org that you are decommissioning a database server 
2540             machine</para>
2541           </listitem>
2542
2543           <listitem>
2544             <para>Update your cell's central <emphasis role="bold">CellServDB</emphasis> source file and the file you make available
2545             to foreign cells</para>
2546           </listitem>
2547
2548           <listitem>
2549             <para>Update every client machine's <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file and kernel memory
2550             list of database server machines</para>
2551           </listitem>
2552
2553           <listitem>
2554             <para>Remove the machine from the <emphasis role="bold">/usr/afs/etc/CellServDB</emphasis> file on file server
2555             machines</para>
2556           </listitem>
2557
2558           <listitem>
2559             <para>Stop the database server processes and remove them from the <emphasis
2560             role="bold">/usr/afs/local/BosConfig</emphasis> file if desired</para>
2561           </listitem>
2562
2563           <listitem>
2564             <para>Restart the database server processes on the remaining database server machines</para>
2565           </listitem>
2566         </orderedlist></para>
2567     </sect2>
2568
2569     <sect2 id="Header_114">
2570       <title>Instructions</title>
2571
2572       <note>
2573         <para>It is assumed that your PATH environment variable includes the directory that houses the AFS command binaries. If not,
2574         you possibly need to precede the command names with the appropriate pathname.</para>
2575       </note>
2576
2577       <orderedlist>
2578         <listitem>
2579           <para>You can perform the following instructions on either a server or client machine. Login as an AFS administrator who
2580           is listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file on all server machines. 
2581 <programlisting>
2582    % <emphasis role="bold">kinit</emphasis> <replaceable>admin_user</replaceable>
2583    Password: <replaceable>admin_password</replaceable>
2584    % <emphasis role="bold">aklog</emphasis>
2585 </programlisting></para>
2586         </listitem>
2587
2588         <listitem>
2589           <para>If you are working on a client machine configured in the conventional manner, the <emphasis
2590           role="bold">bos</emphasis> command suite resides in the <emphasis role="bold">/usr/afsws/bin</emphasis> directory, a
2591           symbolic link to an AFS directory. An error during installation can potentially block access to AFS, in which case it is
2592           helpful to have a copy of the <emphasis role="bold">bos</emphasis> binary on the local disk. This step is not necessary if
2593           you are working on a server machine, where the binary resides in the local <emphasis role="bold">/usr/afs/bin</emphasis>
2594           directory. <programlisting>
2595    % <emphasis role="bold">cp  /usr/afsws/bin/bos   /tmp</emphasis>
2596 </programlisting></para>
2597         </listitem>
2598
2599         <listitem id="LIWQ126">
2600           <para>If your cell is included in the global
2601           <emphasis role="bold">CellServDB</emphasis>, send the revised list of 
2602           your cell's database server machines to grand.central.org</para>
2603
2604           <para>If the administrators in foreign cells do not learn about the change in your cell,
2605           they cannot update the <emphasis role="bold">CellServDB</emphasis> file on their client machines. Users in foreign cells
2606           continue to send database requests to the decommissioned machine, which creates needless network traffic and activity on
2607           the machine. Also, the users experience time-out delays while their request is forwarded to a valid database server
2608           machine.</para>
2609         </listitem>
2610
2611         <listitem id="LIWQ127">
2612           <para>Remove the decommissioned machine from your cell's central <emphasis
2613           role="bold">CellServDB</emphasis> source file, if you use one. The conventional location is <emphasis
2614           role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
2615           role="bold">/common/etc/CellServDB</emphasis>.</para>
2616
2617           <para>If you maintain a file that users in foreign cells can access to learn about your cell's database server machines,
2618           update it also. The conventional location is <emphasis
2619           role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
2620           role="bold">/service/etc/CellServDB.local</emphasis>. <indexterm>
2621               <primary>database server machine</primary>
2622
2623               <secondary>entry in client CellServDB file</secondary>
2624
2625               <tertiary>removing</tertiary>
2626             </indexterm> <indexterm>
2627               <primary>CellServDB file (client)</primary>
2628
2629               <secondary>removing entry</secondary>
2630             </indexterm> <indexterm>
2631               <primary>client machine</primary>
2632
2633               <secondary>CellServDB file</secondary>
2634
2635               <tertiary>removing entry</tertiary>
2636             </indexterm> <indexterm>
2637               <primary>removing</primary>
2638
2639               <secondary>entry from CellServDB file</secondary>
2640             </indexterm></para>
2641         </listitem>
2642
2643         <listitem id="LIWQ128">
2644           <para>Update every client machine's <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file
2645           and kernel memory list to exclude this machine. Altering the <emphasis role="bold">CellServDB</emphasis> file and kernel
2646           memory list before stopping the actual database server processes avoids possible time-out delays that result when users
2647           send requests to a decommissioned database server machine that is still listed in the file.</para>
2648
2649           <para>There are several ways to update the <emphasis role="bold">CellServDB</emphasis> file on client machines, as
2650           detailed in the chapter of the <emphasis>OpenAFS Administration Guide</emphasis> about administering client machines. One
2651           option is to copy over the central update source (which you updated in Step <link linkend="LIWQ116">5</link>).
2652           To update the machine's kernel memory list, you can
2653           either reboot after changing the <emphasis role="bold">CellServDB</emphasis> file or issue the <emphasis role="bold">fs
2654           newcell</emphasis> command. <indexterm>
2655               <primary>bos commands</primary>
2656
2657               <secondary>removehost</secondary>
2658             </indexterm> <indexterm>
2659               <primary>commands</primary>
2660
2661               <secondary>bos removehost</secondary>
2662             </indexterm> <indexterm>
2663               <primary>CellServDB file (server)</primary>
2664
2665               <secondary>removing entry</secondary>
2666             </indexterm> <indexterm>
2667               <primary>database server machine</primary>
2668
2669               <secondary>entry in server CellServDB file</secondary>
2670
2671               <tertiary>removing</tertiary>
2672             </indexterm></para>
2673         </listitem>
2674
2675         <listitem id="LIWQ129">
2676           <para>Issue the <emphasis role="bold">bos removehost</emphasis> command to remove the
2677           decommissioned database server machine from the <emphasis role="bold">/usr/afs/etc/CellServDB</emphasis> file on server
2678           machines.</para>
2679
2680           <para>Substitute the decommissioned database server machine's fully-qualified hostname for the <replaceable>host
2681           name</replaceable> argument. If you run a system control machine, substitute its fully-qualified hostname for the
2682           <replaceable>machine&nbsp;name</replaceable> argument. If you do not run a system control machine, repeat the <emphasis
2683           role="bold">bos removehost</emphasis> command once for each server machine in your cell (including the decommissioned
2684           database server machine itself), by substituting each one's fully-qualified hostname for the
2685           <replaceable>machine&nbsp;name</replaceable> argument in turn.</para>
2686
2687           <programlisting>
2688    % <emphasis role="bold">bos removehost</emphasis> &lt;<replaceable>machine name</replaceable>&gt;  &lt;<replaceable>host name</replaceable>&gt;   
2689 </programlisting>
2690
2691           <para>If you run a system control machine, wait for the Update Server to distribute the new <emphasis
2692           role="bold">CellServDB</emphasis> file, which takes up to five minutes by default. If issuing individual <emphasis
2693           role="bold">bos removehost</emphasis> commands, attempt to issue all of them within five minutes.</para>
2694         </listitem>
2695
2696         <listitem>
2697           <para><emphasis role="bold">(Optional)</emphasis> Issue the <emphasis role="bold">bos listhosts</emphasis> command on each
2698           server machine to verify that the decommissioned database server machine no longer appears in its <emphasis
2699           role="bold">CellServDB</emphasis> file. <programlisting>
2700    % <emphasis role="bold">bos listhosts</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
2701 </programlisting> <indexterm>
2702               <primary>commands</primary>
2703
2704               <secondary>bos stop</secondary>
2705             </indexterm> <indexterm>
2706               <primary>bos commands</primary>
2707
2708               <secondary>stop</secondary>
2709             </indexterm> <indexterm>
2710               <primary>database server machine</primary>
2711
2712               <secondary>stopping database server processes</secondary>
2713             </indexterm> <indexterm>
2714               <primary>stopping</primary>
2715
2716               <secondary>database server processes</secondary>
2717             </indexterm> <indexterm>
2718               <primary>Backup Server</primary>
2719
2720               <secondary>stopping</secondary>
2721             </indexterm> <indexterm>
2722               <primary>Protection Server</primary>
2723
2724               <secondary>stopping</secondary>
2725             </indexterm> <indexterm>
2726               <primary>VL Server (vlserver process)</primary>
2727
2728               <secondary>stopping</secondary>
2729             </indexterm></para>
2730         </listitem>
2731
2732         <listitem id="LIWQ130">
2733           <para>Issue the <emphasis role="bold">bos stop</emphasis> command to stop the database server
2734           processes on the machine, by substituting its fully-qualified hostname for the
2735           <replaceable>machine&nbsp;name</replaceable> argument. The command changes each process's status in the <emphasis
2736           role="bold">/usr/afs/local/BosConfig</emphasis> file to <computeroutput>NotRun</computeroutput>, but does not remove its
2737           entry from the file. <programlisting>
2738    % <emphasis role="bold">bos stop</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">kaserver buserver ptserver vlserver</emphasis>
2739 </programlisting> <indexterm>
2740               <primary>commands</primary>
2741
2742               <secondary>bos delete</secondary>
2743             </indexterm> <indexterm>
2744               <primary>bos commands</primary>
2745
2746               <secondary>delete</secondary>
2747             </indexterm> <indexterm>
2748               <primary>BosConfig file</primary>
2749
2750               <secondary>removing entries</secondary>
2751             </indexterm> <indexterm>
2752               <primary>removing</primary>
2753
2754               <secondary>entries from BosConfig File</secondary>
2755             </indexterm> <indexterm>
2756               <primary>database server machine</primary>
2757
2758               <secondary>removing db-server processes from BosConfig file</secondary>
2759             </indexterm></para>
2760         </listitem>
2761
2762         <listitem id="LIWQ131">
2763           <para><emphasis role="bold">(Optional)</emphasis> Issue the <emphasis role="bold">bos
2764           delete</emphasis> command to remove the entries for database server processes from the <emphasis
2765           role="bold">BosConfig</emphasis> file. This step is unnecessary if you plan to restart the database server functionality
2766           on this machine in future. <programlisting>
2767    % <emphasis role="bold">bos delete</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">buserver ptserver vlserver</emphasis>
2768 </programlisting> <indexterm>
2769               <primary>commands</primary>
2770
2771               <secondary>bos restart</secondary>
2772
2773               <tertiary>on removed db-server machine</tertiary>
2774             </indexterm> <indexterm>
2775               <primary>bos commands</primary>
2776
2777               <secondary>restart</secondary>
2778
2779               <tertiary>on removed db-server machine</tertiary>
2780             </indexterm> <indexterm>
2781               <primary>restarting server process</primary>
2782
2783               <secondary>on removed db-server machine</secondary>
2784             </indexterm> <indexterm>
2785               <primary>server process</primary>
2786
2787               <secondary>restarting</secondary>
2788
2789               <tertiary>on removed db-server machine</tertiary>
2790             </indexterm></para>
2791         </listitem>
2792
2793         <listitem id="LIWQ132">
2794           <para>Issue the <emphasis role="bold">bos restart</emphasis> command on every database server
2795           machine in the cell, to restart the Backup, Protection, and VL Servers. This forces the election of a Ubik
2796           coordinator for each process, ensuring that the remaining database server processes recognize that the machine is no
2797           longer a database server.</para>
2798
2799           <para>A cell-wide service outage is possible during the election of a new coordinator for the VL Server, but it normally
2800           lasts less than five minutes. Messages tracing the progress of the election appear on the console.</para>
2801
2802           <para>Repeat this command on each of your cell's database server machines in quick succession. Begin with the machine with
2803           the lowest IP address.</para>
2804
2805           <programlisting>
2806    %  <emphasis role="bold">bos restart</emphasis> &lt;<replaceable>machine name</replaceable>&gt; <emphasis role="bold">buserver ptserver vlserver</emphasis>    
2807 </programlisting>
2808
2809           <para>If an error occurs, restart all server processes on the database server machines again by using one of the following
2810           methods: <itemizedlist>
2811               <listitem>
2812                 <para>Issue the <emphasis role="bold">bos restart</emphasis> command with the <emphasis
2813                 role="bold">-bosserver</emphasis> flag for each database server machine</para>
2814               </listitem>
2815
2816               <listitem>
2817                 <para>Reboot each database server machine, either using the <emphasis role="bold">bos exec</emphasis> command or at
2818                 its console</para>
2819               </listitem>
2820             </itemizedlist></para>
2821         </listitem>
2822       </orderedlist>
2823     </sect2>
2824   </sect1>
2825 </chapter>