Provided by: openafs-client_1.6.7-1ubuntu1.1_amd64 bug

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>+]
             [-columnwidths <number of characters>+]
             [-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>+]
             [-c <number of characters+>]
             [-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

       -columnwidths <number of characters>+
           Specifies the number of characters to display in each column of the scout statistics
           display region. Specify one to six numbers separated by spaces to set the number of
           characters to be displayed in each column.  The values specify the widths of the
           columns in the same order the columns are displayed from left to right.  Use 0 as a
           placeholder to specify a default column width.

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