Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
AFSMONITOR(1)		     AFS Command Reference		 AFSMONITOR(1)

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:

       o   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.

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

       o   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:

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

       o   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.

       -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:

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

       o   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.)

       o   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.

       o   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:

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

       o   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.

OpenAFS				  2016-12-14			 AFSMONITOR(1)

NAME | SYNOPSIS | DESCRIPTION | CAUTIONS | OPTIONS | OUTPUT | EXAMPLES | PRIVILEGE REQUIRED | SEE ALSO | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=afsmonitor&sektion=1&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help