doc/xml/AdminReference/sect1/scout.xml

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