1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 4//EN">
3 <TITLE>Administration Guide</TITLE>
4 <!-- Begin Header Records ========================================== -->
5 <!-- /tmp/idwt3570/auagd000.scr converted by idb2h R4.2 (359) ID -->
6 <!-- Workbench Version (AIX) on 2 Oct 2000 at 11:42:14 -->
7 <META HTTP-EQUIV="updated" CONTENT="Mon, 02 Oct 2000 11:42:13">
8 <META HTTP-EQUIV="review" CONTENT="Tue, 02 Oct 2001 11:42:13">
9 <META HTTP-EQUIV="expires" CONTENT="Wed, 02 Oct 2002 11:42:13">
11 <!-- (C) IBM Corporation 2000. All Rights Reserved -->
12 <BODY bgcolor="ffffff">
13 <!-- End Header Records ============================================ -->
14 <A NAME="Top_Of_Page"></A>
15 <H1>Administration Guide</H1>
16 <HR><P ALIGN="center"> <A HREF="../index.htm"><IMG SRC="../books.gif" BORDER="0" ALT="[Return to Library]"></A> <A HREF="auagd002.htm#ToC"><IMG SRC="../toc.gif" BORDER="0" ALT="[Contents]"></A> <A HREF="auagd014.htm"><IMG SRC="../prev.gif" BORDER="0" ALT="[Previous Topic]"></A> <A HREF="#Bot_Of_Page"><IMG SRC="../bot.gif" BORDER="0" ALT="[Bottom of Topic]"></A> <A HREF="auagd016.htm"><IMG SRC="../next.gif" BORDER="0" ALT="[Next Topic]"></A> <A HREF="auagd026.htm#HDRINDEX"><IMG SRC="../index.gif" BORDER="0" ALT="[Index]"></A> <P>
18 <A NAME="IDX7308"></A>
19 <A NAME="IDX7309"></A>
20 <HR><H1><A NAME="HDRWQ387" HREF="auagd002.htm#ToC_431">Administering Client Machines and the Cache Manager</A></H1>
21 <P>This chapter describes how to administer an AFS client
22 machine, which is any machine from which users can access the AFS filespace
23 and communicate with AFS server processes. (A client machine can
24 simultaneously function as an AFS server machine if appropriately
25 configured.) An AFS client machine has the following
28 <P><LI>The kernel includes the set of modifications, commonly referred to as the
29 Cache Manager, that enable access to AFS files and directories. You can
30 configure many of the Cache Manager's features to suit your users'
31 needs. See <A HREF="#HDRWQ390">Overview of Cache Manager Customization</A>.
32 <P><LI>The <B>/usr/vice/etc</B> directory on the local disk stores several
33 configuration files. See <A HREF="#HDRWQ392">Configuration Files in the /usr/vice/etc Directory</A>.
34 <P><LI>A cache stores temporary copies of data fetched from AFS file server
35 machines, either in machine memory or on a devoted local disk
36 partition. See <A HREF="#HDRWQ394">Determining the Cache Type, Size, and Location</A> and <A HREF="#HDRWQ402">Setting Other Cache Parameters with the afsd program</A>.
38 <P>To learn how to install the client functionality on a machine, see the
39 <I>IBM AFS Quick Beginnings</I>.
40 <HR><H2><A NAME="HDRWQ388" HREF="auagd002.htm#ToC_432">Summary of Instructions</A></H2>
41 <P>This chapter explains how to perform the following tasks by
42 using the indicated commands:
46 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="67%">Display cache size set at reboot
47 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="33%"><B>cat /usr/vice/etc/cacheinfo</B>
49 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="67%">Display current cache size and usage
50 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="33%"><B>fs getcacheparms</B>
52 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="67%">Change disk cache size without rebooting
53 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="33%"><B>fs setcachesize</B>
55 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="67%">Initialize Cache Manager
56 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="33%"><B>afsd</B>
58 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="67%">Display contents of <B>CellServDB</B> file
59 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="33%"><B>cat /usr/vice/etc/CellServDB</B>
61 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="67%">Display list of database server machines from kernel memory
62 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="33%"><B>fs listcells</B>
64 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="67%">Change list of database server machines in kernel memory
65 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="33%"><B>fs newcell</B>
67 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="67%">Check cell's status regarding setuid
68 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="33%"><B>fs getcellstatus</B>
70 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="67%">Set cell's status regarding setuid
71 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="33%"><B>fs setcell</B>
73 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="67%">Set server probe interval
74 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="33%"><B>fs checkservers -interval</B>
76 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="67%">Display machine's cell membership
77 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="33%"><B>cat /usr/vice/etc/ThisCell</B>
79 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="67%">Change machine's cell membership
80 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="33%">Edit <B>/usr/vice/etc/ThisCell</B>
82 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="67%">Flush cached file/directory
83 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="33%"><B>fs flush</B>
85 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="67%">Flush everything cached from a volume
86 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="33%"><B>fs flushvolume</B>
88 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="67%">Update volume-to-mount-point mappings
89 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="33%"><B>fs checkvolumes</B>
91 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="67%">Display Cache Manager's server preference ranks
92 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="33%"><B>fs getserverprefs</B>
94 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="67%">Set Cache Manager's server preference ranks
95 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="33%"><B>fs setserverprefs</B>
97 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="67%">Display client machine addresses to register
98 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="33%"><B>fs getclientaddrs</B>
100 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="67%">Set client machine addresses to register
101 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="33%"><B>fs setclientaddrs</B>
103 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="67%">Control the display of warning and status messages
104 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="33%"><B>fs messages</B>
106 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="67%">Display and change machine's system type
107 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="33%"><B>fs sysname</B>
109 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="67%">Enable asynchronous writes
110 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="33%"><B>fs storebehind</B>
112 <HR><H2><A NAME="HDRWQ390" HREF="auagd002.htm#ToC_433">Overview of Cache Manager Customization</A></H2>
113 <A NAME="IDX7310"></A>
114 <A NAME="IDX7311"></A>
115 <A NAME="IDX7312"></A>
116 <P>An AFS client machine's kernel includes a set of modifications,
117 commonly referred to as the <I>Cache Manager</I>, that enable access to
118 AFS files and directories and communications with AFS server processes.
119 It is common to speak of the Cache Manager as a process or program, and in
120 regular usage it appears to function like one. When configuring it,
121 though, it is helpful to keep in mind that this usage is not strictly
123 <P>The Cache Manager mainly fetches files on behalf of application programs
124 running on the machine. When an application requests an AFS file, the
125 Cache Manager contacts the Volume Location (VL) Server to obtain a list of the
126 file server machines that house the volume containing the file. The
127 Cache Manager then translates the application program's system call
128 requests into remote procedure calls (RPCs) to the File Server running on the
129 appropriate machine. When the File Server delivers the file, the Cache
130 Manager stores it in a local <I>cache</I> before delivering it to the
132 <P>The File Server delivers a data structure called a <I>callback</I>
133 along with the file. (To be precise, it delivers a callback for each
134 file fetched from a read/write volume, and a single callback for all data
135 fetched from a read-only volume.) A valid callback indicates that the
136 Cache Manager's cached copy of a file matches the central copy maintained
137 by the File Server. If an application on another AFS client machine
138 changes the central copy, the File Server breaks the callback, and the Cache
139 Manager must retrieve the new version when an application program on its
140 machine next requests data from the file. As long as the callback is
141 unbroken, however, the Cache Manager can continue to provide the cached
142 version of the file to applications on its machine, which eliminates
143 unnecessary network traffic.
144 <P>The indicated sections of this chapter explain how to configure and
145 customize the following Cache Manager features. All but the first
146 (choosing disk or memory cache) are optional, because AFS sets suitable
149 <P><LI><I>disk or memory cache</I>. The AFS Cache Manager can use
150 machine memory for caching instead of space on the local disk. Deciding
151 which to use is the most basic configuration decision you must make.
152 See <A HREF="#HDRWQ394">Determining the Cache Type, Size, and Location</A>.
153 <P><LI><I>cache size</I>. Cache size probably has the most direct
154 influence on client machine performance. It determines how often the
155 Cache Manager must contact the File Server across the network or discard
156 cached data to make room for newly requested files, both of which affect how
157 quickly the Cache Manager delivers files to users. See <A HREF="#HDRWQ394">Determining the Cache Type, Size, and Location</A>.
158 <P><LI><I>cache location</I>. For a disk cache, you can alter the
159 conventional cache directory location (<B>/usr/vice/cache</B>) to take
160 advantage of greater space availability on other disks on the machine.
161 A larger cache can result in faster file delivery. See <A HREF="#HDRWQ394">Determining the Cache Type, Size, and Location</A>.
162 <P><LI><I>chunk size and number</I>. The <B>afsd</B> program,
163 which initializes the Cache Manager, allows you to control the size and number
164 of chunks into which a cache is divided, plus related parameters.
165 Setting these parameters is optional, because there are reasonable defaults,
166 but it provides precise control. The AFS distribution includes
167 configuration scripts that set Cache Manager parameters to values that are
168 reasonable for different configurations and usage patterns. See <A HREF="#HDRWQ402">Setting Other Cache Parameters with the afsd program</A>.
169 <P><LI><I>knowledge of database server machines</I>. Enable access to
170 a cell's AFS filespace and other services by listing the cell's
171 database server machines in the <B>/usr/vice/etc/CellServDB</B> file on
172 the local disk. See <A HREF="#HDRWQ406">Maintaining Knowledge of Database Server Machines</A>.
173 <P><LI><I>setuid privilege</I>. You can control whether the Cache
174 Manager allows programs from a cell to execute with setuid permission.
175 See <A HREF="#HDRWQ409">Determining if a Client Can Run Setuid Programs</A>.
176 <P><LI><I>cell membership</I>. Each client belongs to a one cell
177 defined by the local <B>/usr/vice/etc/ThisCell</B> file. Cell
178 membership determines the default cell in which the machine's users are
179 authenticated and in which AFS commands run. See <A HREF="#HDRWQ411">Setting a Client Machine's Cell Membership</A>.
180 <P><LI><I>cached file version</I>. AFS's system of callbacks
181 normally guarantees that the Cache Manager has the most current versions of
182 files and directories possible. Nevertheless, you can force the Cache
183 Manager to fetch the most current version of a file from the File Server if
184 you suspect that the cache contains an outdated version. See <A HREF="#HDRWQ412">Forcing the Update of Cached Data</A>.
185 <P><LI><I>File Server and Volume Location Server preferences</I>. The
186 Cache Manager sets numerical preference ranks for the interfaces on file
187 server machines and Volume Server (VL) machines. The ranks determine
188 which interface the Cache Manager first attempts to use when fetching data
189 from a volume or from the Volume Location Database (VLDB). The Cache
190 Manager sets default ranks as it initializes, basing them on its network
191 proximity to each interface, but you can modify the preference ranks if you
192 wish. See <A HREF="#HDRWQ414">Maintaining Server Preference Ranks</A>.
193 <P><LI><I>interfaces registered with the File Server</I>. If the Cache
194 Manager is multihomed (has multiple interface addresses), you can control
195 which of them it registers for File Servers to use when they initiate RPCs to
196 the client machine. See <A HREF="#HDRWQ415">Managing Multihomed Client Machines</A>.
197 <P><LI><I>display of information messages</I>. By default, the Cache
198 Manager sends basic error and informational messages to the client
199 machine's console and to command shells. You can disable the
200 messaging. See <A HREF="#HDRWQ416">Controlling the Display of Warning and Informational Messages</A>.
201 <P><LI><I>system type</I>. The Cache Manager records the local
202 machine's AFS system type in kernel memory, and substitutes the value for
203 the <VAR>@sys</VAR> variable in pathnames. See <A HREF="#HDRWQ417">Displaying and Setting the System Type Name</A>.
204 <P><LI><I>delayed writes</I>. By default, the Cache Manager writes all
205 data to the File Server immediately and synchronously when an application
206 program closes a file. You can enable asynchronous writes, either for
207 an individual file, or all files that the Cache Manager handles, and set how
208 much data remains to be written when the Cache Manager returns control to the
209 closing application. See <A HREF="#HDRWQ418">Enabling Asynchronous Writes</A>.
211 <P>You must make all configuration changes on the client machine itself (at
212 the console or over a direct connection such as a <B>telnet</B>
213 connection). You cannot configure the Cache Manager remotely.
214 You must be logged in as the local superuser <B>root</B> to issue some
215 commands, whereas others require no privilege. All files mentioned in
216 this chapter must actually reside on the local disk of each AFS client machine
217 (they cannot, for example, be symbolic links to files in AFS).
218 <P>AFS's <B>package</B> program can simplify other aspects of client
219 machine configuration, including those normally set in the machine's AFS
220 initialization file. See <A HREF="auagd016.htm#HDRWQ419">Configuring Client Machines with the package Program</A>.
221 <HR><H2><A NAME="HDRWQ391" HREF="auagd002.htm#ToC_434">Configuration and Cache-Related Files on the Local Disk</A></H2>
222 <A NAME="IDX7313"></A>
223 <A NAME="IDX7314"></A>
224 <A NAME="IDX7315"></A>
225 <A NAME="IDX7316"></A>
226 <A NAME="IDX7317"></A>
227 <P>This section briefly describes the client configuration files that must
228 reside in the local <B>/usr/vice/etc</B> directory on every client
229 machine. If the machine uses a disk cache, there must be a partition
230 devoted to cache files; by convention, it is mounted at the
231 <B>/usr/vice/cache</B> directory.
232 <P><B>Note for Windows users:</B> Some files described in this
233 document possibly do not exist on machines that run a Windows operating
234 system. Also, Windows uses a backslash
235 ( <B>\</B> ) rather than a forward slash
236 ( <B>/</B> ) to separate the elements in a
238 <P><H3><A NAME="HDRWQ392" HREF="auagd002.htm#ToC_435">Configuration Files in the /usr/vice/etc Directory</A></H3>
239 <P>The <B>/usr/vice/etc</B> directory on a client
240 machine's local disk must contain certain configuration files for the
241 Cache Manager to function properly. They control the most basic aspects
242 of Cache Manager configuration.
243 <P>If it is important that the client machines in your cell perform uniformly,
244 it is most efficient to update these files from a central source. The
245 following descriptions include pointers to sections that discuss how best to
248 <A NAME="IDX7318"></A>
249 <A NAME="IDX7319"></A>
250 <A NAME="IDX7320"></A>
251 <A NAME="IDX7321"></A>
252 <A NAME="IDX7322"></A>
254 </B><DD>The binary file for the program that initializes the Cache Manager.
255 It must run each time the machine reboots in order for the machine to remain
256 an AFS client machine. The program also initializes several daemons
257 that improve Cache Manager functioning, such as the process that handles
259 <A NAME="IDX7323"></A>
260 <A NAME="IDX7324"></A>
262 </B><DD>A one-line file that sets the cache's most basic configuration
263 parameters: the local directory at which the Cache Manager mounts the
264 AFS filespace, the local disk directory to use as the cache, and how many
265 kilobytes to allocate to the cache.
266 <P>The <I>IBM AFS Quick Beginnings</I> explains how to create this file as
267 you install a client machine. To change the cache size on a machine
268 that uses a memory cache, edit the file and reboot the machine. On a
269 machine that uses a disk cache, you can change the cache size without
270 rebooting by issuing the <B>fs setcachesize</B> command. For
271 instructions, see <A HREF="#HDRWQ394">Determining the Cache Type, Size, and Location</A>.
272 <A NAME="IDX7325"></A>
273 <A NAME="IDX7326"></A>
275 </B><DD>This ASCII file names the database server machines in the local cell and
276 in any foreign cell to which you want to enable access from this
277 machine. (Database server machines are the machines in a cell that run
278 the Authentication, Backup, Protection, and VL Server processes; see <A HREF="auagd008.htm#HDRWQ92">Database Server Machines</A>.)
279 <P>The Cache Manager must be able to reach a cell's database server
280 machines to fetch files from its filespace. Incorrect or missing
281 information in the <B>CellServDB</B> file can slow or completely block
282 access. It is important to update the file whenever a cell's
283 database server machines change.
284 <P>As the <B>afsd</B> program initializes the Cache Manager, it loads the
285 contents of the file into kernel memory. The Cache Manager does not
286 read the file between reboots, so to incorporate changes to the file into
287 kernel memory, you must reboot the machine. Alternatively, you can
288 issue the <B>fs newcell</B> command to insert the changes directly into
289 kernel memory without changing the file. It can also be convenient to
290 upgrade the file from a central source. For instructions, see <A HREF="#HDRWQ406">Maintaining Knowledge of Database Server Machines</A>.
291 <P>(The <B>CellServDB</B> file on client machines is not the same as the
292 one kept in the <B>/usr/afs/etc</B> directory on server machines, which
293 lists only the local cell's database server machines. For
294 instructions on maintaining the server <B>CellServDB</B> file, see <A HREF="auagd008.htm#HDRWQ118">Maintaining the Server CellServDB File</A>).
295 <A NAME="IDX7327"></A>
296 <A NAME="IDX7328"></A>
298 </B><DD>This optional ASCII file lists one or more of the network interface
299 addresses on the client machine. If it exists when the Cache Manager
300 initializes, the Cache Manager uses it as the basis for the list of interfaces
301 that it registers with File Servers. See <A HREF="#HDRWQ415">Managing Multihomed Client Machines</A>.
302 <A NAME="IDX7329"></A>
303 <A NAME="IDX7330"></A>
304 <P><DT><B>NetRestrict
305 </B><DD>This optional ASCII file lists one or more network interface
306 addresses. If it exists when the Cache Manager initializes, the Cache
307 Manager removes the specified addresses from the list of interfaces that it
308 registers with File Servers. See <A HREF="#HDRWQ415">Managing Multihomed Client Machines</A>.
309 <A NAME="IDX7331"></A>
310 <A NAME="IDX7332"></A>
312 </B><DD>This ASCII file contains a single line that specifies the complete
313 domain-style name of the cell to which the machine belongs. Examples
314 are <TT>abc.com</TT> and <TT>stateu.edu</TT>. This
315 value defines the default cell in which the machine's users become
316 authenticated, and in which the command interpreters (for example, the
317 <B>bos</B> command) contact server processes.
318 <P>The <I>IBM AFS Quick Beginnings</I> explains how to create this file as
319 you install the AFS client functionality. To learn about changing a
320 client machine's cell membership, see <A HREF="#HDRWQ411">Setting a Client Machine's Cell Membership</A>.
322 <P>In addition to these files, the <B>/usr/vice/etc</B> directory also
323 sometimes contains the following types of files and subdirectories:
325 <A NAME="IDX7333"></A>
326 <A NAME="IDX7334"></A>
327 <A NAME="IDX7335"></A>
328 <A NAME="IDX7336"></A>
329 <P><LI>The AFS initialization script, called <B>afs.rc</B> on many
330 system types. In the conventional configuration specified by the
331 <I>IBM AFS Quick Beginnings</I>, it is a symbolic link to the actual
332 script kept in the same directory as other initialization files used by the
334 <A NAME="IDX7337"></A>
335 <A NAME="IDX7338"></A>
336 <P><LI>A subdirectory that houses AFS kernel library files used by a dynamic
337 kernel loading program.
338 <A NAME="IDX7339"></A>
339 <A NAME="IDX7340"></A>
340 <P><LI>A subdirectory called <B>C</B>, which houses the Cache Manager catalog
341 file called <B>afszcm.cat</B>. The fstrace program uses the
342 catalog file to translate operation codes into character strings, which makes
343 the message in the trace log more readable. See <A HREF="auagd013.htm#HDRWQ342">About the fstrace Command Suite</A>.
345 <P><H3><A NAME="HDRWQ393" HREF="auagd002.htm#ToC_436">Cache-Related Files</A></H3>
346 <A NAME="IDX7341"></A>
347 <A NAME="IDX7342"></A>
348 <A NAME="IDX7343"></A>
349 <A NAME="IDX7344"></A>
350 <A NAME="IDX7345"></A>
351 <P>A client machine that uses a disk cache must have a local disk directory
352 devoted to the cache. The conventional mount point is
353 <B>/usr/vice/cache</B>, but you can use another partition that has more
355 <P>Do not delete or directly modify any of the files in the cache
356 directory. Doing so can cause a kernel panic, from which the only way
357 to recover is to reboot the machine. By default, only the local
358 superuser <B>root</B> can read the files directly, by virtue of owning
360 <P>A client machine that uses a memory cache keeps all of the information
361 stored in these files in machine memory instead.
363 <A NAME="IDX7346"></A>
364 <A NAME="IDX7347"></A>
366 </B><DD>A binary-format file in which the Cache Manager tracks the contents of
367 cache chunks (the <B>V</B> files in the directory, described just
368 following), including the file ID number (fID) and the data version
370 <A NAME="IDX7348"></A>
371 <A NAME="IDX7349"></A>
372 <P><DT><B>VolumeItems
373 </B><DD>A binary-format file in which the Cache Manager records the mapping
374 between mount points and the volumes from which it has fetched data.
375 The Cache Manager uses the information when responding to the <B>pwd</B>
376 command, among others.
377 <A NAME="IDX7350"></A>
378 <A NAME="IDX7351"></A>
379 <A NAME="IDX7352"></A>
380 <P><DT><B>V<VAR>n</VAR>
381 </B><DD>A cache chunk file, which expands to a maximum size (by default, 64 KB) to
382 house data fetched from AFS files. The number of <B>V</B><VAR>n</VAR>
383 files in the cache depends on the cache size among other factors. The
384 <VAR>n</VAR> is the index assigned to each file; they are numbered
385 sequentially, but the Cache Manager does not necessarily use them in order or
386 contiguously. If an AFS file is larger than the maximum size for
387 <B>V</B><VAR>n</VAR> files, the Cache Manager divides it across multiple
388 <B>V</B><VAR>n</VAR> files.
390 <HR><H2><A NAME="HDRWQ394" HREF="auagd002.htm#ToC_437">Determining the Cache Type, Size, and Location</A></H2>
391 <P>This section explains how to configure a memory or disk
392 cache, how to display and set the size of either type of cache, and how to set
393 the location of the cache directory for a disk cache.
394 <A NAME="IDX7353"></A>
395 <A NAME="IDX7354"></A>
396 <P>The Cache Manager uses a disk cache by default, and it is the preferred
397 type of caching. To configure a memory cache, include the
398 <B>-memcache</B> flag on the <B>afsd</B> command, which is normally
399 invoked in the machine's AFS initialization file. If configured to
400 use a memory cache, the Cache Manager does no disk caching, even if the
402 <P><H3><A NAME="Header_438" HREF="auagd002.htm#ToC_438">Choosing the Cache Size</A></H3>
403 <A NAME="IDX7355"></A>
404 <P>Cache size influences the performance of a client machine more directly
405 than perhaps any other cache parameter. The larger the cache, the
406 faster the Cache Manager is likely to deliver files to users. A small
407 cache can impair performance because it increases the frequency at which the
408 Cache Manager must discard cached data to make room for newly requested
409 data. When an application asks for data that has been discarded, the
410 Cache Manager must request it from the File Server, and fetching data across
411 the network is almost always slower than fetching it from the local
412 disk. The Cache Manager never discards data from a file that has been
413 modified locally but not yet stored back to the File Server. If the
414 cache is very small, the Cache Manager possible cannot find any data to
415 discard. For more information about the algorithm it uses when
416 discarding cached data, see <A HREF="#HDRWQ401">How the Cache Manager Chooses Data to Discard</A>).
417 <P>The amount of disk or memory you devote to caching depends on several
418 factors. The amount of space available in memory or on the partition
419 housing the disk cache directory imposes an absolute limit. In
420 addition, you cannot allocate more than 95% of the space available on the
421 cache directory's partition to a disk cache. The <B>afsd</B>
422 program exits without starting the Cache Manager and prints an appropriate
423 message to the standard output stream if you violate this restriction.
424 For a memory cache, you must leave enough memory for other processes and
425 applications to run. If you try to allocate more memory than is
426 actually available, the <B>afsd</B> program exits without initializing the
427 Cache Manager and produces the following message on the standard output
429 <PRE> afsd: memCache allocation failure at <VAR>number</VAR> KB
431 <P>where <VAR>number</VAR> is how many kilobytes were allocated just before the
433 <P>Within these hard limits, the factors that determine appropriate cache size
434 include the number of users working on the machine, the size of the files with
435 which they usually work, and (for a memory cache) the number of processes that
436 usually run on the machine. The higher the demand from these factors,
437 the larger the cache needs to be to maintain good performance.
438 <P>Disk caches smaller than 10 MB do not generally perform well.
439 Machines serving multiple users usually perform better with a cache of at
440 least 60 to 70 MB. The point at which enlarging the cache further does
441 not really improve performance depends on the factors mentioned previously,
442 and is difficult to predict.
443 <P>Memory caches smaller than 1 MB are nonfunctional, and the performance of
444 caches smaller than 5 MB is usually unsatisfactory. Suitable upper
445 limits are similar to those for disk caches but are probably determined more
446 by the demands on memory from other sources on the machine (number of users
447 and processes). Machines running only a few processes possibly can use
448 a smaller memory cache.
449 <P>AFS imposes an absolute limit on cache size in some versions. See
450 the <I>IBM AFS Release Notes</I> for the version you are using.
452 <P><H3><A NAME="HDRWQ395" HREF="auagd002.htm#ToC_439">Displaying and Setting the Cache Size and Location</A></H3>
453 <A NAME="IDX7356"></A>
454 <A NAME="IDX7357"></A>
455 <A NAME="IDX7358"></A>
456 <A NAME="IDX7359"></A>
457 <A NAME="IDX7360"></A>
458 <A NAME="IDX7361"></A>
459 <A NAME="IDX7362"></A>
460 <A NAME="IDX7363"></A>
461 <A NAME="IDX7364"></A>
462 <A NAME="IDX7365"></A>
463 <A NAME="IDX7366"></A>
464 <A NAME="IDX7367"></A>
465 <A NAME="IDX7368"></A>
466 <A NAME="IDX7369"></A>
467 <A NAME="IDX7370"></A>
468 <A NAME="IDX7371"></A>
469 <A NAME="IDX7372"></A>
470 <A NAME="IDX7373"></A>
471 <A NAME="IDX7374"></A>
472 <A NAME="IDX7375"></A>
473 <A NAME="IDX7376"></A>
474 <P>The Cache Manager determines how big to make the cache by reading the
475 <B>/usr/vice/etc/cacheinfo</B> file as it initializes. As directed
476 in the <I>IBM AFS Quick Beginnings</I>, you must create the file before
477 running the <B>afsd</B> program. The file also defines the
478 directory on which to mount AFS (by convention, <B>/afs</B>), and the
479 local disk directory to use for a cache directory.
480 <P>To change any of the values in the file, log in as the local superuser
481 <B>root</B>. You must reboot the machine to have the new value take
482 effect. For instructions, see <A HREF="#HDRWQ398">To edit the cacheinfo file</A>.
483 <P>To change the cache size at reboot without editing the <B>cacheinfo</B>
484 file, include the <B>-blocks</B> argument to the <B>afsd</B>
485 command; see the command's reference page in the <I>IBM AFS
486 Administration Reference</I>.
487 <P>For a disk cache, you can also use the <B>fs setcachesize</B> command
488 to reset the cache size without rebooting. The value you set persists
489 until the next reboot, at which time the cache size returns to the value
490 specified in the <B>cacheinfo</B> file or by the <B>-blocks</B>
491 argument to the <B>afsd</B> command. For instructions, see <A HREF="#HDRWQ399">To change the disk cache size without rebooting</A>.
492 <P>To display the current cache size and the amount of space the Cache Manager
493 is using at the moment, use the <B>fs getcacheparms</B> command as
494 detailed in <A HREF="#HDRWQ397">To display the current cache size</A>.
495 <P><H3><A NAME="HDRWQ396" HREF="auagd002.htm#ToC_440">To display the cache size set at reboot</A></H3>
497 <P><LI>Use a text editor or the <B>cat</B> command to display the contents of
498 the <B>/usr/vice/etc/cacheinfo</B> file.
499 <PRE> % <B>cat /usr/vice/etc/cacheinfo</B>
502 <A NAME="IDX7377"></A>
503 <A NAME="IDX7378"></A>
504 <A NAME="IDX7379"></A>
505 <A NAME="IDX7380"></A>
506 <A NAME="IDX7381"></A>
507 <A NAME="IDX7382"></A>
508 <P><H3><A NAME="HDRWQ397" HREF="auagd002.htm#ToC_441">To display the current cache size</A></H3>
510 <P><LI>Issue the <B>fs getcacheparms</B> command on the client
512 <PRE> % <B>fs getcacheparms</B>
514 <P>where <B>getca</B> is the shortest acceptable abbreviation of
515 <B>getcacheparms</B>.
516 <P>The output shows the number of kilobyte blocks the Cache Manager is using
517 as a cache at the moment the command is issued, and the current size of the
519 <PRE> AFS using 13709 of the cache's available 15000 1K byte blocks.
522 <A NAME="IDX7383"></A>
523 <A NAME="IDX7384"></A>
524 <A NAME="IDX7385"></A>
525 <A NAME="IDX7386"></A>
526 <A NAME="IDX7387"></A>
527 <P><H3><A NAME="HDRWQ398" HREF="auagd002.htm#ToC_442">To edit the cacheinfo file</A></H3>
529 <P><LI>Become the local superuser <B>root</B> on the machine, if you are not
530 already, by issuing the <B>su</B> command.
531 <PRE> % <B>su root</B>
532 Password: <VAR>root_password</VAR>
534 <P><LI>Use a text editor to edit the <B>/usr/vice/etc/cacheinfo</B> file,
535 which has three fields, separated by colons:
537 <P><LI>The first field names the local directory on which to mount the AFS
538 filespace. The conventional location is <B>/afs</B>.
539 <P><LI>The second field defines the local disk directory to use for the disk
540 cache. The conventional location is the <B>/usr/vice/cache</B>
541 directory, but you can specify an alternate directory if another partition has
542 more space available. There must always be a value in this field, but
543 the Cache Manager ignores it if the machine uses a memory cache.
544 <P><LI>The third field defines cache size as a number of kilobyte (1024-byte)
547 <P>The following example mounts the AFS filespace at the <B>/afs</B>
548 directory, names <B>/usr/vice/cache</B> as the cache directory, and sets
549 cache size to 50,000 KB:
550 <PRE> <B>/afs:/usr/vice/cache:50000</B>
553 <A NAME="IDX7388"></A>
554 <A NAME="IDX7389"></A>
555 <A NAME="IDX7390"></A>
556 <A NAME="IDX7391"></A>
557 <A NAME="IDX7392"></A>
558 <A NAME="IDX7393"></A>
559 <P><H3><A NAME="HDRWQ399" HREF="auagd002.htm#ToC_443">To change the disk cache size without rebooting</A></H3>
561 <P><LI>Become the local superuser <B>root</B> on the machine, if you are not
562 already, by issuing the <B>su</B> command.
563 <PRE> % <B>su root</B>
564 Password: <VAR>root_password</VAR>
566 <P><LI><A NAME="LIWQ400"></A>Issue the <B>fs setcachesize</B> command to set a new disk
568 <TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">This command does not work for a memory cache.
570 <PRE> # <B>fs setcachesize</B> <<VAR>size in 1K byte blocks (0 => reset)</VAR>>
574 <P><DT><B><B>setca</B>
575 </B><DD>Is the shortest acceptable abbreviation of <B>setcachesize</B>.
576 <P><DT><B><VAR>size in 1K byte blocks (0 => reset)</VAR>
577 </B><DD>Sets the number of kilobyte blocks to be used for the cache.
578 Specify a positive integer (<B>1024</B> equals 1 MB), or <B>0</B>
579 (zero) to reset the cache size to the value specified in the
580 <B>cacheinfo</B> file.
583 <A NAME="IDX7394"></A>
584 <A NAME="IDX7395"></A>
585 <A NAME="IDX7396"></A>
586 <A NAME="IDX7397"></A>
587 <A NAME="IDX7398"></A>
588 <A NAME="IDX7399"></A>
589 <P><H3><A NAME="Header_444" HREF="auagd002.htm#ToC_444">To reset the disk cache size to the default without rebooting</A></H3>
591 <P><LI>Become the local superuser <B>root</B> on the machine, if you are not
592 already, by issuing the <B>su</B> command.
593 <PRE> % <B>su root</B>
594 Password: <VAR>root_password</VAR>
596 <P><LI>Issue the <B>fs setcachesize</B> command to reset the size of the
597 local disk cache (the command does not work for a memory cache). Choose
598 one of the two following options:
600 <P><LI>To reset the cache size to the value specified in the local
601 <B>cacheinfo</B> file, specify the value <B>0</B> (zero)
602 <PRE> # <B>fs setcachesize 0</B>
604 <P><LI>To reset the cache size to the value set at the last reboot of the
605 machine, include the <B>-reset</B> flag. Unless the
606 <B>-blocks</B> argument was used on the <B>afsd</B> command, this is
607 also the value in the <B>cacheinfo</B> file.
608 <PRE> # <B>fs setcachesize -reset</B>
613 <P><DT><B><B>setca</B>
614 </B><DD>Is the shortest acceptable abbreviation of <B>setcachesize</B>.
616 </B><DD>Resets the disk cache size to the value in the third field of the
617 <B>/usr/vice/etc/cacheinfo</B> file.
619 </B><DD>Resets the cache size to the value set at the last reboot.
622 <P><H3><A NAME="HDRWQ401" HREF="auagd002.htm#ToC_445">How the Cache Manager Chooses Data to Discard</A></H3>
623 <P>When the cache is full and application programs request more
624 data from AFS, the Cache Manager must flush out cache chunks to make room for
625 the data. The Cache Manager considers two factors:
627 <P><LI>How recently an application last accessed the data.
628 <P><LI>Whether the chunk is <I>dirty</I>. A dirty chunk contains
629 changes to a file that have not yet been saved back to the permanent copy
630 stored on a file server machine.
632 <P>The Cache Manager first checks the least-recently used chunk. If it
633 is not dirty, the Cache Manager discards the data in that chunk. If the
634 chunk is dirty, the Cache Manager moves on to check the next least recently
635 used chunk. It continues in this manner until it has created a
636 sufficient number of empty chunks.
637 <P>Chunks that contain data fetched from a read-only volume are by definition
638 never dirty, so the Cache Manager can always discard them. Normally,
639 the Cache Manager can also find chunks of data fetched from read/write volumes
640 that are not dirty, but a small cache makes it difficult to find enough
641 eligible data. If the Cache Manager cannot find any data to discard, it
642 must return I/O errors to application programs that request more data from
643 AFS. Application programs usually have a means for notifying the user
644 of such errors, but not for revealing their cause.
645 <HR><H2><A NAME="HDRWQ402" HREF="auagd002.htm#ToC_446">Setting Other Cache Parameters with the afsd program</A></H2>
646 <P>There are only three cache configuration parameters you must
647 set: the mount directory for AFS, the location of the disk cache
648 directory, and the cache size. They correspond to the three fields in
649 the <B>/usr/vice/etc/cacheinfo</B> file, as discussed in <A HREF="#HDRWQ394">Determining the Cache Type, Size, and Location</A>. However, if you want to experiment with fine-tuning
650 cache performance, you can use the arguments on the <B>afsd</B> command to
651 control several other parameters. This section discusses a few of these
652 parameters that have the most direct effect on cache performance. To
653 learn more about the <B>afsd</B> command's arguments, see its
654 reference page in the <I>IBM AFS Administration Reference</I>.
655 <P>In addition, the AFS initialization script included in the AFS distribution
656 for each system type includes several variables that set several
657 <B>afsd</B> arguments in a way that is suitable for client machines of
658 different sizes and usage patterns. For instructions on using the
659 script most effectively, see the section on configuring the Cache Manager in
660 the <I>IBM AFS Quick Beginnings</I>.
661 <P><H3><A NAME="HDRWQ403" HREF="auagd002.htm#ToC_447">Setting Cache Configuration Parameters</A></H3>
662 <P>The cache configuration parameters with the most direct
663 effect on cache performance include the following:
665 <P><LI><I>total cache size.</I> This is the amount of disk space or
666 machine memory available for caching, as discussed in detail in <A HREF="#HDRWQ394">Determining the Cache Type, Size, and Location</A>.
667 <P><LI><I>number of cache chunks.</I> For a disk cache, each chunk is
668 a <B>V</B><VAR>n</VAR> file in the local cache directory (see <A HREF="#HDRWQ393">Cache-Related Files</A>). For a memory cache, each chunk is a set of
669 contiguous blocks allocated in machine memory.
670 <P>This parameter does not have as much of an effect on cache performance as
671 total size. However, adjusting it can influence how often the Cache
672 Manager must discard cached data to make room for new data. Suppose,
673 for example, that you set the disk cache size to 50 MB and the number of
674 chunks (<B>V</B><VAR>n</VAR> files) to 1,000. If each of the ten
675 users on the machine caches 100 AFS files that average 20 KB in size, then all
676 1,000 chunks are full (a chunk can contain data from only one AFS file) but
677 the cache holds only about 20 MB of data. When a user requests more
678 data from the File Server, the Cache Manager must discard cached data to
679 reclaim some chunks, even though the cache is filled to less than 50% of its
680 capacity. In such a situation, increasing the number of chunks enables
681 the Cache Manager to discard data less often.
682 <P><LI><I>chunk size.</I> This parameter determines the maximum amount
683 of data that can fit in a chunk. If a cached element is smaller than
684 the chunk size, the remaining space in the chunk is not used (a chunk can hold
685 no more than one element). If an element cannot fit in a single chunk,
686 it is split across as many chunks as needed. This parameter also
687 determines how much data the Cache Manager requests at a time from the File
688 Server (how much data per <I>fetch RPC</I>, because AFS uses partial file
690 <P>The main reason to change chunk size is because of its relation to the
691 amount of data fetched per RPC. If your network links are very fast, it
692 can improve performance to increase chunk size; if the network is
693 especially slow, it can make sense to decrease chunk size.
694 <P><LI><I>number of dcache entries in memory.</I> The Cache Manager
695 maintains one dcache entry for each cache chunk, recording a small amount of
696 information, such as the file ID (fID) and version number of the AFS file
697 corresponding to the chunk.
698 <P>For a disk cache, dcache entries reside in the
699 <B>/usr/vice/cache/CacheItems</B> file; a small number are duplicated
700 in machine memory to speed access.
701 <P>For a memory cache, the number of dcache entries equals the number of cache
702 chunks. For a discussion of the implications of this correspondence,
703 see <A HREF="#HDRWQ405">Controlling Memory Cache Configuration</A>.
705 <P>For a description of how the Cache Manager determines defaults for number
706 of chunks, chunk size, and number of dcache entries in a disk cache, see <A HREF="#HDRWQ404">Configuring a Disk Cache</A>; for a memory cache, see <A HREF="#HDRWQ405">Controlling Memory Cache Configuration</A>. The instructions also explain
707 how to use the <B>afsd</B> command's arguments to override the
709 <P><H3><A NAME="HDRWQ404" HREF="auagd002.htm#ToC_448">Configuring a Disk Cache</A></H3>
710 <P>The default number of cache chunks (<B>V</B><VAR>n</VAR>
711 files) in a disk cache is calculated by the <B>afsd</B> command to be the
712 greatest of the following:
715 <P><LI>1.5 times the result of dividing cache size by chunk size
716 (<VAR>cachesize</VAR>/<VAR>chunksize</VAR> * 1.5)
717 <P><LI>The result of dividing cachesize by 10 MB (<VAR>cachesize</VAR>/10240)
719 <P>You can override this value by specifying a positive integer with the
720 <B>-files</B> argument. Consider increasing this value if more than
721 75% of the <B>V</B><VAR>n</VAR> files are already used soon after the Cache
722 Manager finishes initializing. Consider decreasing it if only a small
723 percentage of the chunks are used at that point. In any case, never
724 specify a value less than 100, because a smaller value can cause performance
726 <P>The following example sets the number of <B>V</B><VAR>n</VAR> files to
728 <PRE> <B>/usr/vice/etc/afsd -files 2000</B>
730 <TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">It is conventional to place the <B>afsd</B> command in a machine's
731 AFS initialization file, rather than entering it in a command shell.
732 Furthermore, the values specified in this section are examples only, and are
733 not necessarily suitable for a specific machine.
735 <P>The default chunk size for a disk cache is 64 KB. In general, the
736 only reason to change it is to adjust to exceptionally slow or fast
737 networks; see <A HREF="#HDRWQ403">Setting Cache Configuration Parameters</A>. You can use the <B>-chunksize</B>
738 argument to override the default. Chunk size must be a power of 2, so
739 provide an integer between 0 (zero) and 30 to be used as an exponent of
740 2. For example, a value of 10 sets chunk size to 1 KB (2<SUP>10</SUP> =
741 1024); a value of 16 equals the default for disk caches (2<SUP>16</SUP> =
742 64 KB). Specifying a value of 0 (zero) or greater than 30 returns chunk
743 size to the default. Values less than 10 (1 KB) are not
744 recommended. The following example sets chunk size to 16 KB
746 <PRE> <B>/usr/vice/etc/afsd -chunksize 14</B>
748 <P>For a disk cache, the default number of dcache entries duplicated in memory
749 is one-half the number of chunks specified with the <B>-files</B>
750 argument, to a maximum of 2,000 entries. You can use the
751 <B>-dcache</B> argument to change the default, even exceeding 2,000 if you
752 wish. Duplicating more than half the dcache entries in memory is not
753 usually necessary, but sometimes improves performance slightly, because access
754 to memory is faster than access to disk. The following example sets the
756 <PRE> <B>/usr/vice/etc/afsd -dcache 750</B>
758 <P>When configuring a disk cache, you can combine the <B>afsd</B>
759 command's arguments in any way. The main reason for this
760 flexibility is that the setting you specify for disk cache size (in the
761 <B>cacheinfo</B> file or with the <B>-blocks</B> argument) is an
762 absolute maximum limit. You cannot override it by specifying higher
763 values for the <B>-files</B> or <B>-chunksize</B> arguments, alone or
764 in combination. A related reason is that the Cache Manager does not
765 have to reserve a set amount of memory on disk. <B>V</B><VAR>n</VAR>
766 files (the chunks in a disk cache) are initially zero-length, but can expand
767 up to the specified chunk size and shrink again, as needed. If you set
768 the number of <B>V</B><VAR>n</VAR> files to such a large value that
769 expanding all of them to the full allowable size exceeds the total cache size,
770 they simply never grow to full size.
771 <P><H3><A NAME="HDRWQ405" HREF="auagd002.htm#ToC_449">Controlling Memory Cache Configuration</A></H3>
772 <P>Configuring a memory cache differs from configuring a disk
773 cache in that not all combinations of the <B>afsd</B> command's
774 arguments are allowed. This limitation results from the greater
775 interaction between the configuration parameters in a memory cache than a disk
776 cache. If all combinations are allowed, it is possible to set the
777 parameters in an inconsistent way. A list of the acceptable and
778 unacceptable combinations follows a discussion of default values.
779 <P>The default chunk size for a memory cache is 8 KB. In general, the
780 only reason to change it is to adjust to exceptionally slow or fast
781 networks; see <A HREF="#HDRWQ403">Setting Cache Configuration Parameters</A>.
782 <P>There is no predefined default for number of chunks in a memory
783 cache. The Cache Manager instead calculates the correct number by
784 dividing the total cache size by the chunk size. Recall that for a
785 memory cache, all dcache entries must be in memory. This implies that
786 the number of chunks equals the number of dcache entries in memory, and that
787 there is no default for number of dcache entries (like the number of chunks,
788 it is calculated by dividing the total size by the chunk size).
789 <P>The following are acceptable combinations of the <B>afsd</B>
790 command's arguments when configuring a memory cache:
792 <P><LI><B>-blocks</B> alone, which overrides the cache size specified in the
793 <B>/usr/vice/etc/cacheinfo</B> file. The Cache Manager divides the
794 value of this argument by the default chunk size of eight KB to calculate the
795 number of chunks and dcache entries. The following example sets cache
796 size to five MB (5,120 KB) and the number of chunks to 640 (5,120 divided by
798 <PRE> <B>/usr/vice/etc/afsd -memcache -blocks 5120</B>
800 <P><LI><B>-chunksize</B> alone, to override the default of eight KB.
801 The chunk size must be a power of two, so provide an integer between 0 (zero)
802 and 30 to be used as an exponent of two. For example, a value of ten
803 sets chunk size to 1 KB (2<SUP>10</SUP> = 1024); a value of 13 equals the
804 default for memory caches (2<SUP>13</SUP> = 8 KB). Specifying a value
805 of 0 (zero) or greater than 30 returns the chunk size to the default.
806 Values less than ten (equivalent to 1 KB) are not recommended. The
807 following example sets the chunk size to four KB (2<SUP>12</SUP>).
808 Assuming a total cache size of four MB (4,096 KB), the resulting number of
810 <PRE> <B>/usr/vice/etc/afsd -memcache -chunksize 12</B>
812 <P><LI><B>-blocks</B> and <B>-chunksize</B> together override the
813 defaults for cache size and chunk size. The Cache Manager divides the
814 first by the second to calculate the number of chunks and dcache
815 entries. For example, the following example sets the cache size to six
816 MB (6,144 KB) and chunksize to four KB (2<SUP>12</SUP>), resulting in 1,536
818 <PRE> <B>/usr/vice/etc/afsd -memcache -blocks 6144 -chunksize 12</B>
821 <P>The following arguments or combinations explicitly set the number of chunks
822 and dcache entries. It is best not to use them, because they set the
823 cache size indirectly, forcing you to perform a hand calculation to determine
824 the size of the cache. Instead, set the <B>-blocks</B> and
825 <B>-chunksize</B> arguments alone or in combination; in those cases,
826 the Cache Manager determines the number of chunks and dcache entries
827 itself. Because the following combinations are not recommended, no
828 examples are included.
830 <P><LI>The <B>-dcache</B> argument alone explicitly sets the number of chunks
831 and dcache entries. The Cache Manager multiples this value times the
832 default chunk size of 8 KB to derive the total cache size (overriding the
833 value in the <B>cacheinfo</B> file).
834 <P><LI>The combination of <B>-dcache</B> and <B>-chunksize</B> sets the
835 chunk number and size. The Cache Manager sets the specified values and
836 multiplies them together to obtain total cache size (overriding the value in
837 the <B>cacheinfo</B> file).
839 <P>Do not use the following arguments for a memory cache:
841 <P><LI><B>-files</B> alone. This argument controls the number of
842 <B>V</B><VAR>n</VAR> files for a disk cache, but is ignored for a memory
844 <P><LI><B>-blocks</B> and <B>-dcache</B>. An error message
845 results, because it is possible to provide values such that dividing the first
846 (total size) by the second (number of chunks) results in a chunk size that is
849 <HR><H2><A NAME="HDRWQ406" HREF="auagd002.htm#ToC_450">Maintaining Knowledge of Database Server Machines</A></H2>
850 <A NAME="IDX7400"></A>
851 <A NAME="IDX7401"></A>
852 <A NAME="IDX7402"></A>
853 <A NAME="IDX7403"></A>
854 <A NAME="IDX7404"></A>
855 <A NAME="IDX7405"></A>
856 <A NAME="IDX7406"></A>
857 <A NAME="IDX7407"></A>
858 <A NAME="IDX7408"></A>
859 <P>For the users of an AFS client machine to access a cell's AFS
860 filespace and other services, the Cache Manager and other client-side agents
861 must have an accurate list of the cell's database server machines.
862 The affected functions include the following:
864 <P><LI>Accessing files. The Cache Manager contacts the Volume Location
865 (VL) Server to learn which file server machine houses the volume containing a
866 requested file or directory. If the Cache Manager cannot contact a
867 cell's VL Servers, it cannot fetch files.
868 <P><LI>Authenticating. The <B>klog</B> program and AFS-modified login
869 utilities contact the Authentication Server to obtain tokens, which the AFS
870 server processes accept as proof that the user is authenticated.
871 <P><LI>Creating protection groups. The <B>pts</B> command interpreter
872 contacts the Protection Server when users create protection groups or request
873 information from the Protection Database.
874 <P><LI>Editing access control lists (ACLs). The <B>fs</B> command
875 interpreter contacts the File Server that maintains the read/write volume
876 containing a file or directory; the location information comes from the
879 <P>To enable a machine's users to access a cell, you must list the names
880 and IP addresses of its database server machines in the
881 <B>/usr/vice/etc/CellServDB</B> file on the machine's local
882 disk. In addition to the machine's home cell, you can list any
883 foreign cells that you want to enable users to access. (To enable
884 access to a cell's filespace, you must also mount its
885 <B>root.cell</B> volume in the local AFS filespace; the
886 conventional location is just under the AFS root directory,
887 <B>/afs</B>. For instructions, see the <I>IBM AFS Quick
889 <P><H3><A NAME="Header_451" HREF="auagd002.htm#ToC_451">How Clients Use the List of Database Server Machines</A></H3>
890 <P>As the <B>afsd</B> program runs and initializes the Cache Manager,
891 it reads the contents of the <B>CellServDB</B> file into kernel
892 memory. The Cache Manager does not consult the file again until the
893 machine next reboots. In contrast, the command interpreters for the AFS
894 command suites (such as <B>fs</B> and <B>pts</B>) read the
895 <B>CellServDB</B> file each time they need to contact a database server
897 <P>When a cell's list of database server machines changes, you must
898 change both the <B>CellServDB</B> file and the list in kernel memory to
899 preserve consistent client performance; some commands probably fail if
900 the two lists of machines disagree. One possible method for updating
901 both the <B>CellServDB</B> file and kernel memory is to edit the file and
902 reboot the machine. To avoid needing to reboot, you can instead perform
903 both of the following steps:
905 <P><LI>Issue the <B>fs newcell</B> command to alter the list in kernel memory
906 directly, making the changes available to the Cache Manager.
907 <P><LI>Edit the <B>CellServDB</B> file to make the changes available to
908 command interpreters. For a description of the file's format, see <A HREF="#HDRWQ407">The Format of the CellServDB file</A>.
910 <P>The consequences of missing or incorrect information in the
911 <B>CellServDB</B> file or kernel memory are as follows:
913 <P><LI>If there is no entry for a cell, the machine's users cannot access
915 <P><LI>If a cell's entry does not include a database server machine, then
916 the Cache Manager and command interpreters never attempt to contact the
917 machine. The omission does not prevent access to the cell--as long
918 as the information about the other database server machines is correct and the
919 server processes, machines, and network are functioning correctly--but it
920 can put an undue burden on the machines that are listed. If all of the
921 listed machines become inaccessible to clients, then the cell becomes
922 inaccessible even if the omitted database server machine is functioning
924 <P><LI>If a machine's name or address is incorrect, or the machine is not
925 actually running the database server processes, then requests from clients
926 time out. Users can experience lengthy delays because they have to wait
927 the full timeout period before the Cache Manager or command interpreter
928 contacts another database server machine.
930 <P><H3><A NAME="HDRWQ407" HREF="auagd002.htm#ToC_452">The Format of the CellServDB file</A></H3>
931 <A NAME="IDX7409"></A>
932 <A NAME="IDX7410"></A>
933 <P>When editing the <B>/usr/vice/etc/CellServDB</B> file, you must use the
934 correct format for cell and machine entries. Each cell has a separate
935 entry. The first line has the following format:
936 <PRE> ><VAR>cell_name</VAR> #<VAR>organization</VAR>
938 <P>where <VAR>cell_name</VAR> is the cell's complete Internet domain name
939 (for example, <B>abc.com</B>) and <VAR>organization</VAR> is an
940 optional field that follows any number of spaces and the number sign
941 (<TT>#</TT>) and can name the organization to which the cell corresponds
942 (for example, the ABC Corporation). After the first line comes a
943 separate line for each database server machine. Each line has the
945 <PRE> <VAR>IP_address</VAR> #<VAR>machine_name</VAR>
947 <P>where <VAR>IP_address</VAR> is the machine's IP address in dotted
948 decimal format (for example, 192.12.105.3).
949 Following any number of spaces and the number sign (<TT>#</TT>) is
950 <VAR>machine_name</VAR>, the machine's fully-qualified hostname (for
951 example, <B>db1.abc.com</B>). In this case, the
952 number sign does not indicate a comment: <VAR>machine_name</VAR> is a
954 <P>The order in which the cells appear is not important, but it is convenient
955 to put the client machine's home cell first. Do not include any
956 blank lines in the file, not even after the last entry.
957 <P>The following example shows entries for two cells, each of which has three
958 database server machines:
959 <PRE> >abc.com #ABC Corporation (home cell)
960 192.12.105.3 #db1.abc.com
961 192.12.105.4 #db2.abc.com
962 192.12.105.55 #db3.abc.com
963 >stateu.edu #State University cell
964 138.255.68.93 #serverA.stateu.edu
965 138.255.68.72 #serverB.stateu.edu
966 138.255.33.154 #serverC.stateu.edu
968 <P><H3><A NAME="HDRWQ408" HREF="auagd002.htm#ToC_453">Maintaining the Client CellServDB File</A></H3>
969 <A NAME="IDX7411"></A>
970 <A NAME="IDX7412"></A>
971 <P>Because a correct entry in the <B>CellServDB</B> file is vital for
972 consistent client performance, you must also update the file on each client
973 machine whenever a cell's list of database server machines changes (for
974 instance, when you follow the instructions in the <I>IBM AFS Quick
975 Beginnings</I> to add or remove a database server machine). To
976 facilitate the client updates, you can use the <B>package</B> program,
977 which copies files from a central source in AFS to the local disk of client
978 machines. It is conventional to invoke the <B>package</B> program
979 in a client machine's AFS initialization file so that it runs as the
980 machine reboots, but you can also issue the <B>package</B> command at any
981 time. For instructions, see <A HREF="auagd016.htm#HDRWQ448">Running the package program</A>.
982 <P>If you use the <B>package</B> program, the conventional location for
983 your cell's central source <B>CellServDB</B> file is
984 <B>/afs/</B><VAR>cell_name</VAR><B>/common/etc/CellServDB</B>, where
985 <VAR>cell_name</VAR> is your cell name.
986 <A NAME="IDX7413"></A>
987 <P>Creating a symbolic or hard link from <B>/usr/vice/etc/CellServDB</B>
988 to a central source file in AFS is not a viable option. The
989 <B>afsd</B> program reads the file into kernel memory before the Cache
990 Manager is completely initialized and able to access AFS.
991 <P>Because every client machine has its own copy of the <B>CellServDB</B>
992 file, you can in theory make the set of accessible cells differ on various
993 machines. In most cases, however, it is best to maintain consistency
994 between the files on all client machines in the cell: differences
995 between machines are particularly confusing if users commonly use a variety of
996 machines rather than just one.
997 <P>The AFS Product Support group maintains a central <B>CellServDB</B>
998 file that includes all cells that have agreed to make their database server
999 machines access to other AFS cells. It is advisable to check this file
1000 periodically for updated information. See <A HREF="auagd007.htm#HDRWQ38">Making Your Cell Visible to Others</A>.
1001 <A NAME="IDX7414"></A>
1002 <P>An entry in the local <B>CellServDB</B> is one of the two requirements
1003 for accessing a cell. The other is that the cell's
1004 <B>root.cell</B> volume is mounted in the local filespace, by
1005 convention as a subdirectory of the <B>/afs</B> directory. For
1006 instructions, see <A HREF="auagd010.htm#HDRWQ213">To create a cellular mount point</A>.
1007 <TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">The <B>/usr/vice/etc/CellServDB</B> file on a client machine is not the
1008 same as the <B>/usr/afs/etc/CellServDB</B> file on the local disk of a
1009 file server machine. The server version lists only the database server
1010 machines in the server machine's home cell, because server processes
1011 never need to contact foreign cells. It is important to update both
1012 types of <B>CellServDB</B> file on all machines in the cell whenever there
1013 is a change to your cell's database server machines. For more
1014 information about maintaining the server version of the <B>CellServDB</B>
1015 file, see <A HREF="auagd008.htm#HDRWQ118">Maintaining the Server CellServDB File</A>.
1017 <A NAME="IDX7415"></A>
1018 <A NAME="IDX7416"></A>
1019 <A NAME="IDX7417"></A>
1020 <A NAME="IDX7418"></A>
1021 <A NAME="IDX7419"></A>
1022 <P><H3><A NAME="Header_454" HREF="auagd002.htm#ToC_454">To display the /usr/vice/etc/CellServDB file</A></H3>
1024 <P><LI>Use a text editor or the <B>cat</B> command to display the contents of
1025 the <B>/usr/vice/etc/CellServDB</B> file. By default, the mode bits
1026 on the file permit anyone to read it.
1027 <PRE> % <B>cat /usr/vice/etc/CellServDB</B>
1030 <A NAME="IDX7420"></A>
1031 <A NAME="IDX7421"></A>
1032 <P><H3><A NAME="Header_455" HREF="auagd002.htm#ToC_455">To display the list of database server machines in kernel memory</A></H3>
1034 <P><LI>Issue the <B>fs listcells</B> command.
1035 <PRE> % <B>fs listcells [&]</B>
1037 <P>where <B>listc</B> is the shortest acceptable abbreviation of
1039 <P>To have your shell prompt return immediately, include the ampersand
1040 (<B>&</B>), which makes the command run in the background. It
1041 can take a while to generate the complete output because the kernel stores
1042 database server machines' IP addresses only, and the <B>fs</B>
1043 command interpreter has the cell's name resolution service (such as the
1044 Domain Name Service or a local host table) translate them into
1045 hostnames. You can halt the command at any time by issuing an interrupt
1046 signal such as <B>Ctrl-c</B>.
1047 <P>The output includes a single line for each cell, in the following
1049 <PRE> Cell <VAR>cell_name</VAR> on hosts <VAR>list_of_hostnames</VAR>.
1051 <P>The name service sometimes returns hostnames in uppercase letters, and if
1052 it cannot resolve a name at all, it returns its IP address. The
1053 following example illustrates all three possibilities:
1054 <PRE> % <B>fs listcells</B>
1057 Cell abc.com on hosts db1.abc.com db2.abc.com db3.abc.com
1058 Cell stateu.edu on hosts SERVERA.STATEU.EDU SERVERB.STATEU.EDU
1060 Cell ghi.org on hosts 191.255.64.111 191.255.64.112
1065 <A NAME="IDX7422"></A>
1066 <A NAME="IDX7423"></A>
1067 <A NAME="IDX7424"></A>
1068 <A NAME="IDX7425"></A>
1069 <A NAME="IDX7426"></A>
1070 <A NAME="IDX7427"></A>
1071 <A NAME="IDX7428"></A>
1072 <A NAME="IDX7429"></A>
1073 <A NAME="IDX7430"></A>
1074 <A NAME="IDX7431"></A>
1075 <A NAME="IDX7432"></A>
1076 <P><H3><A NAME="Header_456" HREF="auagd002.htm#ToC_456">To change the list of a cell's database server machines in kernel memory</A></H3>
1078 <P><LI>Become the local superuser <B>root</B> on the machine, if you are not
1079 already, by issuing the <B>su</B> command.
1080 <PRE> % <B>su root</B>
1081 Password: <VAR>root_password</VAR>
1083 <P><LI>If you a use a central copy of the <B>CellServDB</B> file as a source
1084 for client machines, verify that its directory's ACL grants you the
1085 <B>l</B> (<B>lookup</B>), <B>r</B> (<B>read</B>), and
1086 <B>w</B> (<B>write</B>) permissions. The conventional directory
1087 is <B>/afs/</B><VAR>cell_name</VAR><B>/common/etc</B>. If
1088 necessary, issue the <B>fs listacl</B> command, which is fully described
1089 in <A HREF="auagd020.htm#HDRWQ572">Displaying ACLs</A>.
1090 <PRE> # <B>fs listacl</B> [<<VAR>dir/file path</VAR>>]
1092 <A NAME="IDX7433"></A>
1093 <A NAME="IDX7434"></A>
1094 <P><LI><A NAME="LINEWCELL"></A>Issue the <B>fs newcell</B> command to add or change a
1095 cell's entry in kernel memory. Repeat the command for each
1097 <TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">You cannot use this command to remove a cell's entry completely from
1098 kernel memory. In the rare cases when you urgently need to prevent
1099 access to a specific cell, you must edit the <B>CellServDB</B> file and
1102 <PRE> # <B>fs newcell</B> <<VAR>cell name</VAR>> <<VAR>primary servers</VAR>><SUP>+</SUP> \
1103 [<B>-linkedcell</B> <<VAR>linked cell name</VAR>>]
1108 </B><DD>Is the shortest acceptable abbreviation of <B>newcell</B>.
1109 <P><DT><B><VAR>cell name</VAR>
1110 </B><DD>Specifies the complete Internet domain name of the cell for which to
1111 record a new list of database server machines.
1112 <P><DT><B><VAR>primary servers</VAR>
1113 </B><DD>Specifies the fully-qualified hostname or IP address in dotted-decimal
1114 format for each database server machine in the cell. The list you
1115 provide completely replaces the existing list.
1116 <P><DT><B>-linkedcell
1117 </B><DD>Specifies the complete Internet domain name of the AFS cell to link to a
1118 DCE cell for the purposes of DFS fileset location. You can use this
1119 argument if the machine's AFS users access DFS via the AFS/DFS Migration
1120 Toolkit Protocol Translator. For instructions, see the <I>IBM AFS/DFS
1121 Migration Toolkit Administration Guide and Reference</I>.
1123 <P><LI>Add or edit the cell's entry in the local
1124 <B>/usr/vice/etc/CellServDB</B> file, using one of the following three
1125 methods. In each case, be sure to obey the formatting requirements
1126 described in <A HREF="#HDRWQ407">The Format of the CellServDB file</A>.
1128 <P><LI>If you maintain a central source version of the <B>CellServDB</B> file
1129 and use the <B>package</B> program, first use a text editor to alter the
1130 central copy of the file. Then issue the <B>package</B> command to
1131 transfer the contents of the file to the local machine. For complete
1132 instructions, see <A HREF="auagd016.htm#HDRWQ448">Running the package program</A>.
1133 <PRE> # <B>/etc/package -v -c</B> <<VAR>name of package file</VAR>>
1135 <P><LI>If you maintain a central source <B>CellServDB</B> file but do not use
1136 the <B>package</B> program, first use a text editor to alter the central
1137 copy of the file. Then use a copying command such as the <B>cp</B>
1138 command to copy it to the local <B>/usr/vice/etc/CellServDB</B>
1140 <P><LI>If you do not use a central source <B>CellServDB</B> file, edit the
1141 local machine's <B>/usr/vice/etc/CellServDB</B> file directly.
1144 <HR><H2><A NAME="HDRWQ409" HREF="auagd002.htm#ToC_457">Determining if a Client Can Run Setuid Programs</A></H2>
1145 <A NAME="IDX7435"></A>
1146 <A NAME="IDX7436"></A>
1147 <A NAME="IDX7437"></A>
1148 <P>A <I>setuid program</I> is one whose binary file has the UNIX setuid
1149 mode bit turned on. While a setuid program runs, the user who
1150 initialized it assumes the local identity (UNIX UID) of the binary file's
1151 owner, and so is granted the permissions in the local file system that pertain
1152 to the owner. Most commonly, the issuer's assumed identity (often
1153 referred to as <I>effective UID</I>) is the local superuser
1155 <P>AFS does not recognize effective UID: if a setuid program accesses
1156 AFS files and directories, it uses the current AFS identity of the user who
1157 initialized the program, not of the program's owner. Nevertheless,
1158 it can be useful to store setuid programs in AFS for use on more than one
1159 client machine. AFS enables a client machine's administrator to
1160 determine whether the local Cache Manager allows setuid programs to run or
1162 <P>By default, the Cache Manager allows programs from its home cell to run
1163 with setuid permission, but denies setuid permission to programs from foreign
1164 cells. A program belongs to the same cell as the file server machine
1165 that houses the volume in which the file resides, as specified in the file
1166 server machine's <B>/usr/afs/etc/ThisCell</B> file. The Cache
1167 Manager determines its own home cell by reading the
1168 <B>/usr/vice/etc/ThisCell</B> file at initialization.
1169 <P>To change a cell's setuid status with respect to the local machine,
1170 become the local superuser <B>root</B> and issue the <B>fs setcell</B>
1171 command. To determine a cell's current setuid status, use the
1172 <B>fs getcellstatus</B> command.
1173 <P>When you issue the <B>fs setcell</B> command, you directly alter a
1174 cell's setuid status as recorded in kernel memory, so rebooting the
1175 machine is not necessary. However, nondefault settings do not persist
1176 across reboots of the machine unless you add the appropriate <B>fs
1177 setcell</B> command to the machine's AFS initialization file.
1178 <P>Only members of the <B>system:administrators</B> group can turn
1179 on the setuid mode bit on an AFS file or directory. When the setuid
1180 mode bit is turned on, the UNIX <B>ls -l</B> command displays the third
1181 user mode bit as an <B>s</B> instead of an <B>x</B>, but for an AFS
1182 file or directory, the <B>s</B> appears only if setuid permission is
1183 enabled for the cell in which the file resides.
1184 <A NAME="IDX7438"></A>
1185 <A NAME="IDX7439"></A>
1186 <P><H3><A NAME="Header_458" HREF="auagd002.htm#ToC_458">To determine a cell's setuid status</A></H3>
1188 <P><LI>Issue the <B>fs getcellstatus</B> command to check the setuid status
1189 of each desired cell.
1190 <PRE> % <B>fs getcellstatus</B> <<VAR>cell name</VAR>>
1194 <P><DT><B><B>getce</B>
1195 </B><DD>Is the shortest acceptable abbreviation of
1196 <B>getcellstatus</B>.
1197 <P><DT><B><VAR>cell name</VAR>
1198 </B><DD>Names each cell for which to report setuid status. Provide the
1199 complete Internet domain name or a shortened form that distinguishes it from
1200 the other cells listed in the local <B>/usr/vice/etc/CellServDB</B>
1204 <P>The output reports the setuid status of each cell:
1206 <P><LI>the string <TT>no setuid allowed</TT> indicates that the Cache Manager
1207 does not allow programs from the cell to run with setuid permission
1208 <P><LI><TT>setuid allowed</TT> indicates that the Cache Manager allows programs
1209 from the cell to run with setuid permission
1211 <A NAME="IDX7440"></A>
1212 <A NAME="IDX7441"></A>
1213 <P><H3><A NAME="Header_459" HREF="auagd002.htm#ToC_459">To change a cell's setuid status</A></H3>
1215 <P><LI>Become the local superuser <B>root</B> on the machine, if you are not
1216 already, by issuing the <B>su</B> command.
1217 <PRE> % <B>su root</B>
1218 Password: <VAR>root_password</VAR>
1220 <P><LI>Issue the <B>fs setcell</B> command to change the setuid status of the
1222 <PRE> # <B>fs setcell</B> <<VAR>cell name</VAR>><SUP>+</SUP> [<B>-suid</B>] [<B>-nosuid</B>]
1226 <P><DT><B><B>setce</B>
1227 </B><DD>Is the shortest acceptable abbreviation of <B>setcell</B>.
1228 <P><DT><B><VAR>cell name</VAR>
1229 </B><DD>Names each cell for which to change setuid status as specified by the
1230 <B>-suid</B> or <B>-nosuid</B> flag. Provide each cell's
1231 complete Internet domain name or a shortened form that distinguishes it from
1232 the other cells listed in the local <B>/usr/vice/etc/CellServDB</B>
1234 <P><DT><B><B>-suid</B>
1235 </B><DD>Enables programs from each specified cell to execute with setuid
1236 permission. Provide this flag or the <B>-nosuid</B> flag, or omit
1237 both to disable setuid permission for each cell.
1238 <P><DT><B><B>-nosuid</B>
1239 </B><DD>Prevents programs from each specified cell from executing with setuid
1240 permission. Provide this flag or the <B>-suid</B> flag, or omit
1241 both to disable setuid permission for each cell.
1244 <HR><H2><A NAME="HDRWQ410" HREF="auagd002.htm#ToC_460">Setting the File Server Probe Interval</A></H2>
1245 <A NAME="IDX7442"></A>
1246 <A NAME="IDX7443"></A>
1247 <A NAME="IDX7444"></A>
1248 <P>The Cache Manager periodically sends a probe to server machines to verify
1249 that they are still accessible. Specifically, it probes the database
1250 server machines in its cell and those file servers that house data it has
1252 <P>If a server process does not respond to a probe, the client machine assumes
1253 that it is inaccessible. By default, the interval between probes is
1254 three minutes, so it can take up to three minutes for a client to recognize
1255 that a server process is once again accessible after it was
1257 <P>To adjust the probe interval, include the <B>-interval</B> argument to
1258 the <B>fs checkservers</B> command while logged in as the local superuser
1259 <B>root</B>. The new interval setting persists until you again
1260 issue the command or reboot the machine, at which time the setting returns to
1261 the default. To preserve a nondefault setting across reboots, include
1262 the appropriate <B>fs checkservers</B> command in the machine's AFS
1263 initialization file.
1264 <P><H3><A NAME="Header_461" HREF="auagd002.htm#ToC_461">To set a client's file server probe interval</A></H3>
1266 <P><LI>Become the local superuser <B>root</B> on the machine, if you are not
1267 already, by issuing the <B>su</B> command.
1268 <PRE> % <B>su root</B>
1269 Password: <VAR>root_password</VAR>
1271 <P><LI>Issue the <B>fs checkservers</B> command with the <B>-interval</B>
1273 <A NAME="IDX7445"></A>
1274 <A NAME="IDX7446"></A>
1276 <PRE> # <B>fs checkservers -interval</B> <<VAR>seconds between probes</VAR>>
1280 <P><DT><B><B>checks</B>
1281 </B><DD>Is the shortest acceptable abbreviation of <B>checkservers</B>.
1283 </B><DD>Specifies the number of seconds between probes. Provide an integer
1284 value greater than zero.
1287 <HR><H2><A NAME="HDRWQ411" HREF="auagd002.htm#ToC_462">Setting a Client Machine's Cell Membership</A></H2>
1288 <A NAME="IDX7447"></A>
1289 <A NAME="IDX7448"></A>
1290 <A NAME="IDX7449"></A>
1291 <A NAME="IDX7450"></A>
1292 <A NAME="IDX7451"></A>
1293 <A NAME="IDX7452"></A>
1294 <P>Each client machine belongs to a particular cell, as named in the
1295 <B>/usr/vice/etc/ThisCell</B> on its local disk. The machine's
1296 cell membership determines three defaults important to users of the
1299 <P><LI>The cell for which users of the machine obtain tokens (authenticate) when
1300 they use the <B>login</B> program or issue the <B>klog</B>
1301 command. There are two effects:
1303 <P><LI>The <B>klog</B> program and AFS-modified login utilities contact an
1304 Authentication Server in the cell named in the <B>ThisCell</B>
1306 <P><LI>The <B>klog</B> program and AFS-modified login utilities combine the
1307 contents of the <B>ThisCell</B> file with the password that the user
1308 provides, generating an encryption key from the combination. The
1309 user's entry in the Authentication Database includes an encryption key
1310 also generated from the combination of password and cell name. If the
1311 cell name in the <B>ThisCell</B> file is incorrect, users cannot
1312 authenticate even if they provide the correct password.
1314 <P><LI>The cell the Cache Manager considers its local, or home, cell. The
1315 Cache Manager allows programs from its local cell to run with setuid
1316 permission, but not programs from foreign cells, as discussed further in <A HREF="#HDRWQ409">Determining if a Client Can Run Setuid Programs</A>.
1317 <P><LI>The default database server machines that are contacted by the AFS command
1318 interpreters running on this machine.
1320 <P><H3><A NAME="Header_463" HREF="auagd002.htm#ToC_463">To display a client machine's cell membership</A></H3>
1322 <P><LI>Use a text editor or the <B>cat</B> command to display the contents of
1323 the <B>/usr/vice/etc/ThisCell</B> file.
1324 <PRE> % <B>cat /usr/vice/etc/ThisCell</B>
1327 <P><H3><A NAME="Header_464" HREF="auagd002.htm#ToC_464">To set a client machine's cell membership</A></H3>
1329 <P><LI>Become the local superuser <B>root</B> on the machine, if you are not
1330 already, by issuing the <B>su</B> command.
1331 <PRE> % <B>su root</B>
1332 Password: <VAR>root_password</VAR>
1334 <P><LI>Using a text editor, replace the cell name in the
1335 <B>/usr/vice/etc/ThisCell</B> file.
1336 <P><LI><B>(Optional.)</B> Reboot the machine to enable the Cache
1337 Manager to use the new cell name immediately; the appropriate command
1338 depends on the machine's system type. The <B>klog</B> program,
1339 AFS-modified login utilities, and the AFS command interpreters use the new
1340 cell name the next time they are invoked; no reboot is necessary.
1346 <HR><H2><A NAME="HDRWQ412" HREF="auagd002.htm#ToC_465">Forcing the Update of Cached Data</A></H2>
1347 <A NAME="IDX7453"></A>
1348 <A NAME="IDX7454"></A>
1349 <A NAME="IDX7455"></A>
1350 <A NAME="IDX7456"></A>
1351 <A NAME="IDX7457"></A>
1352 <A NAME="IDX7458"></A>
1353 <A NAME="IDX7459"></A>
1354 <A NAME="IDX7460"></A>
1355 <P>AFS's callback mechanism normally guarantees that the Cache Manager
1356 provides the most current version of a file or directory to the application
1357 programs running on its machine. However, you can force the Cache
1358 Manager to discard (flush) cached data so that the next time an application
1359 program requests it, the Cache Manager fetches the latest version available at
1361 <P>You can control how many file system elements to flush at a time:
1363 <P><LI>To flush only specific files or directories, use the <B>fs flush</B>
1364 command. This command forces the Cache Manager to discard the data and
1365 status information it has cached from the specified files or
1366 directories. It does not discard information from an application
1367 program's buffer or information that has been altered locally (changes
1368 made in the cache but not yet saved permanently to the File Server).
1369 However, the next time an application requests the element's data or
1370 status information, the Cache Manager has to contact the File Server to get
1372 <P><LI>To flush everything cached from a certain volume, use the <B>fs
1373 flushvolume</B> command. This command works like the <B>fs
1374 flush</B> command, but differs in two ways:
1376 <P><LI>The Cache Manager discards data for all elements in the cache that come
1377 from the same volume as the specified files or directories.
1378 <P><LI>The Cache Manager discards only data, not status information. This
1379 difference has little practical effect, but can lead to different output from
1380 the <B>ls</B> command when the two different commands are used to flush
1384 <P>In addition to callbacks, the Cache Manager has a mechanism for tracking
1385 other kinds of possible changes, such as changes in a volume's
1386 location. If a volume moves and the Cache Manager has not accessed any
1387 data in it for a long time, the Cache Manager's volume location record
1388 can be wrong. To resynchronize it, use the <B>fs checkvolumes</B>
1389 command. When you issue the command, the Cache Manager creates a new
1390 table of mappings between volume names, ID numbers, and locations. This
1391 forces the Cache Manager to reference newly relocated and renamed volumes
1392 before it can provide data from them.
1393 <P>It is also possible for information about mount points to become corrupted
1394 in the cache. Symptoms of a corrupted mount point included garbled
1395 output from the <B>fs lsmount</B> command, and failed attempts to change
1396 directory to or list the contents of a mount point. Use the <B>fs
1397 flushmount</B> command to discard a corrupted mount point. The Cache
1398 Manager must refetch the mount point the next time it crosses it in a
1399 pathname. (The Cache Manager periodically refreshes cached mount
1400 points, but the only other way to discard them immediately is to reinitialize
1401 the Cache Manager by rebooting the machine.
1402 <A NAME="IDX7461"></A>
1403 <A NAME="IDX7462"></A>
1404 <P><H3><A NAME="Header_466" HREF="auagd002.htm#ToC_466">To flush certain files or directories</A></H3>
1406 <P><LI>Issue the <B>fs flush</B> command.
1407 <PRE> % <B>fs flush</B> [<<VAR>dir/file path</VAR>><SUP>+</SUP>]
1411 <P><DT><B><B>flush</B>
1412 </B><DD>Must be typed in full.
1413 <P><DT><B><VAR>dir/file path</VAR>
1414 </B><DD>Names each file or directory structure to flush from the cache.
1415 Omit this argument to flush the current working directory. Flushing a
1416 directory structure does not flush any files or subdirectories cached from
1420 <A NAME="IDX7463"></A>
1421 <A NAME="IDX7464"></A>
1422 <P><H3><A NAME="Header_467" HREF="auagd002.htm#ToC_467">To flush all data from a volume</A></H3>
1424 <P><LI>Issue the <B>fs flushvolume</B> command.
1425 <PRE> % <B>fs flushvolume</B> [<<VAR>dir/file path</VAR>><SUP>+</SUP>]
1429 <P><DT><B><B>flushv</B>
1430 </B><DD>Is the shortest acceptable abbreviation of <B>flushvolume</B>.
1431 <P><DT><B><VAR>dir/file path</VAR>
1432 </B><DD>Names a file or directory from each volume to flush from the cache.
1433 The Cache Manager flushes everything in the cache that it has fetched from the
1434 same volume. Omit this argument to flush all cached data fetched from
1435 the volume that contains the current working directory.
1438 <A NAME="IDX7465"></A>
1439 <A NAME="IDX7466"></A>
1440 <P><H3><A NAME="Header_468" HREF="auagd002.htm#ToC_468">To force the Cache Manager to notice other volume changes</A></H3>
1442 <P><LI>Issue the <B>fs checkvolumes</B> command.
1443 <PRE> % <B>fs checkvolumes</B>
1445 <P>where <B>checkv</B> is the shortest acceptable abbreviation of
1446 <B>checkvolumes</B>.
1448 <P>The following command confirms that the command completed
1450 <PRE> All volumeID/name mappings checked.
1452 <A NAME="IDX7467"></A>
1453 <A NAME="IDX7468"></A>
1454 <P><H3><A NAME="HDRWQ413" HREF="auagd002.htm#ToC_469">To flush one or more mount points</A></H3>
1456 <P><LI>Issue the <B>fs flushmount</B> command.
1457 <PRE> % <B>fs flush</B> [<<VAR>dir/file path</VAR>><SUP>+</SUP>]
1461 <P><DT><B><B>flushm</B>
1462 </B><DD>Is the shortest acceptable abbreviation of <B>flushmount</B>.
1463 <P><DT><B><VAR>dir/file path</VAR>
1464 </B><DD>Names each mount point to flush from the cache. Omit this argument
1465 to flush the current working directory. Files or subdirectories cached
1466 from the associated volume are unaffected.
1469 <HR><H2><A NAME="HDRWQ414" HREF="auagd002.htm#ToC_470">Maintaining Server Preference Ranks</A></H2>
1470 <A NAME="IDX7469"></A>
1471 <A NAME="IDX7470"></A>
1472 <A NAME="IDX7471"></A>
1473 <A NAME="IDX7472"></A>
1474 <A NAME="IDX7473"></A>
1475 <A NAME="IDX7474"></A>
1476 <P>As mentioned in the introduction to this chapter, AFS uses client-side data
1477 caching and callbacks to reduce the amount of network traffic in your
1478 cell. The Cache Manager also tries to make its use of the network as
1479 efficient as possible by assigning <I>preference ranks</I> to server
1480 machines based on their network proximity to the local machine. The
1481 ranks bias the Cache Manager to fetch information from the server machines
1482 that are on its own subnetwork or network rather than on other networks, if
1483 possible. Reducing the network distance that data travels between
1484 client and server machine tends to reduce network traffic and speed the Cache
1485 Manager's delivery of data to applications.
1486 <P>The Cache Manager stores two separate sets of preference ranks in kernel
1487 memory. The first set of ranks applies to machines that run the Volume
1488 Location (VL) Server process, hereafter referred to as <I>VL Server
1489 machines</I>. The second set of ranks applies to machines that run
1490 the File Server process, hereafter referred to as <I>file server
1491 machines</I>. This section explains how the Cache Manager sets
1492 default ranks, how to use the <B>fs setserverprefs</B> command to change
1493 the defaults or set new ranks, and how to use the <B>fs getserverprefs</B>
1494 command to display the current set of ranks.
1495 <P><H3><A NAME="Header_471" HREF="auagd002.htm#ToC_471">How the Cache Manager Sets Default Ranks</A></H3>
1496 <P>As the <B>afsd</B> program initializes the Cache Manager, it
1497 assigns a preference rank of 10,000 to each of the VL Server machines listed
1498 in the local <B>/usr/vice/etc/CellServDB</B> file. It then
1499 randomizes the ranks by adding an integer randomly chosen from the range 0
1500 (zero) to 126. It avoids assigning the same rank to machines in one
1501 cell, but it is possible for machines from different cells to have the same
1502 rank. This does not present a problem in use, because the Cache Manager
1503 compares the ranks of only one cell's database server machines at a
1504 time. Although AFS supports the use of multihomed database server
1505 machines, the Cache Manager only uses the single address listed for each
1506 database server machine in the local <B>/usr/vice/etc/CellServDB</B>
1507 file. Only Ubik can take advantage of a multihomed database server
1508 machine's multiple interfaces.
1509 <P>The Cache Manager assigns preference ranks to a file server machine when it
1510 obtains the server's VLDB record from the VL Server, the first time that
1511 it accesses a volume that resides on the machine. If the machine is
1512 multihomed, the Cache Manager assigns a distinct rank to each of its
1513 interfaces (up to the number of interfaces that the VLDB can store for each
1514 machine, which is specified in the <I>IBM AFS Release Notes</I>).
1515 The Cache Manager compares the interface's IP address to the local
1516 machine's address and applies the following algorithm:
1518 <P><LI>If the local machine is a file server machine, the base rank for each of
1519 its interfaces is 5,000.
1520 <P><LI>If the file server machine interface is on the same subnetwork as the
1521 local machine, its base rank is 20,000.
1522 <P><LI>If the file server machine interface is on the same network as the local
1523 machine, or is at the distant end of a point-to-point link with the local
1524 machine, its base rank is 30,000.
1525 <P><LI>If the file server machine interface is on a different network than the
1526 local machine, or the Cache Manager cannot obtain network information about
1527 it, its base rank is 40,000.
1529 <P>If the client machine has only one interface, the Cache Manager compares it
1530 to the server interface's IP address and sets a rank according to the
1531 algorithm. If the client machine is multihomed, the Cache Manager
1532 compares each of the local interface addresses to the server interface, and
1533 assigns to the server interface the lowest rank that results from comparing it
1534 to all of the client interfaces.
1535 <P>After assigning a base rank to a file server machine interface, the Cache
1536 Manager adds to it a number randomly chosen from the range 0 (zero) to
1537 15. As an example, a file server machine interface in the same
1538 subnetwork as the local machine receives a base rank of 20,000, but the Cache
1539 Manager records the actual rank as an integer between 20,000 and
1540 20,015. This process reduces the number of interfaces that have exactly
1541 the same rank. As with VL Server machine ranks, it is possible for file
1542 server machine interfaces from foreign cells to have the same rank as
1543 interfaces in the local cell, but this does not present a problem. Only
1544 the relative ranks of the interfaces that house a specific volume are
1545 relevant, and AFS supports storage of a volume in only one cell at a
1547 <P><H3><A NAME="Header_472" HREF="auagd002.htm#ToC_472">How the Cache Manager Uses Preference Ranks</A></H3>
1548 <P>Each preference rank pairs an interface's IP address with an
1549 integer that can range from 1 to 65,534. A lower rank (lower number)
1550 indicates a stronger preference. Once set, a rank persists until the
1551 machine reboots, or until you use the <B>fs setserverprefs</B> command to
1553 <P>The Cache Manager uses VL Server machine ranks when it needs to fetch
1554 volume location information from a cell. It compares the ranks for the
1555 cell's VL Server machines and attempts to contact the VL Server process
1556 on the machine with the best (lowest integer) rank. If it cannot reach
1557 that VL Server, it tries to contact the VL Server with the next best rank, and
1558 so on. If all of a cell's VL Server machines are inaccessible, the
1559 Cache Manager cannot fetch data from the cell.
1560 <P>Similarly, when the Cache Manager needs to fetch data from a volume, it
1561 compares the ranks for the interfaces of machines that house the volume, and
1562 attempts to contact the interface that has the best rank. If it cannot
1563 reach the <B>fileserver</B> process via that interface, it tries to
1564 contact the interface with the next best integer rank, and so on. If it
1565 cannot reach any of the interfaces for machines that house the volume, it
1566 cannot fetch data from the volume.
1567 <P><H3><A NAME="Header_473" HREF="auagd002.htm#ToC_473">Displaying and Setting Preference Ranks</A></H3>
1568 <P>To display the file server machine ranks that the Cache Manager is
1569 using, use the <B>fs getserverprefs</B> command. Include the
1570 <B>-vlservers</B> flag to display VL Server machine ranks instead.
1571 By default, the output appears on the standard output stream (stdout), but you
1572 can write it to a file instead by including the <B>-file</B>
1574 <P>The Cache Manager stores IP addresses rather than hostnames in its kernel
1575 list of ranks, but by default the output identifies interfaces by hostname
1576 after calling a translation routine that refers to either the cell's name
1577 service (such as the Domain Name Server) or the local host table. If an
1578 IP address appears in this case, it is because the translation attempt
1579 failed. To bypass the translation step and display IP addresses rather
1580 than hostnames, include the <B>-numeric</B> flag. This can
1581 significantly speed up the output.
1582 <P>You can use the <B>fs setserverprefs</B> command to reset an existing
1583 preference rank, or to set the initial rank of a file server machine interface
1584 or VL Server machine for which the Cache Manager has no rank. The ranks
1585 you set persist until the machine reboots or until you issue the <B>fs
1586 setserverprefs</B> command again. To make a rank persist across a
1587 reboot, place the appropriate <B>fs setserverprefs</B> command in the
1588 machine's AFS initialization file.
1589 <P>As with default ranks, the Cache Manager adds a randomly chosen integer to
1590 each rank range that you assign. For file server machine interfaces,
1591 the randomizing number is from the range 0 (zero) to 15; for VL Server
1592 machines, it is from the range 0 (zero) to 126. For example, if you
1593 assign a rank of 15,000 to a file server machine interface, the Cache Manager
1594 stores an integer between 15,000 to 15,015.
1595 <P>To assign VL Server machine ranks, list them after the <B>-vlserver</B>
1596 argument to the <B>fs setserverprefs</B> command.
1597 <P>To assign file server machine ranks, use or more of the three possible
1600 <P><LI>List them after the <B>-servers</B> argument on the command
1602 <P><LI>Record them in a file and name it with the <B>-file</B>
1603 argument. You can easily generate a file with the proper format by
1604 including the <B>-file</B> argument to the <B>fs getserverprefs</B>
1606 <P><LI>Provide them via the standard input stream, by including the
1607 <B>-stdin</B> flag. This enables you to feed in values directly
1608 from a command or script that generates preferences using an algorithm
1609 appropriate for your cell. It must generate them in the proper format,
1610 with one or more spaces between each pair and between the two parts of the
1611 pair. The AFS distribution does not include such a script, so you must
1612 write one if you want to use this method.
1614 <P>You can combine any of the <B>-servers</B>, <B>-file</B>, and
1615 <B>-stdin</B> options on the same command line if you wish. If more
1616 than one of them specifies a rank for the same interface, the one assigned
1617 with the <B>-servers</B> argument takes precedence. You can also
1618 provide the <B>-vlservers</B> argument on the same command line to set VL
1619 Server machine ranks at the same time as file server machine ranks.
1620 <P>The <B>fs</B> command interpreter does not verify hostnames or IP
1621 addresses, and so willingly stores ranks for hostnames and addresses that
1622 don't actually exist. The Cache Manager never uses such ranks
1623 unless the same VLDB record for a server machine records the same incorrect
1625 <A NAME="IDX7475"></A>
1626 <A NAME="IDX7476"></A>
1627 <P><H3><A NAME="Header_474" HREF="auagd002.htm#ToC_474">To display server preference ranks</A></H3>
1629 <P><LI>Issue the <B>fs getserverprefs</B> command to display the Cache
1630 Manager's preference ranks for file server machines or VL Server
1632 <PRE> % <B>fs getserverprefs</B> [<B>-file</B> <<VAR>output to named file</VAR>>] [<B>-numeric</B>] [<B>-vlservers</B>]
1637 </B><DD>Is an acceptable alias for <B>getserverprefs</B> (<B>gets</B> is
1638 the shortest acceptable abbreviation).
1640 </B><DD>Specifies the pathname of the file to which to write the list of
1641 ranks. Omit this argument to display the list on the standard output
1644 </B><DD>Displays the IP address, rather than the hostname, of each ranked machine
1645 interface. Omit this flag to have the addresses translated into
1646 hostnames, which takes longer.
1647 <P><DT><B>-vlservers
1648 </B><DD>Displays ranks for VL Server machines rather than file server
1651 <P>The following example displays file server machine ranks. The
1652 <B>-numeric</B> flag is not used, so the appearance of an IP address
1653 indicates that is not currently possible to translate it to a hostname.
1655 <PRE> % <B>fs gp</B>
1658 server1.stateu.edu 40011
1661 192.12.106.120 40002
1662 192.12.106.119 40001
1666 <A NAME="IDX7477"></A>
1667 <A NAME="IDX7478"></A>
1668 <A NAME="IDX7479"></A>
1669 <P><H3><A NAME="Header_475" HREF="auagd002.htm#ToC_475">To set server preference ranks</A></H3>
1671 <P><LI>Become the local superuser <B>root</B> on the machine, if you are not
1672 already, by issuing the <B>su</B> command.
1673 <PRE> % <B>su root</B>
1674 Password: <VAR>root_password</VAR>
1676 <P><LI>Issue the <B>fs setserverprefs</B> command to set the Cache
1677 Manager's preference ranks for one or more file server machines or VL
1679 <PRE> # <B>fs setserverprefs</B> [<B>-servers</B> <<VAR>fileserver names and ranks</VAR>><SUP>+</SUP>] \
1680 [<B>-vlservers</B> <<VAR>VL server names and ranks</VAR>><SUP>+</SUP>] \
1681 [<B>-file</B> <<VAR>input from named file</VAR>>] [<B>-stdin</B>]
1686 </B><DD>Is an acceptable alias for <B>setserverprefs</B> (<B>sets</B> is
1687 the shortest acceptable abbreviation).
1689 </B><DD>Specifies one or more pairs of file server machine interface and
1690 rank. Identify each interface by its fully-qualified hostname or IP
1691 address in dotted decimal format. Acceptable ranks are the integers
1692 from <B>1</B> to <B>65534</B>. Separate the parts of a pair,
1693 and the pairs from one another, with one or more spaces.
1694 <P><DT><B>-vlservers
1695 </B><DD>Specifies one or more pairs of VL Server machine and rank. Identify
1696 each machine by its fully-qualified hostname or IP address in dotted decimal
1697 format. Acceptable ranks are the integers from <B>1</B> to
1700 </B><DD>Specifies the pathname of a file that contains one more pairs of file
1701 server machine interface and rank. Place each pair on its own line in
1702 the file. Use the same format for interfaces and ranks as with the
1703 <B>-servers</B> argument.
1705 </B><DD>Indicates that pairs of file server machine interface and rank are being
1706 provided via the standard input stream (stdin). The program or script
1707 that generates the pairs must format them in the same manner as for the
1708 <B>-servers</B> argument.
1711 <HR><H2><A NAME="HDRWQ415" HREF="auagd002.htm#ToC_476">Managing Multihomed Client Machines</A></H2>
1712 <A NAME="IDX7480"></A>
1713 <A NAME="IDX7481"></A>
1714 <A NAME="IDX7482"></A>
1715 <A NAME="IDX7483"></A>
1716 <A NAME="IDX7484"></A>
1717 <A NAME="IDX7485"></A>
1718 <P>The File Server can choose the interface to which to send a message when it
1719 initiates communication with the Cache Manager on a multihomed client machine
1720 (one with more than one network interface and IP address). If that
1721 interface is inaccessible, it automatically switches to an alternate.
1722 This improves AFS performance, because it means that the outage of an
1723 interface does not interrupt communication between File Server and Cache
1725 <P>The File Server can choose the client interface when it sends two types of
1728 <P><LI>A message to break the callback that the Cache Manager holds on a cached
1730 <P><LI>A <I>ping</I> message to check that the Cache Manager is still
1731 accessible and responding; the File Server sends such a message every few
1734 <P>(The File Server does not choose which client interface to respond to when
1735 filling a Cache Manager's request for AFS data. In that case, it
1736 always responds to the client interface via which the Cache Manager sent the
1738 <P>The Cache Manager compiles the list of eligible interfaces on its client
1739 machine automatically as it initializes, and records them in kernel
1740 memory. When the Cache Manager first establishes a connection with the
1741 File Server, it sends along the list of interface addresses. The File
1742 Server records the addresses, and uses the one at the top of the list when it
1743 needs to break a callback or send a ping to the Cache Manager. If that
1744 interface is inaccessible, the File Server simultaneously sends a message to
1745 all of the other interfaces in the list. Whichever interface replies
1746 first is the one to which the File Server sends future messages.
1747 <P>You can control which addresses the Cache Manager registers with File
1748 Servers by listing them in two files in the <B>/usr/vice/etc</B> directory
1749 on the client machine's local disk: <B>NetInfo</B> and
1750 <B>NetRestrict</B>. If the <B>NetInfo</B> file exists when the
1751 Cache Manager initializes, the Cache Manager uses its contents as the basis
1752 for the list of interfaces. Otherwise, the Cache Manager uses the list
1753 of interfaces configured with the operating system. It then removes
1754 from the list any addresses that appear in the
1755 <B>/usr/vice/etc/NetRestrict</B> file, if it exists. The Cache
1756 Manager records the resulting list in kernel memory.
1757 <P>You can also use the <B>fs setclientaddrs</B> command to change the
1758 list of addresses stored in the Cache Manager's kernel memory, without
1759 rebooting the client machine. The list of addresses you provide on the
1760 command line completely replaces the current list in kernel memory. The
1761 changes you make persist only until the client machine reboots,
1762 however. To preserve the revised list across reboots, list the
1763 interfaces in the <B>NetInfo</B> file (and if appropriate, the
1764 <B>NetRestrict</B> file) in the local <B>/usr/vice/etc</B>
1765 directory. (You can also place the appropriate <B>fs
1766 setclientaddrs</B> command in the machine's AFS initialization script,
1767 but that is less efficient: by the time the Cache Manager reads the
1768 command in the script, it has already compiled a list of interfaces.)
1769 <P>To display the list of addresses that the Cache Manager is currently
1770 registering with File Servers, use the <B>fs getclientaddrs</B>
1772 <P>Keep the following in mind when you change the <B>NetInfo</B> or
1773 <B>NetRestrict</B> file, or issue the <B>fs getclientaddrs</B> or
1774 <B>fs setclientaddrs</B> commands:
1776 <P><LI>When you issue the <B>fs setclientaddrs</B> command, the revised list
1777 of addresses does not propagate automatically to File Servers with which the
1778 Cache Manager has already established a connection. They continue to
1779 use the list that the Cache Manager registered with them when it first
1780 established a connection. To force previously contacted File Servers to
1781 use the revised list, you must either reboot each file server machine, or
1782 reboot the client machine after changing its <B>NetInfo</B> file,
1783 <B>NetRestrict</B> file, or both.
1784 <P><LI>The <B>fs</B> command interpreter verifies that each of the addresses
1785 you specify on the <B>fs setclientaddrs</B> command line is actually
1786 configured with the client machine's operating system. If it is
1787 not, the command fails with an error message that marks the address as a
1788 <TT>Nonexistent interface</TT>.
1789 <P><LI>As previously noted, the File Server does not use the registered list of
1790 addresses when it responds to the Cache Manager's request for data (as
1791 opposed to initiating communication itself). It always attempts to send
1792 its reply to the interface from which the Cache Manager sent the
1793 request. If the reply attempt fails, the File Server selects an
1794 alternate route for resending the reply according to its server machine's
1795 network routing configuration, not the list of addresses registered by the
1797 <P><LI>The Cache Manager does not use the list of interfaces when choosing the
1798 interface via which to establish a connection to a File Server.
1799 <P><LI>The list of addresses that the <B>fs getclientaddrs</B> command
1800 displays is not necessarily the one that a specific File Server is using, if
1801 an administrator has issued the <B>fs setclientaddrs</B> command since the
1802 Cache Manager first contacted that File Server. It determines only
1803 which addresses the Cache Manager registers when connecting to File Servers in
1806 <A NAME="IDX7486"></A>
1807 <A NAME="IDX7487"></A>
1808 <A NAME="IDX7488"></A>
1809 <A NAME="IDX7489"></A>
1810 <P><H3><A NAME="Header_477" HREF="auagd002.htm#ToC_477">To create or edit the client NetInfo file</A></H3>
1812 <P><LI>Become the local superuser <B>root</B> on the machine, if you are not
1813 already, by issuing the <B>su</B> command.
1814 <PRE> % <B>su root</B>
1815 Password: <VAR>root_password</VAR>
1817 <P><LI>Using a text editor, open the <B>/usr/vice/etc/NetInfo</B>
1818 file. Place one IP address in dotted decimal format (for example,
1819 <TT>192.12.107.33</TT>) on each line. On the
1820 first line, put the address that you want each File Server to use
1821 initially. The order of the remaining machines does not matter, because
1822 if an RPC to the first interface fails, the File Server simultaneously sends
1823 RPCs to all of the other interfaces in the list. Whichever interface
1824 replies first is the one to which the File Server then sends pings and RPCs to
1826 <P><LI>If you want the Cache Manager to start using the revised list immediately,
1827 either reboot the machine, or use the <B>fs setclientaddrs</B> command to
1828 create the same list of addresses in kernel memory directly.
1830 <A NAME="IDX7490"></A>
1831 <A NAME="IDX7491"></A>
1832 <A NAME="IDX7492"></A>
1833 <A NAME="IDX7493"></A>
1834 <P><H3><A NAME="Header_478" HREF="auagd002.htm#ToC_478">To create or edit the client NetRestrict file</A></H3>
1836 <P><LI>Become the local superuser <B>root</B> on the machine, if you are not
1837 already, by issuing the <B>su</B> command.
1838 <PRE> % <B>su root</B>
1839 Password: <VAR>root_password</VAR>
1841 <P><LI>Using a text editor, open the <B>/usr/vice/etc/NetRestrict</B>
1842 file. Place one IP address in dotted decimal format on each
1843 line. The order of the addresses is not significant. Use the
1844 value <B>255</B> as a wildcard that represents all possible addresses in
1845 that field. For example, the entry
1846 <TT>192.12.105.255</TT> indicates that the Cache
1847 Manager does not register any of the addresses in the 192.12.105
1849 <P><LI>If you want the Cache Manager to start using the revised list immediately,
1850 either reboot the machine, or use the <B>fs setclientaddrs</B> command to
1851 set a list of addresses that does not included the prohibited ones.
1853 <A NAME="IDX7494"></A>
1854 <A NAME="IDX7495"></A>
1855 <P><H3><A NAME="Header_479" HREF="auagd002.htm#ToC_479">To display the list of addresses from kernel memory</A></H3>
1857 <P><LI>Issue the <B>fs getclientaddrs</B> command.
1858 <PRE> % <B>fs getclientaddrs</B>
1860 <P>where <B>gc</B> is an acceptable alias for <B>getclientaddrs</B>
1861 (<B>getcl</B> is the shortest acceptable abbreviation).
1863 <P>The output lists each IP address on its own line, in dotted decimal
1865 <A NAME="IDX7496"></A>
1866 <A NAME="IDX7497"></A>
1867 <P><H3><A NAME="Header_480" HREF="auagd002.htm#ToC_480">To set the list of addresses in kernel memory</A></H3>
1869 <P><LI>Become the local superuser <B>root</B> on the machine, if you are not
1870 already, by issuing the <B>su</B> command.
1871 <PRE> % <B>su root</B>
1872 Password: <VAR>root_password</VAR>
1874 <P><LI>Issue the <B>fs setclientaddrs</B> command to replace the list of
1875 addresses currently in kernel memory with a new list.
1876 <PRE> # <B>fs setclientaddrs</B> [<B>-address</B> <<VAR>client network interfaces</VAR>><SUP>+</SUP>]
1881 </B><DD>Is an acceptable alias for <B>setclientaddrs</B> (<B>setcl</B> is
1882 the shortest acceptable abbreviation).
1884 </B><DD>Specifies one or more IP addresses in dotted decimal format (hostnames are
1885 not acceptable). Separate each address with one or more spaces.
1888 <HR><H2><A NAME="HDRWQ416" HREF="auagd002.htm#ToC_481">Controlling the Display of Warning and Informational Messages</A></H2>
1889 <A NAME="IDX7498"></A>
1890 <A NAME="IDX7499"></A>
1891 <P>By default, the Cache Manager generates two types of warning and
1892 informational messages:
1894 <P><LI>It sends <I>user messages</I>, which provide user-level status and
1895 warning information, to user screens.
1896 <P><LI>It sends <I>console messages</I>, which provide system-level status
1897 and warning information, to the client machine's designated
1900 <P>You can use the <B>fs messages</B> command to control whether the Cache
1901 Manager displays either type of message, both types, or neither. It is
1902 best not to disable messages completely, because they provide useful
1904 <P>If you want to monitor Cache Manager status and performance more actively,
1905 you can use the <B>afsmonitor</B> program to collect an extensive set of
1906 statistics (it also gathers File Server statistics). If you experience
1907 performance problems, you can use <B>fstrace</B> suite of commands to
1908 gather a low-level trace of Cache Manager operations, which the AFS Support
1909 and Development groups can analyze to help solve your problem. To learn
1910 about both utilities, see <A HREF="auagd013.htm#HDRWQ323">Monitoring and Auditing AFS Performance</A>.
1911 <A NAME="IDX7500"></A>
1912 <A NAME="IDX7501"></A>
1913 <P><H3><A NAME="Header_482" HREF="auagd002.htm#ToC_482">To control the display of warning and status messages</A></H3>
1915 <P><LI>Become the local superuser <B>root</B> on the machine, if you are not
1916 already, by issuing the <B>su</B> command.
1917 <PRE> % <B>su root</B>
1918 Password: <VAR>root_password</VAR>
1920 <P><LI>Issue the <B>fs messages</B> command, using the <B>-show</B>
1921 argument to specify the type of messages to be displayed.
1922 <PRE> # <B>fs messages -show</B> <<B>user</B>|<B>console</B>|<B>all</B>|<B>none</B>>
1927 </B><DD>Is the shortest acceptable abbreviation of <B>messages</B>.
1929 </B><DD>Specifies the types of messages to display. Choose one of the
1933 </B><DD>Sends user messages to user screens.
1935 </B><DD>Sends console messages to the console.
1937 </B><DD>Sends user messages to user screens and console messages to the console
1938 (the default if the <B>-show</B> argument is omitted).
1940 </B><DD>Disables messages completely.
1944 <HR><H2><A NAME="HDRWQ417" HREF="auagd002.htm#ToC_483">Displaying and Setting the System Type Name</A></H2>
1945 <A NAME="IDX7502"></A>
1946 <A NAME="IDX7503"></A>
1947 <P>The Cache Manager stores the system type name of the local client machine
1948 in kernel memory. It reads in the default value from a hardcoded
1949 definition in the AFS client software.
1950 <P>The Cache Manager uses the system name as a substitute for the
1951 <VAR>@sys</VAR> variable in AFS pathnames. The variable is useful when
1952 creating a symbolic link from the local disk to an AFS directory that houses
1953 binaries for the client machine's system type. Because the
1954 <VAR>@sys</VAR> variable automatically steers the Cache Manager to the
1955 appropriate directory, you can create the same symbolic link on client
1956 machines of different system types. (You can even automate the creation
1957 operation by using the package utility described in <A HREF="auagd016.htm#HDRWQ419">Configuring Client Machines with the package Program</A>.) The link also remains valid when you upgrade the
1958 machine to a new system type.
1959 <P>Configuration is simplest if you use the system type names that AFS
1960 assigns. For a list, see the <I>IBM AFS Release Notes</I>.
1961 <P>To display the system name stored in kernel memory, use the <B>sys</B>
1962 or <B>fs sysname</B> command. To change the name, add the latter
1963 command's <B>-newsys</B> argument.
1964 <A NAME="IDX7504"></A>
1965 <A NAME="IDX7505"></A>
1966 <A NAME="IDX7506"></A>
1967 <A NAME="IDX7507"></A>
1968 <P><H3><A NAME="Header_484" HREF="auagd002.htm#ToC_484">To display the system type name</A></H3>
1970 <P><LI>Issue the <B>fs sysname</B> or <B>sys</B> command.
1971 <PRE> % <B>fs sysname</B>
1976 <P>The output of the <B>fs sysname</B> command has the following
1978 <PRE> Current sysname is '<VAR>system_name</VAR>'
1980 <P>The <B>sys</B> command displays the <VAR>system_name</VAR> string with no
1982 <P><H3><A NAME="Header_485" HREF="auagd002.htm#ToC_485">To change the system type name</A></H3>
1984 <P><LI>Become the local superuser <B>root</B> on the machine, if you are not
1985 already, by issuing the <B>su</B> command.
1986 <PRE> % <B>su root</B>
1987 Password: <VAR>root_password</VAR>
1989 <P><LI>Issue the <B>fs sysname</B> command, using the <B>-newsys</B>
1990 argument to specify the new name.
1991 <PRE> # <B>fs sysname</B> <<VAR>new sysname</VAR>>
1996 </B><DD>Is the shortest acceptable abbreviation of <B>sysname</B>.
1997 <P><DT><B><VAR>new sysname</VAR>
1998 </B><DD>Specifies the new system type name.
2001 <HR><H2><A NAME="HDRWQ418" HREF="auagd002.htm#ToC_486">Enabling Asynchronous Writes</A></H2>
2002 <A NAME="IDX7508"></A>
2003 <A NAME="IDX7509"></A>
2004 <A NAME="IDX7510"></A>
2005 <P>By default, the Cache Manager writes all data to the File Server
2006 immediately and synchronously when an application program closes a
2007 file. That is, the <B>close</B> system call does not return until
2008 the Cache Manager has actually written all of the cached data from the file
2009 back to the File Server. You can enable the Cache Manager to write
2010 files asynchronously by specifying the number of kilobytes of a file that can
2011 remain to be written to the File Server when the Cache Manager returns control
2013 <P>Enabling asynchronous writes can be helpful to users who commonly work with
2014 very large files, because it usually means that the application appears to
2015 perform faster. However, it introduces some complications. It is
2016 best not to enable asynchronous writes unless the machine's users are
2017 sophisticated enough to understand the potential problems and how to avoid
2018 them. The complications include the following:
2020 <P><LI>In most cases, the Cache Manager returns control to applications earlier
2021 than it does by default, but it is not guaranteed to do so. Users
2022 cannot always expect faster performance.
2023 <P><LI>If an asynchronous write fails, there is no way to notify the application,
2024 because the <B>close</B> system call has already returned with a code
2026 <P><LI>Asynchronous writing increases the possibility that the user fails to
2027 notice when a write operation makes a volume exceed its quota. As
2028 always, the portion of the file that exceeds the quota is lost, as indicated
2029 by a message like the following:
2030 <PRE> No space left on device
2032 <P>To avoid losing data because of insufficient quota, before closing a file
2033 users must verify that the volume housing the file has enough free space to
2036 <P>When you enable asynchronous writes by issuing the <B>fs
2037 storebehind</B> command, you set the number of kilobytes of a file that can
2038 still remain to be written to the File Server when the Cache Manager returns
2039 control to the application program. You can apply the setting either to
2040 all files manipulated by applications running on the machine, or only to
2043 <P><LI>The setting that applies to all files is called the <I>default store
2044 asynchrony</I> for the machine, and persists until the machine
2045 reboots. If, for example, you set the default store asynchrony to 10
2046 KB, it means that when an application closes a file, the Cache Manager can
2047 return control to the application as soon as no more than 10 KB of a file that
2048 the application has closed remain to be written to the File Server.
2049 <P><LI>The setting for an individual file overrides the default store asynchrony
2050 and persists as long as there is an entry for the file in the internal table
2051 that the Cache Manager uses to track information about files. In
2052 general, such an entry persists at least until an application closes the file
2053 or exits completely, but the Cache Manager is free to recycle the entry if the
2054 file is inactive and it needs to free up slots in the table. To be sure
2055 the entry exists in the table, issue the <B>fs storebehind</B> command
2056 shortly before closing the file.
2058 <A NAME="IDX7511"></A>
2059 <A NAME="IDX7512"></A>
2060 <P><H3><A NAME="Header_487" HREF="auagd002.htm#ToC_487">To set the default store asynchrony</A></H3>
2062 <P><LI>Become the local superuser <B>root</B> on the machine, if you are not
2063 already, by issuing the <B>su</B> command.
2064 <PRE> % <B>su root</B>
2065 Password: <VAR>root_password</VAR>
2067 <P><LI>Issue the <B>fs storebehind</B> command with the <B>-allfiles</B>
2069 <PRE> # <B>fs storebehind -allfiles</B> <<VAR>new default (KB)</VAR>> [<B>-verbose</B>]
2074 </B><DD>Is the shortest acceptable abbreviation of <B>storebehind</B>.
2076 </B><DD>Sets the number of kilobytes of data that can remain to be written to the
2077 File Server when the Cache Manager returns control to the application that
2080 </B><DD>Produces a message that confirms the new setting.
2083 <A NAME="IDX7513"></A>
2084 <A NAME="IDX7514"></A>
2085 <P><H3><A NAME="Header_488" HREF="auagd002.htm#ToC_488">To set the store asynchrony for one or more files</A></H3>
2087 <P><LI>Verify that you have the <B>w</B> (<B>write</B>) permission on the
2088 access control list (ACL) of each file for which you are setting the store
2089 asynchrony, by issuing the <B>fs listacl</B> command, which is described
2090 fully in <A HREF="auagd020.htm#HDRWQ572">Displaying ACLs</A>.
2091 <PRE> % <B>fs listacl</B> <VAR>dir/file path</VAR>
2093 <P>Alternatively, become the local superuser <B>root</B> on the client
2094 machine, if you are not already, by issuing the <B>su</B> command.
2095 <PRE> % <B>su root</B>
2096 Password: <VAR>root_password</VAR>
2098 <P><LI>Issue the <B>fs storebehind</B> command with the <B>-kbytes</B>
2099 and <B>-files</B> arguments.
2100 <PRE> # <B>fs storebehind -kbytes</B> <<VAR>asynchrony for specified names</VAR>> \
2101 <B>-files</B> <<VAR>specific pathnames</VAR>><SUP>+</SUP> \
2107 </B><DD>Is the shortest acceptable abbreviation of <B>storebehind</B>.
2109 </B><DD>Sets the number of kilobytes of data that can remain to be written to the
2110 File Server when the Cache Manager returns control to the application that
2111 closed a file named by the <B>-files</B> argument.
2113 </B><DD>Specifies each file for which to set a store asynchrony that overrides the
2114 default. Partial pathnames are interpreted relative to the current
2117 </B><DD>Produces a message that confirms that new setting.
2120 <A NAME="IDX7515"></A>
2121 <A NAME="IDX7516"></A>
2122 <P><H3><A NAME="Header_489" HREF="auagd002.htm#ToC_489">To display the default store asynchrony</A></H3>
2124 <P><LI>Issue the <B>fs storebehind</B> command with no arguments, or with the
2125 <B>-verbose</B> flag only.
2126 <PRE> % <B>fs storebehind </B> [<B>-verbose</B>]
2131 </B><DD>Is the shortest acceptable abbreviation of <B>storebehind</B>.
2133 </B><DD>Produces output that reports the default store asynchrony.
2136 <A NAME="IDX7517"></A>
2137 <A NAME="IDX7518"></A>
2138 <P><H3><A NAME="Header_490" HREF="auagd002.htm#ToC_490">To display the store asynchrony for one or more files</A></H3>
2140 <P><LI>Issue the <B>fs storebehind</B> command with the <B>-files</B>
2142 <PRE> % <B>fs storebehind</B> <B>-files</B> <<VAR>specific pathnames</VAR>><SUP>+</SUP>
2147 </B><DD>Is the shortest acceptable abbreviation of <B>storebehind</B>.
2149 </B><DD>Specifies each file for which to display the store asynchrony.
2150 Partial pathnames are interpreted relative to the current working
2154 <P>The output lists each file separately. If a value has previously
2155 been set for the specified files, the output reports the following:
2156 <PRE> Will store up to <VAR>y</VAR> kbytes of <VAR>file</VAR> asynchronously.
2157 Default store asynchrony is <VAR>x</VAR> kbytes.
2159 <P>If the default store asynchrony applies to a file (because you have not set
2160 a <B>-kbytes</B> value for it), the output reports the following:
2161 <PRE> Will store <VAR>file</VAR> according to default.
2162 Default store asynchrony is <VAR>x</VAR> kbytes.
2164 <HR><P ALIGN="center"> <A HREF="../index.htm"><IMG SRC="../books.gif" BORDER="0" ALT="[Return to Library]"></A> <A HREF="auagd002.htm#ToC"><IMG SRC="../toc.gif" BORDER="0" ALT="[Contents]"></A> <A HREF="auagd014.htm"><IMG SRC="../prev.gif" BORDER="0" ALT="[Previous Topic]"></A> <A HREF="#Top_Of_Page"><IMG SRC="../top.gif" BORDER="0" ALT="[Top of Topic]"></A> <A HREF="auagd016.htm"><IMG SRC="../next.gif" BORDER="0" ALT="[Next Topic]"></A> <A HREF="auagd026.htm#HDRINDEX"><IMG SRC="../index.gif" BORDER="0" ALT="[Index]"></A> <P>
2165 <!-- Begin Footer Records ========================================== -->
2167 <br>© <A HREF="http://www.ibm.com/">IBM Corporation 2000.</A> All Rights Reserved
2169 <!-- End Footer Records ============================================ -->
2170 <A NAME="Bot_Of_Page"></A>
git://git.openafs.org / openafs.git / blob