3 scout - Monitors the File Server process
7 B<scout> [B<initcmd>] B<-server> <I<servers to monitor>>+
8 [B<-basename> <I<base server name>>]
9 [B<-frequency> <I<poll frequency, in seconds>>] [B<-host>]
10 [B<-attention> <I<specify attention (highlighting) level>>+]
11 [B<-debug> <I<turn debugging output on to the named file>>]
14 B<scout> [B<i>] B<-s> <I<servers to monitor>>+
15 [B<-b> <I<base server name>>] [B<-f> <I<poll frequency, in seconds>>]
16 [B<-ho>] [B<-a> <I<specify attention (highlighting) level>>+]
17 [B<-d> <I<turn debugging output on to the named file>>] [B<-he>]
21 The scout command displays statistics gathered from the File Server
22 process running on each machine specified with the B<-server>
23 argument. L<OUTPUT> explains the meaning of the statistics and describes
24 how they appear in the command shell, which is preferably a window managed
25 by a window manager program.
29 The B<scout> program must be able to access the curses graphics package,
30 which it uses to display statistics. Most UNIX distributions include
31 curses as a standard utility.
33 Both dumb terminals and windowing systems that emulate terminals can
34 display the B<scout> program's statistics. The display makes use of
35 reverse video and cursor addressing, so the display environment must
36 support those features for it to look its best (most windowing systems do,
37 most dumb terminals do not). Also, set the TERM environment variable to
38 the correct terminal type, or one with characteristics similar to the
39 actual ones. For machines running the AIX operating system, the
40 recommended setting for TERM is C<vt100>, as long as the terminal is
41 similar to that. For other operating systems, the wider range of
42 acceptable values includes C<xterm>, C<xterms>, C<vt100>, C<vt200>, and
51 Accommodates the command's use of the AFS command parser, and is optional.
53 =item B<-server> <I<servers to monitor>>+
55 Specifies each file server machine running a File Server process to
56 monitor. Provide each machine's fully qualified hostname unless the
57 B<-basename> argument is used. In that case, specify only the unique
58 initial part of each machine name, omitting the domain name suffix (the
59 basename) common to all the names. It is also acceptable to use the
60 shortest abbreviated form of a host name that distinguishes it from other
61 machines, but successful resolution depends on the availability of a name
62 resolution service (such as the Domain Name Service or a local host table)
63 at the time the command is issued.
65 =item B<-basename> <I<base server name>>
67 Specifies the basename (domain name) suffix common to all of the file
68 server machine names specified with the B<-server> argument, and is
69 automatically appended to them. This argument is normally the name of the
70 cell to which the machines belong. Do not include the period that
71 separates this suffix from the distinguishing part of each file server
72 machine name, but do include any periods that occur within the suffix
73 itself. For example, in the ABC Corporation cell, the proper value is
74 C<abc.com> rather than C<.abc.com>.
76 =item B<-frequency> <I<poll frequency>>
78 Indicates how often to probe the File Server processes. Specify a number
79 of seconds greater than C<0> (zero). The default is 60 seconds.
83 Displays the name of the machine that is running the scout program, in the
84 banner line of the display screen.
86 =item B<-attention> <I<attention level>>+
88 Defines a list of entries, each of which pairs a statistic and a threshold
89 value. When the value of the statistic exceeds the indicated threshold
90 value, it is highlighted (in reverse video) in the display. List the pairs
91 in any order. The acceptable values are the following:
95 =item conn <I<connections>>
97 Indicates the number of open connections to client processes at which to
98 highlight the statistic. The statistic returns to regular display when
99 the value goes back below the threshold. There is no default threshold.
101 An example of an acceptable value is conn 300.
103 =item disk <I<blocks_free>>
105 Indicates the number of remaining free kilobyte blocks at which to
106 highlight the statistic. The statistic returns to regular display when the
107 value again exceeds the threshold. There is no default threshold.
109 An example of an acceptable value is disk 5000.
111 =item disk <I<percent_full>>%
113 Indicates the percentage of disk usage at which to highlight the
114 statistic. The statistic returns to regular display when the value goes
115 back below the threshold. The default threshold is 95%. Acceptable values
116 are the integers in the range from C<0> to C<99>, followed by the percent
117 sign (C<%>) to distinguish this type of value from the one described just
120 An example is disk 90%.
122 =item fetch <I<fetch RPCs>>
124 Indicates the cumulative number of fetch RPCs from client processes at
125 which to highlight the statistic. The statistic does not return to regular
126 display until the File Server process restarts, at which time the value
127 returns to zero. There is no default threshold.
129 Example of a legal value: fetch 6000000
131 =item store <I<store RPCs>>
133 Indicates the cumulative number of store RPCs from client processes at
134 which to highlight the statistic. The statistic does not return to regular
135 display until the File Server process restarts, at which time the value
136 returns to zero. There is no default threshold.
138 Example of an acceptable value: store 200000
140 =item ws <I<active client machines>>
142 Indicates the number of client machines with active open connections at
143 which to highlight the statistic. An active connection is defined as one
144 over which the File Server and client have communicated in the last 15
145 minutes. The statistic returns to regular display when the value goes back
146 below the threshold. There is no default threshold.
148 Example of an acceptable value: ws 65
152 =item B<-debug> <I<debugging trace file>>
154 Specifies the pathname of the file into which to write a debugging
155 trace. Partial pathnames are interpreted relative to the current working
160 Prints the online help for this command. All other valid options are
167 The B<scout> program can display statistics either in a dedicated window
168 or on a plain screen if a windowing environment is not available. For best
169 results, the window or screen needs the ability to print in reverse video.
171 The B<scout> screen has three main parts: the banner line, the statistics
172 display region and the message/probe line.
174 =head2 The Banner Line
176 By default, the string C<Scout> appears in the banner line at the top of
177 the window or screen. Two optional arguments place additional information
184 The B<-host> flag displays the name of the machine where the B<scout>
185 program is running. As mentioned previously, this is useful when running
186 the B<scout> program on several machines but displaying the results on a
189 For example, when the B<-host> flag is included and the B<scout> program
190 is running on the machine C<client1.abc.com>, the banner line reads as
193 [client1.abc.com] Scout
197 The B<-basename> argument displays the indicated basename on the banner
198 line. For example, including the argument C<-basename abc.com> argument
199 results in the following banner line:
205 =head2 The Statistics Display Region
207 In this region, which occupies the majority of the window, the B<scout>
208 process displays the statistics gathered for each File Server
209 process. Each process appears on its own line.
211 The region is divided into six columns, labeled as indicated and
212 displaying the following information:
218 The first column displays the number of RPC connections open between the
219 File Server process and client machines. This number equals or exceeds
220 the number in the C<Ws> column (see the fourth entry below), because each
221 user on the machine can have several separate connections open at once,
222 and one client machine can handle several users.
226 The second column displays the number of fetch-type RPCs (fetch data,
227 fetch access list, and fetch status) that client machines have made to the
228 File Server process since the latter started. This number is reset to
229 zero each time the File Server process restarts.
233 The third column displays the number of store-type RPCs (store data, store
234 access list, and store status) that client machines have made to the File
235 Server process since the latter started. This number is reset to zero each
236 time the File Server process restarts.
240 The fourth column displays the number of client machines (C<Ws> stands for
241 workstations) that have communicated with the File Server process within
242 the last 15 minutes. Such machines are termed I<active>). This number is
243 likely to be smaller than the number in the first (C<Conn>) column because
244 a single client machine can have several connections open to one File
249 The fifth, unlabeled, column displays the name of the file server machine
250 on which the File Server process is running. Names of 12 characters or
251 less are displayed in full; longer names are truncated and an asterisk
252 (C<*>) appears as the last character in the name. Using the B<-basename>
253 argument is a good way to avoid truncation, but only if all machine names
254 end in a common string.
258 The sixth column displays the number of available kilobyte blocks on each
259 AFS disk partition on the file server machine.
261 The display for each partition has the following form:
265 where C<x> indicates the partition name. For example, C<a:8949> specifies
266 that the F</vicepa> partition has 8,949 1-KB blocks free. Available space
267 can be displayed for up to 26 partitions. If the window is not wide enough
268 for all partition entries to appear on a single line, the B<scout> process
269 automatically creates multiple lines, stacking the partition entries into
270 sub-columns within the sixth column.
272 The label on the C<Disk attn> column indicates the threshold value at
273 which entries in the column become highlighted. By default, the label is
275 Disk attn: > 95% used
277 because by default the scout program highlights the entry for any
278 partition that is over 95% full.
282 For all columns except the fifth (file server machine name), the optional
283 B<-attention> argument sets the value at which entries in the column are
284 highlighted to indicate that a certain value has been exceeded. Only
285 values in the fifth and C<Disk attn> columns ever become highlighted by
288 If the scout program is unable to access or otherwise obtain information
289 about a partition, it generates a message similar to the following
292 Could not get information on server fs1.abc.com partition /vicepa
294 =head2 The Message/Probe Line
296 The bottom line of the scout screen indicates how many times the B<scout>
297 program has probed the File Server processes for statistics. The
298 statistics gathered in the latest probe appear in the statistics display
299 region. The B<-frequency> argument overrides the default probe frequency
304 See the chapter on monitoring tools in the I<IBM AFS Administration
305 Guide>, which illustrates the displays that result from different
306 combinations of options.
308 =head1 PRIVILEGE REQUIRED
319 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
321 This documentation is covered by the IBM Public License Version 1.0. It was
322 converted from HTML to POD by software written by Chas Williams and Russ
323 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.