doc: fix some broken link specifications
[openafs.git] / doc / man-pages / pod1 / scout.pod
1 =head1 NAME
2
3 scout - Monitors the File Server process
4
5 =head1 SYNOPSIS
6
7 =for html
8 <div class="synopsis">
9
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<-columnwidths> <I<number of characters>>+] >>>
15       S<<< [B<-debug> <I<turn debugging output on to the named file>>] >>>
16       [B<-help>]
17
18 B<scout> [B<i>] S<<< B<-s> <I<servers to monitor>>+ >>>
19       S<<< [B<-b> <I<base server name>>] >>> S<<< [B<-f> <I<poll frequency, in seconds>>] >>>
20       [B<-ho>] S<<< [B<-a> <I<specify attention (highlighting) level>>+] >>>
21       S<<< [B<-c> <I<number of characters>+>] >>>
22       S<<< [B<-d> <I<turn debugging output on to the named file>>] >>> [B<-he>]
23
24 =for html
25 </div>
26
27 =head1 DESCRIPTION
28
29 The scout command displays statistics gathered from the File Server
30 process running on each machine specified with the B<-server>
31 argument. L</OUTPUT> explains the meaning of the statistics and describes
32 how they appear in the command shell, which is preferably a window managed
33 by a window manager program.
34
35 =head1 CAUTIONS
36
37 The B<scout> program must be able to access the curses graphics package,
38 which it uses to display statistics. Most UNIX distributions include
39 curses as a standard utility.
40
41 Both dumb terminals and windowing systems that emulate terminals can
42 display the B<scout> program's statistics. The display makes use of
43 reverse video and cursor addressing, so the display environment must
44 support those features for it to look its best (most windowing systems do,
45 most dumb terminals do not). Also, set the TERM environment variable to
46 the correct terminal type, or one with characteristics similar to the
47 actual ones. For machines running the AIX operating system, the
48 recommended setting for TERM is C<vt100>, as long as the terminal is
49 similar to that. For other operating systems, the wider range of
50 acceptable values includes C<xterm>, C<xterms>, C<vt100>, C<vt200>, and
51 C<wyse85>.
52
53 =head1 OPTIONS
54
55 =over 4
56
57 =item B<initcmd>
58
59 Accommodates the command's use of the AFS command parser, and is optional.
60
61 =item B<-server> <I<servers to monitor>>+
62
63 Specifies each file server machine running a File Server process to
64 monitor. Provide each machine's fully qualified hostname unless the
65 B<-basename> argument is used. In that case, specify only the unique
66 initial part of each machine name, omitting the domain name suffix (the
67 basename) common to all the names. It is also acceptable to use the
68 shortest abbreviated form of a host name that distinguishes it from other
69 machines, but successful resolution depends on the availability of a name
70 resolution service (such as the Domain Name Service or a local host table)
71 at the time the command is issued.
72
73 =item B<-basename> <I<base server name>>
74
75 Specifies the basename (domain name) suffix common to all of the file
76 server machine names specified with the B<-server> argument, and is
77 automatically appended to them. This argument is normally the name of the
78 cell to which the machines belong. Do not include the period that
79 separates this suffix from the distinguishing part of each file server
80 machine name, but do include any periods that occur within the suffix
81 itself.  For example, in the ABC Corporation cell, the proper value is
82 C<abc.com> rather than C<.abc.com>.
83
84 =item B<-frequency> <I<poll frequency>>
85
86 Indicates how often to probe the File Server processes. Specify a number
87 of seconds greater than C<0> (zero). The default is 60 seconds.
88
89 =item B<-host>
90
91 Displays the name of the machine that is running the scout program, in the
92 banner line of the display screen.
93
94 =item B<-attention> <I<attention level>>+
95
96 Defines a list of entries, each of which pairs a statistic and a threshold
97 value. When the value of the statistic exceeds the indicated threshold
98 value, it is highlighted (in reverse video) in the display. List the pairs
99 in any order. The acceptable values are the following:
100
101 =over 4
102
103 =item conn <I<connections>>
104
105 Indicates the number of open connections to client processes at which to
106 highlight the statistic.  The statistic returns to regular display when
107 the value goes back below the threshold. There is no default threshold.
108
109 An example of an acceptable value is conn 300.
110
111 =item disk <I<blocks_free>>
112
113 Indicates the number of remaining free kilobyte blocks at which to
114 highlight the statistic. The statistic returns to regular display when the
115 value again exceeds the threshold. There is no default threshold.
116
117 An example of an acceptable value is disk 5000.
118
119 =item disk <I<percent_full>>%
120
121 Indicates the percentage of disk usage at which to highlight the
122 statistic. The statistic returns to regular display when the value goes
123 back below the threshold. The default threshold is 95%. Acceptable values
124 are the integers in the range from C<0> to C<99>, followed by the percent
125 sign (C<%>) to distinguish this type of value from the one described just
126 previously.
127
128 An example is disk 90%.
129
130 =item fetch <I<fetch RPCs>>
131
132 Indicates the cumulative number of fetch RPCs from client processes at
133 which to highlight the statistic. The statistic does not return to regular
134 display until the File Server process restarts, at which time the value
135 returns to zero.  There is no default threshold.
136
137 Example of a legal value: fetch 6000000
138
139 =item store <I<store RPCs>>
140
141 Indicates the cumulative number of store RPCs from client processes at
142 which to highlight the statistic. The statistic does not return to regular
143 display until the File Server process restarts, at which time the value
144 returns to zero.  There is no default threshold.
145
146 Example of an acceptable value: store 200000
147
148 =item ws <I<active client machines>>
149
150 Indicates the number of client machines with active open connections at
151 which to highlight the statistic. An active connection is defined as one
152 over which the File Server and client have communicated in the last 15
153 minutes. The statistic returns to regular display when the value goes back
154 below the threshold. There is no default threshold.
155
156 Example of an acceptable value: ws 65
157
158 =back
159
160 =item B<-columnwidths> <I<number of characters>>+
161
162 Specifies the number of characters to display in each column of the B<scout>
163 statistics display region. Specify one to six numbers separated by spaces to
164 set the number of characters to be displayed in each column.  The values
165 specify the widths of the columns in the same order the columns are displayed
166 from left to right.  Use 0 as a placeholder to specify a default column width.
167
168 =item B<-debug> <I<debugging trace file>>
169
170 Specifies the pathname of the file into which to write a debugging
171 trace. Partial pathnames are interpreted relative to the current working
172 directory.
173
174 =item B<-help>
175
176 Prints the online help for this command. All other valid options are
177 ignored.
178
179 =back
180
181 =head1 OUTPUT
182
183 The B<scout> program can display statistics either in a dedicated window
184 or on a plain screen if a windowing environment is not available. For best
185 results, the window or screen needs the ability to print in reverse video.
186
187 The B<scout> screen has three main parts: the banner line, the statistics
188 display region and the message/probe line.
189
190 =head2 The Banner Line
191
192 By default, the string C<Scout> appears in the banner line at the top of
193 the window or screen. Two optional arguments place additional information
194 in the banner line:
195
196 =over 4
197
198 =item *
199
200 The B<-host> flag displays the name of the machine where the B<scout>
201 program is running. As mentioned previously, this is useful when running
202 the B<scout> program on several machines but displaying the results on a
203 single machine.
204
205 For example, when the B<-host> flag is included and the B<scout> program
206 is running on the machine C<client1.abc.com>, the banner line reads as
207 follows:
208
209    [client1.abc.com] Scout
210
211 =item *
212
213 The B<-basename> argument displays the indicated basename on the banner
214 line. For example, including the argument C<-basename abc.com> argument
215 results in the following banner line:
216
217    Scout for abc.com
218
219 =back
220
221 =head2 The Statistics Display Region
222
223 In this region, which occupies the majority of the window, the B<scout>
224 process displays the statistics gathered for each File Server
225 process. Each process appears on its own line.
226
227 The region is divided into six columns, labeled as indicated and
228 displaying the following information:
229
230 =over 4
231
232 =item Conn
233
234 The first column displays the number of RPC connections open between the
235 File Server process and client machines.  This number equals or exceeds
236 the number in the C<Ws> column (see the fourth entry below), because each
237 user on the machine can have several separate connections open at once,
238 and one client machine can handle several users.
239
240 =item Fetch
241
242 The second column displays the number of fetch-type RPCs (fetch data,
243 fetch access list, and fetch status) that client machines have made to the
244 File Server process since the latter started.  This number is reset to
245 zero each time the File Server process restarts.
246
247 =item Store
248
249 The third column displays the number of store-type RPCs (store data, store
250 access list, and store status) that client machines have made to the File
251 Server process since the latter started. This number is reset to zero each
252 time the File Server process restarts.
253
254 =item Ws
255
256 The fourth column displays the number of client machines (C<Ws> stands for
257 workstations) that have communicated with the File Server process within
258 the last 15 minutes. Such machines are termed I<active>). This number is
259 likely to be smaller than the number in the first (C<Conn>) column because
260 a single client machine can have several connections open to one File
261 Server.
262
263 =item server name
264
265 The fifth, unlabeled, column displays the name of the file server machine
266 on which the File Server process is running. Names of 12 characters or
267 less are displayed in full; longer names are truncated and an asterisk
268 (C<*>) appears as the last character in the name. Using the B<-basename>
269 argument is a good way to avoid truncation, but only if all machine names
270 end in a common string.
271
272 =item Disk attn
273
274 The sixth column displays the number of available kilobyte blocks on each
275 AFS disk partition on the file server machine.
276
277 The display for each partition has the following form:
278
279    x:<free_blocks>
280
281 where C<x> indicates the partition name. For example, C<a:8949> specifies
282 that the F</vicepa> partition has 8,949 1-KB blocks free. Available space
283 can be displayed for up to 26 partitions. If the window is not wide enough
284 for all partition entries to appear on a single line, the B<scout> process
285 automatically creates multiple lines, stacking the partition entries into
286 sub-columns within the sixth column.
287
288 The label on the C<Disk attn> column indicates the threshold value at
289 which entries in the column become highlighted. By default, the label is
290
291    Disk attn: > 95% used
292
293 because by default the scout program highlights the entry for any
294 partition that is over 95% full.
295
296 =back
297
298 For all columns except the fifth (file server machine name), the optional
299 B<-attention> argument sets the value at which entries in the column are
300 highlighted to indicate that a certain value has been exceeded.  Only
301 values in the fifth and C<Disk attn> columns ever become highlighted by
302 default.
303
304 If the scout program is unable to access or otherwise obtain information
305 about a partition, it generates a message similar to the following
306 example:
307
308    Could not get information on server fs1.abc.com partition /vicepa
309
310 =head2 The Message/Probe Line
311
312 The bottom line of the scout screen indicates how many times the B<scout>
313 program has probed the File Server processes for statistics. The
314 statistics gathered in the latest probe appear in the statistics display
315 region. The B<-frequency> argument overrides the default probe frequency
316 of 60 seconds.
317
318 =head1 EXAMPLES
319
320 See the chapter on monitoring tools in the I<OpenAFS Administration
321 Guide>, which illustrates the displays that result from different
322 combinations of options.
323
324 =head1 PRIVILEGE REQUIRED
325
326 None
327
328 =head1 SEE ALSO
329
330 L<afsmonitor(1)>,
331 L<fstrace(8)>
332
333 =head1 COPYRIGHT
334
335 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
336
337 This documentation is covered by the IBM Public License Version 1.0.  It was
338 converted from HTML to POD by software written by Chas Williams and Russ
339 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.