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<-version>] [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<-version>] [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 Example Corporation cell, the proper value is
  82 C<example.com> rather than C<.example.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 =item B<-version>
 180
 181 Prints the program version and then exits. All other valid options
 182 are ignored.
 183
 184 =back
 185
 186 =head1 OUTPUT
 187
 188 The B<scout> program can display statistics either in a dedicated window
 189 or on a plain screen if a windowing environment is not available. For best
 190 results, the window or screen needs the ability to print in reverse video.
 191
 192 The B<scout> screen has three main parts: the banner line, the statistics
 193 display region and the message/probe line.
 194
 195 =head2 The Banner Line
 196
 197 By default, the string C<Scout> appears in the banner line at the top of
 198 the window or screen. Two optional arguments place additional information
 199 in the banner line:
 200
 201 =over 4
 202
 203 =item *
 204
 205 The B<-host> flag displays the name of the machine where the B<scout>
 206 program is running. As mentioned previously, this is useful when running
 207 the B<scout> program on several machines but displaying the results on a
 208 single machine.
 209
 210 For example, when the B<-host> flag is included and the B<scout> program
 211 is running on the machine C<client1.example.com>, the banner line reads as
 212 follows:
 213
 214    [client1.example.com] Scout
 215
 216 =item *
 217
 218 The B<-basename> argument displays the indicated basename on the banner
 219 line. For example, including the argument C<-basename example.com> argument
 220 results in the following banner line:
 221
 222    Scout for example.com
 223
 224 =back
 225
 226 =head2 The Statistics Display Region
 227
 228 In this region, which occupies the majority of the window, the B<scout>
 229 process displays the statistics gathered for each File Server
 230 process. Each process appears on its own line.
 231
 232 The region is divided into six columns, labeled as indicated and
 233 displaying the following information:
 234
 235 =over 4
 236
 237 =item Conn
 238
 239 The first column displays the number of RPC connections open between the
 240 File Server process and client machines.  This number equals or exceeds
 241 the number in the C<Ws> column (see the fourth entry below), because each
 242 user on the machine can have several separate connections open at once,
 243 and one client machine can handle several users.
 244
 245 =item Fetch
 246
 247 The second column displays the number of fetch-type RPCs (fetch data,
 248 fetch access list, and fetch status) that client machines have made to the
 249 File Server process since the latter started.  This number is reset to
 250 zero each time the File Server process restarts.
 251
 252 =item Store
 253
 254 The third column displays the number of store-type RPCs (store data, store
 255 access list, and store status) that client machines have made to the File
 256 Server process since the latter started. This number is reset to zero each
 257 time the File Server process restarts.
 258
 259 =item Ws
 260
 261 The fourth column displays the number of client machines (C<Ws> stands for
 262 workstations) that have communicated with the File Server process within
 263 the last 15 minutes. Such machines are termed I<active>). This number is
 264 likely to be smaller than the number in the first (C<Conn>) column because
 265 a single client machine can have several connections open to one File
 266 Server.
 267
 268 =item server name
 269
 270 The fifth, unlabeled, column displays the name of the file server machine
 271 on which the File Server process is running. Names of 12 characters or
 272 less are displayed in full; longer names are truncated and an asterisk
 273 (C<*>) appears as the last character in the name. Using the B<-basename>
 274 argument is a good way to avoid truncation, but only if all machine names
 275 end in a common string.
 276
 277 =item Disk attn
 278
 279 The sixth column displays the number of available kilobyte blocks on each
 280 AFS disk partition on the file server machine.
 281
 282 The display for each partition has the following form:
 283
 284    x:<free_blocks>
 285
 286 where C<x> indicates the partition name. For example, C<a:8949> specifies
 287 that the F</vicepa> partition has 8,949 1-KB blocks free. Available space
 288 can be displayed for up to 26 partitions. If the window is not wide enough
 289 for all partition entries to appear on a single line, the B<scout> process
 290 automatically creates multiple lines, stacking the partition entries into
 291 sub-columns within the sixth column.
 292
 293 The label on the C<Disk attn> column indicates the threshold value at
 294 which entries in the column become highlighted. By default, the label is
 295
 296    Disk attn: > 95% used
 297
 298 because by default the scout program highlights the entry for any
 299 partition that is over 95% full.
 300
 301 =back
 302
 303 For all columns except the fifth (file server machine name), the optional
 304 B<-attention> argument sets the value at which entries in the column are
 305 highlighted to indicate that a certain value has been exceeded.  Only
 306 values in the fifth and C<Disk attn> columns ever become highlighted by
 307 default.
 308
 309 If the scout program is unable to access or otherwise obtain information
 310 about a partition, it generates a message similar to the following
 311 example:
 312
 313    Could not get information on server fs1.example.com partition /vicepa
 314
 315 =head2 The Message/Probe Line
 316
 317 The bottom line of the scout screen indicates how many times the B<scout>
 318 program has probed the File Server processes for statistics. The
 319 statistics gathered in the latest probe appear in the statistics display
 320 region. The B<-frequency> argument overrides the default probe frequency
 321 of 60 seconds.
 322
 323 =head1 EXAMPLES
 324
 325 See the chapter on monitoring tools in the I<OpenAFS Administration
 326 Guide>, which illustrates the displays that result from different
 327 combinations of options.
 328
 329 =head1 PRIVILEGE REQUIRED
 330
 331 None
 332
 333 =head1 SEE ALSO
 334
 335 L<afsmonitor(1)>,
 336 L<fstrace(8)>
 337
 338 =head1 COPYRIGHT
 339
 340 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
 341
 342 This documentation is covered by the IBM Public License Version 1.0.  It was
 343 converted from HTML to POD by software written by Chas Williams and Russ
 344 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.