1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 3//EN">
3 <TITLE>Administration Guide</TITLE>
4 <!-- Begin Header Records ========================================== -->
5 <!-- /tmp/idwt3191/auagd000.scr converted by idb2h R4.2 (359) ID -->
6 <!-- Workbench Version (AIX) on 5 Nov 1999 at 14:06:34 -->
7 <META HTTP-EQUIV="updated" CONTENT="Fri, 05 Nov 1999 14:06:34">
8 <META HTTP-EQUIV="review" CONTENT="Sun, 05 Nov 2000 14:06:34">
9 <META HTTP-EQUIV="expires" CONTENT="Mon, 05 Nov 2001 14:06:34">
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="HDRWQ512" 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="#HDRWQ536">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="#HDRWQ538">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="#HDRWQ540">Determining the Cache Type, Size, and Location</A> and <A HREF="#HDRWQ548">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>AFS Quick Beginnings</I>.
40 <HR><H2><A NAME="HDRWQ513" 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="HDRWQ536" 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="#HDRWQ540">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="#HDRWQ540">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="#HDRWQ540">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="#HDRWQ548">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="#HDRWQ552">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="#HDRWQ555">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="#HDRWQ557">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="#HDRWQ558">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="#HDRWQ560">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="#HDRWQ561">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="#HDRWQ562">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="#HDRWQ563">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="#HDRWQ564">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#HDRWQ565">Configuring Client Machines with the package Program</A>.
221 <HR><H2><A NAME="HDRWQ537" 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="HDRWQ538" 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>AFS Quick Beginnings</I> explains how to create this file as you
267 install a client machine. To change the cache size on a machine that
268 uses a memory cache, edit the file and reboot the machine. On a machine
269 that uses a disk cache, you can change the cache size without rebooting by
270 issuing the <B>fs setcachesize</B> command. For instructions, see <A HREF="#HDRWQ540">Determining the Cache Type, Size, and Location</A>.
271 <A NAME="IDX7325"></A>
272 <A NAME="IDX7326"></A>
274 </B><DD>This ASCII file names the database server machines in the local cell and
275 in any foreign cell to which you want to enable access from this
276 machine. (Database server machines are the machines in a cell that run
277 the Authentication, Backup, Protection, and VL Server processes; see <A HREF="auagd008.htm#HDRWQ126">Database Server Machines</A>.)
278 <P>The Cache Manager must be able to reach a cell's database server
279 machines to fetch files from its filespace. Incorrect or missing
280 information in the <B>CellServDB</B> file can slow or completely block
281 access. It is important to update the file whenever a cell's
282 database server machines change.
283 <P>As the <B>afsd</B> program initializes the Cache Manager, it loads the
284 contents of the file into kernel memory. The Cache Manager does not
285 read the file between reboots, so to incorporate changes to the file into
286 kernel memory, you must reboot the machine. Alternatively, you can
287 issue the <B>fs newcell</B> command to insert the changes directly into
288 kernel memory without changing the file. It can also be convenient to
289 upgrade the file from a central source. For instructions, see <A HREF="#HDRWQ552">Maintaining Knowledge of Database Server Machines</A>.
290 <P>(The <B>CellServDB</B> file on client machines is not the same as the
291 one kept in the <B>/usr/afs/etc</B> directory on server machines, which
292 lists only the local cell's database server machines. For
293 instructions on maintaining the server <B>CellServDB</B> file, see <A HREF="auagd008.htm#HDRWQ152">Maintaining the Server CellServDB File</A>).
294 <A NAME="IDX7327"></A>
295 <A NAME="IDX7328"></A>
297 </B><DD>This optional ASCII file lists one or more of the network interface
298 addresses on the client machine. If it exists when the Cache Manager
299 initializes, the Cache Manager uses it as the basis for the list of interfaces
300 that it registers with File Servers. See <A HREF="#HDRWQ561">Managing Multihomed Client Machines</A>.
301 <A NAME="IDX7329"></A>
302 <A NAME="IDX7330"></A>
303 <P><DT><B>NetRestrict
304 </B><DD>This optional ASCII file lists one or more network interface
305 addresses. If it exists when the Cache Manager initializes, the Cache
306 Manager removes the specified addresses from the list of interfaces that it
307 registers with File Servers. See <A HREF="#HDRWQ561">Managing Multihomed Client Machines</A>.
308 <A NAME="IDX7331"></A>
309 <A NAME="IDX7332"></A>
311 </B><DD>This ASCII file contains a single line that specifies the complete
312 domain-style name of the cell to which the machine belongs. Examples
313 are <TT>abc.com</TT> and <TT>stateu.edu</TT>. This
314 value defines the default cell in which the machine's users become
315 authenticated, and in which the command interpreters (for example, the
316 <B>bos</B> command) contact server processes.
317 <P>The <I>AFS Quick Beginnings</I> explains how to create this file as you
318 install the AFS client functionality. To learn about changing a client
319 machine's cell membership, see <A HREF="#HDRWQ557">Setting a Client Machine's Cell Membership</A>.
321 <P>In addition to these files, the <B>/usr/vice/etc</B> directory also
322 sometimes contains the following types of files and subdirectories:
324 <A NAME="IDX7333"></A>
325 <A NAME="IDX7334"></A>
326 <A NAME="IDX7335"></A>
327 <A NAME="IDX7336"></A>
328 <P><LI>The AFS initialization script, called <B>afs.rc</B> on many
329 system types. In the conventional configuration specified by the
330 <I>AFS Quick Beginnings</I>, it is a symbolic link to the actual script
331 kept in the same directory as other initialization files used by the operating
333 <A NAME="IDX7337"></A>
334 <A NAME="IDX7338"></A>
335 <P><LI>A subdirectory that houses AFS kernel library files used by a dynamic
336 kernel loading program.
337 <A NAME="IDX7339"></A>
338 <A NAME="IDX7340"></A>
339 <P><LI>A subdirectory called <B>C</B>, which houses the Cache Manager catalog
340 file called <B>afszcm.cat</B>. The fstrace program uses the
341 catalog file to translate operation codes into character strings, which makes
342 the message in the trace log more readable. See <A HREF="auagd013.htm#HDRWQ464">About the fstrace Command Suite</A>.
344 <P><H3><A NAME="HDRWQ539" HREF="auagd002.htm#ToC_436">Cache-Related Files</A></H3>
345 <A NAME="IDX7341"></A>
346 <A NAME="IDX7342"></A>
347 <A NAME="IDX7343"></A>
348 <A NAME="IDX7344"></A>
349 <A NAME="IDX7345"></A>
350 <P>A client machine that uses a disk cache must have a local disk directory
351 devoted to the cache. The conventional mount point is
352 <B>/usr/vice/cache</B>, but you can use another partition that has more
354 <P>Do not delete or directly modify any of the files in the cache
355 directory. Doing so can cause a kernel panic, from which the only way
356 to recover is to reboot the machine. By default, only the local
357 superuser <B>root</B> can read the files directly, by virtue of owning
359 <P>A client machine that uses a memory cache keeps all of the information
360 stored in these files in machine memory instead.
362 <A NAME="IDX7346"></A>
363 <A NAME="IDX7347"></A>
365 </B><DD>A binary-format file in which the Cache Manager tracks the contents of
366 cache chunks (the <B>V</B> files in the directory, described just
367 following), including the file ID number (fID) and the data version
369 <A NAME="IDX7348"></A>
370 <A NAME="IDX7349"></A>
371 <P><DT><B>VolumeItems
372 </B><DD>A binary-format file in which the Cache Manager records the mapping
373 between mount points and the volumes from which it has fetched data.
374 The Cache Manager uses the information when responding to the <B>pwd</B>
375 command, among others.
376 <A NAME="IDX7350"></A>
377 <A NAME="IDX7351"></A>
378 <A NAME="IDX7352"></A>
379 <P><DT><B>V<VAR>n</VAR>
380 </B><DD>A cache chunk file, which expands to a maximum size (by default, 64 KB) to
381 house data fetched from AFS files. The number of <B>V</B><VAR>n</VAR>
382 files in the cache depends on the cache size among other factors. The
383 <VAR>n</VAR> is the index assigned to each file; they are numbered
384 sequentially, but the Cache Manager does not necessarily use them in order or
385 contiguously. If an AFS file is larger than the maximum size for
386 <B>V</B><VAR>n</VAR> files, the Cache Manager divides it across multiple
387 <B>V</B><VAR>n</VAR> files.
389 <HR><H2><A NAME="HDRWQ540" HREF="auagd002.htm#ToC_437">Determining the Cache Type, Size, and Location</A></H2>
390 <P>This section explains how to configure a memory or disk
391 cache, how to display and set the size of either type of cache, and how to set
392 the location of the cache directory for a disk cache.
393 <A NAME="IDX7353"></A>
394 <A NAME="IDX7354"></A>
395 <P>The Cache Manager uses a disk cache by default, and it is the preferred
396 type of caching. To configure a memory cache, include the
397 <B>-memcache</B> flag on the <B>afsd</B> command, which is normally
398 invoked in the machine's AFS initialization file. If configured to
399 use a memory cache, the Cache Manager does no disk caching, even if the
401 <P><H3><A NAME="Header_438" HREF="auagd002.htm#ToC_438">Choosing the Cache Size</A></H3>
402 <A NAME="IDX7355"></A>
403 <P>Cache size influences the performance of a client machine more directly
404 than perhaps any other cache parameter. The larger the cache, the
405 faster the Cache Manager is likely to deliver files to users. A small
406 cache can impair performance because it increases the frequency at which the
407 Cache Manager must discard cached data to make room for newly requested
408 data. When an application asks for data that has been discarded, the
409 Cache Manager must request it from the File Server, and fetching data across
410 the network is almost always slower than fetching it from the local
411 disk. The Cache Manager never discards data from a file that has been
412 modified locally but not yet stored back to the File Server. If the
413 cache is very small, the Cache Manager possible cannot find any data to
414 discard. For more information about the algorithm it uses when
415 discarding cached data, see <A HREF="#HDRWQ547">How the Cache Manager Chooses Data to Discard</A>).
416 <P>The amount of disk or memory you devote to caching depends on several
417 factors. The amount of space available in memory or on the partition
418 housing the disk cache directory imposes an absolute limit. In
419 addition, you cannot allocate more than 95% of the space available on the
420 cache directory's partition to a disk cache. The <B>afsd</B>
421 program exits without starting the Cache Manager and prints an appropriate
422 message to the standard output stream if you violate this restriction.
423 For a memory cache, you must leave enough memory for other processes and
424 applications to run. If you try to allocate more memory than is
425 actually available, the <B>afsd</B> program exits without initializing the
426 Cache Manager and produces the following message on the standard output
428 <PRE> afsd: memCache allocation failure at <VAR>number</VAR> KB
430 <P>where <VAR>number</VAR> is how many kilobytes were allocated just before the
432 <P>Within these hard limits, the factors that determine appropriate cache size
433 include the number of users working on the machine, the size of the files with
434 which they usually work, and (for a memory cache) the number of processes that
435 usually run on the machine. The higher the demand from these factors,
436 the larger the cache needs to be to maintain good performance.
437 <P>Disk caches smaller than 10 MB do not generally perform well.
438 Machines serving multiple users usually perform better with a cache of at
439 least 60 to 70 MB. The point at which enlarging the cache further does
440 not really improve performance depends on the factors mentioned previously,
441 and is difficult to predict.
442 <P>Memory caches smaller than 1 MB are nonfunctional, and the performance of
443 caches smaller than 5 MB is usually unsatisfactory. Suitable upper
444 limits are similar to those for disk caches but are probably determined more
445 by the demands on memory from other sources on the machine (number of users
446 and processes). Machines running only a few processes possibly can use
447 a smaller memory cache.
448 <P>AFS imposes an absolute limit on cache size in some versions. See
449 the <I>AFS Release Notes</I> for the version you are using.
451 <P><H3><A NAME="HDRWQ541" HREF="auagd002.htm#ToC_439">Displaying and Setting the Cache Size and Location</A></H3>
452 <A NAME="IDX7356"></A>
453 <A NAME="IDX7357"></A>
454 <A NAME="IDX7358"></A>
455 <A NAME="IDX7359"></A>
456 <A NAME="IDX7360"></A>
457 <A NAME="IDX7361"></A>
458 <A NAME="IDX7362"></A>
459 <A NAME="IDX7363"></A>
460 <A NAME="IDX7364"></A>
461 <A NAME="IDX7365"></A>
462 <A NAME="IDX7366"></A>
463 <A NAME="IDX7367"></A>
464 <A NAME="IDX7368"></A>
465 <A NAME="IDX7369"></A>
466 <A NAME="IDX7370"></A>
467 <A NAME="IDX7371"></A>
468 <A NAME="IDX7372"></A>
469 <A NAME="IDX7373"></A>
470 <A NAME="IDX7374"></A>
471 <A NAME="IDX7375"></A>
472 <A NAME="IDX7376"></A>
473 <P>The Cache Manager determines how big to make the cache by reading the
474 <B>/usr/vice/etc/cacheinfo</B> file as it initializes. As directed
475 in the <I>AFS Quick Beginnings</I>, you must create the file before
476 running the <B>afsd</B> program. The file also defines the
477 directory on which to mount AFS (by convention, <B>/afs</B>), and the
478 local disk directory to use for a cache directory.
479 <P>To change any of the values in the file, log in as the local superuser
480 <B>root</B>. You must reboot the machine to have the new value take
481 effect. For instructions, see <A HREF="#HDRWQ544">To edit the cacheinfo file</A>.
482 <P>To change the cache size at reboot without editing the <B>cacheinfo</B>
483 file, include the <B>-blocks</B> argument to the <B>afsd</B>
484 command; see the command's reference page in the <I>AFS
485 Administration Reference</I>.
486 <P>For a disk cache, you can also use the <B>fs setcachesize</B> command
487 to reset the cache size without rebooting. The value you set persists
488 until the next reboot, at which time the cache size returns to the value
489 specified in the <B>cacheinfo</B> file or by the <B>-blocks</B>
490 argument to the <B>afsd</B> command. For instructions, see <A HREF="#HDRWQ545">To change the disk cache size without rebooting</A>.
491 <P>To display the current cache size and the amount of space the Cache Manager
492 is using at the moment, use the <B>fs getcacheparms</B> command as
493 detailed in <A HREF="#HDRWQ543">To display the current cache size</A>.
494 <P><H3><A NAME="HDRWQ542" HREF="auagd002.htm#ToC_440">To display the cache size set at reboot</A></H3>
496 <P><LI>Use a text editor or the <B>cat</B> command to display the contents of
497 the <B>/usr/vice/etc/cacheinfo</B> file.
498 <PRE> % <B>cat /usr/vice/etc/cacheinfo</B>
501 <A NAME="IDX7377"></A>
502 <A NAME="IDX7378"></A>
503 <A NAME="IDX7379"></A>
504 <A NAME="IDX7380"></A>
505 <A NAME="IDX7381"></A>
506 <A NAME="IDX7382"></A>
507 <P><H3><A NAME="HDRWQ543" HREF="auagd002.htm#ToC_441">To display the current cache size</A></H3>
509 <P><LI>Issue the <B>fs getcacheparms</B> command on the client
511 <PRE> % <B>fs getcacheparms</B>
513 <P>where <B>getca</B> is the shortest acceptable abbreviation of
514 <B>getcacheparms</B>.
515 <P>The output shows the number of kilobyte blocks the Cache Manager is using
516 as a cache at the moment the command is issued, and the current size of the
517 cache. For example:
518 <PRE> AFS using 13709 of the cache's available 15000 1K byte blocks.
521 <A NAME="IDX7383"></A>
522 <A NAME="IDX7384"></A>
523 <A NAME="IDX7385"></A>
524 <A NAME="IDX7386"></A>
525 <A NAME="IDX7387"></A>
526 <P><H3><A NAME="HDRWQ544" HREF="auagd002.htm#ToC_442">To edit the cacheinfo file</A></H3>
528 <P><LI>Become the local superuser <B>root</B> on the machine, if you are not
529 already, by issuing the <B>su</B> command.
530 <PRE> % <B>su root</B>
531 Password: <VAR>root_password</VAR>
533 <P><LI>Use a text editor to edit the <B>/usr/vice/etc/cacheinfo</B> file,
534 which has three fields, separated by colons:
536 <P><LI>The first field names the local directory on which to mount the AFS
537 filespace. The conventional location is <B>/afs</B>.
538 <P><LI>The second field defines the local disk directory to use for the disk
539 cache. The conventional location is the <B>/usr/vice/cache</B>
540 directory, but you can specify an alternate directory if another partition has
541 more space available. There must always be a value in this field, but
542 the Cache Manager ignores it if the machine uses a memory cache.
543 <P><LI>The third field defines cache size as a number of kilobyte (1024-byte)
546 <P>The following example mounts the AFS filespace at the <B>/afs</B>
547 directory, names <B>/usr/vice/cache</B> as the cache directory, and sets
548 cache size to 50,000 KB:
549 <PRE> <B>/afs:/usr/vice/cache:50000</B>
552 <A NAME="IDX7388"></A>
553 <A NAME="IDX7389"></A>
554 <A NAME="IDX7390"></A>
555 <A NAME="IDX7391"></A>
556 <A NAME="IDX7392"></A>
557 <A NAME="IDX7393"></A>
558 <P><H3><A NAME="HDRWQ545" HREF="auagd002.htm#ToC_443">To change the disk cache size without rebooting</A></H3>
560 <P><LI>Become the local superuser <B>root</B> on the machine, if you are not
561 already, by issuing the <B>su</B> command.
562 <PRE> % <B>su root</B>
563 Password: <VAR>root_password</VAR>
565 <P><LI><A NAME="LIWQ546"></A>Issue the <B>fs setcachesize</B> command to set a new disk
567 <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.
569 <PRE> # <B>fs setcachesize</B> <<VAR>size in 1K byte blocks (0 => reset)</VAR>>
573 <P><DT><B><B>setca</B>
574 </B><DD>Is the shortest acceptable abbreviation of <B>setcachesize</B>.
575 <P><DT><B><VAR>size in 1K byte blocks (0 => reset)</VAR>
576 </B><DD>Sets the number of kilobyte blocks to be used for the cache.
577 Specify a positive integer (<B>1024</B> equals 1 MB), or <B>0</B>
578 (zero) to reset the cache size to the value specified in the
579 <B>cacheinfo</B> file.
582 <A NAME="IDX7394"></A>
583 <A NAME="IDX7395"></A>
584 <A NAME="IDX7396"></A>
585 <A NAME="IDX7397"></A>
586 <A NAME="IDX7398"></A>
587 <A NAME="IDX7399"></A>
588 <P><H3><A NAME="Header_444" HREF="auagd002.htm#ToC_444">To reset the disk cache size to the default without rebooting</A></H3>
590 <P><LI>Become the local superuser <B>root</B> on the machine, if you are not
591 already, by issuing the <B>su</B> command.
592 <PRE> % <B>su root</B>
593 Password: <VAR>root_password</VAR>
595 <P><LI>Issue the <B>fs setcachesize</B> command to reset the size of the
596 local disk cache (the command does not work for a memory cache). Choose
597 one of the two following options:
599 <P><LI>To reset the cache size to the value specified in the local
600 <B>cacheinfo</B> file, specify the value <B>0</B> (zero)
601 <PRE> # <B>fs setcachesize 0</B>
603 <P><LI>To reset the cache size to the value set at the last reboot of the
604 machine, include the <B>-reset</B> flag. Unless the
605 <B>-blocks</B> argument was used on the <B>afsd</B> command, this is
606 also the value in the <B>cacheinfo</B> file.
607 <PRE> # <B>fs setcachesize -reset</B>
612 <P><DT><B><B>setca</B>
613 </B><DD>Is the shortest acceptable abbreviation of <B>setcachesize</B>.
615 </B><DD>Resets the disk cache size to the value in the third field of the
616 <B>/usr/vice/etc/cacheinfo</B> file.
618 </B><DD>Resets the cache size to the value set at the last reboot.
621 <P><H3><A NAME="HDRWQ547" HREF="auagd002.htm#ToC_445">How the Cache Manager Chooses Data to Discard</A></H3>
622 <P>When the cache is full and application programs request more
623 data from AFS, the Cache Manager must flush out cache chunks to make room for
624 the data. The Cache Manager considers two factors:
626 <P><LI>How recently an application last accessed the data.
627 <P><LI>Whether the chunk is <I>dirty</I>. A dirty chunk contains
628 changes to a file that have not yet been saved back to the permanent copy
629 stored on a file server machine.
631 <P>The Cache Manager first checks the least-recently used chunk. If it
632 is not dirty, the Cache Manager discards the data in that chunk. If the
633 chunk is dirty, the Cache Manager moves on to check the next least recently
634 used chunk. It continues in this manner until it has created a
635 sufficient number of empty chunks.
636 <P>Chunks that contain data fetched from a read-only volume are by definition
637 never dirty, so the Cache Manager can always discard them. Normally,
638 the Cache Manager can also find chunks of data fetched from read/write volumes
639 that are not dirty, but a small cache makes it difficult to find enough
640 eligible data. If the Cache Manager cannot find any data to discard, it
641 must return I/O errors to application programs that request more data from
642 AFS. Application programs usually have a means for notifying the user
643 of such errors, but not for revealing their cause.
644 <HR><H2><A NAME="HDRWQ548" HREF="auagd002.htm#ToC_446">Setting Other Cache Parameters with the afsd program</A></H2>
645 <P>There are only three cache configuration parameters you must
646 set: the mount directory for AFS, the location of the disk cache
647 directory, and the cache size. They correspond to the three fields in
648 the <B>/usr/vice/etc/cacheinfo</B> file, as discussed in <A HREF="#HDRWQ540">Determining the Cache Type, Size, and Location</A>. However, if you want to experiment with fine-tuning
649 cache performance, you can use the arguments on the <B>afsd</B> command to
650 control several other parameters. This section discusses a few of these
651 parameters that have the most direct effect on cache performance. To
652 learn more about the <B>afsd</B> command's arguments, see its
653 reference page in the <I>AFS Administration Reference</I>.
654 <P>In addition, the AFS initialization script included in the AFS distribution
655 for each system type includes several variables that set several
656 <B>afsd</B> arguments in a way that is suitable for client machines of
657 different sizes and usage patterns. For instructions on using the
658 script most effectively, see the section on configuring the Cache Manager in
659 the <I>AFS Quick Beginnings</I>.
660 <P><H3><A NAME="HDRWQ549" HREF="auagd002.htm#ToC_447">Setting Cache Configuration Parameters</A></H3>
661 <P>The cache configuration parameters with the most direct
662 effect on cache performance include the following:
664 <P><LI><I>total cache size.</I> This is the amount of disk space or
665 machine memory available for caching, as discussed in detail in <A HREF="#HDRWQ540">Determining the Cache Type, Size, and Location</A>.
666 <P><LI><I>number of cache chunks.</I> For a disk cache, each chunk is
667 a <B>V</B><VAR>n</VAR> file in the local cache directory (see <A HREF="#HDRWQ539">Cache-Related Files</A>). For a memory cache, each chunk is a set of
668 contiguous blocks allocated in machine memory.
669 <P>This parameter does not have as much of an effect on cache performance as
670 total size. However, adjusting it can influence how often the Cache
671 Manager must discard cached data to make room for new data. Suppose,
672 for example, that you set the disk cache size to 50 MB and the number of
673 chunks (<B>V</B><VAR>n</VAR> files) to 1,000. If each of the ten
674 users on the machine caches 100 AFS files that average 20 KB in size, then all
675 1,000 chunks are full (a chunk can contain data from only one AFS file) but
676 the cache holds only about 20 MB of data. When a user requests more
677 data from the File Server, the Cache Manager must discard cached data to
678 reclaim some chunks, even though the cache is filled to less than 50% of its
679 capacity. In such a situation, increasing the number of chunks enables
680 the Cache Manager to discard data less often.
681 <P><LI><I>chunk size.</I> This parameter determines the maximum amount
682 of data that can fit in a chunk. If a cached element is smaller than
683 the chunk size, the remaining space in the chunk is not used (a chunk can hold
684 no more than one element). If an element cannot fit in a single chunk,
685 it is split across as many chunks as needed. This parameter also
686 determines how much data the Cache Manager requests at a time from the File
687 Server (how much data per <I>fetch RPC</I>, because AFS uses partial file
689 <P>The main reason to change chunk size is because of its relation to the
690 amount of data fetched per RPC. If your network links are very fast, it
691 can improve performance to increase chunk size; if the network is
692 especially slow, it can make sense to decrease chunk size.
693 <P><LI><I>number of dcache entries in memory.</I> The Cache Manager
694 maintains one dcache entry for each cache chunk, recording a small amount of
695 information, such as the file ID (fID) and version number of the AFS file
696 corresponding to the chunk.
697 <P>For a disk cache, dcache entries reside in the
698 <B>/usr/vice/cache/CacheItems</B> file; a small number are duplicated
699 in machine memory to speed access.
700 <P>For a memory cache, the number of dcache entries equals the number of cache
701 chunks. For a discussion of the implications of this correspondence,
702 see <A HREF="#HDRWQ551">Controlling Memory Cache Configuration</A>.
704 <P>For a description of how the Cache Manager determines defaults for number
705 of chunks, chunk size, and number of dcache entries in a disk cache, see <A HREF="#HDRWQ550">Configuring a Disk Cache</A>; for a memory cache, see <A HREF="#HDRWQ551">Controlling Memory Cache Configuration</A>. The instructions also explain
706 how to use the <B>afsd</B> command's arguments to override the
708 <P><H3><A NAME="HDRWQ550" HREF="auagd002.htm#ToC_448">Configuring a Disk Cache</A></H3>
709 <P>The default number of cache chunks (<B>V</B><VAR>n</VAR>
710 files) in a disk cache is calculated by the <B>afsd</B> command to be the
711 greatest of the following:
714 <P><LI>1.5 times the result of dividing cache size by chunk size
715 (<VAR>cachesize</VAR>/<VAR>chunksize</VAR> * 1.5)
716 <P><LI>The result of dividing cachesize by 10 MB (<VAR>cachesize</VAR>/10240)
718 <P>You can override this value by specifying a positive integer with the
719 <B>-files</B> argument. Consider increasing this value if more than
720 75% of the <B>V</B><VAR>n</VAR> files are already used soon after the Cache
721 Manager finishes initializing. Consider decreasing it if only a small
722 percentage of the chunks are used at that point. In any case, never
723 specify a value less than 100, because a smaller value can cause performance
725 <P>The following example sets the number of <B>V</B><VAR>n</VAR> files to
727 <PRE> <B>/usr/vice/etc/afsd -files 2000</B>
729 <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
730 AFS initialization file, rather than entering it in a command shell.
731 Furthermore, the values specified in this section are examples only, and are
732 not necessarily suitable for a specific machine.
734 <P>The default chunk size for a disk cache is 64 KB. In general, the
735 only reason to change it is to adjust to exceptionally slow or fast
736 networks; see <A HREF="#HDRWQ549">Setting Cache Configuration Parameters</A>. You can use the <B>-chunksize</B>
737 argument to override the default. Chunk size must be a power of 2, so
738 provide an integer between 0 (zero) and 30 to be used as an exponent of
739 2. For example, a value of 10 sets chunk size to 1 KB (2<SUP>10</SUP> =
740 1024); a value of 16 equals the default for disk caches (2<SUP>16</SUP> =
741 64 KB). Specifying a value of 0 (zero) or greater than 30 returns chunk
742 size to the default. Values less than 10 (1 KB) are not
743 recommended. The following example sets chunk size to 16 KB
744 (2<SUP>14</SUP>):
745 <PRE> <B>/usr/vice/etc/afsd -chunksize 14</B>
747 <P>For a disk cache, the default number of dcache entries duplicated in memory
748 is one-half the number of chunks specified with the <B>-files</B>
749 argument, to a maximum of 2,000 entries. You can use the
750 <B>-dcache</B> argument to change the default, even exceeding 2,000 if you
751 wish. Duplicating more than half the dcache entries in memory is not
752 usually necessary, but sometimes improves performance slightly, because access
753 to memory is faster than access to disk. The following example sets the
755 <PRE> <B>/usr/vice/etc/afsd -dcache 750</B>
757 <P>When configuring a disk cache, you can combine the <B>afsd</B>
758 command's arguments in any way. The main reason for this
759 flexibility is that the setting you specify for disk cache size (in the
760 <B>cacheinfo</B> file or with the <B>-blocks</B> argument) is an
761 absolute maximum limit. You cannot override it by specifying higher
762 values for the <B>-files</B> or <B>-chunksize</B> arguments, alone or
763 in combination. A related reason is that the Cache Manager does not
764 have to reserve a set amount of memory on disk. <B>V</B><VAR>n</VAR>
765 files (the chunks in a disk cache) are initially zero-length, but can expand
766 up to the specified chunk size and shrink again, as needed. If you set
767 the number of <B>V</B><VAR>n</VAR> files to such a large value that
768 expanding all of them to the full allowable size exceeds the total cache size,
769 they simply never grow to full size.
770 <P><H3><A NAME="HDRWQ551" HREF="auagd002.htm#ToC_449">Controlling Memory Cache Configuration</A></H3>
771 <P>Configuring a memory cache differs from configuring a disk
772 cache in that not all combinations of the <B>afsd</B> command's
773 arguments are allowed. This limitation results from the greater
774 interaction between the configuration parameters in a memory cache than a disk
775 cache. If all combinations are allowed, it is possible to set the
776 parameters in an inconsistent way. A list of the acceptable and
777 unacceptable combinations follows a discussion of default values.
778 <P>The default chunk size for a memory cache is 8 KB. In general, the
779 only reason to change it is to adjust to exceptionally slow or fast
780 networks; see <A HREF="#HDRWQ549">Setting Cache Configuration Parameters</A>.
781 <P>There is no predefined default for number of chunks in a memory
782 cache. The Cache Manager instead calculates the correct number by
783 dividing the total cache size by the chunk size. Recall that for a
784 memory cache, all dcache entries must be in memory. This implies that
785 the number of chunks equals the number of dcache entries in memory, and that
786 there is no default for number of dcache entries (like the number of chunks,
787 it is calculated by dividing the total size by the chunk size).
788 <P>The following are acceptable combinations of the <B>afsd</B>
789 command's arguments when configuring a memory cache:
791 <P><LI><B>-blocks</B> alone, which overrides the cache size specified in the
792 <B>/usr/vice/etc/cacheinfo</B> file. The Cache Manager divides the
793 value of this argument by the default chunk size of eight KB to calculate the
794 number of chunks and dcache entries. The following example sets cache
795 size to five MB (5,120 KB) and the number of chunks to 640 (5,120 divided by
797 <PRE> <B>/usr/vice/etc/afsd -memcache -blocks 5120</B>
799 <P><LI><B>-chunksize</B> alone, to override the default of eight KB.
800 The chunk size must be a power of two, so provide an integer between 0 (zero)
801 and 30 to be used as an exponent of two. For example, a value of ten
802 sets chunk size to 1 KB (2<SUP>10</SUP> = 1024); a value of 13 equals the
803 default for memory caches (2<SUP>13</SUP> = 8 KB). Specifying a value
804 of 0 (zero) or greater than 30 returns the chunk size to the default.
805 Values less than ten (equivalent to 1 KB) are not recommended. The
806 following example sets the chunk size to four KB (2<SUP>12</SUP>).
807 Assuming a total cache size of four MB (4,096 KB), the resulting number of
809 <PRE> <B>/usr/vice/etc/afsd -memcache -chunksize 12</B>
811 <P><LI><B>-blocks</B> and <B>-chunksize</B> together override the
812 defaults for cache size and chunk size. The Cache Manager divides the
813 first by the second to calculate the number of chunks and dcache
814 entries. For example, the following example sets the cache size to six
815 MB (6,144 KB) and chunksize to four KB (2<SUP>12</SUP>), resulting in 1,536
817 <PRE> <B>/usr/vice/etc/afsd -memcache -blocks 6144 -chunksize 12</B>
820 <P>The following arguments or combinations explicitly set the number of chunks
821 and dcache entries. It is best not to use them, because they set the
822 cache size indirectly, forcing you to perform a hand calculation to determine
823 the size of the cache. Instead, set the <B>-blocks</B> and
824 <B>-chunksize</B> arguments alone or in combination; in those cases,
825 the Cache Manager determines the number of chunks and dcache entries
826 itself. Because the following combinations are not recommended, no
827 examples are included.
829 <P><LI>The <B>-dcache</B> argument alone explicitly sets the number of chunks
830 and dcache entries. The Cache Manager multiples this value times the
831 default chunk size of 8 KB to derive the total cache size (overriding the
832 value in the <B>cacheinfo</B> file).
833 <P><LI>The combination of <B>-dcache</B> and <B>-chunksize</B> sets the
834 chunk number and size. The Cache Manager sets the specified values and
835 multiplies them together to obtain total cache size (overriding the value in
836 the <B>cacheinfo</B> file).
838 <P>Do not use the following arguments for a memory cache:
840 <P><LI><B>-files</B> alone. This argument controls the number of
841 <B>V</B><VAR>n</VAR> files for a disk cache, but is ignored for a memory
843 <P><LI><B>-blocks</B> and <B>-dcache</B>. An error message
844 results, because it is possible to provide values such that dividing the first
845 (total size) by the second (number of chunks) results in a chunk size that is
848 <HR><H2><A NAME="HDRWQ552" HREF="auagd002.htm#ToC_450">Maintaining Knowledge of Database Server Machines</A></H2>
849 <A NAME="IDX7400"></A>
850 <A NAME="IDX7401"></A>
851 <A NAME="IDX7402"></A>
852 <A NAME="IDX7403"></A>
853 <A NAME="IDX7404"></A>
854 <A NAME="IDX7405"></A>
855 <A NAME="IDX7406"></A>
856 <A NAME="IDX7407"></A>
857 <A NAME="IDX7408"></A>
858 <P>For the users of an AFS client machine to access a cell's AFS
859 filespace and other services, the Cache Manager and other client-side agents
860 must have an accurate list of the cell's database server machines.
861 The affected functions include the following:
863 <P><LI>Accessing files. The Cache Manager contacts the Volume Location
864 (VL) Server to learn which file server machine houses the volume containing a
865 requested file or directory. If the Cache Manager cannot contact a
866 cell's VL Servers, it cannot fetch files.
867 <P><LI>Authenticating. The <B>klog</B> program and AFS-modified login
868 utilities contact the Authentication Server to obtain tokens, which the AFS
869 server processes accept as proof that the user is authenticated.
870 <P><LI>Creating protection groups. The <B>pts</B> command interpreter
871 contacts the Protection Server when users create protection groups or request
872 information from the Protection Database.
873 <P><LI>Editing access control lists (ACLs). The <B>fs</B> command
874 interpreter contacts the File Server that maintains the read/write volume
875 containing a file or directory; the location information comes from the
878 <P>To enable a machine's users to access a cell, you must list the names
879 and IP addresses of its database server machines in the
880 <B>/usr/vice/etc/CellServDB</B> file on the machine's local
881 disk. In addition to the machine's home cell, you can list any
882 foreign cells that you want to enable users to access. (To enable
883 access to a cell's filespace, you must also mount its
884 <B>root.cell</B> volume in the local AFS filespace; the
885 conventional location is just under the AFS root directory,
886 <B>/afs</B>. For instructions, see the <I>AFS Quick
888 <P><H3><A NAME="Header_451" HREF="auagd002.htm#ToC_451">How Clients Use the List of Database Server Machines</A></H3>
889 <P>As the <B>afsd</B> program runs and initializes the Cache Manager,
890 it reads the contents of the <B>CellServDB</B> file into kernel
891 memory. The Cache Manager does not consult the file again until the
892 machine next reboots. In contrast, the command interpreters for the AFS
893 command suites (such as <B>fs</B> and <B>pts</B>) read the
894 <B>CellServDB</B> file each time they need to contact a database server
896 <P>When a cell's list of database server machines changes, you must
897 change both the <B>CellServDB</B> file and the list in kernel memory to
898 preserve consistent client performance; some commands probably fail if
899 the two lists of machines disagree. One possible method for updating
900 both the <B>CellServDB</B> file and kernel memory is to edit the file and
901 reboot the machine. To avoid needing to reboot, you can instead perform
902 both of the following steps:
904 <P><LI>Issue the <B>fs newcell</B> command to alter the list in kernel memory
905 directly, making the changes available to the Cache Manager.
906 <P><LI>Edit the <B>CellServDB</B> file to make the changes available to
907 command interpreters. For a description of the file's format, see <A HREF="#HDRWQ553">The Format of the CellServDB file</A>.
909 <P>The consequences of missing or incorrect information in the
910 <B>CellServDB</B> file or kernel memory are as follows:
912 <P><LI>If there is no entry for a cell, the machine's users cannot access
914 <P><LI>If a cell's entry does not include a database server machine, then
915 the Cache Manager and command interpreters never attempt to contact the
916 machine. The omission does not prevent access to the cell--as long
917 as the information about the other database server machines is correct and the
918 server processes, machines, and network are functioning correctly--but it
919 can put an undue burden on the machines that are listed. If all of the
920 listed machines become inaccessible to clients, then the cell becomes
921 inaccessible even if the omitted database server machine is functioning
923 <P><LI>If a machine's name or address is incorrect, or the machine is not
924 actually running the database server processes, then requests from clients
925 time out. Users can experience lengthy delays because they have to wait
926 the full timeout period before the Cache Manager or command interpreter
927 contacts another database server machine.
929 <P><H3><A NAME="HDRWQ553" HREF="auagd002.htm#ToC_452">The Format of the CellServDB file</A></H3>
930 <A NAME="IDX7409"></A>
931 <A NAME="IDX7410"></A>
932 <P>When editing the <B>/usr/vice/etc/CellServDB</B> file, you must use the
933 correct format for cell and machine entries. Each cell has a separate
934 entry. The first line has the following format:
935 <PRE> ><VAR>cell_name</VAR> #<VAR>organization</VAR>
937 <P>where <VAR>cell_name</VAR> is the cell's complete Internet domain name
938 (for example, <B>abc.com</B>) and <VAR>organization</VAR> is an
939 optional field that follows any number of spaces and the number sign
940 (<TT>#</TT>) and can name the organization to which the cell corresponds
941 (for example, the ABC Corporation). After the first line comes a
942 separate line for each database server machine. Each line has the
943 following format:
944 <PRE> <VAR>IP_address</VAR> #<VAR>machine_name</VAR>
946 <P>where <VAR>IP_address</VAR> is the machine's IP address in dotted
947 decimal format (for example, 192.12.105.3).
948 Following any number of spaces and the number sign (<TT>#</TT>) is
949 <VAR>machine_name</VAR>, the machine's fully-qualified hostname (for
950 example, <B>db1.abc.com</B>). In this case, the
951 number sign does not indicate a comment: <VAR>machine_name</VAR> is a
953 <P>The order in which the cells appear is not important, but it is convenient
954 to put the client machine's home cell first. Do not include any
955 blank lines in the file, not even after the last entry.
956 <P>The following example shows entries for two cells, each of which has three
957 database server machines:
958 <PRE> >abc.com #ABC Corporation (home cell)
959 192.12.105.3 #db1.abc.com
960 192.12.105.4 #db2.abc.com
961 192.12.105.55 #db3.abc.com
962 >stateu.edu #State University cell
963 138.255.68.93 #serverA.stateu.edu
964 138.255.68.72 #serverB.stateu.edu
965 138.255.33.154 #serverC.stateu.edu
967 <P><H3><A NAME="HDRWQ554" HREF="auagd002.htm#ToC_453">Maintaining the Client CellServDB File</A></H3>
968 <A NAME="IDX7411"></A>
969 <A NAME="IDX7412"></A>
970 <P>Because a correct entry in the <B>CellServDB</B> file is vital for
971 consistent client performance, you must also update the file on each client
972 machine whenever a cell's list of database server machines changes (for
973 instance, when you follow the instructions in the <I>AFS Quick
974 Beginnings</I> to add or remove a database server machine). To
975 facilitate the client updates, you can use the <B>package</B> program,
976 which copies files from a central source in AFS to the local disk of client
977 machines. It is conventional to invoke the <B>package</B> program
978 in a client machine's AFS initialization file so that it runs as the
979 machine reboots, but you can also issue the <B>package</B> command at any
980 time. For instructions, see <A HREF="auagd016.htm#HDRWQ600">Running the package program</A>.
981 <P>If you use the <B>package</B> program, the conventional location for
982 your cell's central source <B>CellServDB</B> file is
983 <B>/afs/</B><VAR>cell_name</VAR><B>/common/etc/CellServDB</B>, where
984 <VAR>cell_name</VAR> is your cell name.
985 <A NAME="IDX7413"></A>
986 <P>Creating a symbolic or hard link from <B>/usr/vice/etc/CellServDB</B>
987 to a central source file in AFS is not a viable option. The
988 <B>afsd</B> program reads the file into kernel memory before the Cache
989 Manager is completely initialized and able to access AFS.
990 <P>Because every client machine has its own copy of the <B>CellServDB</B>
991 file, you can in theory make the set of accessible cells differ on various
992 machines. In most cases, however, it is best to maintain consistency
993 between the files on all client machines in the cell: differences
994 between machines are particularly confusing if users commonly use a variety of
995 machines rather than just one.
996 <P>The AFS Product Support group maintains a central <B>CellServDB</B>
997 file that includes all cells that have agreed to make their database server
998 machines access to other AFS cells. It is advisable to check this file
999 periodically for updated information. See <A HREF="auagd007.htm#HDRWQ38">Making Your Cell Visible to Others</A>.
1000 <A NAME="IDX7414"></A>
1001 <P>An entry in the local <B>CellServDB</B> is one of the two requirements
1002 for accessing a cell. The other is that the cell's
1003 <B>root.cell</B> volume is mounted in the local filespace, by
1004 convention as a subdirectory of the <B>/afs</B> directory. For
1005 instructions, see <A HREF="auagd010.htm#HDRWQ298">To create a cellular mount point</A>.
1006 <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
1007 same as the <B>/usr/afs/etc/CellServDB</B> file on the local disk of a
1008 file server machine. The server version lists only the database server
1009 machines in the server machine's home cell, because server processes
1010 never need to contact foreign cells. It is important to update both
1011 types of <B>CellServDB</B> file on all machines in the cell whenever there
1012 is a change to your cell's database server machines. For more
1013 information about maintaining the server version of the <B>CellServDB</B>
1014 file, see <A HREF="auagd008.htm#HDRWQ152">Maintaining the Server CellServDB File</A>.
1016 <A NAME="IDX7415"></A>
1017 <A NAME="IDX7416"></A>
1018 <A NAME="IDX7417"></A>
1019 <A NAME="IDX7418"></A>
1020 <A NAME="IDX7419"></A>
1021 <P><H3><A NAME="Header_454" HREF="auagd002.htm#ToC_454">To display the /usr/vice/etc/CellServDB file</A></H3>
1023 <P><LI>Use a text editor or the <B>cat</B> command to display the contents of
1024 the <B>/usr/vice/etc/CellServDB</B> file. By default, the mode bits
1025 on the file permit anyone to read it.
1026 <PRE> % <B>cat /usr/vice/etc/CellServDB</B>
1029 <A NAME="IDX7420"></A>
1030 <A NAME="IDX7421"></A>
1031 <P><H3><A NAME="Header_455" HREF="auagd002.htm#ToC_455">To display the list of database server machines in kernel memory</A></H3>
1033 <P><LI>Issue the <B>fs listcells</B> command.
1034 <PRE> % <B>fs listcells [&]</B>
1036 <P>where <B>listc</B> is the shortest acceptable abbreviation of
1038 <P>To have your shell prompt return immediately, include the ampersand
1039 (<B>&</B>), which makes the command run in the background. It
1040 can take a while to generate the complete output because the kernel stores
1041 database server machines' IP addresses only, and the <B>fs</B>
1042 command interpreter has the cell's name resolution service (such as the
1043 Domain Name Service or a local host table) translate them into
1044 hostnames. You can halt the command at any time by issuing an interrupt
1045 signal such as <B>Ctrl-c</B>.
1046 <P>The output includes a single line for each cell, in the following
1048 <PRE> Cell <VAR>cell_name</VAR> on hosts <VAR>list_of_hostnames</VAR>.
1050 <P>The name service sometimes returns hostnames in uppercase letters, and if
1051 it cannot resolve a name at all, it returns its IP address. The
1052 following example illustrates all three possibilities:
1053 <PRE> % <B>fs listcells</B>
1056 Cell abc.com on hosts db1.abc.com db2.abc.com db3.abc.com
1057 Cell stateu.edu on hosts SERVERA.STATEU.EDU SERVERB.STATEU.EDU
1059 Cell ghi.org on hosts 191.255.64.111 191.255.64.112
1064 <A NAME="IDX7422"></A>
1065 <A NAME="IDX7423"></A>
1066 <A NAME="IDX7424"></A>
1067 <A NAME="IDX7425"></A>
1068 <A NAME="IDX7426"></A>
1069 <A NAME="IDX7427"></A>
1070 <A NAME="IDX7428"></A>
1071 <A NAME="IDX7429"></A>
1072 <A NAME="IDX7430"></A>
1073 <A NAME="IDX7431"></A>
1074 <A NAME="IDX7432"></A>
1075 <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>
1077 <P><LI>Become the local superuser <B>root</B> on the machine, if you are not
1078 already, by issuing the <B>su</B> command.
1079 <PRE> % <B>su root</B>
1080 Password: <VAR>root_password</VAR>
1082 <P><LI>If you a use a central copy of the <B>CellServDB</B> file as a source
1083 for client machines, verify that its directory's ACL grants you the
1084 <B>l</B> (<B>lookup</B>), <B>r</B> (<B>read</B>), and
1085 <B>w</B> (<B>write</B>) permissions. The conventional directory
1086 is <B>/afs/</B><VAR>cell_name</VAR><B>/common/etc</B>. If
1087 necessary, issue the <B>fs listacl</B> command, which is fully described
1088 in <A HREF="auagd020.htm#HDRWQ787">Displaying ACLs</A>.
1089 <PRE> # <B>fs listacl</B> [<<VAR>dir/file path</VAR>>]
1091 <A NAME="IDX7433"></A>
1092 <A NAME="IDX7434"></A>
1093 <P><LI><A NAME="LINEWCELL"></A>Issue the <B>fs newcell</B> command to add or change a
1094 cell's entry in kernel memory. Repeat the command for each
1096 <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
1097 kernel memory. In the rare cases when you urgently need to prevent
1098 access to a specific cell, you must edit the <B>CellServDB</B> file and
1101 <PRE> # <B>fs newcell</B> <<VAR>cell name</VAR>> <<VAR>primary servers</VAR>><SUP>+</SUP> \
1102 [<B>-linkedcell</B> <<VAR>linked cell name</VAR>>]
1107 </B><DD>Is the shortest acceptable abbreviation of <B>newcell</B>.
1108 <P><DT><B><VAR>cell name</VAR>
1109 </B><DD>Specifies the complete Internet domain name of the cell for which to
1110 record a new list of database server machines.
1111 <P><DT><B><VAR>primary servers</VAR>
1112 </B><DD>Specifies the fully-qualified hostname or IP address in dotted-decimal
1113 format for each database server machine in the cell. The list you
1114 provide completely replaces the existing list.
1115 <P><DT><B>-linkedcell
1116 </B><DD>Specifies the complete Internet domain name of the AFS cell to link to a
1117 DCE cell for the purposes of DFS fileset location. You can use this
1118 argument if the machine's AFS users access DFS via the AFS/DFS Migration
1119 Toolkit Protocol Translator. For instructions, see the <I>AFS/DFS
1120 Migration Toolkit Administration Guide and Reference</I>.
1122 <P><LI>Add or edit the cell's entry in the local
1123 <B>/usr/vice/etc/CellServDB</B> file, using one of the following three
1124 methods. In each case, be sure to obey the formatting requirements
1125 described in <A HREF="#HDRWQ553">The Format of the CellServDB file</A>.
1127 <P><LI>If you maintain a central source version of the <B>CellServDB</B> file
1128 and use the <B>package</B> program, first use a text editor to alter the
1129 central copy of the file. Then issue the <B>package</B> command to
1130 transfer the contents of the file to the local machine. For complete
1131 instructions, see <A HREF="auagd016.htm#HDRWQ600">Running the package program</A>.
1132 <PRE> # <B>/etc/package -v -c</B> <<VAR>name of package file</VAR>>
1134 <P><LI>If you maintain a central source <B>CellServDB</B> file but do not use
1135 the <B>package</B> program, first use a text editor to alter the central
1136 copy of the file. Then use a copying command such as the <B>cp</B>
1137 command to copy it to the local <B>/usr/vice/etc/CellServDB</B>
1139 <P><LI>If you do not use a central source <B>CellServDB</B> file, edit the
1140 local machine's <B>/usr/vice/etc/CellServDB</B> file directly.
1143 <HR><H2><A NAME="HDRWQ555" HREF="auagd002.htm#ToC_457">Determining if a Client Can Run Setuid Programs</A></H2>
1144 <A NAME="IDX7435"></A>
1145 <A NAME="IDX7436"></A>
1146 <A NAME="IDX7437"></A>
1147 <P>A <I>setuid program</I> is one whose binary file has the UNIX setuid
1148 mode bit turned on. While a setuid program runs, the user who
1149 initialized it assumes the local identity (UNIX UID) of the binary file's
1150 owner, and so is granted the permissions in the local file system that pertain
1151 to the owner. Most commonly, the issuer's assumed identity (often
1152 referred to as <I>effective UID</I>) is the local superuser
1154 <P>AFS does not recognize effective UID: if a setuid program accesses
1155 AFS files and directories, it uses the current AFS identity of the user who
1156 initialized the program, not of the program's owner. Nevertheless,
1157 it can be useful to store setuid programs in AFS for use on more than one
1158 client machine. AFS enables a client machine's administrator to
1159 determine whether the local Cache Manager allows setuid programs to run or
1161 <P>By default, the Cache Manager allows programs from its home cell to run
1162 with setuid permission, but denies setuid permission to programs from foreign
1163 cells. A program belongs to the same cell as the file server machine
1164 that houses the volume in which the file resides, as specified in the file
1165 server machine's <B>/usr/afs/etc/ThisCell</B> file. The Cache
1166 Manager determines its own home cell by reading the
1167 <B>/usr/vice/etc/ThisCell</B> file at initialization.
1168 <P>To change a cell's setuid status with respect to the local machine,
1169 become the local superuser <B>root</B> and issue the <B>fs setcell</B>
1170 command. To determine a cell's current setuid status, use the
1171 <B>fs getcellstatus</B> command.
1172 <P>When you issue the <B>fs setcell</B> command, you directly alter a
1173 cell's setuid status as recorded in kernel memory, so rebooting the
1174 machine is not necessary. However, nondefault settings do not persist
1175 across reboots of the machine unless you add the appropriate <B>fs
1176 setcell</B> command to the machine's AFS initialization file.
1177 <P>Only members of the <B>system:administrators</B> group can turn
1178 on the setuid mode bit on an AFS file or directory. When the setuid
1179 mode bit is turned on, the UNIX <B>ls -l</B> command displays the third
1180 user mode bit as an <B>s</B> instead of an <B>x</B>, but for an AFS
1181 file or directory, the <B>s</B> appears only if setuid permission is
1182 enabled for the cell in which the file resides.
1183 <A NAME="IDX7438"></A>
1184 <A NAME="IDX7439"></A>
1185 <P><H3><A NAME="Header_458" HREF="auagd002.htm#ToC_458">To determine a cell's setuid status</A></H3>
1187 <P><LI>Issue the <B>fs getcellstatus</B> command to check the setuid status
1188 of each desired cell.
1189 <PRE> % <B>fs getcellstatus</B> <<VAR>cell name</VAR>>
1193 <P><DT><B><B>getce</B>
1194 </B><DD>Is the shortest acceptable abbreviation of
1195 <B>getcellstatus</B>.
1196 <P><DT><B><VAR>cell name</VAR>
1197 </B><DD>Names each cell for which to report setuid status. Provide the
1198 complete Internet domain name or a shortened form that distinguishes it from
1199 the other cells listed in the local <B>/usr/vice/etc/CellServDB</B>
1203 <P>The output reports the setuid status of each cell:
1205 <P><LI>the string <TT>no setuid allowed</TT> indicates that the Cache Manager
1206 does not allow programs from the cell to run with setuid permission
1207 <P><LI><TT>setuid allowed</TT> indicates that the Cache Manager allows programs
1208 from the cell to run with setuid permission
1210 <A NAME="IDX7440"></A>
1211 <A NAME="IDX7441"></A>
1212 <P><H3><A NAME="Header_459" HREF="auagd002.htm#ToC_459">To change a cell's setuid status</A></H3>
1214 <P><LI>Become the local superuser <B>root</B> on the machine, if you are not
1215 already, by issuing the <B>su</B> command.
1216 <PRE> % <B>su root</B>
1217 Password: <VAR>root_password</VAR>
1219 <P><LI>Issue the <B>fs setcell</B> command to change the setuid status of the
1221 <PRE> # <B>fs setcell</B> <<VAR>cell name</VAR>><SUP>+</SUP> [<B>-suid</B>] [<B>-nosuid</B>]
1225 <P><DT><B><B>setce</B>
1226 </B><DD>Is the shortest acceptable abbreviation of <B>setcell</B>.
1227 <P><DT><B><VAR>cell name</VAR>
1228 </B><DD>Names each cell for which to change setuid status as specified by the
1229 <B>-suid</B> or <B>-nosuid</B> flag. Provide each cell's
1230 complete Internet domain name or a shortened form that distinguishes it from
1231 the other cells listed in the local <B>/usr/vice/etc/CellServDB</B>
1233 <P><DT><B><B>-suid</B>
1234 </B><DD>Enables programs from each specified cell to execute with setuid
1235 permission. Provide this flag or the <B>-nosuid</B> flag, or omit
1236 both to disable setuid permission for each cell.
1237 <P><DT><B><B>-nosuid</B>
1238 </B><DD>Prevents programs from each specified cell from executing with setuid
1239 permission. Provide this flag or the <B>-suid</B> flag, or omit
1240 both to disable setuid permission for each cell.
1243 <HR><H2><A NAME="HDRWQ556" HREF="auagd002.htm#ToC_460">Setting the File Server Probe Interval</A></H2>
1244 <A NAME="IDX7442"></A>
1245 <A NAME="IDX7443"></A>
1246 <A NAME="IDX7444"></A>
1247 <P>The Cache Manager periodically sends a probe to server machines to verify
1248 that they are still accessible. Specifically, it probes the database
1249 server machines in its cell and those file servers that house data it has
1251 <P>If a server process does not respond to a probe, the client machine assumes
1252 that it is inaccessible. By default, the interval between probes is
1253 three minutes, so it can take up to three minutes for a client to recognize
1254 that a server process is once again accessible after it was
1256 <P>To adjust the probe interval, include the <B>-interval</B> argument to
1257 the <B>fs checkservers</B> command while logged in as the local superuser
1258 <B>root</B>. The new interval setting persists until you again
1259 issue the command or reboot the machine, at which time the setting returns to
1260 the default. To preserve a nondefault setting across reboots, include
1261 the appropriate <B>fs checkservers</B> command in the machine's AFS
1262 initialization file.
1263 <P><H3><A NAME="Header_461" HREF="auagd002.htm#ToC_461">To set a client's file server probe interval</A></H3>
1265 <P><LI>Become the local superuser <B>root</B> on the machine, if you are not
1266 already, by issuing the <B>su</B> command.
1267 <PRE> % <B>su root</B>
1268 Password: <VAR>root_password</VAR>
1270 <P><LI>Issue the <B>fs checkservers</B> command with the <B>-interval</B>
1272 <A NAME="IDX7445"></A>
1273 <A NAME="IDX7446"></A>
1275 <PRE> # <B>fs checkservers -interval</B> <<VAR>seconds between probes</VAR>>
1279 <P><DT><B><B>checks</B>
1280 </B><DD>Is the shortest acceptable abbreviation of <B>checkservers</B>.
1282 </B><DD>Specifies the number of seconds between probes. Provide an integer
1283 value greater than zero.
1286 <HR><H2><A NAME="HDRWQ557" HREF="auagd002.htm#ToC_462">Setting a Client Machine's Cell Membership</A></H2>
1287 <A NAME="IDX7447"></A>
1288 <A NAME="IDX7448"></A>
1289 <A NAME="IDX7449"></A>
1290 <A NAME="IDX7450"></A>
1291 <A NAME="IDX7451"></A>
1292 <A NAME="IDX7452"></A>
1293 <P>Each client machine belongs to a particular cell, as named in the
1294 <B>/usr/vice/etc/ThisCell</B> on its local disk. The machine's
1295 cell membership determines three defaults important to users of the
1298 <P><LI>The cell for which users of the machine obtain tokens (authenticate) when
1299 they use the <B>login</B> program or issue the <B>klog</B>
1300 command. There are two effects:
1302 <P><LI>The <B>klog</B> program and AFS-modified login utilities contact an
1303 Authentication Server in the cell named in the <B>ThisCell</B>
1305 <P><LI>The <B>klog</B> program and AFS-modified login utilities combine the
1306 contents of the <B>ThisCell</B> file with the password that the user
1307 provides, generating an encryption key from the combination. The
1308 user's entry in the Authentication Database includes an encryption key
1309 also generated from the combination of password and cell name. If the
1310 cell name in the <B>ThisCell</B> file is incorrect, users cannot
1311 authenticate even if they provide the correct password.
1313 <P><LI>The cell the Cache Manager considers its local, or home, cell. The
1314 Cache Manager allows programs from its local cell to run with setuid
1315 permission, but not programs from foreign cells, as discussed further in <A HREF="#HDRWQ555">Determining if a Client Can Run Setuid Programs</A>.
1316 <P><LI>The default database server machines that are contacted by the AFS command
1317 interpreters running on this machine.
1319 <P><H3><A NAME="Header_463" HREF="auagd002.htm#ToC_463">To display a client machine's cell membership</A></H3>
1321 <P><LI>Use a text editor or the <B>cat</B> command to display the contents of
1322 the <B>/usr/vice/etc/ThisCell</B> file.
1323 <PRE> % <B>cat /usr/vice/etc/ThisCell</B>
1326 <P><H3><A NAME="Header_464" HREF="auagd002.htm#ToC_464">To set a client machine's cell membership</A></H3>
1328 <P><LI>Become the local superuser <B>root</B> on the machine, if you are not
1329 already, by issuing the <B>su</B> command.
1330 <PRE> % <B>su root</B>
1331 Password: <VAR>root_password</VAR>
1333 <P><LI>Using a text editor, replace the cell name in the
1334 <B>/usr/vice/etc/ThisCell</B> file.
1335 <P><LI><B>(Optional.)</B> Reboot the machine to enable the Cache
1336 Manager to use the new cell name immediately; the appropriate command
1337 depends on the machine's system type. The <B>klog</B> program,
1338 AFS-modified login utilities, and the AFS command interpreters use the new
1339 cell name the next time they are invoked; no reboot is necessary.
1345 <HR><H2><A NAME="HDRWQ558" HREF="auagd002.htm#ToC_465">Forcing the Update of Cached Data</A></H2>
1346 <A NAME="IDX7453"></A>
1347 <A NAME="IDX7454"></A>
1348 <A NAME="IDX7455"></A>
1349 <A NAME="IDX7456"></A>
1350 <A NAME="IDX7457"></A>
1351 <A NAME="IDX7458"></A>
1352 <A NAME="IDX7459"></A>
1353 <A NAME="IDX7460"></A>
1354 <P>AFS's callback mechanism normally guarantees that the Cache Manager
1355 provides the most current version of a file or directory to the application
1356 programs running on its machine. However, you can force the Cache
1357 Manager to discard (flush) cached data so that the next time an application
1358 program requests it, the Cache Manager fetches the latest version available at
1360 <P>You can control how many file system elements to flush at a time:
1362 <P><LI>To flush only specific files or directories, use the <B>fs flush</B>
1363 command. This command forces the Cache Manager to discard the data and
1364 status information it has cached from the specified files or
1365 directories. It does not discard information from an application
1366 program's buffer or information that has been altered locally (changes
1367 made in the cache but not yet saved permanently to the File Server).
1368 However, the next time an application requests the element's data or
1369 status information, the Cache Manager has to contact the File Server to get
1371 <P><LI>To flush everything cached from a certain volume, use the <B>fs
1372 flushvolume</B> command. This command works like the <B>fs
1373 flush</B> command, but differs in two ways:
1375 <P><LI>The Cache Manager discards data for all elements in the cache that come
1376 from the same volume as the specified files or directories.
1377 <P><LI>The Cache Manager discards only data, not status information. This
1378 difference has little practical effect, but can lead to different output from
1379 the <B>ls</B> command when the two different commands are used to flush
1383 <P>In addition to callbacks, the Cache Manager has a mechanism for tracking
1384 other kinds of possible changes, such as changes in a volume's
1385 location. If a volume moves and the Cache Manager has not accessed any
1386 data in it for a long time, the Cache Manager's volume location record
1387 can be wrong. To resynchronize it, use the <B>fs checkvolumes</B>
1388 command. When you issue the command, the Cache Manager creates a new
1389 table of mappings between volume names, ID numbers, and locations. This
1390 forces the Cache Manager to reference newly relocated and renamed volumes
1391 before it can provide data from them.
1392 <P>It is also possible for information about mount points to become corrupted
1393 in the cache. Symptoms of a corrupted mount point included garbled
1394 output from the <B>fs lsmount</B> command, and failed attempts to change
1395 directory to or list the contents of a mount point. Use the <B>fs
1396 flushmount</B> command to discard a corrupted mount point. The Cache
1397 Manager must refetch the mount point the next time it crosses it in a
1398 pathname. (The Cache Manager periodically refreshes cached mount
1399 points, but the only other way to discard them immediately is to reinitialize
1400 the Cache Manager by rebooting the machine.
1401 <A NAME="IDX7461"></A>
1402 <A NAME="IDX7462"></A>
1403 <P><H3><A NAME="Header_466" HREF="auagd002.htm#ToC_466">To flush certain files or directories</A></H3>
1405 <P><LI>Issue the <B>fs flush</B> command.
1406 <PRE> % <B>fs flush</B> [<<VAR>dir/file path</VAR>><SUP>+</SUP>]
1410 <P><DT><B><B>flush</B>
1411 </B><DD>Must be typed in full.
1412 <P><DT><B><VAR>dir/file path</VAR>
1413 </B><DD>Names each file or directory structure to flush from the cache.
1414 Omit this argument to flush the current working directory. Flushing a
1415 directory structure does not flush any files or subdirectories cached from
1419 <A NAME="IDX7463"></A>
1420 <A NAME="IDX7464"></A>
1421 <P><H3><A NAME="Header_467" HREF="auagd002.htm#ToC_467">To flush all data from a volume</A></H3>
1423 <P><LI>Issue the <B>fs flushvolume</B> command.
1424 <PRE> % <B>fs flushvolume</B> [<<VAR>dir/file path</VAR>><SUP>+</SUP>]
1428 <P><DT><B><B>flushv</B>
1429 </B><DD>Is the shortest acceptable abbreviation of <B>flushvolume</B>.
1430 <P><DT><B><VAR>dir/file path</VAR>
1431 </B><DD>Names a file or directory from each volume to flush from the cache.
1432 The Cache Manager flushes everything in the cache that it has fetched from the
1433 same volume. Omit this argument to flush all cached data fetched from
1434 the volume that contains the current working directory.
1437 <A NAME="IDX7465"></A>
1438 <A NAME="IDX7466"></A>
1439 <P><H3><A NAME="Header_468" HREF="auagd002.htm#ToC_468">To force the Cache Manager to notice other volume changes</A></H3>
1441 <P><LI>Issue the <B>fs checkvolumes</B> command.
1442 <PRE> % <B>fs checkvolumes</B>
1444 <P>where <B>checkv</B> is the shortest acceptable abbreviation of
1445 <B>checkvolumes</B>.
1447 <P>The following command confirms that the command completed
1449 <PRE> All volumeID/name mappings checked.
1451 <A NAME="IDX7467"></A>
1452 <A NAME="IDX7468"></A>
1453 <P><H3><A NAME="HDRWQ559" HREF="auagd002.htm#ToC_469">To flush one or more mount points</A></H3>
1455 <P><LI>Issue the <B>fs flushmount</B> command.
1456 <PRE> % <B>fs flush</B> [<<VAR>dir/file path</VAR>><SUP>+</SUP>]
1460 <P><DT><B><B>flushm</B>
1461 </B><DD>Is the shortest acceptable abbreviation of <B>flushmount</B>.
1462 <P><DT><B><VAR>dir/file path</VAR>
1463 </B><DD>Names each mount point to flush from the cache. Omit this argument
1464 to flush the current working directory. Files or subdirectories cached
1465 from the associated volume are unaffected.
1468 <HR><H2><A NAME="HDRWQ560" HREF="auagd002.htm#ToC_470">Maintaining Server Preference Ranks</A></H2>
1469 <A NAME="IDX7469"></A>
1470 <A NAME="IDX7470"></A>
1471 <A NAME="IDX7471"></A>
1472 <A NAME="IDX7472"></A>
1473 <A NAME="IDX7473"></A>
1474 <A NAME="IDX7474"></A>
1475 <P>As mentioned in the introduction to this chapter, AFS uses client-side data
1476 caching and callbacks to reduce the amount of network traffic in your
1477 cell. The Cache Manager also tries to make its use of the network as
1478 efficient as possible by assigning <I>preference ranks</I> to server
1479 machines based on their network proximity to the local machine. The
1480 ranks bias the Cache Manager to fetch information from the server machines
1481 that are on its own subnetwork or network rather than on other networks, if
1482 possible. Reducing the network distance that data travels between
1483 client and server machine tends to reduce network traffic and speed the Cache
1484 Manager's delivery of data to applications.
1485 <P>The Cache Manager stores two separate sets of preference ranks in kernel
1486 memory. The first set of ranks applies to machines that run the Volume
1487 Location (VL) Server process, hereafter referred to as <I>VL Server
1488 machines</I>. The second set of ranks applies to machines that run
1489 the File Server process, hereafter referred to as <I>file server
1490 machines</I>. This section explains how the Cache Manager sets
1491 default ranks, how to use the <B>fs setserverprefs</B> command to change
1492 the defaults or set new ranks, and how to use the <B>fs getserverprefs</B>
1493 command to display the current set of ranks.
1494 <P><H3><A NAME="Header_471" HREF="auagd002.htm#ToC_471">How the Cache Manager Sets Default Ranks</A></H3>
1495 <P>As the <B>afsd</B> program initializes the Cache Manager, it
1496 assigns a preference rank of 10,000 to each of the VL Server machines listed
1497 in the local <B>/usr/vice/etc/CellServDB</B> file. It then
1498 randomizes the ranks by adding an integer randomly chosen from the range 0
1499 (zero) to 126. It avoids assigning the same rank to machines in one
1500 cell, but it is possible for machines from different cells to have the same
1501 rank. This does not present a problem in use, because the Cache Manager
1502 compares the ranks of only one cell's database server machines at a
1503 time. Although AFS supports the use of multihomed database server
1504 machines, the Cache Manager only uses the single address listed for each
1505 database server machine in the local <B>/usr/vice/etc/CellServDB</B>
1506 file. Only Ubik can take advantage of a multihomed database server
1507 machine's multiple interfaces.
1508 <P>The Cache Manager assigns preference ranks to a file server machine when it
1509 obtains the server's VLDB record from the VL Server, the first time that
1510 it accesses a volume that resides on the machine. If the machine is
1511 multihomed, the Cache Manager assigns a distinct rank to each of its
1512 interfaces (up to the number of interfaces that the VLDB can store for each
1513 machine, which is specified in the <I>AFS Release Notes</I>). The
1514 Cache Manager compares the interface's IP address to the local
1515 machine's address and applies the following algorithm:
1517 <P><LI>If the local machine is a file server machine, the base rank for each of
1518 its interfaces is 5,000.
1519 <P><LI>If the file server machine interface is on the same subnetwork as the
1520 local machine, its base rank is 20,000.
1521 <P><LI>If the file server machine interface is on the same network as the local
1522 machine, or is at the distant end of a point-to-point link with the local
1523 machine, its base rank is 30,000.
1524 <P><LI>If the file server machine interface is on a different network than the
1525 local machine, or the Cache Manager cannot obtain network information about
1526 it, its base rank is 40,000.
1528 <P>If the client machine has only one interface, the Cache Manager compares it
1529 to the server interface's IP address and sets a rank according to the
1530 algorithm. If the client machine is multihomed, the Cache Manager
1531 compares each of the local interface addresses to the server interface, and
1532 assigns to the server interface the lowest rank that results from comparing it
1533 to all of the client interfaces.
1534 <P>After assigning a base rank to a file server machine interface, the Cache
1535 Manager adds to it a number randomly chosen from the range 0 (zero) to
1536 15. As an example, a file server machine interface in the same
1537 subnetwork as the local machine receives a base rank of 20,000, but the Cache
1538 Manager records the actual rank as an integer between 20,000 and
1539 20,015. This process reduces the number of interfaces that have exactly
1540 the same rank. As with VL Server machine ranks, it is possible for file
1541 server machine interfaces from foreign cells to have the same rank as
1542 interfaces in the local cell, but this does not present a problem. Only
1543 the relative ranks of the interfaces that house a specific volume are
1544 relevant, and AFS supports storage of a volume in only one cell at a
1546 <P><H3><A NAME="Header_472" HREF="auagd002.htm#ToC_472">How the Cache Manager Uses Preference Ranks</A></H3>
1547 <P>Each preference rank pairs an interface's IP address with an
1548 integer that can range from 1 to 65,534. A lower rank (lower number)
1549 indicates a stronger preference. Once set, a rank persists until the
1550 machine reboots, or until you use the <B>fs setserverprefs</B> command to
1552 <P>The Cache Manager uses VL Server machine ranks when it needs to fetch
1553 volume location information from a cell. It compares the ranks for the
1554 cell's VL Server machines and attempts to contact the VL Server process
1555 on the machine with the best (lowest integer) rank. If it cannot reach
1556 that VL Server, it tries to contact the VL Server with the next best rank, and
1557 so on. If all of a cell's VL Server machines are inaccessible, the
1558 Cache Manager cannot fetch data from the cell.
1559 <P>Similarly, when the Cache Manager needs to fetch data from a volume, it
1560 compares the ranks for the interfaces of machines that house the volume, and
1561 attempts to contact the interface that has the best rank. If it cannot
1562 reach the <B>fileserver</B> process via that interface, it tries to
1563 contact the interface with the next best integer rank, and so on. If it
1564 cannot reach any of the interfaces for machines that house the volume, it
1565 cannot fetch data from the volume.
1566 <P><H3><A NAME="Header_473" HREF="auagd002.htm#ToC_473">Displaying and Setting Preference Ranks</A></H3>
1567 <P>To display the file server machine ranks that the Cache Manager is
1568 using, use the <B>fs getserverprefs</B> command. Include the
1569 <B>-vlservers</B> flag to display VL Server machine ranks instead.
1570 By default, the output appears on the standard output stream (stdout), but you
1571 can write it to a file instead by including the <B>-file</B>
1573 <P>The Cache Manager stores IP addresses rather than hostnames in its kernel
1574 list of ranks, but by default the output identifies interfaces by hostname
1575 after calling a translation routine that refers to either the cell's name
1576 service (such as the Domain Name Server) or the local host table. If an
1577 IP address appears in this case, it is because the translation attempt
1578 failed. To bypass the translation step and display IP addresses rather
1579 than hostnames, include the <B>-numeric</B> flag. This can
1580 significantly speed up the output.
1581 <P>You can use the <B>fs setserverprefs</B> command to reset an existing
1582 preference rank, or to set the initial rank of a file server machine interface
1583 or VL Server machine for which the Cache Manager has no rank. The ranks
1584 you set persist until the machine reboots or until you issue the <B>fs
1585 setserverprefs</B> command again. To make a rank persist across a
1586 reboot, place the appropriate <B>fs setserverprefs</B> command in the
1587 machine's AFS initialization file.
1588 <P>As with default ranks, the Cache Manager adds a randomly chosen integer to
1589 each rank range that you assign. For file server machine interfaces,
1590 the randomizing number is from the range 0 (zero) to 15; for VL Server
1591 machines, it is from the range 0 (zero) to 126. For example, if you
1592 assign a rank of 15,000 to a file server machine interface, the Cache Manager
1593 stores an integer between 15,000 to 15,015.
1594 <P>To assign VL Server machine ranks, list them after the <B>-vlserver</B>
1595 argument to the <B>fs setserverprefs</B> command.
1596 <P>To assign file server machine ranks, use or more of the three possible
1599 <P><LI>List them after the <B>-servers</B> argument on the command
1601 <P><LI>Record them in a file and name it with the <B>-file</B>
1602 argument. You can easily generate a file with the proper format by
1603 including the <B>-file</B> argument to the <B>fs getserverprefs</B>
1605 <P><LI>Provide them via the standard input stream, by including the
1606 <B>-stdin</B> flag. This enables you to feed in values directly
1607 from a command or script that generates preferences using an algorithm
1608 appropriate for your cell. It must generate them in the proper format,
1609 with one or more spaces between each pair and between the two parts of the
1610 pair. The AFS distribution does not include such a script, so you must
1611 write one if you want to use this method.
1613 <P>You can combine any of the <B>-servers</B>, <B>-file</B>, and
1614 <B>-stdin</B> options on the same command line if you wish. If more
1615 than one of them specifies a rank for the same interface, the one assigned
1616 with the <B>-servers</B> argument takes precedence. You can also
1617 provide the <B>-vlservers</B> argument on the same command line to set VL
1618 Server machine ranks at the same time as file server machine ranks.
1619 <P>The <B>fs</B> command interpreter does not verify hostnames or IP
1620 addresses, and so willingly stores ranks for hostnames and addresses that
1621 don't actually exist. The Cache Manager never uses such ranks
1622 unless the same VLDB record for a server machine records the same incorrect
1624 <A NAME="IDX7475"></A>
1625 <A NAME="IDX7476"></A>
1626 <P><H3><A NAME="Header_474" HREF="auagd002.htm#ToC_474">To display server preference ranks</A></H3>
1628 <P><LI>Issue the <B>fs getserverprefs</B> command to display the Cache
1629 Manager's preference ranks for file server machines or VL Server
1631 <PRE> % <B>fs getserverprefs</B> [<B>-file</B> <<VAR>output to named file</VAR>>] [<B>-numeric</B>] [<B>-vlservers</B>]
1636 </B><DD>Is an acceptable alias for <B>getserverprefs</B> (<B>gets</B> is
1637 the shortest acceptable abbreviation).
1639 </B><DD>Specifies the pathname of the file to which to write the list of
1640 ranks. Omit this argument to display the list on the standard output
1643 </B><DD>Displays the IP address, rather than the hostname, of each ranked machine
1644 interface. Omit this flag to have the addresses translated into
1645 hostnames, which takes longer.
1646 <P><DT><B>-vlservers
1647 </B><DD>Displays ranks for VL Server machines rather than file server
1650 <P>The following example displays file server machine ranks. The
1651 <B>-numeric</B> flag is not used, so the appearance of an IP address
1652 indicates that is not currently possible to translate it to a hostname.
1654 <PRE> % <B>fs gp</B>
1657 server1.stateu.edu 40011
1660 192.12.106.120 40002
1661 192.12.106.119 40001
1665 <A NAME="IDX7477"></A>
1666 <A NAME="IDX7478"></A>
1667 <A NAME="IDX7479"></A>
1668 <P><H3><A NAME="Header_475" HREF="auagd002.htm#ToC_475">To set server preference ranks</A></H3>
1670 <P><LI>Become the local superuser <B>root</B> on the machine, if you are not
1671 already, by issuing the <B>su</B> command.
1672 <PRE> % <B>su root</B>
1673 Password: <VAR>root_password</VAR>
1675 <P><LI>Issue the <B>fs setserverprefs</B> command to set the Cache
1676 Manager's preference ranks for one or more file server machines or VL
1678 <PRE> # <B>fs setserverprefs</B> [<B>-servers</B> <<VAR>fileserver names and ranks</VAR>><SUP>+</SUP>] \
1679 [<B>-vlservers</B> <<VAR>VL server names and ranks</VAR>><SUP>+</SUP>] \
1680 [<B>-file</B> <<VAR>input from named file</VAR>>] [<B>-stdin</B>]
1685 </B><DD>Is an acceptable alias for <B>setserverprefs</B> (<B>sets</B> is
1686 the shortest acceptable abbreviation).
1688 </B><DD>Specifies one or more pairs of file server machine interface and
1689 rank. Identify each interface by its fully-qualified hostname or IP
1690 address in dotted decimal format. Acceptable ranks are the integers
1691 from <B>1</B> to <B>65534</B>. Separate the parts of a pair,
1692 and the pairs from one another, with one or more spaces.
1693 <P><DT><B>-vlservers
1694 </B><DD>Specifies one or more pairs of VL Server machine and rank. Identify
1695 each machine by its fully-qualified hostname or IP address in dotted decimal
1696 format. Acceptable ranks are the integers from <B>1</B> to
1699 </B><DD>Specifies the pathname of a file that contains one more pairs of file
1700 server machine interface and rank. Place each pair on its own line in
1701 the file. Use the same format for interfaces and ranks as with the
1702 <B>-servers</B> argument.
1704 </B><DD>Indicates that pairs of file server machine interface and rank are being
1705 provided via the standard input stream (stdin). The program or script
1706 that generates the pairs must format them in the same manner as for the
1707 <B>-servers</B> argument.
1710 <HR><H2><A NAME="HDRWQ561" HREF="auagd002.htm#ToC_476">Managing Multihomed Client Machines</A></H2>
1711 <A NAME="IDX7480"></A>
1712 <A NAME="IDX7481"></A>
1713 <A NAME="IDX7482"></A>
1714 <A NAME="IDX7483"></A>
1715 <A NAME="IDX7484"></A>
1716 <A NAME="IDX7485"></A>
1717 <P>The File Server can choose the interface to which to send a message when it
1718 initiates communication with the Cache Manager on a multihomed client machine
1719 (one with more than one network interface and IP address). If that
1720 interface is inaccessible, it automatically switches to an alternate.
1721 This improves AFS performance, because it means that the outage of an
1722 interface does not interrupt communication between File Server and Cache
1724 <P>The File Server can choose the client interface when it sends two types of
1727 <P><LI>A message to break the callback that the Cache Manager holds on a cached
1729 <P><LI>A <I>ping</I> message to check that the Cache Manager is still
1730 accessible and responding; the File Server sends such a message every few
1733 <P>(The File Server does not choose which client interface to respond to when
1734 filling a Cache Manager's request for AFS data. In that case, it
1735 always responds to the client interface via which the Cache Manager sent the
1737 <P>The Cache Manager compiles the list of eligible interfaces on its client
1738 machine automatically as it initializes, and records them in kernel
1739 memory. When the Cache Manager first establishes a connection with the
1740 File Server, it sends along the list of interface addresses. The File
1741 Server records the addresses, and uses the one at the top of the list when it
1742 needs to break a callback or send a ping to the Cache Manager. If that
1743 interface is inaccessible, the File Server simultaneously sends a message to
1744 all of the other interfaces in the list. Whichever interface replies
1745 first is the one to which the File Server sends future messages.
1746 <P>You can control which addresses the Cache Manager registers with File
1747 Servers by listing them in two files in the <B>/usr/vice/etc</B> directory
1748 on the client machine's local disk: <B>NetInfo</B> and
1749 <B>NetRestrict</B>. If the <B>NetInfo</B> file exists when the
1750 Cache Manager initializes, the Cache Manager uses its contents as the basis
1751 for the list of interfaces. Otherwise, the Cache Manager uses the list
1752 of interfaces configured with the operating system. It then removes
1753 from the list any addresses that appear in the
1754 <B>/usr/vice/etc/NetRestrict</B> file, if it exists. The Cache
1755 Manager records the resulting list in kernel memory.
1756 <P>You can also use the <B>fs setclientaddrs</B> command to change the
1757 list of addresses stored in the Cache Manager's kernel memory, without
1758 rebooting the client machine. The list of addresses you provide on the
1759 command line completely replaces the current list in kernel memory. The
1760 changes you make persist only until the client machine reboots,
1761 however. To preserve the revised list across reboots, list the
1762 interfaces in the <B>NetInfo</B> file (and if appropriate, the
1763 <B>NetRestrict</B> file) in the local <B>/usr/vice/etc</B>
1764 directory. (You can also place the appropriate <B>fs
1765 setclientaddrs</B> command in the machine's AFS initialization script,
1766 but that is less efficient: by the time the Cache Manager reads the
1767 command in the script, it has already compiled a list of interfaces.)
1768 <P>To display the list of addresses that the Cache Manager is currently
1769 registering with File Servers, use the <B>fs getclientaddrs</B>
1771 <P>Keep the following in mind when you change the <B>NetInfo</B> or
1772 <B>NetRestrict</B> file, or issue the <B>fs getclientaddrs</B> or
1773 <B>fs setclientaddrs</B> commands:
1775 <P><LI>When you issue the <B>fs setclientaddrs</B> command, the revised list
1776 of addresses does not propagate automatically to File Servers with which the
1777 Cache Manager has already established a connection. They continue to
1778 use the list that the Cache Manager registered with them when it first
1779 established a connection. To force previously contacted File Servers to
1780 use the revised list, you must either reboot each file server machine, or
1781 reboot the client machine after changing its <B>NetInfo</B> file,
1782 <B>NetRestrict</B> file, or both.
1783 <P><LI>The <B>fs</B> command interpreter verifies that each of the addresses
1784 you specify on the <B>fs setclientaddrs</B> command line is actually
1785 configured with the client machine's operating system. If it is
1786 not, the command fails with an error message that marks the address as a
1787 <TT>Nonexistent interface</TT>.
1788 <P><LI>As previously noted, the File Server does not use the registered list of
1789 addresses when it responds to the Cache Manager's request for data (as
1790 opposed to initiating communication itself). It always attempts to send
1791 its reply to the interface from which the Cache Manager sent the
1792 request. If the reply attempt fails, the File Server selects an
1793 alternate route for resending the reply according to its server machine's
1794 network routing configuration, not the list of addresses registered by the
1796 <P><LI>The Cache Manager does not use the list of interfaces when choosing the
1797 interface via which to establish a connection to a File Server.
1798 <P><LI>The list of addresses that the <B>fs getclientaddrs</B> command
1799 displays is not necessarily the one that a specific File Server is using, if
1800 an administrator has issued the <B>fs setclientaddrs</B> command since the
1801 Cache Manager first contacted that File Server. It determines only
1802 which addresses the Cache Manager registers when connecting to File Servers in
1805 <A NAME="IDX7486"></A>
1806 <A NAME="IDX7487"></A>
1807 <A NAME="IDX7488"></A>
1808 <A NAME="IDX7489"></A>
1809 <P><H3><A NAME="Header_477" HREF="auagd002.htm#ToC_477">To create or edit the client NetInfo file</A></H3>
1811 <P><LI>Become the local superuser <B>root</B> on the machine, if you are not
1812 already, by issuing the <B>su</B> command.
1813 <PRE> % <B>su root</B>
1814 Password: <VAR>root_password</VAR>
1816 <P><LI>Using a text editor, open the <B>/usr/vice/etc/NetInfo</B>
1817 file. Place one IP address in dotted decimal format (for example,
1818 <TT>192.12.107.33</TT>) on each line. On the
1819 first line, put the address that you want each File Server to use
1820 initially. The order of the remaining machines does not matter, because
1821 if an RPC to the first interface fails, the File Server simultaneously sends
1822 RPCs to all of the other interfaces in the list. Whichever interface
1823 replies first is the one to which the File Server then sends pings and RPCs to
1825 <P><LI>If you want the Cache Manager to start using the revised list immediately,
1826 either reboot the machine, or use the <B>fs setclientaddrs</B> command to
1827 create the same list of addresses in kernel memory directly.
1829 <A NAME="IDX7490"></A>
1830 <A NAME="IDX7491"></A>
1831 <A NAME="IDX7492"></A>
1832 <A NAME="IDX7493"></A>
1833 <P><H3><A NAME="Header_478" HREF="auagd002.htm#ToC_478">To create or edit the client NetRestrict file</A></H3>
1835 <P><LI>Become the local superuser <B>root</B> on the machine, if you are not
1836 already, by issuing the <B>su</B> command.
1837 <PRE> % <B>su root</B>
1838 Password: <VAR>root_password</VAR>
1840 <P><LI>Using a text editor, open the <B>/usr/vice/etc/NetRestrict</B>
1841 file. Place one IP address in dotted decimal format on each
1842 line. The order of the addresses is not significant. Use the
1843 value <B>255</B> as a wildcard that represents all possible addresses in
1844 that field. For example, the entry
1845 <TT>192.12.105.255</TT> indicates that the Cache
1846 Manager does not register any of the addresses in the 192.12.105
1848 <P><LI>If you want the Cache Manager to start using the revised list immediately,
1849 either reboot the machine, or use the <B>fs setclientaddrs</B> command to
1850 set a list of addresses that does not included the prohibited ones.
1852 <A NAME="IDX7494"></A>
1853 <A NAME="IDX7495"></A>
1854 <P><H3><A NAME="Header_479" HREF="auagd002.htm#ToC_479">To display the list of addresses from kernel memory</A></H3>
1856 <P><LI>Issue the <B>fs getclientaddrs</B> command.
1857 <PRE> % <B>fs getclientaddrs</B>
1859 <P>where <B>gc</B> is an acceptable alias for <B>getclientaddrs</B>
1860 (<B>getcl</B> is the shortest acceptable abbreviation).
1862 <P>The output lists each IP address on its own line, in dotted decimal
1864 <A NAME="IDX7496"></A>
1865 <A NAME="IDX7497"></A>
1866 <P><H3><A NAME="Header_480" HREF="auagd002.htm#ToC_480">To set the list of addresses in kernel memory</A></H3>
1868 <P><LI>Become the local superuser <B>root</B> on the machine, if you are not
1869 already, by issuing the <B>su</B> command.
1870 <PRE> % <B>su root</B>
1871 Password: <VAR>root_password</VAR>
1873 <P><LI>Issue the <B>fs setclientaddrs</B> command to replace the list of
1874 addresses currently in kernel memory with a new list.
1875 <PRE> # <B>fs setclientaddrs</B> [<B>-address</B> <<VAR>client network interfaces</VAR>><SUP>+</SUP>]
1880 </B><DD>Is an acceptable alias for <B>setclientaddrs</B> (<B>setcl</B> is
1881 the shortest acceptable abbreviation).
1883 </B><DD>Specifies one or more IP addresses in dotted decimal format (hostnames are
1884 not acceptable). Separate each address with one or more spaces.
1887 <HR><H2><A NAME="HDRWQ562" HREF="auagd002.htm#ToC_481">Controlling the Display of Warning and Informational Messages</A></H2>
1888 <A NAME="IDX7498"></A>
1889 <A NAME="IDX7499"></A>
1890 <P>By default, the Cache Manager generates two types of warning and
1891 informational messages:
1893 <P><LI>It sends <I>user messages</I>, which provide user-level status and
1894 warning information, to user screens.
1895 <P><LI>It sends <I>console messages</I>, which provide system-level status
1896 and warning information, to the client machine's designated
1899 <P>You can use the <B>fs messages</B> command to control whether the Cache
1900 Manager displays either type of message, both types, or neither. It is
1901 best not to disable messages completely, because they provide useful
1903 <P>If you want to monitor Cache Manager status and performance more actively,
1904 you can use the <B>afsmonitor</B> program to collect an extensive set of
1905 statistics (it also gathers File Server statistics). If you experience
1906 performance problems, you can use <B>fstrace</B> suite of commands to
1907 gather a low-level trace of Cache Manager operations, which the AFS Support
1908 and Development groups can analyze to help solve your problem. To learn
1909 about both utilities, see <A HREF="auagd013.htm#HDRWQ438">Monitoring and Auditing AFS Performance</A>.
1910 <A NAME="IDX7500"></A>
1911 <A NAME="IDX7501"></A>
1912 <P><H3><A NAME="Header_482" HREF="auagd002.htm#ToC_482">To control the display of warning and status messages</A></H3>
1914 <P><LI>Become the local superuser <B>root</B> on the machine, if you are not
1915 already, by issuing the <B>su</B> command.
1916 <PRE> % <B>su root</B>
1917 Password: <VAR>root_password</VAR>
1919 <P><LI>Issue the <B>fs messages</B> command, using the <B>-show</B>
1920 argument to specify the type of messages to be displayed.
1921 <PRE> # <B>fs messages -show</B> <<B>user</B>|<B>console</B>|<B>all</B>|<B>none</B>>
1926 </B><DD>Is the shortest acceptable abbreviation of <B>messages</B>.
1928 </B><DD>Specifies the types of messages to display. Choose one of the
1929 following values:
1932 </B><DD>Sends user messages to user screens.
1934 </B><DD>Sends console messages to the console.
1936 </B><DD>Sends user messages to user screens and console messages to the console
1937 (the default if the <B>-show</B> argument is omitted).
1939 </B><DD>Disables messages completely.
1943 <HR><H2><A NAME="HDRWQ563" HREF="auagd002.htm#ToC_483">Displaying and Setting the System Type Name</A></H2>
1944 <A NAME="IDX7502"></A>
1945 <A NAME="IDX7503"></A>
1946 <P>The Cache Manager stores the system type name of the local client machine
1947 in kernel memory. It reads in the default value from a hardcoded
1948 definition in the AFS client software.
1949 <P>The Cache Manager uses the system name as a substitute for the
1950 <VAR>@sys</VAR> variable in AFS pathnames. The variable is useful when
1951 creating a symbolic link from the local disk to an AFS directory that houses
1952 binaries for the client machine's system type. Because the
1953 <VAR>@sys</VAR> variable automatically steers the Cache Manager to the
1954 appropriate directory, you can create the same symbolic link on client
1955 machines of different system types. (You can even automate the creation
1956 operation by using the package utility described in <A HREF="auagd016.htm#HDRWQ565">Configuring Client Machines with the package Program</A>.) The link also remains valid when you upgrade the
1957 machine to a new system type.
1958 <P>Configuration is simplest if you use the system type names that AFS
1959 assigns. For a list, see the <I>AFS Release Notes</I>.
1960 <P>To display the system name stored in kernel memory, use the <B>sys</B>
1961 or <B>fs sysname</B> command. To change the name, add the latter
1962 command's <B>-newsys</B> argument.
1963 <A NAME="IDX7504"></A>
1964 <A NAME="IDX7505"></A>
1965 <A NAME="IDX7506"></A>
1966 <A NAME="IDX7507"></A>
1967 <P><H3><A NAME="Header_484" HREF="auagd002.htm#ToC_484">To display the system type name</A></H3>
1969 <P><LI>Issue the <B>fs sysname</B> or <B>sys</B> command.
1970 <PRE> % <B>fs sysname</B>
1975 <P>The output of the <B>fs sysname</B> command has the following
1977 <PRE> Current sysname is '<VAR>system_name</VAR>'
1979 <P>The <B>sys</B> command displays the <VAR>system_name</VAR> string with no
1981 <P><H3><A NAME="Header_485" HREF="auagd002.htm#ToC_485">To change the system type name</A></H3>
1983 <P><LI>Become the local superuser <B>root</B> on the machine, if you are not
1984 already, by issuing the <B>su</B> command.
1985 <PRE> % <B>su root</B>
1986 Password: <VAR>root_password</VAR>
1988 <P><LI>Issue the <B>fs sysname</B> command, using the <B>-newsys</B>
1989 argument to specify the new name.
1990 <PRE> # <B>fs sysname</B> <<VAR>new sysname</VAR>>
1995 </B><DD>Is the shortest acceptable abbreviation of <B>sysname</B>.
1996 <P><DT><B><VAR>new sysname</VAR>
1997 </B><DD>Specifies the new system type name.
2000 <HR><H2><A NAME="HDRWQ564" HREF="auagd002.htm#ToC_486">Enabling Asynchronous Writes</A></H2>
2001 <A NAME="IDX7508"></A>
2002 <A NAME="IDX7509"></A>
2003 <A NAME="IDX7510"></A>
2004 <P>By default, the Cache Manager writes all data to the File Server
2005 immediately and synchronously when an application program closes a
2006 file. That is, the <B>close</B> system call does not return until
2007 the Cache Manager has actually written all of the cached data from the file
2008 back to the File Server. You can enable the Cache Manager to write
2009 files asynchronously by specifying the number of kilobytes of a file that can
2010 remain to be written to the File Server when the Cache Manager returns control
2012 <P>Enabling asynchronous writes can be helpful to users who commonly work with
2013 very large files, because it usually means that the application appears to
2014 perform faster. However, it introduces some complications. It is
2015 best not to enable asynchronous writes unless the machine's users are
2016 sophisticated enough to understand the potential problems and how to avoid
2017 them. The complications include the following:
2019 <P><LI>In most cases, the Cache Manager returns control to applications earlier
2020 than it does by default, but it is not guaranteed to do so. Users
2021 cannot always expect faster performance.
2022 <P><LI>If an asynchronous write fails, there is no way to notify the application,
2023 because the <B>close</B> system call has already returned with a code
2025 <P><LI>Asynchronous writing increases the possibility that the user fails to
2026 notice when a write operation makes a volume exceed its quota. As
2027 always, the portion of the file that exceeds the quota is lost, as indicated
2028 by a message like the following:
2029 <PRE> No space left on device
2031 <P>To avoid losing data because of insufficient quota, before closing a file
2032 users must verify that the volume housing the file has enough free space to
2035 <P>When you enable asynchronous writes by issuing the <B>fs
2036 storebehind</B> command, you set the number of kilobytes of a file that can
2037 still remain to be written to the File Server when the Cache Manager returns
2038 control to the application program. You can apply the setting either to
2039 all files manipulated by applications running on the machine, or only to
2042 <P><LI>The setting that applies to all files is called the <I>default store
2043 asynchrony</I> for the machine, and persists until the machine
2044 reboots. If, for example, you set the default store asynchrony to 10
2045 KB, it means that when an application closes a file, the Cache Manager can
2046 return control to the application as soon as no more than 10 KB of a file that
2047 the application has closed remain to be written to the File Server.
2048 <P><LI>The setting for an individual file overrides the default store asynchrony
2049 and persists as long as there is an entry for the file in the internal table
2050 that the Cache Manager uses to track information about files. In
2051 general, such an entry persists at least until an application closes the file
2052 or exits completely, but the Cache Manager is free to recycle the entry if the
2053 file is inactive and it needs to free up slots in the table. To be sure
2054 the entry exists in the table, issue the <B>fs storebehind</B> command
2055 shortly before closing the file.
2057 <A NAME="IDX7511"></A>
2058 <A NAME="IDX7512"></A>
2059 <P><H3><A NAME="Header_487" HREF="auagd002.htm#ToC_487">To set the default store asynchrony</A></H3>
2061 <P><LI>Become the local superuser <B>root</B> on the machine, if you are not
2062 already, by issuing the <B>su</B> command.
2063 <PRE> % <B>su root</B>
2064 Password: <VAR>root_password</VAR>
2066 <P><LI>Issue the <B>fs storebehind</B> command with the <B>-allfiles</B>
2068 <PRE> # <B>fs storebehind -allfiles</B> <<VAR>new default (KB)</VAR>> [<B>-verbose</B>]
2073 </B><DD>Is the shortest acceptable abbreviation of <B>storebehind</B>.
2075 </B><DD>Sets the number of kilobytes of data that can remain to be written to the
2076 File Server when the Cache Manager returns control to the application that
2079 </B><DD>Produces a message that confirms the new setting.
2082 <A NAME="IDX7513"></A>
2083 <A NAME="IDX7514"></A>
2084 <P><H3><A NAME="Header_488" HREF="auagd002.htm#ToC_488">To set the store asynchrony for one or more files</A></H3>
2086 <P><LI>Verify that you have the <B>w</B> (<B>write</B>) permission on the
2087 access control list (ACL) of each file for which you are setting the store
2088 asynchrony, by issuing the <B>fs listacl</B> command, which is described
2089 fully in <A HREF="auagd020.htm#HDRWQ787">Displaying ACLs</A>.
2090 <PRE> % <B>fs listacl</B> <VAR>dir/file path</VAR>
2092 <P>Alternatively, become the local superuser <B>root</B> on the client
2093 machine, if you are not already, by issuing the <B>su</B> command.
2094 <PRE> % <B>su root</B>
2095 Password: <VAR>root_password</VAR>
2097 <P><LI>Issue the <B>fs storebehind</B> command with the <B>-kbytes</B>
2098 and <B>-files</B> arguments.
2099 <PRE> # <B>fs storebehind -kbytes</B> <<VAR>asynchrony for specified names</VAR>> \
2100 <B>-files</B> <<VAR>specific pathnames</VAR>><SUP>+</SUP> \
2106 </B><DD>Is the shortest acceptable abbreviation of <B>storebehind</B>.
2108 </B><DD>Sets the number of kilobytes of data that can remain to be written to the
2109 File Server when the Cache Manager returns control to the application that
2110 closed a file named by the <B>-files</B> argument.
2112 </B><DD>Specifies each file for which to set a store asynchrony that overrides the
2113 default. Partial pathnames are interpreted relative to the current
2116 </B><DD>Produces a message that confirms that new setting.
2119 <A NAME="IDX7515"></A>
2120 <A NAME="IDX7516"></A>
2121 <P><H3><A NAME="Header_489" HREF="auagd002.htm#ToC_489">To display the default store asynchrony</A></H3>
2123 <P><LI>Issue the <B>fs storebehind</B> command with no arguments, or with the
2124 <B>-verbose</B> flag only.
2125 <PRE> % <B>fs storebehind </B> [<B>-verbose</B>]
2130 </B><DD>Is the shortest acceptable abbreviation of <B>storebehind</B>.
2132 </B><DD>Produces output that reports the default store asynchrony.
2135 <A NAME="IDX7517"></A>
2136 <A NAME="IDX7518"></A>
2137 <P><H3><A NAME="Header_490" HREF="auagd002.htm#ToC_490">To display the store asynchrony for one or more files</A></H3>
2139 <P><LI>Issue the <B>fs storebehind</B> command with the <B>-files</B>
2141 <PRE> % <B>fs storebehind</B> <B>-files</B> <<VAR>specific pathnames</VAR>><SUP>+</SUP>
2146 </B><DD>Is the shortest acceptable abbreviation of <B>storebehind</B>.
2148 </B><DD>Specifies each file for which to display the store asynchrony.
2149 Partial pathnames are interpreted relative to the current working
2153 <P>The output lists each file separately. If a value has previously
2154 been set for the specified files, the output reports the following:
2155 <PRE> Will store up to <VAR>y</VAR> kbytes of <VAR>file</VAR> asynchronously.
2156 Default store asynchrony is <VAR>x</VAR> kbytes.
2158 <P>If the default store asynchrony applies to a file (because you have not set
2159 a <B>-kbytes</B> value for it), the output reports the following:
2160 <PRE> Will store <VAR>file</VAR> according to default.
2161 Default store asynchrony is <VAR>x</VAR> kbytes.
2163 <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>
2164 <!-- Begin Footer Records ========================================== -->
2166 <br>© <A HREF="http://www.ibm.com/">IBM Corporation 2000.</A> All Rights Reserved
2168 <!-- End Footer Records ============================================ -->
2169 <A NAME="Bot_Of_Page"></A>
git://git.openafs.org / openafs.git / blob