Correctly document the AFS client setuid defaults
[openafs.git] / doc / xml / AdminGuide / auagd015.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <chapter id="HDRWQ387">
3   <title>Administering Client Machines and the Cache Manager</title>
4
5   <para>This chapter describes how to administer an AFS client machine, which is any machine from which users can access the AFS
6   filespace and communicate with AFS server processes. (A client machine can simultaneously function as an AFS server machine if
7   appropriately configured.) An AFS client machine has the following characteristics: <itemizedlist>
8       <listitem>
9         <para>The kernel includes the set of modifications, commonly referred to as the <emphasis>Cache Manager</emphasis>, that
10         enable access to AFS files and directories. You can configure many of the Cache Manager's features to suit your users'
11         needs. See <link linkend="HDRWQ390">Overview of Cache Manager Customization</link>.</para>
12       </listitem>
13
14       <listitem>
15         <para>The <emphasis role="bold">/usr/vice/etc</emphasis> directory on the local disk stores several configuration files. See
16         <link linkend="HDRWQ392">Configuration Files in the /usr/vice/etc Directory</link>.</para>
17       </listitem>
18
19       <listitem>
20         <para>A cache stores temporary copies of data fetched from AFS file server machines, either in machine memory or on a
21         devoted local disk partition. See <link linkend="HDRWQ394">Determining the Cache Type, Size, and Location</link> and <link
22         linkend="HDRWQ402">Setting Other Cache Parameters with the afsd program</link>.</para>
23       </listitem>
24     </itemizedlist></para>
25
26   <para>To learn how to install the client functionality on a machine, see the <emphasis>OpenAFS Quick Beginnings</emphasis>.</para>
27
28   <sect1 id="HDRWQ388">
29     <title>Summary of Instructions</title>
30
31     <para>This chapter explains how to perform the following tasks by using the indicated commands:</para>
32
33     <informaltable frame="none">
34       <tgroup cols="2">
35         <colspec colwidth="67*" />
36
37         <colspec colwidth="33*" />
38
39         <tbody>
40           <row>
41             <entry>Display cache size set at reboot</entry>
42
43             <entry><emphasis role="bold">cat /usr/vice/etc/cacheinfo</emphasis></entry>
44           </row>
45
46           <row>
47             <entry>Display current cache size and usage</entry>
48
49             <entry><emphasis role="bold">fs getcacheparms</emphasis></entry>
50           </row>
51
52           <row>
53             <entry>Change disk cache size without rebooting</entry>
54
55             <entry><emphasis role="bold">fs setcachesize</emphasis></entry>
56           </row>
57
58           <row>
59             <entry>Initialize Cache Manager</entry>
60
61             <entry><emphasis role="bold">afsd</emphasis></entry>
62           </row>
63
64           <row>
65             <entry>Display contents of <emphasis role="bold">CellServDB</emphasis> file</entry>
66
67             <entry><emphasis role="bold">cat /usr/vice/etc/CellServDB</emphasis></entry>
68           </row>
69
70           <row>
71             <entry>Display list of database server machines from kernel memory</entry>
72
73             <entry><emphasis role="bold">fs listcells</emphasis></entry>
74           </row>
75
76           <row>
77             <entry>Change list of database server machines in kernel memory</entry>
78
79             <entry><emphasis role="bold">fs newcell</emphasis></entry>
80           </row>
81
82           <row>
83             <entry>Check cell's status regarding setuid</entry>
84
85             <entry><emphasis role="bold">fs getcellstatus</emphasis></entry>
86           </row>
87
88           <row>
89             <entry>Set cell's status regarding setuid</entry>
90
91             <entry><emphasis role="bold">fs setcell</emphasis></entry>
92           </row>
93
94           <row>
95             <entry>Set server probe interval</entry>
96
97             <entry><emphasis role="bold">fs checkservers -interval</emphasis></entry>
98           </row>
99
100           <row>
101             <entry>Display machine's cell membership</entry>
102
103             <entry><emphasis role="bold">cat /usr/vice/etc/ThisCell</emphasis></entry>
104           </row>
105
106           <row>
107             <entry>Change machine's cell membership</entry>
108
109             <entry>Edit <emphasis role="bold">/usr/vice/etc/ThisCell</emphasis></entry>
110           </row>
111
112           <row>
113             <entry>Flush cached file/directory</entry>
114
115             <entry><emphasis role="bold">fs flush</emphasis></entry>
116           </row>
117
118           <row>
119             <entry>Flush everything cached from a volume</entry>
120
121             <entry><emphasis role="bold">fs flushvolume</emphasis></entry>
122           </row>
123
124           <row>
125             <entry>Update volume-to-mount-point mappings</entry>
126
127             <entry><emphasis role="bold">fs checkvolumes</emphasis></entry>
128           </row>
129
130           <row>
131             <entry>Display Cache Manager's server preference ranks</entry>
132
133             <entry><emphasis role="bold">fs getserverprefs</emphasis></entry>
134           </row>
135
136           <row>
137             <entry>Set Cache Manager's server preference ranks</entry>
138
139             <entry><emphasis role="bold">fs setserverprefs</emphasis></entry>
140           </row>
141
142           <row>
143             <entry>Display client machine addresses to register</entry>
144
145             <entry><emphasis role="bold">fs getclientaddrs</emphasis></entry>
146           </row>
147
148           <row>
149             <entry>Set client machine addresses to register</entry>
150
151             <entry><emphasis role="bold">fs setclientaddrs</emphasis></entry>
152           </row>
153
154           <row>
155             <entry>Control the display of warning and status messages</entry>
156
157             <entry><emphasis role="bold">fs messages</emphasis></entry>
158           </row>
159
160           <row>
161             <entry>Display and change machine's system type</entry>
162
163             <entry><emphasis role="bold">fs sysname</emphasis></entry>
164           </row>
165
166           <row>
167             <entry>Enable asynchronous writes</entry>
168
169             <entry><emphasis role="bold">fs storebehind</emphasis></entry>
170           </row>
171         </tbody>
172       </tgroup>
173     </informaltable>
174   </sect1>
175
176   <sect1 id="HDRWQ390">
177     <title>Overview of Cache Manager Customization</title>
178
179     <indexterm>
180       <primary>Cache Manager</primary>
181
182       <secondary>configuring and customizing</secondary>
183     </indexterm>
184
185     <indexterm>
186       <primary>configuring</primary>
187
188       <secondary>Cache Manager</secondary>
189     </indexterm>
190
191     <indexterm>
192       <primary>Cache Manager</primary>
193
194       <secondary>described</secondary>
195     </indexterm>
196
197     <para>An AFS client machine's kernel includes a set of modifications, commonly referred to as the <emphasis>Cache
198     Manager</emphasis>, that enable access to AFS files and directories and communications with AFS server processes. It is common
199     to speak of the Cache Manager as a process or program, and in regular usage it appears to function like one. When configuring
200     it, though, it is helpful to keep in mind that this usage is not strictly accurate.</para>
201
202     <para>The Cache Manager mainly fetches files on behalf of application programs running on the machine. When an application
203     requests an AFS file, the Cache Manager contacts the Volume Location (VL) Server to obtain a list of the file server machines
204     that house the volume containing the file. The Cache Manager then translates the application program's system call requests into
205     remote procedure calls (RPCs) to the File Server running on the appropriate machine. When the File Server delivers the file, the
206     Cache Manager stores it in a local <emphasis>cache</emphasis> before delivering it to the application program.</para>
207
208     <para>The File Server delivers a data structure called a <emphasis>callback</emphasis> along with the file. (To be precise, it
209     delivers a callback for each file fetched from a read/write volume, and a single callback for all data fetched from a read-only
210     volume.) A valid callback indicates that the Cache Manager's cached copy of a file matches the central copy maintained by the
211     File Server. If an application on another AFS client machine changes the central copy, the File Server breaks the callback, and
212     the Cache Manager must retrieve the new version when an application program on its machine next requests data from the file. As
213     long as the callback is unbroken, however, the Cache Manager can continue to provide the cached version of the file to
214     applications on its machine, which eliminates unnecessary network traffic.</para>
215
216     <para>The indicated sections of this chapter explain how to configure and customize the following Cache Manager features. All
217     but the first (choosing disk or memory cache) are optional, because AFS sets suitable defaults for them. <itemizedlist>
218         <listitem>
219           <para><emphasis>disk or memory cache</emphasis>. The AFS Cache Manager can use machine memory for caching instead of space
220           on the local disk. Deciding which to use is the most basic configuration decision you must make. See <link
221           linkend="HDRWQ394">Determining the Cache Type, Size, and Location</link>.</para>
222         </listitem>
223
224         <listitem>
225           <para><emphasis>cache size</emphasis>. Cache size probably has the most direct influence on client machine performance. It
226           determines how often the Cache Manager must contact the File Server across the network or discard cached data to make room
227           for newly requested files, both of which affect how quickly the Cache Manager delivers files to users. See <link
228           linkend="HDRWQ394">Determining the Cache Type, Size, and Location</link>.</para>
229         </listitem>
230
231         <listitem>
232           <para><emphasis>cache location</emphasis>. For a disk cache, you can alter the conventional cache directory location
233           (<emphasis role="bold">/usr/vice/cache</emphasis>) to take advantage of greater space availability on other disks on the
234           machine. A larger cache can result in faster file delivery. See <link linkend="HDRWQ394">Determining the Cache Type, Size,
235           and Location</link>.</para>
236         </listitem>
237
238         <listitem>
239           <para><emphasis>chunk size and number</emphasis>. The <emphasis role="bold">afsd</emphasis> program, which initializes the
240           Cache Manager, allows you to control the size and number of chunks into which a cache is divided, plus related parameters.
241           Setting these parameters is optional, because there are reasonable defaults, but it provides precise control. The AFS
242           distribution includes configuration scripts that set Cache Manager parameters to values that are reasonable for different
243           configurations and usage patterns. See <link linkend="HDRWQ402">Setting Other Cache Parameters with the afsd
244           program</link>.</para>
245         </listitem>
246
247         <listitem>
248           <para><emphasis>knowledge of database server machines</emphasis>. Enable access to a cell's AFS filespace and other
249           services by listing the cell's database server machines in the <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis>
250           file on the local disk. See <link linkend="HDRWQ406">Maintaining Knowledge of Database Server Machines</link>.</para>
251         </listitem>
252
253         <listitem>
254           <para><emphasis>setuid privilege</emphasis>. You can control whether the Cache Manager allows programs from a cell to
255           execute with setuid permission. See <link linkend="HDRWQ409">Determining if a Client Can Run Setuid
256           Programs</link>.</para>
257         </listitem>
258
259         <listitem>
260           <para><emphasis>cell membership</emphasis>. Each client belongs to a one cell defined by the local <emphasis
261           role="bold">/usr/vice/etc/ThisCell</emphasis> file. Cell membership determines the default cell in which the machine's
262           users are authenticated and in which AFS commands run. See <link linkend="HDRWQ411">Setting a Client Machine's Cell
263           Membership</link>.</para>
264         </listitem>
265
266         <listitem>
267           <para><emphasis>cached file version</emphasis>. AFS's system of callbacks normally guarantees that the Cache Manager has
268           the most current versions of files and directories possible. Nevertheless, you can force the Cache Manager to fetch the
269           most current version of a file from the File Server if you suspect that the cache contains an outdated version. See <link
270           linkend="HDRWQ412">Forcing the Update of Cached Data</link>.</para>
271         </listitem>
272
273         <listitem>
274           <para><emphasis>File Server and Volume Location Server preferences</emphasis>. The Cache Manager sets numerical preference
275           ranks for the interfaces on file server machines and Volume Server (VL) machines. The ranks determine which interface the
276           Cache Manager first attempts to use when fetching data from a volume or from the Volume Location Database (VLDB). The
277           Cache Manager sets default ranks as it initializes, basing them on its network proximity to each interface, but you can
278           modify the preference ranks if you wish. See <link linkend="HDRWQ414">Maintaining Server Preference Ranks</link>.</para>
279         </listitem>
280
281         <listitem>
282           <para><emphasis>interfaces registered with the File Server</emphasis>. If the Cache Manager is multihomed (has multiple
283           interface addresses), you can control which of them it registers for File Servers to use when they initiate RPCs to the
284           client machine. See <link linkend="HDRWQ415">Managing Multihomed Client Machines</link>.</para>
285         </listitem>
286
287         <listitem>
288           <para><emphasis>display of information messages</emphasis>. By default, the Cache Manager sends basic error and
289           informational messages to the client machine's console and to command shells. You can disable the messaging. See <link
290           linkend="HDRWQ416">Controlling the Display of Warning and Informational Messages</link>.</para>
291         </listitem>
292
293         <listitem>
294           <para><emphasis>system type</emphasis>. The Cache Manager records the local machine's AFS system type in kernel memory,
295           and substitutes the value for the @sys variable in pathnames. See <link linkend="HDRWQ417">Displaying and Setting the
296           System Type Name</link>.</para>
297         </listitem>
298
299         <listitem>
300           <para><emphasis>delayed writes</emphasis>. By default, the Cache Manager writes all data to the File Server immediately
301           and synchronously when an application program closes a file. You can enable asynchronous writes, either for an individual
302           file, or all files that the Cache Manager handles, and set how much data remains to be written when the Cache Manager
303           returns control to the closing application. See <link linkend="HDRWQ418">Enabling Asynchronous Writes</link>.</para>
304         </listitem>
305       </itemizedlist></para>
306
307     <para>You must make all configuration changes on the client machine itself (at the console or over a direct connection such as a
308     <emphasis role="bold">telnet</emphasis> connection). You cannot configure the Cache Manager remotely. You must be logged in as
309     the local superuser <emphasis role="bold">root</emphasis> to issue some commands, whereas others require no privilege. All files
310     mentioned in this chapter must actually reside on the local disk of each AFS client machine (they cannot, for example, be
311     symbolic links to files in AFS).</para>
312
313     <para>AFS's <emphasis role="bold">package</emphasis> program can simplify other aspects of client machine configuration,
314     including those normally set in the machine's AFS initialization file. See <link linkend="HDRWQ419">Configuring Client Machines
315     with the package Program</link>.</para>
316   </sect1>
317
318   <sect1 id="HDRWQ391">
319     <title>Configuration and Cache-Related Files on the Local Disk</title>
320
321     <indexterm>
322       <primary>usr/vice/etc directory</primary>
323     </indexterm>
324
325     <indexterm>
326       <primary>directory</primary>
327
328       <secondary>/usr/vice/etc</secondary>
329     </indexterm>
330
331     <indexterm>
332       <primary>configuration files</primary>
333
334       <secondary>client machine</secondary>
335     </indexterm>
336
337     <indexterm>
338       <primary>client machine</primary>
339
340       <secondary>configuration files</secondary>
341     </indexterm>
342
343     <indexterm>
344       <primary>client machine</primary>
345
346       <secondary>/usr/vice/etc directory</secondary>
347     </indexterm>
348
349     <para>This section briefly describes the client configuration files that must reside in the local <emphasis
350     role="bold">/usr/vice/etc</emphasis> directory on every client machine. If the machine uses a disk cache, there must be a
351     partition devoted to cache files; by convention, it is mounted at the <emphasis role="bold">/usr/vice/cache</emphasis>
352     directory.</para>
353
354     <para><emphasis role="bold">Note for Windows users:</emphasis> Some files described in this document possibly do not exist on
355     machines that run a Windows operating system. Also, Windows uses a backslash (<emphasis role="bold">\</emphasis>) rather than a
356     forward slash (<emphasis role="bold">/</emphasis>) to separate the elements in a pathname.</para>
357
358     <sect2 id="HDRWQ392">
359       <title>Configuration Files in the /usr/vice/etc Directory</title>
360
361       <para>The <emphasis role="bold">/usr/vice/etc</emphasis> directory on a client machine's local disk must contain certain
362       configuration files for the Cache Manager to function properly. They control the most basic aspects of Cache Manager
363       configuration.</para>
364
365       <para>If it is important that the client machines in your cell perform uniformly, it is most efficient to update these files
366       from a central source. The following descriptions include pointers to sections that discuss how best to maintain the files.
367       <variablelist>
368           <indexterm>
369             <primary>afsd program</primary>
370           </indexterm>
371
372           <indexterm>
373             <primary>Cache Manager</primary>
374
375             <secondary>afsd initialization program</secondary>
376           </indexterm>
377
378           <indexterm>
379             <primary>files</primary>
380
381             <secondary>afsd</secondary>
382           </indexterm>
383
384           <indexterm>
385             <primary>commands</primary>
386
387             <secondary>afsd</secondary>
388           </indexterm>
389
390           <indexterm>
391             <primary>programs</primary>
392
393             <secondary>afsd</secondary>
394           </indexterm>
395
396           <varlistentry>
397             <term><emphasis role="bold">afsd</emphasis></term>
398
399             <listitem>
400               <para>The binary file for the program that initializes the Cache Manager. It must run each time the machine reboots in
401               order for the machine to remain an AFS client machine. The program also initializes several daemons that improve Cache
402               Manager functioning, such as the process that handles callbacks. <indexterm>
403                   <primary>files</primary>
404
405                   <secondary>cacheinfo</secondary>
406                 </indexterm> <indexterm>
407                   <primary>cacheinfo file</primary>
408                 </indexterm></para>
409             </listitem>
410           </varlistentry>
411
412           <varlistentry>
413             <term><emphasis role="bold">cacheinfo</emphasis></term>
414
415             <listitem>
416               <para>A one-line file that sets the cache's most basic configuration parameters: the local directory at which the
417               Cache Manager mounts the AFS filespace, the local disk directory to use as the cache, and how many kilobytes to
418               allocate to the cache.</para>
419
420               <para>The <emphasis>OpenAFS Quick Beginnings</emphasis> explains how to create this file as you install a client
421               machine. To change the cache size on a machine that uses a memory cache, edit the file and reboot the machine. On a
422               machine that uses a disk cache, you can change the cache size without rebooting by issuing the <emphasis
423               role="bold">fs setcachesize</emphasis> command. For instructions, see <link linkend="HDRWQ394">Determining the Cache
424               Type, Size, and Location</link>. <indexterm>
425                   <primary>CellServDB file (client)</primary>
426
427                   <secondary>about</secondary>
428                 </indexterm> <indexterm>
429                   <primary>files</primary>
430
431                   <secondary>CellServDB (client)</secondary>
432                 </indexterm></para>
433             </listitem>
434           </varlistentry>
435
436           <varlistentry>
437             <term><emphasis role="bold">CellServDB</emphasis></term>
438
439             <listitem>
440               <para>This ASCII file names the database server machines in the local cell and in any foreign cell to which you want
441               to enable access from this machine. (Database server machines are the machines in a cell that run the Authentication,
442               Backup, Protection, and VL Server processes; see <link linkend="HDRWQ92">Database Server Machines</link>.)</para>
443
444               <para>The Cache Manager must be able to reach a cell's database server machines to fetch files from its filespace.
445               Incorrect or missing information in the <emphasis role="bold">CellServDB</emphasis> file can slow or completely block
446               access. It is important to update the file whenever a cell's database server machines change.</para>
447
448               <para>As the <emphasis role="bold">afsd</emphasis> program initializes the Cache Manager, it loads the contents of the
449               file into kernel memory. The Cache Manager does not read the file between reboots, so to incorporate changes to the
450               file into kernel memory, you must reboot the machine. Alternatively, you can issue the <emphasis role="bold">fs
451               newcell</emphasis> command to insert the changes directly into kernel memory without changing the file. It can also be
452               convenient to upgrade the file from a central source. For instructions, see <link linkend="HDRWQ406">Maintaining
453               Knowledge of Database Server Machines</link>.</para>
454
455               <para>(The <emphasis role="bold">CellServDB</emphasis> file on client machines is not the same as the one kept in the
456               <emphasis role="bold">/usr/afs/etc</emphasis> directory on server machines, which lists only the local cell's database
457               server machines. For instructions on maintaining the server <emphasis role="bold">CellServDB</emphasis> file, see
458               <link linkend="HDRWQ118">Maintaining the Server CellServDB File</link>). <indexterm>
459                   <primary>NetInfo file (client version)</primary>
460                 </indexterm> <indexterm>
461                   <primary>files</primary>
462
463                   <secondary>NetInfo (client version)</secondary>
464                 </indexterm></para>
465             </listitem>
466           </varlistentry>
467
468           <varlistentry>
469             <term><emphasis role="bold">NetInfo</emphasis></term>
470
471             <listitem>
472               <para>This optional ASCII file lists one or more of the network interface addresses on the client machine. If it
473               exists when the Cache Manager initializes, the Cache Manager uses it as the basis for the list of interfaces that it
474               registers with File Servers. See <link linkend="HDRWQ415">Managing Multihomed Client Machines</link>. <indexterm>
475                   <primary>NetRestrict file (client version)</primary>
476                 </indexterm> <indexterm>
477                   <primary>files</primary>
478
479                   <secondary>NetRestrict (client version)</secondary>
480                 </indexterm></para>
481             </listitem>
482           </varlistentry>
483
484           <varlistentry>
485             <term><emphasis role="bold">NetRestrict</emphasis></term>
486
487             <listitem>
488               <para>This optional ASCII file lists one or more network interface addresses. If it exists when the Cache Manager
489               initializes, the Cache Manager removes the specified addresses from the list of interfaces that it registers with File
490               Servers. See <link linkend="HDRWQ415">Managing Multihomed Client Machines</link>. <indexterm>
491                   <primary>ThisCell file (client)</primary>
492                 </indexterm> <indexterm>
493                   <primary>files</primary>
494
495                   <secondary>ThisCell (client)</secondary>
496                 </indexterm></para>
497             </listitem>
498           </varlistentry>
499
500           <varlistentry>
501             <term><emphasis role="bold">ThisCell</emphasis></term>
502
503             <listitem>
504               <para>This ASCII file contains a single line that specifies the complete domain-style name of the cell to which the
505               machine belongs. Examples are <computeroutput>abc.com</computeroutput> and
506               <computeroutput>stateu.edu</computeroutput>. This value defines the default cell in which the machine's users become
507               authenticated, and in which the command interpreters (for example, the <emphasis role="bold">bos</emphasis> command)
508               contact server processes.</para>
509
510               <para>The <emphasis>OpenAFS Quick Beginnings</emphasis> explains how to create this file as you install the AFS client
511               functionality. To learn about changing a client machine's cell membership, see <link linkend="HDRWQ411">Setting a
512               Client Machine's Cell Membership</link>.</para>
513             </listitem>
514           </varlistentry>
515         </variablelist></para>
516
517       <para>In addition to these files, the <emphasis role="bold">/usr/vice/etc</emphasis> directory also sometimes contains the
518       following types of files and subdirectories: <itemizedlist>
519           <indexterm>
520             <primary>AFS</primary>
521
522             <secondary>initialization script</secondary>
523           </indexterm>
524
525           <indexterm>
526             <primary>files</primary>
527
528             <secondary>AFS initialization script</secondary>
529           </indexterm>
530
531           <indexterm>
532             <primary>initialization script for AFS</primary>
533           </indexterm>
534
535           <indexterm>
536             <primary>script for AFS initialization</primary>
537           </indexterm>
538
539           <listitem>
540             <para>The AFS initialization script, called <emphasis role="bold">afs.rc</emphasis> on many system types. In the
541             conventional configuration specified by the <emphasis>OpenAFS Quick Beginnings</emphasis>, it is a symbolic link to the
542             actual script kept in the same directory as other initialization files used by the operating system. <indexterm>
543                 <primary>dynamic kernel loader programs</primary>
544
545                 <secondary>directory for AFS library files</secondary>
546               </indexterm> <indexterm>
547                 <primary>files</primary>
548
549                 <secondary>AFS libraries used by dynamic kernel loader programs</secondary>
550               </indexterm></para>
551           </listitem>
552
553           <listitem>
554             <para>A subdirectory that houses AFS kernel library files used by a dynamic kernel loading program. <indexterm>
555                 <primary>afszcm.cat file</primary>
556               </indexterm> <indexterm>
557                 <primary>files</primary>
558
559                 <secondary>afszcm.cat</secondary>
560               </indexterm></para>
561           </listitem>
562
563           <listitem>
564             <para>A subdirectory called <emphasis role="bold">C</emphasis>, which houses the Cache Manager catalog file called
565             <emphasis role="bold">afszcm.cat</emphasis>. The fstrace program uses the catalog file to translate operation codes into
566             character strings, which makes the message in the trace log more readable. See <link linkend="HDRWQ342">About the
567             fstrace Command Suite</link>.</para>
568           </listitem>
569         </itemizedlist></para>
570     </sect2>
571
572     <sect2 id="HDRWQ393">
573       <title>Cache-Related Files</title>
574
575       <indexterm>
576         <primary>usr/vice/cache directory</primary>
577       </indexterm>
578
579       <indexterm>
580         <primary>directory</primary>
581
582         <secondary>/usr/vice/cache</secondary>
583       </indexterm>
584
585       <indexterm>
586         <primary>directory</primary>
587
588         <secondary>disk cache</secondary>
589       </indexterm>
590
591       <indexterm>
592         <primary>cache files (client)</primary>
593       </indexterm>
594
595       <indexterm>
596         <primary>client machine</primary>
597
598         <secondary>cache files</secondary>
599       </indexterm>
600
601       <para>A client machine that uses a disk cache must have a local disk directory devoted to the cache. The conventional mount
602       point is <emphasis role="bold">/usr/vice/cache</emphasis>, but you can use another partition that has more available
603       space.</para>
604
605       <para>Do not delete or directly modify any of the files in the cache directory. Doing so can cause a kernel panic, from which
606       the only way to recover is to reboot the machine. By default, only the local superuser <emphasis role="bold">root</emphasis>
607       can read the files directly, by virtue of owning them.</para>
608
609       <para>A client machine that uses a memory cache keeps all of the information stored in these files in machine memory instead.
610       <variablelist>
611           <indexterm>
612             <primary>CacheItems file</primary>
613           </indexterm>
614
615           <indexterm>
616             <primary>files</primary>
617
618             <secondary>CacheItems</secondary>
619           </indexterm>
620
621           <varlistentry>
622             <term><emphasis role="bold">CacheItems</emphasis></term>
623
624             <listitem>
625               <para>A binary-format file in which the Cache Manager tracks the contents of cache chunks (the <emphasis
626               role="bold">V</emphasis> files in the directory, described just following), including the file ID number (fID) and the
627               data version number. <indexterm>
628                   <primary>files</primary>
629
630                   <secondary>VolumeItems</secondary>
631                 </indexterm> <indexterm>
632                   <primary>VolumeItems file</primary>
633                 </indexterm></para>
634             </listitem>
635           </varlistentry>
636
637           <varlistentry>
638             <term><emphasis role="bold">VolumeItems</emphasis></term>
639
640             <listitem>
641               <para>A binary-format file in which the Cache Manager records the mapping between mount points and the volumes from
642               which it has fetched data. The Cache Manager uses the information when responding to the <emphasis
643               role="bold">pwd</emphasis> command, among others. <indexterm>
644                   <primary>files</primary>
645
646                   <secondary>Vn</secondary>
647                 </indexterm> <indexterm>
648                   <primary>Vn file (data cache)</primary>
649                 </indexterm> <indexterm>
650                   <primary>data cache</primary>
651
652                   <secondary>Vn file in</secondary>
653                 </indexterm></para>
654             </listitem>
655           </varlistentry>
656
657           <varlistentry>
658             <term><emphasis role="bold">Vn</emphasis></term>
659
660             <listitem>
661               <para>A cache chunk file, which expands to a maximum size (by default, 64 KB) to house data fetched from AFS files.
662               The number of <emphasis role="bold">V</emphasis>n files in the cache depends on the cache size among other factors.
663               The n is the index assigned to each file; they are numbered sequentially, but the Cache Manager does not necessarily
664               use them in order or contiguously. If an AFS file is larger than the maximum size for <emphasis
665               role="bold">V</emphasis>n files, the Cache Manager divides it across multiple <emphasis role="bold">V</emphasis>n
666               files.</para>
667             </listitem>
668           </varlistentry>
669         </variablelist></para>
670     </sect2>
671   </sect1>
672
673   <sect1 id="HDRWQ394">
674     <title>Determining the Cache Type, Size, and Location</title>
675
676     <para>This section explains how to configure a memory or disk cache, how to display and set the size of either type of cache,
677     and how to set the location of the cache directory for a disk cache. <indexterm>
678         <primary>data cache</primary>
679
680         <secondary>disk versus memory</secondary>
681       </indexterm> <indexterm>
682         <primary>client machine</primary>
683
684         <secondary>disk versus memory cache</secondary>
685       </indexterm></para>
686
687     <para>The Cache Manager uses a disk cache by default, and it is the preferred type of caching. To configure a memory cache,
688     include the <emphasis role="bold">-memcache</emphasis> flag on the <emphasis role="bold">afsd</emphasis> command, which is
689     normally invoked in the machine's AFS initialization file. If configured to use a memory cache, the Cache Manager does no disk
690     caching, even if the machine has a disk.</para>
691
692     <sect2 id="Header_438">
693       <title>Choosing the Cache Size</title>
694
695       <indexterm>
696         <primary>data cache</primary>
697
698         <secondary>size</secondary>
699
700         <tertiary>recommendations</tertiary>
701       </indexterm>
702
703       <para>Cache size influences the performance of a client machine more directly than perhaps any other cache parameter. The
704       larger the cache, the faster the Cache Manager is likely to deliver files to users. A small cache can impair performance
705       because it increases the frequency at which the Cache Manager must discard cached data to make room for newly requested data.
706       When an application asks for data that has been discarded, the Cache Manager must request it from the File Server, and
707       fetching data across the network is almost always slower than fetching it from the local disk. The Cache Manager never
708       discards data from a file that has been modified locally but not yet stored back to the File Server. If the cache is very
709       small, the Cache Manager possible cannot find any data to discard. For more information about the algorithm it uses when
710       discarding cached data, see <link linkend="HDRWQ401">How the Cache Manager Chooses Data to Discard</link>).</para>
711
712       <para>The amount of disk or memory you devote to caching depends on several factors. The amount of space available in memory
713       or on the partition housing the disk cache directory imposes an absolute limit. In addition, you cannot allocate more than 95%
714       of the space available on the cache directory's partition to a disk cache. The <emphasis role="bold">afsd</emphasis> program
715       exits without starting the Cache Manager and prints an appropriate message to the standard output stream if you violate this
716       restriction. For a memory cache, you must leave enough memory for other processes and applications to run. If you try to
717       allocate more memory than is actually available, the <emphasis role="bold">afsd</emphasis> program exits without initializing
718       the Cache Manager and produces the following message on the standard output stream:</para>
719
720       <programlisting>
721    afsd: memCache allocation failure at number KB
722 </programlisting>
723
724       <para>where number is how many kilobytes were allocated just before the failure.</para>
725
726       <para>Within these hard limits, the factors that determine appropriate cache size include the number of users working on the
727       machine, the size of the files with which they usually work, and (for a memory cache) the number of processes that usually run
728       on the machine. The higher the demand from these factors, the larger the cache needs to be to maintain good
729       performance.</para>
730
731       <para>Disk caches smaller than 10 MB do not generally perform well. Machines serving multiple users usually perform better
732       with a cache of at least 60 to 70 MB. The point at which enlarging the cache further does not really improve performance
733       depends on the factors mentioned previously, and is difficult to predict.</para>
734
735       <para>Memory caches smaller than 1 MB are nonfunctional, and the performance of caches smaller than 5 MB is usually
736       unsatisfactory. Suitable upper limits are similar to those for disk caches but are probably determined more by the demands on
737       memory from other sources on the machine (number of users and processes). Machines running only a few processes possibly can
738       use a smaller memory cache.</para>
739
740       <para>AFS imposes an absolute limit on cache size in some versions. See the <emphasis>OpenAFS Release Notes</emphasis> for the
741       version you are using.</para>
742     </sect2>
743
744     <sect2 id="HDRWQ395">
745       <title>Displaying and Setting the Cache Size and Location</title>
746
747       <indexterm>
748         <primary>Cache Manager</primary>
749
750         <secondary>setting</secondary>
751
752         <tertiary>disk cache location</tertiary>
753       </indexterm>
754
755       <indexterm>
756         <primary>Cache Manager</primary>
757
758         <secondary>displaying</secondary>
759
760         <tertiary>cache size from cacheinfo file</tertiary>
761       </indexterm>
762
763       <indexterm>
764         <primary>Cache Manager</primary>
765
766         <secondary>setting</secondary>
767
768         <tertiary>cache size in cacheinfo file</tertiary>
769       </indexterm>
770
771       <indexterm>
772         <primary>Cache Manager</primary>
773
774         <secondary>data cache</secondary>
775
776         <tertiary>displaying size set at reboot</tertiary>
777       </indexterm>
778
779       <indexterm>
780         <primary>cacheinfo file</primary>
781
782         <secondary>setting</secondary>
783
784         <tertiary>disk cache location</tertiary>
785       </indexterm>
786
787       <indexterm>
788         <primary>cacheinfo file</primary>
789
790         <secondary>displaying contents</secondary>
791       </indexterm>
792
793       <indexterm>
794         <primary>cacheinfo file</primary>
795
796         <secondary>setting</secondary>
797
798         <tertiary>cache size</tertiary>
799       </indexterm>
800
801       <indexterm>
802         <primary>changing</primary>
803
804         <secondary>data cache size specified in cacheinfo file</secondary>
805       </indexterm>
806
807       <indexterm>
808         <primary>changing</primary>
809
810         <secondary>disk cache location, in cacheinfo file</secondary>
811       </indexterm>
812
813       <indexterm>
814         <primary>client machine</primary>
815
816         <secondary>setting</secondary>
817
818         <tertiary>disk cache location</tertiary>
819       </indexterm>
820
821       <indexterm>
822         <primary>client machine</primary>
823
824         <secondary>data cache size set at reboot</secondary>
825
826         <tertiary>displaying</tertiary>
827       </indexterm>
828
829       <indexterm>
830         <primary>client machine</primary>
831
832         <secondary>displaying</secondary>
833
834         <tertiary>data cache size from cacheinfo file</tertiary>
835       </indexterm>
836
837       <indexterm>
838         <primary>client machine</primary>
839
840         <secondary>setting</secondary>
841
842         <tertiary>data cache size in cacheinfo file</tertiary>
843       </indexterm>
844
845       <indexterm>
846         <primary>displaying</primary>
847
848         <secondary>data cache size</secondary>
849
850         <tertiary>set at reboot</tertiary>
851       </indexterm>
852
853       <indexterm>
854         <primary>displaying</primary>
855
856         <secondary>data cache size</secondary>
857
858         <tertiary>specified in cacheinfo file</tertiary>
859       </indexterm>
860
861       <indexterm>
862         <primary>data cache</primary>
863
864         <secondary>size</secondary>
865
866         <tertiary>setting in cacheinfo file</tertiary>
867       </indexterm>
868
869       <indexterm>
870         <primary>data cache</primary>
871
872         <secondary>changing location of disk cache</secondary>
873       </indexterm>
874
875       <indexterm>
876         <primary>data cache</primary>
877
878         <secondary>size</secondary>
879
880         <tertiary>set at reboot, displaying</tertiary>
881       </indexterm>
882
883       <indexterm>
884         <primary>data cache</primary>
885
886         <secondary>displaying size specified in cacheinfo file</secondary>
887       </indexterm>
888
889       <indexterm>
890         <primary>location</primary>
891
892         <secondary>setting for client</secondary>
893       </indexterm>
894
895       <indexterm>
896         <primary>setting</primary>
897
898         <secondary>disk cache location in cacheinfo file</secondary>
899       </indexterm>
900
901       <para>The Cache Manager determines how big to make the cache by reading the <emphasis
902       role="bold">/usr/vice/etc/cacheinfo</emphasis> file as it initializes. As directed in the <emphasis>OpenAFS Quick
903       Beginnings</emphasis>, you must create the file before running the <emphasis role="bold">afsd</emphasis> program. The file
904       also defines the directory on which to mount AFS (by convention, <emphasis role="bold">/afs</emphasis>), and the local disk
905       directory to use for a cache directory.</para>
906
907       <para>To change any of the values in the file, log in as the local superuser <emphasis role="bold">root</emphasis>. You must
908       reboot the machine to have the new value take effect. For instructions, see <link linkend="HDRWQ398">To edit the cacheinfo
909       file</link>.</para>
910
911       <para>To change the cache size at reboot without editing the <emphasis role="bold">cacheinfo</emphasis> file, include the
912       <emphasis role="bold">-blocks</emphasis> argument to the <emphasis role="bold">afsd</emphasis> command; see the command's
913       reference page in the OpenAFS Administration Reference.</para>
914
915       <para>For a disk cache, you can also use the <emphasis role="bold">fs setcachesize</emphasis> command to reset the cache size
916       without rebooting. The value you set persists until the next reboot, at which time the cache size returns to the value
917       specified in the <emphasis role="bold">cacheinfo</emphasis> file or by the <emphasis role="bold">-blocks</emphasis> argument
918       to the <emphasis role="bold">afsd</emphasis> command. For instructions, see <link linkend="HDRWQ399">To change the disk cache
919       size without rebooting</link>.</para>
920
921       <para>To display the current cache size and the amount of space the Cache Manager is using at the moment, use the <emphasis
922       role="bold">fs getcacheparms</emphasis> command as detailed in <link linkend="HDRWQ397">To display the current cache
923       size</link>.</para>
924     </sect2>
925
926     <sect2 id="HDRWQ396">
927       <title>To display the cache size set at reboot</title>
928
929       <orderedlist>
930         <listitem>
931           <para>Use a text editor or the <emphasis role="bold">cat</emphasis> command to display the contents of the <emphasis
932           role="bold">/usr/vice/etc/cacheinfo</emphasis> file. <programlisting>
933    % <emphasis role="bold">cat /usr/vice/etc/cacheinfo</emphasis>
934 </programlisting></para>
935         </listitem>
936       </orderedlist>
937
938       <indexterm>
939         <primary>data cache</primary>
940
941         <secondary>size</secondary>
942
943         <tertiary>current, displaying</tertiary>
944       </indexterm>
945
946       <indexterm>
947         <primary>client machine</primary>
948
949         <secondary>data cache size</secondary>
950
951         <tertiary>displaying current</tertiary>
952       </indexterm>
953
954       <indexterm>
955         <primary>Cache Manager</primary>
956
957         <secondary>data cache size</secondary>
958
959         <tertiary>displaying current</tertiary>
960       </indexterm>
961
962       <indexterm>
963         <primary>displaying</primary>
964
965         <secondary>data cache size, current</secondary>
966       </indexterm>
967
968       <indexterm>
969         <primary>fs commands</primary>
970
971         <secondary>getcacheparms</secondary>
972       </indexterm>
973
974       <indexterm>
975         <primary>commands</primary>
976
977         <secondary>fs getcacheparms</secondary>
978       </indexterm>
979     </sect2>
980
981     <sect2 id="HDRWQ397">
982       <title>To display the current cache size</title>
983
984       <orderedlist>
985         <listitem>
986           <para>Issue the <emphasis role="bold">fs getcacheparms</emphasis> command on the client machine. <programlisting>
987    % <emphasis role="bold">fs getcacheparms</emphasis>
988 </programlisting></para>
989
990           <para>where <emphasis role="bold">getca</emphasis> is the shortest acceptable abbreviation of <emphasis
991           role="bold">getcacheparms</emphasis>.</para>
992
993           <para>The output shows the number of kilobyte blocks the Cache Manager is using as a cache at the moment the command is
994           issued, and the current size of the cache. For example:</para>
995
996           <programlisting>
997    AFS using 13709 of the cache's available 15000 1K byte blocks.
998 </programlisting>
999         </listitem>
1000       </orderedlist>
1001
1002       <indexterm>
1003         <primary>data cache</primary>
1004
1005         <secondary>size</secondary>
1006
1007         <tertiary>setting in cacheinfo file</tertiary>
1008       </indexterm>
1009
1010       <indexterm>
1011         <primary>client machine</primary>
1012
1013         <secondary>data cache size</secondary>
1014
1015         <tertiary>setting in cacheinfo file</tertiary>
1016       </indexterm>
1017
1018       <indexterm>
1019         <primary>Cache Manager</primary>
1020
1021         <secondary>data cache size</secondary>
1022
1023         <tertiary>setting in cacheinfo file</tertiary>
1024       </indexterm>
1025
1026       <indexterm>
1027         <primary>setting</primary>
1028
1029         <secondary>data cache size in cacheinfo file</secondary>
1030       </indexterm>
1031
1032       <indexterm>
1033         <primary>cacheinfo file</primary>
1034
1035         <secondary>format</secondary>
1036       </indexterm>
1037     </sect2>
1038
1039     <sect2 id="HDRWQ398">
1040       <title>To edit the cacheinfo file</title>
1041
1042       <orderedlist>
1043         <listitem>
1044           <para>Become the local superuser <emphasis role="bold">root</emphasis> on the machine, if you are not already, by issuing
1045           the <emphasis role="bold">su</emphasis> command. <programlisting>
1046    % <emphasis role="bold">su root</emphasis>
1047    Password: &lt;<replaceable>root_password</replaceable>&gt;
1048 </programlisting></para>
1049         </listitem>
1050
1051         <listitem>
1052           <para>Use a text editor to edit the <emphasis role="bold">/usr/vice/etc/cacheinfo</emphasis> file, which has three fields,
1053           separated by colons: <itemizedlist>
1054               <listitem>
1055                 <para>The first field names the local directory on which to mount the AFS filespace. The conventional location is
1056                 <emphasis role="bold">/afs</emphasis>.</para>
1057               </listitem>
1058
1059               <listitem>
1060                 <para>The second field defines the local disk directory to use for the disk cache. The conventional location is the
1061                 <emphasis role="bold">/usr/vice/cache</emphasis> directory, but you can specify an alternate directory if another
1062                 partition has more space available. There must always be a value in this field, but the Cache Manager ignores it if
1063                 the machine uses a memory cache.</para>
1064               </listitem>
1065
1066               <listitem>
1067                 <para>The third field defines cache size as a number of kilobyte (1024-byte) blocks.</para>
1068               </listitem>
1069             </itemizedlist></para>
1070
1071           <para>The following example mounts the AFS filespace at the <emphasis role="bold">/afs</emphasis> directory, names
1072           <emphasis role="bold">/usr/vice/cache</emphasis> as the cache directory, and sets cache size to 50,000 KB:</para>
1073
1074           <programlisting>
1075             <emphasis role="bold">/afs:/usr/vice/cache:50000</emphasis>
1076           </programlisting>
1077         </listitem>
1078       </orderedlist>
1079
1080       <indexterm>
1081         <primary>data cache</primary>
1082
1083         <secondary>size</secondary>
1084
1085         <tertiary>setting until next reboot</tertiary>
1086       </indexterm>
1087
1088       <indexterm>
1089         <primary>changing</primary>
1090
1091         <secondary>data cache size temporarily</secondary>
1092       </indexterm>
1093
1094       <indexterm>
1095         <primary>client machine</primary>
1096
1097         <secondary>data cache size</secondary>
1098
1099         <tertiary>setting until next reboot</tertiary>
1100       </indexterm>
1101
1102       <indexterm>
1103         <primary>Cache Manager</primary>
1104
1105         <secondary>data cache size</secondary>
1106
1107         <tertiary>setting until next reboot</tertiary>
1108       </indexterm>
1109
1110       <indexterm>
1111         <primary>fs commands</primary>
1112
1113         <secondary>setcachesize</secondary>
1114       </indexterm>
1115
1116       <indexterm>
1117         <primary>commands</primary>
1118
1119         <secondary>fs setcachesize</secondary>
1120       </indexterm>
1121     </sect2>
1122
1123     <sect2 id="HDRWQ399">
1124       <title>To change the disk cache size without rebooting</title>
1125
1126       <orderedlist>
1127         <listitem>
1128           <para>Become the local superuser <emphasis role="bold">root</emphasis> on the machine, if you are not already, by issuing
1129           the <emphasis role="bold">su</emphasis> command. <programlisting>
1130    % <emphasis role="bold">su root</emphasis>
1131    Password: &lt;<replaceable>root_password</replaceable>&gt;
1132 </programlisting></para>
1133         </listitem>
1134
1135         <listitem>
1136           <para><anchor id="LIWQ400" />Issue the <emphasis role="bold">fs setcachesize</emphasis> command to set a new disk cache
1137           size.</para>
1138
1139           <note>
1140             <para>This command does not work for a memory cache.</para>
1141           </note>
1142
1143           <programlisting>
1144    # <emphasis role="bold">fs setcachesize</emphasis> &lt;<replaceable>size in 1K byte blocks (0 =</replaceable>&gt; reset)&gt;
1145 </programlisting>
1146
1147           <para>where <variablelist>
1148               <varlistentry>
1149                 <term><emphasis role="bold">setca</emphasis></term>
1150
1151                 <listitem>
1152                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">setcachesize</emphasis>.</para>
1153                 </listitem>
1154               </varlistentry>
1155
1156               <varlistentry>
1157                 <term><emphasis role="bold">size in 1K byte blocks (0 =&gt; reset)</emphasis></term>
1158
1159                 <listitem>
1160                   <para>Sets the number of kilobyte blocks to be used for the cache. Specify a positive integer (<emphasis
1161                   role="bold">1024</emphasis> equals 1 MB), or <emphasis role="bold">0</emphasis> (zero) to reset the cache size to
1162                   the value specified in the <emphasis role="bold">cacheinfo</emphasis> file.</para>
1163                 </listitem>
1164               </varlistentry>
1165             </variablelist></para>
1166         </listitem>
1167       </orderedlist>
1168
1169       <indexterm>
1170         <primary>data cache</primary>
1171
1172         <secondary>disk cache size</secondary>
1173
1174         <tertiary>resetting to default value</tertiary>
1175       </indexterm>
1176
1177       <indexterm>
1178         <primary>changing</primary>
1179
1180         <secondary>disk cache size to default value</secondary>
1181       </indexterm>
1182
1183       <indexterm>
1184         <primary>resetting</primary>
1185
1186         <secondary>disk cache size to default value</secondary>
1187       </indexterm>
1188
1189       <indexterm>
1190         <primary>cacheinfo file</primary>
1191
1192         <secondary>resetting disk cache to size specified</secondary>
1193       </indexterm>
1194
1195       <indexterm>
1196         <primary>client machine</primary>
1197
1198         <secondary>disk cache size</secondary>
1199
1200         <tertiary>resetting to default value</tertiary>
1201       </indexterm>
1202
1203       <indexterm>
1204         <primary>Cache Manager</primary>
1205
1206         <secondary>data cache size</secondary>
1207
1208         <tertiary>resetting to default value (for disk cache only)</tertiary>
1209       </indexterm>
1210     </sect2>
1211
1212     <sect2 id="Header_444">
1213       <title>To reset the disk cache size to the default without rebooting</title>
1214
1215       <orderedlist>
1216         <listitem>
1217           <para>Become the local superuser <emphasis role="bold">root</emphasis> on the machine, if you are not already, by issuing
1218           the <emphasis role="bold">su</emphasis> command. <programlisting>
1219    % <emphasis role="bold">su root</emphasis>
1220    Password: &lt;<replaceable>root_password</replaceable>&gt;
1221 </programlisting></para>
1222         </listitem>
1223
1224         <listitem>
1225           <para>Issue the <emphasis role="bold">fs setcachesize</emphasis> command to reset the size of the local disk cache (the
1226           command does not work for a memory cache). Choose one of the two following options: <itemizedlist>
1227               <listitem>
1228                 <para>To reset the cache size to the value specified in the local <emphasis role="bold">cacheinfo</emphasis> file,
1229                 specify the value <emphasis role="bold">0</emphasis> (zero) <programlisting>
1230    # <emphasis role="bold">fs setcachesize 0</emphasis>
1231 </programlisting></para>
1232               </listitem>
1233
1234               <listitem>
1235                 <para>To reset the cache size to the value set at the last reboot of the machine, include the <emphasis
1236                 role="bold">-reset</emphasis> flag. Unless the <emphasis role="bold">-blocks</emphasis> argument was used on the
1237                 <emphasis role="bold">afsd</emphasis> command, this is also the value in the <emphasis
1238                 role="bold">cacheinfo</emphasis> file. <programlisting>
1239    # <emphasis role="bold">fs setcachesize -reset</emphasis>
1240 </programlisting></para>
1241               </listitem>
1242             </itemizedlist></para>
1243
1244           <para>where <variablelist>
1245               <varlistentry>
1246                 <term><emphasis role="bold">setca</emphasis></term>
1247
1248                 <listitem>
1249                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">setcachesize</emphasis>.</para>
1250                 </listitem>
1251               </varlistentry>
1252
1253               <varlistentry>
1254                 <term><emphasis role="bold">0</emphasis></term>
1255
1256                 <listitem>
1257                   <para>Resets the disk cache size to the value in the third field of the <emphasis
1258                   role="bold">/usr/vice/etc/cacheinfo</emphasis> file.</para>
1259                 </listitem>
1260               </varlistentry>
1261
1262               <varlistentry>
1263                 <term><emphasis role="bold">-reset</emphasis></term>
1264
1265                 <listitem>
1266                   <para>Resets the cache size to the value set at the last reboot.</para>
1267                 </listitem>
1268               </varlistentry>
1269             </variablelist></para>
1270         </listitem>
1271       </orderedlist>
1272     </sect2>
1273
1274     <sect2 id="HDRWQ401">
1275       <title>How the Cache Manager Chooses Data to Discard</title>
1276
1277       <para>When the cache is full and application programs request more data from AFS, the Cache Manager must flush out cache
1278       chunks to make room for the data. The Cache Manager considers two factors: <orderedlist>
1279           <listitem>
1280             <para>How recently an application last accessed the data.</para>
1281           </listitem>
1282
1283           <listitem>
1284             <para>Whether the chunk is <emphasis>dirty</emphasis>. A dirty chunk contains changes to a file that have not yet been
1285             saved back to the permanent copy stored on a file server machine.</para>
1286           </listitem>
1287         </orderedlist></para>
1288
1289       <para>The Cache Manager first checks the least-recently used chunk. If it is not dirty, the Cache Manager discards the data in
1290       that chunk. If the chunk is dirty, the Cache Manager moves on to check the next least recently used chunk. It continues in
1291       this manner until it has created a sufficient number of empty chunks.</para>
1292
1293       <para>Chunks that contain data fetched from a read-only volume are by definition never dirty, so the Cache Manager can always
1294       discard them. Normally, the Cache Manager can also find chunks of data fetched from read/write volumes that are not dirty, but
1295       a small cache makes it difficult to find enough eligible data. If the Cache Manager cannot find any data to discard, it must
1296       return I/O errors to application programs that request more data from AFS. Application programs usually have a means for
1297       notifying the user of such errors, but not for revealing their cause.</para>
1298     </sect2>
1299   </sect1>
1300
1301   <sect1 id="HDRWQ402">
1302     <title>Setting Other Cache Parameters with the afsd program</title>
1303
1304     <para>There are only three cache configuration parameters you must set: the mount directory for AFS, the location of the disk
1305     cache directory, and the cache size. They correspond to the three fields in the <emphasis
1306     role="bold">/usr/vice/etc/cacheinfo</emphasis> file, as discussed in <link linkend="HDRWQ394">Determining the Cache Type, Size,
1307     and Location</link>. However, if you want to experiment with fine-tuning cache performance, you can use the arguments on the
1308     <emphasis role="bold">afsd</emphasis> command to control several other parameters. This section discusses a few of these
1309     parameters that have the most direct effect on cache performance. To learn more about the <emphasis role="bold">afsd</emphasis>
1310     command's arguments, see its reference page in the <emphasis>OpenAFS Administration Reference</emphasis>.</para>
1311
1312     <para>In addition, the AFS initialization script included in the AFS distribution for each system type includes several
1313     variables that set several <emphasis role="bold">afsd</emphasis> arguments in a way that is suitable for client machines of
1314     different sizes and usage patterns. For instructions on using the script most effectively, see the section on configuring the
1315     Cache Manager in the <emphasis>OpenAFS Quick Beginnings</emphasis>.</para>
1316
1317     <sect2 id="HDRWQ403">
1318       <title>Setting Cache Configuration Parameters</title>
1319
1320       <para>The cache configuration parameters with the most direct effect on cache performance include the following: <itemizedlist>
1321           <listitem>
1322             <para><emphasis>total cache size</emphasis>. This is the amount of disk space or machine memory available for caching,
1323             as discussed in detail in <link linkend="HDRWQ394">Determining the Cache Type, Size, and Location</link>.</para>
1324           </listitem>
1325
1326           <listitem>
1327             <para><emphasis>number of cache chunks</emphasis>. For a disk cache, each chunk is a <emphasis role="bold">V</emphasis>n
1328             file in the local cache directory (see <link linkend="HDRWQ393">Cache-Related Files</link>). For a memory cache, each
1329             chunk is a set of contiguous blocks allocated in machine memory.</para>
1330
1331             <para>This parameter does not have as much of an effect on cache performance as total size. However, adjusting it can
1332             influence how often the Cache Manager must discard cached data to make room for new data. Suppose, for example, that you
1333             set the disk cache size to 50 MB and the number of chunks (<emphasis role="bold">V</emphasis>n files) to 1,000. If each
1334             of the ten users on the machine caches 100 AFS files that average 20 KB in size, then all 1,000 chunks are full (a chunk
1335             can contain data from only one AFS file) but the cache holds only about 20 MB of data. When a user requests more data
1336             from the File Server, the Cache Manager must discard cached data to reclaim some chunks, even though the cache is filled
1337             to less than 50% of its capacity. In such a situation, increasing the number of chunks enables the Cache Manager to
1338             discard data less often.</para>
1339           </listitem>
1340
1341           <listitem>
1342             <para><emphasis>chunk size</emphasis>. This parameter determines the maximum amount of data that can fit in a chunk. If
1343             a cached element is smaller than the chunk size, the remaining space in the chunk is not used (a chunk can hold no more
1344             than one element). If an element cannot fit in a single chunk, it is split across as many chunks as needed. This
1345             parameter also determines how much data the Cache Manager requests at a time from the File Server (how much data per
1346             <emphasis>fetch RPC</emphasis>, because AFS uses partial file transfer).</para>
1347
1348             <para>The main reason to change chunk size is because of its relation to the amount of data fetched per RPC. If your
1349             network links are very fast, it can improve performance to increase chunk size; if the network is especially slow, it
1350             can make sense to decrease chunk size.</para>
1351           </listitem>
1352
1353           <listitem>
1354             <para><emphasis>number of dcache entries in memory</emphasis>. The Cache Manager maintains one dcache entry for each
1355             cache chunk, recording a small amount of information, such as the file ID (fID) and version number of the AFS file
1356             corresponding to the chunk.</para>
1357
1358             <para>For a disk cache, dcache entries reside in the <emphasis role="bold">/usr/vice/cache/CacheItems</emphasis> file; a
1359             small number are duplicated in machine memory to speed access.</para>
1360
1361             <para>For a memory cache, the number of dcache entries equals the number of cache chunks. For a discussion of the
1362             implications of this correspondence, see <link linkend="HDRWQ405">Controlling Memory Cache Configuration</link>.</para>
1363           </listitem>
1364         </itemizedlist></para>
1365
1366       <para>For a description of how the Cache Manager determines defaults for number of chunks, chunk size, and number of dcache
1367       entries in a disk cache, see <link linkend="HDRWQ404">Configuring a Disk Cache</link>; for a memory cache, see <link
1368       linkend="HDRWQ405">Controlling Memory Cache Configuration</link>. The instructions also explain how to use the <emphasis
1369       role="bold">afsd</emphasis> command's arguments to override the defaults.</para>
1370     </sect2>
1371
1372     <sect2 id="HDRWQ404">
1373       <title>Configuring a Disk Cache</title>
1374
1375       <para>The default number of cache chunks (<emphasis role="bold">V</emphasis>n files) in a disk cache is calculated by the
1376       <emphasis role="bold">afsd</emphasis> command to be the greatest of the following: <itemizedlist>
1377           <listitem>
1378             <para>100</para>
1379           </listitem>
1380
1381           <listitem>
1382             <para>1.5 times the result of dividing cache size by chunk size (cachesize/chunksize * 1.5)</para>
1383           </listitem>
1384
1385           <listitem>
1386             <para>The result of dividing cachesize by 10 MB (cachesize/10240)</para>
1387           </listitem>
1388         </itemizedlist></para>
1389
1390       <para>You can override this value by specifying a positive integer with the <emphasis role="bold">-files</emphasis> argument.
1391       Consider increasing this value if more than 75% of the <emphasis role="bold">V</emphasis>n files are already used soon after
1392       the Cache Manager finishes initializing. Consider decreasing it if only a small percentage of the chunks are used at that
1393       point. In any case, never specify a value less than 100, because a smaller value can cause performance problems.</para>
1394
1395       <para>The following example sets the number of <emphasis role="bold">V</emphasis>n files to 2,000:</para>
1396
1397       <programlisting>
1398         <emphasis role="bold">/usr/vice/etc/afsd -files 2000</emphasis>
1399       </programlisting>
1400
1401       <note>
1402         <para>It is conventional to place the <emphasis role="bold">afsd</emphasis> command in a machine's AFS initialization file,
1403         rather than entering it in a command shell. Furthermore, the values specified in this section are examples only, and are not
1404         necessarily suitable for a specific machine.</para>
1405       </note>
1406
1407       <para>The default chunk size for a disk cache is 64 KB. In general, the only reason to change it is to adjust to exceptionally
1408       slow or fast networks; see <link linkend="HDRWQ403">Setting Cache Configuration Parameters</link>. You can use the <emphasis
1409       role="bold">-chunksize</emphasis> argument to override the default. Chunk size must be a power of 2, so provide an integer
1410       between 0 (zero) and 30 to be used as an exponent of 2. For example, a value of 10 sets chunk size to 1 KB (210 = 1024); a
1411       value of 16 equals the default for disk caches (216 = 64 KB). Specifying a value of 0 (zero) or greater than 30 returns chunk
1412       size to the default. Values less than 10 (1 KB) are not recommended. The following example sets chunk size to 16 KB
1413       (214):</para>
1414
1415       <programlisting>
1416         <emphasis role="bold">/usr/vice/etc/afsd -chunksize 14</emphasis>
1417       </programlisting>
1418
1419       <para>For a disk cache, the default number of dcache entries duplicated in memory is one-half the number of chunks specified
1420       with the <emphasis role="bold">-files</emphasis> argument, to a maximum of 2,000 entries. You can use the <emphasis
1421       role="bold">-dcache</emphasis> argument to change the default, even exceeding 2,000 if you wish. Duplicating more than half
1422       the dcache entries in memory is not usually necessary, but sometimes improves performance slightly, because access to memory
1423       is faster than access to disk. The following example sets the number to 750:</para>
1424
1425       <programlisting>
1426         <emphasis role="bold">/usr/vice/etc/afsd -dcache 750</emphasis>
1427       </programlisting>
1428
1429       <para>When configuring a disk cache, you can combine the <emphasis role="bold">afsd</emphasis> command's arguments in any way.
1430       The main reason for this flexibility is that the setting you specify for disk cache size (in the <emphasis
1431       role="bold">cacheinfo</emphasis> file or with the <emphasis role="bold">-blocks</emphasis> argument) is an absolute maximum
1432       limit. You cannot override it by specifying higher values for the <emphasis role="bold">-files</emphasis> or <emphasis
1433       role="bold">-chunksize</emphasis> arguments, alone or in combination. A related reason is that the Cache Manager does not have
1434       to reserve a set amount of memory on disk. <emphasis role="bold">V</emphasis>n files (the chunks in a disk cache) are
1435       initially zero-length, but can expand up to the specified chunk size and shrink again, as needed. If you set the number of
1436       <emphasis role="bold">V</emphasis>n files to such a large value that expanding all of them to the full allowable size exceeds
1437       the total cache size, they simply never grow to full size.</para>
1438     </sect2>
1439
1440     <sect2 id="HDRWQ405">
1441       <title>Controlling Memory Cache Configuration</title>
1442
1443       <para>Configuring a memory cache differs from configuring a disk cache in that not all combinations of the <emphasis
1444       role="bold">afsd</emphasis> command's arguments are allowed. This limitation results from the greater interaction between the
1445       configuration parameters in a memory cache than a disk cache. If all combinations are allowed, it is possible to set the
1446       parameters in an inconsistent way. A list of the acceptable and unacceptable combinations follows a discussion of default
1447       values.</para>
1448
1449       <para>The default chunk size for a memory cache is 8 KB. In general, the only reason to change it is to adjust to
1450       exceptionally slow or fast networks; see <link linkend="HDRWQ403">Setting Cache Configuration Parameters</link>.</para>
1451
1452       <para>There is no predefined default for number of chunks in a memory cache. The Cache Manager instead calculates the correct
1453       number by dividing the total cache size by the chunk size. Recall that for a memory cache, all dcache entries must be in
1454       memory. This implies that the number of chunks equals the number of dcache entries in memory, and that there is no default for
1455       number of dcache entries (like the number of chunks, it is calculated by dividing the total size by the chunk size).</para>
1456
1457       <para>The following are acceptable combinations of the <emphasis role="bold">afsd</emphasis> command's arguments when
1458       configuring a memory cache: <itemizedlist>
1459           <listitem>
1460             <para><emphasis role="bold">-blocks</emphasis> alone, which overrides the cache size specified in the <emphasis
1461             role="bold">/usr/vice/etc/cacheinfo</emphasis> file. The Cache Manager divides the value of this argument by the default
1462             chunk size of eight KB to calculate the number of chunks and dcache entries. The following example sets cache size to
1463             five MB (5,120 KB) and the number of chunks to 640 (5,120 divided by 8): <programlisting><emphasis role="bold">/usr/vice/etc/afsd -memcache -blocks 5120</emphasis></programlisting></para>
1464           </listitem>
1465
1466           <listitem>
1467             <para><emphasis role="bold">-chunksize</emphasis> alone, to override the default of eight KB. The chunk size must be a
1468             power of two, so provide an integer between 0 (zero) and 30 to be used as an exponent of two. For example, a value of
1469             ten sets chunk size to 1 KB (210 = 1024); a value of 13 equals the default for memory caches (213 = 8 KB). Specifying a
1470             value of 0 (zero) or greater than 30 returns the chunk size to the default. Values less than ten (equivalent to 1 KB)
1471             are not recommended. The following example sets the chunk size to four KB (212). Assuming a total cache size of four MB
1472             (4,096 KB), the resulting number of chunks is 1024. <programlisting><emphasis role="bold">/usr/vice/etc/afsd -memcache -chunksize 12</emphasis></programlisting></para>
1473           </listitem>
1474
1475           <listitem>
1476             <para><emphasis role="bold">-blocks</emphasis> and <emphasis role="bold">-chunksize</emphasis> together override the
1477             defaults for cache size and chunk size. The Cache Manager divides the first by the second to calculate the number of
1478             chunks and dcache entries. For example, the following example sets the cache size to six MB (6,144 KB) and chunksize to
1479             four KB (212), resulting in 1,536 chunks: <programlisting><emphasis role="bold">/usr/vice/etc/afsd -memcache -blocks 6144 -chunksize 12</emphasis></programlisting></para>
1480           </listitem>
1481         </itemizedlist></para>
1482
1483       <para>The following arguments or combinations explicitly set the number of chunks and dcache entries. It is best not to use
1484       them, because they set the cache size indirectly, forcing you to perform a hand calculation to determine the size of the
1485       cache. Instead, set the <emphasis role="bold">-blocks</emphasis> and <emphasis role="bold">-chunksize</emphasis> arguments
1486       alone or in combination; in those cases, the Cache Manager determines the number of chunks and dcache entries itself. Because
1487       the following combinations are not recommended, no examples are included. <itemizedlist>
1488           <listitem>
1489             <para>The <emphasis role="bold">-dcache</emphasis> argument alone explicitly sets the number of chunks and dcache
1490             entries. The Cache Manager multiples this value times the default chunk size of 8 KB to derive the total cache size
1491             (overriding the value in the <emphasis role="bold">cacheinfo</emphasis> file).</para>
1492           </listitem>
1493
1494           <listitem>
1495             <para>The combination of <emphasis role="bold">-dcache</emphasis> and <emphasis role="bold">-chunksize</emphasis> sets
1496             the chunk number and size. The Cache Manager sets the specified values and multiplies them together to obtain total
1497             cache size (overriding the value in the <emphasis role="bold">cacheinfo</emphasis> file).</para>
1498           </listitem>
1499         </itemizedlist></para>
1500
1501       <para>Do not use the following arguments for a memory cache: <itemizedlist>
1502           <listitem>
1503             <para><emphasis role="bold">-files</emphasis> alone. This argument controls the number of <emphasis
1504             role="bold">V</emphasis>n files for a disk cache, but is ignored for a memory cache.</para>
1505           </listitem>
1506
1507           <listitem>
1508             <para><emphasis role="bold">-blocks</emphasis> and <emphasis role="bold">-dcache</emphasis>. An error message results,
1509             because it is possible to provide values such that dividing the first (total size) by the second (number of chunks)
1510             results in a chunk size that is not a power of two.</para>
1511           </listitem>
1512         </itemizedlist></para>
1513     </sect2>
1514
1515
1516     <sect2 id="tuning-cache-configuration">
1517       <title>Tuning Cache Configuration</title>
1518
1519       <indexterm>
1520         <primary>cache</primary>
1521         <secondary>tuning</secondary>
1522       </indexterm>
1523
1524       <indexterm>
1525         <primary>performance</primary>
1526         <secondary>cache</secondary>
1527       </indexterm>
1528
1529       <para>
1530         Tuning the parameters of the OpenAFS cache for optimal performance
1531         is highly dependent on the behavior of applications and users on a
1532         client machine. The default options may perform poorly under
1533         certain conditions.
1534       </para>
1535
1536       <para>
1537         The <emphasis role="bold">xstat_cm_test</emphasis> command is
1538         useful for measuring how effectively the cache is operating. The
1539         following procedure may be used to aide in tuning the parameters
1540         for the data cache (dcache) and the stats cache (vcache):
1541         <orderedlist>
1542           <listitem>
1543             <para>
1544               Run the following command and replace "hostname" with the hostname of the machine to be measured:
1545               <programlisting>
1546                 <emphasis role="bold">xstat_cm_test hostname 2 -onceonly</emphasis>
1547               </programlisting>
1548             </para>
1549             <para>
1550               Take note of the following fields: dcacheHits, dcacheMisses,
1551               vcacheHits, and vcacheMisses. Saving the above command
1552               output to a file or filtering it using grep is advised.
1553             </para>
1554           </listitem>
1555           <listitem>
1556             <para>
1557               Using the noted fields, compute the miss ratios for the
1558               dcache and vcache using the following formulas:
1559               <programlisting>
1560                 <emphasis role="bold">
1561                   dcache miss ratio = dcacheMisses / ( dcacheMisses + dcacheHits )
1562                 </emphasis>
1563               </programlisting>
1564               <programlisting>
1565                 <emphasis role="bold">
1566                   vcache miss ratio = vcacheMisses / ( vcacheMisses + vcacheHits )
1567                 </emphasis>
1568               </programlisting>
1569               As a guideline, a miss ratio of 0.05 (5 percent) or less is
1570               acceptable and a miss ratio of 0.01 (1 percent) or less is
1571               recommended.
1572             </para>
1573           </listitem>
1574           <listitem>
1575             <para>
1576               If your dcache miss ratio is too large, then cache
1577               performance is likely to improve if the data cache is made
1578               larger. If the vcache miss ratio is too large, then increase
1579               the size of the stat cache using
1580               the <emphasis role="bold">-stat</emphasis> parameter
1581               to <emphasis role="bold">afsd</emphasis> for a Unix-based
1582               client or using the Control Panel or registry interfaces on
1583               Microsoft Windows-based clients. The default size of the
1584               stat cache is 10,000 entries on windows platforms and 300
1585               entries on Unix platforms. There may be a significant
1586               performance penalty when the vcache size is much smaller
1587               than the working set of commonly accessed files. On the
1588               fileserver, the number of callbacks should be more than the
1589               size of the vcache of any client that connects to the
1590               server. If the cache is too small or there aren't enough
1591               callbacks (<emphasis role="bold">-cb</emphasis>) on the
1592               fileserver, then the cached entries will be discarded
1593               prematurely, causing thrashing.
1594               <tip>
1595                 <para>
1596                   As an example of how the wrong vcache size can degrade
1597                   performance, one OpenAFS site had performance issues
1598                   with the Apache and mod_php software on a Unix web
1599                   server serving web pages directly out of AFS. During
1600                   peak times, the load on the server would spike with an
1601                   excess of Apache processes. After profiling, it was
1602                   found that Apache and PHP made lots
1603                   of <emphasis role="bold">stat()</emphasis> library calls
1604                   and that the default vcache size of 300 was too
1605                   small. After some experimentation, a vcache size of
1606                   50,000 was found to improve performance. This size makes
1607                   sense in light of that fact that the total number of
1608                   files in the website exceeded 350,000, including 50,000
1609                   PHP files. The number of callbacks configured on the
1610                   fileserver was 1,500,000, so the vcache size was not too
1611                   large.
1612                 </para>
1613               </tip>
1614             </para>
1615           </listitem>
1616           <listitem>
1617             <para>
1618               After changing your configuration appropriately and
1619               restarting the AFS client service, wait until enough data
1620               has been collected before changing the configuration
1621               further. The sum of the hits and misses should be at least
1622               five times the value of the configured parameter before
1623               making further adjustments. Repeat this process until the
1624               desired miss ratio is achieved. Take note that the numbers
1625               from the <emphasis role="bold">xstat_cm_test</emphasis>
1626               command only reset when the client is restarted. If multiple
1627               samples are taken, then subtract the previous measurement
1628               from the current measurement to accurately measure the
1629               activity that happened between the samples.
1630             </para>
1631           </listitem>
1632         </orderedlist>
1633       </para>
1634     </sect2>
1635   </sect1>
1636
1637
1638   <sect1 id="HDRWQ406">
1639     <title>Maintaining Knowledge of Database Server Machines</title>
1640
1641     <indexterm>
1642       <primary>CellServDB file (client)</primary>
1643
1644       <secondary>about</secondary>
1645     </indexterm>
1646
1647     <indexterm>
1648       <primary>files</primary>
1649
1650       <secondary>CellServDB file (client)</secondary>
1651     </indexterm>
1652
1653     <indexterm>
1654       <primary>database server machine</primary>
1655
1656       <secondary>client knowledge of</secondary>
1657     </indexterm>
1658
1659     <indexterm>
1660       <primary>client machine</primary>
1661
1662       <secondary>database server processes, contacting</secondary>
1663     </indexterm>
1664
1665     <indexterm>
1666       <primary>Cache Manager</primary>
1667
1668       <secondary>database server processes, contacting</secondary>
1669     </indexterm>
1670
1671     <indexterm>
1672       <primary>Cache Manager</primary>
1673
1674       <secondary>CellServDB file (client), using</secondary>
1675     </indexterm>
1676
1677     <indexterm>
1678       <primary>command interpreters</primary>
1679
1680       <secondary>CellServDB file (client), using</secondary>
1681     </indexterm>
1682
1683     <indexterm>
1684       <primary>CellServDB file (client)</primary>
1685
1686       <secondary>copied into kernel memory</secondary>
1687     </indexterm>
1688
1689     <indexterm>
1690       <primary>kernel memory (client)</primary>
1691
1692       <secondary>CellServDB file, reading into</secondary>
1693     </indexterm>
1694
1695     <para>For the users of an AFS client machine to access a cell's AFS filespace and other services, the Cache Manager and other
1696     client-side agents must have an accurate list of the cell's database server machines. The affected functions include the
1697     following: <itemizedlist>
1698         <listitem>
1699           <para>Accessing files. The Cache Manager contacts the Volume Location (VL) Server to learn which file server machine
1700           houses the volume containing a requested file or directory. If the Cache Manager cannot contact a cell's VL Servers, it
1701           cannot fetch files.</para>
1702         </listitem>
1703
1704         <listitem>
1705           <para>Authenticating. The <emphasis role="bold">klog</emphasis> program and AFS-modified login utilities contact the
1706           Authentication Server to obtain tokens, which the AFS server processes accept as proof that the user is
1707           authenticated.</para>
1708         </listitem>
1709
1710         <listitem>
1711           <para>Creating protection groups. The <emphasis role="bold">pts</emphasis> command interpreter contacts the Protection
1712           Server when users create protection groups or request information from the Protection Database.</para>
1713         </listitem>
1714
1715         <listitem>
1716           <para>Editing access control lists (ACLs). The <emphasis role="bold">fs</emphasis> command interpreter contacts the File
1717           Server that maintains the read/write volume containing a file or directory; the location information comes from the VL
1718           Server.</para>
1719         </listitem>
1720       </itemizedlist></para>
1721
1722     <para>To enable a machine's users to access a cell, you must list the names and IP addresses of its database server machines in
1723     the <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file on the machine's local disk. In addition to the machine's
1724     home cell, you can list any foreign cells that you want to enable users to access. (To enable access to a cell's filespace, you
1725     must also mount its <emphasis role="bold">root.cell</emphasis> volume in the local AFS filespace; the conventional location is
1726     just under the AFS root directory, <emphasis role="bold">/afs</emphasis>. For instructions, see the <emphasis>OpenAFS Quick
1727     Beginnings</emphasis>.)</para>
1728
1729     <sect2 id="Header_451">
1730       <title>How Clients Use the List of Database Server Machines</title>
1731
1732       <para>As the <emphasis role="bold">afsd</emphasis> program runs and initializes the Cache Manager, it reads the contents of
1733       the <emphasis role="bold">CellServDB</emphasis> file into kernel memory. The Cache Manager does not consult the file again
1734       until the machine next reboots. In contrast, the command interpreters for the AFS command suites (such as <emphasis
1735       role="bold">fs</emphasis> and <emphasis role="bold">pts</emphasis>) read the <emphasis role="bold">CellServDB</emphasis> file
1736       each time they need to contact a database server process.</para>
1737
1738       <para>When a cell's list of database server machines changes, you must change both the <emphasis
1739       role="bold">CellServDB</emphasis> file and the list in kernel memory to preserve consistent client performance; some commands
1740       probably fail if the two lists of machines disagree. One possible method for updating both the <emphasis
1741       role="bold">CellServDB</emphasis> file and kernel memory is to edit the file and reboot the machine. To avoid needing to
1742       reboot, you can instead perform both of the following steps: <orderedlist>
1743           <listitem>
1744             <para>Issue the <emphasis role="bold">fs newcell</emphasis> command to alter the list in kernel memory directly, making
1745             the changes available to the Cache Manager.</para>
1746           </listitem>
1747
1748           <listitem>
1749             <para>Edit the <emphasis role="bold">CellServDB</emphasis> file to make the changes available to command interpreters.
1750             For a description of the file's format, see <link linkend="HDRWQ407">The Format of the CellServDB file</link>.</para>
1751           </listitem>
1752         </orderedlist></para>
1753
1754       <para>The consequences of missing or incorrect information in the <emphasis role="bold">CellServDB</emphasis> file or kernel
1755       memory are as follows: <itemizedlist>
1756           <listitem>
1757             <para>If there is no entry for a cell, the machine's users cannot access the cell.</para>
1758           </listitem>
1759
1760           <listitem>
1761             <para>If a cell's entry does not include a database server machine, then the Cache Manager and command interpreters
1762             never attempt to contact the machine. The omission does not prevent access to the cell--as long as the information about
1763             the other database server machines is correct and the server processes, machines, and network are functioning
1764             correctly--but it can put an undue burden on the machines that are listed. If all of the listed machines become
1765             inaccessible to clients, then the cell becomes inaccessible even if the omitted database server machine is functioning
1766             correctly.</para>
1767           </listitem>
1768
1769           <listitem>
1770             <para>If a machine's name or address is incorrect, or the machine is not actually running the database server processes,
1771             then requests from clients time out. Users can experience lengthy delays because they have to wait the full timeout
1772             period before the Cache Manager or command interpreter contacts another database server machine.</para>
1773           </listitem>
1774         </itemizedlist></para>
1775     </sect2>
1776
1777     <sect2 id="HDRWQ407">
1778       <title>The Format of the CellServDB file</title>
1779
1780       <indexterm>
1781         <primary>CellServDB file (client)</primary>
1782
1783         <secondary>correct format</secondary>
1784       </indexterm>
1785
1786       <indexterm>
1787         <primary>format of CellServDB file (client)</primary>
1788       </indexterm>
1789
1790       <para>When editing the <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file, you must use the correct format for
1791       cell and machine entries. Each cell has a separate entry. The first line has the following format:</para>
1792
1793       <programlisting>
1794    &gt;cell_name      #organization
1795 </programlisting>
1796
1797       <para>where cell_name is the cell's complete Internet domain name (for example, <emphasis role="bold">abc.com</emphasis>) and
1798       organization is an optional field that follows any number of spaces and the number sign (<computeroutput>#</computeroutput>)
1799       and can name the organization to which the cell corresponds (for example, the ABC Corporation). After the first line comes a
1800       separate line for each database server machine. Each line has the following format:</para>
1801
1802       <programlisting>
1803    IP_address   #machine_name
1804 </programlisting>
1805
1806       <para>where IP_address is the machine's IP address in dotted decimal format (for example, 192.12.105.3). Following any number
1807       of spaces and the number sign (<computeroutput>#</computeroutput>) is machine_name, the machine's fully-qualified hostname
1808       (for example, <emphasis role="bold">db1.abc.com</emphasis>). In this case, the number sign does not indicate a comment:
1809       machine_name is a required field.</para>
1810
1811       <para>The order in which the cells appear is not important, but it is convenient to put the client machine's home cell first.
1812       Do not include any blank lines in the file, not even after the last entry.</para>
1813
1814       <para>The following example shows entries for two cells, each of which has three database server machines:</para>
1815
1816       <programlisting>
1817    &gt;abc.com       #ABC Corporation (home cell)
1818    192.12.105.3      #db1.abc.com
1819    192.12.105.4      #db2.abc.com
1820    192.12.105.55     #db3.abc.com
1821    &gt;stateu.edu    #State University cell
1822    138.255.68.93     #serverA.stateu.edu
1823    138.255.68.72     #serverB.stateu.edu
1824    138.255.33.154    #serverC.stateu.edu
1825 </programlisting>
1826     </sect2>
1827
1828     <sect2 id="HDRWQ408">
1829       <title>Maintaining the Client CellServDB File</title>
1830
1831       <indexterm>
1832         <primary>maintaining</primary>
1833
1834         <secondary>CellServDB file (client)</secondary>
1835       </indexterm>
1836
1837       <indexterm>
1838         <primary>CellServDB file (client)</primary>
1839
1840         <secondary>maintaining</secondary>
1841       </indexterm>
1842
1843       <para>Because a correct entry in the <emphasis role="bold">CellServDB</emphasis> file is vital for consistent client
1844       performance, you must also update the file on each client machine whenever a cell's list of database server machines changes
1845       (for instance, when you follow the instructions in the <emphasis>OpenAFS Quick Beginnings</emphasis> to add or remove a
1846       database server machine). To facilitate the client updates, you can use the <emphasis role="bold">package</emphasis> program,
1847       which copies files from a central source in AFS to the local disk of client machines. It is conventional to invoke the
1848       <emphasis role="bold">package</emphasis> program in a client machine's AFS initialization file so that it runs as the machine
1849       reboots, but you can also issue the <emphasis role="bold">package</emphasis> command at any time. For instructions, see <link
1850       linkend="HDRWQ448">Running the package program</link>.</para>
1851
1852       <para>If you use the <emphasis role="bold">package</emphasis> program, the conventional location for your cell's central
1853       source <emphasis role="bold">CellServDB</emphasis> file is <emphasis role="bold">/afs/</emphasis>cell_name<emphasis
1854       role="bold">/common/etc/CellServDB</emphasis>, where cell_name is your cell name. <indexterm>
1855           <primary>CellServDB file (client)</primary>
1856
1857           <secondary>central update source for clients</secondary>
1858         </indexterm></para>
1859
1860       <para>Creating a symbolic or hard link from <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> to a central source file
1861       in AFS is not a viable option. The <emphasis role="bold">afsd</emphasis> program reads the file into kernel memory before the
1862       Cache Manager is completely initialized and able to access AFS.</para>
1863
1864       <para>Because every client machine has its own copy of the <emphasis role="bold">CellServDB</emphasis> file, you can in theory
1865       make the set of accessible cells differ on various machines. In most cases, however, it is best to maintain consistency
1866       between the files on all client machines in the cell: differences between machines are particularly confusing if users
1867       commonly use a variety of machines rather than just one.</para>
1868
1869       <para>The AFS Product Support group maintains a central <emphasis role="bold">CellServDB</emphasis> file that includes all
1870       cells that have agreed to make their database server machines access to other AFS cells. It is advisable to check this file
1871       periodically for updated information. See <link linkend="HDRWQ38">Making Your Cell Visible to Others</link>. <indexterm>
1872           <primary>CellServDB file (client)</primary>
1873
1874           <secondary>global source from AFS Support</secondary>
1875         </indexterm></para>
1876
1877       <para>An entry in the local <emphasis role="bold">CellServDB</emphasis> is one of the two requirements for accessing a cell.
1878       The other is that the cell's <emphasis role="bold">root.cell</emphasis> volume is mounted in the local filespace, by
1879       convention as a subdirectory of the <emphasis role="bold">/afs</emphasis> directory. For instructions, see <link
1880       linkend="HDRWQ213">To create a cellular mount point</link>.</para>
1881
1882       <note>
1883         <para>The <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file on a client machine is not the same as the
1884         <emphasis role="bold">/usr/afs/etc/CellServDB</emphasis> file on the local disk of a file server machine. The server version
1885         lists only the database server machines in the server machine's home cell, because server processes never need to contact
1886         foreign cells. It is important to update both types of <emphasis role="bold">CellServDB</emphasis> file on all machines in
1887         the cell whenever there is a change to your cell's database server machines. For more information about maintaining the
1888         server version of the <emphasis role="bold">CellServDB</emphasis> file, see <link linkend="HDRWQ118">Maintaining the Server
1889         CellServDB File</link>.</para>
1890       </note>
1891
1892       <indexterm>
1893         <primary>CellServDB file (client)</primary>
1894
1895         <secondary>displaying</secondary>
1896       </indexterm>
1897
1898       <indexterm>
1899         <primary>displaying</primary>
1900
1901         <secondary>CellServDB file (client)</secondary>
1902       </indexterm>
1903
1904       <indexterm>
1905         <primary>database server machine</primary>
1906
1907         <secondary>CellServDB file (client), displaying</secondary>
1908       </indexterm>
1909
1910       <indexterm>
1911         <primary>client machine</primary>
1912
1913         <secondary>CellServDB file, displaying</secondary>
1914       </indexterm>
1915
1916       <indexterm>
1917         <primary>client machine</primary>
1918
1919         <secondary>database server machines, displaying knowledge of</secondary>
1920       </indexterm>
1921     </sect2>
1922
1923     <sect2 id="Header_454">
1924       <title>To display the /usr/vice/etc/CellServDB file</title>
1925
1926       <orderedlist>
1927         <listitem>
1928           <para>Use a text editor or the <emphasis role="bold">cat</emphasis> command to display the contents of the <emphasis
1929           role="bold">/usr/vice/etc/CellServDB</emphasis> file. By default, the mode bits on the file permit anyone to read it.
1930           <programlisting>
1931    % <emphasis role="bold">cat /usr/vice/etc/CellServDB</emphasis>
1932 </programlisting></para>
1933         </listitem>
1934       </orderedlist>
1935
1936       <indexterm>
1937         <primary>fs commands</primary>
1938
1939         <secondary>listcells</secondary>
1940       </indexterm>
1941
1942       <indexterm>
1943         <primary>commands</primary>
1944
1945         <secondary>fs listcells</secondary>
1946       </indexterm>
1947     </sect2>
1948
1949     <sect2 id="Header_455">
1950       <title>To display the list of database server machines in kernel memory</title>
1951
1952       <orderedlist>
1953         <listitem>
1954           <para>Issue the <emphasis role="bold">fs listcells</emphasis> command. <programlisting>
1955    % <emphasis role="bold">fs listcells [&amp;]</emphasis> 
1956 </programlisting></para>
1957
1958           <para>where <emphasis role="bold">listc</emphasis> is the shortest acceptable abbreviation of <emphasis
1959           role="bold">listcells</emphasis>.</para>
1960
1961           <para>To have your shell prompt return immediately, include the ampersand (<emphasis role="bold">&amp;</emphasis>), which
1962           makes the command run in the background. It can take a while to generate the complete output because the kernel stores
1963           database server machines' IP addresses only, and the <emphasis role="bold">fs</emphasis> command interpreter has the
1964           cell's name resolution service (such as the Domain Name Service or a local host table) translate them into hostnames. You
1965           can halt the command at any time by issuing an interrupt signal such as <emphasis role="bold">Ctrl-c</emphasis>.</para>
1966
1967           <para>The output includes a single line for each cell, in the following format:</para>
1968
1969           <programlisting>
1970    Cell cell_name on hosts list_of_hostnames.
1971 </programlisting>
1972
1973           <para>The name service sometimes returns hostnames in uppercase letters, and if it cannot resolve a name at all, it
1974           returns its IP address. The following example illustrates all three possibilities:</para>
1975
1976           <programlisting>
1977    % <emphasis role="bold">fs listcells</emphasis>
1978       .
1979       .
1980    Cell abc.com on hosts db1.abc.com db2.abc.com db3.abc.com
1981    Cell stateu.edu on hosts SERVERA.STATEU.EDU SERVERB.STATEU.EDU 
1982                             SERVERC.STATEU.EDU
1983    Cell ghi.org on hosts 191.255.64.111 191.255.64.112
1984       .
1985       .
1986 </programlisting>
1987         </listitem>
1988       </orderedlist>
1989
1990       <indexterm>
1991         <primary>adding</primary>
1992
1993         <secondary>database server machine</secondary>
1994
1995         <tertiary>to client CellServDB file and kernel memory</tertiary>
1996       </indexterm>
1997
1998       <indexterm>
1999         <primary>removing</primary>
2000
2001         <secondary>database server machine</secondary>
2002
2003         <tertiary>from client CellServDB file and kernel memory</tertiary>
2004       </indexterm>
2005
2006       <indexterm>
2007         <primary>database server machine</primary>
2008
2009         <secondary>adding</secondary>
2010
2011         <tertiary>to client CellServDB file and kernel memory</tertiary>
2012       </indexterm>
2013
2014       <indexterm>
2015         <primary>database server machine</primary>
2016
2017         <secondary>removing</secondary>
2018
2019         <tertiary>from client CellServDB file and kernel memory</tertiary>
2020       </indexterm>
2021
2022       <indexterm>
2023         <primary>client machine</primary>
2024
2025         <secondary>changing list of cells in kernel memory</secondary>
2026       </indexterm>
2027
2028       <indexterm>
2029         <primary>cell</primary>
2030
2031         <secondary>changing list in client kernel memory</secondary>
2032       </indexterm>
2033
2034       <indexterm>
2035         <primary>client machine</primary>
2036
2037         <secondary>changing CellServDB file</secondary>
2038       </indexterm>
2039
2040       <indexterm>
2041         <primary>CellServDB file (client)</primary>
2042
2043         <secondary>changing</secondary>
2044       </indexterm>
2045
2046       <indexterm>
2047         <primary>package</primary>
2048
2049         <secondary>to update client</secondary>
2050       </indexterm>
2051
2052       <indexterm>
2053         <primary>CellServDB file (client)</primary>
2054
2055         <secondary>updating with or without package</secondary>
2056       </indexterm>
2057
2058       <indexterm>
2059         <primary>updating</primary>
2060
2061         <secondary>CellServDB file (client) with or without package</secondary>
2062       </indexterm>
2063     </sect2>
2064
2065     <sect2 id="Header_456">
2066       <title>To change the list of a cell's database server machines in kernel memory</title>
2067
2068       <orderedlist>
2069         <listitem>
2070           <para>Become the local superuser <emphasis role="bold">root</emphasis> on the machine, if you are not already, by issuing
2071           the <emphasis role="bold">su</emphasis> command. <programlisting>
2072    % <emphasis role="bold">su root</emphasis>
2073    Password: &lt;<replaceable>root_password</replaceable>&gt;
2074 </programlisting></para>
2075         </listitem>
2076
2077         <listitem>
2078           <para>If you a use a central copy of the <emphasis role="bold">CellServDB</emphasis> file as a source for client machines,
2079           verify that its directory's ACL grants you the <emphasis role="bold">l</emphasis> (<emphasis
2080           role="bold">lookup</emphasis>), <emphasis role="bold">r</emphasis> (<emphasis role="bold">read</emphasis>), and <emphasis
2081           role="bold">w</emphasis> (<emphasis role="bold">write</emphasis>) permissions. The conventional directory is <emphasis
2082           role="bold">/afs/</emphasis>cell_name<emphasis role="bold">/common/etc</emphasis>. If necessary, issue the <emphasis
2083           role="bold">fs listacl</emphasis> command, which is fully described in <link linkend="HDRWQ572">Displaying ACLs</link>.
2084           <programlisting>
2085    # <emphasis role="bold">fs listacl</emphasis> [&lt;<replaceable>dir/file path</replaceable>&gt;]
2086 </programlisting> <indexterm>
2087               <primary>fs commands</primary>
2088
2089               <secondary>newcell</secondary>
2090             </indexterm> <indexterm>
2091               <primary>commands</primary>
2092
2093               <secondary>fs newcell</secondary>
2094             </indexterm></para>
2095         </listitem>
2096
2097         <listitem>
2098           <para><anchor id="LINEWCELL" />Issue the <emphasis role="bold">fs newcell</emphasis> command to add or change a cell's
2099           entry in kernel memory. Repeat the command for each cell.</para>
2100
2101           <note>
2102             <para>You cannot use this command to remove a cell's entry completely from kernel memory. In the rare cases when you
2103             urgently need to prevent access to a specific cell, you must edit the <emphasis role="bold">CellServDB</emphasis> file
2104             and reboot the machine.</para>
2105           </note>
2106
2107           <programlisting>
2108    # <emphasis role="bold">fs newcell</emphasis> &lt;<replaceable>cell name</replaceable>&gt; &lt;<replaceable>primary servers</replaceable>&gt;+ \
2109                 [<emphasis role="bold">-linkedcell</emphasis> &lt;<replaceable>linked cell name</replaceable>&gt;]
2110 </programlisting>
2111
2112           <para>where <variablelist>
2113               <varlistentry>
2114                 <term><emphasis role="bold">n</emphasis></term>
2115
2116                 <listitem>
2117                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">newcell</emphasis>.</para>
2118                 </listitem>
2119               </varlistentry>
2120
2121               <varlistentry>
2122                 <term><emphasis role="bold">cell name</emphasis></term>
2123
2124                 <listitem>
2125                   <para>Specifies the complete Internet domain name of the cell for which to record a new list of database server
2126                   machines.</para>
2127                 </listitem>
2128               </varlistentry>
2129
2130               <varlistentry>
2131                 <term><emphasis role="bold">primary servers</emphasis></term>
2132
2133                 <listitem>
2134                   <para>Specifies the fully-qualified hostname or IP address in dotted-decimal format for each database server
2135                   machine in the cell. The list you provide completely replaces the existing list.</para>
2136                 </listitem>
2137               </varlistentry>
2138
2139               <varlistentry>
2140                 <term><emphasis role="bold">-linkedcell</emphasis></term>
2141
2142                 <listitem>
2143                   <para>Specifies the complete Internet domain name of the AFS cell to link to a DCE cell for the purposes of DFS
2144                   fileset location. You can use this argument if the machine's AFS users access DFS via the AFS/DFS Migration
2145                   Toolkit Protocol Translator. For instructions, see the <emphasis>OpenAFS/DFS Migration Toolkit Administration
2146                   Guide and Reference</emphasis>.</para>
2147                 </listitem>
2148               </varlistentry>
2149             </variablelist></para>
2150         </listitem>
2151
2152         <listitem>
2153           <para>Add or edit the cell's entry in the local <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file, using one
2154           of the following three methods. In each case, be sure to obey the formatting requirements described in <link
2155           linkend="HDRWQ407">The Format of the CellServDB file</link>. <itemizedlist>
2156               <listitem>
2157                 <para>If you maintain a central source version of the <emphasis role="bold">CellServDB</emphasis> file and use the
2158                 <emphasis role="bold">package</emphasis> program, first use a text editor to alter the central copy of the file.
2159                 Then issue the <emphasis role="bold">package</emphasis> command to transfer the contents of the file to the local
2160                 machine. For complete instructions, see <link linkend="HDRWQ448">Running the package program</link>.
2161                 <programlisting>
2162    # <emphasis role="bold">/etc/package -v -c</emphasis> &lt;<replaceable>name of package file</replaceable>&gt;
2163 </programlisting></para>
2164               </listitem>
2165
2166               <listitem>
2167                 <para>If you maintain a central source <emphasis role="bold">CellServDB</emphasis> file but do not use the <emphasis
2168                 role="bold">package</emphasis> program, first use a text editor to alter the central copy of the file. Then use a
2169                 copying command such as the <emphasis role="bold">cp</emphasis> command to copy it to the local <emphasis
2170                 role="bold">/usr/vice/etc/CellServDB</emphasis> file.</para>
2171               </listitem>
2172
2173               <listitem>
2174                 <para>If you do not use a central source <emphasis role="bold">CellServDB</emphasis> file, edit the local machine's
2175                 <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file directly.</para>
2176               </listitem>
2177             </itemizedlist></para>
2178         </listitem>
2179       </orderedlist>
2180     </sect2>
2181   </sect1>
2182
2183   <sect1 id="HDRWQ409">
2184     <title>Determining if a Client Can Run Setuid Programs</title>
2185
2186     <indexterm>
2187       <primary>client machine</primary>
2188
2189       <secondary>controlling running of setuid programs</secondary>
2190     </indexterm>
2191
2192     <indexterm>
2193       <primary>Cache Manager</primary>
2194
2195       <secondary>setuid programs</secondary>
2196     </indexterm>
2197
2198     <indexterm>
2199       <primary>setuid programs</primary>
2200     </indexterm>
2201
2202     <para>A <emphasis>setuid program</emphasis> is one whose binary file
2203     has the UNIX setuid mode bit turned on. While a setuid program runs,
2204     the user who initialized it assumes the local identity (UNIX UID) of
2205     the binary file's owner, and so is granted the permissions in the
2206     local file system that pertain to the owner. Most commonly, the
2207     issuer's assumed identity (often referred to as <emphasis>effective
2208     UID</emphasis>) is the local superuser <emphasis
2209     role="bold">root</emphasis>.</para>
2210
2211     <para>AFS does not recognize effective UID: if a setuid program
2212     accesses AFS files and directories, it uses the current AFS identity
2213     of the user who initialized the program, not of the program's
2214     owner. Nevertheless, it can be useful to store setuid programs in AFS
2215     for use on more than one client machine. AFS enables a client
2216     machine's administrator to determine and change whether the local
2217     Cache Manager allows setuid programs to run or not.</para>
2218
2219     <para>By default, the Cache Manager ignores all setuid permissions in
2220     AFS, but this can be changed by a client machine's administrator. Each
2221     cell's setuid status is set independently of other cells. To change a
2222     cell's setuid status with respect to the local machine, become the
2223     local superuser <emphasis role="bold">root</emphasis> and issue the
2224     <emphasis role="bold">fs setcell</emphasis> command. To determine a
2225     cell's current setuid status, use the <emphasis role="bold">fs
2226     getcellstatus</emphasis> command.</para>
2227
2228     <warning>
2229       <para>Enabling support for the UNIX setuid bit for AFS programs is
2230       not secure with the current AFS protocol. Enabling this capability
2231       is not recommended except in very restricted environments on trusted
2232       networks.</para>
2233     </warning>
2234
2235     <para>When you issue the <emphasis role="bold">fs setcell</emphasis>
2236     command, you directly alter a cell's setuid status as recorded in
2237     kernel memory, so rebooting the machine is not necessary. However,
2238     nondefault settings do not persist across reboots of the machine
2239     unless you add the appropriate <emphasis role="bold">fs
2240     setcell</emphasis> command to the machine's AFS initialization
2241     file.</para>
2242
2243     <para>Only members of the <emphasis
2244     role="bold">system:administrators</emphasis> group can turn on the
2245     setuid mode bit on an AFS file or directory. When the setuid mode bit
2246     is turned on, the UNIX <emphasis role="bold">ls -l</emphasis> command
2247     displays the third user mode bit as an <emphasis
2248     role="bold">s</emphasis> instead of an <emphasis
2249     role="bold">x</emphasis>, but for an AFS file or directory, the
2250     <emphasis role="bold">s</emphasis> appears only if setuid permission
2251     is enabled for the cell in which the file resides.
2252     <indexterm>
2253       <primary>fs commands</primary>
2254       <secondary>getcellstatus</secondary>
2255     </indexterm>
2256     <indexterm>
2257       <primary>commands</primary>
2258       <secondary>fs getcellstatus</secondary>
2259     </indexterm>
2260     </para>
2261
2262     <sect2 id="Header_458">
2263       <title>To determine a cell's setuid status</title>
2264
2265       <orderedlist>
2266         <listitem>
2267           <para>Issue the <emphasis role="bold">fs getcellstatus</emphasis> command to check the setuid status of each desired cell.
2268           <programlisting>
2269    % <emphasis role="bold">fs getcellstatus</emphasis> &lt;<replaceable>cell name</replaceable>&gt;
2270 </programlisting></para>
2271
2272           <para>where <variablelist>
2273               <varlistentry>
2274                 <term><emphasis role="bold">getce</emphasis></term>
2275
2276                 <listitem>
2277                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">getcellstatus</emphasis>.</para>
2278                 </listitem>
2279               </varlistentry>
2280
2281               <varlistentry>
2282                 <term><emphasis role="bold">cell name</emphasis></term>
2283
2284                 <listitem>
2285                   <para>Names each cell for which to report setuid status. Provide the complete Internet domain name or a shortened
2286                   form that distinguishes it from the other cells listed in the local <emphasis
2287                   role="bold">/usr/vice/etc/CellServDB</emphasis> file.</para>
2288                 </listitem>
2289               </varlistentry>
2290             </variablelist></para>
2291         </listitem>
2292       </orderedlist>
2293
2294       <para>The output reports the setuid status of each cell: <itemizedlist>
2295           <listitem>
2296             <para>the string <computeroutput>no setuid allowed</computeroutput> indicates that the Cache Manager does not allow
2297             programs from the cell to run with <computeroutput>setuid permission</computeroutput></para>
2298           </listitem>
2299
2300           <listitem>
2301             <para>setuid allowed indicates that the Cache Manager allows programs from the cell to run with setuid permission</para>
2302           </listitem>
2303         </itemizedlist></para>
2304
2305       <indexterm>
2306         <primary>fs commands</primary>
2307
2308         <secondary>setcell</secondary>
2309       </indexterm>
2310
2311       <indexterm>
2312         <primary>commands</primary>
2313
2314         <secondary>fs setcell</secondary>
2315       </indexterm>
2316     </sect2>
2317
2318     <sect2 id="Header_459">
2319       <title>To change a cell's setuid status</title>
2320
2321       <orderedlist>
2322         <listitem>
2323           <para>Become the local superuser <emphasis role="bold">root</emphasis> on the machine, if you are not already, by issuing
2324           the <emphasis role="bold">su</emphasis> command. <programlisting>
2325    % <emphasis role="bold">su root</emphasis>
2326    Password: &lt;<replaceable>root_password</replaceable>&gt;
2327 </programlisting></para>
2328         </listitem>
2329
2330         <listitem>
2331           <para>Issue the <emphasis role="bold">fs setcell</emphasis> command to change the setuid status of the cell.
2332           <programlisting>
2333    # <emphasis role="bold">fs setcell</emphasis> &lt;<replaceable>cell name</replaceable>&gt;+ [<emphasis role="bold">-suid</emphasis>] [<emphasis
2334                 role="bold">-nosuid</emphasis>]
2335 </programlisting></para>
2336
2337           <para>where <variablelist>
2338               <varlistentry>
2339                 <term><emphasis role="bold">setce</emphasis></term>
2340
2341                 <listitem>
2342                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">setcell</emphasis>.</para>
2343                 </listitem>
2344               </varlistentry>
2345
2346               <varlistentry>
2347                 <term><emphasis role="bold">cell name</emphasis></term>
2348
2349                 <listitem>
2350                   <para>Names each cell for which to change setuid status as specified by the <emphasis role="bold">-suid</emphasis>
2351                   or <emphasis role="bold">-nosuid</emphasis> flag. Provide each cell's complete Internet domain name or a shortened
2352                   form that distinguishes it from the other cells listed in the local <emphasis
2353                   role="bold">/usr/vice/etc/CellServDB</emphasis> file.</para>
2354                 </listitem>
2355               </varlistentry>
2356
2357               <varlistentry>
2358                 <term><emphasis role="bold">-suid</emphasis></term>
2359
2360                 <listitem>
2361                   <para>Enables programs from each specified cell to execute with setuid permission. Provide this flag or the
2362                   <emphasis role="bold">-nosuid</emphasis> flag, or omit both to disable setuid permission for each cell.</para>
2363                 </listitem>
2364               </varlistentry>
2365
2366               <varlistentry>
2367                 <term><emphasis role="bold">-nosuid</emphasis></term>
2368
2369                 <listitem>
2370                   <para>Prevents programs from each specified cell from executing with setuid permission. Provide this flag or the
2371                   <emphasis role="bold">-suid</emphasis> flag, or omit both to disable setuid permission for each cell.</para>
2372                 </listitem>
2373               </varlistentry>
2374             </variablelist></para>
2375         </listitem>
2376       </orderedlist>
2377     </sect2>
2378   </sect1>
2379
2380   <sect1 id="HDRWQ410">
2381     <title>Setting the File Server Probe Interval</title>
2382
2383     <indexterm>
2384       <primary>file server probe interval</primary>
2385
2386       <secondary>setting for a client machine</secondary>
2387     </indexterm>
2388
2389     <indexterm>
2390       <primary>setting</primary>
2391
2392       <secondary>client-to-file-server probe interval</secondary>
2393     </indexterm>
2394
2395     <indexterm>
2396       <primary>Cache Manager</primary>
2397
2398       <secondary>setting</secondary>
2399
2400       <tertiary>probe interval for File Server</tertiary>
2401     </indexterm>
2402
2403     <para>The Cache Manager periodically sends a probe to server machines to verify that they are still accessible. Specifically, it
2404     probes the database server machines in its cell and those file servers that house data it has cached.</para>
2405
2406     <para>If a server process does not respond to a probe, the client machine assumes that it is inaccessible. By default, the
2407     interval between probes is three minutes, so it can take up to three minutes for a client to recognize that a server process is
2408     once again accessible after it was inaccessible.</para>
2409
2410     <para>To adjust the probe interval, include the <emphasis role="bold">-interval</emphasis> argument to the <emphasis
2411     role="bold">fs checkservers</emphasis> command while logged in as the local superuser <emphasis role="bold">root</emphasis>. The
2412     new interval setting persists until you again issue the command or reboot the machine, at which time the setting returns to the
2413     default. To preserve a nondefault setting across reboots, include the appropriate <emphasis role="bold">fs
2414     checkservers</emphasis> command in the machine's AFS initialization file.</para>
2415
2416     <sect2 id="Header_461">
2417       <title>To set a client's file server probe interval</title>
2418
2419       <orderedlist>
2420         <listitem>
2421           <para>Become the local superuser <emphasis role="bold">root</emphasis> on the machine, if you are not already, by issuing
2422           the <emphasis role="bold">su</emphasis> command. <programlisting>
2423    % <emphasis role="bold">su root</emphasis>
2424    Password: &lt;<replaceable>root_password</replaceable>&gt;
2425 </programlisting></para>
2426         </listitem>
2427
2428         <listitem>
2429           <para>Issue the <emphasis role="bold">fs checkservers</emphasis> command with the <emphasis
2430           role="bold">-interval</emphasis> argument. <indexterm>
2431               <primary>fs commands</primary>
2432
2433               <secondary>checkservers</secondary>
2434             </indexterm> <indexterm>
2435               <primary>commands</primary>
2436
2437               <secondary>fs checkservers</secondary>
2438             </indexterm> <programlisting>
2439    # <emphasis role="bold">fs checkservers -interval</emphasis> &lt;<replaceable>seconds between probes</replaceable>&gt;
2440 </programlisting></para>
2441
2442           <para>where <variablelist>
2443               <varlistentry>
2444                 <term><emphasis role="bold">checks</emphasis></term>
2445
2446                 <listitem>
2447                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">checkservers</emphasis>.</para>
2448                 </listitem>
2449               </varlistentry>
2450
2451               <varlistentry>
2452                 <term><emphasis role="bold">-interval</emphasis></term>
2453
2454                 <listitem>
2455                   <para>Specifies the number of seconds between probes. Provide an integer value greater than zero.</para>
2456                 </listitem>
2457               </varlistentry>
2458             </variablelist></para>
2459         </listitem>
2460       </orderedlist>
2461     </sect2>
2462   </sect1>
2463
2464   <sect1 id="HDRWQ411">
2465     <title>Setting a Client Machine's Cell Membership</title>
2466
2467     <indexterm>
2468       <primary>cell</primary>
2469
2470       <secondary>setting home cell for client machine</secondary>
2471     </indexterm>
2472
2473     <indexterm>
2474       <primary>setting</primary>
2475
2476       <secondary>home cell for client machine</secondary>
2477     </indexterm>
2478
2479     <indexterm>
2480       <primary>setting</primary>
2481
2482       <secondary>ThisCell file (client), value in</secondary>
2483     </indexterm>
2484
2485     <indexterm>
2486       <primary>Cache Manager</primary>
2487
2488       <secondary>setting</secondary>
2489
2490       <tertiary>home cell</tertiary>
2491     </indexterm>
2492
2493     <indexterm>
2494       <primary>client machine</primary>
2495
2496       <secondary>setting</secondary>
2497
2498       <tertiary>home cell</tertiary>
2499     </indexterm>
2500
2501     <indexterm>
2502       <primary>ThisCell file (client)</primary>
2503
2504       <secondary>setting value in</secondary>
2505     </indexterm>
2506
2507     <para>Each client machine belongs to a particular cell, as named in the <emphasis role="bold">/usr/vice/etc/ThisCell</emphasis>
2508     on its local disk. The machine's cell membership determines three defaults important to users of the machine: <itemizedlist>
2509         <listitem>
2510           <para>The cell for which users of the machine obtain tokens (authenticate) when they use the <emphasis
2511           role="bold">login</emphasis> program or issue the <emphasis role="bold">klog</emphasis> command. There are two effects:
2512           <itemizedlist>
2513               <listitem>
2514                 <para>The <emphasis role="bold">klog</emphasis> program and AFS-modified login utilities contact an Authentication
2515                 Server in the cell named in the <emphasis role="bold">ThisCell</emphasis> file.</para>
2516               </listitem>
2517
2518               <listitem>
2519                 <para>The <emphasis role="bold">klog</emphasis> program and AFS-modified login utilities combine the contents of the
2520                 <emphasis role="bold">ThisCell</emphasis> file with the password that the user provides, generating an encryption
2521                 key from the combination. The user's entry in the Authentication Database includes an encryption key also generated
2522                 from the combination of password and cell name. If the cell name in the <emphasis role="bold">ThisCell</emphasis>
2523                 file is incorrect, users cannot authenticate even if they provide the correct password.</para>
2524               </listitem>
2525             </itemizedlist></para>
2526         </listitem>
2527
2528         <listitem>
2529           <para>The cell the Cache Manager considers its local, or home, cell. The Cache Manager allows programs from its local cell
2530           to run with setuid permission, but not programs from foreign cells, as discussed further in <link
2531           linkend="HDRWQ409">Determining if a Client Can Run Setuid Programs</link>.</para>
2532         </listitem>
2533
2534         <listitem>
2535           <para>The default database server machines that are contacted by the AFS command interpreters running on this
2536           machine.</para>
2537         </listitem>
2538       </itemizedlist></para>
2539
2540     <sect2 id="Header_463">
2541       <title>To display a client machine's cell membership</title>
2542
2543       <orderedlist>
2544         <listitem>
2545           <para>Use a text editor or the <emphasis role="bold">cat</emphasis> command to display the contents of the <emphasis
2546           role="bold">/usr/vice/etc/ThisCell</emphasis> file. <programlisting>
2547    % <emphasis role="bold">cat /usr/vice/etc/ThisCell</emphasis>
2548 </programlisting></para>
2549         </listitem>
2550       </orderedlist>
2551     </sect2>
2552
2553     <sect2 id="Header_464">
2554       <title>To set a client machine's cell membership</title>
2555
2556       <orderedlist>
2557         <listitem>
2558           <para>Become the local superuser <emphasis role="bold">root</emphasis> on the machine, if you are not already, by issuing
2559           the <emphasis role="bold">su</emphasis> command. <programlisting>
2560    % <emphasis role="bold">su root</emphasis>
2561    Password: &lt;<replaceable>root_password</replaceable>&gt;
2562 </programlisting></para>
2563         </listitem>
2564
2565         <listitem>
2566           <para>Using a text editor, replace the cell name in the <emphasis role="bold">/usr/vice/etc/ThisCell</emphasis>
2567           file.</para>
2568         </listitem>
2569
2570         <listitem>
2571           <para><emphasis role="bold">(Optional.)</emphasis> Reboot the machine to enable the Cache Manager to use the new cell name
2572           immediately; the appropriate command depends on the machine's system type. The <emphasis role="bold">klog</emphasis>
2573           program, AFS-modified login utilities, and the AFS command interpreters use the new cell name the next time they are
2574           invoked; no reboot is necessary. <programlisting>
2575    # <emphasis role="bold">sync</emphasis>
2576    # <emphasis role="bold">shutdown</emphasis>
2577 </programlisting></para>
2578         </listitem>
2579       </orderedlist>
2580     </sect2>
2581   </sect1>
2582
2583   <sect1 id="HDRWQ412">
2584     <title>Forcing the Update of Cached Data</title>
2585
2586     <indexterm>
2587       <primary>flushing</primary>
2588
2589       <secondary>data cache on client machine</secondary>
2590     </indexterm>
2591
2592     <indexterm>
2593       <primary>data cache</primary>
2594
2595       <secondary>flushing (forcing update)</secondary>
2596     </indexterm>
2597
2598     <indexterm>
2599       <primary>Cache Manager</primary>
2600
2601       <secondary>flushing cache</secondary>
2602     </indexterm>
2603
2604     <indexterm>
2605       <primary>file</primary>
2606
2607       <secondary>flushing from data cache on client machine</secondary>
2608     </indexterm>
2609
2610     <indexterm>
2611       <primary>directory</primary>
2612
2613       <secondary>flushing from data cache on client machine</secondary>
2614     </indexterm>
2615
2616     <indexterm>
2617       <primary>volume</primary>
2618
2619       <secondary>flushing from data cache on client machine</secondary>
2620     </indexterm>
2621
2622     <indexterm>
2623       <primary>mount point</primary>
2624
2625       <secondary>flushing from data cache on client machine</secondary>
2626     </indexterm>
2627
2628     <indexterm>
2629       <primary>client machine</primary>
2630
2631       <secondary>flushing data cache</secondary>
2632     </indexterm>
2633
2634     <para>AFS's callback mechanism normally guarantees that the Cache Manager provides the most current version of a file or
2635     directory to the application programs running on its machine. However, you can force the Cache Manager to discard (flush) cached
2636     data so that the next time an application program requests it, the Cache Manager fetches the latest version available at the
2637     File Server.</para>
2638
2639     <para>You can control how many file system elements to flush at a time: <itemizedlist>
2640         <listitem>
2641           <para>To flush only specific files or directories, use the <emphasis role="bold">fs flush</emphasis> command. This command
2642           forces the Cache Manager to discard the data and status information it has cached from the specified files or directories.
2643           It does not discard information from an application program's buffer or information that has been altered locally (changes
2644           made in the cache but not yet saved permanently to the File Server). However, the next time an application requests the
2645           element's data or status information, the Cache Manager has to contact the File Server to get it.</para>
2646         </listitem>
2647
2648         <listitem>
2649           <para>To flush everything cached from a certain volume, use the <emphasis role="bold">fs flushvolume</emphasis> command.
2650           This command works like the <emphasis role="bold">fs flush</emphasis> command, but differs in two ways: <itemizedlist>
2651               <listitem>
2652                 <para>The Cache Manager discards data for all elements in the cache that come from the same volume as the specified
2653                 files or directories.</para>
2654               </listitem>
2655
2656               <listitem>
2657                 <para>The Cache Manager discards only data, not status information. This difference has little practical effect, but
2658                 can lead to different output from the <emphasis role="bold">ls</emphasis> command when the two different commands
2659                 are used to flush the same element.</para>
2660               </listitem>
2661             </itemizedlist></para>
2662         </listitem>
2663       </itemizedlist></para>
2664
2665     <para>In addition to callbacks, the Cache Manager has a mechanism for tracking other kinds of possible changes, such as changes
2666     in a volume's location. If a volume moves and the Cache Manager has not accessed any data in it for a long time, the Cache
2667     Manager's volume location record can be wrong. To resynchronize it, use the <emphasis role="bold">fs checkvolumes</emphasis>
2668     command. When you issue the command, the Cache Manager creates a new table of mappings between volume names, ID numbers, and
2669     locations. This forces the Cache Manager to reference newly relocated and renamed volumes before it can provide data from
2670     them.</para>
2671
2672     <para>It is also possible for information about mount points to become corrupted in the cache. Symptoms of a corrupted mount
2673     point included garbled output from the <emphasis role="bold">fs lsmount</emphasis> command, and failed attempts to change
2674     directory to or list the contents of a mount point. Use the <emphasis role="bold">fs flushmount</emphasis> command to discard a
2675     corrupted mount point. The Cache Manager must refetch the mount point the next time it crosses it in a pathname. (The Cache
2676     Manager periodically refreshes cached mount points, but the only other way to discard them immediately is to reinitialize the
2677     Cache Manager by rebooting the machine. <indexterm>
2678         <primary>fs commands</primary>
2679
2680         <secondary>flush</secondary>
2681       </indexterm> <indexterm>
2682         <primary>commands</primary>
2683
2684         <secondary>fs flush</secondary>
2685       </indexterm></para>
2686
2687     <sect2 id="Header_466">
2688       <title>To flush certain files or directories</title>
2689
2690       <orderedlist>
2691         <listitem>
2692           <para>Issue the <emphasis role="bold">fs flush</emphasis> command. <programlisting>
2693    % <emphasis role="bold">fs flush</emphasis> [&lt;<replaceable>dir/file path</replaceable>&gt;+]
2694 </programlisting></para>
2695
2696           <para>where <variablelist>
2697               <varlistentry>
2698                 <term><emphasis role="bold">flush</emphasis></term>
2699
2700                 <listitem>
2701                   <para>Must be typed in full.</para>
2702                 </listitem>
2703               </varlistentry>
2704
2705               <varlistentry>
2706                 <term><emphasis role="bold">dir/file path</emphasis></term>
2707
2708                 <listitem>
2709                   <para>Names each file or directory structure to flush from the cache. Omit this argument to flush the current
2710                   working directory. Flushing a directory structure does not flush any files or subdirectories cached from
2711                   it.</para>
2712                 </listitem>
2713               </varlistentry>
2714             </variablelist></para>
2715         </listitem>
2716       </orderedlist>
2717
2718       <indexterm>
2719         <primary>fs commands</primary>
2720
2721         <secondary>flushvolume</secondary>
2722       </indexterm>
2723
2724       <indexterm>
2725         <primary>commands</primary>
2726
2727         <secondary>fs flushvolume</secondary>
2728       </indexterm>
2729     </sect2>
2730
2731     <sect2 id="Header_467">
2732       <title>To flush all data from a volume</title>
2733
2734       <orderedlist>
2735         <listitem>
2736           <para>Issue the <emphasis role="bold">fs flushvolume</emphasis> command. <programlisting>
2737   % <emphasis role="bold">fs flushvolume</emphasis> [&lt;<replaceable>dir/file path</replaceable>&gt;+]
2738 </programlisting></para>
2739
2740           <para>where <variablelist>
2741               <varlistentry>
2742                 <term><emphasis role="bold">flushv</emphasis></term>
2743
2744                 <listitem>
2745                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">flushvolume</emphasis>.</para>
2746                 </listitem>
2747               </varlistentry>
2748
2749               <varlistentry>
2750                 <term><emphasis role="bold">dir/file path</emphasis></term>
2751
2752                 <listitem>
2753                   <para>Names a file or directory from each volume to flush from the cache. The Cache Manager flushes everything in
2754                   the cache that it has fetched from the same volume. Omit this argument to flush all cached data fetched from the
2755                   volume that contains the current working directory.</para>
2756                 </listitem>
2757               </varlistentry>
2758             </variablelist></para>
2759         </listitem>
2760       </orderedlist>
2761
2762       <indexterm>
2763         <primary>fs commands</primary>
2764
2765         <secondary>checkvolumes</secondary>
2766       </indexterm>
2767
2768       <indexterm>
2769         <primary>commands</primary>
2770
2771         <secondary>fs checkvolumes</secondary>
2772       </indexterm>
2773     </sect2>
2774
2775     <sect2 id="Header_468">
2776       <title>To force the Cache Manager to notice other volume changes</title>
2777
2778       <orderedlist>
2779         <listitem>
2780           <para>Issue the <emphasis role="bold">fs checkvolumes</emphasis> command. <programlisting>
2781    % <emphasis role="bold">fs checkvolumes</emphasis>
2782 </programlisting></para>
2783
2784           <para>where <emphasis role="bold">checkv</emphasis> is the shortest acceptable abbreviation of <emphasis
2785           role="bold">checkvolumes</emphasis>.</para>
2786         </listitem>
2787       </orderedlist>
2788
2789       <para>The following command confirms that the command completed successfully:</para>
2790
2791       <programlisting>
2792    All volumeID/name mappings checked.
2793 </programlisting>
2794
2795       <indexterm>
2796         <primary>fs commands</primary>
2797
2798         <secondary>flushmount</secondary>
2799       </indexterm>
2800
2801       <indexterm>
2802         <primary>commands</primary>
2803
2804         <secondary>fs flushmount</secondary>
2805       </indexterm>
2806     </sect2>
2807
2808     <sect2 id="HDRWQ413">
2809       <title>To flush one or more mount points</title>
2810
2811       <orderedlist>
2812         <listitem>
2813           <para>Issue the <emphasis role="bold">fs flushmount</emphasis> command. <programlisting>
2814    % <emphasis role="bold">fs flush</emphasis> [&lt;<replaceable>dir/file path</replaceable>&gt;+]
2815 </programlisting></para>
2816
2817           <para>where <variablelist>
2818               <varlistentry>
2819                 <term><emphasis role="bold">flushm</emphasis></term>
2820
2821                 <listitem>
2822                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">flushmount</emphasis>.</para>
2823                 </listitem>
2824               </varlistentry>
2825
2826               <varlistentry>
2827                 <term><emphasis role="bold">dir/file path</emphasis></term>
2828
2829                 <listitem>
2830                   <para>Names each mount point to flush from the cache. Omit this argument to flush the current working directory.
2831                   Files or subdirectories cached from the associated volume are unaffected.</para>
2832                 </listitem>
2833               </varlistentry>
2834             </variablelist></para>
2835         </listitem>
2836       </orderedlist>
2837     </sect2>
2838   </sect1>
2839
2840   <sect1 id="HDRWQ414">
2841     <title>Maintaining Server Preference Ranks</title>
2842
2843     <indexterm>
2844       <primary>Cache Manager</primary>
2845
2846       <secondary>preference ranks for File Server and VL Server</secondary>
2847     </indexterm>
2848
2849     <indexterm>
2850       <primary>file server machine</primary>
2851
2852       <secondary>Cache Manager preference ranks for</secondary>
2853     </indexterm>
2854
2855     <indexterm>
2856       <primary>displaying</primary>
2857
2858       <secondary>Cache Manager preference ranks for file server machines</secondary>
2859     </indexterm>
2860
2861     <indexterm>
2862       <primary>setting</primary>
2863
2864       <secondary>Cache Manager preferences for file server machines</secondary>
2865     </indexterm>
2866
2867     <indexterm>
2868       <primary>server preference ranks</primary>
2869     </indexterm>
2870
2871     <indexterm>
2872       <primary>VL Server</primary>
2873
2874       <secondary>Cache Manager preference ranks for</secondary>
2875     </indexterm>
2876
2877     <para>As mentioned in the introduction to this chapter, AFS uses client-side data caching and callbacks to reduce the amount of
2878     network traffic in your cell. The Cache Manager also tries to make its use of the network as efficient as possible by assigning
2879     <emphasis>preference ranks</emphasis> to server machines based on their network proximity to the local machine. The ranks bias
2880     the Cache Manager to fetch information from the server machines that are on its own subnetwork or network rather than on other
2881     networks, if possible. Reducing the network distance that data travels between client and server machine tends to reduce network
2882     traffic and speed the Cache Manager's delivery of data to applications.</para>
2883
2884     <para>The Cache Manager stores two separate sets of preference ranks in kernel memory. The first set of ranks applies to
2885     machines that run the Volume Location (VL) Server process, hereafter referred to as <emphasis>VL Server machines</emphasis>. The
2886     second set of ranks applies to machines that run the File Server process, hereafter referred to as <emphasis>file server
2887     machines</emphasis>. This section explains how the Cache Manager sets default ranks, how to use the <emphasis role="bold">fs
2888     setserverprefs</emphasis> command to change the defaults or set new ranks, and how to use the <emphasis role="bold">fs
2889     getserverprefs</emphasis> command to display the current set of ranks.</para>
2890
2891     <sect2 id="Header_471">
2892       <title>How the Cache Manager Sets Default Ranks</title>
2893
2894       <para>As the <emphasis role="bold">afsd</emphasis> program initializes the Cache Manager, it assigns a preference rank of
2895       10,000 to each of the VL Server machines listed in the local <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file.
2896       It then randomizes the ranks by adding an integer randomly chosen from the range 0 (zero) to 126. It avoids assigning the same
2897       rank to machines in one cell, but it is possible for machines from different cells to have the same rank. This does not
2898       present a problem in use, because the Cache Manager compares the ranks of only one cell's database server machines at a time.
2899       Although AFS supports the use of multihomed database server machines, the Cache Manager only uses the single address listed
2900       for each database server machine in the local <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file. Only Ubik can
2901       take advantage of a multihomed database server machine's multiple interfaces.</para>
2902
2903       <para>The Cache Manager assigns preference ranks to a file server machine when it obtains the server's VLDB record from the VL
2904       Server, the first time that it accesses a volume that resides on the machine. If the machine is multihomed, the Cache Manager
2905       assigns a distinct rank to each of its interfaces (up to the number of interfaces that the VLDB can store for each machine,
2906       which is specified in the <emphasis>OpenAFS Release Notes</emphasis>). The Cache Manager compares the interface's IP address
2907       to the local machine's address and applies the following algorithm: <itemizedlist>
2908           <listitem>
2909             <para>If the local machine is a file server machine, the base rank for each of its interfaces is 5,000.</para>
2910           </listitem>
2911
2912           <listitem>
2913             <para>If the file server machine interface is on the same subnetwork as the local machine, its base rank is
2914             20,000.</para>
2915           </listitem>
2916
2917           <listitem>
2918             <para>If the file server machine interface is on the same network as the local machine, or is at the distant end of a
2919             point-to-point link with the local machine, its base rank is 30,000.</para>
2920           </listitem>
2921
2922           <listitem>
2923             <para>If the file server machine interface is on a different network than the local machine, or the Cache Manager cannot
2924             obtain network information about it, its base rank is 40,000.</para>
2925           </listitem>
2926         </itemizedlist></para>
2927
2928       <para>If the client machine has only one interface, the Cache Manager compares it to the server interface's IP address and
2929       sets a rank according to the algorithm. If the client machine is multihomed, the Cache Manager compares each of the local
2930       interface addresses to the server interface, and assigns to the server interface the lowest rank that results from comparing
2931       it to all of the client interfaces.</para>
2932
2933       <para>After assigning a base rank to a file server machine interface, the Cache Manager adds to it a number randomly chosen
2934       from the range 0 (zero) to 15. As an example, a file server machine interface in the same subnetwork as the local machine
2935       receives a base rank of 20,000, but the Cache Manager records the actual rank as an integer between 20,000 and 20,015. This
2936       process reduces the number of interfaces that have exactly the same rank. As with VL Server machine ranks, it is possible for
2937       file server machine interfaces from foreign cells to have the same rank as interfaces in the local cell, but this does not
2938       present a problem. Only the relative ranks of the interfaces that house a specific volume are relevant, and AFS supports
2939       storage of a volume in only one cell at a time.</para>
2940     </sect2>
2941
2942     <sect2 id="Header_472">
2943       <title>How the Cache Manager Uses Preference Ranks</title>
2944
2945       <para>Each preference rank pairs an interface's IP address with an integer that can range from 1 to 65,534. A lower rank
2946       (lower number) indicates a stronger preference. Once set, a rank persists until the machine reboots, or until you use the
2947       <emphasis role="bold">fs setserverprefs</emphasis> command to change it.</para>
2948
2949       <para>The Cache Manager uses VL Server machine ranks when it needs to fetch volume location information from a cell. It
2950       compares the ranks for the cell's VL Server machines and attempts to contact the VL Server process on the machine with the
2951       best (lowest integer) rank. If it cannot reach that VL Server, it tries to contact the VL Server with the next best rank, and
2952       so on. If all of a cell's VL Server machines are inaccessible, the Cache Manager cannot fetch data from the cell.</para>
2953
2954       <para>Similarly, when the Cache Manager needs to fetch data from a volume, it compares the ranks for the interfaces of
2955       machines that house the volume, and attempts to contact the interface that has the best rank. If it cannot reach the <emphasis
2956       role="bold">fileserver</emphasis> process via that interface, it tries to contact the interface with the next best integer
2957       rank, and so on. If it cannot reach any of the interfaces for machines that house the volume, it cannot fetch data from the
2958       volume.</para>
2959     </sect2>
2960
2961     <sect2 id="Header_473">
2962       <title>Displaying and Setting Preference Ranks</title>
2963
2964       <para>To display the file server machine ranks that the Cache Manager is using, use the <emphasis role="bold">fs
2965       getserverprefs</emphasis> command. Include the <emphasis role="bold">-vlservers</emphasis> flag to display VL Server machine
2966       ranks instead. By default, the output appears on the standard output stream (stdout), but you can write it to a file instead
2967       by including the <emphasis role="bold">-file</emphasis> argument.</para>
2968
2969       <para>The Cache Manager stores IP addresses rather than hostnames in its kernel list of ranks, but by default the output
2970       identifies interfaces by hostname after calling a translation routine that refers to either the cell's name service (such as
2971       the Domain Name Server) or the local host table. If an IP address appears in this case, it is because the translation attempt
2972       failed. To bypass the translation step and display IP addresses rather than hostnames, include the <emphasis
2973       role="bold">-numeric</emphasis> flag. This can significantly speed up the output.</para>
2974
2975       <para>You can use the <emphasis role="bold">fs setserverprefs</emphasis> command to reset an existing preference rank, or to
2976       set the initial rank of a file server machine interface or VL Server machine for which the Cache Manager has no rank. The
2977       ranks you set persist until the machine reboots or until you issue the <emphasis role="bold">fs setserverprefs</emphasis>
2978       command again. To make a rank persist across a reboot, place the appropriate <emphasis role="bold">fs
2979       setserverprefs</emphasis> command in the machine's AFS initialization file.</para>
2980
2981       <para>As with default ranks, the Cache Manager adds a randomly chosen integer to each rank range that you assign. For file
2982       server machine interfaces, the randomizing number is from the range 0 (zero) to 15; for VL Server machines, it is from the
2983       range 0 (zero) to 126. For example, if you assign a rank of 15,000 to a file server machine interface, the Cache Manager
2984       stores an integer between 15,000 to 15,015.</para>
2985
2986       <para>To assign VL Server machine ranks, list them after the <emphasis role="bold">-vlserver</emphasis> argument to the
2987       <emphasis role="bold">fs setserverprefs</emphasis> command.</para>
2988
2989       <para>To assign file server machine ranks, use or more of the three possible methods: <orderedlist>
2990           <listitem>
2991             <para>List them after the <emphasis role="bold">-servers</emphasis> argument on the command line.</para>
2992           </listitem>
2993
2994           <listitem>
2995             <para>Record them in a file and name it with the <emphasis role="bold">-file</emphasis> argument. You can easily
2996             generate a file with the proper format by including the <emphasis role="bold">-file</emphasis> argument to the <emphasis
2997             role="bold">fs getserverprefs</emphasis> command.</para>
2998           </listitem>
2999
3000           <listitem>
3001             <para>Provide them via the standard input stream, by including the <emphasis role="bold">-stdin</emphasis> flag. This
3002             enables you to feed in values directly from a command or script that generates preferences using an algorithm
3003             appropriate for your cell. It must generate them in the proper format, with one or more spaces between each pair and
3004             between the two parts of the pair. The AFS distribution does not include such a script, so you must write one if you
3005             want to use this method.</para>
3006           </listitem>
3007         </orderedlist></para>
3008
3009       <para>You can combine any of the <emphasis role="bold">-servers</emphasis>, <emphasis role="bold">-file</emphasis>, and
3010       <emphasis role="bold">-stdin</emphasis> options on the same command line if you wish. If more than one of them specifies a
3011       rank for the same interface, the one assigned with the <emphasis role="bold">-servers</emphasis> argument takes precedence.
3012       You can also provide the <emphasis role="bold">-vlservers</emphasis> argument on the same command line to set VL Server
3013       machine ranks at the same time as file server machine ranks.</para>
3014
3015       <para>The <emphasis role="bold">fs</emphasis> command interpreter does not verify hostnames or IP addresses, and so willingly
3016       stores ranks for hostnames and addresses that don't actually exist. The Cache Manager never uses such ranks unless the same
3017       VLDB record for a server machine records the same incorrect information. <indexterm>
3018           <primary>fs commands</primary>
3019
3020           <secondary>getserverprefs</secondary>
3021         </indexterm> <indexterm>
3022           <primary>commands</primary>
3023
3024           <secondary>fs getserverprefs</secondary>
3025         </indexterm></para>
3026     </sect2>
3027
3028     <sect2 id="Header_474">
3029       <title>To display server preference ranks</title>
3030
3031       <orderedlist>
3032         <listitem>
3033           <para>Issue the <emphasis role="bold">fs getserverprefs</emphasis> command to display the Cache Manager's preference ranks
3034           for file server machines or VL Server machines. <programlisting>
3035    % <emphasis role="bold">fs getserverprefs</emphasis> [<emphasis role="bold">-file</emphasis> &lt;<replaceable>output to named file</replaceable>&gt;] [<emphasis
3036                 role="bold">-numeric</emphasis>] [<emphasis role="bold">-vlservers</emphasis>]
3037 </programlisting></para>
3038
3039           <para>where <variablelist>
3040               <varlistentry>
3041                 <term><emphasis role="bold">gp</emphasis></term>
3042
3043                 <listitem>
3044                   <para>Is an acceptable alias for <emphasis role="bold">getserverprefs</emphasis> (<emphasis
3045                   role="bold">gets</emphasis> is the shortest acceptable abbreviation).</para>
3046                 </listitem>
3047               </varlistentry>
3048
3049               <varlistentry>
3050                 <term><emphasis role="bold">-file</emphasis></term>
3051
3052                 <listitem>
3053                   <para>Specifies the pathname of the file to which to write the list of ranks. Omit this argument to display the
3054                   list on the standard output stream (stdout).</para>
3055                 </listitem>
3056               </varlistentry>
3057
3058               <varlistentry>
3059                 <term><emphasis role="bold">-numeric</emphasis></term>
3060
3061                 <listitem>
3062                   <para>Displays the IP address, rather than the hostname, of each ranked machine interface. Omit this flag to have
3063                   the addresses translated into hostnames, which takes longer.</para>
3064                 </listitem>
3065               </varlistentry>
3066
3067               <varlistentry>
3068                 <term><emphasis role="bold">-vlservers</emphasis></term>
3069
3070                 <listitem>
3071                   <para>Displays ranks for VL Server machines rather than file server machines.</para>
3072                 </listitem>
3073               </varlistentry>
3074             </variablelist></para>
3075
3076           <para>The following example displays file server machine ranks. The <emphasis role="bold">-numeric</emphasis> flag is not
3077           used, so the appearance of an IP address indicates that is not currently possible to translate it to a hostname.</para>
3078
3079           <programlisting>
3080    % <emphasis role="bold">fs gp</emphasis>
3081    fs5.abc.com         20000
3082    fs1.abc.com         30014
3083    server1.stateu.edu  40011
3084    fs3.abc.com         20001
3085    fs4.abc.com         30001
3086    192.12.106.120      40002
3087    192.12.106.119      40001
3088       .   .   .   .   .     . .
3089 </programlisting>
3090         </listitem>
3091       </orderedlist>
3092
3093       <indexterm>
3094         <primary>fs commands</primary>
3095
3096         <secondary>setserverprefs</secondary>
3097       </indexterm>
3098
3099       <indexterm>
3100         <primary>commands</primary>
3101
3102         <secondary>fs setserverprefs</secondary>
3103       </indexterm>
3104
3105       <indexterm>
3106         <primary>preferences</primary>
3107
3108         <secondary>setting</secondary>
3109       </indexterm>
3110     </sect2>
3111
3112     <sect2 id="Header_475">
3113       <title>To set server preference ranks</title>
3114
3115       <orderedlist>
3116         <listitem>
3117           <para>Become the local superuser <emphasis role="bold">root</emphasis> on the machine, if you are not already, by issuing
3118           the <emphasis role="bold">su</emphasis> command. <programlisting>
3119    % <emphasis role="bold">su root</emphasis>
3120    Password: &lt;<replaceable>root_password</replaceable>&gt;
3121 </programlisting></para>
3122         </listitem>
3123
3124         <listitem>
3125           <para>Issue the <emphasis role="bold">fs setserverprefs</emphasis> command to set the Cache Manager's preference ranks for
3126           one or more file server machines or VL Server machines. <programlisting>
3127    # <emphasis role="bold">fs setserverprefs</emphasis> [<emphasis role="bold">-servers</emphasis> &lt;<replaceable>fileserver names and ranks</replaceable>&gt;+]  \
3128                        [<emphasis role="bold">-vlservers</emphasis> &lt;<replaceable>VL server names and ranks</replaceable>&gt;+]  \
3129                        [<emphasis role="bold">-file</emphasis> &lt;<replaceable>input from named file</replaceable>&gt;] [<emphasis
3130                 role="bold">-stdin</emphasis>]
3131 </programlisting></para>
3132
3133           <para>where <variablelist>
3134               <varlistentry>
3135                 <term><emphasis role="bold">sp</emphasis></term>
3136
3137                 <listitem>
3138                   <para>Is an acceptable alias for <emphasis role="bold">setserverprefs</emphasis> (<emphasis
3139                   role="bold">sets</emphasis> is the shortest acceptable abbreviation).</para>
3140                 </listitem>
3141               </varlistentry>
3142
3143               <varlistentry>
3144                 <term><emphasis role="bold">-servers</emphasis></term>
3145
3146                 <listitem>
3147                   <para>Specifies one or more pairs of file server machine interface and rank. Identify each interface by its
3148                   fully-qualified hostname or IP address in dotted decimal format. Acceptable ranks are the integers from <emphasis
3149                   role="bold">1</emphasis> to <emphasis role="bold">65534</emphasis>. Separate the parts of a pair, and the pairs
3150                   from one another, with one or more spaces.</para>
3151                 </listitem>
3152               </varlistentry>
3153
3154               <varlistentry>
3155                 <term><emphasis role="bold">-vlservers</emphasis></term>
3156
3157                 <listitem>
3158                   <para>Specifies one or more pairs of VL Server machine and rank. Identify each machine by its fully-qualified
3159                   hostname or IP address in dotted decimal format. Acceptable ranks are the integers from <emphasis
3160                   role="bold">1</emphasis> to <emphasis role="bold">65534</emphasis>.</para>
3161                 </listitem>
3162               </varlistentry>
3163
3164               <varlistentry>
3165                 <term><emphasis role="bold">-file</emphasis></term>
3166
3167                 <listitem>
3168                   <para>Specifies the pathname of a file that contains one more pairs of file server machine interface and rank.
3169                   Place each pair on its own line in the file. Use the same format for interfaces and ranks as with the <emphasis
3170                   role="bold">-servers</emphasis> argument.</para>
3171                 </listitem>
3172               </varlistentry>
3173
3174               <varlistentry>
3175                 <term><emphasis role="bold">-stdin</emphasis></term>
3176
3177                 <listitem>
3178                   <para>Indicates that pairs of file server machine interface and rank are being provided via the standard input
3179                   stream (stdin). The program or script that generates the pairs must format them in the same manner as for the
3180                   <emphasis role="bold">-servers</emphasis> argument.</para>
3181                 </listitem>
3182               </varlistentry>
3183             </variablelist></para>
3184         </listitem>
3185       </orderedlist>
3186     </sect2>
3187   </sect1>
3188
3189   <sect1 id="HDRWQ415">
3190     <title>Managing Multihomed Client Machines</title>
3191
3192     <indexterm>
3193       <primary>Cache Manager</primary>
3194
3195       <secondary>use of NetInfo file</secondary>
3196     </indexterm>
3197