scout                      AFS Commands                   scout


NAME

   scout -- monitor  File  Server  process on one or more file

                       server machines.


                                                 +
   scout -server <File Server name(s) to monitor> 
   [-basename <base server name>]
   [-frequency <poll frequency, in seconds>]  [-host]
                                                       +
   [-attention <specify attention (highlighting) level> ]
   [-debug <turn debugging on to the named file>]  [-help]

ACCEPTABLE ABBREVIATIONS/ALIASES

                                            +
   scout -s <File Server name(s) to monitor> 
   [-b <base server name>]
   [-f <poll frequency, in seconds>]  [-ho]
                                               +
   [-a <specify attention (highlighting) level> ]
   [-d <turn debugging on to the named file>]  [-he]

DESCRIPTION

   Displays statistics gathered from the  File  Server  process
   running  on each machine specified with -server.  The OUTPUT
   section explains the meaning of the statistics and describes
   how they appear on the screen.

REQUIREMENTS

   In addition to the scout binary, the machine must be able to
   access the "curses" graphics package, since scout's  display
   abilities  rely  on  it.    Most  UNIX distributions include
   curses as a standard utility.

   Both "dumb" terminals and  windowing  systems  that  emulate
   terminals can display scout's statistics.  The scout display
   makes use of reverse video and cursor addressing, so for the
   display  to  look  its  best, the display environment should
   support those features (most windowing systems do, most dumb
   terminals  do  not).    To  let  scout  know  what  type  of
   environment  is  being  used,  the  user  should   set   the
   environment  variable  TERM to the correct terminal type, or
   one with characteristics similar to the actual  ones.    For
   machines  running  AIX,  the recommended setting for TERM is
   vt100, as long as the terminal is  similar  to  that.    For
   other  operating  systems,  the  wider  range  of acceptable
   values includes xterm, xterms, vt100, vt200 and wyse85.



ARGUMENTS

   -server   names each File  Server  process  to  monitor,  by
             identifying  the file server machine it is running
             on.  Complete Internet-style host names are  best,
             unless  the  -basename  argument is used.  In that
             case, specify only the unique initial part of each
             machine name, omitting the domain/cell name suffix
             (or  "basename")  common   to   all   the   names.
             Shortened  unambiguous  names  are  legal when the
             -basename argument is not used, but in  that  case
             their  correct  resolution depends on the state of
             the cell's naming service at the time the  command
             is issued.

   -basename specifies  the  basename (domain/cell name) suffix
             common to all of the  file  server  machine  names
             specified   with  -server,  and  is  automatically
             appended to them.  This argument is  normally  the
             name of the cell to which the machines belong.  Do
             not include the period that separates this  suffix
             from  the  distinguishing part of each file server
             machine name, but  do  include  any  periods  that
             occur  within the suffix itself.  (For example, in
             the Transarc Corporation cell,  the  proper  value
             would be "transarc.com", not ".transarc.com".)

   -frequency
             indicates how often scout should  probe  the  File
             Server  processes.    Specify  a number of seconds
             greater than 0.  The default is 60 seconds.

   -host     causes the banner line to display the name of  the
             machine that is running scout.  The default is not
             to display the machine name in the banner.

   -attention
             defines  a  list  of  one or more entries, each of
             which pairs a type of statistic  and  a  threshold
             value.    When  the value of the statistic exceeds
             the indicated threshold  value,  scout  highlights
             the  value.    The  pairs may appear in any order.
             Legal values for the pairs are

            - conn <connections>.  Indicates  the  maximum
              number  of  connections that the File Server
              may have open to client machines before  the
              value  is  highlighted.    Highlighting goes
              away when the  value  goes  back  below  the
              threshold.  By default, no threshold is set.

              Example of a legal value: conn 300

            - fetch   <bytes   fetched>.    Indicates  the
              maximum number of bytes of data that clients
              can have fetched from the File Server before
              the value is highlighted.  Highlighting goes
              away  when  the  value  goes  back below the
              threshold, but this is possible only if  the
              File  Server is restarted, at which time the
              value  returns  to  0.    By   default,   no



              threshold is set.

              Example of a legal value: fetch 45000

            - store <bytes stored>.  Indicates the maximum
              number of bytes of  data  that  clients  can
              have  sent  to  the  File Server for storage
              before    the    value    is    highlighted.
              Highlighting  goes  away when the value goes
              back  below  the  threshold,  but  this   is
              possible   only   if   the  File  Server  is
              restarted, at which time the  value  returns
              to 0.  By default, no threshold is set.

              Example of a legal value: store 120000

            - ws   <number  of  active  client  machines>.
              Indicates the  maximum  number  of  "active"
              client  machines  the  File  Server  can  be
              serving before  the  value  is  highlighted.
              "Active"  machines are defined as those that
              have communicated with the  File  Server  in
              the last 15 minutes.  Highlighting goes away
              when  the  value   goes   back   below   the
              threshold.  By default, no threshold is set.

              Example of a legal value: ws 65

            - disk <percent full>%.  Indicates the maximum
              percentage of the  disk  that  can  be  full
              before  the  value  is  highlighted; in that
              case legal values are the integers between 0
              and 99.

              Examples  of legal values: disk 90% and disk
              72%.

              OR

              disk <minimum blocks free>.   Indicates  the
              minimum  number of kilobyte blocks that must
              be available on the partition if  the  value
              is not to be highlighted.

              Examples  of  legal  values:   disk 1500 and
              disk 5000.

              Specify one type  of  value  or  the  other.
              Highlighting  goes  away when the value goes
              back below the percent  threshold  or  above
              the  blocks-free threshold.  By default, the
              threshold is 95%.

   -debug    enables debugging output and directs it  into  the
             specified  file.  Providing a complete pathname is
             best; otherwise it is interpreted relative to  the
             current   working   directory.    By  default,  no
             debugging output is produced.

   -help     prints the online help for this command.   Do  not
             provide  any  other  arguments  or flags with this



             one.

OUTPUT

   Scout can display statistics either in a dedicated window or
   on  a  plain  screen  if  a  windowing  environment  is  not
   available.  For best results, the window  or  screen  should
   have the ability to print in reverse video.

   The  scout screen has three main parts: the banner line, the
   statistics display region and the message/probe line.

   The Banner Line

   The word "Scout" appears in the banner line at  the  top  of
   the  window  or  screen,  to indicate that scout is running.
   Additional information may appear in the banner line if  the
   system     administrator     includes     the    appropriate
   flags/arguments on the  command  line.    By  default,  this
   information does not appear.

      - The  name  of  the  machine  executing scout.  The
        -hostname  flag  causes  scout  to  display   this
        machine  name  in the banner line.  This is useful
        in cases where  the  administrator  wants  to  run
        scout  on several machines, but view the output on
        only one machine (to achieve this, he or she could
        open  several windows on a machine, then telnet to
        a different machine in each one in  order  to  run
        scout there).

        An  example:  if  a user runs scout on the machine
        client1.transarc.com and use the  -hostname  flag,
        the banner line will read


           [client1.transarc.com] Scout

      - The ``basename'' of the file server machines being
        monitored.  Scout identifies a File Server process
        by  the  name  of  the  file  server machine it is
        running on.  If all of  the  machine  names  in  a
        scout  window  end  in  the same string (share the
        same basename), then it is useful to  display  the
        basename in one place rather than on every machine
        name.  The  -basename  argument  causes  scout  to
        display the indicated basename on the banner line.
        The issuer then leaves the basename  off  of  each
        file server machine name provided, specifying only
        the distinguishing prefix rather than the complete
        machine name.

        An  example,  if  a  user  specifies  a  value  of
        transarc.com for -basename, the banner  line  will
        read


           Scout for transarc.com

   The Statistics Display Region

   In  this  region, which takes up the majority of the window,



   Scout displays the statistics gathered for each File  Server
   process.  Each process appears on its own line.

   The region is divided into six columns, labeled as indicated
   and displaying the following information:

      - Conn: number  of  connections  with  clients.  The
        first   column   displays   the   number   of  RPC
        connections open between the File  Server  process
        and  client machines.  This number should equal or
        exceed the number  in  the  Ws  column  (explained
        below).    It  can  exceed it because each process
        access  group  (PAG)  requires  a   separate   RPC
        connection,  and  one  client  machine  can handle
        several PAGs.    The  administrator  can  use  the
        -attention  argument to specify the value at which
        entries in the column should be highlighted.

      - Fetch: bytes fetched from File Server.  The second
        column  displays  the number of bytes of data that
        client machines have fetched from the File  Server
        process.    This number is reset to zero each time
        the   File   Server   process   restarts.      The
        administrator  can  use the -attention argument to
        specify the value at which entries in  the  column
        should be highlighted.

      - Store: bytes stored by the File Server.  The third
        column displays the number of bytes of  data  that
        client  machines  have  sent  to  the  File Server
        process for storage.  This number is reset to zero
        each  time  the File Server process restarts.  The
        administrator can use the -attention  argument  to
        specify  the  value at which entries in the column
        should be highlighted.

      - Ws: number  of  "active"  client  machines.    The
        fourth   column  displays  the  number  of  client
        machines  (workstations)  that  have  communicated
        with  the  File  Server process within the last 15
        minutes.  This number is likely to be smaller than
        the  number  in  the Conn column, because a single
        client machine can have several  connections  open
        to one File Server.  The administrator can use the
        -attention argument to specify the value at  which
        entries in the column should be highlighted.

      - File  server  machine name.  The fifth, unlabeled,
        column  displays  the  name  of  the  file  server
        machine  on  which  the  File  Server  process  is
        running.  If a name is too  long  to  fit  in  the
        field, it is truncated and an asterisk (*) appears
        as the last character in  the  name.    Using  the
        -basename   argument   is  a  good  way  to  avoid
        truncation, but only if all machine names end in a
        common  string.    Entries  in  this column become
        highlighted if the File Server  process  does  not
        respond to scout's probes.

      - Disk  attn: disk usage.  The sixth column displays
        how many kilobyte blocks are available on each AFS



        disk  partition  on  the file server machine.  The
        display for each partition has the form


           x:free_blocks

        where  x  indicates  the  partition  name.     For
        example,  a:8949  specifies that partition /vicepa
        has 8,949 free kilobyte  blocks.    The  available
        space  may  be  displayed for up to 10 partitions.
        If the window is not wide enough for  all  of  the
        partition  entries  to  appear  on  a single line,
        scout  automatically   creates   multiple   lines,
        "stacking"  the partition entries into sub-columns
        within the Disk attn column.

        The label on the Disk attn  column  indicates  the
        threshold  at  which  values  are highlighted.  By
        default, the label is


           Disk attn: > 95% used

        because by default scout highlights the entry  for
        any   partition  that  is  over  95%  full.    The
        administrator may use the -attention  argument  to
        change  this  default to either another percentage
        or a minimum number of free blocks.

   The Message/Probe Line

   The bottom line of the scout screen indicates how many times
   scout has "probed" the File Server processes for statistics.
   The columns in the Statistics Display region above this line
   display  the  result of the latest probe.  By default, scout
   probes  the  File  Servers  every  60   seconds,   but   the
   administrator  can  use the -frequency argument to specify a
   different number of seconds.

EXAMPLE

   See the chapter on scout in the AFS  System  Administrator's
   Guide,  which illustrates the on-screen displays that result
   from different combinations of switches and flags.

PRIVILEGE REQUIRED

   None.
