Deorbit AIX-specific QuickStartGuide bits
[openafs.git] / doc / xml / QuickStartUnix / auqbg007.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <chapter id="HDRWQ133">
3   <title>Installing Additional Client Machines</title>
4
5   <para>
6   <indexterm>
7     <primary>instructions</primary>
8
9     <secondary>client machine</secondary>
10   </indexterm>
11
12   <indexterm>
13     <primary>installing</primary>
14
15     <secondary>client functionality</secondary>
16
17     <tertiary>client machine</tertiary>
18   </indexterm>
19
20   This chapter describes how to install AFS client machines after you have installed the first AFS machine. Some parts of the
21   installation differ depending on whether or not the new client is of the same AFS system type (uses the same AFS binaries) as a
22   previously installed client machine. <indexterm>
23       <primary>overview</primary>
24
25       <secondary>installing client machine</secondary>
26     </indexterm></para>
27
28   <sect1 id="Header_116">
29     <title>Summary of Procedures</title>
30
31     <orderedlist>
32       <listitem>
33         <para>Incorporate AFS into the machine's kernel</para>
34       </listitem>
35
36       <listitem>
37         <para>Define the machine's cell membership</para>
38       </listitem>
39
40       <listitem>
41         <para>Define cache location and size</para>
42       </listitem>
43
44       <listitem>
45         <para>Create the <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file, which determines which foreign cells the
46         client can access in addition to the local cell</para>
47       </listitem>
48
49       <listitem>
50         <para>Create the <emphasis role="bold">/afs</emphasis> directory and start the Cache Manager</para>
51       </listitem>
52
53       <listitem>
54         <para>Create and mount volumes for housing AFS client binaries (necessary only for clients of a new system type)</para>
55       </listitem>
56
57       <listitem>
58         <para>Create a link from the local <emphasis role="bold">/usr/afsws</emphasis> directory to the AFS directory housing the
59         AFS client binaries</para>
60       </listitem>
61
62       <listitem>
63         <para>Modify the machine's authentication system to enable AFS users to obtain tokens at login</para>
64       </listitem>
65     </orderedlist>
66
67     <indexterm>
68       <primary>Binary Distribution</primary>
69
70       <secondary>creating /tmp/afsdist directory</secondary>
71
72       <tertiary>client machine</tertiary>
73     </indexterm>
74
75     <indexterm>
76       <primary>afsdist directory</primary>
77
78       <secondary>client machine</secondary>
79     </indexterm>
80
81     <indexterm>
82       <primary>client machine</primary>
83
84       <secondary>/tmp/afsdist directory</secondary>
85     </indexterm>
86
87     <indexterm>
88       <primary>creating</primary>
89
90       <secondary>/tmp/afsdist directory</secondary>
91
92       <tertiary>client machine</tertiary>
93     </indexterm>
94
95     <indexterm>
96       <primary>usr/vice/etc directory</primary>
97
98       <secondary>client machine</secondary>
99     </indexterm>
100
101     <indexterm>
102       <primary>client machine</primary>
103
104       <secondary>/usr/vice/etc directory</secondary>
105     </indexterm>
106
107     <indexterm>
108       <primary>creating</primary>
109
110       <secondary>/usr/vice/etc directory</secondary>
111
112       <tertiary>client machine</tertiary>
113     </indexterm>
114   </sect1>
115
116   <sect1 id="HDRWQ134">
117     <title>Creating AFS Directories on the Local Disk</title>
118
119     <para>If you are not installing from a packaged distribution, create the <emphasis role="bold">/usr/vice/etc</emphasis> directory on the local disk, to house client binaries and
120     configuration files. Subsequent instructions copy files from the OpenAFS binary distribution into them. Create the <emphasis
121     role="bold">/tmp/afsdist</emphasis> directory as a location to uncompress this distribution, if it does not already exist.</para>
122
123     <programlisting>
124    # <emphasis role="bold">mkdir /usr/vice</emphasis>
125    # <emphasis role="bold">mkdir /usr/vice/etc</emphasis>
126    # <emphasis role="bold">mkdir /tmp/afsdist</emphasis>
127 </programlisting>
128   </sect1>
129
130   <sect1 id="HDRWQ135">
131     <title>Performing Platform-Specific Procedures</title>
132
133     <para>Every AFS client machine's kernel must incorporate AFS modifications. Some system types use a dynamic kernel loader
134     program, whereas on other system types you build AFS modifications into a static kernel. Some system types support both
135     methods.</para>
136
137     <para>Also modify the machine's authentication system so that users obtain an AFS token as they log into the local file system.
138     Using AFS is simpler and more convenient for your users if you make the modifications on all client machines. Otherwise, users
139     must perform a two or three step login procedure (login to the local system, obtain Kerberos credentials, and then issue the <emphasis role="bold">klog</emphasis>
140     command). For further discussion of AFS authentication, see the chapter in the <emphasis>OpenAFS Administration Guide</emphasis>
141     about cell configuration and administration issues.</para>
142
143     <para>For convenience, the following sections group the two procedures by system type. Proceed to the appropriate section.
144     <itemizedlist>
145         <listitem>
146           <para><link linkend="HDRWQ143">Getting Started on Linux Systems</link></para>
147         </listitem>
148
149         <listitem>
150           <para><link linkend="HDRWQ144">Getting Started on Solaris Systems</link></para>
151         </listitem>
152       </itemizedlist>
153
154       <indexterm>
155           <primary>incorporating AFS kernel extensions</primary>
156
157           <secondary>client machine</secondary>
158
159           <tertiary>Linux</tertiary>
160         </indexterm> <indexterm>
161           <primary>AFS kernel extensions</primary>
162
163           <secondary>on client machine</secondary>
164
165           <tertiary>Linux</tertiary>
166         </indexterm> <indexterm>
167           <primary>client machine</primary>
168
169           <secondary>AFS kernel extensions</secondary>
170
171           <tertiary>on Linux</tertiary>
172         </indexterm> <indexterm>
173           <primary>Linux</primary>
174
175           <secondary>AFS kernel extensions</secondary>
176
177           <tertiary>on client machine</tertiary>
178         </indexterm> <indexterm>
179           <primary>enabling AFS login</primary>
180
181           <secondary>client machine</secondary>
182
183           <tertiary>Linux</tertiary>
184         </indexterm> <indexterm>
185           <primary>AFS login</primary>
186
187           <secondary>on client machine</secondary>
188
189           <tertiary>Linux</tertiary>
190         </indexterm> <indexterm>
191           <primary>client machine</primary>
192
193           <secondary>AFS login</secondary>
194
195           <tertiary>on Linux</tertiary>
196         </indexterm> <indexterm>
197           <primary>Linux</primary>
198
199           <secondary>AFS login</secondary>
200
201           <tertiary>on client machine</tertiary>
202         </indexterm> <indexterm>
203           <primary>PAM</primary>
204
205           <secondary>on Linux</secondary>
206
207           <tertiary>client machine</tertiary>
208         </indexterm>
209       </para>
210   </sect1>
211
212   <sect1 id="HDRWQ143">
213     <title>Getting Started on Linux Systems</title>
214
215     <para>In this section you load AFS into the Linux kernel. Then incorporate AFS modifications into the machine's Pluggable
216     Authentication Module (PAM) system, if you wish to enable AFS login.</para>
217
218     <sect2 id="Header_133">
219       <title>Loading AFS into the Linux Kernel</title>
220
221       <para>The <emphasis role="bold">modprobe</emphasis> program is the dynamic kernel loader for Linux. Linux does not support
222       incorporation of AFS modifications during a kernel build.</para>
223
224       <para>For AFS to function correctly, the <emphasis role="bold">modprobe</emphasis> program must run each time the machine
225       reboots, so your distributions's AFS initialization script invokes it automatically. The script also includes
226       commands that select the appropriate AFS library file automatically. In this section you run the script.</para>
227
228       <para>In a later section you also verify that the script correctly initializes the Cache Manager, then activate a
229       configuration variable, which results in the script being incorporated into the Linux startup and shutdown sequence.</para>
230       
231       <para>The procedure for starting up OpenAFS depends upon your distribution</para>
232       <sect3>
233         <title>Fedora and RedHat Enterprise Linux</title>
234         <para>OpenAFS ships RPMS for all current Fedora and RHEL releases.
235         <orderedlist>
236           <listitem>
237             <para>Download and install the RPM set for your operating system.
238             RPMs are available from the OpenAFS web site. You will need the
239             <emphasis role="bold">openafs</emphasis>, <emphasis role="bold">openafs-server</emphasis>, 
240             <emphasis role="bold">openafs-client</emphasis> and
241             <emphasis role="bold">openafs-krb5</emphasis> packages, along
242             with an <emphasis role="bold">kmod-openafs</emphasis> package
243             matching your current, running ,kernel.</para>
244
245             <para>You can find the version of your current kernel by running
246 <programlisting>
247   # uname -r
248 <replaceable>2.6.20-1.2933.fc6</replaceable>
249 </programlisting></para>
250
251             <para>Once downloaded, the packages may be installed with the
252             <emphasis role="bold">rpm</emphasis> command
253 <programlisting>
254   # rpm -U openafs-* openafs-client-* openafs-server-* openafs-krb5-* kmod-openafs-*
255 </programlisting></para>
256           </listitem>
257         </orderedlist>
258       </para>
259       </sect3>
260       <sect3>
261         <title>Systems packaged as tar files</title>
262         <para>If you are running a system where the OpenAFS Binary Distribution
263         is provided as a tar file, or where you have built the system from
264         source yourself, you need to install the relevant components by hand
265         </para>
266         <orderedlist>
267           <listitem>
268             <para>Unpack the distribution tarball. The examples below assume
269             that you have unpacked the files into the
270             <emphasis role="bold">/tmp/afsdist</emphasis>directory. If you
271             pick a different location, substitute this in all of the following
272             examples. Once you have unpacked the distribution,
273             change directory as indicated.
274 <programlisting>
275   # <emphasis role="bold">cd /tmp/afsdist/linux/dest/root.client/usr/vice/etc</emphasis>
276 </programlisting></para>
277           </listitem>
278
279           <listitem>
280             <para>Copy the AFS kernel library files to the local <emphasis role="bold">/usr/vice/etc/modload</emphasis> directory.
281             The filenames for the libraries have the format <emphasis
282             role="bold">libafs-</emphasis><replaceable>version</replaceable><emphasis role="bold">.o</emphasis>, where
283             <replaceable>version</replaceable> indicates the kernel build level. The string <emphasis role="bold">.mp</emphasis> in
284             the <replaceable>version</replaceable> indicates that the file is appropriate for machines running a multiprocessor
285             kernel. <programlisting>
286    # <emphasis role="bold">cp -rp  modload  /usr/vice/etc</emphasis>
287 </programlisting></para>
288           </listitem>
289
290           <listitem>
291             <para>Copy the AFS initialization script to the local directory for initialization files (by convention, <emphasis
292             role="bold">/etc/rc.d/init.d</emphasis> on Linux machines). Note the removal of the <emphasis role="bold">.rc</emphasis>
293             extension as you copy the script. <programlisting>
294    # <emphasis role="bold">cp -p   afs.rc  /etc/rc.d/init.d/afs</emphasis> 
295 </programlisting></para>
296           </listitem>
297
298 <!--
299           <listitem>
300             <para>Run the AFS initialization script to load AFS extensions into the kernel. You can ignore any error messages about
301             the inability to start the BOS Server or the Cache Manager or AFS client. <programlisting>
302    # <emphasis role="bold">/etc/rc.d/init.d/afs  start</emphasis>
303 </programlisting></para>
304           </listitem>
305 -->
306         </orderedlist>
307       </sect3>
308     </sect2>
309
310     <sect2 id="Header_134">
311       <title>Enabling AFS Login on Linux Systems</title>
312
313       <para>At this point you incorporate AFS into the operating system's Pluggable Authentication Module (PAM) scheme. PAM
314       integrates all authentication mechanisms on the machine, including login, to provide the security infrastructure for
315       authenticated access to and from the machine.</para>
316
317       <para>At this time, we recommend that new sites requiring AFS credentials
318       to be gained as part of PAM authentication use Russ Alberry's 
319       pam_afs_session, rather than utilising the bundled pam_afs2 module. 
320       A typical PAM stack should authenticate the user using an external 
321       Kerberos V service, and then use the AFS PAM module to obtain AFS 
322       credentials in the <computeroutput>session</computeroutput> section</para>
323
324       <para>If you are at a site which still requires 
325       <emphasis role="bold">kaserver</emphasis> or external Kerberos v4 based 
326       authentication, please consult 
327       <link linkend="KAS015">Enabling kaserver based AFS Login on Linux Systems</link>
328       for further installation instructions.</para>
329       
330       <para>Proceed to 
331       <link linkend="HDRWQ145">Loading and Creating Client Files</link>.</para>
332
333       <indexterm>
334         <primary>incorporating AFS kernel extensions</primary>
335
336         <secondary>client machine</secondary>
337
338         <tertiary>Solaris</tertiary>
339       </indexterm>
340
341       <indexterm>
342         <primary>AFS kernel extensions</primary>
343
344         <secondary>on client machine</secondary>
345
346         <tertiary>Solaris</tertiary>
347       </indexterm>
348
349       <indexterm>
350         <primary>client machine</primary>
351
352         <secondary>AFS kernel extensions</secondary>
353
354         <tertiary>on Solaris</tertiary>
355       </indexterm>
356
357       <indexterm>
358         <primary>Solaris</primary>
359
360         <secondary>AFS kernel extensions</secondary>
361
362         <tertiary>on client machine</tertiary>
363       </indexterm>
364
365       <indexterm>
366         <primary>enabling AFS login</primary>
367
368         <secondary>client machine</secondary>
369
370         <tertiary>Solaris</tertiary>
371       </indexterm>
372
373       <indexterm>
374         <primary>AFS login</primary>
375
376         <secondary>on client machine</secondary>
377
378         <tertiary>Solaris</tertiary>
379       </indexterm>
380
381       <indexterm>
382         <primary>client machine</primary>
383
384         <secondary>AFS login</secondary>
385
386         <tertiary>on Solaris</tertiary>
387       </indexterm>
388
389       <indexterm>
390         <primary>Solaris</primary>
391
392         <secondary>AFS login</secondary>
393
394         <tertiary>on client machine</tertiary>
395       </indexterm>
396
397       <indexterm>
398         <primary>PAM</primary>
399
400         <secondary>on Solaris</secondary>
401
402         <tertiary>client machine</tertiary>
403       </indexterm>
404
405       <indexterm>
406         <primary>Solaris</primary>
407
408         <secondary>file systems clean-up script</secondary>
409
410         <tertiary>on client machine</tertiary>
411       </indexterm>
412
413       <indexterm>
414         <primary>file systems clean-up script (Solaris)</primary>
415
416         <secondary>client machine</secondary>
417       </indexterm>
418
419       <indexterm>
420         <primary>scripts</primary>
421
422         <secondary>file systems clean-up (Solaris)</secondary>
423
424         <tertiary>client machine</tertiary>
425       </indexterm>
426     </sect2>
427   </sect1>
428
429   <sect1 id="HDRWQ144">
430     <title>Getting Started on Solaris Systems</title>
431
432     <para>In this section you load AFS into the Solaris kernel. Then incorporate AFS modifications into the machine's Pluggable
433     Authentication Module (PAM) system, if you wish to enable AFS login.</para>
434
435     <sect2 id="Header_136">
436       <title>Loading AFS into the Solaris Kernel</title>
437
438       <para>The <emphasis role="bold">modload</emphasis> program is the dynamic kernel loader provided by Sun Microsystems for
439       Solaris systems. Solaris does not support incorporation of AFS modifications during a kernel build.</para>
440
441       <para>For AFS to function correctly, the <emphasis role="bold">modload</emphasis> program must run each time the machine
442       reboots, so the AFS initialization script (included on the AFS CD-ROM) invokes it automatically. In this section you copy the
443       appropriate AFS library file to the location where the <emphasis role="bold">modload</emphasis> program accesses it and then
444       run the script.</para>
445
446       <para>In a later section you verify that the script correctly initializes the Cache Manager, then create the links that
447       incorporate AFS into the Solaris startup and shutdown sequence. <orderedlist>
448           <listitem>
449             <para>Unpack the OpenAFS Solaris distribution tarball. The examples
450             below assume that you have unpacked the files into the 
451             <emphasis role="bold">/tmp/afsdist</emphasis> directory. If you 
452             pick a diferent location, substitute this in all of the following
453             exmaples. Once you have unpacked the distribution, change directory
454             as indicated. 
455 <programlisting>
456    # <emphasis role="bold">cd  /tmp/afsdist/sun4x_56/dest/root.client/usr/vice/etc</emphasis>
457 </programlisting></para>
458           </listitem>          
459
460           <listitem>
461             <para>Copy the AFS initialization script to the local directory for initialization files (by convention, <emphasis
462             role="bold">/etc/init.d</emphasis> on Solaris machines). Note the removal of the <emphasis role="bold">.rc</emphasis>
463             extension as you copy the script. <programlisting>
464    # <emphasis role="bold">cp -p  afs.rc  /etc/init.d/afs</emphasis>
465 </programlisting></para>
466           </listitem>
467
468           <listitem>
469             <para>Copy the appropriate AFS kernel library file to the local file <emphasis
470             role="bold">/kernel/fs/afs</emphasis>.</para>
471
472             <para>If the machine is running Solaris 11 on the x86_64 platform:</para>
473
474             <programlisting>
475    # <emphasis role="bold">cp -p modload/libafs64.o /kernel/drv/amd64/afs</emphasis>
476 </programlisting>
477
478             <para>If the machine is running Solaris 10 on the x86_64 platform:</para>
479
480             <programlisting>
481    # <emphasis role="bold">cp -p modload/libafs64.o /kernel/fs/amd64/afs</emphasis>
482 </programlisting>
483
484             <para>If the machine is running Solaris 2.6 or the 32-bit version of Solaris 7, its kernel supports NFS server
485             functionality, and the <emphasis role="bold">nfsd</emphasis> process is running:</para>
486
487             <programlisting>
488    # <emphasis role="bold">cp -p modload/libafs.o /kernel/fs/afs</emphasis>   
489 </programlisting>
490
491             <para>If the machine is running Solaris 2.6 or the 32-bit version of Solaris 7, and its kernel does not support NFS
492             server functionality or the <emphasis role="bold">nfsd</emphasis> process is not running:</para>
493
494             <programlisting>
495    # <emphasis role="bold">cp -p modload/libafs.nonfs.o /kernel/fs/afs</emphasis>   
496 </programlisting>
497
498             <para>If the machine is running the 64-bit version of Solaris 7, its kernel supports NFS server functionality, and the
499             <emphasis role="bold">nfsd</emphasis> process is running:</para>
500
501             <programlisting>
502    # <emphasis role="bold">cp -p modload/libafs64.o /kernel/fs/sparcv9/afs</emphasis>   
503 </programlisting>
504
505             <para>If the machine is running the 64-bit version of Solaris 7, and its kernel does not support NFS server
506             functionality or the <emphasis role="bold">nfsd</emphasis> process is not running:</para>
507
508             <programlisting>
509    # <emphasis role="bold">cp -p modload/libafs64.nonfs.o /kernel/fs/sparcv9/afs</emphasis>
510 </programlisting>
511           </listitem>
512
513           <listitem>
514             <para>Run the AFS initialization script to load AFS modifications into the kernel. You can ignore any error messages
515             about the inability to start the BOS Server or the Cache Manager or AFS client. <programlisting>
516    # <emphasis role="bold">/etc/init.d/afs start</emphasis>   
517 </programlisting></para>
518
519             <para>When an entry called <computeroutput>afs</computeroutput> does not already exist in the local <emphasis
520             role="bold">/etc/name_to_sysnum</emphasis> file, the script automatically creates it and reboots the machine to start
521             using the new version of the file. If this happens, log in again as the superuser <emphasis role="bold">root</emphasis>
522             after the reboot and run the initialization script again. This time the required entry exists in the <emphasis
523             role="bold">/etc/name_to_sysnum</emphasis> file, and the <emphasis role="bold">modload</emphasis> program runs.</para>
524
525             <programlisting>
526    login: <emphasis role="bold">root</emphasis>
527    Password: <replaceable>root_password</replaceable>
528    # <emphasis role="bold">/etc/init.d/afs start</emphasis>
529 </programlisting>
530           </listitem>
531         </orderedlist></para>
532     </sect2>
533
534     <sect2 id="Header_137">
535       <title>Enabling AFS Login on Solaris Systems</title>
536
537       <para>At this point you incorporate AFS into the operating system's Pluggable Authentication Module (PAM) scheme. PAM
538       integrates all authentication mechanisms on the machine, including login, to provide the security infrastructure for
539       authenticated access to and from the machine.</para>
540
541       <para>In modern AFS installations, you should be using Kerberos v5
542       for user login, and obtaining AFS tokens subsequent to this authentication
543       step. OpenAFS does not currently distribute a PAM module allowing AFS 
544       tokens to be automatically gained at login. Some of these, such as
545       pam-krb5 and pam-afs-session from http://www.eyrie.org/~eagle/software/
546       or pam_afs2 from ftp://achilles.ctd.anl.gov/pub/DEE/pam_afs2-0.1.tar,
547       have been tested with Solaris.</para>
548
549       <para>If you are at a site which still requires 
550       <emphasis role="bold">kaserver</emphasis> or external Kerberos v4 based 
551       authentication, please consult 
552       <link linkend="KAS016">Enabling kaserver based AFS Login on Solaris Systems</link>
553       for further installation instructions.</para>
554     </sect2>
555     <sect2 id="Header_137a">
556       <title>Editing the File Systems Clean-up Script on Solaris Systems</title>
557       <para>
558         <orderedlist>
559           <listitem>
560             <para>Some Solaris distributions include a script that locates 
561             and removes unneeded files from various file systems. Its
562             conventional location is 
563             <emphasis role="bold">/usr/lib/fs/nfs/nfsfind</emphasis>. The 
564             script generally uses an argument to the 
565             <emphasis role="bold">find</emphasis> command to define which file 
566             systems to search. In this step you modify the
567             command to exclude the <emphasis role="bold">/afs</emphasis> 
568             directory. Otherwise, the command traverses the AFS
569             filespace of every cell that is accessible from the machine, which can take many hours. The following alterations are
570             possibilities, but you must verify that they are appropriate for your cell.</para>
571
572             <para>The first possible alteration is to add the <emphasis role="bold">-local</emphasis> flag to the existing command,
573             so that it looks like the following:</para>
574
575             <programlisting>
576    find $dir -local -name .nfs\* -mtime +7 -mount -exec rm -f {} \;   
577 </programlisting>
578
579             <para>Another alternative is to exclude any directories whose names begin with the lowercase letter <emphasis
580             role="bold">a</emphasis> or a non-alphabetic character.</para>
581
582             <programlisting>
583    find /[A-Zb-z]*  <replaceable>remainder of existing command</replaceable>   
584 </programlisting>
585
586             <para>Do not use the following command, which still searches under the <emphasis role="bold">/afs</emphasis> directory,
587             looking for a subdirectory of type <emphasis role="bold">4.2</emphasis>.</para>
588
589             <programlisting>
590    find / -fstype 4.2     /* <replaceable>do not use</replaceable> */
591 </programlisting>
592           </listitem>
593
594           <listitem>
595             <para>Proceed to <link linkend="HDRWQ145">Loading and Creating Client Files</link>.</para>
596           </listitem>
597         </orderedlist></para>
598
599       <indexterm>
600         <primary>Binary Distribution</primary>
601
602         <secondary>copying client files from</secondary>
603
604         <tertiary>client machine</tertiary>
605       </indexterm>
606
607       <indexterm>
608         <primary>client machine</primary>
609
610         <secondary>copying client files to local disk</secondary>
611       </indexterm>
612
613       <indexterm>
614         <primary>copying</primary>
615
616         <secondary>client files to local disk</secondary>
617
618         <tertiary>client machine</tertiary>
619       </indexterm>
620
621       <indexterm>
622         <primary>cell name</primary>
623
624         <secondary>setting in client ThisCell file</secondary>
625
626         <tertiary>client machine</tertiary>
627       </indexterm>
628
629       <indexterm>
630         <primary>setting</primary>
631
632         <secondary>cell name in client ThisCell file</secondary>
633
634         <tertiary>client machine</tertiary>
635       </indexterm>
636
637       <indexterm>
638         <primary>client machine</primary>
639
640         <secondary>cell membership</secondary>
641       </indexterm>
642
643       <indexterm>
644         <primary>client machine</primary>
645
646         <secondary>ThisCell file</secondary>
647       </indexterm>
648
649       <indexterm>
650         <primary>ThisCell file (client)</primary>
651
652         <secondary>client machine</secondary>
653       </indexterm>
654
655       <indexterm>
656         <primary>CellServDB file (client)</primary>
657
658         <secondary>creating</secondary>
659
660         <tertiary>on client machine</tertiary>
661       </indexterm>
662
663       <indexterm>
664         <primary>database server machine</primary>
665
666         <secondary>entry in client CellServDB file</secondary>
667
668         <tertiary>on client machine</tertiary>
669       </indexterm>
670
671       <indexterm>
672         <primary>creating</primary>
673
674         <secondary>CellServDB file (client)</secondary>
675
676         <tertiary>client machine</tertiary>
677       </indexterm>
678
679       <indexterm>
680         <primary>client machine</primary>
681
682         <secondary>CellServDB file</secondary>
683
684         <tertiary>creating during initial installation</tertiary>
685       </indexterm>
686     </sect2>
687   </sect1>
688
689   <sect1 id="HDRWQ145">
690     <title>Loading and Creating Client Files</title>
691
692     <para>If you are using a non-packaged distribution (that is, one provided as
693     a tarball) you should now copy files from the istribution to the 
694     <emphasis role="bold">/usr/vice/etc</emphasis> directory. On some platforms 
695     that use a dynamic loader program to incorporate AFS modifications into the 
696     kernel, you have already copied over some the files.
697     Copying them again does no harm.</para>
698
699     <para>Every AFS client machine has a copy of the <emphasis role="bold">/usr/vice/etc/ThisCell</emphasis> file on its local disk
700     to define the machine's cell membership for the AFS client programs that run on it. Among other functions, this file determines
701     the following: <itemizedlist>
702         <listitem>
703           <para>The cell in which users authenticate when they log onto the machine, assuming it is using an AFS-modified login
704           utility</para>
705         </listitem>
706
707         <listitem>
708           <para>The cell in which users authenticate by default when they issue the <emphasis role="bold">aklog</emphasis>
709           command</para>
710         </listitem>
711
712         <listitem>
713           <para>The cell membership of the AFS server processes that the AFS command interpreters on this machine contact by
714           default</para>
715         </listitem>
716       </itemizedlist></para>
717
718     <para>Similarly, the <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file on a client machine's local disk lists the
719     database server machines in each cell that the local Cache Manager can contact. If there is no entry in the file for a cell, or
720     the list of database server machines is wrong, then users working on this machine cannot access the cell. The chapter in the
721     <emphasis>OpenAFS Administration Guide</emphasis> about administering client machines explains how to maintain the file after
722     creating it. A version of the client <emphasis role="bold">CellServDB</emphasis> file was created during the installation of
723     your cell's first machine (in <link linkend="HDRWQ66">Creating the Client CellServDB File</link>). It is probably also
724     appropriate for use on this machine.</para>
725
726     <para>Remember that the Cache Manager consults the <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file only at
727     reboot, when it copies the information into the kernel. For the Cache Manager to perform properly, the <emphasis
728     role="bold">CellServDB</emphasis> file must be accurate at all times. Refer to the chapter in the <emphasis>OpenAFS
729     Administration Guide</emphasis> about administering client machines for instructions on updating this file, with or without
730     rebooting. <orderedlist>
731         <listitem>
732           <para>If you have not already done so, unpack the distribution 
733           tarball for this machine's system type into a suitable location on 
734           the filesystem, such as <emphasis role="bold">/tmp/afsdist</emphasis>.
735           If you use a different location, substitue that in the examples that 
736           follow.</para>
737         </listitem>
738
739         <listitem>
740           <para>Copy files to the local <emphasis role="bold">/usr/vice/etc</emphasis> directory.</para>
741
742           <para>This step places a copy of the AFS initialization script (and related files, if applicable) into the <emphasis
743           role="bold">/usr/vice/etc</emphasis> directory. In the preceding instructions for incorporating AFS into the kernel, you
744           copied the script directly to the operating system's conventional location for initialization files. When you incorporate
745           AFS into the machine's startup sequence in a later step, you can choose to link the two files.</para>
746
747           <para>On some system types that use a dynamic kernel loader program, you previously copied AFS library files into a
748           subdirectory of the <emphasis role="bold">/usr/vice/etc</emphasis> directory. On other system types, you copied the
749           appropriate AFS library file directly to the directory where the operating system accesses it. The following commands do
750           not copy or recopy the AFS library files into the <emphasis role="bold">/usr/vice/etc</emphasis> directory, because on
751           some system types the library files consume a large amount of space. If you want to copy them, add the <emphasis
752           role="bold">-r</emphasis> flag to the first <emphasis role="bold">cp</emphasis> command and skip the second <emphasis
753           role="bold">cp</emphasis> command.</para>
754
755           <programlisting>
756    # <emphasis role="bold">cd /cdrom/</emphasis><replaceable>sysname</replaceable><emphasis role="bold">/root.client/usr/vice/etc</emphasis>
757    # <emphasis role="bold">cp -p  *  /usr/vice/etc</emphasis>
758    # <emphasis role="bold">cp -rp  C  /usr/vice/etc</emphasis>
759 </programlisting>
760         </listitem>
761
762         <listitem>
763           <para>Create the <emphasis role="bold">/usr/vice/etc/ThisCell</emphasis> file. <programlisting>
764    # <emphasis role="bold">echo "</emphasis><replaceable>cellname</replaceable><emphasis role="bold">" &gt; /usr/vice/etc/ThisCell</emphasis>
765 </programlisting></para>
766         </listitem>
767
768         <listitem>
769           <para>Create the 
770           <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file. Use a 
771           network file transfer program such as 
772           <emphasis role="bold">sftp</emphasis> or 
773           <emphasis role="bold">scp</emphasis> to copy it from one of the 
774           following sources, which are listed in decreasing order of 
775           preference: <itemizedlist>
776               <listitem>
777                 <para>Your cell's central <emphasis role="bold">CellServDB</emphasis> source file (the conventional location is
778                 <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
779                 role="bold">/common/etc/CellServDB</emphasis>)</para>
780               </listitem>
781
782               <listitem>
783                 <para>The global <emphasis role="bold">CellServDB</emphasis> 
784                 file maintained at grand.central.org</para>
785               </listitem>
786
787               <listitem>
788                 <para>An existing client machine in your cell</para>
789               </listitem>
790
791               <listitem>
792                 <para>The <emphasis role="bold">CellServDB.sample</emphasis> 
793                 file included in the
794                 <replaceable>sysname</replaceable><emphasis role="bold">/root.client/usr/vice/etc</emphasis> 
795                 directory of each OpenAFS distribution; add an entry for the 
796                 local cell by following the instructions in 
797                 <link linkend="HDRWQ66">Creating the Client CellServDB File</link>
798                 </para>
799               </listitem>
800             </itemizedlist></para>
801         </listitem>
802       </orderedlist></para>
803
804     <indexterm>
805       <primary>client cache</primary>
806
807       <see>cache</see>
808     </indexterm>
809
810     <indexterm>
811       <primary>AFS cache</primary>
812
813       <see>cache</see>
814     </indexterm>
815
816     <indexterm>
817       <primary>disk cache</primary>
818
819       <see>cache</see>
820     </indexterm>
821
822     <indexterm>
823       <primary>memory cache</primary>
824
825       <see>cache</see>
826     </indexterm>
827
828     <indexterm>
829       <primary>cache</primary>
830
831       <secondary>requirements</secondary>
832     </indexterm>
833
834     <indexterm>
835       <primary>cache</primary>
836
837       <secondary>choosing size</secondary>
838     </indexterm>
839
840     <indexterm>
841       <primary>requirements</primary>
842
843       <secondary>cache</secondary>
844     </indexterm>
845
846     <indexterm>
847       <primary>usr/vice/etc/cacheinfo</primary>
848
849       <see>cacheinfo file</see>
850     </indexterm>
851
852     <indexterm>
853       <primary>cacheinfo file</primary>
854     </indexterm>
855
856     <indexterm>
857       <primary>files</primary>
858
859       <secondary>cacheinfo</secondary>
860     </indexterm>
861
862     <indexterm>
863       <primary>usr/vice/cache directory</primary>
864     </indexterm>
865
866     <indexterm>
867       <primary>directories</primary>
868
869       <secondary>/usr/vice/cache</secondary>
870     </indexterm>
871
872     <indexterm>
873       <primary>cache</primary>
874
875       <secondary>configuring</secondary>
876
877       <tertiary>client machine</tertiary>
878     </indexterm>
879
880     <indexterm>
881       <primary>configuring</primary>
882
883       <secondary>cache</secondary>
884
885       <tertiary>client machine</tertiary>
886     </indexterm>
887
888     <indexterm>
889       <primary>setting</primary>
890
891       <secondary>cache size and location</secondary>
892
893       <tertiary>client machine</tertiary>
894     </indexterm>
895
896     <indexterm>
897       <primary>client machine</primary>
898
899       <secondary>cache size and location</secondary>
900     </indexterm>
901   </sect1>
902
903   <sect1 id="HDRWQ146">
904     <title>Configuring the Cache</title>
905
906     <para>The Cache Manager uses a cache on the local disk or in machine memory to store local copies of files fetched from file
907     server machines. As the <emphasis role="bold">afsd</emphasis> program initializes the Cache Manager, it sets basic cache
908     configuration parameters according to definitions in the local <emphasis role="bold">/usr/vice/etc/cacheinfo</emphasis> file.
909     The file has three fields: <orderedlist>
910         <listitem>
911           <para>The first field names the local directory on which to mount the AFS filespace. The conventional location is the
912           <emphasis role="bold">/afs</emphasis> directory.</para>
913         </listitem>
914
915         <listitem>
916           <para>The second field defines the local disk directory to use for the disk cache. The conventional location is the
917           <emphasis role="bold">/usr/vice/cache</emphasis> directory, but you can specify an alternate directory if another
918           partition has more space available. There must always be a value in this field, but the Cache Manager ignores it if the
919           machine uses a memory cache.</para>
920         </listitem>
921
922         <listitem>
923           <para>The third field specifies the number of kilobyte (1024 byte) blocks to allocate for the cache.</para>
924         </listitem>
925       </orderedlist></para>
926
927     <para>The values you define must meet the following requirements. <itemizedlist>
928         <listitem>
929           <para>On a machine using a disk cache, the Cache Manager expects always to be able to use the amount of space specified in
930           the third field. Failure to meet this requirement can cause serious problems, some of which can be repaired only by
931           rebooting. You must prevent non-AFS processes from filling up the cache partition. The simplest way is to devote a
932           partition to the cache exclusively.</para>
933         </listitem>
934
935         <listitem>
936           <para>The amount of space available in memory or on the partition housing the disk cache directory imposes an absolute
937           limit on cache size.</para>
938         </listitem>
939
940         <listitem>
941           <para>The maximum supported cache size can vary in each AFS release; see the <emphasis>OpenAFS Release Notes</emphasis>
942           for the current version.</para>
943         </listitem>
944
945         <listitem>
946           <para>For a disk cache, you cannot specify a value in the third field that exceeds 95% of the space available on the
947           partition mounted at the directory named in the second field. If you violate this restriction, the <emphasis
948           role="bold">afsd</emphasis> program exits without starting the Cache Manager and prints an appropriate message on the
949           standard output stream. A value of 90% is more appropriate on most machines. Some operating systems do not
950           automatically reserve some space to prevent the partition from filling completely; for them, a smaller value (say, 80% to
951           85% of the space available) is more appropriate.</para>
952         </listitem>
953
954         <listitem>
955           <para>For a memory cache, you must leave enough memory for other processes and applications to run. If you try to allocate
956           more memory than is actually available, the <emphasis role="bold">afsd</emphasis> program exits without initializing the
957           Cache Manager and produces the following message on the standard output stream. <programlisting>
958    afsd: memCache allocation failure at <replaceable>number</replaceable> KB
959 </programlisting></para>
960
961           <para>The <replaceable>number</replaceable> value is how many kilobytes were allocated just before the failure, and so
962           indicates the approximate amount of memory available.</para>
963         </listitem>
964       </itemizedlist></para>
965
966     <para>Within these hard limits, the factors that determine appropriate cache size include the number of users working on the
967     machine, the size of the files with which they work, and (for a memory cache) the number of processes that run on the machine.
968     The higher the demand from these factors, the larger the cache needs to be to maintain good performance.</para>
969
970     <para>Disk caches smaller than 10 MB do not generally perform well. Machines serving multiple users usually perform better with
971     a cache of at least 60 to 70 MB. The point at which enlarging the cache further does not really improve performance depends on
972     the factors mentioned previously and is difficult to predict.</para>
973
974     <para>Memory caches smaller than 1 MB are nonfunctional, and the performance of caches smaller than 5 MB is usually
975     unsatisfactory. Suitable upper limits are similar to those for disk caches but are probably determined more by the demands on
976     memory from other sources on the machine (number of users and processes). Machines running only a few processes possibly can use
977     a smaller memory cache.</para>
978
979     <sect2 id="HDRWQ147">
980       <title>Configuring a Disk Cache</title>
981
982       <note>
983         <para>Not all file system types that an operating system supports are necessarily supported for use as the cache partition.
984         For possible restrictions, see the <emphasis>OpenAFS Release Notes</emphasis>.</para>
985       </note>
986
987       <para>To configure the disk cache, perform the following procedures: <orderedlist>
988           <listitem>
989             <para>Create the local directory to use for caching. The following instruction shows the conventional location,
990             <emphasis role="bold">/usr/vice/cache</emphasis>. If you are devoting a partition exclusively to caching, as
991             recommended, you must also configure it, make a file system on it, and mount it at the directory created in this step.
992             <programlisting>
993    # <emphasis role="bold">mkdir /usr/vice/cache</emphasis>
994 </programlisting></para>
995           </listitem>
996
997           <listitem>
998             <para>Create the <emphasis role="bold">cacheinfo</emphasis> file to define the configuration parameters discussed
999             previously. The following instruction shows the standard mount location, <emphasis role="bold">/afs</emphasis>, and the
1000             standard cache location, <emphasis role="bold">/usr/vice/cache</emphasis>. <programlisting>
1001    # <emphasis role="bold">echo "/afs:/usr/vice/cache:</emphasis><replaceable>#blocks</replaceable><emphasis role="bold">" &gt; /usr/vice/etc/cacheinfo</emphasis>
1002 </programlisting></para>
1003
1004             <para>The following example defines the disk cache size as 50,000 KB:</para>
1005
1006             <programlisting>
1007    # <emphasis role="bold">echo "/afs:/usr/vice/cache:50000" &gt; /usr/vice/etc/cacheinfo</emphasis>
1008 </programlisting>
1009           </listitem>
1010         </orderedlist></para>
1011     </sect2>
1012
1013     <sect2 id="HDRWQ148">
1014       <title>Configuring a Memory Cache</title>
1015
1016       <para>To configure a memory cache, create the <emphasis role="bold">cacheinfo</emphasis> file to define the configuration
1017       parameters discussed previously. The following instruction shows the standard mount location, <emphasis
1018       role="bold">/afs</emphasis>, and the standard cache location, <emphasis role="bold">/usr/vice/cache</emphasis> (though the
1019       exact value of the latter is irrelevant for a memory cache).</para>
1020
1021       <programlisting>
1022    # <emphasis role="bold">echo "/afs:/usr/vice/cache:</emphasis><replaceable>#blocks</replaceable><emphasis role="bold">" &gt; /usr/vice/etc/cacheinfo</emphasis>
1023 </programlisting>
1024
1025       <para>The following example allocates 25,000 KB of memory for the cache.</para>
1026
1027       <programlisting>
1028    # <emphasis role="bold">echo "/afs:/usr/vice/cache:25000" &gt; /usr/vice/etc/cacheinfo</emphasis>
1029 </programlisting>
1030
1031       <indexterm>
1032         <primary>afs (/afs) directory</primary>
1033
1034         <secondary>creating</secondary>
1035
1036         <tertiary>client machine</tertiary>
1037       </indexterm>
1038
1039       <indexterm>
1040         <primary>afs (/afs) directory</primary>
1041
1042         <secondary>as root of AFS filespace</secondary>
1043       </indexterm>
1044
1045       <indexterm>
1046         <primary>AFS filespace</primary>
1047
1048         <secondary>root at /afs directory</secondary>
1049       </indexterm>
1050
1051       <indexterm>
1052         <primary>directories</primary>
1053
1054         <secondary>/afs</secondary>
1055       </indexterm>
1056
1057       <indexterm>
1058         <primary>afsd</primary>
1059
1060         <secondary>options file (Linux)</secondary>
1061       </indexterm>
1062
1063       <indexterm>
1064         <primary>files</primary>
1065
1066         <secondary>afsd options file (Linux)</secondary>
1067       </indexterm>
1068
1069       <indexterm>
1070         <primary>files</primary>
1071
1072         <secondary>afs</secondary>
1073
1074         <tertiary>afsd options file (Linux)</tertiary>
1075       </indexterm>
1076
1077       <indexterm>
1078         <primary>afs file</primary>
1079
1080         <secondary>afsd options file (Linux)</secondary>
1081       </indexterm>
1082
1083       <indexterm>
1084         <primary>etc/sysconfig/afs</primary>
1085
1086         <see>afs file</see>
1087       </indexterm>
1088
1089       <indexterm>
1090         <primary>Linux</primary>
1091
1092         <secondary>afsd options file</secondary>
1093       </indexterm>
1094
1095       <indexterm>
1096         <primary>client machine</primary>
1097
1098         <secondary>afsd options file (Linux)</secondary>
1099       </indexterm>
1100
1101       <indexterm>
1102         <primary>afsd</primary>
1103
1104         <secondary>command in AFS init. script</secondary>
1105       </indexterm>
1106
1107       <indexterm>
1108         <primary>commands</primary>
1109
1110         <secondary>afsd</secondary>
1111       </indexterm>
1112
1113       <indexterm>
1114         <primary>OPTIONS variable in AFS initialization file</primary>
1115       </indexterm>
1116
1117       <indexterm>
1118         <primary>files</primary>
1119
1120         <secondary>AFS initialization</secondary>
1121
1122         <see>AFS initialization script</see>
1123       </indexterm>
1124
1125       <indexterm>
1126         <primary>scripts</primary>
1127
1128         <secondary>AFS initialization</secondary>
1129
1130         <see>AFS initialization script</see>
1131       </indexterm>
1132
1133       <indexterm>
1134         <primary>AFS initialization script</primary>
1135
1136         <secondary>setting afsd parameters</secondary>
1137
1138         <tertiary>client machine</tertiary>
1139       </indexterm>
1140
1141       <indexterm>
1142         <primary>client machine</primary>
1143
1144         <secondary>afsd command parameters</secondary>
1145       </indexterm>
1146
1147       <indexterm>
1148         <primary>variables</primary>
1149
1150         <secondary>OPTIONS (in AFS initialization file)</secondary>
1151       </indexterm>
1152
1153       <indexterm>
1154         <primary>environment variables</primary>
1155
1156         <see>variables</see>
1157       </indexterm>
1158
1159       <indexterm>
1160         <primary>Cache Manager</primary>
1161
1162         <secondary>client machine</secondary>
1163       </indexterm>
1164
1165       <indexterm>
1166         <primary>configuring</primary>
1167
1168         <secondary>Cache Manager</secondary>
1169
1170         <tertiary>client machine</tertiary>
1171       </indexterm>
1172
1173       <indexterm>
1174         <primary>client machine</primary>
1175
1176         <secondary>Cache Manager</secondary>
1177       </indexterm>
1178
1179     </sect2>
1180   </sect1>
1181
1182   <sect1 id="HDRWQ149">
1183     <title>Configuring the Cache Manager</title>
1184
1185     <para>By convention, the Cache Manager mounts the AFS filespace on the local <emphasis role="bold">/afs</emphasis> directory. In
1186     this section you create that directory.</para>
1187
1188     <para>The <emphasis role="bold">afsd</emphasis> program sets several cache configuration parameters as it initializes the Cache
1189     Manager, and starts daemons that improve performance. You can use the <emphasis role="bold">afsd</emphasis> command's arguments
1190     to override the parameters' default values and to change the number of some of the daemons. Depending on the machine's cache
1191     size, its amount of RAM, and how many people work on it, you can sometimes improve Cache Manager performance by overriding the
1192     default values. For a discussion of all of the <emphasis role="bold">afsd</emphasis> command's arguments, see its reference page
1193     in the <emphasis>OpenAFS Administration Reference</emphasis>.</para>
1194
1195     <para>On platforms using the standard 'afs' initialisation script (this does
1196     not apply to Fedora or RHEL based distributions), the 
1197     <emphasis role="bold">afsd</emphasis> command line in the AFS 
1198     initialization script on each system type includes an
1199     <computeroutput>OPTIONS</computeroutput> variable. You can use it to set 
1200     nondefault values for the command's arguments, in one
1201     of the following ways: <itemizedlist>
1202         <listitem>
1203           <para>You can create an <emphasis role="bold">afsd</emphasis> <emphasis>options file</emphasis> that sets values for
1204           arguments to the <emphasis role="bold">afsd</emphasis> command. If the file exists, its contents are automatically
1205           substituted for the <computeroutput>OPTIONS</computeroutput> variable in the AFS initialization script. The AFS
1206           distribution for some system types includes an options file; on other system types, you must create it.</para>
1207
1208           <para>You use two variables in the AFS initialization script to specify the path to the options file:
1209           <computeroutput>CONFIG</computeroutput> and <computeroutput>AFSDOPT</computeroutput>. On system types that define a
1210           conventional directory for configuration files, the <computeroutput>CONFIG</computeroutput> variable indicates it by
1211           default; otherwise, the variable indicates an appropriate location.</para>
1212
1213           <para>List the desired <emphasis role="bold">afsd</emphasis> options on a single line in the options file, separating each
1214           option with one or more spaces. The following example sets the <emphasis role="bold">-stat</emphasis> argument to 2500,
1215           the <emphasis role="bold">-daemons</emphasis> argument to 4, and the <emphasis role="bold">-volumes</emphasis> argument to
1216           100.</para>
1217
1218           <programlisting>
1219    -stat 2500 -daemons 4 -volumes 100   
1220 </programlisting>
1221         </listitem>
1222
1223         <listitem>
1224           <para>On a machine that uses a disk cache, you can set the <computeroutput>OPTIONS</computeroutput> variable in the AFS
1225           initialization script to one of <computeroutput>$SMALL</computeroutput>, <computeroutput>$MEDIUM</computeroutput>, or
1226           <computeroutput>$LARGE</computeroutput>. The AFS initialization script uses one of these settings if the <emphasis
1227           role="bold">afsd</emphasis> options file named by the <computeroutput>AFSDOPT</computeroutput> variable does not exist. In
1228           the script as distributed, the <computeroutput>OPTIONS</computeroutput> variable is set to the value
1229           <computeroutput>$MEDIUM</computeroutput>.</para>
1230
1231           <note>
1232             <para>Do not set the <computeroutput>OPTIONS</computeroutput> variable to <computeroutput>$SMALL</computeroutput>,
1233             <computeroutput>$MEDIUM</computeroutput>, or <computeroutput>$LARGE</computeroutput> on a machine that uses a memory
1234             cache. The arguments it sets are appropriate only on a machine that uses a disk cache.</para>
1235           </note>
1236
1237           <para>The script (or on some system types the <emphasis role="bold">afsd</emphasis> options file named by the
1238           <computeroutput>AFSDOPT</computeroutput> variable) defines a value for each of <computeroutput>SMALL</computeroutput>,
1239           <computeroutput>MEDIUM</computeroutput>, and <computeroutput>LARGE</computeroutput> that sets <emphasis
1240           role="bold">afsd</emphasis> command arguments appropriately for client machines of different sizes: <itemizedlist>
1241               <listitem>
1242                 <para><computeroutput>SMALL</computeroutput> is suitable for a small machine that serves one or two users and has
1243                 approximately 8 MB of RAM and a 20-MB cache</para>
1244               </listitem>
1245
1246               <listitem>
1247                 <para><computeroutput>MEDIUM</computeroutput> is suitable for a medium-sized machine that serves two to six users
1248                 and has 16 MB of RAM and a 40-MB cache</para>
1249               </listitem>
1250
1251               <listitem>
1252                 <para><computeroutput>LARGE</computeroutput> is suitable for a large machine that serves five to ten users and has
1253                 32 MB of RAM and a 100-MB cache</para>
1254               </listitem>
1255             </itemizedlist></para>
1256         </listitem>
1257
1258         <listitem>
1259           <para>You can choose not to create an <emphasis role="bold">afsd</emphasis> options file and to set the
1260           <computeroutput>OPTIONS</computeroutput> variable in the initialization script to a null value rather than to the default
1261           <computeroutput>$MEDIUM</computeroutput> value. You can then either set arguments directly on the <emphasis
1262           role="bold">afsd</emphasis> command line in the script, or set no arguments (and so accept default values for all Cache
1263           Manager parameters).</para>
1264         </listitem>
1265       </itemizedlist>
1266       
1267       <note>
1268         <para>If you are running on a Fedora or RHEL based system, the 
1269         openafs-client initialization script behaves differently from that
1270         described above. It sources 
1271         <emphasis role="bold">/etc/sysconfig/openafs</emphasis>, in which the
1272         AFSD_ARGS variable may be set to contain any, or all, of the afsd 
1273         options detailed above. Note that this script does not support setting
1274         an <computeroutput>OPTIONS</computeroutput> variable, or the 
1275         <computeroutput>SMALL</computeroutput>,
1276         <computeroutput>MEDIUM</computeroutput> and
1277         <computeroutput>LARGE</computeroutput> methods of defining cache size.
1278         </para>
1279       </note>
1280       
1281       <orderedlist>
1282         <listitem>
1283           <para>Create the local directory on which to mount the AFS filespace, by convention <emphasis role="bold">/afs</emphasis>.
1284           If the directory already exists, verify that it is empty. <programlisting>
1285    # <emphasis role="bold">mkdir /afs</emphasis>
1286 </programlisting></para>
1287         </listitem>
1288
1289         <listitem>
1290           <para>On non-package based Linux systems, copy the <emphasis role="bold">afsd</emphasis> options file from the <emphasis
1291           role="bold">/usr/vice/etc</emphasis> directory to the <emphasis role="bold">/etc/sysconfig</emphasis> directory, removing
1292           the <emphasis role="bold">.conf</emphasis> extension as you do so. <programlisting>
1293    # <emphasis role="bold">cp /usr/vice/etc/afs.conf /etc/sysconfig/afs</emphasis>
1294 </programlisting></para>
1295         </listitem>
1296
1297         <listitem>
1298           <para>Edit the machine's AFS initialization script or <emphasis role="bold">afsd</emphasis> options file to set
1299           appropriate values for <emphasis role="bold">afsd</emphasis> command parameters. The appropriate file for each system type
1300           is as follows: <itemizedlist>
1301               <listitem>
1302                 <para>On Fedora and RHEL systems, <emphasis role="bold">/etc/sysconfig/openafs</emphasis></para>
1303               </listitem>
1304               
1305               <listitem>
1306                 <para>On Linux systems, <emphasis role="bold">/etc/sysconfig/afs</emphasis> (the <emphasis
1307                 role="bold">afsd</emphasis> options file)</para>
1308               </listitem>
1309
1310               <listitem>
1311                 <para>On Solaris systems, <emphasis role="bold">/etc/init.d/afs</emphasis></para>
1312               </listitem>
1313             </itemizedlist></para>
1314
1315           <para>Use one of the methods described in the introduction to this section to add the following flags to the <emphasis
1316           role="bold">afsd</emphasis> command line. Also set any performance-related arguments you wish. <itemizedlist>
1317               <listitem>
1318                 <para>Add the <emphasis role="bold">-memcache</emphasis> flag if the machine is to use a memory cache.</para>
1319               </listitem>
1320
1321               <listitem>
1322                 <para>Add the <emphasis role="bold">-verbose</emphasis> flag to display a trace of the Cache Manager's
1323                 initialization on the standard output stream.</para>
1324               </listitem>
1325             </itemizedlist></para>
1326         </listitem>
1327       </orderedlist></para>
1328
1329     <indexterm>
1330       <primary>AFS initialization script</primary>
1331
1332       <secondary>running</secondary>
1333
1334       <tertiary>client machine</tertiary>
1335     </indexterm>
1336
1337     <indexterm>
1338       <primary>client machine</primary>
1339
1340       <secondary>AFS initialization script</secondary>
1341     </indexterm>
1342
1343     <indexterm>
1344       <primary>running AFS init. script</primary>
1345
1346       <secondary>client machine</secondary>
1347     </indexterm>
1348
1349     <indexterm>
1350       <primary>installing</primary>
1351
1352       <secondary>AFS initialization script</secondary>
1353
1354       <tertiary>client machine</tertiary>
1355     </indexterm>
1356
1357     <indexterm>
1358       <primary>AFS initialization script</primary>
1359
1360       <secondary>adding to machine startup sequence</secondary>
1361
1362       <tertiary>client machine</tertiary>
1363     </indexterm>
1364   </sect1>
1365
1366   <sect1 id="HDRWQ150">
1367     <title>Starting the Cache Manager and Installing the AFS Initialization Script</title>
1368
1369     <para>In this section you run the AFS initialization script to start the Cache Manager. If the script works correctly, perform
1370     the steps that incorporate it into the machine's startup and shutdown sequence. If there are problems during the initialization,
1371     attempt to resolve them. The AFS Product Support group can provide assistance if necessary.</para>
1372
1373     <para>On machines that use a disk cache, it can take a while for the <emphasis role="bold">afsd</emphasis> program to run the
1374     first time on a machine, because it must create all of the <emphasis role="bold">V</emphasis><replaceable>n</replaceable> files
1375     in the cache directory. Subsequent Cache Manager initializations do not take nearly as long, because the <emphasis
1376     role="bold">V</emphasis><replaceable>n</replaceable> files already exist.</para>
1377
1378     <para>On system types that use a dynamic loader program, you must reboot the machine before running the initialization script,
1379     so that it can freshly load AFS modifications into the kernel.</para>
1380
1381     <para>Proceed to the instructions for your system type:</para>
1382
1383     <itemizedlist>
1384       <listitem>
1385         <para><link linkend="HDRWQ155">Running the Script on Linux Systems</link></para>
1386       </listitem>
1387
1388       <listitem>
1389         <para><link linkend="HDRWQ156">Running the Script on Solaris Systems</link></para>
1390       </listitem>
1391     </itemizedlist>
1392
1393       <indexterm>
1394         <primary>afs file</primary>
1395
1396         <secondary>AFS initialization file</secondary>
1397       </indexterm>
1398
1399       <indexterm>
1400         <primary>files</primary>
1401
1402         <secondary>afs</secondary>
1403
1404         <tertiary>AFS initialization file</tertiary>
1405       </indexterm>
1406
1407       <indexterm>
1408         <primary>etc/rc.d/init.d/afs</primary>
1409
1410         <see>afs file</see>
1411       </indexterm>
1412
1413       <indexterm>
1414         <primary>Linux</primary>
1415
1416         <secondary>AFS initialization script</secondary>
1417
1418         <tertiary>on client machine</tertiary>
1419       </indexterm>
1420
1421     <sect2>
1422       <title>Running the Script on Fedora / RHEL Systems</title>
1423
1424       <orderedlist>
1425         <listitem>
1426           <para>Reboot the machine and log in again as the local superuser <emphasis role="bold">root</emphasis>. <programlisting>
1427    # <emphasis role="bold">cd /</emphasis>
1428    # <emphasis role="bold">shutdown -r now</emphasis>
1429    login: <emphasis role="bold">root</emphasis>
1430    Password: <replaceable>root_password</replaceable>
1431 </programlisting></para>
1432         </listitem>
1433
1434         <listitem>
1435           <para>Run the AFS initialization script. 
1436 <programlisting>
1437    # <emphasis role="bold">/etc/rc.d/init.d/openafs-client  start</emphasis>
1438 </programlisting></para>
1439         </listitem>
1440
1441         <listitem>
1442           <para>Issue the <emphasis role="bold">chkconfig</emphasis> command to activate the <emphasis role="bold">openafs-client</emphasis>
1443           configuration variable. Based on the instruction in the AFS initialization file that begins with the string
1444           <computeroutput>#chkconfig</computeroutput>, the command automatically creates the symbolic links that incorporate the
1445           script into the Linux startup and shutdown sequence. <programlisting>
1446    # <emphasis role="bold">/sbin/chkconfig  --add openafs-client</emphasis>
1447 </programlisting></para>
1448         </listitem>
1449       </orderedlist>
1450     </sect2>
1451       
1452     <sect2 id="HDRWQ155">
1453       <title>Running the Script on other Linux Systems</title>
1454
1455       <orderedlist>
1456         <listitem>
1457           <para>Reboot the machine and log in again as the local superuser <emphasis role="bold">root</emphasis>. <programlisting>
1458    # <emphasis role="bold">cd /</emphasis>
1459    # <emphasis role="bold">shutdown -r now</emphasis>
1460    login: <emphasis role="bold">root</emphasis>
1461    Password: <replaceable>root_password</replaceable>
1462 </programlisting></para>
1463         </listitem>
1464
1465         <listitem>
1466           <para>Run the AFS initialization script. <programlisting>
1467    # <emphasis role="bold">/etc/rc.d/init.d/afs  start</emphasis>
1468 </programlisting></para>
1469         </listitem>
1470
1471         <listitem>
1472           <para>Issue the <emphasis role="bold">chkconfig</emphasis> command to activate the <emphasis role="bold">afs</emphasis>
1473           configuration variable. Based on the instruction in the AFS initialization file that begins with the string
1474           <computeroutput>#chkconfig</computeroutput>, the command automatically creates the symbolic links that incorporate the
1475           script into the Linux startup and shutdown sequence. <programlisting>
1476    # <emphasis role="bold">/sbin/chkconfig  --add afs</emphasis>
1477 </programlisting></para>
1478         </listitem>
1479
1480         <listitem>
1481           <para><emphasis role="bold">(Optional)</emphasis> There are now copies of the AFS initialization file in both the
1482           <emphasis role="bold">/usr/vice/etc</emphasis> and <emphasis role="bold">/etc/rc.d/init.d</emphasis> directories, and
1483           copies of the <emphasis role="bold">afsd</emphasis> options file in both the <emphasis
1484           role="bold">/usr/vice/etc</emphasis> and <emphasis role="bold">/etc/sysconfig</emphasis> directories. If you want to avoid
1485           potential confusion by guaranteeing that the two copies of each file are always the same, create a link between them. You
1486           can always retrieve the original script or options file from the AFS CD-ROM if necessary. <programlisting>
1487    # <emphasis role="bold">cd /usr/vice/etc</emphasis>
1488    # <emphasis role="bold">rm afs.rc afs.conf</emphasis>
1489    # <emphasis role="bold">ln -s  /etc/rc.d/init.d/afs  afs.rc</emphasis>
1490    # <emphasis role="bold">ln -s  /etc/sysconfig/afs  afs.conf</emphasis>
1491 </programlisting></para>
1492         </listitem>
1493
1494         <listitem>
1495           <para>If a volume for housing AFS binaries for this machine's system type does not already exist, proceed to <link
1496           linkend="HDRWQ157">Setting Up Volumes and Loading Binaries into AFS</link>. Otherwise, the installation is
1497           complete.</para>
1498         </listitem>
1499       </orderedlist>
1500
1501       <indexterm>
1502         <primary>afs file</primary>
1503
1504         <secondary>AFS initialization file</secondary>
1505       </indexterm>
1506
1507       <indexterm>
1508         <primary>files</primary>
1509
1510         <secondary>afs</secondary>
1511
1512         <tertiary>AFS initialization file</tertiary>
1513       </indexterm>
1514
1515       <indexterm>
1516         <primary>Solaris</primary>
1517
1518         <secondary>AFS initialization script</secondary>
1519
1520         <tertiary>on client machine</tertiary>
1521       </indexterm>
1522     </sect2>
1523
1524     <sect2 id="HDRWQ156">
1525       <title>Running the Script on Solaris Systems</title>
1526
1527       <orderedlist>
1528         <listitem>
1529           <para>Reboot the machine and log in again as the local superuser <emphasis role="bold">root</emphasis>. <programlisting>
1530    # <emphasis role="bold">cd /</emphasis>
1531    # <emphasis role="bold">shutdown -i6 -g0 -y</emphasis>
1532    login: <emphasis role="bold">root</emphasis>
1533    Password: <replaceable>root_password</replaceable>
1534 </programlisting></para>
1535         </listitem>
1536
1537         <listitem>
1538           <para>Run the AFS initialization script. <programlisting>
1539    # <emphasis role="bold">/etc/init.d/afs  start</emphasis>
1540 </programlisting></para>
1541         </listitem>
1542
1543         <listitem>
1544           <para>Change to the <emphasis role="bold">/etc/init.d</emphasis> directory and issue the <emphasis role="bold">ln
1545           -s</emphasis> command to create symbolic links that incorporate the AFS initialization script into the Solaris startup and
1546           shutdown sequence. <programlisting>
1547    # <emphasis role="bold">cd /etc/init.d</emphasis>
1548    # <emphasis role="bold">ln -s ../init.d/afs /etc/rc3.d/S99afs</emphasis>
1549    # <emphasis role="bold">ln -s ../init.d/afs /etc/rc0.d/K66afs</emphasis>
1550 </programlisting></para>
1551         </listitem>
1552
1553         <listitem>
1554           <para><emphasis role="bold">(Optional)</emphasis> There are now copies of the AFS initialization file in both the
1555           <emphasis role="bold">/usr/vice/etc</emphasis> and <emphasis role="bold">/etc/init.d</emphasis> directories. If you want
1556           to avoid potential confusion by guaranteeing that they are always the same, create a link between them. You can always
1557           retrieve the original script from the OpenAFS Binary Distribution if necessary. <programlisting>
1558    # <emphasis role="bold">cd /usr/vice/etc</emphasis>
1559    # <emphasis role="bold">rm afs.rc</emphasis>
1560    # <emphasis role="bold">ln -s  /etc/init.d/afs  afs.rc</emphasis>
1561 </programlisting></para>
1562         </listitem>
1563
1564         <listitem>
1565           <para>If a volume for housing AFS binaries for this machine's system type does not already exist, proceed to <link
1566           linkend="HDRWQ157">Setting Up Volumes and Loading Binaries into AFS</link>. Otherwise, the installation is
1567           complete.</para>
1568         </listitem>
1569       </orderedlist>
1570
1571       <indexterm>
1572         <primary>storing</primary>
1573
1574         <secondary>AFS binaries in volumes</secondary>
1575       </indexterm>
1576
1577       <indexterm>
1578         <primary>creating</primary>
1579
1580         <secondary>volume</secondary>
1581
1582         <tertiary>for AFS binaries</tertiary>
1583       </indexterm>
1584
1585       <indexterm>
1586         <primary>volume</primary>
1587
1588         <secondary>for AFS binaries</secondary>
1589       </indexterm>
1590
1591       <indexterm>
1592         <primary>binaries</primary>
1593
1594         <secondary>storing AFS in volume</secondary>
1595       </indexterm>
1596
1597       <indexterm>
1598         <primary>usr/afsws directory</primary>
1599       </indexterm>
1600
1601       <indexterm>
1602         <primary>directories</primary>
1603
1604         <secondary>/usr/afsws</secondary>
1605       </indexterm>
1606     </sect2>
1607   </sect1>
1608
1609   <sect1 id="HDRWQ157">
1610     <title>Setting Up Volumes and Loading Binaries into AFS</title>
1611
1612     <note><para>If you are using an operating system which uses packaged
1613     binaries, such as .rpms or .debs, you should allow these package management
1614     systems to maintain your AFS binaries, rather than following the 
1615     instructions in this section.</para></note>
1616     
1617     <para>In this section, you link <emphasis role="bold">/usr/afsws</emphasis> on the local disk to the directory in AFS that
1618     houses AFS binaries for this system type. The conventional name for the AFS directory is <emphasis
1619     role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1620     role="bold">/</emphasis><replaceable>sysname</replaceable><emphasis role="bold">/usr/afsws</emphasis>.</para>
1621
1622     <para>If this machine is an existing system type, the AFS directory presumably already exists. You can simply create a link from
1623     the local <emphasis role="bold">/usr/afsws</emphasis> directory to it. Follow the instructions in <link
1624     linkend="HDRWQ158">Linking /usr/afsws on an Existing System Type</link>.</para>
1625
1626     <para>If this machine is a new system type (there are no AFS machines of this type in your cell), you must first create and
1627     mount volumes to store its AFS binaries, and then create the link from <emphasis role="bold">/usr/afsws</emphasis> to the new
1628     directory. See <link linkend="HDRWQ159">Creating Binary Volumes for a New System Type</link>.</para>
1629
1630     <para>You can also store UNIX system binaries (the files normally stored in local disk directories such as <emphasis
1631     role="bold">/bin</emphasis>, <emphasis role="bold">/etc</emphasis>, and <emphasis role="bold">/lib</emphasis>) in volumes
1632     mounted under <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1633     role="bold">/</emphasis><replaceable>sysname</replaceable>. See <link linkend="HDRWQ88">Storing System Binaries in AFS</link>
1634     .</para>
1635
1636     <sect2 id="HDRWQ158">
1637       <title>Linking /usr/afsws on an Existing System Type</title>
1638
1639       <para>If this client machine is an existing system type, there is already a volume mounted in the AFS filespace that houses
1640       AFS client binaries for it. <orderedlist>
1641           <listitem>
1642             <para>Create <emphasis role="bold">/usr/afsws</emphasis> on the local disk as a symbolic link to the directory <emphasis
1643             role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/@sys/usr/afsws</emphasis>. You can
1644             specify the actual system name instead of <emphasis role="bold">@sys</emphasis> if you wish, but the advantage of using
1645             <emphasis role="bold">@sys</emphasis> is that it remains valid if you upgrade this machine to a different system type.
1646             <programlisting>
1647    # <emphasis role="bold">ln -s /afs/</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/@sys/usr/afsws  /usr/afsws</emphasis>
1648 </programlisting></para>
1649           </listitem>
1650
1651           <listitem>
1652             <para><emphasis role="bold">(Optional)</emphasis> If you believe it is helpful to your users to access the AFS documents
1653             in a certain format via a local disk directory, create <emphasis role="bold">/usr/afsdoc</emphasis> on the local disk as
1654             a symbolic link to the documentation directory in AFS (<emphasis
1655             role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1656             role="bold">/afsdoc/</emphasis><replaceable>format_name</replaceable>). <programlisting>
1657    # <emphasis role="bold">ln -s /afs/</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/afsdoc/</emphasis><replaceable>format_name</replaceable> <emphasis
1658                   role="bold">/usr/afsdoc</emphasis>
1659 </programlisting></para>
1660
1661             <para>An alternative is to create a link in each user's home directory to the <emphasis
1662             role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1663             role="bold">/afsdoc/</emphasis><replaceable>format_name</replaceable> directory.</para>
1664           </listitem>
1665         </orderedlist></para>
1666     </sect2>
1667
1668     <sect2 id="HDRWQ159">
1669       <title>Creating Binary Volumes for a New System Type</title>
1670
1671       <para>If this client machine is a new system type, you must create and mount volumes for its binaries before you can link the
1672       local <emphasis role="bold">/usr/afsws</emphasis> directory to an AFS directory.</para>
1673
1674       <para>To create and mount the volumes, you use the 
1675       <emphasis role="bold">kinit</emphasis> command to authenticate as an
1676       administrator, followed by the <emphasis role="bold">aklog</emphasis> 
1677       command to gain tokens, and then issue commands from the 
1678       <emphasis role="bold">vos</emphasis> and 
1679       <emphasis role="bold">fs</emphasis> command suites. However, the 
1680       command binaries are not yet available on this machine (by convention, 
1681       they are accessible via the <emphasis role="bold">/usr/afsws</emphasis> 
1682       link that you are about to create). You have two choices: 
1683       <itemizedlist>
1684           <listitem>
1685             <para>Perform all steps except the last one (Step <link linkend="LIWQ162">10</link>) on an existing AFS machine. On a
1686             file server machine, the <emphasis role="bold">aklog</emphasis>, <emphasis role="bold">fs</emphasis> and <emphasis
1687             role="bold">vos</emphasis> binaries reside in the <emphasis role="bold">/usr/afs/bin</emphasis> directory. On client
1688             machines, the <emphasis role="bold">aklog</emphasis> and <emphasis role="bold">fs</emphasis> binaries reside in the
1689             <emphasis role="bold">/usr/afsws/bin</emphasis> directory and the <emphasis role="bold">vos</emphasis> binary in the
1690             <emphasis role="bold">/usr/afsws/etc</emphasis> directory. Depending on how your PATH environment variable is set, you
1691             possibly need to precede the command names with a pathname.</para>
1692
1693             <para>If you work on another AFS machine, be sure to substitute the new system type name for the
1694             <replaceable>sysname</replaceable> argument in the following commands, not the system type of the machine on which you
1695             are issuing the commands.</para>
1696           </listitem>
1697
1698           <listitem>
1699             <para>Copy the necessary command binaries to a temporary location on the local disk, which enables you to perform the
1700             steps on the local machine. The following procedure installs them in the <emphasis role="bold">/tmp</emphasis> directory
1701             and removes them at the end. Depending on how your PATH environment variable is set, you possibly need to precede the
1702             command names with a pathname.</para>
1703           </listitem>
1704         </itemizedlist></para>
1705
1706       <para>Perform the following steps to create a volume for housing AFS binaries. <orderedlist>
1707           <listitem>
1708             <para>Working either on the local machine or another AFS machine, 
1709             extract the Open AFS distribtion tarball onto a directory on that 
1710             machine. The following instructions assume that you are using the
1711             <emphasis role="bold">/tmp/afsdist</emphasis> directory.</para>
1712           </listitem>
1713
1714           <listitem>
1715             <para>If working on the local machine, copy the necessary binaries to a temporary location on the local disk. Substitute
1716             a different directory name for <emphasis role="bold">/tmp</emphasis> if you wish. <programlisting>
1717    # <emphasis role="bold">cd  /tmp/afsdist/</emphasis><replaceable>new_sysname</replaceable><emphasis role="bold">/root.server/usr/afs/bin</emphasis>
1718    # <emphasis role="bold">cp -p  aklog  /tmp</emphasis>
1719    # <emphasis role="bold">cp -p  fs  /tmp</emphasis>
1720    # <emphasis role="bold">cp -p  vos  /tmp</emphasis>
1721 </programlisting></para>
1722           </listitem>
1723
1724           <listitem>
1725             <para>Authenticate as the user <emphasis role="bold">admin</emphasis>. 
1726 <programlisting>
1727    # <emphasis role="bold">kinit admin</emphasis>
1728    Password: <replaceable>admin_password</replaceable>
1729    # <emphasis role="bold">aklog</emphasis>
1730 </programlisting></para>
1731           </listitem>
1732
1733           <listitem id="LIWQ160">
1734             <para>Issue the <emphasis role="bold">vos create</emphasis> command to create volumes for storing
1735             the AFS client binaries for this system type. The following example instruction creates volumes called
1736             <replaceable>sysname</replaceable>, <replaceable>sysname</replaceable>.<emphasis role="bold">usr</emphasis>, and
1737             <replaceable>sysname</replaceable>.<emphasis role="bold">usr.afsws</emphasis>. Refer to the <emphasis>OpenAFS Release
1738             Notes</emphasis> to learn the proper value of <replaceable>sysname</replaceable> for this system type. <programlisting>
1739    # <emphasis role="bold">vos create</emphasis> &lt;<replaceable>machine name</replaceable>&gt; &lt;<replaceable>partition name</replaceable>&gt; <replaceable>sysname</replaceable>
1740    # <emphasis role="bold">vos create</emphasis> &lt;<replaceable>machine name</replaceable>&gt; &lt;<replaceable>partition name</replaceable>&gt; <replaceable>sysname</replaceable><emphasis
1741                   role="bold">.usr</emphasis>
1742    # <emphasis role="bold">vos create</emphasis> &lt;<replaceable>machine name</replaceable>&gt; &lt;<replaceable>partition name</replaceable>&gt; <replaceable>sysname</replaceable><emphasis
1743                   role="bold">.usr.afsws</emphasis>
1744 </programlisting></para>
1745           </listitem>
1746
1747           <listitem>
1748             <para>Issue the <emphasis role="bold">fs mkmount</emphasis> command to mount the newly created volumes. Because the
1749             <emphasis role="bold">root.cell</emphasis> volume is replicated, you must precede the <emphasis>cellname</emphasis> part
1750             of the pathname with a period to specify the read/write mount point, as shown. Then issue the <emphasis role="bold">vos
1751             release</emphasis> command to release a new replica of the <emphasis role="bold">root.cell</emphasis> volume, and the
1752             <emphasis role="bold">fs checkvolumes</emphasis> command to force the local Cache Manager to access them.
1753             <programlisting>
1754    # <emphasis role="bold">fs mkmount -dir /afs/.</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/</emphasis><replaceable>sysname</replaceable> <emphasis
1755                   role="bold">-vol</emphasis> <replaceable>sysname</replaceable>
1756    # <emphasis role="bold">fs mkmount -dir /afs/.</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/</emphasis><replaceable>sysname</replaceable><emphasis
1757                   role="bold">/usr</emphasis>  <emphasis role="bold">-vol</emphasis> <replaceable>sysname</replaceable><emphasis
1758                   role="bold">.usr</emphasis>
1759    # <emphasis role="bold">fs mkmount -dir /afs/.</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/</emphasis><replaceable>sysname</replaceable><emphasis
1760                   role="bold">/usr/afsws</emphasis> <emphasis role="bold">-vol</emphasis> <replaceable>sysname</replaceable><emphasis
1761                   role="bold">.usr.afsws</emphasis>
1762    # <emphasis role="bold">vos release root.cell</emphasis>
1763    # <emphasis role="bold">fs checkvolumes</emphasis>
1764 </programlisting></para>
1765           </listitem>
1766
1767           <listitem>
1768             <para>Issue the <emphasis role="bold">fs setacl</emphasis> command to grant the <emphasis role="bold">l</emphasis>
1769             (<emphasis role="bold">lookup</emphasis>) and <emphasis role="bold">r</emphasis> (<emphasis role="bold">read</emphasis>)
1770             permissions to the <emphasis role="bold">system:anyuser</emphasis> group on each new directory's ACL. <programlisting>
1771    # <emphasis role="bold">cd /afs/.</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/</emphasis><replaceable>sysname</replaceable>
1772    # <emphasis role="bold">fs setacl  -dir  .  usr  usr/afsws  -acl  system:anyuser rl</emphasis> 
1773 </programlisting></para>
1774           </listitem>
1775
1776           <listitem>
1777             <para>Issue the <emphasis role="bold">fs setquota</emphasis> command to set an unlimited quota on the volume mounted at
1778             the <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1779             role="bold">/</emphasis><replaceable>sysname</replaceable><emphasis role="bold">/usr/afsws</emphasis> directory. This
1780             enables you to copy all of the appropriate files from the CD-ROM into the volume without exceeding the volume's
1781             quota.</para>
1782
1783             <para>If you wish, you can set the volume's quota to a finite value after you complete the copying operation. At that
1784             point, use the <emphasis role="bold">vos examine</emphasis> command to determine how much space the volume is occupying.
1785             Then issue the <emphasis role="bold">fs setquota</emphasis> command to set a quota that is slightly larger.</para>
1786
1787             <programlisting>
1788    # <emphasis role="bold">fs setquota /afs/.</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/</emphasis><replaceable>sysname</replaceable><emphasis
1789                 role="bold">/usr/afsws  0</emphasis>
1790 </programlisting>
1791           </listitem>
1792
1793           <listitem id="LIWQ161">
1794             <para>Copy the contents of the indicated 
1795             directories from the OpenAFS binary distribution into the 
1796             <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1797             role="bold">/</emphasis><replaceable>sysname</replaceable><emphasis role="bold">/usr/afsws</emphasis> directory.
1798             <programlisting>
1799    # <emphasis role="bold">cd /afs/.</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/</emphasis><replaceable>sysname</replaceable><emphasis
1800                   role="bold">/usr/afsws</emphasis>
1801    # <emphasis role="bold">cp -rp /cdrom/</emphasis><replaceable>sysname</replaceable><emphasis role="bold">/bin  .</emphasis>
1802    # <emphasis role="bold">cp -rp /cdrom/</emphasis><replaceable>sysname</replaceable><emphasis role="bold">/etc  .</emphasis>
1803    # <emphasis role="bold">cp -rp /cdrom/</emphasis><replaceable>sysname</replaceable><emphasis role="bold">/include  .</emphasis>
1804    # <emphasis role="bold">cp -rp /cdrom/</emphasis><replaceable>sysname</replaceable><emphasis role="bold">/lib  .</emphasis>
1805 </programlisting></para>
1806           </listitem>
1807
1808           <listitem>
1809             <para>Issue the <emphasis role="bold">fs setacl</emphasis> command 
1810             to set the ACL on each directory appropriately. If you wish to 
1811             enable access to the software for locally authenticated users only, 
1812             set the ACL on the <emphasis role="bold">etc</emphasis>, 
1813             <emphasis role="bold">include</emphasis>, and 
1814             <emphasis role="bold">lib</emphasis> subdirectories to grant the 
1815             <emphasis role="bold">l</emphasis> and 
1816             <emphasis role="bold">r</emphasis> permissions to the 
1817             <emphasis role="bold">system:authuser</emphasis> group rather than 
1818             the <emphasis role="bold">system:anyuser</emphasis> group. The
1819             <emphasis role="bold">system:anyuser</emphasis> group must retain 
1820             the <emphasis role="bold">l</emphasis> and 
1821             <emphasis role="bold">r</emphasis> permissions on the 
1822             <emphasis role="bold">bin</emphasis> subdirectory to enable 
1823             unauthenticated users to access the 
1824             <emphasis role="bold">aklog</emphasis> binary. 
1825 <programlisting>
1826    # <emphasis role="bold">cd /afs/.</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/</emphasis><replaceable>sysname</replaceable><emphasis
1827                   role="bold">/usr/afsws</emphasis>
1828    # <emphasis role="bold">fs setacl  -dir etc include lib  -acl  system:authuser rl</emphasis>  \
1829               <emphasis role="bold">system:anyuser none</emphasis>
1830 </programlisting></para>
1831           </listitem>
1832
1833           <listitem id="LIWQ162">
1834             <para>Perform this step on the new client machine even if you have performed the previous steps
1835             on another machine. Create <emphasis role="bold">/usr/afsws</emphasis> on the local disk as a symbolic link to the
1836             directory <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1837             role="bold">/@sys/usr/afsws</emphasis>. You can specify the actual system name instead of <emphasis
1838             role="bold">@sys</emphasis> if you wish, but the advantage of using <emphasis role="bold">@sys</emphasis> is that it
1839             remains valid if you upgrade this machine to a different system type. <programlisting>
1840    # <emphasis role="bold">ln -s /afs/</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/@sys/usr/afsws  /usr/afsws</emphasis>
1841 </programlisting></para>
1842           </listitem>
1843
1844           <listitem>
1845             <para><emphasis role="bold">(Optional)</emphasis> To enable users to issue commands from the AFS suites (such as
1846             <emphasis role="bold">fs</emphasis>) without having to specify a pathname to their binaries, include the <emphasis
1847             role="bold">/usr/afsws/bin</emphasis> and <emphasis role="bold">/usr/afsws/etc</emphasis> directories in the PATH
1848             environment variable you define in each user's shell initialization file (such as <emphasis
1849             role="bold">.cshrc</emphasis>).</para>
1850           </listitem>
1851
1852           <listitem>
1853             <para><emphasis role="bold">(Optional)</emphasis> If you believe it is helpful to your users to access the AFS documents
1854             in a certain format via a local disk directory, create <emphasis role="bold">/usr/afsdoc</emphasis> on the local disk as
1855             a symbolic link to the documentation directory in AFS (<emphasis
1856             role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1857             role="bold">/afsdoc/</emphasis><replaceable>format_name</replaceable>). <programlisting>
1858    # <emphasis role="bold">ln -s /afs/</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/afsdoc/</emphasis><replaceable>format_name</replaceable> <emphasis
1859                   role="bold">/usr/afsdoc</emphasis>
1860 </programlisting></para>
1861
1862             <para>An alternative is to create a link in each user's home directory to the <emphasis
1863             role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1864             role="bold">/afsdoc/</emphasis><replaceable>format_name</replaceable> directory.</para>
1865           </listitem>
1866
1867           <listitem>
1868             <para><emphasis role="bold">(Optional)</emphasis> If working on the local machine, remove the AFS binaries from the
1869             temporary location. They are now accessible in the <emphasis role="bold">/usr/afsws</emphasis> directory.
1870             <programlisting>
1871    # <emphasis role="bold">cd  /tmp</emphasis>
1872    # <emphasis role="bold">rm  klog  fs  vos</emphasis>
1873 </programlisting></para>
1874           </listitem>
1875         </orderedlist></para>
1876     </sect2>
1877   </sect1>
1878 </chapter>