1 ETHERWATCH
 The  ETHERWATCH  Utility  is an Ethernet "sniffer" program that allows
 monitoring of network activity and can be used in  the  identification
 and diagnosis of network problems.

 It  is expected that you are familiar with the contents of the Chapter
 entitled "Local Area Network (LAN) Device Drivers" in the OpenVMS  I/O
 User's Reference Manual (referred to as IOURM in this manual).
2 UsageSummary
 ETHERWATCH  allows  you  to  monitor traffic based on Ethernet address
 (either source, destination or both), Protocol Type (Ethernet  Format)
 or  Protocol Identifier (IEEE 802 Extended Format), or any combination
 of these.  When selecting specific packets to be monitored, they  must
 match  ALL  of the items you specify in the command line for the match
 to be considered successful.  By default, any item  not  specified  in
 the  command  line  will  default in such a way that it will match any
 packet, therefore specifying items in the command line  will  restrict
 the number of packets that are successfully matched.

 ETHERWATCH  should  be  invoked  via  a foreign command i.e.  define a
 symbol (in this example ETHERWATCH) as follows:

 	$ ETHERWATCH == "$device:[directory]ETHERWATCH"

 Where "device" and "directory" identify the location of the image.

2 OtherSettings
 You should also define a logical ETHERWATCHER to point to the location
 of the file NODELIST.DAT (described  later).   Depending  on  how  the
 image  was built, you may also need to define the logical DBSSYSRTL as
 "device:[directory]DBSSYSRTL" where "device" and "directory"  are  the
 location of the Run-Time Library.

 In  order  to  run  ETHERWATCH  successfully,  you  will  need  PHY_IO
 privilege.

 To exit ETHERWATCH use Control/C.
2 HeaderFormats
 Complete  details  of packet header formats can be found in the IOURM.
 The following is supplied to show the positions of the  Protocol  Type
 fields and the DSAP, SSAP, Control and Protocol Identifier fields


             Ethernet Format:
             +-----------------------------------------+ 0
             |                                         |
             +---        6 byte Destination         ---+ 2
             |                 Address                 |
             +---                                   ---+ 4
             |                                         |
             +-----------------------------------------+ 6
             |                                         |
             +---          6 byte Source            ---+ 8
             |                 Address                 |
             +---                                   ---+ 10
             |                                         |
             +-----------------------------------------+ 12
             |          2 byte Protocol Type           |
             +-----------------------------------------+

             IEEE 802 Format:
             +-----------------------------------------+ 0
             |                                         |
             +---        6 byte Destination         ---+ 2
             |                 Address                 |
             +---                                   ---+ 4
             |                                         |
             +-----------------------------------------+ 6
             |                                         |
             +---          6 byte Source            ---+ 8
             |                 Address                 |
             +---                                   ---+ 10
             |                                         |
             +-----------------------------------------+ 12
             |       SSAP         |       DSAP         |
             +-----------------------------------------+ 14
             |        1 or 2 byte Control field        |
             +-----------------------------------------+

             802 Extended Format:
             +-----------------------------------------+ 0
             |                                         |
             +---        6 byte Destination         ---+ 2
             |                 Address                 |
             +---                                   ---+ 4
             |                                         |
             +-----------------------------------------+ 6
             |                                         |
             +---          6 byte Source            ---+ 8
             |                 Address                 |
             +---                                   ---+ 10
             |                                         |
             +-----------------------------------------+ 12
             |       SSAP         |       DSAP         |
             +-----------------------------------------+ 14
             |                    |  1 byte Control    |
             +---                 +--------------------+ 16
             |                                         |
             +---    5 byte Protocol Identifier     ---+ 18
             |                                         |
             +-----------------------------------------+

2 Addresses
 An  Ethernet  address  is  48 bits in length and is represented by the
 Ethernet Standard as six pairs  of  hexadecimal  digits  (six  bytes),
 separated   by   hyphens   (for   example,  08-00-2B-23-3E-01).   When
 specifying addresses to ETHERWATCH using the /FROM and /TO qualifiers,
 this  is  the format that is to be used.  It is also possible to use a
 "name" if it  is  defined  the  the  file  NODELIST.DAT  (see  section
 NodeList)  and  equates  to  a  valid  Ethernet  address in the format
 explained above. Standard VMS wildcard characters (% and *)  can  also
 be  used  to  specify addresses since comparisons are performed on the
 ASCII representations of the addresses and not the binary versions.

 Similarly,  the  values  required  by  /PROTOCOL,  /DSAP, /SSAP, /PID,
 /COPID  and  /IPID  should  be  specified  using  hexadecimal   digits
 (separated by hyphens where appropriate) or valid wildcard constructs.
 The size of each of these fields is detailed in  the  section  of  the
 manual  dealing  with  each  qualifier.   In  addition,  the /PROTOCOL
 qualifier can accept a number of pre-defined keywords (again  see  the
 relevant section).
2 NodeList
 When   starting   up,   ETHERWATCH   attempts   to   open   the   file
 ETHERWATCHER:NODELIST.DAT.  The logical ETHERWATCHER should be defined
 to point to the device and directory containing the file NODELIST.DAT.
3 Format
 The file itself can be created and maintained with your favourite
 editor and is simply a list of Ethernet addresses,  each  with  a
 descriptive  name  that  will  be  displayed in the packet header
 information when that address is detected in the packet header.  
 Each line of the file can be

 (i)   a blank line, which will be ignored

 (ii)  a comment, beginning with either an exclamation mark (!) or
       a semi-colon (;)

 (iii) an Ethernet address (with or without wildcards) followed by
       an equals sign (=) followed by a description (usually a node
       name).
3 NodeNames
 The "descriptions" (or names, as they are referred later) will be
 converted to uppercase and all spaces and tabs  will  be  removed
 when read from the file, therefore you may want to use underscore
 characters in place of spaces if desired.   Names  will  also  be
 truncated to 32 characters if necessary.
3 Limitations
 Prior  to  loading the addresses and names found in NODELIST.DAT,
 the file is read to determine how much memory is to be  allocated
 for  the  data and lookup tables.  A limit of 30,000 is placed on
 the number of address and name entries, which should be more than
 enough.   Although  no testing has been done with "large" numbers
 to see the impact on performance, it  seems  to  work  reasonably
 well with around 1,000 entries.
3 Example
 The   following  is  an  example  of  the  contents  of  a  valid
 NODELIST.DAT file.

       $ TYPE ETHERWATCHER:NODELIST.DAT

       ! The following are generic type addresses, multicast etc.
       09-00-02-04-00-01 = Bridge_Mgt
       09-00-02-04-00-02 = Vitalink_BrMgt
       09-00-2B-00-00-00 = ?MUMPS?
       09-00-2B-00-00-01 = ?DMS/DTP?
       09-00-2B-00-00-02 = ?VAXELN?
       09-00-2B-00-00-03 = LAN_TrafficMon
       09-00-2B-00-00-07 = NetBiosEmu
       09-00-2B-00-00-0F = LAT_Multicast
       09-00-2B-00-00-1* = ?DEC_Experimental?
       09-00-2B-01-00-00 = All_Bridges
       09-00-2B-01-00-01 = Local_Bridges
       09-00-2B-02-00-00 = DNA_L2_Routers
       09-00-2B-02-01-00 = DNS_Advert
       09-00-2B-02-01-01 = DNS_Solicit
       09-00-2B-02-01-02 = LAT_Solicit
       09-00-2B-02-01-09 = DECamds
       09-00-2B-03*      = ?Bridge_Filter?
       09-00-2B-04-00-00 = LAST
       09-00-2B-23-00-00 = Argonaut_Console
       09-00-7C-04-00-00 = Vitalink_?1
       09-00-7C-04-00-02 = Dls_multicast
       09-00-7C-06-10-00 = Vitalink_?2
       AB-00-00-01-00-00 = MOP_Dump/Load
       AB-00-00-02-00-00 = MOP_Remote_Console
       AB-00-00-03-00-00 = All_Routers
       AB-00-00-04-00-00 = All_End_Nodes
       AB-00-03-00-00-00 = LAT
       AB-00-04-00*      = CustomerUse
       AB-00-04-01*      = LAVAXcluster
       AB-00-04-02*      = *Reserved*
       CF-00-00-00-00-00 = LoopbackAssist
       FF-FF-FF-FF-FF-FF = Broadcast
       ! The following are specific addresses/name for this system
       AA-00-04-00-01-04 = PER1
       AA-00-04-00-02-04 = PER2
       00-00-1D-01-86-6D = PSRV07
       00-00-B5-00-06-2E = TSRV01
       08-00-2B-25-D5-E3 = PVCS01
       08-00-2B-3E-37-1E = PERVCS_E
       AA-00-04-00-61-04 = PERVCS
       08-00-2B-28-00-6E = INFOSERVER
       $
2 Qualifiers
 The available qualifiers allow selection of specific Ethernet packets. 
 For a packet to match the selection criteria, it must match ALL values
 specified.   By default, all selectable fields are matched.  Therefore
 supplying a value for any of these fields will  limit  the  number  of
 packets  that  are  displayed.   All  matching  of  fields  is done on
 character strings, thus allowing the  use  of  standard  VMS  wildcard
 constructs using the % and * wildcard characters.
3 UsageSummary
 The following list shows the qualifiers and default values.
                Qualifier                    Default

              /BEGIN=date_time               See description.
              /BOTH                          not /BOTH
              /CONTROL=match_string          *
              /COPID=match_string            *
              /COUNT=packet_count            See description.
              /DEVICE=device                 See description.
              /DISPLAY=format                ASCII
              /DSAP=match_string             *
              /END=date_time                 See description.
              /FROM=address                  *
              /IPID=match_string             *
              /NONAMES                       include names
              /OUTPUT[=filespec]             Output to SYS$OUTPUT.
              /PID=match_string              *
              /PLAYBACK[=filespec]           See description.
              /PROTOCOL=protocol             *
              /RECORD[=filespec]             See description.
              /SSAP=match_string             *
              /TO=address                    *

2 /BEGIN
   	/BEGIN=date_time

 Specifies when ETHERWATCH should start processing packets.

 The  /BEGIN  qualifier  can  be  used  to get ETHERWATCH to start
 processing  packets  at  a  predetermined   time.    By   default
 ETHERWATCH will start processing packets immediately.

2 /BOTH
         /BOTH

 Selects   bi-directional   matching  of  source  and  destination
 addresses.

 The  /BOTH  qualifier  overrides the default matching scheme when
 used with the /FROM and  /TO  qualifiers.   Normal  selection  of
 packets  is  performed by successfully matching the packet source
 address with the address in the /FROM qualifier, and  the  packet
 destination  address  with  the address in the /TO qualifier.  If
 /BOTH is specified,  then  a  mismatch  with  the  packet  source
 address  and the address in the /FROM qualifier will result in an
 attempt to match the packet source address with  the  address  in
 the  /TO  qualifier.   Similar  processing  is  performed with an
 initial mismatch  on  the  packet  destination  address  and  the
 address in the /TO qualifier.
3 Examples
   1.  /FROM=NODEA/BOTH
	 By  specifying  /BOTH,  packets  originating  from
	 NODEA and  packets  addressed  to  NODEA  will  be
	 chosen  and  displayed,  regardless  of  the other
	 nodes  involved.   Without  /BOTH,  only   packets
	 originating at NODEA would be selected.

   2.  /FROM=NODEA/TO=NODEB
	 This  will result in only packets originating from
	 NODEA  addressed  to  NODEB   being   chosen   and
	 displayed.

   3.  /FROM=NODEA/TO=NODEB/BOTH
	 By  specifying  /BOTH,  packets  originating  from
	 NODEA addressed to NODEB and  packets  originating
	 from  NODEB  addressed to NODEA will be chosen and
	 displayed.
2 /CONTROL
         /CONTROL=control_code

 Allows selection of packets based on the control byte field.

 The  /CONTROL  qualifier allows selection of packets based on the
 contents of the Control byte field in the Ethernet packet header.
 It   is  a  single  byte  value  and  should  be  specified  as a
 hexadecimal byte value or a valid wildcard construct.

2 /COPID
         /COPID=company_id

 Allows  selection  of  packets  based  on  the  Company  Protocol
 Identifier (COPID) field.

 The  /COPID  qualifier  allows  selection of packets based on the
 contents of the Company Protocol Identifier field in the Ethernet
 packet  header.   This  is  a  sub-field  of  the User's Protocol
 Identifier field and should be  specified  as  three  hexadecimal
 byte  values  separated by hyphens (XX-XX-XX) or a valid wildcard
 construct.

2 /COUNT
         /COUNT=packet_count

 Tells ETHERWATCH to stop processing after the specified number of
 packets.

 The  /COUNT qualifier specifies the number of packets that should
 be processed by ETHERWATCH before  terminating.   This  qualifier
 cannot  be  used  with the /END qualifier and if neither is used,
 processing will terminate after 30 minutes.

 Specifying  a  value of zero will result in processing continuing
 until interrupted by a Control/C.

2 /DEVICE
         /DEVICE=device

 The /DEVICE qualifier is used to select which Ethernet controller
 is to be monitored.

 If /DEVICE is not specified, then the first Ethernet device found
 on the system is used.  If no devices are found or the  specified
 device  is  invalid,  no  processing  is performed and ETHERWATCH
 terminates with an error.

2 /DISPLAY
         /DISPLAY=option

 Allows selection of the display format of the packet contents.

 The /DISPLAY qualifier is used to change the format of the packet
 data when it is displayed.  By default, the data is displayed  in
 ASCII format.
3 Option
 ALL     specifies  that  packet  data is to be displayed in ASCII
	 and hexadecimal format.

 ASCII   specifies  that  packet  data is to be displayed in ASCII
	 format only.  This is the default value.

 BOTH 	 is the same as ALL.

 FAST    will  result  in the packet data being displayed in ASCII
	 (using the !AF directive of the $FAO system service) with
	 no byte counters.

 HEXADECIMAL  
	 specifies  that  the  packet  data  is to be displayed in
	 hexadecimal byte format.

 NONE    will  result  in  no packet data being displayed.  Packet
	 headers will still be displayed.

 TEXT    is the same as ASCII.
3 Examples
   1.  /DISPLAY=NONE
	 Will  result in no packet data being displayed but
	 will still allow  display  of  the  packet  header
	 information   i.e.   the  source  and  destination
	 Ethernet addresses, along with the node  names  if
	 defined   in   the  nodelist  file,  the  protocol
	 information, the data buffer size and a  date  and
	 time stamp.

   2.  /DISPLAY=ALL
	 Will  result  in  packet  data  being displayed in
	 ASCII and hexadecimal byte format. 

2 /DSAP
         /DSAP=destination_sap

 Allows  selection  of  packets  based  on the Destination Service
 Access Point (DSAP) field.

 The  /DSAP  qualifier  allows  selection  of packets based on the
 contents of the Destination Service Access  Point  field  in  the
 Ethernet  packet header.  It is a single byte value and should be
 specified as  a  hexadecimal  byte  value  or  a  valid  wildcard
 construct.   This  field  also  maps  over  the first byte of the
 Ethernet Protocol Type field.

2 /END
         /END=date_time

 Specifies when ETHERWATCH should stop processing packets.

 The  /END  qualifier  can  be  used  to  get  ETHERWATCH  to stop
 processing  packets  at  a  predetermined   time.    By   default
 ETHERWATCH  will  stop processing packets after 30 minutes unless
 overridden by the /COUNT qualifier.  The /END qualifier cannot be
 used with the /COUNT qualifier

2 /FROM
         /FROM=address

 Allows selection of packets based on the packet source address.

 UNKNOWN  can  be  used as the address to match and will result in
 the display of all packets received from nodes that do not  exist
 in the NODELIST.DAT file.

 The  /FROM  qualifier  allows  selection  of packets based on the
 contents of the Source  Address  field  in  the  Ethernet  packet
 header.   It  can  be  specified  as  six hexadecimal byte values
 separated by hyphens (XX-XX-XX-XX-XX-XX) or a name  matching  one
 of  the entries in NODELIST.DAT or any valid wildcard string or a
 valid DECnet node address in the form area.node.
3 Examples

   1.  /FROM=NODEA
	 If NODEA is listed in NODELIST.DAT then ETHERWATCH
	 will use the  corresponding  Ethernet  address  to
	 match the packet source address.

   2.  /FROM=AA-00-04-00-01-04
	 This  will  result in packets originating from the
	 specified address being matched.

   3.  /FROM=1.4
	 The "1.4" will be translated into a DECnet AA type
	 address and this will be used to match the  packet
	 source address.

   4.  /FROM=AA-00-04*
	 This will result in a match on any DECnet Phase IV
	 station address as the packet source address being
	 matched.

   5.  /FROM=UNKNOWN
	 This  will  result  in the selection of any packet
	 whose   source   address   is   not   listed    in
	 NODELIST.DAT.

2 /IPID
         /IPID=internal_pid

 Allows  selection of packets based on the Implementation Specific
 Protocol Identifier (IPID) field.

 The  /IPID  qualifier  allows  selection  of packets based on the
 contents of the Implementation Specific Protocol Identifier field
 in the Ethernet packet header.  This is a sub-field of the User's
 Protocol  Identifier  field  and  should  be  specified  as   two
 hexadecimal  byte values separated by a hyphen (XX-XX) or a valid
 wildcard construct.

2 /NONAMES
         /NONAMES

 Suppresses   matching  of  Ethernet  addresses  with  names  when
 displaying packet header information.

 The  /NONAMES  qualifier  will  prevent ETHERWATCH from trying to
 match Ethernet addresses with names from the nodelist  file  when
 it  is  processing  the  packet  header.   This results in faster
 processing and is useful when dealing with  traffic  between  two
 known addreses.

 Although this qualifier will prevent searching the node name list
 when displaying packet headers, the nodelist file will  still  be
 read when ETHERWATCH starts and you will still be able to specify
 names on the /FROM and /TO qualifiers.

2 /OUTPUT
         /OUTPUT[=filespec]

 Allows output to be directed to a file.

 The  /OUTPUT  qualifier  allows  the output to be directed to the
 specified  file.   If  no  filename  is  given,  the  default  is
 ETHERWATCH.LOG in the current directory.

 If  a file by the same name exists, the output is appended to the
 existing file otherwise a new file is created.

2 /PID
         /PID=protoocl_id

 Allows   selection  of  packets  based  on  the  User's  Protocol
 Identifier (PID) field.

 The  /PID  qualifier  allows  selection  of  packets based on the
 contents of the User's Protocol Identifier field in the  Ethernet
 packet header.  This should be specified as five hexadecimal byte
 values separated by hyphens (XX-XX-XX-XX-XX) or a valid  wildcard
 construct.

2 /PLAYBACK
         /PLAYBACK[=filespec]

 Allows  processing  of  data  that has been previously recorded. 
 field.

 The  /PLAYBACK  qualifier  allows  previously  recorded  ethernet
 packet data to  be  processed.   The  default  filename  for  the
 recorded  data  is  ETHERWATCH.RECORD.   This qualifier cannot be
 used with the /RECORD, /BEGIN or /END qualifiers.

2 /PROTOCOL
         /PROTOCOL=protocol

 Allows  selection  of packets based on the Ethernet Protocol Type
 field.

 The  /PROTOCOL qualifier allows selection of packets based on the
 contents of the Ethernet Protocol  Type  field  in  the  Ethernet
 packet  header.   The  value  specified  can either be one of the
 keywords above or can be specified as two hexadecimal byte values
 separated  by a hyphen (XX-XX) or a valid wildcard construct. Any
 other value given in  the  command  line  will  be  used  as  the
 protocol to match against.
3 Protocols
 The  following  list  shows  currently available keywords and the
 associated protocol.

             Protocol                Keyword
	  -----------------------------------------------
              60-01                  MOPDUMP
              60-02                  MOPCONSOLE
              60-03                  DECNET
              60-04                  LAT
              60-05                  DIAGNOSTICS
              60-07                  LAVC
              80-38                  RBMS
              80-3B                  VAXELN
              80-3E                  DNS
              80-40                  NETBIOS
              80-41                  LAST

         (Others may be added to the list in later releases.)
3 Examples
   1.  /PROTOCOL=DECNET
	 This  will result in only DECnet protocol messages
	 (60-03)  being  matched.   Using   /PROTOCOL=60-03
	 would achieve the same result.

   2.  /PROTOCOL=80-41
	 This  will  result  in  packets with the specified
	 protocol type being matched.

   3.  /PROTOCOL=60*
	 This   will   result  in  packets  with  protocols
	 beginning with 60 being matched.

2 /RECORD
         /RECORD[=filespec]

 Allows  recording  of  data  so  that it can be processed later. 
 field.

 The  /RECORD  qualifier  allows  ethernet  data to be recorded in
 binary format for later processing via the  /PLAYBACK  qualifier.
 The default filename for the recorded data is ETHERWATCH.RECORD.

2 /SSAP
         /SSAP=source_sap

 Allows  selection  of  packets based on the Source Service Access
 Point (SSAP) field.

 The  /SSAP  qualifier  allows  selection  of packets based on the
 contents of the Source Service Access Point field in the Ethernet
 packet header.  It is a single byte value and should be specified
 as a hexadecimal byte value or a valid wildcard construct.   This
 field  also  maps  over  the second byte of the Ethernet Protocol
 Type field.

2 /TO
         /TO=address

 Allows  selection  of  packets  based  on  the packet destination
 address.

 UNKNOWN  can  be  used as the address to match and will result in
 the display of all packets addressed to nodes that do  not  exist
 in the NODELIST.DAT file.

 The  /TO  qualifier  allows  selection  of  packets  based on the
 contents of the Destination Address field in the Ethernet  packet
 header.   It can be specified as six two hexadecimal digit values
 separated by hyphens (XX-XX-XX-XX-XX-XX) or a name  matching  one
 of  the entries in NODELIST.DAT or any valid wildcard string or a
 valid DECnet node address in the form area.node.
3 Examples
   1.  /TO=NODEA
	 If NODEA is listed in NODELIST.DAT then ETHERWATCH
	 will use the  corresponding  Ethernet  address  to
	 match the packet destination address.

   2.  /TO=AA-00-04-00-01-04
	 This  will  result  in  packets  destined  for the
	 specified address being matched.

   3.  /TO=1.4
	 The "1.4" will be translated into a DECnet AA type
	 address and this will be used to match the  packet
	 destination address.

   4.  /TO=AA-00-04*
	 This will result in a match on any DECnet Phase IV
	 station address as the  packet  destination  being
	 matched.

   5.  /TO=UNKNOWN
	 This  will  result  in the selection of any packet
	 whose  destination  address  is  not   listed   in
	 NODELIST.DAT.

2 Author
 David B Sneddon   (dbs)                          
 VMS Systems Programmer       
 On-Line Computing, Subiaco
 Western Australia       

 E-mail: sneddo@perth.dialix.oz.au

 Phone +61 9 381 3000
 Fax +61 9 388 1746

