1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 4//EN">
3 <TITLE>Administration Reference</TITLE>
4 <!-- Begin Header Records ========================================== -->
5 <!-- /tmp/idwt3672/auarf000.scr converted by idb2h R4.2 (359) ID -->
6 <!-- Workbench Version (AIX) on 3 Oct 2000 at 16:18:30 -->
7 <META HTTP-EQUIV="updated" CONTENT="Tue, 03 Oct 2000 16:18:29">
8 <META HTTP-EQUIV="review" CONTENT="Wed, 03 Oct 2001 16:18:29">
9 <META HTTP-EQUIV="expires" CONTENT="Thu, 03 Oct 2002 16:18:29">
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 Reference</H1>
16 <HR><P ALIGN="center"> <A HREF="../index.htm"><IMG SRC="../books.gif" BORDER="0" ALT="[Return to Library]"></A> <A HREF="auarf002.htm#ToC"><IMG SRC="../toc.gif" BORDER="0" ALT="[Contents]"></A> <A HREF="auarf057.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="auarf059.htm"><IMG SRC="../next.gif" BORDER="0" ALT="[Next Topic]"></A> <A HREF="auarf284.htm#HDRINDEX"><IMG SRC="../index.gif" BORDER="0" ALT="[Index]"></A> <P>
18 <H2><A NAME="HDRAFSD" HREF="auarf002.htm#ToC_72">afsd</A></H2>
19 <A NAME="IDX4184"></A>
20 <A NAME="IDX4185"></A>
21 <A NAME="IDX4186"></A>
22 <A NAME="IDX4187"></A>
23 <A NAME="IDX4188"></A>
24 <A NAME="IDX4189"></A>
25 <A NAME="IDX4190"></A>
26 <A NAME="IDX4191"></A>
27 <P><STRONG>Purpose</STRONG>
28 <P>Initializes the Cache Manager and starts related daemons.
29 <P><STRONG>Synopsis</STRONG>
30 <PRE><B>afsd</B> [-<B>blocks</B> <<VAR>1024 byte blocks in cache</VAR>>]
31 [<B>-files</B> <<VAR>files in cache</VAR>>]
32 [<B>-rootvol</B> <<VAR>name of AFS root volume</VAR>>]
33 [<B>-stat</B> <<VAR>number of stat entries</VAR>>]
34 [<B>-memcache</B>] [<B>-cachedir</B> <<VAR>cache directory</VAR>>]
35 [<B>-mountdir</B> <<VAR>mount location</VAR>>]
36 [<B>-daemons</B> <<VAR>number of daemons to use</VAR>>]
37 [<B>-nosettime</B>] [<B>-verbose</B>] [<B>-rmtsys</B>] [<B>-debug</B>]
38 [<B>-chunksize</B> <<VAR>log(2) of chunk size</VAR>>]
39 [<B>-dcache</B> <<VAR>number of dcache entries</VAR>>]
40 [<B>-volumes</B> <<VAR>number of volume entries</VAR>>]
41 [<B>-biods</B> <<VAR>number of bkg I/O daemons (aix vm)</VAR>>]
42 [<B>-prealloc</B> <<VAR>number of 'small' preallocated blocks</VAR>>]
43 [<B>-confdir</B> <<VAR>configuration directory</VAR>>]
44 [<B>-logfile</B> <<VAR>Place to keep the CM log</VAR>>]
45 [<B>-waitclose</B>] [<B>-shutdown</B>] [<B>-enable_peer_stats</B>]
46 [<B>-enable_process_stats</B>] [<B>-help</B>]
48 <P>This command does not use the syntax conventions of the AFS command
49 suites. Provide the command name and all option names in full.
50 <P><STRONG>Description</STRONG>
51 <P>The <B>afsd</B> command initializes the Cache Manager on an AFS client
52 machine by transferring AFS-related configuration information into kernel
53 memory and starting several daemons. More specifically, the
54 <B>afsd</B> command performs the following actions:
56 <P><LI>Sets a field in kernel memory that defines the machine's cell
57 membership. Some Cache Manager-internal operations and system calls
58 consult this field to learn which cell to execute in. (The AFS command
59 interpreters refer to the <B>/usr/vice/etc/ThisCell</B> file
60 instead.) This information is transferred into the kernel from the
61 <B>/usr/vice/etc/ThisCell</B> file and cannot be changed until the
62 <B>afsd</B> program runs again.
63 <P><LI>Places in kernel memory the names and Internet addresses of the database
64 server machines in the local cell and (optionally) foreign cells. The
65 appearance of a cell's database server machines in this list enables the
66 Cache Manager to contact them and to access files in the cell. Omission
67 of a cell from this list, or incorrect information about its database server
68 machines, prevents the Cache Manager from accessing files in it.
69 <P>The list of database server machines is transferred into the kernel from
70 the <B>/usr/vice/etc/CellServDB</B> file. After initialization, use
71 the <B>fs newcell</B> command to change the kernel-resident list without
73 <P><LI>Mounts the root of the AFS filespace on a directory on the machine's
74 local disk, according to either the first field in the
75 <B>/usr/vice/etc/cacheinfo</B> file (the default) or the <B>afsd</B>
76 command's <B>-mountdir</B> argument. The conventional value is
78 <P><LI>Determines which volume to mount at the root of the AFS file tree.
79 The default is the volume <B>root.afs</B>; use the
80 <B>-rootvol</B> argument to override it. Although the base
81 (read/write) form of the volume name is the appropriate value, the Cache
82 Manager has a bias for accessing the read-only version of the volume (by
83 convention, <B>root.afs.readonly</B>) if it is
85 <P><LI>Configures the cache on disk (the default) or in machine memory if the
86 <B>-memcache</B> argument is provided. In the latter case, the
87 <B>afsd</B> program allocates space in machine memory for caching, and the
88 Cache Manager uses no disk space for caching even if the machine has a
90 <P><LI>Defines the name of the local disk directory devoted to caching, when the
91 <B>-memcache</B> argument is not used. If necessary, the
92 <B>afsd</B> program creates the directory (its parent directory must
93 already exist). It does not remove the directory that formerly served
94 this function, if one exists.
95 <P>The second field in the <B>/usr/vice/etc/cacheinfo</B> file is the
96 source for this name, and the standard value is the <B>/usr/vice/cache</B>
97 directory. Use the <B>-cachedir</B> argument to override the value
98 in the <B>cacheinfo</B> file.
99 <P><LI>Sets the size of the cache. The default source for the value is the
100 third field in the <B>/usr/vice/etc/cacheinfo</B> file, which specifies a
102 <P>For a memory cache, the following arguments to the <B>afsd</B> command
103 override the value in the <B>cacheinfo</B> file:
105 <P><LI>The <B>-blocks</B> argument, to specify a different number of kilobyte
107 <P><LI>The <B>-dcache</B> and <B>-chunksize</B> arguments together, to
108 set both the number of dcache entries and the chunk size (see below for
109 definition of these parameters). In this case, the <B>afsd</B>
110 program derives cache size by multiplying the two values. Using this
111 combination is not recommended, as it requires the issuer to perform the
112 calculation beforehand to determine the resulting cache size.
113 <P><LI>The <B>-dcache</B> argument by itself. In this case, the
114 <B>afsd</B> program derives cache size by multiplying the value specified
115 by the <B>-dcache</B> argument by the default memory cache chunk size of
116 eight kilobytes. Using this argument is not recommended, as it requires
117 the issuer to perform the calculation beforehand to determine the resulting
120 <P>For satisfactory memory cache performance, the specified value must leave
121 enough memory free to accommodate all other processes and commands that can
122 run on the machine. If the value exceeds the amount of memory
123 available, the <B>afsd</B> program exits without initializing the Cache
124 Manager and produces the following message on the standard output
126 <PRE> afsd: memCache allocation failure at <VAR>number</VAR> KB
129 <P>where <VAR>number</VAR> is how many kilobytes were allocated just before the
131 <P>For a disk cache, use the <B>-blocks</B> argument to the
132 <B>afsd</B> command to override the value in the <B>cacheinfo</B>
133 file. The value specified in either way sets an absolute upper limit on
134 cache size; values provided for other arguments (such as
135 <B>-dcache</B> and <B>-chunksize</B>) never result in a larger
136 cache. The <B>afsd</B> program rejects any setting larger than 95%
137 of the partition size, and exits after generating an error message on the
138 standard output stream, because the cache implementation itself requires a
139 small amount of disk space and overfilling the partition can cause the client
141 <P>To change the size of a disk cache after initialization without rebooting,
142 use the <B>fs setcachesize</B> command; the setting persists until
143 the <B>afsd</B> command runs again or the <B>fs setcachesize</B>
144 command is reissued. The <B>fs setcachesize</B> command does not
145 work for memory caches.
146 <P><LI>Sets the size of each cache <VAR>chunk</VAR>, and by implication the amount
147 of data that the Cache Manager requests at a time from the File Server (how
148 much data per fetch RPC, since AFS uses partial file transfer).
149 <P>For a disk cache, a chunk is a <B>V</B><VAR>n</VAR> file and this
150 parameter sets the maximum size to which each one can expand; the default
151 is 64 KB. For a memory cache, each chunk is a collection of contiguous
152 memory blocks; the default is size is 8 KB.
153 <P>To override the default chunk size for either type of cache, use the
154 <B>-chunksize</B> argument to provide an integer to be used as an exponent
155 of two; see the <B>Options</B> section for details. For a
156 memory cache, if total cache size divided by chunk size leaves a remainder,
157 the <B>afsd</B> program rounds down the number of dcache entries,
158 resulting in a slightly smaller cache.
159 <P><LI>Sets the number of chunks in the cache. For a memory cache, the
160 number of chunks is equal to the cache size divided by the chunk size.
161 For a disk cache, the number of chunks (<B>V</B><VAR>n</VAR> files) is set
162 to the largest of the following unless the <B>-files</B> argument is used
163 to set the value explicitly:
166 <P><LI>1.5 times the result of dividing cache size by chunk size
167 (<VAR>cachesize</VAR>/<VAR>chunksize</VAR> * 1.5)
168 <P><LI>The result of dividing cachesize by 10 KB (<VAR>cachesize</VAR>/10240)
170 <P><LI>Sets the number of <VAR>dcache entries</VAR> allocated in machine memory for
171 storing information about the chunks in the cache.
172 <P>For a disk cache, the <B>/usr/vice/cache/CacheItems</B> file contains
173 one entry for each <B>V</B><VAR>n</VAR> file. By default, one half
174 the number of these entries (but not more that 2,000) are duplicated as dcache
175 entries in machine memory for quicker access.
176 <P>For a memory cache, there is no <B>CacheItems</B> file so all
177 information about cache chunks must be in memory as dcache entries.
178 Thus, there is no default number of dcache entries for a memory cache;
179 instead, the <B>afsd</B> program derives it by dividing the cache size by
181 <P>To set the number of dcache entries, use the <B>-dcache</B>
182 argument; the specified value can exceed the default limit of
183 2,000. Using this argument is not recommended for either type of
184 cache. Increasing the number of dcache entries for a disk cache
185 sometimes improves performance (because more entries are retrieved from memory
186 rather than from disk), but only marginally. Using this argument for a
187 memory cache requires the issuer to calculate the cache size by multiplying
188 this value by the chunk size.
189 <P><LI>Sets the number of <VAR>stat</VAR> entries available in machine memory for
190 caching status information about cached AFS files. The default is
191 300; use the <B>-stat</B> argument to override the default.
192 <P><LI>Randomly selects a file server machine in the local cell as the source for
193 the correct time. Every five minutes thereafter, the local clock is
194 adjusted (if necessary) to match the file server machine's clock.
195 <P>Use the <B>-nosettime</B> flag to prevent the <B>afsd</B> command
196 from selecting a time standard. This is recommended only on file server
197 machines that are also acting as clients. File server machines maintain
198 the correct time using the Network Time Protocol Daemon instead.
200 <P>In addition to setting cache configuration parameters, the <B>afsd</B>
201 program starts the following daemons. (On most system types, these
202 daemons appear as nameless entries in the output of the UNIX <B>ps</B>
205 <P><LI>One <I>callback</I> daemon, which handles callbacks. It also
206 responds to the File Server's periodic probes, which check that the
207 client machine is still alive.
208 <P><LI>One <I>maintenance</I> daemon, which performs the following
211 <P><LI>Garbage collects obsolete data (for example, expired tokens) from kernel
213 <P><LI>Synchronizes files
214 <P><LI>Refreshes information from read-only volumes once per hour
215 <P><LI>Does delayed writes for NFS clients if the machine is running the NFS/AFS
218 <P><LI>One <I>cache-truncation</I> daemon, which flushes the cache when free
219 space is required, by writing cached data and status information to the File
221 <P><LI>One <I>server connection</I> daemon, which sends a probe to the File
222 Server every few minutes to check that it is still accessible. It also
223 synchronizes the machine's clock with the clock on a randomly-chosen file
224 server machine, unless the <B>-nosettime</B> flag is used. There is
225 always one server connection daemon.
226 <P><LI>One or more <I>background</I> daemons that improve performance by
227 pre-fetching files and performing background (delayed) writes of saved data
229 <P>The default number of background daemons is two, enough to service at least
230 five simultaneous users of the machine. To increase the number, use the
231 <B>-daemons</B> argument. A value greater than six is not generally
233 <P><LI>On some system types, one <I>Rx listener</I> daemon, which listens for
235 <P><LI>On some system types, one <I>Rx event</I> daemon, which reviews the Rx
236 system's queue of tasks and performs them as appropriate. Most
237 items in the queue are retransmissions of failed packets.
238 <P><LI>On machines that run AIX with virtual memory (VM) integration, one or more
239 <I>VM</I> daemons (sometimes called <I>I/O</I> daemons, which transfer
240 data between disk and machine memory. The number of them depends on the
241 setting of the <B>-biods</B> and <B>-daemons</B> arguments:
243 <P><LI>If the <B>-biods</B> argument is used, it sets the number of VM
245 <P><LI>If only the <B>-daemons</B> argument is used, the number of VM daemons
246 is twice the number of background daemons.
247 <P><LI>If neither argument is used, there are five VM daemons.
250 <P><STRONG>Cautions</STRONG>
251 <P>Do not use the <B>-shutdown</B> parameter. It does not shutdown
252 the Cache Manager effectively. Instead, halt Cache Manager activity by
253 using the standard UNIX <B>umount</B> command to unmount the AFS root
254 directory (by convention, <B>/afs</B>). The machine must then be
255 rebooted to reinitialize the Cache Manager.
256 <P><STRONG>Options</STRONG>
259 </B><DD>Specifies the number of kilobyte blocks to be made available for caching
260 in the machine's cache directory (for a disk cache) or memory (for a
261 memory cache), overriding the default defined in the third field of the
262 <B>/usr/vice/etc/cacheinfo</B> file. For a disk cache, the value
263 cannot exceed 95% of the space available in the cache partition. If
264 using a memory cache, do not combine this argument with the <B>-dcache</B>
265 argument, since doing so can possibly result in a chunk size that is not an
268 </B><DD>Specifies the number of <B>V</B><VAR>n</VAR> files to create in the
269 cache directory for a disk cache, overriding the default that is calculated as
270 described in the <B>Description</B> section. Each
271 <B>V</B><VAR>n</VAR> file accommodates a chunk of data, and can grow to a
272 maximum size of 64 KB by default. Do not combine this argument with the
273 <B>-memcache</B> argument.
275 </B><DD>Names the read/write volume corresponding to the root directory for the
276 AFS file tree (which is usually the <B>/afs</B> directory). This
277 value overrides the default of the <B>root.afs</B> volume.
279 </B><DD>Specifies the number of entries to allocate in the machine's memory
280 for recording status information about the AFS files in the cache. This
281 value overrides the default of 300.
283 </B><DD>Initializes a memory cache rather than a disk cache. Do not combine
284 this flag with the <B>-files</B> argument.
286 </B><DD>Names the local disk directory to be used as the cache. This value
287 overrides the default defined in the second field of the
288 <B>/usr/vice/etc/cacheinfo</B> file.
290 </B><DD>Names the local disk directory on which to mount the root of the AFS
291 filespace. This value overrides the default defined in the first field
292 of the <B>/usr/vice/etc/cacheinfo</B> file. If a value other than
293 the <B>/afs</B> directory is used, the machine cannot access the filespace
294 of cells that do use that value.
296 </B><DD>Specifies the number of background daemons to run on the machine.
297 These daemons improve efficiency by doing prefetching and background writing
298 of saved data. This value overrides the default of 2, which is adequate
299 for a machine serving up to five users. Values greater than
300 <B>6</B> are not generally more effective than <B>6</B>.
301 <P><B>Note:</B> On AIX machines with integrated virtual memory (VM),
302 the number of VM daemons is set to twice the value of this argument, if it is
303 provided and the <B>-biods</B> argument is not. If both arguments
304 are omitted, there are five VM daemons.
306 </B><DD>Prevents the Cache Manager from synchronizing its clock with the clock on
307 a server machine selected at random, by checking the time on the server
308 machine every five minutes. Use this flag only on a machine that is
309 already using another time synchronization protocol (for example, a server
310 machine that is running the <B>runntp</B> process).
312 </B><DD>Generates a detailed trace of the <B>afsd</B> program's actions
313 on the standard output stream.
315 </B><DD>Initializes an additional daemon to execute AFS-specific system calls on
316 behalf of NFS client machines. Use this flag only if the machine is an
317 NFS/AFS translator machine serving users of NFS client machines who execute
319 <A NAME="IDX4192"></A>
321 </B><DD>Generates a highly detailed trace of the <B>afsd</B> program's
322 actions on the standard output stream. The information is useful mostly
323 for debugging purposes.
325 </B><DD>Sets the size of each cache chunk. The integer provided, which must
326 be from the range <B>0</B> to <B>30</B>, is used as an exponent on the
327 number 2. It overrides the default of 16 for a disk cache
328 (2<SUP>16</SUP> is 64 KB) and 13 for a memory cache (2<SUP>13</SUP> is 8
329 KB). A value of <B>0</B> or less, or greater than <B>30</B>,
330 sets chunk size to the appropriate default. Values less than
331 <B>10</B> (which sets chunk size to a 1 KB) are not recommended.
332 Combining this argument with the <B>-dcache</B> argument is not
333 recommended because it requires that the issuer calculate the cache size that
336 </B><DD>Sets the number of dcache entries in memory, which are used to store
337 information about cache chunks. For a disk cache, this overrides the
338 default, which is 50% of the number of <B>V</B><VAR>n</VAR> files (cache
339 chunks). For a memory cache, this argument effectively sets the number
340 of cache chunks, but its use is not recommended, because it requires the
341 issuer to calculate the resulting total cache size (derived by multiplying
342 this value by the chunk size). Do not combine this argument with the
343 <B>-blocks</B> argument, since doing so can possibly result in a chunk
344 size that is not an exponent of 2.
346 </B><DD>Specifies the number of memory structures to allocate for storing volume
347 location information. The default value is 50.
349 </B><DD>Sets the number of VM daemons dedicated to performing I/O operations on a
350 machine running a version of AIX with virtual memory (VM) integration.
351 If both this argument and the <B>-daemons</B> argument are omitted, the
352 default is five. If this argument is omitted but the
353 <B>-daemons</B> argument is provided, the number of VM daemons is set to
354 twice the value of the <B>-daemons</B> argument.
355 <TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">Provide this argument only on a machine that runs AIX with VM
359 </B><DD>Specifies the number of pieces of memory to preallocate for the Cache
360 Manager's internal use. The default initial value is 400, but the
361 Cache Manager dynamically allocates more memory as it needs it.
363 </B><DD>Names a directory other than the <B>/usr/vice/etc</B> directory from
364 which to fetch the <B>cacheinfo</B>, <B>ThisCell</B>, and
365 <B>CellServDB</B> configuration files.
367 </B><DD>Is obsolete and has no real effect. It specifies an alternate file
368 in which to record a type of trace that the Cache Manager no longer
369 generates; the default value is <B>/usr/vice/etc/AFSLog</B>.
371 </B><DD>Has no effect on the operation of the Cache Manager. The behavior
372 it affected in previous versions of the Cache Manager, to perform synchronous
373 writes to the File Server, is now the default behavior. To perform
374 asynchronous writes in certain cases, use the <B>fs storebehind</B>
377 </B><DD>Shuts down the Cache Manager, but not in the most effective possible
378 way. Do not use this flag.
379 <P><DT><B>-enable_peer_stats
380 </B><DD>Activates the collection of Rx statistics and allocates memory for their
381 storage. For each connection with a specific UDP port on another
382 machine, a separate record is kept for each type of RPC (FetchFile, GetStatus,
383 and so on) sent or received. To display or otherwise access the
384 records, use the Rx Monitoring API.
385 <P><DT><B>-enable_process_stats
386 </B><DD>Activates the collection of Rx statistics and allocates memory for their
387 storage. A separate record is kept for each type of RPC (FetchFile,
388 GetStatus, and so on) sent or received, aggregated over all connections to
389 other machines. To display or otherwise access the records, use the Rx
392 </B><DD>Prints the online help for this command. All other valid options
395 <P><STRONG>Examples</STRONG>
396 <P>The <B>afsd</B> command is normally included in the machine's AFS
397 initialization file, rather than typed at the command shell prompt. For
398 most disk caches, the appropriate form is
399 <PRE> /usr/vice/etc/afsd
402 <P>The following command is appropriate when enabling a machine to act as an
403 NFS/AFS Translator machine serving more than five users.
404 <PRE> /usr/vice/etc/afsd -daemons 4 -rmtsys
407 <P>The following command initializes a memory cache and sets chunk size to 16
409 <PRE> /usr/vice/etc/afsd -memcache -chunksize 14
412 <P><STRONG>Privilege Required</STRONG>
413 <P>The issuer must be logged in as the local superuser <B>root</B>.
414 <P><STRONG>Related Information</STRONG>
415 <P><A HREF="auarf017.htm#HDRCACHEITEMS">CacheItems</A>
416 <P><A HREF="auarf019.htm#HDRCLI_CSDB">CellServDB (client version)</A>
417 <P><A HREF="auarf032.htm#HDRCLI_THISCELL">ThisCell (client version)</A>
418 <P><A HREF="auarf036.htm#HDRVN">V<I>n</I></A>
419 <P><A HREF="auarf043.htm#HDRCACHEINFO">cacheinfo</A>
420 <A NAME="IDX4193"></A>
421 <A NAME="IDX4194"></A>
422 <A NAME="IDX4195"></A>
423 <A NAME="IDX4196"></A>
424 <A NAME="IDX4197"></A>
426 <HR><P ALIGN="center"> <A HREF="../index.htm"><IMG SRC="../books.gif" BORDER="0" ALT="[Return to Library]"></A> <A HREF="auarf002.htm#ToC"><IMG SRC="../toc.gif" BORDER="0" ALT="[Contents]"></A> <A HREF="auarf057.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="auarf059.htm"><IMG SRC="../next.gif" BORDER="0" ALT="[Next Topic]"></A> <A HREF="auarf284.htm#HDRINDEX"><IMG SRC="../index.gif" BORDER="0" ALT="[Index]"></A> <P>
427 <!-- Begin Footer Records ========================================== -->
429 <br>© <A HREF="http://www.ibm.com/">IBM Corporation 2000.</A> All Rights Reserved
431 <!-- End Footer Records ============================================ -->
432 <A NAME="Bot_Of_Page"></A>