Command Reference Manual

scout

Purpose

Monitors the File Server process

Synopsis

scout [initcmd]  -server <FileServer name(s) 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 <FileServer name(s) 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. The Output section explains the meaning of the statistics and describes how they appear on the screen.

Cautions

The scout process 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

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

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 .transarc.com.

-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 process, in the banner line of the display screen.

-attention

Defines a list of entries, each pairing 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. 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, which takes one of two types of values:
- 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.
  An example is disk 90%.
- 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 goes back above the threshold. There is no default threshold.
  An example of an acceptable value is disk 5000.
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 0 (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 0 (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

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

Scout 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 should have 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 word "scout" appears in the banner line at the top of the window or screen, to indicate that the scout process is running. Two command-line arguments place additional information in the banner line:

The -host flag causes the scout process to display this machine name in the banner line. As mentioned previously, this is useful when running the scout process on several machines but displaying the results on a single machine.
For example, -host is used when the scout process is running on the machine client1.abc.com, the banner line reads:
```
[client1.abc.com] Scout
```
The -basename argument causes the scout process to display the indicated basename on the banner line. For example, using the argument -basename abc.com argument causes the banner line to read:
```
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 should equal or exceed the number in the Ws column (see the fourth entry below). It can exceed the Ws number 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 (workstations) that have communicated with the File Server process within the last 15 minutes (such machines are defined as "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.
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 form
```
x:free_blocks
```
where x indicates the partition name. For example, a:8949 specifies that the /vicepa partition has 8,949 1Kbyte 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 process 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 should be highlighted to indicate that a certain value has been exceeded. Only the fifth and Disk attn columns ever become highlighted by default.

The scout command includes the name of the file server in a message when a problem exists on a partition. An example of the scout message for a partition named /vicepa on a file server named fs1.abc.com follows:

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 process 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 the scout process in the AFS System Administrator's Guide, which illustrates the displays that result from different combinations of arguments and flags.

Privilege Required

None