doc/man-pages/pod1/scout.pod

   1 =head1 NAME
   2
   3 scout - Monitors the File Server process
   4
   5 =head1 SYNOPSIS
   6
   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>>]
  12       [B<-help>]
  13
  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>]
  18
  19 =head1 DESCRIPTION
  20
  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.
  26
  27 =head1 CAUTIONS
  28
  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.
  32
  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
  43 C<wyse85>.
  44
  45 =head1 OPTIONS
  46
  47 =over 4
  48
  49 =item B<initcmd>
  50
  51 Accommodates the command's use of the AFS command parser, and is optional.
  52
  53 =item B<-server> <I<servers to monitor>>+
  54
  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.
  64
  65 =item B<-basename> <I<base server name>>
  66
  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>.
  75
  76 =item B<-frequency> <I<poll frequency>>
  77
  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.
  80
  81 =item B<-host>
  82
  83 Displays the name of the machine that is running the scout program, in the
  84 banner line of the display screen.
  85
  86 =item B<-attention> <I<attention level>>+
  87
  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:
  92
  93 =over 4
  94
  95 =item conn <I<connections>>
  96
  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.
 100
 101 An example of an acceptable value is conn 300.
 102
 103 =item disk <I<blocks_free>>
 104
 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.
 108
 109 An example of an acceptable value is disk 5000.
 110
 111 =item disk <I<percent_full>>%
 112
 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
 118 previously.
 119
 120 An example is disk 90%.
 121
 122 =item fetch <I<fetch RPCs>>
 123
 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.
 128
 129 Example of a legal value: fetch 6000000
 130
 131 =item store <I<store RPCs>>
 132
 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.
 137
 138 Example of an acceptable value: store 200000
 139
 140 =item ws <I<active client machines>>
 141
 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.
 147
 148 Example of an acceptable value: ws 65
 149
 150 =back
 151
 152 =item B<-debug> <I<debugging trace file>>
 153
 154 Specifies the pathname of the file into which to write a debugging
 155 trace. Partial pathnames are interpreted relative to the current working
 156 directory.
 157
 158 =item B<-help>
 159
 160 Prints the online help for this command. All other valid options are
 161 ignored.
 162
 163 =back
 164
 165 =head1 OUTPUT
 166
 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.
 170
 171 The B<scout> screen has three main parts: the banner line, the statistics
 172 display region and the message/probe line.
 173
 174 =head2 The Banner Line
 175
 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
 178 in the banner line:
 179
 180 =over 4
 181
 182 =item *
 183
 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
 187 single machine.
 188
 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
 191 follows:
 192
 193    [client1.abc.com] Scout
 194
 195 =item *
 196
 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:
 200
 201    Scout for abc.com
 202
 203 =back
 204
 205 =head2 The Statistics Display Region
 206
 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.
 210
 211 The region is divided into six columns, labeled as indicated and
 212 displaying the following information:
 213
 214 =over 4
 215
 216 =item Conn
 217
 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.
 223
 224 =item Fetch
 225
 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.
 230
 231 =item Store
 232
 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.
 237
 238 =item Ws
 239
 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
 245 Server.
 246
 247 =item server name
 248
 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.
 255
 256 =item Disk attn
 257
 258 The sixth column displays the number of available kilobyte blocks on each
 259 AFS disk partition on the file server machine.
 260
 261 The display for each partition has the following form:
 262
 263    x:<free_blocks>
 264
 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.
 271
 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
 274
 275    Disk attn: > 95% used
 276
 277 because by default the scout program highlights the entry for any
 278 partition that is over 95% full.
 279
 280 =back
 281
 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
 286 default.
 287
 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
 290 example:
 291
 292    Could not get information on server fs1.abc.com partition /vicepa
 293
 294 =head2 The Message/Probe Line
 295
 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
 300 of 60 seconds.
 301
 302 =head1 EXAMPLES
 303
 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.
 307
 308 =head1 PRIVILEGE REQUIRED
 309
 310 None
 311
 312 =head1 SEE ALSO
 313
 314 L<afsmonitor(1)>,
 315 L<fstrace(8)>
 316
 317 =head1 COPYRIGHT
 318
 319 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
 320
 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.