3 scout - Monitors the File Server process
10 B<scout> [B<initcmd>] S<<< B<-server> <I<servers to monitor>>+ >>>
11 S<<< [B<-basename> <I<base server name>>] >>>
12 S<<< [B<-frequency> <I<poll frequency, in seconds>>] >>> [B<-host>]
13 S<<< [B<-attention> <I<specify attention (highlighting) level>>+] >>>
14 S<<< [B<-debug> <I<turn debugging output on to the named file>>] >>>
17 B<scout> [B<i>] S<<< B<-s> <I<servers to monitor>>+ >>>
18 S<<< [B<-b> <I<base server name>>] >>> S<<< [B<-f> <I<poll frequency, in seconds>>] >>>
19 [B<-ho>] S<<< [B<-a> <I<specify attention (highlighting) level>>+] >>>
20 S<<< [B<-d> <I<turn debugging output on to the named file>>] >>> [B<-he>]
27 The scout command displays statistics gathered from the File Server
28 process running on each machine specified with the B<-server>
29 argument. L<OUTPUT> explains the meaning of the statistics and describes
30 how they appear in the command shell, which is preferably a window managed
31 by a window manager program.
35 The B<scout> program must be able to access the curses graphics package,
36 which it uses to display statistics. Most UNIX distributions include
37 curses as a standard utility.
39 Both dumb terminals and windowing systems that emulate terminals can
40 display the B<scout> program's statistics. The display makes use of
41 reverse video and cursor addressing, so the display environment must
42 support those features for it to look its best (most windowing systems do,
43 most dumb terminals do not). Also, set the TERM environment variable to
44 the correct terminal type, or one with characteristics similar to the
45 actual ones. For machines running the AIX operating system, the
46 recommended setting for TERM is C<vt100>, as long as the terminal is
47 similar to that. For other operating systems, the wider range of
48 acceptable values includes C<xterm>, C<xterms>, C<vt100>, C<vt200>, and
57 Accommodates the command's use of the AFS command parser, and is optional.
59 =item B<-server> <I<servers to monitor>>+
61 Specifies each file server machine running a File Server process to
62 monitor. Provide each machine's fully qualified hostname unless the
63 B<-basename> argument is used. In that case, specify only the unique
64 initial part of each machine name, omitting the domain name suffix (the
65 basename) common to all the names. It is also acceptable to use the
66 shortest abbreviated form of a host name that distinguishes it from other
67 machines, but successful resolution depends on the availability of a name
68 resolution service (such as the Domain Name Service or a local host table)
69 at the time the command is issued.
71 =item B<-basename> <I<base server name>>
73 Specifies the basename (domain name) suffix common to all of the file
74 server machine names specified with the B<-server> argument, and is
75 automatically appended to them. This argument is normally the name of the
76 cell to which the machines belong. Do not include the period that
77 separates this suffix from the distinguishing part of each file server
78 machine name, but do include any periods that occur within the suffix
79 itself. For example, in the ABC Corporation cell, the proper value is
80 C<abc.com> rather than C<.abc.com>.
82 =item B<-frequency> <I<poll frequency>>
84 Indicates how often to probe the File Server processes. Specify a number
85 of seconds greater than C<0> (zero). The default is 60 seconds.
89 Displays the name of the machine that is running the scout program, in the
90 banner line of the display screen.
92 =item B<-attention> <I<attention level>>+
94 Defines a list of entries, each of which pairs a statistic and a threshold
95 value. When the value of the statistic exceeds the indicated threshold
96 value, it is highlighted (in reverse video) in the display. List the pairs
97 in any order. The acceptable values are the following:
101 =item conn <I<connections>>
103 Indicates the number of open connections to client processes at which to
104 highlight the statistic. The statistic returns to regular display when
105 the value goes back below the threshold. There is no default threshold.
107 An example of an acceptable value is conn 300.
109 =item disk <I<blocks_free>>
111 Indicates the number of remaining free kilobyte blocks at which to
112 highlight the statistic. The statistic returns to regular display when the
113 value again exceeds the threshold. There is no default threshold.
115 An example of an acceptable value is disk 5000.
117 =item disk <I<percent_full>>%
119 Indicates the percentage of disk usage at which to highlight the
120 statistic. The statistic returns to regular display when the value goes
121 back below the threshold. The default threshold is 95%. Acceptable values
122 are the integers in the range from C<0> to C<99>, followed by the percent
123 sign (C<%>) to distinguish this type of value from the one described just
126 An example is disk 90%.
128 =item fetch <I<fetch RPCs>>
130 Indicates the cumulative number of fetch RPCs from client processes at
131 which to highlight the statistic. The statistic does not return to regular
132 display until the File Server process restarts, at which time the value
133 returns to zero. There is no default threshold.
135 Example of a legal value: fetch 6000000
137 =item store <I<store RPCs>>
139 Indicates the cumulative number of store RPCs from client processes at
140 which to highlight the statistic. The statistic does not return to regular
141 display until the File Server process restarts, at which time the value
142 returns to zero. There is no default threshold.
144 Example of an acceptable value: store 200000
146 =item ws <I<active client machines>>
148 Indicates the number of client machines with active open connections at
149 which to highlight the statistic. An active connection is defined as one
150 over which the File Server and client have communicated in the last 15
151 minutes. The statistic returns to regular display when the value goes back
152 below the threshold. There is no default threshold.
154 Example of an acceptable value: ws 65
158 =item B<-debug> <I<debugging trace file>>
160 Specifies the pathname of the file into which to write a debugging
161 trace. Partial pathnames are interpreted relative to the current working
166 Prints the online help for this command. All other valid options are
173 The B<scout> program can display statistics either in a dedicated window
174 or on a plain screen if a windowing environment is not available. For best
175 results, the window or screen needs the ability to print in reverse video.
177 The B<scout> screen has three main parts: the banner line, the statistics
178 display region and the message/probe line.
180 =head2 The Banner Line
182 By default, the string C<Scout> appears in the banner line at the top of
183 the window or screen. Two optional arguments place additional information
190 The B<-host> flag displays the name of the machine where the B<scout>
191 program is running. As mentioned previously, this is useful when running
192 the B<scout> program on several machines but displaying the results on a
195 For example, when the B<-host> flag is included and the B<scout> program
196 is running on the machine C<client1.abc.com>, the banner line reads as
199 [client1.abc.com] Scout
203 The B<-basename> argument displays the indicated basename on the banner
204 line. For example, including the argument C<-basename abc.com> argument
205 results in the following banner line:
211 =head2 The Statistics Display Region
213 In this region, which occupies the majority of the window, the B<scout>
214 process displays the statistics gathered for each File Server
215 process. Each process appears on its own line.
217 The region is divided into six columns, labeled as indicated and
218 displaying the following information:
224 The first column displays the number of RPC connections open between the
225 File Server process and client machines. This number equals or exceeds
226 the number in the C<Ws> column (see the fourth entry below), because each
227 user on the machine can have several separate connections open at once,
228 and one client machine can handle several users.
232 The second column displays the number of fetch-type RPCs (fetch data,
233 fetch access list, and fetch status) that client machines have made to the
234 File Server process since the latter started. This number is reset to
235 zero each time the File Server process restarts.
239 The third column displays the number of store-type RPCs (store data, store
240 access list, and store status) that client machines have made to the File
241 Server process since the latter started. This number is reset to zero each
242 time the File Server process restarts.
246 The fourth column displays the number of client machines (C<Ws> stands for
247 workstations) that have communicated with the File Server process within
248 the last 15 minutes. Such machines are termed I<active>). This number is
249 likely to be smaller than the number in the first (C<Conn>) column because
250 a single client machine can have several connections open to one File
255 The fifth, unlabeled, column displays the name of the file server machine
256 on which the File Server process is running. Names of 12 characters or
257 less are displayed in full; longer names are truncated and an asterisk
258 (C<*>) appears as the last character in the name. Using the B<-basename>
259 argument is a good way to avoid truncation, but only if all machine names
260 end in a common string.
264 The sixth column displays the number of available kilobyte blocks on each
265 AFS disk partition on the file server machine.
267 The display for each partition has the following form:
271 where C<x> indicates the partition name. For example, C<a:8949> specifies
272 that the F</vicepa> partition has 8,949 1-KB blocks free. Available space
273 can be displayed for up to 26 partitions. If the window is not wide enough
274 for all partition entries to appear on a single line, the B<scout> process
275 automatically creates multiple lines, stacking the partition entries into
276 sub-columns within the sixth column.
278 The label on the C<Disk attn> column indicates the threshold value at
279 which entries in the column become highlighted. By default, the label is
281 Disk attn: > 95% used
283 because by default the scout program highlights the entry for any
284 partition that is over 95% full.
288 For all columns except the fifth (file server machine name), the optional
289 B<-attention> argument sets the value at which entries in the column are
290 highlighted to indicate that a certain value has been exceeded. Only
291 values in the fifth and C<Disk attn> columns ever become highlighted by
294 If the scout program is unable to access or otherwise obtain information
295 about a partition, it generates a message similar to the following
298 Could not get information on server fs1.abc.com partition /vicepa
300 =head2 The Message/Probe Line
302 The bottom line of the scout screen indicates how many times the B<scout>
303 program has probed the File Server processes for statistics. The
304 statistics gathered in the latest probe appear in the statistics display
305 region. The B<-frequency> argument overrides the default probe frequency
310 See the chapter on monitoring tools in the I<IBM AFS Administration
311 Guide>, which illustrates the displays that result from different
312 combinations of options.
314 =head1 PRIVILEGE REQUIRED
325 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
327 This documentation is covered by the IBM Public License Version 1.0. It was
328 converted from HTML to POD by software written by Chas Williams and Russ
329 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.