Provided by: openafs-client_1.8.0~pre5-1ubuntu1.2_amd64 bug

NAME

       afsmonitor - Monitors File Servers and Cache Managers

SYNOPSIS

       afsmonitor [initcmd] [-config <configuration file>]
           [-frequency <poll frequency, in seconds>]
           [-output <storage file name>] [-detailed]
           [-debug <debug output file>]
           [-fshosts <list of file servers to monitor>+]
           [-cmhosts <list of cache managers to monitor>+]
           [-buffers <number of buffer slots>] [-version] [-help]

       afsmonitor [i]  [-co <configuration file>]
           [-fr <poll frequency, in seconds>]
           [-o <storage file name>] [-det]
           [-deb <debug output file>]
           [-fs <list of file servers to monitor>+]
           [-cm <list of cache managers to monitor>+]
           [-b <number of buffer slots>] [-version] [-h]

DESCRIPTION

       The afsmonitor command initializes a program that gathers and displays statistics about
       specified File Server and Cache Manager operations. It allows the issuer to monitor, from
       a single location, a wide range of File Server and Cache Manager operations on any number
       of machines in both local and foreign cells.

       There are 271 available File Server statistics and 571 available Cache Manager statistics,
       listed in the appendix about afsmonitor statistics in the OpenAFS Administration Guide. By
       default, the command displays all of the relevant statistics for the file server machines
       named by the -fshosts argument and the client machines named by the -cmhosts argument. To
       limit the display to only the statistics of interest, list them in the configuration file
       specified by the -config argument. In addition, use the configuration file for the
       following purposes:

       •   To set threshold values for any monitored statistic. When the value of a statistic
           exceeds the threshold, the afsmonitor command displays it in reverse video. There are
           no default threshold values.

       •   To invoke a program or script automatically when a statistic exceeds its threshold.
           The AFS distribution does not include any such scripts.

       •   To list the file server and client machines to monitor, instead of using the -fshosts
           and -cmhosts arguments.

       For a description of the configuration file, see afsmonitor(5).

CAUTIONS

       The following software must be accessible to a machine where the afsmonitor program is
       running:

       •   The AFS xstat libraries, which the afsmonitor program uses to gather data.

       •   The curses graphics package, which most UNIX distributions provide as a standard
           utility.

       The afsmonitor 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.

       The afsmonitor 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 afsmonitor program is running. Any number of instances of the afsmonitor 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.

OPTIONS

       initcmd
           Accommodates the command's use of the AFS command parser, and is optional.

       -config <file>
           Names the configuration file which lists the machines to monitor, statistics to
           display, and threshold values, if any. A partial pathname is interpreted relative to
           the current working directory. Provide this argument if not providing the -fshosts
           argument, -cmhosts argument, or neither. For instructions on creating this file, see
           the preceding DESCRIPTION section, and the section on the afsmonitor program in the
           OpenAFS Administration Guide.

       -frequency <poll frequency>
           Specifies in seconds how often the afsmonitor program probes the File Servers and
           Cache Managers. Valid values range from 1 to 86400 (which is 24 hours); the default
           value is 60. This frequency applies to both File Servers and Cache Managers, but the
           afsmonitor program initiates the two types of probes, and processes their results,
           separately. The actual interval between probes to a host is the probe frequency plus
           the time required for all hosts to respond.

       -output <file>
           Names the file to which the afsmonitor program writes all of the statistics that it
           collects. By default, no output file is created. See the section on the afsmonitor
           command in the OpenAFS Administration Guide for information on this file.

       -detailed
           Formats the information in the output file named by -output argument in a maximally
           readable format. Provide the -output argument along with this one.

       -fshosts <host>+
           Names one or more machines from which to gather File Server statistics. For each
           machine, provide either a fully qualified host name, or an unambiguous abbreviation
           (the ability to resolve an abbreviation depends on the state of the cell's name
           service at the time the command is issued). This argument can be combined with the
           -cmhosts argument, but not with the -config argument.

       -cmhosts <host>+
           Names one or more machines from which to gather Cache Manager statistics. For each
           machine, provide either a fully qualified host name, or an unambiguous abbreviation
           (the ability to resolve an abbreviation depends on the state of the cell's name
           service at the time the command is issued). This argument can be combined with the
           -fshosts argument, but not with the -config argument.

       -buffers <slots>
           Is nonoperational and provided to accommodate potential future enhancements to the
           program.

       -debug <debut output file>
           Turns on debugging output, and writes debugging information to the specified file.

       -help
           Prints the online help for this command. All other valid options are ignored.

       -version
           Prints the program version and then exits. All other valid options are ignored.

OUTPUT

       The afsmonitor program displays its data on three screens:

       System Overview
           This screen appears automatically when the afsmonitor program initializes. It
           summarizes separately for File Servers and Cache Managers the number of machines being
           monitored and how many of them have alerts (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.

       File Server
           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.

       Cache Managers
           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.

       Fields at the corners of every screen display the following information:

       •   In the top left corner, the program name and version number.

       •   In the top right corner, the screen name, current and total page numbers, and current
           and total column numbers. The page number (for example, "p. 1 of 3") indicates the
           index of the current page and the total number of (vertical) pages over which data is
           displayed. The column number (for example, "c. 1 of 235") indicates the index of the
           current leftmost column and the total number of columns in which data appears. (The
           symbol ">>>" indicates that there is additional data to the right; the symbol "<<<"
           indicates that there is additional data to the left.)

       •   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 "next" and "prev" 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.

       •   In the bottom right corner, the "probes" field reports how many times the program has
           probed File Servers ("fs"), Cache Managers ("cm"), or both. The counts for File
           Servers and Cache Managers can differ. The "freq" field reports how often the program
           sends probes.

   Navigating the afsmonitor Display Screens
       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.

       "cm"
           Switches to the "Cache Managers" screen. Available only on the "System Overview" and
           "File Servers" screens.

       "fs"
           Switches to the "File Servers" screen. Available only on the "System Overview" and the
           "Cache Managers" screens.

       "left"
           Scrolls horizontally to the left, to access the data columns situated to the left of
           the current set. Available when the "<<<" symbol appears at the top left of the
           screen. Press uppercase "L" to scroll horizontally all the way to the left (to display
           the first set of data columns).

       "next"
           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 "N" to scroll to the final page.

       "oview"
           Switches to the "System Overview" screen. Available only on the "Cache Managers" and
           "File Servers" screens.

       "prev"
           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 "N" to scroll to the first page.

       "right"
           Scrolls horizontally to the right, to access the data columns situated to the right of
           the current set. This command is available when the ">>>" symbol appears at the upper
           right of the screen. Press uppercase "R" to scroll horizontally all the way to the
           right (to display the final set of data columns).

   The System Overview Screen
       The "System Overview" screen appears automatically as the afsmonitor 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.

       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:

       •   The number of machines on which the program is monitoring the indicated process.

       •   The number of alerts and the number of machines affected by them (an alert means that
           a statistic has exceeded its threshold or a process failed to respond to the last
           probe).

       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 "PF" (probe failure) appear in square brackets
       to the left of the hostname.

   The File Servers Screen
       The "File Servers" screen displays the values collected at the most recent probe for File
       Server statistics.

       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.

       The first column always displays the hostnames of the machines running the monitored File
       Servers.

       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 ("--")
       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.

   The Cache Managers Screen
       The "Cache Managers" screen displays the values collected at the most recent probe for
       Cache Manager statistics.

       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.

       The first column always displays the hostnames of the machines running the monitored Cache
       Managers.

       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 ("--")
       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.

   Writing to an Output File
       Include the -output argument to name the file into which the afsmonitor program writes all
       of the statistics it collects.  The output file can be useful for tracking performance
       over long periods of time, and enables the administrator to apply post-processing
       techniques that reveal system trends. The AFS distribution does not include any post-
       processing programs.

       The output file is in ASCII format and records the same information as the "File Server"
       and "Cache Manager" display screens.  Each line in the file uses the following format to
       record the time at which the afsmonitor program gathered the indicated statistic from the
       Cache Manager ("CM") or File Server ("FS") running on the machine called host_name. If a
       probe failed, the error code "-1" appears in the statistic field.

          <time>  <host_name>  CM|FS   <statistic>

       If the administrator usually reviews the output file manually, rather than using it as
       input to an automated analysis program or script, including the -detail flag formats the
       data in a more easily readable form.

EXAMPLES

       For examples of commands, display screens, and configuration files, see the section about
       the afsmonitor program in the OpenAFS Administration Guide.

PRIVILEGE REQUIRED

       None

SEE ALSO

       afsmonitor(5) fstrace(8), scout(1)

       The OpenAFS Administration Guide at <http://docs.openafs.org/AdminGuide/>.

COPYRIGHT

       IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.

       This documentation is covered by the IBM Public License Version 1.0.  It was converted
       from HTML to POD by software written by Chas Williams and Russ Allbery, based on work by
       Alf Wachsmann and Elizabeth Cassell.