NAME
scout - Monitors the File Server process
SYNOPSIS
scout [initcmd] -server <servers to monitor>+
[-basename <base server name>]
[-frequency <poll frequency, in seconds>] [-host]
[-attention <specify attention (highlighting) level>+]
[-debug <turn debugging output on to the named file>]
[-help]
scout [i] -s <servers to monitor>+
[-b <base server name>] [-f <poll frequency, in seconds>]
[-ho] [-a <specify attention (highlighting) level>+]
[-d <turn debugging output on to the named file>] [-he]
DESCRIPTION
The scout command displays statistics gathered from the File Server
process running on each machine specified with the -server argument.
OUTPUT explains the meaning of the statistics and describes how they
appear in the command shell, which is preferably a window managed by a
window manager program.
CAUTIONS
The scout program must be able to access the curses graphics package,
which it uses to display statistics. Most UNIX distributions include
curses as a standard utility.
Both dumb terminals and windowing systems that emulate terminals can
display the scout program’s statistics. The display makes use of
reverse video and cursor addressing, so the display environment must
support those features for it to look its best (most windowing systems
do, most dumb terminals do not). Also, set the TERM environment
variable to the correct terminal type, or one with characteristics
similar to the actual ones. For machines running the AIX operating
system, the recommended setting for TERM is "vt100", as long as the
terminal is similar to that. For other operating systems, the wider
range of acceptable values includes "xterm", "xterms", "vt100",
"vt200", and "wyse85".
OPTIONS
initcmd
Accommodates the command’s use of the AFS command parser, and is
optional.
-server <servers to monitor>+
Specifies each file server machine running a File Server process to
monitor. Provide each machine’s fully qualified hostname unless the
-basename argument is used. In that case, specify only the unique
initial part of each machine name, omitting the domain name suffix
(the basename) common to all the names. It is also acceptable to
use the shortest abbreviated form of a host name that distinguishes
it from other machines, but successful resolution depends on the
availability of a name resolution service (such as the Domain Name
Service or a local host table) at the time the command is issued.
-basename <base server name>
Specifies the basename (domain name) suffix common to all of the
file server machine names specified with the -server argument, and
is automatically appended to them. This argument is normally the
name of the cell to which the machines belong. Do not include the
period that separates this suffix from the distinguishing part of
each file server machine name, but do include any periods that
occur within the suffix itself. For example, in the ABC
Corporation cell, the proper value is "abc.com" rather than
".abc.com".
-frequency <poll frequency>
Indicates how often to probe the File Server processes. Specify a
number of seconds greater than 0 (zero). The default is 60 seconds.
-host
Displays the name of the machine that is running the scout program,
in the banner line of the display screen.
-attention <attention level>+
Defines a list of entries, each of which pairs a statistic and a
threshold value. When the value of the statistic exceeds the
indicated threshold value, it is highlighted (in reverse video) in
the display. List the pairs in any order. The acceptable values are
the following:
conn <connections>
Indicates the number of open connections to client processes at
which to highlight the statistic. The statistic returns to
regular display when the value goes back below the threshold.
There is no default threshold.
An example of an acceptable value is conn 300.
disk <blocks_free>
Indicates the number of remaining free kilobyte blocks at which
to highlight the statistic. The statistic returns to regular
display when the value again exceeds the threshold. There is no
default threshold.
An example of an acceptable value is disk 5000.
disk <percent_full>%
Indicates the percentage of disk usage at which to highlight
the statistic. The statistic returns to regular display when
the value goes back below the threshold. The default threshold
is 95%. Acceptable values are the integers in the range from 0
to 99, followed by the percent sign ("%") to distinguish this
type of value from the one described just previously.
An example is disk 90%.
fetch <fetch RPCs>
Indicates the cumulative number of fetch RPCs from client
processes at which to highlight the statistic. The statistic
does not return to regular display until the File Server
process restarts, at which time the value returns to zero.
There is no default threshold.
Example of a legal value: fetch 6000000
store <store RPCs>
Indicates the cumulative number of store RPCs from client
processes at which to highlight the statistic. The statistic
does not return to regular display until the File Server
process restarts, at which time the value returns to zero.
There is no default threshold.
Example of an acceptable value: store 200000
ws <active client machines>
Indicates the number of client machines with active open
connections at which to highlight the statistic. An active
connection is defined as one over which the File Server and
client have communicated in the last 15 minutes. The statistic
returns to regular display when the value goes back below the
threshold. There is no default threshold.
Example of an acceptable value: ws 65
-debug <debugging trace file>
Specifies the pathname of the file into which to write a debugging
trace. Partial pathnames are interpreted relative to the current
working directory.
-help
Prints the online help for this command. All other valid options
are ignored.
OUTPUT
The scout program can display statistics either in a dedicated window
or on a plain screen if a windowing environment is not available. For
best results, the window or screen needs the ability to print in
reverse video.
The scout screen has three main parts: the banner line, the statistics
display region and the message/probe line.
The Banner Line
By default, the string "Scout" appears in the banner line at the top of
the window or screen. Two optional arguments place additional
information in the banner line:
· The -host flag displays the name of the machine where the scout
program is running. As mentioned previously, this is useful when
running the scout program on several machines but displaying the
results on a single machine.
For example, when the -host flag is included and the scout program
is running on the machine "client1.abc.com", the banner line reads
as follows:
[client1.abc.com] Scout
· The -basename argument displays the indicated basename on the
banner line. For example, including the argument "-basename
abc.com" argument results in the following banner line:
Scout for abc.com
The Statistics Display Region
In this region, which occupies the majority of the window, the scout
process displays the statistics gathered for each File Server process.
Each process appears on its own line.
The region is divided into six columns, labeled as indicated and
displaying the following information:
Conn
The first column displays the number of RPC connections open
between the File Server process and client machines. This number
equals or exceeds the number in the "Ws" column (see the fourth
entry below), because each user on the machine can have several
separate connections open at once, and one client machine can
handle several users.
Fetch
The second column displays the number of fetch-type RPCs (fetch
data, fetch access list, and fetch status) that client machines
have made to the File Server process since the latter started.
This number is reset to zero each time the File Server process
restarts.
Store
The third column displays the number of store-type RPCs (store
data, store access list, and store status) that client machines
have made to the File Server process since the latter started. This
number is reset to zero each time the File Server process restarts.
Ws The fourth column displays the number of client machines ("Ws"
stands for workstations) that have communicated with the File
Server process within the last 15 minutes. Such machines are termed
active). This number is likely to be smaller than the number in the
first ("Conn") column because a single client machine can have
several connections open to one File Server.
server name
The fifth, unlabeled, column displays the name of the file server
machine on which the File Server process is running. Names of 12
characters or less are displayed in full; longer names are
truncated and an asterisk ("*") appears as the last character in
the name. Using the -basename argument is a good way to avoid
truncation, but only if all machine names end in a common string.
Disk attn
The sixth column displays the number of available kilobyte blocks
on each AFS disk partition on the file server machine.
The display for each partition has the following form:
x:<free_blocks>
where "x" indicates the partition name. For example, "a:8949"
specifies that the /vicepa partition has 8,949 1-KB blocks free.
Available space can be displayed for up to 26 partitions. If the
window is not wide enough for all partition entries to appear on a
single line, the scout process automatically creates multiple
lines, stacking the partition entries into sub-columns within the
sixth column.
The label on the "Disk attn" column indicates the threshold value
at which entries in the column become highlighted. By default, the
label is
Disk attn: > 95% used
because by default the scout program highlights the entry for any
partition that is over 95% full.
For all columns except the fifth (file server machine name), the
optional -attention argument sets the value at which entries in the
column are highlighted to indicate that a certain value has been
exceeded. Only values in the fifth and "Disk attn" columns ever become
highlighted by default.
If the scout program is unable to access or otherwise obtain
information about a partition, it generates a message similar to the
following example:
Could not get information on server fs1.abc.com partition /vicepa
The Message/Probe Line
The bottom line of the scout screen indicates how many times the scout
program has probed the File Server processes for statistics. The
statistics gathered in the latest probe appear in the statistics
display region. The -frequency argument overrides the default probe
frequency of 60 seconds.
EXAMPLES
See the chapter on monitoring tools in the IBM AFS Administration
Guide, which illustrates the displays that result from different
combinations of options.
PRIVILEGE REQUIRED
None
SEE ALSO
afsmonitor(1), fstrace(8)
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.