Provided by: nfswatch_4.99.11-3build1_amd64 bug

NAME

       nfswatch - monitor an NFS server

SYNOPSIS

       nfswatch [ -dst dsthost ] [ -src srchost ] [ -server serverhost ] [ -all ] [ -dev device ]
       [ -allif ] [ -f filelist ] [ -lf logfile ] [ -sf snapfile ] [ -map mapfile ] [ -T  maxtime
       ]  [ -t timeout ] [ -fs ] [ -if ] [ -auth ] [ -procs ] [ -procs3 ] [ -clients ] [ -usage ]
       [ -l ] [ -bg ]

DESCRIPTION

       nfswatch monitors all incoming network traffic to an NFS file server and divides  it  into
       several  categories.   The  number  and percentage of packets received in each category is
       displayed on the screen in a continuously updated display.  The screen  is  updated  every
       ten seconds by default; this time period is called an interval.

       On  Irix:  You must be the super-user to invoke nfswatch or it must be installed setuid to
       ``root.''  On SunOS 4.x and SunOS 5.x (Solaris 2.x): You must be the super-user to  invoke
       nfswatch  or  it must be installed setuid to ``root.''  On System V Release 4: You must be
       the super-user to invoke nfswatch or it must be installed setuid to ``root.''   On  Ultrix
       or  DEC  OSF/1:  Any user can invoke nfswatch once the super-user has enabled promiscuous-
       mode operation using pfconfig(8).  (For example, "pfconfig +p +c -a".)  On Linux: You must
       be the super-user to invoke nfswatch or it must be installed setuid to ``root.''

       By  default,  nfswatch  monitors  all packets destined for the current host.  An alternate
       destination host to watch for may be specified using the -dst argument.  If a source  host
       is  specified  with  the -src argument, then only packets arriving at the destination host
       which were sent by the source host are monitored.  Traffic between a specific  server  and
       its clients may be watched by specifying the name of the server with the -server argument.
       If the -all argument is given, then all NFS traffic on the network is  monitored.   It  is
       usually desirable to specify the -all option whenever using the -server option.

       The  nfswatch  screen  is  divided  into  three  parts.  The first part, at the top of the
       screen, is made up of three lines.  The first line displays the name  of  the  host  being
       monitored,  the current date and time, and the time elapsed since the start of monitoring.
       The second line displays the total number of  packets  received  during  the  most  recent
       interval,  and  the  third  line  displays  the  total  number  of  packets received since
       monitoring started.  These two lines display three  numbers  each:  the  total  number  of
       packets  on  the  network,  the  total  number of packets received by the destination host
       (possibly subject to being only from the specified source host), and the number of packets
       dropped  by the monitoring interface due to buffer space limitations.  Dropped packets are
       not included in the packet monitoring totals.

       The second part of the screen divides the  received  packets  into  16  categories.   Each
       category  is  displayed  with three numbers: the number of packets received this interval,
       the percentage this represents of all packets received by the host during  this  interval,
       and  the total number of packets received since monitoring started.  The packet categories
       are not mutually exclusive; some packets may be counted in more  than  one  category  (for
       example,  NFS  packets  are  also  UDP packets).  The categories in this section and their
       meanings are:

       NFS3 Read
              NFS v3 requests which primarily result in a file system read being performed  (read
              file, read directory, etc.).

       NFS3 Write
              NFS  v3  requests  which  primarily  result  in a file system write being performed
              (write file, rename file, create file, delete file, etc.).

       NFS Read
              NFS requests which primarily result in a file system  read  being  performed  (read
              file, read directory, etc.).

       NFS Write
              NFS  requests  which primarily result in a file system write being performed (write
              file, rename file, create file, delete file, etc.).

       NFS Mount
              NFS mount requests.

       YP/NIS/NIS+
              Sun NIS (Yellow Pages) and NIS+ requests.

       RPC Authorization
              All RPC reply packets fall into this category, because RPC replies do  not  contain
              the  protocol number, and thus cannot be classified as anything else.  (If the -all
              argument is given, then you will see all the RPC replies on  the  network  in  this
              category.)

       Other RPC Packets
              All RPC requests which do not fall into one of the above categories.

       TCP Packets
              Packets sent using the Transmission Control Protocol.

       UDP Packets
              Packets sent using the User Datagram Protocol.

       ICMP Packets
              Packets sent using the Internet Control Message Protocol.

       Routing Control
              Routing Information Protocol (RIP) packets.

       Address Resolution
              Address Resolution Protocol (ARP) packets.  These packets are not counted on System
              V Release 4 systems (except for SunOS 5.x),  due  to  limitations  of  the  dlpi(7)
              interface.

       Reverse Addr Resol
              Reverse  Address Resolution Protocol (RARP) packets.  These packets are not counted
              on System V Release 4 systems (except for SunOS 5.x), due  to  limitations  of  the
              dlpi(7) interface.

       Ethernet/FDDI Bdcst
              Ethernet  (or FDDI) broadcast packets.  These packets are destined for and received
              by all hosts on the local network.  These packets  are  not  counted  on  System  V
              Release  4  systems  (except  for  SunOS  5.x),  due  to limitations of the dlpi(7)
              interface.

       Other Packets
              A catch-all for any packets not counted in any of the above categories.

       The third part of the display shows the mounted file systems exported by the  file  server
       for  mounting  through  NFS.   If nfswatch is monitoring the same host it is being run on,
       these file systems are listed by path name.  Otherwise, the program attempts to decode the
       server's  major  and  minor  device  numbers  for  the  file  system, and displays them in
       parentheses.  (If the -all argument is given, the name of the server is also shown.)  With
       each  file  system,  three numbers are displayed: the number of NFS requests for this file
       system received during the interval, the percentage this represents of  all  NFS  requests
       received  by  the host, and the total number of NFS requests for this file system received
       since monitoring started.  Up to 1024 file systems  will  be  monitored  by  nfswatch  and
       recorded  in  the  log  file,  but  only  as  many  as will fit (2 * (LINES - 16)) will be
       displayed on the screen.

       If the -map mapfile option is specified, nfswatch will read pairs of  file  system  device
       specifications (as described above) and the proper names of the file systems from mapfile.
       Each line should contain a string representing what nfswatch  would  normally  print,  and
       then separated from that by whitespace, the name that is preferred.  For example,

                                       myhost(7,24)     /homedirs

       If  the  -f filelist option is specified, a list of file names (one per line) is read from
       filelist, and the traffic to these individual files is also  monitored.   The  files  must
       reside  in  file  systems exported by the file server.  When this option is specified, the
       third section of the screen will display counters for these  files,  instead  of  for  the
       mounted  file  systems.   Up  to  1024  individual files will be monitored by nfswatch and
       recorded in the log file, but only as many as  will  fit  (2  *  (LINES  -  16))  will  be
       displayed on the screen.

       If the -procs or -procs3 option is specified, then instead of showing per-file or per-file
       system statistics, nfswatch shows the frequency of each NFS procedure (RPC  call)  (or  as
       many  as  will  fit  on  the screen).  For each procedure, some timing statistics are also
       displayed; these include the number of completed operations (request  and  response  seen)
       during  the interval, the average response time during the interval (in milliseconds), the
       standard deviation from the average during the interval, and  the  maximum  response  time
       over all time.

       If  the  -clients option is specified, then instead of showing per-file or per-file system
       statistics, nfswatch shows the  operation  rate  of  each  NFS  client  of  the  specified
       server(s) (or as many as will fit on the screen).

       It  should  be  noted here that only NFS requests, made by client machines, are counted in
       the NFS packet monitoring area.  The NFS traffic generated by the server  in  response  to
       these requests is not counted.

       If  the  -auth option is specified, then the display will show packet counts divided up by
       user name (or user id, if the login name  is  not  in  the  local  password  file).   This
       information  is  decoded  from  the  AUTH_UNIX  authentication  part  of  each RPC packet.
       nfswatch only decodes AUTH_UNIX authenticators, the other types of  authentication  (e.g.,
       AUTH_DES) are lumped into a single bucket for each authentication type.

LOGFILE

       When  logging  is  on,  nfswatch  writes  one  entry  to  the log file each interval.  The
       information printed to the log file is easily readable, and basically contains a  copy  of
       all  information  on  the  screen.   Additionally,  any  NFS  traffic  to  file systems or
       individual files which was not printed on the screen (due to space limitations) is printed
       in the log file.  Finally, in the log file, the NFS traffic to file systems and individual
       files is further broken down into counts of how many times each specific NFS procedure was
       called.

       The  information  in the nfswatch log file can be summarized easily using the nfslogsum(8)
       program.

COMMANDS

       nfswatch also allows several commands to be entered at its prompt during  execution.   The
       prompt  is  displayed  on  the  last  line  of  the  screen.   For most commands, feedback
       describing the effect of the command is printed on the  same  line  as  the  prompt.   The
       commands are:

       ^L     Clear and redraw the screen.

       a      Switches the display to show statistics on individual users.

       c      Switches  the display to show statistics on NFS client hosts instead of per-file or
              per-filesystem information.

       f      Toggle the display of mounted file systems and the display of individual  files  in
              the NFS packet monitoring area.  This command is only meaningful if the -f filelist
              option was specified  on  the  command  line.   (If  the  display  is  showing  NFS
              procedures  or  clients,  then  this  command  switches  the  display  to show file
              systems.)

       p      Switches the display to show statistics on NFS procedures instead  of  per-file  or
              per-filesystem information.

       P      Switches the display to show statistics on NFS v3 procedures instead of per-file or
              per-filesystem information.

       l      Toggle the logging feature.  If logging is off it is (re)started; if logging is on,
              it is turned off.

       n      Toggle  display  of  host names or host numbers in client mode.  By default, client
              mode displays host names.  However, this may not be sufficient for determining  the
              names  of unknown remote hosts, since domain names are not displayed.  This command
              tells nfswatch to display host numbers instead, enabling each host to  be  uniquely
              identified.

       s      Take a ``snapshot'' of the current screen and save it to a file.  This is useful to
              record occasional copies of the data when the logfile is not needed.

       u      Toggle the sort key for the display of mounted  file  systems  in  the  NFS  packet
              monitoring  area.   By  default, these are sorted by file system name, but they can
              also be sorted in declining order of percent usage.

       -      Decrease the cycle time (interval length) by ten seconds.  This  will  take  effect
              after the next screen update.

       +      Increase  the  cycle  time (interval length) by ten seconds.  This will take effect
              after the next screen update.

       <      Decrease the cycle time (interval length) by one second.   This  will  take  effect
              after the next screen update.

       >      Increase  the  cycle  time  (interval length) by one second.  This will take effect
              after the next screen update.

       ]      Scroll forward through the bottom part of the  display,  if  there  are  files/file
              systems/clients/procedures not being displayed due to lack of space.

       [      Scroll back.

       q      Exit nfswatch.  Using the interrupt key will also cause nfswatch to exit.

       Typing any other character will cause a help screen to be displayed.

OPTIONS

       nfswatch  can  usually  be run without arguments and will obtain useful results.  However,
       for those occasions when the defaults are not  good  enough,  the  following  options  are
       provided:

       -dst dsthost
              Monitor packets destined for dsthost instead of the local host.

       -src srchost
              Restrict packets being counted to those sent by srchost.

       -server serverhost
              Restrict packets being counted to those sent to or from serverhost.

       -all   Monitor packets to and from all NFS servers on the local network.

       -dev device
              On  non-DEC  systems: Use network interface device device to read packets from.  By
              default, nfswatch will use the system's default  network  device  for  an  Internet
              datagram.   On  Ultrix  or  DEC OSF/1: device specifies the packet filter interface
              from which to read packets.  You can specify  interfaces  either  by  their  actual
              names (such as ln0) or by their generic packet filter interface names (pfN, for N a
              small integer).  By default, pf0 (the first configured interface that supports  the
              packet filter) is used.

       -allif Read  packets  from  all configured network interfaces, instead of a single device.
              On Irix: The first five (0-4) of each of the following devices are checked: ec, et,
              fxp,  enp,  and  epg.   If configured, they will be monitored.  On SunOS: The first
              five le (0-4) devices, the first five ie (0-4) devices, and  the  first  five  fddi
              (0-4)  devices  are  checked,  and  if  configured, will be monitored.  On System V
              Release 4: The first five emd (0-4) devices are checked, and if configured, will be
              monitored.   On  Ultrix  and DEC OSF/1: The first ten pf devices (0-9) are checked,
              and if configured, will be monitored.

       -f filelist
              Read a list of file names (one per line) from filelist and monitor the NFS  traffic
              to these files in addition to the normal monitoring of exported file systems.

       -lf logfile
              When logging, write information to the file logfile.  The default is nfswatch.log.

       -sf snapfile
              Write snapshots to the file snapfile.  The default is nfswatch.snap.

       -map mapfile
              Read  a list of device names and file system names (one pair per line) from mapfile
              and translate from one to the other when displaying file system names.

       -T maxtime
              Terminate execution after running for maxtime seconds.  This is primarily  for  use
              with the -bg option.

       -t timeout
              Set  the  cycle time (interval length) to timeout seconds.  The default is 10.  The
              cycle time may also be adjusted from the command prompt.

       -fs    Display the file system NFS monitoring data instead of the  individual  file  data.
              This  option  is  only  meaningful  if  the  -f filelist option was specified.  The
              display may also be controlled from the command prompt.

       -if    Display the individual file NFS monitoring data instead of the  file  system  data.
              This  option  is  only  meaningful  if  the  -f filelist option was specified.  The
              display may also be controlled from the command prompt.

       -auth  Display statistics on authentication packets (individual users).

       -procs Display statistics on NFS procedures  (RPC  calls)  instead  of  per-file  or  per-
              filesystem data.

       -procs3
              Display  statistics  on  NFS  v3 procedures (RPC calls) instead of per-file or per-
              filesystem data.

       -client
              Display statistics on NFS client  operation  rates  instead  of  per-file  or  per-
              filesystem data.

       -usage Set  file  system,  procedure, or client display to be sorted in declining order of
              percent usage.  By default, the display is sorted alphabetically.  This may also be
              toggled from the command prompt.

       -l     Turn  logging  on  at  startup  time.  Logging is turned off by default, but may be
              enabled from the command prompt.

       -bg    Start as a daemon, running in the background.  No screen updates will be performed;
              all  data  will  be  written  to the log file only.  When started with this option,
              nfswatch will print the process id of the daemon process.  To  terminate  nfswatch,
              send  the  process  a  SIGTERM  signal,  or  use  the  -T option to set the maximum
              execution time.

BUGS

       To monitor NFS traffic to files and file systems, nfswatch must extract  information  from
       the  NFS  file  handle.   The file handle is a server-specific item, and its contents vary
       from vendor to vendor and operating system to operating system.  Unfortunately,  there  is
       no  server-independent way to extract information from a file handle.  nfswatch uses a set
       of heuristics to parse the file handle format used by many popular  NFS  servers,  but  in
       some cases there is no way to disambiguate the file handle format, and the program may get
       the wrong answer.  It should, however, get the right answer for file handles generated  by
       the host it is running on.

       nfswatch uses the Snoop (snoop(7)) network monitoring protocol under Irix 4.x, the Network
       Interface Tap (nit(4)) under SunOS 4.x, the Data Link Provider Interface  (dlpi(7))  under
       SunOS 5.x (Solaris 2.x) and System V Release 4, the Packet Filter {(packetfilter(4)) under
       Ultrix (4.0 or later); (packetfilter(7)) under DEC OSF/1 (V1.3 or later)}, and the  packet
       interface  (packet(7)) under Linux.  To run on other systems, code will have to be written
       to read packets from the network in promiscuous mode.

       On Ultrix systems, FDDI is only supported under appropriately patched versions  of  Ultrix
       4.2  (the  kernel modules net_common.o and pfilt.o must be replaced; contact your Customer
       Support Center).  Native FDDI support is standard in Ultrix 4.3 and later systems.

SEE ALSO

       etherfind(8c), dlpi(7),  nit(4),  nfslogsum(8),  packetfilter(4/7),  snoop(1m),  snoop(7),
       packet(7)

AUTHORS

       David A. Curry
       Purdue University
       Engineering Computer Network
       1285 Electrical Engineering Building
       West Lafayette, IN 47907-1285
       davy@ecn.purdue.edu

       Jeffrey C. Mogul
       Digital Equipment Corporation
       Western Research Laboratory
       250 University Avenue
       Palo Alto, CA 94301
       mogul@wrl.dec.com

       Christian Iseli
       Ludwig Institute for Cancer Research
       UNIL - BEP
       Lausanne, CH-1015
       Christian.Iseli@licr.org