+++ /dev/null
-<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 3//EN">
-<HTML><HEAD>
-<TITLE>Administration Guide</TITLE>
-<!-- Begin Header Records ========================================== -->
-<!-- /tmp/idwt3191/auagd000.scr converted by idb2h R4.2 (359) ID -->
-<!-- Workbench Version (AIX) on 5 Nov 1999 at 14:06:34 -->
-<META HTTP-EQUIV="updated" CONTENT="Fri, 05 Nov 1999 14:06:34">
-<META HTTP-EQUIV="review" CONTENT="Sun, 05 Nov 2000 14:06:34">
-<META HTTP-EQUIV="expires" CONTENT="Mon, 05 Nov 2001 14:06:34">
-</HEAD><BODY>
-<!-- (C) IBM Corporation 2000. All Rights Reserved -->
-<BODY bgcolor="ffffff">
-<!-- End Header Records ============================================ -->
-<A NAME="Top_Of_Page"></A>
-<H1>Administration Guide</H1>
-<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>
-<HR><H1><A NAME="HDRWQ438" HREF="auagd002.htm#ToC_360">Monitoring and Auditing AFS Performance</A></H1>
-<A NAME="IDX7094"></A>
-<A NAME="IDX7095"></A>
-<A NAME="IDX7096"></A>
-<A NAME="IDX7097"></A>
-<A NAME="IDX7098"></A>
-<A NAME="IDX7099"></A>
-<A NAME="IDX7100"></A>
-<A NAME="IDX7101"></A>
-<P>AFS comes with three main monitoring tools:
-<UL>
-<P><LI>The <B>scout</B> program, which monitors and gathers statistics on
-File Server performance.
-<P><LI>The <B>fstrace</B> command suite, which traces Cache Manager
-operations in detail.
-<P><LI>The <B>afsmonitor</B> program, which monitors and gathers statistics
-on both the File Server and the Cache Manager.
-</UL>
-<P>AFS also provides a tool for auditing AFS events on file server machines
-running AIX.
-<HR><H2><A NAME="HDRWQ439" HREF="auagd002.htm#ToC_361">Summary of Instructions</A></H2>
-<P>This chapter explains how to perform the following tasks by
-using the indicated commands:
-<BR>
-<TABLE WIDTH="100%">
-<TR>
-<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Initialize the <B>scout</B> program
-</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>scout</B>
-</TD></TR><TR>
-<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Display information about a trace log
-</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>fstrace lslog</B>
-</TD></TR><TR>
-<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Display information about an event set
-</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>fstrace lsset</B>
-</TD></TR><TR>
-<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Change the size of a trace log
-</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>fstrace setlog</B>
-</TD></TR><TR>
-<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Set the state of an event set
-</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>fstrace setset</B>
-</TD></TR><TR>
-<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Dump contents of a trace log
-</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>fstrace dump</B>
-</TD></TR><TR>
-<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Clear a trace log
-</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>fstrace clear</B>
-</TD></TR><TR>
-<TD ALIGN="LEFT" VALIGN="TOP" WIDTH="70%">Initialize the <B>afsmonitor</B> program
-</TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="30%"><B>afsmonitor</B>
-</TD></TR></TABLE>
-<HR><H2><A NAME="HDRWQ448" HREF="auagd002.htm#ToC_362">Using the scout Program</A></H2>
-<A NAME="IDX7102"></A>
-<P>The <B>scout</B> program monitors the status of the File Server process
-running on file server machines. It periodically collects statistics
-from a specified set of File Server processes, displays them in a graphical
-format, and alerts you if any of the statistics exceed a configurable
-threshold.
-<P>More specifically, the <B>scout</B> program includes the following
-features.
-<UL>
-<P><LI>You can monitor, from a single location, the File Server process on any
-number of server machines from the local and foreign cells. The number
-is limited only by the size of the display window, which must be large enough
-to display the statistics.
-<P><LI>You can set a threshold for many of the statistics. When the value
-of a statistic exceeds the threshold, the <B>scout</B> program highlights
-it (displays it in reverse video) to draw your attention to it. If the
-value goes back under the threshold, the highlighting is deactivated.
-You control the thresholds, so highlighting reflects what you consider to be a
-noteworthy situation. See <A HREF="#HDRWQ454">Highlighting Significant Statistics</A>.
-<P><LI>The <B>scout</B> program alerts you to File Server process, machine,
-and network outages by highlighting the name of each machine that does not
-respond to its probe, enabling you to respond more quickly.
-<P><LI>You can set how often the <B>scout</B> program collects statistics
-from the File Server processes.
-</UL>
-<P><H3><A NAME="HDRWQ449" HREF="auagd002.htm#ToC_363">System Requirements</A></H3>
-<A NAME="IDX7103"></A>
-<A NAME="IDX7104"></A>
-<A NAME="IDX7105"></A>
-<A NAME="IDX7106"></A>
-<A NAME="IDX7107"></A>
-<A NAME="IDX7108"></A>
-<A NAME="IDX7109"></A>
-<P>The <B>scout</B> program runs on any AFS client machine that has access
-to the <B>curses</B> graphics package, which most UNIX distributions
-include as a standard utility. It can run on both dumb terminals and
-under windowing systems that emulate terminals, but the output looks best on
-machines that support reverse video and cursor addressing. For best
-results, set the TERM environment variable to the correct terminal type, or
-one with characteristics similar to the actual ones. For machines
-running AIX, the recommended TERM setting is <B>vt100</B>, assuming the
-terminal is similar to that. For other operating systems, the wider
-range of acceptable values includes <B>xterm</B>, <B>xterms</B>,
-<B>vt100</B>, <B>vt200</B>, and <B>wyse85</B>.
-<A NAME="IDX7110"></A>
-<P>No privilege is required to run the <B>scout</B> program, so any user
-who can access the directory where its binary resides (the
-<B>/usr/afsws/bin</B> directory in the conventional configuration) can use
-it. The program's probes for collecting statistics do not impose a
-significant burden on the File Server process, but you can restrict its use by
-placing the binary file in a directory with a more restrictive access control
-list (ACL).
-<P>Multiple instances of the <B>scout</B> program can run on a single
-client machine, each over its own dedicated connection (in its own
-window). It must run in the foreground, so the window in which it runs
-does not accept further input except for an interrupt signal.
-<P>You can also run the <B>scout</B> program on several machines and view
-its output on a single machine, by opening telnet connections to the other
-machines from the central one and initializing the program in each remote
-window. In this case, you can include the <B>-host</B> flag to the
-<B>scout</B> command to make the name of each remote machine appear in the
-<I>banner line</I> at the top of the window displaying its output.
-See <A HREF="#HDRWQ452">The Banner Line</A>.
-<P><H3><A NAME="HDRWQ450" HREF="auagd002.htm#ToC_364">Using the -basename argument to Specify a Domain Name</A></H3>
-<A NAME="IDX7111"></A>
-<A NAME="IDX7112"></A>
-<P>As previously mentioned, the <B>scout</B> program can monitor the File
-Server process on any number of file server machines. If all of the
-machines belong to the same cell, then their hostnames probably all have the
-same domain name suffix, such as <B>abc.com</B> in the ABC
-Corporation cell. In this case, you can use the <B>-basename</B>
-argument to the <B>scout</B> command, which has several advantages:
-<UL>
-<P><LI>You can omit the domain name suffix as you enter each file server
-machine's name on the command line. The <B>scout</B> program
-automatically appends the domain name to each machine's name, resulting
-in a fully-qualified hostname. You can omit the domain name suffix even
-when you don't include the <B>-basename</B> argument, but in that
-case correct resolution of the name depends on the state of your cell's
-naming service at the time of connection.
-<P><LI>The machine names are more likely to fit in the appropriate column of the
-display without having to be truncated (for more on truncating names in the
-display column, see <A HREF="#HDRWQ453">The Statistics Display Region</A>).
-<P><LI>The domain name appears in the banner line at the top of the display
-window to indicate the name of the cell you are monitoring.
-</UL>
-<P><H3><A NAME="HDRWQ451" HREF="auagd002.htm#ToC_365">The Layout of the scout Display</A></H3>
-<A NAME="IDX7113"></A>
-<A NAME="IDX7114"></A>
-<P>The <B>scout</B> program can display statistics either in a dedicated
-window or on a plain screen if a windowing environment is not
-available. For best results, use a window or screen that can print in
-reverse video and do cursor addressing.
-<P>The <B>scout</B> program screen has three main regions: the
-<I>banner line</I>, the <I>statistics display region</I> and the
-<I>probe/message line</I>. This section describes their contents,
-and graphic examples appear in <A HREF="#HDRWQ458">Example Commands and Displays</A>.
-<P><H4><A NAME="HDRWQ452">The Banner Line</A></H4>
-<A NAME="IDX7115"></A>
-<A NAME="IDX7116"></A>
-<P>By default, the string <TT>scout</TT> appears in the banner line at the
-top of the window or screen, to indicate that the <B>scout</B> program is
-running. You can display two additional types of information by include
-the appropriate option on the command line:
-<UL>
-<P><LI>Include the <B>-host</B> flag to display the local machine's name
-in the banner line. This is particularly useful when you are running
-the <B>scout</B> program on several machines but displaying the results on
-a single machine.
-<P>For example, the following banner line appears when you run the
-<B>scout</B> program on the machine
-<B>client1.abc.com</B> and use the<B>-host</B>
-flag:
-<PRE> [client1.abc.com] scout
-</PRE>
-<P><LI>Include the <B>-basename</B> argument to display the specified cell
-domain name in the banner line. For further discussion, see <A HREF="#HDRWQ450">Using the -basename argument to Specify a Domain Name</A>.
-<P>For example, if you specify a value of <B>abc.com</B> for the
-<B>-basename</B> argument, the banner line reads:
-<PRE> scout for abc.com
-</PRE>
-</UL>
-<P><H4><A NAME="HDRWQ453">The Statistics Display Region</A></H4>
-<A NAME="IDX7117"></A>
-<A NAME="IDX7118"></A>
-<P>The statistics display region occupies most of the window and is divided
-into six columns. The following list describes them as they appear from
-left to right in the window.
-<DL>
-<P><DT><B><TT>Conn</TT>
-<A NAME="IDX7119"></A>
-</B><DD>Displays the number of RPC connections open between the File Server
-process and client machines. This number normally equals or exceeds the
-number in the fourth <TT>Ws</TT> column. It can exceed the number in
-that column because each user on the machine can have more than one connection
-open at once, and one client machine can handle several users.
-<P><DT><B><TT>Fetch</TT>
-<A NAME="IDX7120"></A>
-</B><DD>Displays the number of fetch-type RPCs (fetch data, fetch access list, and
-fetch status) that the File Server process has received from client machines
-since it started. It resets to zero when the File Server process
-restarts.
-<P><DT><B><TT>Store</TT>
-<A NAME="IDX7121"></A>
-</B><DD>Displays the number of store-type RPCs (store data, store access list, and
-store status) that the File Server process has received from client machines
-since it started. It resets to zero when the File Server process
-restarts.
-<P><DT><B><TT>Ws</TT>
-<A NAME="IDX7122"></A>
-<A NAME="IDX7123"></A>
-<A NAME="IDX7124"></A>
-</B><DD>Displays the number of client machines (workstations) that have
-communicated with the File Server process within the last 15 minutes (such
-machines are termed <I>active</I>). This number is likely to be
-smaller than the number in the <TT>Conn</TT>) column because a single client
-machine can have several connections open to one File Server process.
-<P><DT><B>[Unlabeled column]
-</B><DD>Displays the name of the file server machine on which the File Server
-process is running. It is 12 characters wide. Longer names are
-truncated and an asterisk (<TT>*</TT>) appears as the last character in the
-name. If all machines have the same domain name suffix, you can use the
-<B>-basename</B> argument to decrease the need for truncation; see <A HREF="#HDRWQ450">Using the -basename argument to Specify a Domain Name</A>.
-<P><DT><B><TT>Disk attn</TT>
-<A NAME="IDX7125"></A>
-<A NAME="IDX7126"></A>
-<A NAME="IDX7127"></A>
-<A NAME="IDX7128"></A>
-</B><DD>Displays the number of kilobyte blocks available on up to 26 of the file
-server machine's AFS server (<B>/vicep</B>) partitions. The
-display for each partition has the following format:
-<PRE> <VAR>partition_letter</VAR>:<VAR>free_blocks</VAR>
-</PRE>
-<P>
-<P>For example, <TT>a:8949</TT> indicates that partition
-<B>/vicepa</B> has 8,949 KB free. If the window is not wide enough
-for all partition entries to appear on a single line, the <B>scout</B>
-program automatically stacks the partition entries into subcolumns within the
-sixth column.
-<P>The label on the <TT>Disk attn</TT> column indicates the threshold value
-at which entries in the column become highlighted. By default, the
-<B>scout</B> program highlights a partition that is over 95% full, in
-which case the label is as follows:
-<PRE> Disk attn: > 95% used
-</PRE>
-<P>
-<P>For more on this threshold and its effect on highlighting, see <A HREF="#HDRWQ454">Highlighting Significant Statistics</A>.
-</DL>
-<P>For all columns except the fifth (file server machine name), you can use
-the <B>-attention</B> argument to set a threshold value above which the
-<B>scout</B> program highlights the statistic. By default, only
-values in the fifth and sixth columns ever become highlighted. For
-instructions on using the <B>-attention</B> argument, see <A HREF="#HDRWQ454">Highlighting Significant Statistics</A>.
-<P><H4><A NAME="Header_368">The Probe Reporting Line</A></H4>
-<A NAME="IDX7129"></A>
-<A NAME="IDX7130"></A>
-<P>The bottom line of the display indicates how many times the
-<B>scout</B> program has probed the File Server processes for
-statistics. The statistics gathered in the latest probe appear in the
-statistics display region. By default, the <B>scout</B> program
-probes the File Servers every 60 seconds, but you can use the
-<B>-frequency</B> argument to specify a different probe frequency.
-<P><H3><A NAME="HDRWQ454" HREF="auagd002.htm#ToC_369">Highlighting Significant Statistics</A></H3>
-<A NAME="IDX7131"></A>
-<A NAME="IDX7132"></A>
-<A NAME="IDX7133"></A>
-<A NAME="IDX7134"></A>
-<P>To draw your attention to a statistic that currently exceed a threshold
-value, the <B>scout</B> program displays it in reverse video (highlights
-it). You can set the threshold value for most statistics, and so
-determine which values are worthy of special attention and which are
-normal.
-<P><H4><A NAME="HDRWQ455">Highlighting Server Outages</A></H4>
-<A NAME="IDX7135"></A>
-<A NAME="IDX7136"></A>
-<A NAME="IDX7137"></A>
-<A NAME="IDX7138"></A>
-<A NAME="IDX7139"></A>
-<P>The only column in which you cannot control highlighting is the fifth,
-which identifies the file server machine for which statistics are displayed in
-the other columns. The <B>scout</B> program uses highlighting in
-this column to indicate that the File Server process on a machine fails to
-respond to its probe, and automatically blanks out the other columns.
-Failure to respond to the probe can indicate a File Server process, file
-server machine, or network outage, so the highlighting draws your attention to
-a situation that is probably interrupting service to users.
-<P>When the File Server process once again responds to the probes, its name
-appears normally and statistics reappear in the other columns. If all
-machine names become highlighted at once, a possible network outage has
-disrupted the connection between the file server machines and the client
-machine running the <B>scout</B> program.
-<P><H4><A NAME="Header_371">Highlighting for Extreme Statistic Values</A></H4>
-<P>To set the threshold value for one or more of the five
-statistics-displaying columns, use the <B>-attention</B> argument.
-The threshold value applies to all File Server processes you are monitoring
-(you cannot set different thresholds for different machines). For
-details, see the syntax description in <A HREF="#HDRWQ457">To start the scout program</A>.
-<P>It is not possible to change the threshold values for a running
-<B>scout</B> program. Stop the current program and start a new
-one. Also, the <B>scout</B> program does not retain threshold
-values across restarts, so you must specify all thresholds every time you
-start the program.
-<P><H3><A NAME="HDRWQ456" HREF="auagd002.htm#ToC_372">Resizing the scout Display</A></H3>
-<A NAME="IDX7140"></A>
-<A NAME="IDX7141"></A>
-<A NAME="IDX7142"></A>
-<P>Do not resize the display window while the <B>scout</B> program is
-running. Increasing the size does no harm, but the <B>scout</B>
-program does not necessarily adjust to the new dimensions. Decreasing
-the display's width can disturb column alignment, making the display
-harder to read. With any type of resizing, the <B>scout</B> program
-does not adjust the display in any way until it displays the results of the
-next probe.
-<P>To resize the display effectively, stop the <B>scout</B> program,
-resize the window and then restart the program. Even in this case, the
-<B>scout</B> program's response depends on the accuracy of the
-information it receives from the display environment. Testing during
-development has shown that the display environment does not reliably provide
-information about window resizing. If you use the X windowing system,
-issuing the following sequence of commands before starting the
-<B>scout</B> program (or placing them in the shell initialization file)
-sometimes makes it adjust properly to resizing.
-<PRE> %<B> set noglob</B>
- % <B>eval '/usr/bin/X11/resize'</B>
- % <B>unset noglob</B>
-</PRE>
-<A NAME="IDX7143"></A>
-<A NAME="IDX7144"></A>
-<A NAME="IDX7145"></A>
-<A NAME="IDX7146"></A>
-<A NAME="IDX7147"></A>
-<P><H3><A NAME="HDRWQ457" HREF="auagd002.htm#ToC_373">To start the scout program</A></H3>
-<OL TYPE=1>
-<P><LI>Open a dedicated command shell. If necessary, adjust it to the
-appropriate size.
-<P><LI>Issue the <B>scout</B> command to start the program.
-<PRE> % <B>scout</B> [<B>initcmd</B>] <B>-server</B> <<VAR>FileServer name(s) to monitor</VAR>><SUP>+</SUP> \
- [<B>-basename</B> <<VAR>base server name</VAR>>] \
- [<B>-frequency</B> <<VAR>poll frequency, in seconds</VAR>>] [<B>-host</B>] \
- [<B>-attention</B> <<VAR>specify attention (highlighting) level</VAR>><SUP>+</SUP>] \
- [<B>-debug</B> <<VAR>turn debugging output on to the named file</VAR>>]
-</PRE>
-<P>where
-<DL>
-<P><DT><B>initcmd
-</B><DD>Is an optional string that accommodates the command's use of the AFS
-command parser. It can be omitted and ignored.
-<P><DT><B>-server
-</B><DD>Identifies each File Server process to monitor, by naming the file server
-machine it is running on. Provide fully-qualified hostnames unless the
-<B>-basename</B> argument is used. In that case, specify only the
-initial part of each machine name, omitting the domain name suffix common to
-all the machine names.
-<P><DT><B>-basename
-</B><DD>Specifies the domain name suffix common to all of the file server machines
-named by the <B>-server</B> argument. For discussion of this
-argument's effects, see <A HREF="#HDRWQ450">Using the -basename argument to Specify a Domain Name</A>.
-<P>Do not include the period that separates the domain suffix from the initial
-part of the machine name, but do include any periods that occur within the
-suffix itself. (For example, in the ABC Corporation cell, the proper
-value is <B>abc.com</B>, not
-<B>.abc.com</B>.)
-<P><DT><B>-frequency
-</B><DD>Sets the frequency, in seconds, of the <B>scout</B> program's
-probes to File Server processes. Specify an integer greater than 0
-(zero). The default is 60 seconds.
-<P><DT><B>-host
-</B><DD>Displays the name of the machine that is running the <B>scout</B>
-program in the display window's banner line. By default, no
-machine name is displayed.
-<P><DT><B>-attention
-</B><DD>Defines the threshold value at which to highlight one or more
-statistics. You can provide the pairs of statistic and threshold in any
-order, separating each pair and the parts of each pair with one or more
-spaces. The following list defines the syntax for each
-statistic.
-<A NAME="IDX7148"></A>
-<A NAME="IDX7149"></A>
-<A NAME="IDX7150"></A>
-<DL>
-<P><DT><B>conn <VAR>connections</VAR>
-</B><DD>Highlights the value in the <TT>Conn</TT> (first) column when the number
-of connections that the File Server has open to client machines exceeds the
-<VAR>connections</VAR> value. The highlighting deactivates when the value
-goes back below the threshold. There is no default threshold.
-<P><DT><B>fetch <VAR>fetch_RPCs</VAR>
-</B><DD>Highlights the value in the <TT>Fetch</TT> (second) column when the
-number of fetch RPCs that clients have made to the File Server process exceeds
-the <VAR>fetch_RPCs</VAR> value. The highlighting deactivates only when
-the File Server process restarts, at which time the value returns to
-zero. There is no default threshold.
-<P><DT><B>store <VAR>store_RPCs</VAR>
-</B><DD>Highlights the value in the <TT>Store</TT> (third) column when the
-number of store RPCs that clients have made to the File Server process exceeds
-the <VAR>store_RPCs</VAR> value. The highlighting deactivates only when
-the File Server process restarts, at which time the value returns to
-zero. There is no default threshold.
-<P><DT><B>ws <VAR>active_clients</VAR>
-</B><DD>Highlights the value in the <TT>Ws</TT> (fourth) column when the number
-of active client machines (those that have contacted the File Server in the
-last 15 minutes) exceeds the <VAR>active_clients</VAR> value. The
-highlighting deactivates when the value goes back below the threshold.
-There is no default threshold.
-<P><DT><B>disk <VAR>percent_full</VAR> % or disk <VAR>min_blocks</VAR>
-</B><DD>Highlights the value for a partition in the <TT>Disk attn</TT> (sixth)
-column when either the amount of disk space used exceeds the percentage
-indicated by the<VAR>percent_full</VAR> value, or the number of free KB blocks
-is less than the <VAR>min_blocks</VAR> value. The highlighting
-deactivates when the value goes back below the <VAR>percent_full</VAR> threshold
-or above the <VAR>min_blocks</VAR> threshold.
-<P>The value you specify appears in the header of the sixth column following
-the string <TT>Disk attn</TT>. The default threshold is 95%
-full.
-<P>Acceptable values for <VAR>percent_full</VAR> are the integers from the range
-<B>0</B> (zero) to <B>99</B>, and you must include the percent sign to
-distinguish this statistic from a <VAR>min_blocks</VAR> value..
-</DL>
-<P>The following example sets the threshold for the <TT>Conn</TT> column to
-100, for the <TT>Ws</TT> column to 50, and for the <TT>Disk attn</TT>
-column to 75%. There is no threshold for the <TT>Fetch</TT> and
-<TT>Store</TT> columns.
-<P><B>-attention conn 100 ws 50 disk 75%</B>
-<P>The following example has the same affect as the previous one except that
-it sets the threshold for the <TT>Disk attn</TT> column to 5000 free KB
-blocks:
-<P><B>-attention disk 5000 ws 50 conn 100</B>
-<P><DT><B>-debug
-</B><DD>Enables debugging output and directs it into the specified file.
-Partial pathnames are interpreted relative to the current working
-directory. By default, no debugging output is produced.
-</DL>
-</OL>
-<P><H3><A NAME="Header_374" HREF="auagd002.htm#ToC_374">To stop the scout program</A></H3>
-<A NAME="IDX7151"></A>
-<OL TYPE=1>
-<P><LI>Enter <B>Ctrl-c</B> in the display window. This is the proper
-interrupt signal even if the general interrupt signal in your environment is
-different.
-</OL>
-<P><H3><A NAME="HDRWQ458" HREF="auagd002.htm#ToC_375">Example Commands and Displays</A></H3>
-<A NAME="IDX7152"></A>
-<A NAME="IDX7153"></A>
-<P>This section presents examples of the <B>scout</B> program, combining
-different arguments and illustrating the screen displays that result.
-<P>In the first example, an administrator in the ABC Corporation issues the
-<B>scout</B> command without providing any optional arguments or
-flags. She includes the <B>-server</B> argument because she is
-providing multiple machine names. She chooses to specify on the initial
-part of each machine's name even though she has not used the
-<B>-basename</B> argument, relying on the cell's name service to
-obtain the fully-qualified name that the <B>scout</B> program requires for
-establishing a connection.
-<PRE> % <B>scout -server fs1 fs2</B>
-</PRE>
-<P><A HREF="#FIGWQ459">Figure 2</A> depicts the resulting display. Notice first that the
-machine names in the fifth (unlabeled) column appear in the format the
-administrator used on the command line. Now consider the second line in
-the display region, where the machine name <TT>fs2</TT> appears in the fifth
-column. The <TT>Conn</TT> and <TT>Ws</TT> columns together show
-that machine <B>fs2</B> has 144 RPC connections open to 44 client
-machines, demonstrating that multiple connections per client machine are
-possible. The <TT>Fetch</TT> column shows that client machines have
-made 2,734,278 fetch RPCs to machine <B>fs2</B> since the File Server
-process last started and the <TT>Store</TT> column shows that they have made
-34,066 store RPCs.
-<P>Six partition entries appear in the <TT>Disk attn</TT> column, marked
-<TT>a</TT> through <TT>f</TT> (for <B>/vicepa</B> through
-<B>/vicepf</B>). They appear on three lines in two subcolumns
-because of the width of the window; if the window is wider, there are
-more subcolumns. Four of the partition entries (<TT>a</TT>,
-<TT>c</TT>, <TT>d</TT>, and <TT>e</TT>) appear in reverse video to
-indicate that they are more than 95% full (the threshold value that appears in
-the <TT>Disk attn</TT> header).
-<P><B><A NAME="FIGWQ459" HREF="auagd003.htm#FT_FIGWQ459">Figure 2. First example scout display</A></B><BR>
-<TABLE BORDER ><TR><TD><BR>
-<B><BR><IMG SRC="scout1.gif" ALT="First example scout display"><BR></B><BR>
-</TD></TR></TABLE>
-<P>In the second example, the administrator uses more of the <B>scout</B>
-program's optional arguments.
-<UL>
-<P><LI>She provides the machine names in the same form as in Example 1, but this
-time she also uses the <B>-basename</B> argument to specify their domain
-name suffix, <B>abc.com</B>. This implies that the
-<B>scout</B> program does not need the name service to expand the names to
-fully-qualified hostnames, but the name service still converts the hostnames
-to IP addresses.
-<P><LI>She uses the <B>-host</B> flag to display in the banner line the name
-of the client machine where the <B>scout</B> program is running.
-<P><LI>She uses the <B>-frequency</B> argument to changes the probing
-frequency from its default of once per minute to once every five
-seconds.
-<P><LI>She uses the <B>-attention</B> argument to changes the highlighting
-threshold for partitions to a 5000 KB minimum rather than the default of 95%
-full.
-</UL>
-<PRE> % <B>scout -server fs1 fs2 -basename abc.com -host -frequency 5 -attention disk 5000</B>
-</PRE>
-<P>The use of optional arguments results in several differences between <A HREF="#FIGWQ460">Figure 3</A> and <A HREF="#FIGWQ459">Figure 2</A>. First, because the <B>-host</B>
-flag is included, the banner line displays the name of the machine running the
-<B>scout</B> process as <TT>[client52]</TT> along with the basename
-<TT>abc.com</TT> specified with the <B>-basename</B>
-argument.
-<P>Another difference is that two rather than four of machine
-<B>fs2</B>'s partitions appear in reverse video, even though their
-values are almost the same as in <A HREF="#FIGWQ459">Figure 2</A>. This is because the administrator changed the
-highlight threshold to a 5000 block minimum, as also reflected in the
-<TT>Disk attn</TT> column's header. And while machine
-<B>fs2</B>'s partitions <B>/vicepa</B> and <B>/vicepd</B> are
-still 95% full, they have more than 5000 free blocks left; partitions
-<B>/vicepc</B> and <B>/vicepe</B> are highlighted because they have
-fewer than 5000 blocks free.
-<P>Note also the result of changing the probe frequency, reflected in the
-probe reporting line at the bottom left corner of the display. Both
-this example and the previous one represent a time lapse of one minute after
-the administrator issues the <B>scout</B> command. In this example,
-however, the <B>scout</B> program has probed the File Server processes 12
-times as opposed to once
-<P><B><A NAME="FIGWQ460" HREF="auagd003.htm#FT_FIGWQ460">Figure 3. Second example scout display</A></B><BR>
-<TABLE BORDER ><TR><TD><BR>
-<B><BR><IMG SRC="scout2.gif" ALT="Second example scout display"><BR></B><BR>
-</TD></TR></TABLE>
-<P>In <A HREF="#FIGWQ461">Figure 4</A>, an administrator in the State University cell monitors
-three of that cell's file server machines. He uses the
-<B>-basename</B> argument to specify the <B>stateu.edu</B>
-domain name.
-<PRE> % <B>scout -server server2 server3 server4 -basename stateu.edu</B>
-</PRE>
-<P><B><A NAME="FIGWQ461" HREF="auagd003.htm#FT_FIGWQ461">Figure 4. Third example scout display</A></B><BR>
-<TABLE BORDER ><TR><TD><BR>
-<B><BR><IMG SRC="scout3.gif" ALT="Third example scout display"><BR></B><BR>
-</TD></TR></TABLE>
-<P><A HREF="#FIGWQ462">Figure 5</A> illustrates three of the <B>scout</B> program's
-features. First, you can monitor file server machines from different
-cells in a single display: <B>fs1.abc.com</B>,
-<B>server3.stateu.edu</B>, and
-<B>sv7.def.com</B>. Because the machines belong to
-different cells, it is not possible to provide the <B>-basename</B>
-argument.
-<P>Second, it illustrates how the display must truncate machine names that do
-not fit in the fifth column, using an asterisk at the end of the name to show
-that it is shortened.
-<P>Third, it illustrates what happens when the <B>scout</B> process cannot
-reach a File Server process, in this case the one on the machine
-<B>sv7.def.com</B>: it highlights the machine name and
-blanks out the values in the other columns.
-<P><B><A NAME="FIGWQ462" HREF="auagd003.htm#FT_FIGWQ462">Figure 5. Fourth example scout display</A></B><BR>
-<TABLE BORDER ><TR><TD><BR>
-<B><BR><IMG SRC="scout4.gif" ALT="Fourth example scout display"><BR></B><BR>
-</TD></TR></TABLE>
-<HR><H2><A NAME="HDRWQ463" HREF="auagd002.htm#ToC_376">Using the fstrace Command Suite</A></H2>
-<P>This section describes the <B>fstrace</B> commands that
-system administrators employ to trace Cache Manager activity for debugging
-purposes. It assumes the reader is familiar with the Cache Manager
-concepts described in <A HREF="auagd015.htm#HDRWQ512">Administering Client Machines and the Cache Manager</A>.
-<P>The <B>fstrace</B> command suite monitors the internal activity of the
-Cache Manager and enables you to record, or trace, its operations in
-detail. The operations, which are termed <I>events</I>, comprise
-the <B>cm</B> <I>event set</I>. Examples of <B>cm</B>
-events are fetching files and looking up information for a listing of files
-and subdirectories using the UNIX <B>ls</B> command.
-<P>Following are the <B>fstrace</B> commands and their respective
-functions:
-<UL>
-<P><LI>The <B>fstrace apropos</B> command provides a short description of
-commands.
-<P><LI>The <B>fstrace clear</B> command clears the trace log.
-<P><LI>The <B>fstrace dump</B> command dumps the contents of the trace
-log.
-<P><LI>The <B>fstrace help</B> command provides a description and syntax for
-commands.
-<P><LI>The <B>fstrace lslog</B> command lists information about the trace
-log.
-<P><LI>The <B>fstrace lsset</B> command lists information about the event
-set.
-<P><LI>The <B>fstrace setlog</B> command changes the size of the trace
-log.
-<P><LI>The <B>fstrace setset</B> command sets the state of the event
-set.
-</UL>
-<P><H3><A NAME="HDRWQ464" HREF="auagd002.htm#ToC_377">About the fstrace Command Suite</A></H3>
-<P>The <B>fstrace</B> command suite replaces and greatly
-expands the functionality formerly provided by the <B>fs debug</B>
-command. Its intended use is to aid in diagnosis of specific Cache
-Manager problems, such as client machine hangs, cache consistency problems,
-clock synchronization errors, and failures to access a volume or AFS
-file. Therefore, it is best not to keep <B>fstrace</B> logging
-enabled at all times, unlike the logging for AFS server processes.
-<P>Most of the messages in the trace log correspond to low-level Cache Manager
-operations. It is likely that only personnel familiar with the AFS
-source code can interpret them. If you have an AFS source license, you
-can attempt to interpret the trace yourself, or work with the AFS Product
-Support group to resolve the underlying problems. If you do not have an
-AFS source license, it is probably more efficient to contact the AFS Product
-Support group immediately in case of problems. They can instruct you to
-activate <B>fstrace</B> tracing if appropriate.
-<P>The log can grow in size very quickly; this can use valuable disk
-space if you are writing to a file in the local file space.
-Additionally, if the size of the log becomes too large, it can become
-difficult to parse the results for pertinent information.
-<A NAME="IDX7154"></A>
-<A NAME="IDX7155"></A>
-<P>When AFS tracing is enabled, each time a <B>cm</B> event occurs, a
-message is written to the trace log, <B>cmfx</B>. To diagnose a
-problem, read the output of the trace log and analyze the operations executed
-by the Cache Manager. The default size of the trace log is 60 KB, but
-you can increase or decrease it.
-<A NAME="IDX7156"></A>
-<A NAME="IDX7157"></A>
-<P>To use the <B>fstrace</B> command suite, you must first enable tracing
-and reserve, or allocate, space for the trace log with the <B>fstrace
-setset</B> command. With this command, you can set the <B>cm</B>
-event set to one of three states to enable or disable tracing for the event
-set and to allocate or deallocate space for the trace log in the kernel:
-<A NAME="IDX7158"></A>
-<A NAME="IDX7159"></A>
-<A NAME="IDX7160"></A>
-<DL>
-<P><DT><B>active
-</B><DD>Enables tracing for the event set and allocates space for the trace
-log.
-<P><DT><B>inactive
-</B><DD>Temporarily disables tracing for the event set; however, the event
-set continues to allocate space occupied by the log to which it sends
-data.
-<P><DT><B>dormant
-</B><DD>Disables tracing for the event set; furthermore, the event set
-releases the space occupied by the log to which it sends data. When the
-<B>cm</B> event set that sends data to the <B>cmfx</B> trace log is in
-this state, the space allocated for that log is freed or deallocated.
-</DL>
-<A NAME="IDX7161"></A>
-<A NAME="IDX7162"></A>
-<A NAME="IDX7163"></A>
-<P>Both event sets and trace logs can be designated as <I>persistent</I>,
-which prevents accidental resetting of an event set's state or clearing
-of a trace log. The designation is made as the kernel is compiled and
-cannot be changed.
-<P>If an event set such as <B>cm</B> is persistent, you can change its
-state only by including the <B>-set</B> argument to the <B>fstrace
-setset</B> command. (That is, you cannot change its state along with
-the state of all other event sets by issuing the <B>fstrace setset</B>
-command with no arguments.) Similarly, if a trace log such as
-<B>cmfx</B> is persistent, you can clear it only by including either the
-<B>-set</B> or <B>-log</B> argument to the <B>fstrace clear</B>
-command (you cannot clear it along with all other trace logs by issuing the
-<B>fstrace clear</B> command with no arguments.)
-<P>When a problem occurs, set the <B>cm</B> event set to active using the
-<B>fstrace setset</B> command. When tracing is enabled on a busy
-AFS client, the volume of events being recorded is significant;
-therefore, when you are diagnosing problems, restrict AFS activity as much as
-possible to minimize the amount of extraneous tracing in the log.
-Because tracing can have a negative impact on system performance, leave
-<B>cm</B> tracing in the dormant state when you are not diagnosing
-problems.
-<P>If a problem is reproducible, clear the <B>cmfx</B> trace log with the
-<B>fstrace clear</B> command and reproduce the problem. If the
-problem is not easily reproduced, keep the state of the event set active until
-the problem recurs.
-<P>To view the contents of the trace log and analyze the <B>cm</B> events,
-use the <B>fstrace dump</B> command to copy the content lines of the trace
-log to standard output (stdout) or to a file.
-<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
-id (PID). Search the output of the <B>fstrace dump</B> command for
-the PID to find only those lines associated with the problem.
-</TD></TR></TABLE>
-<P><H3><A NAME="HDRWQ465" HREF="auagd002.htm#ToC_378">Requirements for Using the fstrace Command Suite</A></H3>
-<A NAME="IDX7164"></A>
-<A NAME="IDX7165"></A>
-<P>Except for the <B>fstrace help</B> and <B>fstrace apropos</B>
-commands, which require no privilege, issuing the <B>fstrace</B> commands
-requires that the issuer be logged in as the local superuser <B>root</B>
-on the local client machine. Before issuing an <B>fstrace</B>
-command, verify that you have the necessary privilege.
-<P>The Cache Manager catalog must be in place so that logging can
-occur. The <B>fstrace</B> command suite uses the standard UNIX
-catalog utilities. The default location is
-<B>/usr/vice/etc/C/afszcm.cat</B>. It can be placed in
-another directory by placing the file elsewhere and using the proper NLSPATH
-and LANG environment variables.
-<P><H3><A NAME="Header_379" HREF="auagd002.htm#ToC_379">Using fstrace Commands Effectively</A></H3>
-<P>To use <B>fstrace</B> commands most effectively, configure them as
-indicated:
-<UL>
-<P><LI>Store the <B>fstrace</B> binary in a local disk directory.
-<P><LI>When you dump the <B>fstrace</B> log to a file, direct it to one on
-the local disk.
-<P><LI>The trace can grow large in just a few minutes. Before attempting
-to dump the log to a local file, verify that you have enough room. Be
-particularly careful if you are using disk quotas on partitions in the local
-file system.
-<P><LI>Attempt to limit Cache Manager activity on the AFS client machine other
-than the problem operation. This reduces the amount of extraneous data
-in the trace.
-<P><LI>Activate the <B>fstrace</B> log for the shortest possibly period of
-time. If possible activate the trace immediately before performing the
-problem operation, deactivate it as soon as the operation completes, and dump
-the trace log to a file immediately.
-<P><LI>If possible, obtain UNIX process ID (PID) of the command or program that
-initiates the problematic operation. This enables the person analyzing
-the trace log to search it for messages associated with the PID.
-</UL>
-<P><H3><A NAME="HDRWQ466" HREF="auagd002.htm#ToC_380">Activating the Trace Log</A></H3>
-<P>To start Cache Manager tracing on an AFS client machine, you
-must first configure
-<UL>
-<P><LI>The <B>cmfx</B> kernel trace log using the <B>fstrace setlog</B>
-command
-<P><LI>The <B>cm</B> event set using the <B>fstrace setset</B> command
-</UL>
-<P>The <B>fstrace setlog</B> command sets the size of the <B>cmfx</B>
-kernel trace log in kilobytes. The trace log occupies 60 kilobytes of
-kernel by default. If the trace log already exists, it is cleared when
-this command is issued and a new log of the given size is created.
-Otherwise, a new log of the desired size is created.
-<P>The <B>fstrace setset</B> command sets the state of the <B>cm</B>
-kernel event set. The state of the <B>cm</B> event set determines
-whether information on the events in that event set is logged.
-<P>After establishing kernel tracing on the AFS client machine, you can check
-the state of the event set and the size of the kernel buffer allocated for the
-trace log. To display information about the state of the <B>cm</B>
-event set, issue the <B>fstrace lsset</B> command. To display
-information about the <B>cmfx</B> trace log, use the <B>fstrace
-lslog</B> command. See the instructions in <A HREF="#HDRWQ468">Displaying the State of a Trace Log or Event Set</A>.
-<A NAME="IDX7166"></A>
-<A NAME="IDX7167"></A>
-<A NAME="IDX7168"></A>
-<A NAME="IDX7169"></A>
-<P><H3><A NAME="Header_381" HREF="auagd002.htm#ToC_381">To configure the trace log</A></H3>
-<OL TYPE=1>
-<P><LI>Become the local superuser <B>root</B> on the machine, if you are not
-already, by issuing the <B>su</B> command.
-<PRE> % <B>su root</B>
- Password: <VAR>root_password</VAR>
-</PRE>
-<P><LI>Issue the <B>fstrace setlog</B> command to set the size of the
-<B>cmfx</B> kernel trace log.
-<PRE> # <B>fstrace setlog</B> [<B>-log</B> <<VAR>log_name</VAR>><SUP>+</SUP>] <B>-buffersize</B> <<VAR>1-kilobyte_units</VAR>>
-</PRE>
-</OL>
-<P>The following example sets the size of the <B>cmfx</B> trace log to 80
-KB.
-<PRE> # <B>fstrace setlog cmfx 80</B>
-</PRE>
-<A NAME="IDX7170"></A>
-<A NAME="IDX7171"></A>
-<A NAME="IDX7172"></A>
-<A NAME="IDX7173"></A>
-<P><H3><A NAME="HDRWQ467" HREF="auagd002.htm#ToC_382">To set the event set</A></H3>
-<OL TYPE=1>
-<P><LI>Become the local superuser <B>root</B> on the machine, if you are not
-already, by issuing the <B>su</B> command.
-<PRE> % <B>su root</B>
- Password: <VAR>root_password</VAR>
-</PRE>
-<P><LI>Issue the <B>fstrace setset</B> command to set the state of event
-sets.
-<PRE> % <B>fstrace setset</B> [<B>-set</B> <<VAR>set_name</VAR>><SUP>+</SUP>] [<B>-active</B>] [<B>-inactive</B>] \
- [<B>-dormant</B>]
-</PRE>
-</OL>
-<P>The following example activates the <B>cm</B> event set.
-<PRE> # <B>fstrace setset cm -active</B>
-</PRE>
-<P><H3><A NAME="HDRWQ468" HREF="auagd002.htm#ToC_383">Displaying the State of a Trace Log or Event Set</A></H3>
-<P>An event set must be in the <I>active</I> state to be
-included in the trace log. To display an event set's state, use
-the <B>fstrace lsset</B> command. To set its state, issue the
-<B>fstrace setset</B> command as described in <A HREF="#HDRWQ467">To set the event set</A>.
-<P>To display size and allocation information for the trace log, issue the
-<B>fstrace lslog</B>command with the <B>-long</B> argument.
-<A NAME="IDX7174"></A>
-<A NAME="IDX7175"></A>
-<A NAME="IDX7176"></A>
-<A NAME="IDX7177"></A>
-<P><H3><A NAME="Header_384" HREF="auagd002.htm#ToC_384">To display the state of an event set</A></H3>
-<OL TYPE=1>
-<P><LI>Become the local superuser <B>root</B> on the machine, if you are not
-already, by issuing the <B>su</B> command.
-<PRE> % <B>su root</B>
- Password: <VAR>root_password</VAR>
-</PRE>
-<P><LI>Issue the <B>fstrace lsset</B> command to display the available event
-set and its state.
-<PRE> # <B>fstrace lsset</B> [<B>-set</B> <<VAR>set_name</VAR>><SUP>+</SUP>]
-</PRE>
-</OL>
-<P>The following example displays the event set and its state on the local
-machine.
-<PRE> #<B> fstrace lsset cm</B>
- Available sets:
- cm active
-</PRE>
-<P>The output from this command lists the event set and its states. The
-three event states for the <B>cm</B> event set are:
-<DL>
-<P><DT><B><TT>active</TT>
-</B><DD>Tracing is enabled.
-<P><DT><B><TT>inactive</TT>
-</B><DD>Tracing is disabled, but space is still allocated for the corresponding
-trace log (<B>cmfx</B>).
-<P><DT><B><TT>dormant</TT>
-</B><DD>Tracing is disabled, and space is no longer allocated for the
-corresponding trace log (<B>cmfx</B>).Disables tracing for the
-event set.
-</DL>
-<A NAME="IDX7178"></A>
-<A NAME="IDX7179"></A>
-<A NAME="IDX7180"></A>
-<A NAME="IDX7181"></A>
-<P><H3><A NAME="Header_385" HREF="auagd002.htm#ToC_385">To display the log size</A></H3>
-<OL TYPE=1>
-<P><LI>Become the local superuser <B>root</B> on the machine, if you are not
-already, by issuing the <B>su</B> command.
-<PRE> % <B>su root</B>
- Password: <VAR>root_password</VAR>
-</PRE>
-<P><LI>Issue the <B>fstrace lslog</B> command to display information about
-the kernel trace log.
-<PRE> # <B>fstrace lslog</B> [<B>-set</B> <<VAR>set_name</VAR>><SUP>+</SUP>] [<B>-log</B> <<VAR>log_name</VAR>>] [<B>-long</B>]
-</PRE>
-</OL>
-<P>The following example uses the <B>-long</B> flag to display additional
-information about the <B>cmfx</B> trace log.
-<PRE> # <B>fstrace lslog cmfx -long</B>
- Available logs:
- cmfx : 60 kbytes (allocated)
-</PRE>
-<P>The output from this command lists information on the trace log.
-When issued without the <B>-long</B> flag, the <B>fstrace lslog</B>
-command lists only the name of the log. When issued with the
-<B>-long</B> flag, the <B>fstrace lslog</B> command lists the log, the
-size of the log in kilobytes, and the allocation state of the log.
-<P>There are two allocation states for the kernel trace log:
-<DL>
-<P><DT><B><TT>allocated</TT>
-</B><DD>Space is reserved for the log in the kernel. This indicates that
-the event set that writes to this log is either <I>active</I> (tracing is
-enabled for the event set) or <I>inactive</I> (tracing is temporarily
-disabled for the event set); however, the event set continues to reserve
-space occupied by the log to which it sends data.
-<P><DT><B><TT>unallocated</TT>
-</B><DD>Space is not reserved for the log in the kernel. This indicates
-that the event set that writes to this log is <I>dormant</I> (tracing is
-disabled for the event set); furthermore, the event set releases the
-space occupied by the log to which it sends data.
-</DL>
-<P><H3><A NAME="HDRWQ469" HREF="auagd002.htm#ToC_386">Dumping and Clearing the Trace Log</A></H3>
-<P>After the Cache Manager operation you want to trace is
-complete, use the <B>fstrace dump</B> command to dump the trace log to the
-standard output stream or to the file named by the <B>-file</B>
-argument. Or, to dump the trace log continuously, use the
-<B>-follow</B> argument (combine it with the <B>-file</B> argument if
-desired). To halt continuous dumping, press an interrupt signal such as
-<<B>Ctrl-c</B>>.
-<P>To clear a trace log when you no longer need the data in it, issue the
-<B>fstrace clear</B> command. (The <B>fstrace setlog</B>
-command also clears an existing trace log automatically when you use it to
-change the log's size.)
-<A NAME="IDX7182"></A>
-<A NAME="IDX7183"></A>
-<A NAME="IDX7184"></A>
-<A NAME="IDX7185"></A>
-<A NAME="IDX7186"></A>
-<P><H3><A NAME="Header_387" HREF="auagd002.htm#ToC_387">To dump the contents of a trace log</A></H3>
-<OL TYPE=1>
-<P><LI>Become the local superuser <B>root</B> on the machine, if you are not
-already, by issuing the <B>su</B> command.
-<PRE> % <B>su root</B>
- Password: <VAR>root_password</VAR>
-</PRE>
-<P><LI>Issue the <B>fstrace dump</B> command to dump trace logs.
-<PRE> # <B>fstrace dump</B> [<B>-set</B> <<VAR>set_name</VAR>><SUP>+</SUP>] [<B>-follow</B> <<VAR>log_name></VAR>] \
- [<B>-file</B> <<VAR>output_filename</VAR>>] \
- [<B>-sleep</B> <<VAR>seconds_between_reads</VAR>>]
-</PRE>
-</OL>
-<P>At the beginning of the output of each dump is a header specifying the date
-and time at which the dump began. The number of logs being dumped is
-also displayed if the <B>-follow</B> argument is not specified. The
-header appears as follows:
-<PRE> AFS Trace Dump --
- Date: <VAR>date</VAR> <VAR>time</VAR>
- Found <VAR>n</VAR> logs.
-</PRE>
-<P>where <I>date</I> is the starting date of the trace log dump,
-<I>time</I> is the starting time of the trace log dump, and <I>n</I>
-specifies the number of logs found by the <B>fstrace dump</B>
-command.
-<P>The following is an example of trace log dump header:
-<PRE> AFS Trace Dump --
- Date: Fri Apr 16 10:44:38 1999
- Found 1 logs.
-</PRE>
-<P>The contents of the log follow the header and are comprised of messages
-written to the log from an active event set. The messages written to
-the log contain the following three components:
-<UL>
-<P><LI>The timestamp associated with the message (number of seconds from an
-arbitrary start point)
-<P><LI>The process ID or thread ID associated with the message
-<P><LI>The message itself
-</UL>
-<P>A trace log message is formatted as follows:
-<PRE> time <VAR>timestamp</VAR>, pid <VAR>pid</VAR>:<VAR>event message</VAR>
-</PRE>
-<P>where <I>timestamp</I> is the number of seconds from an arbitrary start
-point, <I>pid</I> is the process ID number of the Cache Manager event, and
-<I>event message</I> is the Cache Manager event which corresponds with a
-function in the AFS source code.
-<P>The following is an example of a dumped trace log message:
-<PRE> time 749.641274, pid 3002:Returning code 2 from 19
-</PRE>
-<P>For the messages in the trace log to be most readable, the Cache Manager
-catalog file needs to be installed on the local disk of the client
-machine; the conventional location is
-<B>/usr/vice/etc/C/afszcm.cat</B>. Log messages that begin
-with the string <TT>raw op</TT>, like the following, indicate that the
-catalog is not installed.
-<PRE> raw op 232c, time 511.916288, pid 0
- p0:Fri Apr 16 10:36:31 1999
-</PRE>
-<P>Every 1024 seconds, a current time message is written to each log.
-This message has the following format:
-<PRE> time <VAR>timestamp</VAR>, pid <VAR>pid</VAR>: Current time: <VAR>unix_time</VAR>
-</PRE>
-<P>where <VAR>timestamp</VAR> is the number of seconds from an arbitrary start
-point, <VAR>pid</VAR> is the process ID number, and <VAR>unix_time</VAR> is the
-standard time format since January 1, 1970.
-<P>The current time message can be used to determine the actual time
-associated with each log message. Determine the actual time as
-follows:
-<OL TYPE=1>
-<P><LI>Locate the log message whose actual time you want to determine.
-<P><LI>Search backward through the dump record until you come to a current time
-message.
-<P><LI>If the current time message's <I>timestamp</I> is smaller than
-the log message's <I>timestamp</I>, subtract the former from the
-latter. If the current time message's <I>timestamp</I> is
-larger than the log message's <I>timestamp</I>, add 1024 to the
-latter and subtract the former from the result.
-<P><LI>Add the resulting number to the current time message's
-<I>unix_time</I> to determine the log message's actual time.
-</OL>
-<P>Because log data is stored in a finite, circular buffer, some of the data
-can be overwritten before being read. If this happens, the following
-message appears at the appropriate place in the dump:
-<PRE> Log wrapped; data missing.
-</PRE>
-<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
-heavy work load, it indicates that not all of the log data is being written to
-the log or some data is being overwritten. Increasing the size of the
-log with the <B>fstrace setlog</B> command can alleviate this
-problem.
-</TD></TR></TABLE>
-<A NAME="IDX7187"></A>
-<A NAME="IDX7188"></A>
-<A NAME="IDX7189"></A>
-<A NAME="IDX7190"></A>
-<A NAME="IDX7191"></A>
-<P><H3><A NAME="Header_388" HREF="auagd002.htm#ToC_388">To clear the contents of a trace log</A></H3>
-<OL TYPE=1>
-<P><LI>Become the local superuser <B>root</B> on the machine, if you are not
-already, by issuing the <B>su</B> command.
-<PRE> % <B>su root</B>
- Password: <VAR>root_password</VAR>
-</PRE>
-<P><LI>Issue the <B>fstrace clear</B> command to clear logs by log name or by
-event set.
-<PRE> # <B>fstrace clear</B> [<B>-set</B> <<VAR>set_name</VAR>><SUP>+</SUP>] [<B>-log</B> <<VAR>log_name</VAR>><SUP>+</SUP>]
-</PRE>
-</OL>
-<P>The following example clears the <B>cmfx</B> log used by the
-<B>cm</B> event set on the local machine.
-<PRE> # <B>fstrace clear cm</B>
-</PRE>
-<P>The following example also clears the <B>cmfx</B> log on the local
-machine.
-<PRE> # <B>fstrace clear cmfx</B>
-</PRE>
-<A NAME="IDX7192"></A>
-<P><H3><A NAME="HDRWQ470" HREF="auagd002.htm#ToC_389">Examples of fstrace Commands</A></H3>
-<P>This section contains an extensive example of the use of the
-<B>fstrace</B> command suite, which is useful for gathering a detailed
-trace of Cache Manager activity when you are working with AFS Product Support
-to diagnose a problem. The Product Support representative can guide you
-in choosing appropriate parameter settings for the trace.
-<P>Before starting the kernel trace log, try to isolate the Cache Manager on
-the AFS client machine that is experiencing the problem accessing the
-file. If necessary, instruct users to move to another machine so as to
-minimize the Cache Manager activity on this machine. To minimize the
-amount of unrelated AFS activity recorded in the trace log, place both the
-<B>fstrace</B> binary and the dump file must reside on the local disk, not
-in AFS. You must be logged in as the local superuser <B>root</B> to
-issue <B>fstrace</B> commands.
-<P>Before starting a kernel trace, issue the <B>fstrace lsset</B> command
-to check the state of the <B>cm</B> event set.
-<PRE> # <B>fstrace lsset cm</B>
-</PRE>
-<P>If tracing has not been enabled previously or if tracing has been turned
-off on the client machine, the following output is displayed:
-<PRE> Available sets:
- cm inactive
-</PRE>
-<P>If tracing has been turned off and kernel memory is not allocated for the
-trace log on the client machine, the following output is displayed:
-<PRE> Available sets:
- cm inactive (dormant)
-</PRE>
-<P>If the current state of the <B>cm</B> event set is <TT>inactive</TT>
-or <TT>inactive (dormant)</TT>, turn on kernel tracing by issuing the
-<B>fstrace setset</B> command with the <B>-active</B> flag.
-<PRE> # <B>fstrace setset cm -active</B>
-</PRE>
-<P>If tracing is enabled currently on the client machine, the following output
-is displayed:
-<PRE> Available sets:
- cm active
-</PRE>
-<P>If tracing is enabled currently, you do not need to use the <B>fstrace
-setset</B> command. Do issue the <B>fstrace clear</B> command to
-clear the contents of any existing trace log, removing prior traces that are
-not related to the current problem.
-<PRE> # <B>fstrace clear cm</B>
-</PRE>
-<P>After checking on the state of the event set, issue the <B>fstrace
-lslog</B> command with the <B>-long</B> flag to check the current state
-and size of the kernel trace log .
-<PRE> # <B>fstrace lslog cmfx -long</B>
-</PRE>
-<P>If tracing has not been enabled previously or the <B>cm</B> event set
-was set to <TT>active</TT> or <TT>inactive</TT> previously, output similar
-to the following is displayed:
-<PRE> Available logs:
- cmfx : 60 kbytes (allocated)
-</PRE>
-<P>The <B>fstrace</B> tracing utility allocates 60 kilobytes of memory to
-the trace log by default. You can increase or decrease the amount of
-memory allocated to the kernel trace log by setting it with the <B>fstrace
-setlog</B> command. The number specified with the
-<B>-buffersize</B> argument represents the number of kilobytes allocated
-to the kernel trace log. If you increase the size of the kernel trace
-log to 100 kilobytes, issue the following command.
-<PRE> # <B>fstrace setlog cmfx</B> 100
-</PRE>
-<P>After ensuring that the kernel trace log is configured for your needs, you
-can set up a file into which you can dump the kernel trace log. For
-example, create a dump file with the name
-<B>cmfx.dump.file.1</B> using the following
-<B>fstrace dump</B> command. Issue the command as a continuous
-process by adding the <B>-follow</B> and <B>-sleep</B>
-arguments. Setting the <B>-sleep</B> argument to <I>10</I>
-dumps output from the kernel trace log to the file every 10 seconds.
-<PRE> # <B>fstrace dump -follow</B> cmfx <B>-file</B> cmfx.dump.file.1 <B>-sleep</B> 10
- AFS Trace Dump -
- Date: Fri Apr 16 10:54:57 1999
- Found 1 logs.
- time 32.965783, pid 0: Fri Apr 16 10:45:52 1999
- time 32.965783, pid 33657: Close 0x5c39ed8 flags 0x20
- time 32.965897, pid 33657: Gn_close vp 0x5c39ed8 flags 0x20 (returns
- 0x0)
- time 35.159854, pid 10891: Breaking callback for 5bd95e4 states 1024
- (volume 0)
- time 35.407081, pid 10891: Breaking callback for 5c0fadc states 1024
- (volume 0)
- . .
- . .
- . .
- time 71.440456, pid 33658: Lookup adp 0x5bbdcf0 name g3oCKs fid (756
- 4fb7e:588d240.2ff978a8.6)
- time 71.440569, pid 33658: Returning code 2 from 19
- time 71.440619, pid 33658: Gn_lookup vp 0x5bbdcf0 name g3oCKs (returns
- 0x2)
- time 71.464989, pid 38267: Gn_open vp 0x5bbd000 flags 0x0 (returns 0x
- 0)
- AFS Trace Dump - Completed
-</PRE>
-<HR><H2><A NAME="HDRWQ471" HREF="auagd002.htm#ToC_390">Using the afsmonitor Program</A></H2>
-<A NAME="IDX7193"></A>
-<P>The <B>afsmonitor</B> program enables you to monitor the status and
-performance of specified File Server and Cache Manager processes by gathering
-statistical information. Among its other uses, the
-<B>afsmonitor</B> program can be used to fine-tune Cache Manager
-configuration and load balance File Servers.
-<P>The <B>afsmonitor</B> program enables you to perform the following
-tasks.
-<UL>
-<P><LI>Monitor any number of File Server and Cache Manager processes on any
-number of machines (in both local and foreign cells) from a single
-location.
-<P><LI>Set threshold values for any monitored statistic. When the value of
-a statistic exceeds the threshold, the <B>afsmonitor</B> program
-highlights it to draw your attention. You can set threshold levels that
-apply to every machine or only some.
-<P><LI>Invoke programs or scripts automatically when a statistic exceeds its
-threshold.
-</UL>
-<P><H3><A NAME="HDRWQ472" HREF="auagd002.htm#ToC_391">Requirements for running the afsmonitor program</A></H3>
-<A NAME="IDX7194"></A>
-<P>The following software must be accessible to a machine where the
-<B>afsmonitor</B> program is running:
-<UL>
-<P><LI>The AFS <B>xstat</B> libraries, which the <B>afsmonitor</B>
-program uses to gather data
-<P><LI>The <B>curses</B> graphics package, which most UNIX distributions
-provide as a standard utility
-</UL>
-<A NAME="IDX7195"></A>
-<A NAME="IDX7196"></A>
-<P>The <B>afsmonitor</B> screens format successfully both on so-called
-dumb terminals and in windowing systems that emulate terminals. For the
-output to looks its best, the display environment needs to support reverse
-video and cursor addressing. Set the TERM environment variable to the
-correct terminal type, or to a value that has characteristics similar to the
-actual terminal type. The display window or terminal must be at least
-80 columns wide and 12 lines long.
-<A NAME="IDX7197"></A>
-<A NAME="IDX7198"></A>
-<A NAME="IDX7199"></A>
-<P>The <B>afsmonitor</B> program must run in the foreground, and in its
-own separate, dedicated window or terminal. The window or terminal is
-unavailable for any other activity as long as the <B>afsmonitor</B>
-program is running. Any number of instances of the
-<B>afsmonitor</B> program can run on a single machine, as long as each
-instance runs in its own dedicated window or terminal. Note that it can
-take up to three minutes to start an additional instance.
-<P>
-<A NAME="IDX7200"></A>
-No privilege is required to run the <B>afsmonitor</B> program. By
-convention, it is installed in the <B>/usr/afsws/bin</B> directory, and
-anyone who can access the directory can monitor File Servers and Cache
-Managers. The probes through which the <B>afsmonitor</B> program
-collects statistics do not constitute a significant burden on the File Server
-or Cache Manager unless hundreds of people are running the program. If
-you wish to restrict its use, place the binary file in a directory available
-only to authorized users.
-<P><H3><A NAME="Header_392" HREF="auagd002.htm#ToC_392">The afsmonitor Output Screens</A></H3>
-<A NAME="IDX7201"></A>
-<P>The <B>afsmonitor</B> program displays its data on three screens:
-<UL>
-<P><LI><TT>System Overview</TT>: This screen appears automatically when
-the <B>afsmonitor</B> program initializes. It summarizes separately
-for File Servers and Cache Managers the number of machines being monitored and
-how many of them have <I>alerts</I> (statistics that have exceeded their
-thresholds). It then lists the hostname and number of alerts for each
-machine being monitored, indicating if appropriate that a process failed to
-respond to the last probe.
-<P><LI><TT>File Server</TT>: This screen displays File Server statistics
-for each file server machine being monitored. It highlights statistics
-that have exceeded their thresholds, and identifies machines that failed to
-respond to the last probe.
-<P><LI><TT>Cache Managers</TT>: This screen displays Cache Manager
-statistics for each client machine being monitored. It highlights
-statistics that have exceeded their thresholds, and identifies machines that
-failed to respond to the last probe.
-</UL>
-<P>Fields at the corners of every screen display the following
-information:
-<UL>
-<P><LI>In the top left corner, the program name and version number.
-<P><LI>In the top right corner, the screen name, current and total page numbers,
-and current and total column numbers. The page number (for example,
-<TT>p. 1 of 3</TT>) indicates the index of the current page and the
-total number of (vertical) pages over which data is displayed. The
-column number (for example, <TT>c. 1 of 235</TT>) indicates the index
-of the current leftmost column and the total number of columns in which data
-appears. (The symbol <TT>>>></TT> indicates that there is additional
-data to the right; the symbol <TT><<<</TT> indicates that
-there is additional data to the left.)
-<P><LI>In the bottom left corner, a list of the available commands. Enter
-the first letter in the command name to run that command. Only the
-currently possible options appear; for example, if there is only one page
-of data, the <TT>next</TT> and <TT>prev</TT> commands, which scroll the
-screen up and down respectively, do not appear. For descriptions of the
-commands, see the following section about navigating the display
-screens.
-<P><LI>In the bottom right corner, the <TT>probes</TT> field reports how many
-times the program has probed File Servers (<TT>fs</TT>), Cache Managers
-(<TT>cm</TT>), or both. The counts for File Servers and Cache
-Managers can differ. The <TT>freq</TT> field reports how often the
-program sends probes.
-</UL>
-<P><B>Navigating the afsmonitor Display Screens</B>
-<P>As noted, the lower left hand corner of every display screen displays the
-names of the commands currently available for moving to alternate screens,
-which can either be a different type or display more statistics or machines of
-the current type. To execute a command, press the lowercase version of
-the first letter in its name. Some commands also have an uppercase
-version that has a somewhat different effect, as indicated in the following
-list.
-<DL>
-<P><DT><B><TT>cm</TT>
-</B><DD>Switches to the <TT>Cache Managers</TT> screen. Available only on
-the <TT>System Overview</TT> and <TT>File Servers</TT> screens.
-<P><DT><B><TT>fs</TT>
-</B><DD>Switches to the <TT>File Servers</TT> screen. Available only on
-the <TT>System Overview</TT> and the <TT>Cache Managers</TT>
-screens.
-<P><DT><B><TT>left</TT>
-</B><DD>Scrolls horizontally to the left, to access the data columns situated to
-the left of the current set. Available when the <TT><<<</TT>
-symbol appears at the top left of the screen. Press uppercase
-<B>L</B> to scroll horizontally all the way to the left (to display the
-first set of data columns).
-<P><DT><B><TT>next</TT>
-</B><DD>Scrolls down vertically to the next page of machine names.
-Available when there are two or more pages of machines and the final page is
-not currently displayed. Press uppercase <B>N</B> to scroll to the
-final page.
-<P><DT><B><TT>oview</TT>
-</B><DD>Switches to the <TT>System Overview</TT> screen. Available only
-on the <TT>Cache Managers</TT> and <TT>File Servers</TT> screens.
-<P><DT><B><TT>prev</TT>
-</B><DD>Scrolls up vertically to the previous page of machine names.
-Available when there are two or more pages of machines and the first page is
-not currently displayed. Press uppercase <B>N</B> to scroll to the
-first page.
-<P><DT><B><TT>right</TT>
-</B><DD>Scrolls horizontally to the right, to access the data columns situated to
-the right of the current set. This command is available when the
-<TT>>>></TT> symbol appears at the upper right of the screen. Press
-uppercase <B>R</B> to scroll horizontally all the way to the right (to
-display the final set of data columns).
-</DL>
-<P><H3><A NAME="Header_393" HREF="auagd002.htm#ToC_393">The System Overview Screen</A></H3>
-<P>The <TT>System Overview</TT> screen appears automatically as the
-<B>afsmonitor</B> program initializes. This screen displays the
-status of as many File Server and Cache Manager processes as can fit in the
-current window; scroll down to access additional information.
-<P>The information on this screen is split into File Server information on the
-left and Cache Manager information on the right. The header for each
-grouping reports two pieces of information:
-<UL>
-<P><LI>The number of machines on which the program is monitoring the indicated
-process
-<P><LI>The number of alerts and the number of machines affected by them (an
-<I>alert</I>means that a statistic has exceeded its threshold or a process
-failed to respond to the last probe)
-</UL>
-<P>A list of the machines being monitored follows. If there are any
-alerts on a machine, the number of them appears in square brackets to the left
-of the hostname. If a process failed to respond to the last probe, the
-letters <TT>PF</TT> (probe failure) appear in square brackets to the left of
-the hostname.
-<P>The following graphic is an example <TT>System Overview</TT>
-screen. The <B>afsmonitor</B> program is monitoring six File
-Servers and seven Cache Managers. The File Server process on host
-<B>fs1.abc.com</B> and the Cache Manager on host
-<B>cli33.abc.com</B> are each marked <TT>[ 1]</TT> to
-indicate that one threshold value is exceeded. The <TT>[PF]</TT>
-marker on host <B>fs6.abc.com</B> indicates that its File
-Server process did not respond to the last probe.
-<P><B><A NAME="Figure_6" HREF="auagd003.htm#FT_Figure_6">Figure 6. The afsmonitor System Overview Screen</A></B><BR>
-<TABLE BORDER ><TR><TD><BR>
-<B><BR><IMG SRC="overview.gif" ALT="System Overview Screen"><BR></B><BR>
-</TD></TR></TABLE>
-<P><H3><A NAME="Header_394" HREF="auagd002.htm#ToC_394">The File Servers Screen</A></H3>
-<P>The <TT>File Servers</TT> screen displays the values collected at the
-most recent probe for File Server statistics.
-<P>A summary line at the top of the screen (just below the standard program
-version and screen title blocks) specifies the number of monitored File
-Servers, the number of alerts, and the number of machines affected by the
-alerts.
-<P>The first column always displays the hostnames of the machines running the
-monitored File Servers.
-<P>To the right of the hostname column appear as many columns of statistics as
-can fit within the current width of the display screen or window; each
-column requires space for 10 characters. The name of the statistic
-appears at the top of each column. If the File Server on a machine did
-not respond to the most recent probe, a pair of dashes (<TT>--</TT>) appears
-in each column. If a value exceeds its configured threshold, it is
-highlighted in reverse video. If a value is too large to fit into the
-allotted column width, it overflows into the next row in the same
-column.
-<P>For a list of the available File Server statistics, see <A HREF="auagd024.htm#HDRWQ842">Appendix C, The afsmonitor Program Statistics</A>.
-<P>The following graphic depicts the <TT>File Servers</TT> screen that
-follows the System Overview Screen example previously discussed; however,
-one additional server probe has been completed. In this example, the
-File Server process on <B>fs1</B> has exceeded the configured threshold
-for the number of performance calls received (the <B>numPerfCalls</B>
-statistic), and that field appears in reverse video. Host
-<B>fs6</B> did not respond to Probe 10, so dashes appear in all
-fields.
-<P><B><A NAME="Figure_7" HREF="auagd003.htm#FT_Figure_7">Figure 7. The afsmonitor File Servers Screen</A></B><BR>
-<TABLE BORDER ><TR><TD><BR>
-<B><BR><IMG SRC="fserver1.gif" ALT="File Servers Screen"><BR></B><BR>
-</TD></TR></TABLE>
-<P>Both the File Servers and Cache Managers screen (discussed in the following
-section) can display hundreds of columns of data and are therefore designed to
-scroll left and right. In the preceding graphic, the screen displays
-the leftmost screen and the screen title block shows that column 1 of 235 is
-displayed. The appearance of the <TT>>>></TT> symbol in the upper
-right hand corner of the screen and the <B>right</B> command in the
-command block indicate that additional data is available by scrolling
-right. (For information on the available statistics, see <A HREF="auagd024.htm#HDRWQ842">Appendix C, The afsmonitor Program Statistics</A>.)
-<P>If the <B>right</B> command is executed, the screen looks something
-like the following example. Note that the horizontal scroll symbols now
-point both to the left (<TT><<<</TT>) and to the right
-(<TT>>>></TT>) and both the <B>left</B> and <B>right</B> commands
-appear, indicating that additional data is available by scrolling both left
-and right.
-<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>
-<TABLE BORDER ><TR><TD><BR>
-<B><BR><IMG SRC="fserver2.gif" ALT="File Servers Screen Shifted One Page to the Right"><BR></B><BR>
-</TD></TR></TABLE>
-<P><H3><A NAME="Header_395" HREF="auagd002.htm#ToC_395">The Cache Managers Screen</A></H3>
-<P>The <TT>Cache Managers</TT> screen displays the values collected at
-the most recent probe for Cache Manager statistics.
-<P>A summary line at the top of the screen (just below the standard program
-version and screen title blocks) specifies the number of monitored Cache
-Managers, the number of alerts, and the number of machines affected by the
-alerts.
-<P>The first column always displays the hostnames of the machines running the
-monitored Cache Managers.
-<P>To the right of the hostname column appear as many columns of statistics as
-can fit within the current width of the display screen or window; each
-column requires space for 10 characters. The name of the statistic
-appears at the top of each column. If the Cache Manager on a machine
-did not respond to the most recent probe, a pair of dashes (<TT>--</TT>)
-appears in each column. If a value exceeds its configured threshold, it
-is highlighted in reverse video. If a value is too large to fit into
-the allotted column width, it overflows into the next row in the same
-column.
-<P>For a list of the available Cache Manager statistics, see <A HREF="auagd024.htm#HDRWQ842">Appendix C, The afsmonitor Program Statistics</A>.
-<P>The following graphic depicts a Cache Managers screen that follows the
-System Overview Screen previously discussed. In the example, the Cache
-Manager process on host <B>cli33</B> has exceeded the configured threshold
-for the number of cells it can contact (the <B>numCellsContacted</B>
-statistic), so that field appears in reverse video.
-<P><B><A NAME="Figure_9" HREF="auagd003.htm#FT_Figure_9">Figure 9. The afsmonitor Cache Managers Screen</A></B><BR>
-<TABLE BORDER WIDTH="100%"><TR><TD>
-<B><BR><IMG SRC="cachmgr.gif" ALT="Cache Managers Screen"><BR></B>
-</TD></TR></TABLE>
-<HR><H2><A NAME="HDRWQ473" HREF="auagd002.htm#ToC_396">Configuring the afsmonitor Program</A></H2>
-<A NAME="IDX7202"></A>
-<A NAME="IDX7203"></A>
-<P>To customize the <B>afsmonitor</B> program, create an ASCII-format
-configuration file and use the <B>-config</B> argument to name it.
-You can specify the following in the configuration file:
-<UL>
-<P><LI>The File Servers, Cache Managers, or both to monitor.
-<P><LI>The statistics to display. By default, the display includes 271
-statistics for File Servers and 570 statistics for Cache Managers. For
-information on the available statistics, see <A HREF="auagd024.htm#HDRWQ842">Appendix C, The afsmonitor Program Statistics</A>.
-<P><LI>The threshold values to set for statistics and a script or program to
-execute if a threshold is exceeded. By default, no threshold values are
-defined and no scripts or programs are executed.
-</UL>
-<P>The following list describes the instructions that can appear in the
-configuration file:
-<DL>
-<P><DT><B><TT>cm <VAR>host_name</VAR></TT>
-</B><DD>Names a client machine for which to display Cache Manager
-statistics. The order of <B>cm</B> lines in the file determines the
-order in which client machines appear from top to bottom on the <TT>System
-Overview</TT> and <TT>Cache Managers</TT> output screens.
-<P><DT><B><TT>fs <VAR>host_name</VAR></TT>
-</B><DD>Names a file server machine for which to display File Server
-statistics. The order of <B>fs</B> lines in the file determines the
-order in which file server machines appear from top to bottom on the
-<TT>System Overview</TT> and <TT>File Servers</TT> output screens.
-<P><DT><B><TT>thresh fs | cm <VAR>field_name</VAR> <VAR>thresh_val</VAR>
-[<VAR>cmd_to_run</VAR>] [<VAR>arg</VAR><SUB>1</SUB>] . . .
-[<VAR>arg</VAR><SUB>n</SUB>]</TT>
-</B><DD>Assigns the threshold value <VAR>thresh_val</VAR> to the statistic
-<VAR>field_name</VAR>, for either a File Server statistic (<B>fs</B>) or a
-Cache Manager statistic (<B>cm</B>). The optional
-<VAR>cmd_to_execute</VAR> field names a binary or script to execute each time
-the value of the statistic changes from being below <VAR>thresh_val</VAR> to
-being at or above <VAR>thresh_val</VAR>. A change between two values that
-both exceed <VAR>thresh_val</VAR> does not retrigger the binary or
-script. The optional <VAR>arg</VAR><SUB>1</SUB> through
-<VAR>arg</VAR><SUB>n</SUB> fields are additional values that the
-<B>afsmonitor</B> program passes as arguments to the
-<VAR>cmd_to_execute</VAR> command. If any of them include one or more
-spaces, enclose the entire field in double quotes.
-<P>The parameters <B>fs</B>, <B>cm</B>, <VAR>field_name</VAR>,
-<VAR>threshold_val</VAR>, and <VAR>arg</VAR><SUB>1</SUB> through
-<VAR>arg</VAR><SUB>n</SUB> correspond to the values with the same name on the
-<B>thresh</B> line. The <VAR>host_name</VAR> parameter identifies the
-file server or client machine where the statistic has crossed the threshold,
-and the <VAR>actual_val</VAR> parameter is the actual value of
-<VAR>field_name</VAR> that equals or exceeds the threshold value.
-<P>Use the <B>thresh</B> line to set either a global threshold, which
-applies to all file server machines listed on <B>fs</B> lines or client
-machines listed on <B>cm</B> lines in the configuration file, or a
-machine-specific threshold, which applies to only one file server or client
-machine.
-<UL>
-<P><LI>To set a global threshold, place the <B>thresh</B> line before any of
-the <B>fs</B> or <B>cm</B> lines in the file.
-<P><LI>To set a machine-specific threshold, place the <B>thresh</B> line
-below the corresponding <B>fs</B> or <B>cm</B> line, and above any
-other <B>fs</B> or <B>cm</B> lines. A machine-specific
-threshold value always overrides the corresponding global threshold, if
-set. Do not place a <B>thresh fs</B> line directly after a
-<B>cm</B> line or a <B>thresh cm</B> line directly after a
-<B>fs</B> line.
-</UL>
-<P><DT><B><TT>show fs | cm <VAR>field/group/section</VAR></TT>
-</B><DD>Specifies which individual statistic, group of statistics, or section of
-statistics to display on the <TT>File Servers</TT> screen (<B>fs</B>) or
-<TT>Cache Managers</TT> screen (<B>cm</B>) and the order in which to
-display them. The appendix of <B>afsmonitor</B> statistics in the
-<I>AFS Administration Guide</I> specifies the group and section to which
-each statistic belongs. Include as many <B>show</B> lines as
-necessary to customize the screen display as desired, and place them anywhere
-in the file. The top-to-bottom order of the <B>show</B> lines in
-the configuration file determines the left-to-right order in which the
-statistics appear on the corresponding screen.
-<P>If there are no <B>show</B> lines in the configuration file, then the
-screens display all statistics for both Cache Managers and File
-Servers. Similarly, if there are no <B>show fs</B> lines, the
-<TT>File Servers</TT> screen displays all file server statistics, and if
-there are no <B>show cm</B> lines, the <TT>Cache Managers</TT> screen
-displays all client statistics.
-<P><DT><B># <VAR>comments</VAR>
-</B><DD>Precedes a line of text that the <B>afsmonitor</B> program ignores
-because of the initial number (<B>#</B>) sign, which must appear in the
-very first column of the line.
-</DL>
-<P>For a list of the values that can appear in the
-<VAR>field/group/section</VAR> field of a <B>show</B> instruction, see <A HREF="auagd024.htm#HDRWQ842">Appendix C, The afsmonitor Program Statistics</A>.)
-<P>The following example illustrates a possible configuration file:
-<PRE> thresh cm dlocalAccesses 1000000
- thresh cm dremoteAccesses 500000 handleDRemote
- thresh fs rx_maxRtt_Usec 1000
- cm client5
- cm client33
- cm client14
- thresh cm dlocalAccesses 2000000
- thresh cm vcacheMisses 10000
- cm client2
- fs fs3
- fs fs9
- fs fs5
- fs fs10
- show cm numCellsContacted
- show cm dlocalAccesses
- show cm dremoteAccesses
- show cm vcacheMisses
- show cm Auth_Stats_group
-</PRE>
-<P>Since the first three <B>thresh</B> instructions appear before any
-<B>fs</B> or <B>cm</B> instructions, they set global threshold
-values:
-<UL>
-<P><LI>All Cache Manager process in this file use <B>1000000</B> as the
-threshold for the <B>dlocalAccesses</B> statistic (except for the machine
-<B>client2</B> which uses an overriding value of
-<B>2000000</B>.)
-<P><LI>All Cache Manager processes in this file use <B>500000</B> as the
-threshold value for the <B>dremoteAccesses</B> statistic; if that
-value is exceeded, the script <B>handleDRemote</B> is invoked.
-<P><LI>All File Server processes in this file use <B>1000</B> as the
-threshold value for the <B>rx_maxRtt_Usec</B> statistic.
-</UL>
-<P>The four <B>cm</B> instructions monitor the Cache Manager on the
-machines <B>client5</B>, <B>client33</B>, <B>client14</B>, and
-<B>client2</B>. The first three use all of the global threshold
-values.
-<P>The Cache Manager on <B>client2</B> uses the global threshold value for
-the <B>dremoteAccesses</B> statistic, but a different one for the
-<B>dlocalAccesses</B> statistic. Furthermore, <B>client22</B>
-is the only Cache Manager that uses the threshold set for the
-<B>vcacheMisses</B> statistic.
-<P>The <B>fs</B> instructions monitor the File Server on the machines
-<B>fs3</B>, <B>fs9</B>, <B>fs5</B>, and <B>fs10</B>.
-They all use the global threshold for the<B>rx_maxRtt_Usec</B>
-statistic.
-<P>Because there are no <B>show fs</B> instructions, the File Servers
-screen displays all File Server statistics. The Cache Managers screen
-displays only the statistics named in <B>show cm</B> instructions,
-ordering them from left to right. The <B>Auth_Stats_group</B>
-includes several statistics, all of which are displayed (<B>curr_PAGs</B>,
-<B>curr_Records</B>, <B>curr_AuthRecords</B>,
-<B>curr_UnauthRecords</B>, <B>curr_MaxRecordsInPAG</B>,
-<B>curr_LongestChain</B>, <B>PAGCreations</B>,
-<B>TicketUpdates</B>, <B>HWM_PAGS</B>, <B>HWM_Records</B>,
-<B>HWM_MaxRecordsInPAG</B>, and <B>HWM_LongestChain</B>).
-<HR><H2><A NAME="HDRWQ474" HREF="auagd002.htm#ToC_397">Writing afsmonitor Statistics to a File</A></H2>
-<A NAME="IDX7204"></A>
-<P>All of the statistical information collected and displayed by the
-<B>afsmonitor</B> program can be preserved by writing it to an output
-file. You can create an output file by using the <B>-output</B>
-argument when you startup the <B>afsmonitor</B> process. You can
-use the output file to track process performance over long periods of time and
-to apply post-processing techniques to further analyze system trends.
-<P>The <B>afsmonitor</B> program output file is a simple ASCII file that
-records the information reported by the File Server and Cache Manager
-screens. The output file has the following format:
-<PRE> <VAR>time</VAR> <VAR>host_name</VAR> <B>CM</B>|<B>FS</B> <VAR>list_of_measured_values</VAR>
-</PRE>
-<P>and specifies the <I>time</I> at which the
-<I>list_of_measured_values</I> were gathered from the Cache Manager
-(<B>CM</B>) or File Server (<B>FS</B>) process housed on
-<VAR>host_name</VAR>. On those occasion where probes fail, the value
-<TT>-1</TT> is reported instead of the
-<I>list_of_measured_values</I>.
-<P>This file format provides several advantages:
-<UL>
-<P><LI>It can be viewed using a standard editor. If you intend to view
-this file frequently, use the <B>-detailed</B> flag with the
-<B>-output</B> argument. It formats the output file in a way that
-is easier to read.
-<P><LI>It can be passed through filters to extract desired information using the
-standard set of UNIX tools.
-<P><LI>It is suitable for long term storage of the <B>afsmonitor</B> program
-output.
-</UL>
-<A NAME="IDX7205"></A>
-<A NAME="IDX7206"></A>
-<HR><H2><A NAME="Header_398" HREF="auagd002.htm#ToC_398">To start the afsmonitor Program</A></H2>
-<OL TYPE=1>
-<P><LI>Open a separate command shell window or use a dedicated terminal for each
-instance of the <B>afsmonitor</B> program. This window or terminal
-must be devoted to the exclusive use of the <B>afsmonitor</B> process
-because the command cannot be run in the background.
-<P><LI>Initialize the <B>afsmonitor</B> program. The message <TT>
-afsmonitor Collecting Statistics...</TT>, followed by
-the appearance of the System Overview screen, confirms a successful
-start.
-<PRE> % <B>afsmonitor</B> [<B>initcmd</B>] [<B>-config</B> <<VAR>configuration file</VAR>>] \
- [<B>-frequency</B> <<VAR>poll frequency, in seconds</VAR>>] \
- [<B>-output</B> <<VAR>storage file name</VAR>>] [<B>-detailed</B>] \
- [<B>-debug</B> <<VAR>turn debugging output on to the named file</VAR>>] \
- [<B>-fshosts</B> <<VAR>list of file servers to monitor</VAR>><SUP>+</SUP>] \
- [<B>-cmhosts</B> <<VAR>list of cache managers to monitor</VAR>><SUP>+</SUP>]
- afsmonitor Collecting Statistics...
-</PRE>
-<P>where
-<DL>
-<P><DT><B>initcmd
-</B><DD>Is an optional string that accommodates the command's use of the AFS
-command parser. It can be omitted and ignored.
-<P><DT><B>-config
-</B><DD>Specifies the pathname of an <B>afsmonitor</B> configuration file,
-which lists the machines and statistics to monitor. Partial pathnames
-are interpreted relative to the current working directory. Provide
-either this argument or one or both of the <B>-fshosts</B> and
-<B>-cmhosts</B> arguments. You must use a configuration file to set
-thresholds or customize the screen display. For instructions on
-creating the configuration file, see <A HREF="#HDRWQ473">Configuring the afsmonitor Program</A>.
-<P><DT><B>-frequency
-</B><DD>Specifies how often to probe the File Server and Cache Manager processes,
-as a number of seconds. Acceptable values range from <B>1</B> and
-<B>86400</B>; the default value is <B>60</B>. This
-frequency applies to both File Server and Cache Manager probes; however,
-File Server and Cache Manager probes are initiated and processed independent
-of each other. The actual interval between probes to a host is the
-probe frequency plus the time needed by all hosts to respond to the
-probe.
-<P><DT><B>-output
-</B><DD>Specifies the name of an output file to which to write all of the
-statistical data. By default, no output file is created. For
-information on this file, see <A HREF="#HDRWQ474">Writing afsmonitor Statistics to a File</A>.
-<P><DT><B>-detailed
-</B><DD>Formats the output file named by the <B>-output</B> argument to be
-more easily readable. The <B>-output</B> argument must be provided
-along with this flag.
-<P><DT><B>-fshosts
-</B><DD>Identifies each File Server process to monitor by specifying the host it
-is running on. You can identify a host using either its complete
-Internet-style host name or an abbreviation acceptable to the cell's
-naming service. Combine this argument with the <B>-cmhosts</B> if
-you wish, but not the <B>-config</B> argument.
-<P><DT><B>-cmhosts
-</B><DD>Identifies each Cache Manager process to monitor by specifying the host it
-is running on. You can identify a host using either its complete
-Internet-style host name or an abbreviation acceptable to the cell's
-naming service. Combine this argument with the <B>-fshosts</B> if
-you wish, but not the <B>-config</B> argument.
-</DL>
-</OL>
-<HR><H2><A NAME="Header_399" HREF="auagd002.htm#ToC_399">To stop the afsmonitor program</A></H2>
-<A NAME="IDX7207"></A>
-<P>To exit an <B>afsmonitor</B> program session, Enter the
-<<B>Ctrl-c</B>> interrupt signal or an uppercase <B>Q</B>.
-<HR><H2><A NAME="HDRWQ475" HREF="auagd002.htm#ToC_400">The xstat Data Collection Facility</A></H2>
-<A NAME="IDX7208"></A>
-<A NAME="IDX7209"></A>
-<A NAME="IDX7210"></A>
-<A NAME="IDX7211"></A>
-<A NAME="IDX7212"></A>
-<A NAME="IDX7213"></A>
-<A NAME="IDX7214"></A>
-<A NAME="IDX7215"></A>
-<A NAME="IDX7216"></A>
-<A NAME="IDX7217"></A>
-<A NAME="IDX7218"></A>
-<P>The <B>afsmonitor</B> program uses the <B>xstat</B> data collection
-facility to gather and calculate the data that it (the <B>afsmonitor</B>
-program) then uses to perform its function. You can also use the
-<B>xstat</B> facility to create your own data display programs. If
-you do, keep the following in mind. The File Server considers any
-program calling its RPC routines to be a Cache Manager; therefore, any
-program calling the File Server interface directly must export the Cache
-Manager's callback interface. The calling program must be capable
-of emulating the necessary callback state, and it must respond to periodic
-keep-alive messages from the File Server. In addition, a calling
-program must be able to gather the collected data.
-<P>The <B>xstat</B> facility consists of two C language libraries
-available to user-level applications:
-<UL>
-<P><LI><B>/usr/afsws/lib/afs/libxstat_fs.a</B> exports calls that
-gather information from one or more running File Server processes.
-<P><LI><B>/usr/afsws/lib/afs/libxstat_cm.a</B> exports calls that
-collect information from one or more running Cache Managers.
-</UL>
-<P>The libraries allow the caller to register
-<UL>
-<P><LI>A set of File Servers or Cache Managers to be examined.
-<P><LI>The frequency with which the File Servers or Cache Managers are to be
-probed for data.
-<P><LI>A user-specified routine to be called each time data is collected.
-</UL>
-<P>The libraries handle all of the lightweight processes, callback
-interactions, and timing issues associated with the data collection.
-The user needs only to process the data as it arrives.
-<P><H3><A NAME="Header_401" HREF="auagd002.htm#ToC_401">The libxstat Libraries</A></H3>
-<A NAME="IDX7219"></A>
-<A NAME="IDX7220"></A>
-<P>The <B>libxstat_fs.a</B> and <B>libxstat_cm.a</B>
-libraries handle the callback requirements and other complications associated
-with the collection of data from File Servers and Cache Managers. The
-user provides only the means of accumulating the desired data. Each
-<B>xstat</B> library implements three routines:
-<UL>
-<P><LI>Initialization (<B>xstat_fs_Init</B> and <B>xstat_cm_Init</B>)
-arranges the periodic collection and handling of data.
-<P><LI>Immediate probe (<B>xstat_fs_ForceProbeNow</B> and
-<B>xstat_cm_ForceProbeNow</B>) forces the immediate collection of data,
-after which collection returns to its normal probe schedule.
-<P><LI>Cleanup (<B>xstat_fs_Cleanup</B> and <B>xstat_cm_Cleanup</B>)
-terminates all connections and removes all traces of the data collection from
-memory.
-</UL>
-<P>
-<A NAME="IDX7221"></A>
-<A NAME="IDX7222"></A>
-<A NAME="IDX7223"></A>
-<A NAME="IDX7224"></A>
-<A NAME="IDX7225"></A>
-The File Server and Cache Manager each define data collections that clients
-can fetch. A data collection is simply a related set of numbers that
-can be collected as a unit. For example, the File Server and Cache
-Manager each define profiling and performance data collections. The
-profiling collections maintain counts of the number of times internal
-functions are called within servers, allowing bottleneck analysis to be
-performed. The performance collections record, among other things,
-internal disk I/O statistics for a File Server and cache effectiveness figures
-for a Cache Manager, allowing for performance analysis.
-<P>
-<A NAME="IDX7226"></A>
-<A NAME="IDX7227"></A>
-<A NAME="IDX7228"></A>
-For a copy of the detailed specification which provides much additional usage
-information about the <B>xstat</B> facility, its libraries, and the
-routines in the libraries, contact AFS Product Support.
-<P><H3><A NAME="Header_402" HREF="auagd002.htm#ToC_402">Example xstat Commands</A></H3>
-<A NAME="IDX7229"></A>
-<A NAME="IDX7230"></A>
-<A NAME="IDX7231"></A>
-<A NAME="IDX7232"></A>
-<A NAME="IDX7233"></A>
-<P>AFS comes with two low-level, example commands:
-<B>xstat_fs_test</B> and <B>xstat_cm_test</B>. The commands
-allow you to experiment with the <B>xstat</B> facility. They gather
-information and display the available data collections for a File Server or
-Cache Manager. They are intended merely to provide examples of the
-types of data that can be collected via <B>xstat</B>; they are not
-intended for use in the actual collection of data.
-<A NAME="IDX7234"></A>
-<A NAME="IDX7235"></A>
-<A NAME="IDX7236"></A>
-<A NAME="IDX7237"></A>
-<P><H4><A NAME="Header_403">To use the example xstat_fs_test command</A></H4>
-<OL TYPE=1>
-<P><LI>Issue the example <B>xstat_fs_test</B> command to test the routines in
-the <B>libxstat_fs.a</B> library and display the data collections
-associated with the File Server process. The command executes in the
-foreground.
-<PRE> % <B>xstat_fs_test</B> [<B>initcmd</B>] \
- <B>-fsname</B> <<VAR>File Server name(s) to monitor</VAR>><SUP>+</SUP> \
- <B>-collID</B> <<VAR>Collection(s) to fetch</VAR>><SUP>+</SUP> [<B>-onceonly</B>] \
- [<B>-frequency</B> <<VAR>poll frequency, in seconds</VAR>>] \
- [<B>-period</B> <<VAR>data collection time, in minutes</VAR>>] [<B>-debug</B>]
-</PRE>
-<P>where
-<DL>
-<P><DT><B>xstat_fs_test
-</B><DD>Must be typed in full.
-<P><DT><B>initcmd
-</B><DD>Is an optional string that accommodates the command's use of the AFS
-command parser. It can be omitted and ignored.
-<P><DT><B>-fsname
-</B><DD>Is the Internet host name of each file server machine on which to monitor
-the File Server process.
-<P><DT><B>-collID
-</B><DD>Specifies each data collection to return. The indicated data
-collection defines the type and amount of data the command is to gather about
-the File Server. Data is returned in the form of a predefined data
-structure (refer to the specification documents referenced previously for more
-information about the data structures).
-<P>There are two acceptable values:
-<UL>
-<P><LI><B>1</B> reports various internal performance statistics related to
-the File Server (for example, vnode cache entries and <B>Rx</B> protocol
-activity).
-<P><LI><B>2</B> reports all of the internal performance statistics provided
-by the <B>1</B> setting, plus some additional, detailed performance
-figures about the File Server (for example, minimum, maximum, and cumulative
-statistics regarding File Server RPCs, how long they take to complete, and how
-many succeed).
-</UL>
-<P><DT><B>-onceonly
-</B><DD>Directs the command to gather statistics just one time. Omit this
-option to have the command continue to probe the File Server for statistics
-every 30 seconds. If you omit this option, you can use the
-<<B>Ctrl-c</B>> interrupt signal to halt the command at any
-time.
-<P><DT><B>-frequency
-</B><DD>Sets the frequency in seconds at which the program initiates probes to the
-File Server. If you omit this argument, the default is 30
-seconds.
-<P><DT><B>-period
-</B><DD>Sets how long the utility runs before exiting, as a number of
-minutes. If you omit this argument, the default is 10 minutes.
-<P><DT><B>-debug
-</B><DD>Displays additional information as the command runs.
-</DL>
-</OL>
-<A NAME="IDX7238"></A>
-<A NAME="IDX7239"></A>
-<A NAME="IDX7240"></A>
-<A NAME="IDX7241"></A>
-<P><H4><A NAME="Header_404">To use the example xstat_cm_test command</A></H4>
-<OL TYPE=1>
-<P><LI>Issue the example <B>xstat_cm_test</B> command to test the routines in
-the <B>libxstat_cm.a</B> library and display the data collections
-associated with the Cache Manager. The command executes in the
-foreground.
-<PRE> % <B>xstat_cm_test</B> [<B>initcmd</B>] \
- <B>-cmname</B> <<VAR>Cache Manager name(s) to monitor</VAR>><SUP>+</SUP> \
- <B>-collID</B> <<VAR>Collection(s) to fetch</VAR>><SUP>+</SUP> \
- [<B>-onceonly</B>] [<B>-frequency</B> <<VAR>poll frequency, in seconds</VAR>>] \
- [<B>-period</B> <<VAR>data collection time, in minutes</VAR>>] [<B>-debug</B>]
-</PRE>
-<P>where
-<DL>
-<P><DT><B>xstat_cm_test
-</B><DD>Must be typed in full.
-<P><DT><B>initcmd
-</B><DD>Is an optional string that accommodates the command's use of the AFS
-command parser. It can be omitted and ignored.
-<P><DT><B>-cmname
-</B><DD>Is the host name of each client machine on which to monitor the Cache
-Manager.
-<P><DT><B>-collID
-</B><DD>Specifies each data collection to return. The indicated data
-collection defines the type and amount of data the command is to gather about
-the Cache Manager. Data is returned in the form of a predefined data
-structure (refer to the specification documents referenced previously for more
-information about the data structures).
-<P>There are two acceptable values:
-<UL>
-<P><LI><B>0</B> provides profiling information about the numbers of times
-different internal Cache Manager routines were called since the Cache manager
-was started.
-<P><LI><B>1</B> reports various internal performance statistics related to
-the Cache manager (for example, statistics about how effectively the cache is
-being used and the quantity of intracell and intercell data access).
-<P><LI><B>2</B> reports all of the internal performance statistics provided
-by the <B>1</B> setting, plus some additional, detailed performance
-figures about the Cache Manager (for example, statistics about the number of
-RPCs sent by the Cache Manager and how long they take to complete; and
-statistics regarding things such as authentication, access, and PAG
-information associated with data access).
-</UL>
-<P><DT><B>-onceonly
-</B><DD>Directs the command to gather statistics just one time. Omit this
-option to have the command continue to probe the Cache Manager for statistics
-every 30 seconds. If you omit this option, you can use the
-<<B>Ctrl-c</B>> interrupt signal to halt the command at any
-time.
-<P><DT><B>-frequency
-</B><DD>Sets the frequency in seconds at which the program initiates probes to the
-Cache Manager. If you omit this argument, the default is 30
-seconds.
-<P><DT><B>-period
-</B><DD>Sets how long the utility runs before exiting, as a number of
-minutes. If you omit this argument, the default is 10 minutes.
-<P><DT><B>-debug
-</B><DD>Displays additional information as the command runs.
-</DL>
-</OL>
-<HR><H2><A NAME="HDRWQ476" HREF="auagd002.htm#ToC_405">Auditing AFS Events on AIX File Servers</A></H2>
-<A NAME="IDX7242"></A>
-<A NAME="IDX7243"></A>
-<A NAME="IDX7244"></A>
-<A NAME="IDX7245"></A>
-<P>You can audit AFS events on AIX File Servers using an AFS mechanism that
-transfers audit information from AFS to the AIX auditing system. The
-following general classes of AFS events can be audited. For a complete
-list of specific AFS audit events, see <A HREF="auagd025.htm#HDRWQ845">Appendix D, AIX Audit Events</A>.
-<UL>
-<P><LI>Authentication and Identification Events
-<P><LI>Security Events
-<P><LI>Privilege Required Events
-<P><LI>Object Creation and Deletion Events
-<P><LI>Attribute Modification Events
-<P><LI>Process Control Events
-</UL>
-<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
-more information, see the <I>AIX System Management Guide</I> for the
-version of AIX you are using.
-</TD></TR></TABLE>
-<P><H3><A NAME="Header_406" HREF="auagd002.htm#ToC_406">Configuring AFS Auditing on AIX File Servers</A></H3>
-<P>The directory <B>/usr/afs/local/audit</B> contains three files that
-contain the information needed to configure AIX File Servers to audit AFS
-events:
-<UL>
-<P><LI>The <B>events.sample</B> file contains information on auditable
-AFS events. The contents of this file are integrated into the
-corresponding AIX events file (<B>/etc/security/audit/events</B>).
-<P><LI>The <B>config.sample</B> file defines the six classes of AFS
-audit events and the events that make up each class. It also defines
-the classes of AFS audit events to audit for the File Server, which runs as
-the local superuser <B>root</B>. The contents of this file must be
-integrated into the corresponding AIX config file
-(<B>/etc/security/audit/config</B>).
-<P><LI>The <B>objects.sample</B> file contains a list of information
-about audited files. You must only audit files in the local file
-space. The contents of this file must be integrated into the
-corresponding AIX objects file
-(<B>/etc/security/audit/objects</B>).
-</UL>
-<P>Once you have properly configured these files to include the AFS-relevant
-information, use the AIX auditing system to start up and shut down the
-auditing.
-<P><H3><A NAME="Header_407" HREF="auagd002.htm#ToC_407">To enable AFS auditing</A></H3>
-<OL TYPE=1>
-<P><LI>Create the following string in the file <B>/usr/afs/local/Audit</B> on
-each File Server on which you plan to audit AFS events:
-<PRE> <B>AFS_AUDIT_AllEvents</B>
-</PRE>
-<P><LI>Issue the <B>bos restart</B> command (with the <B>-all</B> flag)
-to stop and restart all server processes on each File Server. For
-instructions on using this command, see <A HREF="auagd009.htm#HDRWQ224">Stopping and Immediately Restarting Processes</A>.
-</OL>
-<P><H3><A NAME="Header_408" HREF="auagd002.htm#ToC_408">To disable AFS auditing</A></H3>
-<OL TYPE=1>
-<P><LI>Remove the contents of the file <B>/usr/afs/local/Audit</B> on each
-File Server for which you are no longer interested in auditing AFS
-events.
-<P><LI>Issue the <B>bos restart</B> command (with the <B>-all</B> flag)
-to stop and restart all server processes on each File Server. For
-instructions on using this command, see <A HREF="auagd009.htm#HDRWQ224">Stopping and Immediately Restarting Processes</A>.
-</OL>
-<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>
-<!-- Begin Footer Records ========================================== -->
-<P><HR><B>
-<br>© <A HREF="http://www.ibm.com/">IBM Corporation 2000.</A> All Rights Reserved
-</B>
-<!-- End Footer Records ============================================ -->
-<A NAME="Bot_Of_Page"></A>
-</BODY></HTML>