1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 4//EN">
3 <TITLE>Administration Guide</TITLE>
4 <!-- Begin Header Records ========================================== -->
5 <!-- /tmp/idwt3570/auagd000.scr converted by idb2h R4.2 (359) ID -->
6 <!-- Workbench Version (AIX) on 2 Oct 2000 at 11:42:14 -->
7 <META HTTP-EQUIV="updated" CONTENT="Mon, 02 Oct 2000 11:42:13">
8 <META HTTP-EQUIV="review" CONTENT="Tue, 02 Oct 2001 11:42:13">
9 <META HTTP-EQUIV="expires" CONTENT="Wed, 02 Oct 2002 11:42:13">
11 <!-- (C) IBM Corporation 2000. All Rights Reserved -->
12 <BODY bgcolor="ffffff">
13 <!-- End Header Records ============================================ -->
14 <A NAME="Top_Of_Page"></A>
15 <H1>Administration Guide</H1>
16 <HR><P ALIGN="center"> <A HREF="../index.htm"><IMG SRC="../books.gif" BORDER="0" ALT="[Return to Library]"></A> <A HREF="auagd002.htm#ToC"><IMG SRC="../toc.gif" BORDER="0" ALT="[Contents]"></A> <A HREF="auagd012.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="auagd014.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>
17 <HR><H1><A NAME="HDRWQ323" HREF="auagd002.htm#ToC_360">Monitoring and Auditing AFS Performance</A></H1>
18 <A NAME="IDX7094"></A>
19 <A NAME="IDX7095"></A>
20 <A NAME="IDX7096"></A>
21 <A NAME="IDX7097"></A>
22 <A NAME="IDX7098"></A>
23 <A NAME="IDX7099"></A>
24 <A NAME="IDX7100"></A>
25 <A NAME="IDX7101"></A>
26 <P>AFS comes with three main monitoring tools:
28 <P><LI>The <B>scout</B> program, which monitors and gathers statistics on
29 File Server performance.
30 <P><LI>The <B>fstrace</B> command suite, which traces Cache Manager
32 <P><LI>The <B>afsmonitor</B> program, which monitors and gathers statistics
33 on both the File Server and the Cache Manager.
35 <P>AFS also provides a tool for auditing AFS events on file server machines
37 <HR><H2><A NAME="HDRWQ324" HREF="auagd002.htm#ToC_361">Summary of Instructions</A></H2>
38 <P>This chapter explains how to perform the following tasks by
39 using the indicated commands:
43 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Initialize the <B>scout</B> program
44 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>scout</B>
46 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Display information about a trace log
47 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>fstrace lslog</B>
49 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Display information about an event set
50 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>fstrace lsset</B>
52 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Change the size of a trace log
53 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>fstrace setlog</B>
55 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Set the state of an event set
56 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>fstrace setset</B>
58 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Dump contents of a trace log
59 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>fstrace dump</B>
61 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Clear a trace log
62 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>fstrace clear</B>
64 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Initialize the <B>afsmonitor</B> program
65 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>afsmonitor</B>
67 <HR><H2><A NAME="HDRWQ326" HREF="auagd002.htm#ToC_362">Using the scout Program</A></H2>
68 <A NAME="IDX7102"></A>
69 <P>The <B>scout</B> program monitors the status of the File Server process
70 running on file server machines. It periodically collects statistics
71 from a specified set of File Server processes, displays them in a graphical
72 format, and alerts you if any of the statistics exceed a configurable
74 <P>More specifically, the <B>scout</B> program includes the following
77 <P><LI>You can monitor, from a single location, the File Server process on any
78 number of server machines from the local and foreign cells. The number
79 is limited only by the size of the display window, which must be large enough
80 to display the statistics.
81 <P><LI>You can set a threshold for many of the statistics. When the value
82 of a statistic exceeds the threshold, the <B>scout</B> program highlights
83 it (displays it in reverse video) to draw your attention to it. If the
84 value goes back under the threshold, the highlighting is deactivated.
85 You control the thresholds, so highlighting reflects what you consider to be a
86 noteworthy situation. See <A HREF="#HDRWQ332">Highlighting Significant Statistics</A>.
87 <P><LI>The <B>scout</B> program alerts you to File Server process, machine,
88 and network outages by highlighting the name of each machine that does not
89 respond to its probe, enabling you to respond more quickly.
90 <P><LI>You can set how often the <B>scout</B> program collects statistics
91 from the File Server processes.
93 <P><H3><A NAME="HDRWQ327" HREF="auagd002.htm#ToC_363">System Requirements</A></H3>
94 <A NAME="IDX7103"></A>
95 <A NAME="IDX7104"></A>
96 <A NAME="IDX7105"></A>
97 <A NAME="IDX7106"></A>
98 <A NAME="IDX7107"></A>
99 <A NAME="IDX7108"></A>
100 <A NAME="IDX7109"></A>
101 <P>The <B>scout</B> program runs on any AFS client machine that has access
102 to the <B>curses</B> graphics package, which most UNIX distributions
103 include as a standard utility. It can run on both dumb terminals and
104 under windowing systems that emulate terminals, but the output looks best on
105 machines that support reverse video and cursor addressing. For best
106 results, set the TERM environment variable to the correct terminal type, or
107 one with characteristics similar to the actual ones. For machines
108 running AIX, the recommended TERM setting is <B>vt100</B>, assuming the
109 terminal is similar to that. For other operating systems, the wider
110 range of acceptable values includes <B>xterm</B>, <B>xterms</B>,
111 <B>vt100</B>, <B>vt200</B>, and <B>wyse85</B>.
112 <A NAME="IDX7110"></A>
113 <P>No privilege is required to run the <B>scout</B> program, so any user
114 who can access the directory where its binary resides (the
115 <B>/usr/afsws/bin</B> directory in the conventional configuration) can use
116 it. The program's probes for collecting statistics do not impose a
117 significant burden on the File Server process, but you can restrict its use by
118 placing the binary file in a directory with a more restrictive access control
120 <P>Multiple instances of the <B>scout</B> program can run on a single
121 client machine, each over its own dedicated connection (in its own
122 window). It must run in the foreground, so the window in which it runs
123 does not accept further input except for an interrupt signal.
124 <P>You can also run the <B>scout</B> program on several machines and view
125 its output on a single machine, by opening telnet connections to the other
126 machines from the central one and initializing the program in each remote
127 window. In this case, you can include the <B>-host</B> flag to the
128 <B>scout</B> command to make the name of each remote machine appear in the
129 <I>banner line</I> at the top of the window displaying its output.
130 See <A HREF="#HDRWQ330">The Banner Line</A>.
131 <P><H3><A NAME="HDRWQ328" HREF="auagd002.htm#ToC_364">Using the -basename argument to Specify a Domain Name</A></H3>
132 <A NAME="IDX7111"></A>
133 <A NAME="IDX7112"></A>
134 <P>As previously mentioned, the <B>scout</B> program can monitor the File
135 Server process on any number of file server machines. If all of the
136 machines belong to the same cell, then their hostnames probably all have the
137 same domain name suffix, such as <B>abc.com</B> in the ABC
138 Corporation cell. In this case, you can use the <B>-basename</B>
139 argument to the <B>scout</B> command, which has several advantages:
141 <P><LI>You can omit the domain name suffix as you enter each file server
142 machine's name on the command line. The <B>scout</B> program
143 automatically appends the domain name to each machine's name, resulting
144 in a fully-qualified hostname. You can omit the domain name suffix even
145 when you don't include the <B>-basename</B> argument, but in that
146 case correct resolution of the name depends on the state of your cell's
147 naming service at the time of connection.
148 <P><LI>The machine names are more likely to fit in the appropriate column of the
149 display without having to be truncated (for more on truncating names in the
150 display column, see <A HREF="#HDRWQ331">The Statistics Display Region</A>).
151 <P><LI>The domain name appears in the banner line at the top of the display
152 window to indicate the name of the cell you are monitoring.
154 <P><H3><A NAME="HDRWQ329" HREF="auagd002.htm#ToC_365">The Layout of the scout Display</A></H3>
155 <A NAME="IDX7113"></A>
156 <A NAME="IDX7114"></A>
157 <P>The <B>scout</B> program can display statistics either in a dedicated
158 window or on a plain screen if a windowing environment is not
159 available. For best results, use a window or screen that can print in
160 reverse video and do cursor addressing.
161 <P>The <B>scout</B> program screen has three main regions: the
162 <I>banner line</I>, the <I>statistics display region</I> and the
163 <I>probe/message line</I>. This section describes their contents,
164 and graphic examples appear in <A HREF="#HDRWQ336">Example Commands and Displays</A>.
165 <P><H4><A NAME="HDRWQ330">The Banner Line</A></H4>
166 <A NAME="IDX7115"></A>
167 <A NAME="IDX7116"></A>
168 <P>By default, the string <TT>scout</TT> appears in the banner line at the
169 top of the window or screen, to indicate that the <B>scout</B> program is
170 running. You can display two additional types of information by include
171 the appropriate option on the command line:
173 <P><LI>Include the <B>-host</B> flag to display the local machine's name
174 in the banner line. This is particularly useful when you are running
175 the <B>scout</B> program on several machines but displaying the results on
177 <P>For example, the following banner line appears when you run the
178 <B>scout</B> program on the machine
179 <B>client1.abc.com</B> and use the<B>-host</B>
181 <PRE> [client1.abc.com] scout
183 <P><LI>Include the <B>-basename</B> argument to display the specified cell
184 domain name in the banner line. For further discussion, see <A HREF="#HDRWQ328">Using the -basename argument to Specify a Domain Name</A>.
185 <P>For example, if you specify a value of <B>abc.com</B> for the
186 <B>-basename</B> argument, the banner line reads:
187 <PRE> scout for abc.com
190 <P><H4><A NAME="HDRWQ331">The Statistics Display Region</A></H4>
191 <A NAME="IDX7117"></A>
192 <A NAME="IDX7118"></A>
193 <P>The statistics display region occupies most of the window and is divided
194 into six columns. The following list describes them as they appear from
195 left to right in the window.
197 <P><DT><B><TT>Conn</TT>
198 <A NAME="IDX7119"></A>
199 </B><DD>Displays the number of RPC connections open between the File Server
200 process and client machines. This number normally equals or exceeds the
201 number in the fourth <TT>Ws</TT> column. It can exceed the number in
202 that column because each user on the machine can have more than one connection
203 open at once, and one client machine can handle several users.
204 <P><DT><B><TT>Fetch</TT>
205 <A NAME="IDX7120"></A>
206 </B><DD>Displays the number of fetch-type RPCs (fetch data, fetch access list, and
207 fetch status) that the File Server process has received from client machines
208 since it started. It resets to zero when the File Server process
210 <P><DT><B><TT>Store</TT>
211 <A NAME="IDX7121"></A>
212 </B><DD>Displays the number of store-type RPCs (store data, store access list, and
213 store status) that the File Server process has received from client machines
214 since it started. It resets to zero when the File Server process
216 <P><DT><B><TT>Ws</TT>
217 <A NAME="IDX7122"></A>
218 <A NAME="IDX7123"></A>
219 <A NAME="IDX7124"></A>
220 </B><DD>Displays the number of client machines (workstations) that have
221 communicated with the File Server process within the last 15 minutes (such
222 machines are termed <I>active</I>). This number is likely to be
223 smaller than the number in the <TT>Conn</TT>) column because a single client
224 machine can have several connections open to one File Server process.
225 <P><DT><B>[Unlabeled column]
226 </B><DD>Displays the name of the file server machine on which the File Server
227 process is running. It is 12 characters wide. Longer names are
228 truncated and an asterisk (<TT>*</TT>) appears as the last character in the
229 name. If all machines have the same domain name suffix, you can use the
230 <B>-basename</B> argument to decrease the need for truncation; see <A HREF="#HDRWQ328">Using the -basename argument to Specify a Domain Name</A>.
231 <P><DT><B><TT>Disk attn</TT>
232 <A NAME="IDX7125"></A>
233 <A NAME="IDX7126"></A>
234 <A NAME="IDX7127"></A>
235 <A NAME="IDX7128"></A>
236 </B><DD>Displays the number of kilobyte blocks available on up to 26 of the file
237 server machine's AFS server (<B>/vicep</B>) partitions. The
238 display for each partition has the following format:
239 <PRE> <VAR>partition_letter</VAR>:<VAR>free_blocks</VAR>
242 <P>For example, <TT>a:8949</TT> indicates that partition
243 <B>/vicepa</B> has 8,949 KB free. If the window is not wide enough
244 for all partition entries to appear on a single line, the <B>scout</B>
245 program automatically stacks the partition entries into subcolumns within the
247 <P>The label on the <TT>Disk attn</TT> column indicates the threshold value
248 at which entries in the column become highlighted. By default, the
249 <B>scout</B> program highlights a partition that is over 95% full, in
250 which case the label is as follows:
251 <PRE> Disk attn: > 95% used
254 <P>For more on this threshold and its effect on highlighting, see <A HREF="#HDRWQ332">Highlighting Significant Statistics</A>.
256 <P>For all columns except the fifth (file server machine name), you can use
257 the <B>-attention</B> argument to set a threshold value above which the
258 <B>scout</B> program highlights the statistic. By default, only
259 values in the fifth and sixth columns ever become highlighted. For
260 instructions on using the <B>-attention</B> argument, see <A HREF="#HDRWQ332">Highlighting Significant Statistics</A>.
261 <P><H4><A NAME="Header_368">The Probe Reporting Line</A></H4>
262 <A NAME="IDX7129"></A>
263 <A NAME="IDX7130"></A>
264 <P>The bottom line of the display indicates how many times the
265 <B>scout</B> program has probed the File Server processes for
266 statistics. The statistics gathered in the latest probe appear in the
267 statistics display region. By default, the <B>scout</B> program
268 probes the File Servers every 60 seconds, but you can use the
269 <B>-frequency</B> argument to specify a different probe frequency.
270 <P><H3><A NAME="HDRWQ332" HREF="auagd002.htm#ToC_369">Highlighting Significant Statistics</A></H3>
271 <A NAME="IDX7131"></A>
272 <A NAME="IDX7132"></A>
273 <A NAME="IDX7133"></A>
274 <A NAME="IDX7134"></A>
275 <P>To draw your attention to a statistic that currently exceed a threshold
276 value, the <B>scout</B> program displays it in reverse video (highlights
277 it). You can set the threshold value for most statistics, and so
278 determine which values are worthy of special attention and which are
280 <P><H4><A NAME="HDRWQ333">Highlighting Server Outages</A></H4>
281 <A NAME="IDX7135"></A>
282 <A NAME="IDX7136"></A>
283 <A NAME="IDX7137"></A>
284 <A NAME="IDX7138"></A>
285 <A NAME="IDX7139"></A>
286 <P>The only column in which you cannot control highlighting is the fifth,
287 which identifies the file server machine for which statistics are displayed in
288 the other columns. The <B>scout</B> program uses highlighting in
289 this column to indicate that the File Server process on a machine fails to
290 respond to its probe, and automatically blanks out the other columns.
291 Failure to respond to the probe can indicate a File Server process, file
292 server machine, or network outage, so the highlighting draws your attention to
293 a situation that is probably interrupting service to users.
294 <P>When the File Server process once again responds to the probes, its name
295 appears normally and statistics reappear in the other columns. If all
296 machine names become highlighted at once, a possible network outage has
297 disrupted the connection between the file server machines and the client
298 machine running the <B>scout</B> program.
299 <P><H4><A NAME="Header_371">Highlighting for Extreme Statistic Values</A></H4>
300 <P>To set the threshold value for one or more of the five
301 statistics-displaying columns, use the <B>-attention</B> argument.
302 The threshold value applies to all File Server processes you are monitoring
303 (you cannot set different thresholds for different machines). For
304 details, see the syntax description in <A HREF="#HDRWQ335">To start the scout program</A>.
305 <P>It is not possible to change the threshold values for a running
306 <B>scout</B> program. Stop the current program and start a new
307 one. Also, the <B>scout</B> program does not retain threshold
308 values across restarts, so you must specify all thresholds every time you
310 <P><H3><A NAME="HDRWQ334" HREF="auagd002.htm#ToC_372">Resizing the scout Display</A></H3>
311 <A NAME="IDX7140"></A>
312 <A NAME="IDX7141"></A>
313 <A NAME="IDX7142"></A>
314 <P>Do not resize the display window while the <B>scout</B> program is
315 running. Increasing the size does no harm, but the <B>scout</B>
316 program does not necessarily adjust to the new dimensions. Decreasing
317 the display's width can disturb column alignment, making the display
318 harder to read. With any type of resizing, the <B>scout</B> program
319 does not adjust the display in any way until it displays the results of the
321 <P>To resize the display effectively, stop the <B>scout</B> program,
322 resize the window and then restart the program. Even in this case, the
323 <B>scout</B> program's response depends on the accuracy of the
324 information it receives from the display environment. Testing during
325 development has shown that the display environment does not reliably provide
326 information about window resizing. If you use the X windowing system,
327 issuing the following sequence of commands before starting the
328 <B>scout</B> program (or placing them in the shell initialization file)
329 sometimes makes it adjust properly to resizing.
330 <PRE> %<B> set noglob</B>
331 % <B>eval '/usr/bin/X11/resize'</B>
332 % <B>unset noglob</B>
334 <A NAME="IDX7143"></A>
335 <A NAME="IDX7144"></A>
336 <A NAME="IDX7145"></A>
337 <A NAME="IDX7146"></A>
338 <A NAME="IDX7147"></A>
339 <P><H3><A NAME="HDRWQ335" HREF="auagd002.htm#ToC_373">To start the scout program</A></H3>
341 <P><LI>Open a dedicated command shell. If necessary, adjust it to the
343 <P><LI>Issue the <B>scout</B> command to start the program.
344 <PRE> % <B>scout</B> [<B>initcmd</B>] <B>-server</B> <<VAR>FileServer name(s) to monitor</VAR>><SUP>+</SUP> \
345 [<B>-basename</B> <<VAR>base server name</VAR>>] \
346 [<B>-frequency</B> <<VAR>poll frequency, in seconds</VAR>>] [<B>-host</B>] \
347 [<B>-attention</B> <<VAR>specify attention (highlighting) level</VAR>><SUP>+</SUP>] \
348 [<B>-debug</B> <<VAR>turn debugging output on to the named file</VAR>>]
353 </B><DD>Is an optional string that accommodates the command's use of the AFS
354 command parser. It can be omitted and ignored.
356 </B><DD>Identifies each File Server process to monitor, by naming the file server
357 machine it is running on. Provide fully-qualified hostnames unless the
358 <B>-basename</B> argument is used. In that case, specify only the
359 initial part of each machine name, omitting the domain name suffix common to
360 all the machine names.
362 </B><DD>Specifies the domain name suffix common to all of the file server machines
363 named by the <B>-server</B> argument. For discussion of this
364 argument's effects, see <A HREF="#HDRWQ328">Using the -basename argument to Specify a Domain Name</A>.
365 <P>Do not include the period that separates the domain suffix from the initial
366 part of the machine name, but do include any periods that occur within the
367 suffix itself. (For example, in the ABC Corporation cell, the proper
368 value is <B>abc.com</B>, not
371 </B><DD>Sets the frequency, in seconds, of the <B>scout</B> program's
372 probes to File Server processes. Specify an integer greater than 0
373 (zero). The default is 60 seconds.
375 </B><DD>Displays the name of the machine that is running the <B>scout</B>
376 program in the display window's banner line. By default, no
377 machine name is displayed.
379 </B><DD>Defines the threshold value at which to highlight one or more
380 statistics. You can provide the pairs of statistic and threshold in any
381 order, separating each pair and the parts of each pair with one or more
382 spaces. The following list defines the syntax for each
384 <A NAME="IDX7148"></A>
385 <A NAME="IDX7149"></A>
386 <A NAME="IDX7150"></A>
388 <P><DT><B>conn <VAR>connections</VAR>
389 </B><DD>Highlights the value in the <TT>Conn</TT> (first) column when the number
390 of connections that the File Server has open to client machines exceeds the
391 <VAR>connections</VAR> value. The highlighting deactivates when the value
392 goes back below the threshold. There is no default threshold.
393 <P><DT><B>fetch <VAR>fetch_RPCs</VAR>
394 </B><DD>Highlights the value in the <TT>Fetch</TT> (second) column when the
395 number of fetch RPCs that clients have made to the File Server process exceeds
396 the <VAR>fetch_RPCs</VAR> value. The highlighting deactivates only when
397 the File Server process restarts, at which time the value returns to
398 zero. There is no default threshold.
399 <P><DT><B>store <VAR>store_RPCs</VAR>
400 </B><DD>Highlights the value in the <TT>Store</TT> (third) column when the
401 number of store RPCs that clients have made to the File Server process exceeds
402 the <VAR>store_RPCs</VAR> value. The highlighting deactivates only when
403 the File Server process restarts, at which time the value returns to
404 zero. There is no default threshold.
405 <P><DT><B>ws <VAR>active_clients</VAR>
406 </B><DD>Highlights the value in the <TT>Ws</TT> (fourth) column when the number
407 of active client machines (those that have contacted the File Server in the
408 last 15 minutes) exceeds the <VAR>active_clients</VAR> value. The
409 highlighting deactivates when the value goes back below the threshold.
410 There is no default threshold.
411 <P><DT><B>disk <VAR>percent_full</VAR> % or disk <VAR>min_blocks</VAR>
412 </B><DD>Highlights the value for a partition in the <TT>Disk attn</TT> (sixth)
413 column when either the amount of disk space used exceeds the percentage
414 indicated by the<VAR>percent_full</VAR> value, or the number of free KB blocks
415 is less than the <VAR>min_blocks</VAR> value. The highlighting
416 deactivates when the value goes back below the <VAR>percent_full</VAR> threshold
417 or above the <VAR>min_blocks</VAR> threshold.
418 <P>The value you specify appears in the header of the sixth column following
419 the string <TT>Disk attn</TT>. The default threshold is 95%
421 <P>Acceptable values for <VAR>percent_full</VAR> are the integers from the range
422 <B>0</B> (zero) to <B>99</B>, and you must include the percent sign to
423 distinguish this statistic from a <VAR>min_blocks</VAR> value..
425 <P>The following example sets the threshold for the <TT>Conn</TT> column to
426 100, for the <TT>Ws</TT> column to 50, and for the <TT>Disk attn</TT>
427 column to 75%. There is no threshold for the <TT>Fetch</TT> and
428 <TT>Store</TT> columns.
429 <P><B>-attention conn 100 ws 50 disk 75%</B>
430 <P>The following example has the same affect as the previous one except that
431 it sets the threshold for the <TT>Disk attn</TT> column to 5000 free KB
433 <P><B>-attention disk 5000 ws 50 conn 100</B>
435 </B><DD>Enables debugging output and directs it into the specified file.
436 Partial pathnames are interpreted relative to the current working
437 directory. By default, no debugging output is produced.
440 <P><H3><A NAME="Header_374" HREF="auagd002.htm#ToC_374">To stop the scout program</A></H3>
441 <A NAME="IDX7151"></A>
443 <P><LI>Enter <B>Ctrl-c</B> in the display window. This is the proper
444 interrupt signal even if the general interrupt signal in your environment is
447 <P><H3><A NAME="HDRWQ336" HREF="auagd002.htm#ToC_375">Example Commands and Displays</A></H3>
448 <A NAME="IDX7152"></A>
449 <A NAME="IDX7153"></A>
450 <P>This section presents examples of the <B>scout</B> program, combining
451 different arguments and illustrating the screen displays that result.
452 <P>In the first example, an administrator in the ABC Corporation issues the
453 <B>scout</B> command without providing any optional arguments or
454 flags. She includes the <B>-server</B> argument because she is
455 providing multiple machine names. She chooses to specify on the initial
456 part of each machine's name even though she has not used the
457 <B>-basename</B> argument, relying on the cell's name service to
458 obtain the fully-qualified name that the <B>scout</B> program requires for
459 establishing a connection.
460 <PRE> % <B>scout -server fs1 fs2</B>
462 <P><A HREF="#FIGWQ337">Figure 2</A> depicts the resulting display. Notice first that the
463 machine names in the fifth (unlabeled) column appear in the format the
464 administrator used on the command line. Now consider the second line in
465 the display region, where the machine name <TT>fs2</TT> appears in the fifth
466 column. The <TT>Conn</TT> and <TT>Ws</TT> columns together show
467 that machine <B>fs2</B> has 144 RPC connections open to 44 client
468 machines, demonstrating that multiple connections per client machine are
469 possible. The <TT>Fetch</TT> column shows that client machines have
470 made 2,734,278 fetch RPCs to machine <B>fs2</B> since the File Server
471 process last started and the <TT>Store</TT> column shows that they have made
473 <P>Six partition entries appear in the <TT>Disk attn</TT> column, marked
474 <TT>a</TT> through <TT>f</TT> (for <B>/vicepa</B> through
475 <B>/vicepf</B>). They appear on three lines in two subcolumns
476 because of the width of the window; if the window is wider, there are
477 more subcolumns. Four of the partition entries (<TT>a</TT>,
478 <TT>c</TT>, <TT>d</TT>, and <TT>e</TT>) appear in reverse video to
479 indicate that they are more than 95% full (the threshold value that appears in
480 the <TT>Disk attn</TT> header).
481 <P><B><A NAME="FIGWQ337" HREF="auagd003.htm#FT_FIGWQ337">Figure 2. First example scout display</A></B><BR>
482 <TABLE BORDER ><TR><TD><BR>
483 <B><BR><IMG SRC="scout1.gif" ALT="First example scout display"><BR></B><BR>
485 <P>In the second example, the administrator uses more of the <B>scout</B>
486 program's optional arguments.
488 <P><LI>She provides the machine names in the same form as in Example 1, but this
489 time she also uses the <B>-basename</B> argument to specify their domain
490 name suffix, <B>abc.com</B>. This implies that the
491 <B>scout</B> program does not need the name service to expand the names to
492 fully-qualified hostnames, but the name service still converts the hostnames
494 <P><LI>She uses the <B>-host</B> flag to display in the banner line the name
495 of the client machine where the <B>scout</B> program is running.
496 <P><LI>She uses the <B>-frequency</B> argument to changes the probing
497 frequency from its default of once per minute to once every five
499 <P><LI>She uses the <B>-attention</B> argument to changes the highlighting
500 threshold for partitions to a 5000 KB minimum rather than the default of 95%
503 <PRE> % <B>scout -server fs1 fs2 -basename abc.com -host -frequency 5 -attention disk 5000</B>
505 <P>The use of optional arguments results in several differences between <A HREF="#FIGWQ338">Figure 3</A> and <A HREF="#FIGWQ337">Figure 2</A>. First, because the <B>-host</B>
506 flag is included, the banner line displays the name of the machine running the
507 <B>scout</B> process as <TT>[client52]</TT> along with the basename
508 <TT>abc.com</TT> specified with the <B>-basename</B>
510 <P>Another difference is that two rather than four of machine
511 <B>fs2</B>'s partitions appear in reverse video, even though their
512 values are almost the same as in <A HREF="#FIGWQ337">Figure 2</A>. This is because the administrator changed the
513 highlight threshold to a 5000 block minimum, as also reflected in the
514 <TT>Disk attn</TT> column's header. And while machine
515 <B>fs2</B>'s partitions <B>/vicepa</B> and <B>/vicepd</B> are
516 still 95% full, they have more than 5000 free blocks left; partitions
517 <B>/vicepc</B> and <B>/vicepe</B> are highlighted because they have
518 fewer than 5000 blocks free.
519 <P>Note also the result of changing the probe frequency, reflected in the
520 probe reporting line at the bottom left corner of the display. Both
521 this example and the previous one represent a time lapse of one minute after
522 the administrator issues the <B>scout</B> command. In this example,
523 however, the <B>scout</B> program has probed the File Server processes 12
524 times as opposed to once
525 <P><B><A NAME="FIGWQ338" HREF="auagd003.htm#FT_FIGWQ338">Figure 3. Second example scout display</A></B><BR>
526 <TABLE BORDER ><TR><TD><BR>
527 <B><BR><IMG SRC="scout2.gif" ALT="Second example scout display"><BR></B><BR>
529 <P>In <A HREF="#FIGWQ339">Figure 4</A>, an administrator in the State University cell monitors
530 three of that cell's file server machines. He uses the
531 <B>-basename</B> argument to specify the <B>stateu.edu</B>
533 <PRE> % <B>scout -server server2 server3 server4 -basename stateu.edu</B>
535 <P><B><A NAME="FIGWQ339" HREF="auagd003.htm#FT_FIGWQ339">Figure 4. Third example scout display</A></B><BR>
536 <TABLE BORDER ><TR><TD><BR>
537 <B><BR><IMG SRC="scout3.gif" ALT="Third example scout display"><BR></B><BR>
539 <P><A HREF="#FIGWQ340">Figure 5</A> illustrates three of the <B>scout</B> program's
540 features. First, you can monitor file server machines from different
541 cells in a single display: <B>fs1.abc.com</B>,
542 <B>server3.stateu.edu</B>, and
543 <B>sv7.def.com</B>. Because the machines belong to
544 different cells, it is not possible to provide the <B>-basename</B>
546 <P>Second, it illustrates how the display must truncate machine names that do
547 not fit in the fifth column, using an asterisk at the end of the name to show
548 that it is shortened.
549 <P>Third, it illustrates what happens when the <B>scout</B> process cannot
550 reach a File Server process, in this case the one on the machine
551 <B>sv7.def.com</B>: it highlights the machine name and
552 blanks out the values in the other columns.
553 <P><B><A NAME="FIGWQ340" HREF="auagd003.htm#FT_FIGWQ340">Figure 5. Fourth example scout display</A></B><BR>
554 <TABLE BORDER ><TR><TD><BR>
555 <B><BR><IMG SRC="scout4.gif" ALT="Fourth example scout display"><BR></B><BR>
557 <HR><H2><A NAME="HDRWQ341" HREF="auagd002.htm#ToC_376">Using the fstrace Command Suite</A></H2>
558 <P>This section describes the <B>fstrace</B> commands that
559 system administrators employ to trace Cache Manager activity for debugging
560 purposes. It assumes the reader is familiar with the Cache Manager
561 concepts described in <A HREF="auagd015.htm#HDRWQ387">Administering Client Machines and the Cache Manager</A>.
562 <P>The <B>fstrace</B> command suite monitors the internal activity of the
563 Cache Manager and enables you to record, or trace, its operations in
564 detail. The operations, which are termed <I>events</I>, comprise
565 the <B>cm</B> <I>event set</I>. Examples of <B>cm</B>
566 events are fetching files and looking up information for a listing of files
567 and subdirectories using the UNIX <B>ls</B> command.
568 <P>Following are the <B>fstrace</B> commands and their respective
571 <P><LI>The <B>fstrace apropos</B> command provides a short description of
573 <P><LI>The <B>fstrace clear</B> command clears the trace log.
574 <P><LI>The <B>fstrace dump</B> command dumps the contents of the trace
576 <P><LI>The <B>fstrace help</B> command provides a description and syntax for
578 <P><LI>The <B>fstrace lslog</B> command lists information about the trace
580 <P><LI>The <B>fstrace lsset</B> command lists information about the event
582 <P><LI>The <B>fstrace setlog</B> command changes the size of the trace
584 <P><LI>The <B>fstrace setset</B> command sets the state of the event
587 <P><H3><A NAME="HDRWQ342" HREF="auagd002.htm#ToC_377">About the fstrace Command Suite</A></H3>
588 <P>The <B>fstrace</B> command suite replaces and greatly
589 expands the functionality formerly provided by the <B>fs debug</B>
590 command. Its intended use is to aid in diagnosis of specific Cache
591 Manager problems, such as client machine hangs, cache consistency problems,
592 clock synchronization errors, and failures to access a volume or AFS
593 file. Therefore, it is best not to keep <B>fstrace</B> logging
594 enabled at all times, unlike the logging for AFS server processes.
595 <P>Most of the messages in the trace log correspond to low-level Cache Manager
596 operations. It is likely that only personnel familiar with the AFS
597 source code can interpret them. If you have an AFS source license, you
598 can attempt to interpret the trace yourself, or work with the AFS Product
599 Support group to resolve the underlying problems. If you do not have an
600 AFS source license, it is probably more efficient to contact the AFS Product
601 Support group immediately in case of problems. They can instruct you to
602 activate <B>fstrace</B> tracing if appropriate.
603 <P>The log can grow in size very quickly; this can use valuable disk
604 space if you are writing to a file in the local file space.
605 Additionally, if the size of the log becomes too large, it can become
606 difficult to parse the results for pertinent information.
607 <A NAME="IDX7154"></A>
608 <A NAME="IDX7155"></A>
609 <P>When AFS tracing is enabled, each time a <B>cm</B> event occurs, a
610 message is written to the trace log, <B>cmfx</B>. To diagnose a
611 problem, read the output of the trace log and analyze the operations executed
612 by the Cache Manager. The default size of the trace log is 60 KB, but
613 you can increase or decrease it.
614 <A NAME="IDX7156"></A>
615 <A NAME="IDX7157"></A>
616 <P>To use the <B>fstrace</B> command suite, you must first enable tracing
617 and reserve, or allocate, space for the trace log with the <B>fstrace
618 setset</B> command. With this command, you can set the <B>cm</B>
619 event set to one of three states to enable or disable tracing for the event
620 set and to allocate or deallocate space for the trace log in the kernel:
621 <A NAME="IDX7158"></A>
622 <A NAME="IDX7159"></A>
623 <A NAME="IDX7160"></A>
626 </B><DD>Enables tracing for the event set and allocates space for the trace
629 </B><DD>Temporarily disables tracing for the event set; however, the event
630 set continues to allocate space occupied by the log to which it sends
633 </B><DD>Disables tracing for the event set; furthermore, the event set
634 releases the space occupied by the log to which it sends data. When the
635 <B>cm</B> event set that sends data to the <B>cmfx</B> trace log is in
636 this state, the space allocated for that log is freed or deallocated.
638 <A NAME="IDX7161"></A>
639 <A NAME="IDX7162"></A>
640 <A NAME="IDX7163"></A>
641 <P>Both event sets and trace logs can be designated as <I>persistent</I>,
642 which prevents accidental resetting of an event set's state or clearing
643 of a trace log. The designation is made as the kernel is compiled and
645 <P>If an event set such as <B>cm</B> is persistent, you can change its
646 state only by including the <B>-set</B> argument to the <B>fstrace
647 setset</B> command. (That is, you cannot change its state along with
648 the state of all other event sets by issuing the <B>fstrace setset</B>
649 command with no arguments.) Similarly, if a trace log such as
650 <B>cmfx</B> is persistent, you can clear it only by including either the
651 <B>-set</B> or <B>-log</B> argument to the <B>fstrace clear</B>
652 command (you cannot clear it along with all other trace logs by issuing the
653 <B>fstrace clear</B> command with no arguments.)
654 <P>When a problem occurs, set the <B>cm</B> event set to active using the
655 <B>fstrace setset</B> command. When tracing is enabled on a busy
656 AFS client, the volume of events being recorded is significant;
657 therefore, when you are diagnosing problems, restrict AFS activity as much as
658 possible to minimize the amount of extraneous tracing in the log.
659 Because tracing can have a negative impact on system performance, leave
660 <B>cm</B> tracing in the dormant state when you are not diagnosing
662 <P>If a problem is reproducible, clear the <B>cmfx</B> trace log with the
663 <B>fstrace clear</B> command and reproduce the problem. If the
664 problem is not easily reproduced, keep the state of the event set active until
666 <P>To view the contents of the trace log and analyze the <B>cm</B> events,
667 use the <B>fstrace dump</B> command to copy the content lines of the trace
668 log to standard output (stdout) or to a file.
669 <TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">If a particular command or process is causing problems, determine its process
670 id (PID). Search the output of the <B>fstrace dump</B> command for
671 the PID to find only those lines associated with the problem.
673 <P><H3><A NAME="HDRWQ343" HREF="auagd002.htm#ToC_378">Requirements for Using the fstrace Command Suite</A></H3>
674 <A NAME="IDX7164"></A>
675 <A NAME="IDX7165"></A>
676 <P>Except for the <B>fstrace help</B> and <B>fstrace apropos</B>
677 commands, which require no privilege, issuing the <B>fstrace</B> commands
678 requires that the issuer be logged in as the local superuser <B>root</B>
679 on the local client machine. Before issuing an <B>fstrace</B>
680 command, verify that you have the necessary privilege.
681 <P>The Cache Manager catalog must be in place so that logging can
682 occur. The <B>fstrace</B> command suite uses the standard UNIX
683 catalog utilities. The default location is
684 <B>/usr/vice/etc/C/afszcm.cat</B>. It can be placed in
685 another directory by placing the file elsewhere and using the proper NLSPATH
686 and LANG environment variables.
687 <P><H3><A NAME="Header_379" HREF="auagd002.htm#ToC_379">Using fstrace Commands Effectively</A></H3>
688 <P>To use <B>fstrace</B> commands most effectively, configure them as
691 <P><LI>Store the <B>fstrace</B> binary in a local disk directory.
692 <P><LI>When you dump the <B>fstrace</B> log to a file, direct it to one on
694 <P><LI>The trace can grow large in just a few minutes. Before attempting
695 to dump the log to a local file, verify that you have enough room. Be
696 particularly careful if you are using disk quotas on partitions in the local
698 <P><LI>Attempt to limit Cache Manager activity on the AFS client machine other
699 than the problem operation. This reduces the amount of extraneous data
701 <P><LI>Activate the <B>fstrace</B> log for the shortest possibly period of
702 time. If possible activate the trace immediately before performing the
703 problem operation, deactivate it as soon as the operation completes, and dump
704 the trace log to a file immediately.
705 <P><LI>If possible, obtain UNIX process ID (PID) of the command or program that
706 initiates the problematic operation. This enables the person analyzing
707 the trace log to search it for messages associated with the PID.
709 <P><H3><A NAME="HDRWQ344" HREF="auagd002.htm#ToC_380">Activating the Trace Log</A></H3>
710 <P>To start Cache Manager tracing on an AFS client machine, you
713 <P><LI>The <B>cmfx</B> kernel trace log using the <B>fstrace setlog</B>
715 <P><LI>The <B>cm</B> event set using the <B>fstrace setset</B> command
717 <P>The <B>fstrace setlog</B> command sets the size of the <B>cmfx</B>
718 kernel trace log in kilobytes. The trace log occupies 60 kilobytes of
719 kernel by default. If the trace log already exists, it is cleared when
720 this command is issued and a new log of the given size is created.
721 Otherwise, a new log of the desired size is created.
722 <P>The <B>fstrace setset</B> command sets the state of the <B>cm</B>
723 kernel event set. The state of the <B>cm</B> event set determines
724 whether information on the events in that event set is logged.
725 <P>After establishing kernel tracing on the AFS client machine, you can check
726 the state of the event set and the size of the kernel buffer allocated for the
727 trace log. To display information about the state of the <B>cm</B>
728 event set, issue the <B>fstrace lsset</B> command. To display
729 information about the <B>cmfx</B> trace log, use the <B>fstrace
730 lslog</B> command. See the instructions in <A HREF="#HDRWQ346">Displaying the State of a Trace Log or Event Set</A>.
731 <A NAME="IDX7166"></A>
732 <A NAME="IDX7167"></A>
733 <A NAME="IDX7168"></A>
734 <A NAME="IDX7169"></A>
735 <P><H3><A NAME="Header_381" HREF="auagd002.htm#ToC_381">To configure the trace log</A></H3>
737 <P><LI>Become the local superuser <B>root</B> on the machine, if you are not
738 already, by issuing the <B>su</B> command.
739 <PRE> % <B>su root</B>
740 Password: <VAR>root_password</VAR>
742 <P><LI>Issue the <B>fstrace setlog</B> command to set the size of the
743 <B>cmfx</B> kernel trace log.
744 <PRE> # <B>fstrace setlog</B> [<B>-log</B> <<VAR>log_name</VAR>><SUP>+</SUP>] <B>-buffersize</B> <<VAR>1-kilobyte_units</VAR>>
747 <P>The following example sets the size of the <B>cmfx</B> trace log to 80
749 <PRE> # <B>fstrace setlog cmfx 80</B>
751 <A NAME="IDX7170"></A>
752 <A NAME="IDX7171"></A>
753 <A NAME="IDX7172"></A>
754 <A NAME="IDX7173"></A>
755 <P><H3><A NAME="HDRWQ345" HREF="auagd002.htm#ToC_382">To set the event set</A></H3>
757 <P><LI>Become the local superuser <B>root</B> on the machine, if you are not
758 already, by issuing the <B>su</B> command.
759 <PRE> % <B>su root</B>
760 Password: <VAR>root_password</VAR>
762 <P><LI>Issue the <B>fstrace setset</B> command to set the state of event
764 <PRE> % <B>fstrace setset</B> [<B>-set</B> <<VAR>set_name</VAR>><SUP>+</SUP>] [<B>-active</B>] [<B>-inactive</B>] \
768 <P>The following example activates the <B>cm</B> event set.
769 <PRE> # <B>fstrace setset cm -active</B>
771 <P><H3><A NAME="HDRWQ346" HREF="auagd002.htm#ToC_383">Displaying the State of a Trace Log or Event Set</A></H3>
772 <P>An event set must be in the <I>active</I> state to be
773 included in the trace log. To display an event set's state, use
774 the <B>fstrace lsset</B> command. To set its state, issue the
775 <B>fstrace setset</B> command as described in <A HREF="#HDRWQ345">To set the event set</A>.
776 <P>To display size and allocation information for the trace log, issue the
777 <B>fstrace lslog</B>command with the <B>-long</B> argument.
778 <A NAME="IDX7174"></A>
779 <A NAME="IDX7175"></A>
780 <A NAME="IDX7176"></A>
781 <A NAME="IDX7177"></A>
782 <P><H3><A NAME="Header_384" HREF="auagd002.htm#ToC_384">To display the state of an event set</A></H3>
784 <P><LI>Become the local superuser <B>root</B> on the machine, if you are not
785 already, by issuing the <B>su</B> command.
786 <PRE> % <B>su root</B>
787 Password: <VAR>root_password</VAR>
789 <P><LI>Issue the <B>fstrace lsset</B> command to display the available event
791 <PRE> # <B>fstrace lsset</B> [<B>-set</B> <<VAR>set_name</VAR>><SUP>+</SUP>]
794 <P>The following example displays the event set and its state on the local
796 <PRE> #<B> fstrace lsset cm</B>
800 <P>The output from this command lists the event set and its states. The
801 three event states for the <B>cm</B> event set are:
803 <P><DT><B><TT>active</TT>
804 </B><DD>Tracing is enabled.
805 <P><DT><B><TT>inactive</TT>
806 </B><DD>Tracing is disabled, but space is still allocated for the corresponding
807 trace log (<B>cmfx</B>).
808 <P><DT><B><TT>dormant</TT>
809 </B><DD>Tracing is disabled, and space is no longer allocated for the
810 corresponding trace log (<B>cmfx</B>).Disables tracing for the
813 <A NAME="IDX7178"></A>
814 <A NAME="IDX7179"></A>
815 <A NAME="IDX7180"></A>
816 <A NAME="IDX7181"></A>
817 <P><H3><A NAME="Header_385" HREF="auagd002.htm#ToC_385">To display the log size</A></H3>
819 <P><LI>Become the local superuser <B>root</B> on the machine, if you are not
820 already, by issuing the <B>su</B> command.
821 <PRE> % <B>su root</B>
822 Password: <VAR>root_password</VAR>
824 <P><LI>Issue the <B>fstrace lslog</B> command to display information about
825 the kernel trace log.
826 <PRE> # <B>fstrace lslog</B> [<B>-set</B> <<VAR>set_name</VAR>><SUP>+</SUP>] [<B>-log</B> <<VAR>log_name</VAR>>] [<B>-long</B>]
829 <P>The following example uses the <B>-long</B> flag to display additional
830 information about the <B>cmfx</B> trace log.
831 <PRE> # <B>fstrace lslog cmfx -long</B>
833 cmfx : 60 kbytes (allocated)
835 <P>The output from this command lists information on the trace log.
836 When issued without the <B>-long</B> flag, the <B>fstrace lslog</B>
837 command lists only the name of the log. When issued with the
838 <B>-long</B> flag, the <B>fstrace lslog</B> command lists the log, the
839 size of the log in kilobytes, and the allocation state of the log.
840 <P>There are two allocation states for the kernel trace log:
842 <P><DT><B><TT>allocated</TT>
843 </B><DD>Space is reserved for the log in the kernel. This indicates that
844 the event set that writes to this log is either <I>active</I> (tracing is
845 enabled for the event set) or <I>inactive</I> (tracing is temporarily
846 disabled for the event set); however, the event set continues to reserve
847 space occupied by the log to which it sends data.
848 <P><DT><B><TT>unallocated</TT>
849 </B><DD>Space is not reserved for the log in the kernel. This indicates
850 that the event set that writes to this log is <I>dormant</I> (tracing is
851 disabled for the event set); furthermore, the event set releases the
852 space occupied by the log to which it sends data.
854 <P><H3><A NAME="HDRWQ347" HREF="auagd002.htm#ToC_386">Dumping and Clearing the Trace Log</A></H3>
855 <P>After the Cache Manager operation you want to trace is
856 complete, use the <B>fstrace dump</B> command to dump the trace log to the
857 standard output stream or to the file named by the <B>-file</B>
858 argument. Or, to dump the trace log continuously, use the
859 <B>-follow</B> argument (combine it with the <B>-file</B> argument if
860 desired). To halt continuous dumping, press an interrupt signal such as
862 <P>To clear a trace log when you no longer need the data in it, issue the
863 <B>fstrace clear</B> command. (The <B>fstrace setlog</B>
864 command also clears an existing trace log automatically when you use it to
865 change the log's size.)
866 <A NAME="IDX7182"></A>
867 <A NAME="IDX7183"></A>
868 <A NAME="IDX7184"></A>
869 <A NAME="IDX7185"></A>
870 <A NAME="IDX7186"></A>
871 <P><H3><A NAME="Header_387" HREF="auagd002.htm#ToC_387">To dump the contents of a trace log</A></H3>
873 <P><LI>Become the local superuser <B>root</B> on the machine, if you are not
874 already, by issuing the <B>su</B> command.
875 <PRE> % <B>su root</B>
876 Password: <VAR>root_password</VAR>
878 <P><LI>Issue the <B>fstrace dump</B> command to dump trace logs.
879 <PRE> # <B>fstrace dump</B> [<B>-set</B> <<VAR>set_name</VAR>><SUP>+</SUP>] [<B>-follow</B> <<VAR>log_name></VAR>] \
880 [<B>-file</B> <<VAR>output_filename</VAR>>] \
881 [<B>-sleep</B> <<VAR>seconds_between_reads</VAR>>]
884 <P>At the beginning of the output of each dump is a header specifying the date
885 and time at which the dump began. The number of logs being dumped is
886 also displayed if the <B>-follow</B> argument is not specified. The
887 header appears as follows:
888 <PRE> AFS Trace Dump --
889 Date: <VAR>date</VAR> <VAR>time</VAR>
890 Found <VAR>n</VAR> logs.
892 <P>where <I>date</I> is the starting date of the trace log dump,
893 <I>time</I> is the starting time of the trace log dump, and <I>n</I>
894 specifies the number of logs found by the <B>fstrace dump</B>
896 <P>The following is an example of trace log dump header:
897 <PRE> AFS Trace Dump --
898 Date: Fri Apr 16 10:44:38 1999
901 <P>The contents of the log follow the header and are comprised of messages
902 written to the log from an active event set. The messages written to
903 the log contain the following three components:
905 <P><LI>The timestamp associated with the message (number of seconds from an
906 arbitrary start point)
907 <P><LI>The process ID or thread ID associated with the message
908 <P><LI>The message itself
910 <P>A trace log message is formatted as follows:
911 <PRE> time <VAR>timestamp</VAR>, pid <VAR>pid</VAR>:<VAR>event message</VAR>
913 <P>where <I>timestamp</I> is the number of seconds from an arbitrary start
914 point, <I>pid</I> is the process ID number of the Cache Manager event, and
915 <I>event message</I> is the Cache Manager event which corresponds with a
916 function in the AFS source code.
917 <P>The following is an example of a dumped trace log message:
918 <PRE> time 749.641274, pid 3002:Returning code 2 from 19
920 <P>For the messages in the trace log to be most readable, the Cache Manager
921 catalog file needs to be installed on the local disk of the client
922 machine; the conventional location is
923 <B>/usr/vice/etc/C/afszcm.cat</B>. Log messages that begin
924 with the string <TT>raw op</TT>, like the following, indicate that the
925 catalog is not installed.
926 <PRE> raw op 232c, time 511.916288, pid 0
927 p0:Fri Apr 16 10:36:31 1999
929 <P>Every 1024 seconds, a current time message is written to each log.
930 This message has the following format:
931 <PRE> time <VAR>timestamp</VAR>, pid <VAR>pid</VAR>: Current time: <VAR>unix_time</VAR>
933 <P>where <VAR>timestamp</VAR> is the number of seconds from an arbitrary start
934 point, <VAR>pid</VAR> is the process ID number, and <VAR>unix_time</VAR> is the
935 standard time format since January 1, 1970.
936 <P>The current time message can be used to determine the actual time
937 associated with each log message. Determine the actual time as
940 <P><LI>Locate the log message whose actual time you want to determine.
941 <P><LI>Search backward through the dump record until you come to a current time
943 <P><LI>If the current time message's <I>timestamp</I> is smaller than
944 the log message's <I>timestamp</I>, subtract the former from the
945 latter. If the current time message's <I>timestamp</I> is
946 larger than the log message's <I>timestamp</I>, add 1024 to the
947 latter and subtract the former from the result.
948 <P><LI>Add the resulting number to the current time message's
949 <I>unix_time</I> to determine the log message's actual time.
951 <P>Because log data is stored in a finite, circular buffer, some of the data
952 can be overwritten before being read. If this happens, the following
953 message appears at the appropriate place in the dump:
954 <PRE> Log wrapped; data missing.
956 <TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">If this message appears in the middle of a dump, which can happen under a
957 heavy work load, it indicates that not all of the log data is being written to
958 the log or some data is being overwritten. Increasing the size of the
959 log with the <B>fstrace setlog</B> command can alleviate this
962 <A NAME="IDX7187"></A>
963 <A NAME="IDX7188"></A>
964 <A NAME="IDX7189"></A>
965 <A NAME="IDX7190"></A>
966 <A NAME="IDX7191"></A>
967 <P><H3><A NAME="Header_388" HREF="auagd002.htm#ToC_388">To clear the contents of a trace log</A></H3>
969 <P><LI>Become the local superuser <B>root</B> on the machine, if you are not
970 already, by issuing the <B>su</B> command.
971 <PRE> % <B>su root</B>
972 Password: <VAR>root_password</VAR>
974 <P><LI>Issue the <B>fstrace clear</B> command to clear logs by log name or by
976 <PRE> # <B>fstrace clear</B> [<B>-set</B> <<VAR>set_name</VAR>><SUP>+</SUP>] [<B>-log</B> <<VAR>log_name</VAR>><SUP>+</SUP>]
979 <P>The following example clears the <B>cmfx</B> log used by the
980 <B>cm</B> event set on the local machine.
981 <PRE> # <B>fstrace clear cm</B>
983 <P>The following example also clears the <B>cmfx</B> log on the local
985 <PRE> # <B>fstrace clear cmfx</B>
987 <A NAME="IDX7192"></A>
988 <P><H3><A NAME="HDRWQ348" HREF="auagd002.htm#ToC_389">Examples of fstrace Commands</A></H3>
989 <P>This section contains an extensive example of the use of the
990 <B>fstrace</B> command suite, which is useful for gathering a detailed
991 trace of Cache Manager activity when you are working with AFS Product Support
992 to diagnose a problem. The Product Support representative can guide you
993 in choosing appropriate parameter settings for the trace.
994 <P>Before starting the kernel trace log, try to isolate the Cache Manager on
995 the AFS client machine that is experiencing the problem accessing the
996 file. If necessary, instruct users to move to another machine so as to
997 minimize the Cache Manager activity on this machine. To minimize the
998 amount of unrelated AFS activity recorded in the trace log, place both the
999 <B>fstrace</B> binary and the dump file must reside on the local disk, not
1000 in AFS. You must be logged in as the local superuser <B>root</B> to
1001 issue <B>fstrace</B> commands.
1002 <P>Before starting a kernel trace, issue the <B>fstrace lsset</B> command
1003 to check the state of the <B>cm</B> event set.
1004 <PRE> # <B>fstrace lsset cm</B>
1006 <P>If tracing has not been enabled previously or if tracing has been turned
1007 off on the client machine, the following output is displayed:
1008 <PRE> Available sets:
1011 <P>If tracing has been turned off and kernel memory is not allocated for the
1012 trace log on the client machine, the following output is displayed:
1013 <PRE> Available sets:
1014 cm inactive (dormant)
1016 <P>If the current state of the <B>cm</B> event set is <TT>inactive</TT>
1017 or <TT>inactive (dormant)</TT>, turn on kernel tracing by issuing the
1018 <B>fstrace setset</B> command with the <B>-active</B> flag.
1019 <PRE> # <B>fstrace setset cm -active</B>
1021 <P>If tracing is enabled currently on the client machine, the following output
1023 <PRE> Available sets:
1026 <P>If tracing is enabled currently, you do not need to use the <B>fstrace
1027 setset</B> command. Do issue the <B>fstrace clear</B> command to
1028 clear the contents of any existing trace log, removing prior traces that are
1029 not related to the current problem.
1030 <PRE> # <B>fstrace clear cm</B>
1032 <P>After checking on the state of the event set, issue the <B>fstrace
1033 lslog</B> command with the <B>-long</B> flag to check the current state
1034 and size of the kernel trace log .
1035 <PRE> # <B>fstrace lslog cmfx -long</B>
1037 <P>If tracing has not been enabled previously or the <B>cm</B> event set
1038 was set to <TT>active</TT> or <TT>inactive</TT> previously, output similar
1039 to the following is displayed:
1040 <PRE> Available logs:
1041 cmfx : 60 kbytes (allocated)
1043 <P>The <B>fstrace</B> tracing utility allocates 60 kilobytes of memory to
1044 the trace log by default. You can increase or decrease the amount of
1045 memory allocated to the kernel trace log by setting it with the <B>fstrace
1046 setlog</B> command. The number specified with the
1047 <B>-buffersize</B> argument represents the number of kilobytes allocated
1048 to the kernel trace log. If you increase the size of the kernel trace
1049 log to 100 kilobytes, issue the following command.
1050 <PRE> # <B>fstrace setlog cmfx</B> 100
1052 <P>After ensuring that the kernel trace log is configured for your needs, you
1053 can set up a file into which you can dump the kernel trace log. For
1054 example, create a dump file with the name
1055 <B>cmfx.dump.file.1</B> using the following
1056 <B>fstrace dump</B> command. Issue the command as a continuous
1057 process by adding the <B>-follow</B> and <B>-sleep</B>
1058 arguments. Setting the <B>-sleep</B> argument to <I>10</I>
1059 dumps output from the kernel trace log to the file every 10 seconds.
1060 <PRE> # <B>fstrace dump -follow</B> cmfx <B>-file</B> cmfx.dump.file.1 <B>-sleep</B> 10
1062 Date: Fri Apr 16 10:54:57 1999
1064 time 32.965783, pid 0: Fri Apr 16 10:45:52 1999
1065 time 32.965783, pid 33657: Close 0x5c39ed8 flags 0x20
1066 time 32.965897, pid 33657: Gn_close vp 0x5c39ed8 flags 0x20 (returns
1068 time 35.159854, pid 10891: Breaking callback for 5bd95e4 states 1024
1070 time 35.407081, pid 10891: Breaking callback for 5c0fadc states 1024
1075 time 71.440456, pid 33658: Lookup adp 0x5bbdcf0 name g3oCKs fid (756
1076 4fb7e:588d240.2ff978a8.6)
1077 time 71.440569, pid 33658: Returning code 2 from 19
1078 time 71.440619, pid 33658: Gn_lookup vp 0x5bbdcf0 name g3oCKs (returns
1080 time 71.464989, pid 38267: Gn_open vp 0x5bbd000 flags 0x0 (returns 0x
1082 AFS Trace Dump - Completed
1084 <HR><H2><A NAME="HDRWQ349" HREF="auagd002.htm#ToC_390">Using the afsmonitor Program</A></H2>
1085 <A NAME="IDX7193"></A>
1086 <P>The <B>afsmonitor</B> program enables you to monitor the status and
1087 performance of specified File Server and Cache Manager processes by gathering
1088 statistical information. Among its other uses, the
1089 <B>afsmonitor</B> program can be used to fine-tune Cache Manager
1090 configuration and load balance File Servers.
1091 <P>The <B>afsmonitor</B> program enables you to perform the following
1094 <P><LI>Monitor any number of File Server and Cache Manager processes on any
1095 number of machines (in both local and foreign cells) from a single
1097 <P><LI>Set threshold values for any monitored statistic. When the value of
1098 a statistic exceeds the threshold, the <B>afsmonitor</B> program
1099 highlights it to draw your attention. You can set threshold levels that
1100 apply to every machine or only some.
1101 <P><LI>Invoke programs or scripts automatically when a statistic exceeds its
1104 <P><H3><A NAME="HDRWQ350" HREF="auagd002.htm#ToC_391">Requirements for running the afsmonitor program</A></H3>
1105 <A NAME="IDX7194"></A>
1106 <P>The following software must be accessible to a machine where the
1107 <B>afsmonitor</B> program is running:
1109 <P><LI>The AFS <B>xstat</B> libraries, which the <B>afsmonitor</B>
1110 program uses to gather data
1111 <P><LI>The <B>curses</B> graphics package, which most UNIX distributions
1112 provide as a standard utility
1114 <A NAME="IDX7195"></A>
1115 <A NAME="IDX7196"></A>
1116 <P>The <B>afsmonitor</B> screens format successfully both on so-called
1117 dumb terminals and in windowing systems that emulate terminals. For the
1118 output to looks its best, the display environment needs to support reverse
1119 video and cursor addressing. Set the TERM environment variable to the
1120 correct terminal type, or to a value that has characteristics similar to the
1121 actual terminal type. The display window or terminal must be at least
1122 80 columns wide and 12 lines long.
1123 <A NAME="IDX7197"></A>
1124 <A NAME="IDX7198"></A>
1125 <A NAME="IDX7199"></A>
1126 <P>The <B>afsmonitor</B> program must run in the foreground, and in its
1127 own separate, dedicated window or terminal. The window or terminal is
1128 unavailable for any other activity as long as the <B>afsmonitor</B>
1129 program is running. Any number of instances of the
1130 <B>afsmonitor</B> program can run on a single machine, as long as each
1131 instance runs in its own dedicated window or terminal. Note that it can
1132 take up to three minutes to start an additional instance.
1134 <A NAME="IDX7200"></A>
1135 No privilege is required to run the <B>afsmonitor</B> program. By
1136 convention, it is installed in the <B>/usr/afsws/bin</B> directory, and
1137 anyone who can access the directory can monitor File Servers and Cache
1138 Managers. The probes through which the <B>afsmonitor</B> program
1139 collects statistics do not constitute a significant burden on the File Server
1140 or Cache Manager unless hundreds of people are running the program. If
1141 you wish to restrict its use, place the binary file in a directory available
1142 only to authorized users.
1143 <P><H3><A NAME="Header_392" HREF="auagd002.htm#ToC_392">The afsmonitor Output Screens</A></H3>
1144 <A NAME="IDX7201"></A>
1145 <P>The <B>afsmonitor</B> program displays its data on three screens:
1147 <P><LI><TT>System Overview</TT>: This screen appears automatically when
1148 the <B>afsmonitor</B> program initializes. It summarizes separately
1149 for File Servers and Cache Managers the number of machines being monitored and
1150 how many of them have <I>alerts</I> (statistics that have exceeded their
1151 thresholds). It then lists the hostname and number of alerts for each
1152 machine being monitored, indicating if appropriate that a process failed to
1153 respond to the last probe.
1154 <P><LI><TT>File Server</TT>: This screen displays File Server statistics
1155 for each file server machine being monitored. It highlights statistics
1156 that have exceeded their thresholds, and identifies machines that failed to
1157 respond to the last probe.
1158 <P><LI><TT>Cache Managers</TT>: This screen displays Cache Manager
1159 statistics for each client machine being monitored. It highlights
1160 statistics that have exceeded their thresholds, and identifies machines that
1161 failed to respond to the last probe.
1163 <P>Fields at the corners of every screen display the following
1166 <P><LI>In the top left corner, the program name and version number.
1167 <P><LI>In the top right corner, the screen name, current and total page numbers,
1168 and current and total column numbers. The page number (for example,
1169 <TT>p. 1 of 3</TT>) indicates the index of the current page and the
1170 total number of (vertical) pages over which data is displayed. The
1171 column number (for example, <TT>c. 1 of 235</TT>) indicates the index
1172 of the current leftmost column and the total number of columns in which data
1173 appears. (The symbol <TT>>>></TT> indicates that there is additional
1174 data to the right; the symbol <TT><<<</TT> indicates that
1175 there is additional data to the left.)
1176 <P><LI>In the bottom left corner, a list of the available commands. Enter
1177 the first letter in the command name to run that command. Only the
1178 currently possible options appear; for example, if there is only one page
1179 of data, the <TT>next</TT> and <TT>prev</TT> commands, which scroll the
1180 screen up and down respectively, do not appear. For descriptions of the
1181 commands, see the following section about navigating the display
1183 <P><LI>In the bottom right corner, the <TT>probes</TT> field reports how many
1184 times the program has probed File Servers (<TT>fs</TT>), Cache Managers
1185 (<TT>cm</TT>), or both. The counts for File Servers and Cache
1186 Managers can differ. The <TT>freq</TT> field reports how often the
1187 program sends probes.
1189 <P><B>Navigating the afsmonitor Display Screens</B>
1190 <P>As noted, the lower left hand corner of every display screen displays the
1191 names of the commands currently available for moving to alternate screens,
1192 which can either be a different type or display more statistics or machines of
1193 the current type. To execute a command, press the lowercase version of
1194 the first letter in its name. Some commands also have an uppercase
1195 version that has a somewhat different effect, as indicated in the following
1198 <P><DT><B><TT>cm</TT>
1199 </B><DD>Switches to the <TT>Cache Managers</TT> screen. Available only on
1200 the <TT>System Overview</TT> and <TT>File Servers</TT> screens.
1201 <P><DT><B><TT>fs</TT>
1202 </B><DD>Switches to the <TT>File Servers</TT> screen. Available only on
1203 the <TT>System Overview</TT> and the <TT>Cache Managers</TT>
1205 <P><DT><B><TT>left</TT>
1206 </B><DD>Scrolls horizontally to the left, to access the data columns situated to
1207 the left of the current set. Available when the <TT><<<</TT>
1208 symbol appears at the top left of the screen. Press uppercase
1209 <B>L</B> to scroll horizontally all the way to the left (to display the
1210 first set of data columns).
1211 <P><DT><B><TT>next</TT>
1212 </B><DD>Scrolls down vertically to the next page of machine names.
1213 Available when there are two or more pages of machines and the final page is
1214 not currently displayed. Press uppercase <B>N</B> to scroll to the
1216 <P><DT><B><TT>oview</TT>
1217 </B><DD>Switches to the <TT>System Overview</TT> screen. Available only
1218 on the <TT>Cache Managers</TT> and <TT>File Servers</TT> screens.
1219 <P><DT><B><TT>prev</TT>
1220 </B><DD>Scrolls up vertically to the previous page of machine names.
1221 Available when there are two or more pages of machines and the first page is
1222 not currently displayed. Press uppercase <B>N</B> to scroll to the
1224 <P><DT><B><TT>right</TT>
1225 </B><DD>Scrolls horizontally to the right, to access the data columns situated to
1226 the right of the current set. This command is available when the
1227 <TT>>>></TT> symbol appears at the upper right of the screen. Press
1228 uppercase <B>R</B> to scroll horizontally all the way to the right (to
1229 display the final set of data columns).
1231 <P><H3><A NAME="Header_393" HREF="auagd002.htm#ToC_393">The System Overview Screen</A></H3>
1232 <P>The <TT>System Overview</TT> screen appears automatically as the
1233 <B>afsmonitor</B> program initializes. This screen displays the
1234 status of as many File Server and Cache Manager processes as can fit in the
1235 current window; scroll down to access additional information.
1236 <P>The information on this screen is split into File Server information on the
1237 left and Cache Manager information on the right. The header for each
1238 grouping reports two pieces of information:
1240 <P><LI>The number of machines on which the program is monitoring the indicated
1242 <P><LI>The number of alerts and the number of machines affected by them (an
1243 <I>alert</I>means that a statistic has exceeded its threshold or a process
1244 failed to respond to the last probe)
1246 <P>A list of the machines being monitored follows. If there are any
1247 alerts on a machine, the number of them appears in square brackets to the left
1248 of the hostname. If a process failed to respond to the last probe, the
1249 letters <TT>PF</TT> (probe failure) appear in square brackets to the left of
1251 <P>The following graphic is an example <TT>System Overview</TT>
1252 screen. The <B>afsmonitor</B> program is monitoring six File
1253 Servers and seven Cache Managers. The File Server process on host
1254 <B>fs1.abc.com</B> and the Cache Manager on host
1255 <B>cli33.abc.com</B> are each marked <TT>[ 1]</TT> to
1256 indicate that one threshold value is exceeded. The <TT>[PF]</TT>
1257 marker on host <B>fs6.abc.com</B> indicates that its File
1258 Server process did not respond to the last probe.
1259 <P><B><A NAME="Figure_6" HREF="auagd003.htm#FT_Figure_6">Figure 6. The afsmonitor System Overview Screen</A></B><BR>
1260 <TABLE BORDER ><TR><TD><BR>
1261 <B><BR><IMG SRC="overview.gif" ALT="System Overview Screen"><BR></B><BR>
1263 <P><H3><A NAME="Header_394" HREF="auagd002.htm#ToC_394">The File Servers Screen</A></H3>
1264 <P>The <TT>File Servers</TT> screen displays the values collected at the
1265 most recent probe for File Server statistics.
1266 <P>A summary line at the top of the screen (just below the standard program
1267 version and screen title blocks) specifies the number of monitored File
1268 Servers, the number of alerts, and the number of machines affected by the
1270 <P>The first column always displays the hostnames of the machines running the
1271 monitored File Servers.
1272 <P>To the right of the hostname column appear as many columns of statistics as
1273 can fit within the current width of the display screen or window; each
1274 column requires space for 10 characters. The name of the statistic
1275 appears at the top of each column. If the File Server on a machine did
1276 not respond to the most recent probe, a pair of dashes (<TT>--</TT>) appears
1277 in each column. If a value exceeds its configured threshold, it is
1278 highlighted in reverse video. If a value is too large to fit into the
1279 allotted column width, it overflows into the next row in the same
1281 <P>For a list of the available File Server statistics, see <A HREF="auagd024.htm#HDRWQ617">Appendix C, The afsmonitor Program Statistics</A>.
1282 <P>The following graphic depicts the <TT>File Servers</TT> screen that
1283 follows the System Overview Screen example previously discussed; however,
1284 one additional server probe has been completed. In this example, the
1285 File Server process on <B>fs1</B> has exceeded the configured threshold
1286 for the number of performance calls received (the <B>numPerfCalls</B>
1287 statistic), and that field appears in reverse video. Host
1288 <B>fs6</B> did not respond to Probe 10, so dashes appear in all
1290 <P><B><A NAME="Figure_7" HREF="auagd003.htm#FT_Figure_7">Figure 7. The afsmonitor File Servers Screen</A></B><BR>
1291 <TABLE BORDER ><TR><TD><BR>
1292 <B><BR><IMG SRC="fserver1.gif" ALT="File Servers Screen"><BR></B><BR>
1294 <P>Both the File Servers and Cache Managers screen (discussed in the following
1295 section) can display hundreds of columns of data and are therefore designed to
1296 scroll left and right. In the preceding graphic, the screen displays
1297 the leftmost screen and the screen title block shows that column 1 of 235 is
1298 displayed. The appearance of the <TT>>>></TT> symbol in the upper
1299 right hand corner of the screen and the <B>right</B> command in the
1300 command block indicate that additional data is available by scrolling
1301 right. (For information on the available statistics, see <A HREF="auagd024.htm#HDRWQ617">Appendix C, The afsmonitor Program Statistics</A>.)
1302 <P>If the <B>right</B> command is executed, the screen looks something
1303 like the following example. Note that the horizontal scroll symbols now
1304 point both to the left (<TT><<<</TT>) and to the right
1305 (<TT>>>></TT>) and both the <B>left</B> and <B>right</B> commands
1306 appear, indicating that additional data is available by scrolling both left
1308 <P><B><A NAME="Figure_8" HREF="auagd003.htm#FT_Figure_8">Figure 8. The afsmonitor File Servers Screen Shifted One Page to the Right</A></B><BR>
1309 <TABLE BORDER ><TR><TD><BR>
1310 <B><BR><IMG SRC="fserver2.gif" ALT="File Servers Screen Shifted One Page to the Right"><BR></B><BR>
1312 <P><H3><A NAME="Header_395" HREF="auagd002.htm#ToC_395">The Cache Managers Screen</A></H3>
1313 <P>The <TT>Cache Managers</TT> screen displays the values collected at
1314 the most recent probe for Cache Manager statistics.
1315 <P>A summary line at the top of the screen (just below the standard program
1316 version and screen title blocks) specifies the number of monitored Cache
1317 Managers, the number of alerts, and the number of machines affected by the
1319 <P>The first column always displays the hostnames of the machines running the
1320 monitored Cache Managers.
1321 <P>To the right of the hostname column appear as many columns of statistics as
1322 can fit within the current width of the display screen or window; each
1323 column requires space for 10 characters. The name of the statistic
1324 appears at the top of each column. If the Cache Manager on a machine
1325 did not respond to the most recent probe, a pair of dashes (<TT>--</TT>)
1326 appears in each column. If a value exceeds its configured threshold, it
1327 is highlighted in reverse video. If a value is too large to fit into
1328 the allotted column width, it overflows into the next row in the same
1330 <P>For a list of the available Cache Manager statistics, see <A HREF="auagd024.htm#HDRWQ617">Appendix C, The afsmonitor Program Statistics</A>.
1331 <P>The following graphic depicts a Cache Managers screen that follows the
1332 System Overview Screen previously discussed. In the example, the Cache
1333 Manager process on host <B>cli33</B> has exceeded the configured threshold
1334 for the number of cells it can contact (the <B>numCellsContacted</B>
1335 statistic), so that field appears in reverse video.
1336 <P><B><A NAME="Figure_9" HREF="auagd003.htm#FT_Figure_9">Figure 9. The afsmonitor Cache Managers Screen</A></B><BR>
1337 <TABLE BORDER WIDTH="100%"><TR><TD>
1338 <B><BR><IMG SRC="cachmgr.gif" ALT="Cache Managers Screen"><BR></B>
1340 <HR><H2><A NAME="HDRWQ351" HREF="auagd002.htm#ToC_396">Configuring the afsmonitor Program</A></H2>
1341 <A NAME="IDX7202"></A>
1342 <A NAME="IDX7203"></A>
1343 <P>To customize the <B>afsmonitor</B> program, create an ASCII-format
1344 configuration file and use the <B>-config</B> argument to name it.
1345 You can specify the following in the configuration file:
1347 <P><LI>The File Servers, Cache Managers, or both to monitor.
1348 <P><LI>The statistics to display. By default, the display includes 271
1349 statistics for File Servers and 570 statistics for Cache Managers. For
1350 information on the available statistics, see <A HREF="auagd024.htm#HDRWQ617">Appendix C, The afsmonitor Program Statistics</A>.
1351 <P><LI>The threshold values to set for statistics and a script or program to
1352 execute if a threshold is exceeded. By default, no threshold values are
1353 defined and no scripts or programs are executed.
1355 <P>The following list describes the instructions that can appear in the
1358 <P><DT><B><TT>cm <VAR>host_name</VAR></TT>
1359 </B><DD>Names a client machine for which to display Cache Manager
1360 statistics. The order of <B>cm</B> lines in the file determines the
1361 order in which client machines appear from top to bottom on the <TT>System
1362 Overview</TT> and <TT>Cache Managers</TT> output screens.
1363 <P><DT><B><TT>fs <VAR>host_name</VAR></TT>
1364 </B><DD>Names a file server machine for which to display File Server
1365 statistics. The order of <B>fs</B> lines in the file determines the
1366 order in which file server machines appear from top to bottom on the
1367 <TT>System Overview</TT> and <TT>File Servers</TT> output screens.
1368 <P><DT><B><TT>thresh fs | cm <VAR>field_name</VAR> <VAR>thresh_val</VAR>
1369 [<VAR>cmd_to_run</VAR>] [<VAR>arg</VAR><SUB>1</SUB>] . . .
1370 [<VAR>arg</VAR><SUB>n</SUB>]</TT>
1371 </B><DD>Assigns the threshold value <VAR>thresh_val</VAR> to the statistic
1372 <VAR>field_name</VAR>, for either a File Server statistic (<B>fs</B>) or a
1373 Cache Manager statistic (<B>cm</B>). The optional
1374 <VAR>cmd_to_execute</VAR> field names a binary or script to execute each time
1375 the value of the statistic changes from being below <VAR>thresh_val</VAR> to
1376 being at or above <VAR>thresh_val</VAR>. A change between two values that
1377 both exceed <VAR>thresh_val</VAR> does not retrigger the binary or
1378 script. The optional <VAR>arg</VAR><SUB>1</SUB> through
1379 <VAR>arg</VAR><SUB>n</SUB> fields are additional values that the
1380 <B>afsmonitor</B> program passes as arguments to the
1381 <VAR>cmd_to_execute</VAR> command. If any of them include one or more
1382 spaces, enclose the entire field in double quotes.
1383 <P>The parameters <B>fs</B>, <B>cm</B>, <VAR>field_name</VAR>,
1384 <VAR>threshold_val</VAR>, and <VAR>arg</VAR><SUB>1</SUB> through
1385 <VAR>arg</VAR><SUB>n</SUB> correspond to the values with the same name on the
1386 <B>thresh</B> line. The <VAR>host_name</VAR> parameter identifies the
1387 file server or client machine where the statistic has crossed the threshold,
1388 and the <VAR>actual_val</VAR> parameter is the actual value of
1389 <VAR>field_name</VAR> that equals or exceeds the threshold value.
1390 <P>Use the <B>thresh</B> line to set either a global threshold, which
1391 applies to all file server machines listed on <B>fs</B> lines or client
1392 machines listed on <B>cm</B> lines in the configuration file, or a
1393 machine-specific threshold, which applies to only one file server or client
1396 <P><LI>To set a global threshold, place the <B>thresh</B> line before any of
1397 the <B>fs</B> or <B>cm</B> lines in the file.
1398 <P><LI>To set a machine-specific threshold, place the <B>thresh</B> line
1399 below the corresponding <B>fs</B> or <B>cm</B> line, and above any
1400 other <B>fs</B> or <B>cm</B> lines. A machine-specific
1401 threshold value always overrides the corresponding global threshold, if
1402 set. Do not place a <B>thresh fs</B> line directly after a
1403 <B>cm</B> line or a <B>thresh cm</B> line directly after a
1406 <P><DT><B><TT>show fs | cm <VAR>field/group/section</VAR></TT>
1407 </B><DD>Specifies which individual statistic, group of statistics, or section of
1408 statistics to display on the <TT>File Servers</TT> screen (<B>fs</B>) or
1409 <TT>Cache Managers</TT> screen (<B>cm</B>) and the order in which to
1410 display them. The appendix of <B>afsmonitor</B> statistics in the
1411 <I>IBM AFS Administration Guide</I> specifies the group and section to
1412 which each statistic belongs. Include as many <B>show</B> lines as
1413 necessary to customize the screen display as desired, and place them anywhere
1414 in the file. The top-to-bottom order of the <B>show</B> lines in
1415 the configuration file determines the left-to-right order in which the
1416 statistics appear on the corresponding screen.
1417 <P>If there are no <B>show</B> lines in the configuration file, then the
1418 screens display all statistics for both Cache Managers and File
1419 Servers. Similarly, if there are no <B>show fs</B> lines, the
1420 <TT>File Servers</TT> screen displays all file server statistics, and if
1421 there are no <B>show cm</B> lines, the <TT>Cache Managers</TT> screen
1422 displays all client statistics.
1423 <P><DT><B># <VAR>comments</VAR>
1424 </B><DD>Precedes a line of text that the <B>afsmonitor</B> program ignores
1425 because of the initial number (<B>#</B>) sign, which must appear in the
1426 very first column of the line.
1428 <P>For a list of the values that can appear in the
1429 <VAR>field/group/section</VAR> field of a <B>show</B> instruction, see <A HREF="auagd024.htm#HDRWQ617">Appendix C, The afsmonitor Program Statistics</A>.)
1430 <P>The following example illustrates a possible configuration file:
1431 <PRE> thresh cm dlocalAccesses 1000000
1432 thresh cm dremoteAccesses 500000 handleDRemote
1433 thresh fs rx_maxRtt_Usec 1000
1437 thresh cm dlocalAccesses 2000000
1438 thresh cm vcacheMisses 10000
1444 show cm numCellsContacted
1445 show cm dlocalAccesses
1446 show cm dremoteAccesses
1447 show cm vcacheMisses
1448 show cm Auth_Stats_group
1450 <P>Since the first three <B>thresh</B> instructions appear before any
1451 <B>fs</B> or <B>cm</B> instructions, they set global threshold
1454 <P><LI>All Cache Manager process in this file use <B>1000000</B> as the
1455 threshold for the <B>dlocalAccesses</B> statistic (except for the machine
1456 <B>client2</B> which uses an overriding value of
1458 <P><LI>All Cache Manager processes in this file use <B>500000</B> as the
1459 threshold value for the <B>dremoteAccesses</B> statistic; if that
1460 value is exceeded, the script <B>handleDRemote</B> is invoked.
1461 <P><LI>All File Server processes in this file use <B>1000</B> as the
1462 threshold value for the <B>rx_maxRtt_Usec</B> statistic.
1464 <P>The four <B>cm</B> instructions monitor the Cache Manager on the
1465 machines <B>client5</B>, <B>client33</B>, <B>client14</B>, and
1466 <B>client2</B>. The first three use all of the global threshold
1468 <P>The Cache Manager on <B>client2</B> uses the global threshold value for
1469 the <B>dremoteAccesses</B> statistic, but a different one for the
1470 <B>dlocalAccesses</B> statistic. Furthermore, <B>client22</B>
1471 is the only Cache Manager that uses the threshold set for the
1472 <B>vcacheMisses</B> statistic.
1473 <P>The <B>fs</B> instructions monitor the File Server on the machines
1474 <B>fs3</B>, <B>fs9</B>, <B>fs5</B>, and <B>fs10</B>.
1475 They all use the global threshold for the<B>rx_maxRtt_Usec</B>
1477 <P>Because there are no <B>show fs</B> instructions, the File Servers
1478 screen displays all File Server statistics. The Cache Managers screen
1479 displays only the statistics named in <B>show cm</B> instructions,
1480 ordering them from left to right. The <B>Auth_Stats_group</B>
1481 includes several statistics, all of which are displayed (<B>curr_PAGs</B>,
1482 <B>curr_Records</B>, <B>curr_AuthRecords</B>,
1483 <B>curr_UnauthRecords</B>, <B>curr_MaxRecordsInPAG</B>,
1484 <B>curr_LongestChain</B>, <B>PAGCreations</B>,
1485 <B>TicketUpdates</B>, <B>HWM_PAGS</B>, <B>HWM_Records</B>,
1486 <B>HWM_MaxRecordsInPAG</B>, and <B>HWM_LongestChain</B>).
1487 <HR><H2><A NAME="HDRWQ352" HREF="auagd002.htm#ToC_397">Writing afsmonitor Statistics to a File</A></H2>
1488 <A NAME="IDX7204"></A>
1489 <P>All of the statistical information collected and displayed by the
1490 <B>afsmonitor</B> program can be preserved by writing it to an output
1491 file. You can create an output file by using the <B>-output</B>
1492 argument when you startup the <B>afsmonitor</B> process. You can
1493 use the output file to track process performance over long periods of time and
1494 to apply post-processing techniques to further analyze system trends.
1495 <P>The <B>afsmonitor</B> program output file is a simple ASCII file that
1496 records the information reported by the File Server and Cache Manager
1497 screens. The output file has the following format:
1498 <PRE> <VAR>time</VAR> <VAR>host_name</VAR> <B>CM</B>|<B>FS</B> <VAR>list_of_measured_values</VAR>
1500 <P>and specifies the <I>time</I> at which the
1501 <I>list_of_measured_values</I> were gathered from the Cache Manager
1502 (<B>CM</B>) or File Server (<B>FS</B>) process housed on
1503 <VAR>host_name</VAR>. On those occasion where probes fail, the value
1504 <TT>-1</TT> is reported instead of the
1505 <I>list_of_measured_values</I>.
1506 <P>This file format provides several advantages:
1508 <P><LI>It can be viewed using a standard editor. If you intend to view
1509 this file frequently, use the <B>-detailed</B> flag with the
1510 <B>-output</B> argument. It formats the output file in a way that
1512 <P><LI>It can be passed through filters to extract desired information using the
1513 standard set of UNIX tools.
1514 <P><LI>It is suitable for long term storage of the <B>afsmonitor</B> program
1517 <A NAME="IDX7205"></A>
1518 <A NAME="IDX7206"></A>
1519 <HR><H2><A NAME="Header_398" HREF="auagd002.htm#ToC_398">To start the afsmonitor Program</A></H2>
1521 <P><LI>Open a separate command shell window or use a dedicated terminal for each
1522 instance of the <B>afsmonitor</B> program. This window or terminal
1523 must be devoted to the exclusive use of the <B>afsmonitor</B> process
1524 because the command cannot be run in the background.
1525 <P><LI>Initialize the <B>afsmonitor</B> program. The message <TT>
1526 afsmonitor Collecting Statistics...</TT>, followed by
1527 the appearance of the System Overview screen, confirms a successful
1529 <PRE> % <B>afsmonitor</B> [<B>initcmd</B>] [<B>-config</B> <<VAR>configuration file</VAR>>] \
1530 [<B>-frequency</B> <<VAR>poll frequency, in seconds</VAR>>] \
1531 [<B>-output</B> <<VAR>storage file name</VAR>>] [<B>-detailed</B>] \
1532 [<B>-debug</B> <<VAR>turn debugging output on to the named file</VAR>>] \
1533 [<B>-fshosts</B> <<VAR>list of file servers to monitor</VAR>><SUP>+</SUP>] \
1534 [<B>-cmhosts</B> <<VAR>list of cache managers to monitor</VAR>><SUP>+</SUP>]
1535 afsmonitor Collecting Statistics...
1540 </B><DD>Is an optional string that accommodates the command's use of the AFS
1541 command parser. It can be omitted and ignored.
1543 </B><DD>Specifies the pathname of an <B>afsmonitor</B> configuration file,
1544 which lists the machines and statistics to monitor. Partial pathnames
1545 are interpreted relative to the current working directory. Provide
1546 either this argument or one or both of the <B>-fshosts</B> and
1547 <B>-cmhosts</B> arguments. You must use a configuration file to set
1548 thresholds or customize the screen display. For instructions on
1549 creating the configuration file, see <A HREF="#HDRWQ351">Configuring the afsmonitor Program</A>.
1550 <P><DT><B>-frequency
1551 </B><DD>Specifies how often to probe the File Server and Cache Manager processes,
1552 as a number of seconds. Acceptable values range from <B>1</B> and
1553 <B>86400</B>; the default value is <B>60</B>. This
1554 frequency applies to both File Server and Cache Manager probes; however,
1555 File Server and Cache Manager probes are initiated and processed independent
1556 of each other. The actual interval between probes to a host is the
1557 probe frequency plus the time needed by all hosts to respond to the
1560 </B><DD>Specifies the name of an output file to which to write all of the
1561 statistical data. By default, no output file is created. For
1562 information on this file, see <A HREF="#HDRWQ352">Writing afsmonitor Statistics to a File</A>.
1564 </B><DD>Formats the output file named by the <B>-output</B> argument to be
1565 more easily readable. The <B>-output</B> argument must be provided
1566 along with this flag.
1568 </B><DD>Identifies each File Server process to monitor by specifying the host it
1569 is running on. You can identify a host using either its complete
1570 Internet-style host name or an abbreviation acceptable to the cell's
1571 naming service. Combine this argument with the <B>-cmhosts</B> if
1572 you wish, but not the <B>-config</B> argument.
1574 </B><DD>Identifies each Cache Manager process to monitor by specifying the host it
1575 is running on. You can identify a host using either its complete
1576 Internet-style host name or an abbreviation acceptable to the cell's
1577 naming service. Combine this argument with the <B>-fshosts</B> if
1578 you wish, but not the <B>-config</B> argument.
1581 <HR><H2><A NAME="Header_399" HREF="auagd002.htm#ToC_399">To stop the afsmonitor program</A></H2>
1582 <A NAME="IDX7207"></A>
1583 <P>To exit an <B>afsmonitor</B> program session, Enter the
1584 <<B>Ctrl-c</B>> interrupt signal or an uppercase <B>Q</B>.
1585 <HR><H2><A NAME="HDRWQ353" HREF="auagd002.htm#ToC_400">The xstat Data Collection Facility</A></H2>
1586 <A NAME="IDX7208"></A>
1587 <A NAME="IDX7209"></A>
1588 <A NAME="IDX7210"></A>
1589 <A NAME="IDX7211"></A>
1590 <A NAME="IDX7212"></A>
1591 <A NAME="IDX7213"></A>
1592 <A NAME="IDX7214"></A>
1593 <A NAME="IDX7215"></A>
1594 <A NAME="IDX7216"></A>
1595 <A NAME="IDX7217"></A>
1596 <A NAME="IDX7218"></A>
1597 <P>The <B>afsmonitor</B> program uses the <B>xstat</B> data collection
1598 facility to gather and calculate the data that it (the <B>afsmonitor</B>
1599 program) then uses to perform its function. You can also use the
1600 <B>xstat</B> facility to create your own data display programs. If
1601 you do, keep the following in mind. The File Server considers any
1602 program calling its RPC routines to be a Cache Manager; therefore, any
1603 program calling the File Server interface directly must export the Cache
1604 Manager's callback interface. The calling program must be capable
1605 of emulating the necessary callback state, and it must respond to periodic
1606 keep-alive messages from the File Server. In addition, a calling
1607 program must be able to gather the collected data.
1608 <P>The <B>xstat</B> facility consists of two C language libraries
1609 available to user-level applications:
1611 <P><LI><B>/usr/afsws/lib/afs/libxstat_fs.a</B> exports calls that
1612 gather information from one or more running File Server processes.
1613 <P><LI><B>/usr/afsws/lib/afs/libxstat_cm.a</B> exports calls that
1614 collect information from one or more running Cache Managers.
1616 <P>The libraries allow the caller to register
1618 <P><LI>A set of File Servers or Cache Managers to be examined.
1619 <P><LI>The frequency with which the File Servers or Cache Managers are to be
1621 <P><LI>A user-specified routine to be called each time data is collected.
1623 <P>The libraries handle all of the lightweight processes, callback
1624 interactions, and timing issues associated with the data collection.
1625 The user needs only to process the data as it arrives.
1626 <P><H3><A NAME="Header_401" HREF="auagd002.htm#ToC_401">The libxstat Libraries</A></H3>
1627 <A NAME="IDX7219"></A>
1628 <A NAME="IDX7220"></A>
1629 <P>The <B>libxstat_fs.a</B> and <B>libxstat_cm.a</B>
1630 libraries handle the callback requirements and other complications associated
1631 with the collection of data from File Servers and Cache Managers. The
1632 user provides only the means of accumulating the desired data. Each
1633 <B>xstat</B> library implements three routines:
1635 <P><LI>Initialization (<B>xstat_fs_Init</B> and <B>xstat_cm_Init</B>)
1636 arranges the periodic collection and handling of data.
1637 <P><LI>Immediate probe (<B>xstat_fs_ForceProbeNow</B> and
1638 <B>xstat_cm_ForceProbeNow</B>) forces the immediate collection of data,
1639 after which collection returns to its normal probe schedule.
1640 <P><LI>Cleanup (<B>xstat_fs_Cleanup</B> and <B>xstat_cm_Cleanup</B>)
1641 terminates all connections and removes all traces of the data collection from
1645 <A NAME="IDX7221"></A>
1646 <A NAME="IDX7222"></A>
1647 <A NAME="IDX7223"></A>
1648 <A NAME="IDX7224"></A>
1649 <A NAME="IDX7225"></A>
1650 The File Server and Cache Manager each define data collections that clients
1651 can fetch. A data collection is simply a related set of numbers that
1652 can be collected as a unit. For example, the File Server and Cache
1653 Manager each define profiling and performance data collections. The
1654 profiling collections maintain counts of the number of times internal
1655 functions are called within servers, allowing bottleneck analysis to be
1656 performed. The performance collections record, among other things,
1657 internal disk I/O statistics for a File Server and cache effectiveness figures
1658 for a Cache Manager, allowing for performance analysis.
1660 <A NAME="IDX7226"></A>
1661 <A NAME="IDX7227"></A>
1662 <A NAME="IDX7228"></A>
1663 For a copy of the detailed specification which provides much additional usage
1664 information about the <B>xstat</B> facility, its libraries, and the
1665 routines in the libraries, contact AFS Product Support.
1666 <P><H3><A NAME="Header_402" HREF="auagd002.htm#ToC_402">Example xstat Commands</A></H3>
1667 <A NAME="IDX7229"></A>
1668 <A NAME="IDX7230"></A>
1669 <A NAME="IDX7231"></A>
1670 <A NAME="IDX7232"></A>
1671 <A NAME="IDX7233"></A>
1672 <P>AFS comes with two low-level, example commands:
1673 <B>xstat_fs_test</B> and <B>xstat_cm_test</B>. The commands
1674 allow you to experiment with the <B>xstat</B> facility. They gather
1675 information and display the available data collections for a File Server or
1676 Cache Manager. They are intended merely to provide examples of the
1677 types of data that can be collected via <B>xstat</B>; they are not
1678 intended for use in the actual collection of data.
1679 <A NAME="IDX7234"></A>
1680 <A NAME="IDX7235"></A>
1681 <A NAME="IDX7236"></A>
1682 <A NAME="IDX7237"></A>
1683 <P><H4><A NAME="Header_403">To use the example xstat_fs_test command</A></H4>
1685 <P><LI>Issue the example <B>xstat_fs_test</B> command to test the routines in
1686 the <B>libxstat_fs.a</B> library and display the data collections
1687 associated with the File Server process. The command executes in the
1689 <PRE> % <B>xstat_fs_test</B> [<B>initcmd</B>] \
1690 <B>-fsname</B> <<VAR>File Server name(s) to monitor</VAR>><SUP>+</SUP> \
1691 <B>-collID</B> <<VAR>Collection(s) to fetch</VAR>><SUP>+</SUP> [<B>-onceonly</B>] \
1692 [<B>-frequency</B> <<VAR>poll frequency, in seconds</VAR>>] \
1693 [<B>-period</B> <<VAR>data collection time, in minutes</VAR>>] [<B>-debug</B>]
1697 <P><DT><B>xstat_fs_test
1698 </B><DD>Must be typed in full.
1700 </B><DD>Is an optional string that accommodates the command's use of the AFS
1701 command parser. It can be omitted and ignored.
1703 </B><DD>Is the Internet host name of each file server machine on which to monitor
1704 the File Server process.
1706 </B><DD>Specifies each data collection to return. The indicated data
1707 collection defines the type and amount of data the command is to gather about
1708 the File Server. Data is returned in the form of a predefined data
1709 structure (refer to the specification documents referenced previously for more
1710 information about the data structures).
1711 <P>There are two acceptable values:
1713 <P><LI><B>1</B> reports various internal performance statistics related to
1714 the File Server (for example, vnode cache entries and <B>Rx</B> protocol
1716 <P><LI><B>2</B> reports all of the internal performance statistics provided
1717 by the <B>1</B> setting, plus some additional, detailed performance
1718 figures about the File Server (for example, minimum, maximum, and cumulative
1719 statistics regarding File Server RPCs, how long they take to complete, and how
1723 </B><DD>Directs the command to gather statistics just one time. Omit this
1724 option to have the command continue to probe the File Server for statistics
1725 every 30 seconds. If you omit this option, you can use the
1726 <<B>Ctrl-c</B>> interrupt signal to halt the command at any
1728 <P><DT><B>-frequency
1729 </B><DD>Sets the frequency in seconds at which the program initiates probes to the
1730 File Server. If you omit this argument, the default is 30
1733 </B><DD>Sets how long the utility runs before exiting, as a number of
1734 minutes. If you omit this argument, the default is 10 minutes.
1736 </B><DD>Displays additional information as the command runs.
1739 <A NAME="IDX7238"></A>
1740 <A NAME="IDX7239"></A>
1741 <A NAME="IDX7240"></A>
1742 <A NAME="IDX7241"></A>
1743 <P><H4><A NAME="Header_404">To use the example xstat_cm_test command</A></H4>
1745 <P><LI>Issue the example <B>xstat_cm_test</B> command to test the routines in
1746 the <B>libxstat_cm.a</B> library and display the data collections
1747 associated with the Cache Manager. The command executes in the
1749 <PRE> % <B>xstat_cm_test</B> [<B>initcmd</B>] \
1750 <B>-cmname</B> <<VAR>Cache Manager name(s) to monitor</VAR>><SUP>+</SUP> \
1751 <B>-collID</B> <<VAR>Collection(s) to fetch</VAR>><SUP>+</SUP> \
1752 [<B>-onceonly</B>] [<B>-frequency</B> <<VAR>poll frequency, in seconds</VAR>>] \
1753 [<B>-period</B> <<VAR>data collection time, in minutes</VAR>>] [<B>-debug</B>]
1757 <P><DT><B>xstat_cm_test
1758 </B><DD>Must be typed in full.
1760 </B><DD>Is an optional string that accommodates the command's use of the AFS
1761 command parser. It can be omitted and ignored.
1763 </B><DD>Is the host name of each client machine on which to monitor the Cache
1766 </B><DD>Specifies each data collection to return. The indicated data
1767 collection defines the type and amount of data the command is to gather about
1768 the Cache Manager. Data is returned in the form of a predefined data
1769 structure (refer to the specification documents referenced previously for more
1770 information about the data structures).
1771 <P>There are two acceptable values:
1773 <P><LI><B>0</B> provides profiling information about the numbers of times
1774 different internal Cache Manager routines were called since the Cache manager
1776 <P><LI><B>1</B> reports various internal performance statistics related to
1777 the Cache manager (for example, statistics about how effectively the cache is
1778 being used and the quantity of intracell and intercell data access).
1779 <P><LI><B>2</B> reports all of the internal performance statistics provided
1780 by the <B>1</B> setting, plus some additional, detailed performance
1781 figures about the Cache Manager (for example, statistics about the number of
1782 RPCs sent by the Cache Manager and how long they take to complete; and
1783 statistics regarding things such as authentication, access, and PAG
1784 information associated with data access).
1787 </B><DD>Directs the command to gather statistics just one time. Omit this
1788 option to have the command continue to probe the Cache Manager for statistics
1789 every 30 seconds. If you omit this option, you can use the
1790 <<B>Ctrl-c</B>> interrupt signal to halt the command at any
1792 <P><DT><B>-frequency
1793 </B><DD>Sets the frequency in seconds at which the program initiates probes to the
1794 Cache Manager. If you omit this argument, the default is 30
1797 </B><DD>Sets how long the utility runs before exiting, as a number of
1798 minutes. If you omit this argument, the default is 10 minutes.
1800 </B><DD>Displays additional information as the command runs.
1803 <HR><H2><A NAME="HDRWQ354" HREF="auagd002.htm#ToC_405">Auditing AFS Events on AIX File Servers</A></H2>
1804 <A NAME="IDX7242"></A>
1805 <A NAME="IDX7243"></A>
1806 <A NAME="IDX7244"></A>
1807 <A NAME="IDX7245"></A>
1808 <P>You can audit AFS events on AIX File Servers using an AFS mechanism that
1809 transfers audit information from AFS to the AIX auditing system. The
1810 following general classes of AFS events can be audited. For a complete
1811 list of specific AFS audit events, see <A HREF="auagd025.htm#HDRWQ620">Appendix D, AIX Audit Events</A>.
1813 <P><LI>Authentication and Identification Events
1814 <P><LI>Security Events
1815 <P><LI>Privilege Required Events
1816 <P><LI>Object Creation and Deletion Events
1817 <P><LI>Attribute Modification Events
1818 <P><LI>Process Control Events
1820 <TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">This section assumes familiarity with the AIX auditing system. For
1821 more information, see the <I>AIX System Management Guide</I> for the
1822 version of AIX you are using.
1824 <P><H3><A NAME="Header_406" HREF="auagd002.htm#ToC_406">Configuring AFS Auditing on AIX File Servers</A></H3>
1825 <P>The directory <B>/usr/afs/local/audit</B> contains three files that
1826 contain the information needed to configure AIX File Servers to audit AFS
1829 <P><LI>The <B>events.sample</B> file contains information on auditable
1830 AFS events. The contents of this file are integrated into the
1831 corresponding AIX events file (<B>/etc/security/audit/events</B>).
1832 <P><LI>The <B>config.sample</B> file defines the six classes of AFS
1833 audit events and the events that make up each class. It also defines
1834 the classes of AFS audit events to audit for the File Server, which runs as
1835 the local superuser <B>root</B>. The contents of this file must be
1836 integrated into the corresponding AIX config file
1837 (<B>/etc/security/audit/config</B>).
1838 <P><LI>The <B>objects.sample</B> file contains a list of information
1839 about audited files. You must only audit files in the local file
1840 space. The contents of this file must be integrated into the
1841 corresponding AIX objects file
1842 (<B>/etc/security/audit/objects</B>).
1844 <P>Once you have properly configured these files to include the AFS-relevant
1845 information, use the AIX auditing system to start up and shut down the
1847 <P><H3><A NAME="Header_407" HREF="auagd002.htm#ToC_407">To enable AFS auditing</A></H3>
1849 <P><LI>Create the following string in the file <B>/usr/afs/local/Audit</B> on
1850 each File Server on which you plan to audit AFS events:
1851 <PRE> <B>AFS_AUDIT_AllEvents</B>
1853 <P><LI>Issue the <B>bos restart</B> command (with the <B>-all</B> flag)
1854 to stop and restart all server processes on each File Server. For
1855 instructions on using this command, see <A HREF="auagd009.htm#HDRWQ170">Stopping and Immediately Restarting Processes</A>.
1857 <P><H3><A NAME="Header_408" HREF="auagd002.htm#ToC_408">To disable AFS auditing</A></H3>
1859 <P><LI>Remove the contents of the file <B>/usr/afs/local/Audit</B> on each
1860 File Server for which you are no longer interested in auditing AFS
1862 <P><LI>Issue the <B>bos restart</B> command (with the <B>-all</B> flag)
1863 to stop and restart all server processes on each File Server. For
1864 instructions on using this command, see <A HREF="auagd009.htm#HDRWQ170">Stopping and Immediately Restarting Processes</A>.
1866 <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="auagd012.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="auagd014.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>
1867 <!-- Begin Footer Records ========================================== -->
1869 <br>© <A HREF="http://www.ibm.com/">IBM Corporation 2000.</A> All Rights Reserved
1871 <!-- End Footer Records ============================================ -->
1872 <A NAME="Bot_Of_Page"></A>
git://git.openafs.org / openafs.git / blob