1 ETHERWATCHG The  ETHERWATCH  Utility  is an Ethernet "sniffer" program that allowsG monitoring of network activity and can be used in  the  identification# and diagnosis of network problems.G It  is expected that you are familiar with the contents of the ChapterG entitled "Local Area Network (LAN) Device Drivers" in the OpenVMS  I/O? User's Reference Manual (referred to as IOURM in this manual).2 UsageSummaryG ETHERWATCH  allows  you  to  monitor traffic based on Ethernet addressG (either source, destination or both), Protocol Type (Ethernet  Format)G or  Protocol Identifier (IEEE 802 Extended Format), or any combinationG of these.  When selecting specific packets to be monitored, they  mustG match  ALL  of the items you specify in the command line for the matchG to be considered successful.  By default, any item  not  specified  inG the  command  line  will  default in such a way that it will match anyG packet, therefore specifying items in the command line  will  restrict5 the number of packets that are successfully matched.G ETHERWATCH  should  be  invoked  via  a foreign command i.e.  define a0 symbol (in this example ETHERWATCH) as follows:1 	$ ETHERWATCH == "$device:[directory]ETHERWATCH"C Where "device" and "directory" identify the location of the image.2 OtherSettingsG You should also define a logical ETHERWATCHER to point to the locationG of the file NODELIST.DAT (described  later).   Depending  on  how  theG image  was built, you may also need to define the logical DBSSYSRTL asG "device:[directory]DBSSYSRTL" where "device" and "directory"  are  the" location of the Run-Time Library.G In  order  to  run  ETHERWATCH  successfully,  you  will  need  PHY_IO privilege." To exit ETHERWATCH use Control/C.2 HeaderFormatsG Complete  details  of packet header formats can be found in the IOURM.G The following is supplied to show the positions of the  Protocol  TypeB fields and the DSAP, SSAP, Control and Protocol Identifier fields             Ethernet Format::             +-----------------------------------------+ 08             |                                         |:             +---        6 byte Destination         ---+ 28             |                 Address                 |:             +---                                   ---+ 48             |                                         |:             +-----------------------------------------+ 68             |                                         |:             +---          6 byte Source            ---+ 88             |                 Address                 |;             +---                                   ---+ 108             |                                         |;             +-----------------------------------------+ 128             |          2 byte Protocol Type           |8             +-----------------------------------------+             IEEE 802 Format::             +-----------------------------------------+ 08             |                                         |:             +---        6 byte Destination         ---+ 28             |                 Address                 |:             +---                                   ---+ 48             |                                         |:             +-----------------------------------------+ 68             |                                         |:             +---          6 byte Source            ---+ 88             |                 Address                 |;             +---                                   ---+ 108             |                                         |;             +-----------------------------------------+ 128             |       SSAP         |       DSAP         |;             +-----------------------------------------+ 148             |        1 or 2 byte Control field        |8             +-----------------------------------------+!             802 Extended Format::             +-----------------------------------------+ 08             |                                         |:             +---        6 byte Destination         ---+ 28             |                 Address                 |:             +---                                   ---+ 48             |                                         |:             +-----------------------------------------+ 68             |                                         |:             +---          6 byte Source            ---+ 88             |                 Address                 |;             +---                                   ---+ 108             |                                         |;             +-----------------------------------------+ 128             |       SSAP         |       DSAP         |;             +-----------------------------------------+ 148             |                    |  1 byte Control    |;             +---                 +--------------------+ 168             |                                         |;             +---    5 byte Protocol Identifier     ---+ 188             |                                         |8             +-----------------------------------------+2 AddressesG An  Ethernet  address  is  48 bits in length and is represented by theG Ethernet Standard as six pairs  of  hexadecimal  digits  (six  bytes),G separated   by   hyphens   (for   example,  08-00-2B-23-3E-01).   WhenG specifying addresses to ETHERWATCH using the /FROM and /TO qualifiers,G this  is  the format that is to be used.  It is also possible to use aG "name" if it  is  defined  the  the  file  NODELIST.DAT  (see  sectionG NodeList)  and  equates  to  a  valid  Ethernet  address in the formatG explained above. Standard VMS wildcard characters (% and *)  can  alsoG be  used  to  specify addresses since comparisons are performed on theD ASCII representations of the addresses and not the binary versions.G Similarly,  the  values  required  by  /PROTOCOL,  /DSAP, /SSAP, /PID,G /COPID  and  /IPID  should  be  specified  using  hexadecimal   digitsG (separated by hyphens where appropriate) or valid wildcard constructs.G The size of each of these fields is detailed in  the  section  of  theG manual  dealing  with  each  qualifier.   In  addition,  the /PROTOCOLG qualifier can accept a number of pre-defined keywords (again  see  the relevant section).
2 NodeListG When   starting   up,   ETHERWATCH   attempts   to   open   the   fileG ETHERWATCHER:NODELIST.DAT.  The logical ETHERWATCHER should be definedG to point to the device and directory containing the file NODELIST.DAT.3 FormatB The file itself can be created and maintained with your favouriteB editor and is simply a list of Ethernet addresses,  each  with  aB descriptive  name  that  will  be  displayed in the packet headerB information when that address is detected in the packet header.   Each line of the file can be* (i)   a blank line, which will be ignoredB (ii)  a comment, beginning with either an exclamation mark (!) or       a semi-colon (;)B (iii) an Ethernet address (with or without wildcards) followed byC       an equals sign (=) followed by a description (usually a node
       name).3 NodeNamesB The "descriptions" (or names, as they are referred later) will beB converted to uppercase and all spaces and tabs  will  be  removedB when read from the file, therefore you may want to use underscoreB characters in place of spaces if desired.   Names  will  also  be) truncated to 32 characters if necessary.
3 LimitationsB Prior  to  loading the addresses and names found in NODELIST.DAT,B the file is read to determine how much memory is to be  allocatedB for  the  data and lookup tables.  A limit of 30,000 is placed onB the number of address and name entries, which should be more thanB enough.   Although  no testing has been done with "large" numbersB to see the impact on performance, it  seems  to  work  reasonably  well with around 1,000 entries.	3 ExampleB The   following  is  an  example  of  the  contents  of  a  valid NODELIST.DAT file.'       $ TYPE ETHERWATCHER:NODELIST.DATA       ! 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 = BroadcastB       ! 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 QualifiersH The available qualifiers allow selection of specific Ethernet packets. G For a packet to match the selection criteria, it must match ALL valuesG specified.   By default, all selectable fields are matched.  ThereforeG supplying a value for any of these fields will  limit  the  number  ofG packets  that  are  displayed.   All  matching  of  fields  is done onG character strings, thus allowing the  use  of  standard  VMS  wildcard2 constructs using the % and * wildcard characters.3 UsageSummary< The following list shows the qualifiers and default values.4                Qualifier                    Default=              /BEGIN=date_time               See description.6              /BOTH                          not /BOTH.              /CONTROL=match_string          *.              /COPID=match_string            *=              /COUNT=packet_count            See description.=              /DEVICE=device                 See description.2              /DISPLAY=format                ASCII.              /DSAP=match_string             *=              /END=date_time                 See description..              /FROM=address                  *.              /IPID=match_string             *:              /NONAMES                       include namesB              /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.B The  /BEGIN  qualifier  can  be  used  to get ETHERWATCH to startB processing  packets  at  a  predetermined   time.    By   default6 ETHERWATCH will start processing packets immediately.2 /BOTH         /BOTHB Selects   bi-directional   matching  of  source  and  destination addresses.B The  /BOTH  qualifier  overrides the default matching scheme whenB used with the /FROM and  /TO  qualifiers.   Normal  selection  ofB packets  is  performed by successfully matching the packet sourceB address with the address in the /FROM qualifier, and  the  packetB destination  address  with  the address in the /TO qualifier.  IfB /BOTH is specified,  then  a  mismatch  with  the  packet  sourceB address  and the address in the /FROM qualifier will result in anB attempt to match the packet source address with  the  address  inB the  /TO  qualifier.   Similar  processing  is  performed with anB initial mismatch  on  the  packet  destination  address  and  the address in the /TO qualifier.
3 Examples   1.  /FROM=NODEA/BOTH4	 By  specifying  /BOTH,  packets  originating  from4	 NODEA and  packets  addressed  to  NODEA  will  be4	 chosen  and  displayed,  regardless  of  the other4	 nodes  involved.   Without  /BOTH,  only   packets)	 originating at NODEA would be selected.   2.  /FROM=NODEA/TO=NODEB4	 This  will result in only packets originating from4	 NODEA  addressed  to  NODEB   being   chosen   and	 displayed.    3.  /FROM=NODEA/TO=NODEB/BOTH4	 By  specifying  /BOTH,  packets  originating  from4	 NODEA addressed to NODEB and  packets  originating4	 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.B The  /CONTROL  qualifier allows selection of packets based on theB contents of the Control byte field in the Ethernet packet header.B It   is  a  single  byte  value  and  should  be  specified  as a6 hexadecimal byte value or a valid wildcard construct.2 /COPID         /COPID=company_idB Allows  selection  of  packets  based  on  the  Company  Protocol Identifier (COPID) field.B The  /COPID  qualifier  allows  selection of packets based on theB contents of the Company Protocol Identifier field in the EthernetB packet  header.   This  is  a  sub-field  of  the User's ProtocolB Identifier field and should be  specified  as  three  hexadecimalB byte  values  separated by hyphens (XX-XX-XX) or a valid wildcard construct.2 /COUNT         /COUNT=packet_countB Tells ETHERWATCH to stop processing after the specified number of	 packets.B The  /COUNT qualifier specifies the number of packets that shouldB be processed by ETHERWATCH before  terminating.   This  qualifierB cannot  be  used  with the /END qualifier and if neither is used,, processing will terminate after 30 minutes.B Specifying  a  value of zero will result in processing continuing" until interrupted by a Control/C.	2 /DEVICE         /DEVICE=deviceB The /DEVICE qualifier is used to select which Ethernet controller is to be monitored.B If /DEVICE is not specified, then the first Ethernet device foundB on the system is used.  If no devices are found or the  specifiedB 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.B The /DISPLAY qualifier is used to change the format of the packetB data when it is displayed.  By default, the data is displayed  in ASCII format.3 OptionB ALL     specifies  that  packet  data is to be displayed in ASCII	 and hexadecimal format.B ASCII   specifies  that  packet  data is to be displayed in ASCII*	 format only.  This is the default value. BOTH 	 is the same as ALL.B 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.B 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=NONE4	 Will  result in no packet data being displayed but4	 will still allow  display  of  the  packet  header4	 information   i.e.   the  source  and  destination4	 Ethernet addresses, along with the node  names  if4	 defined   in   the  nodelist  file,  the  protocol4	 information, the data buffer size and a  date  and
	 time stamp.   2.  /DISPLAY=ALL4	 Will  result  in  packet  data  being displayed in%	 ASCII and hexadecimal byte format. 2 /DSAP         /DSAP=destination_sapB Allows  selection  of  packets  based  on the Destination Service Access Point (DSAP) field.B The  /DSAP  qualifier  allows  selection  of packets based on theB contents of the Destination Service Access  Point  field  in  theB Ethernet  packet header.  It is a single byte value and should beB specified as  a  hexadecimal  byte  value  or  a  valid  wildcardB 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.B The  /END  qualifier  can  be  used  to  get  ETHERWATCH  to stopB processing  packets  at  a  predetermined   time.    By   defaultB ETHERWATCH  will  stop processing packets after 30 minutes unlessB overridden by the /COUNT qualifier.  The /END qualifier cannot be used with the /COUNT qualifier2 /FROM         /FROM=address@ Allows selection of packets based on the packet source address.B UNKNOWN  can  be  used as the address to match and will result inB the display of all packets received from nodes that do not  exist in the NODELIST.DAT file.B The  /FROM  qualifier  allows  selection  of packets based on theB contents of the Source  Address  field  in  the  Ethernet  packetB header.   It  can  be  specified  as  six hexadecimal byte valuesB separated by hyphens (XX-XX-XX-XX-XX-XX) or a name  matching  oneB of  the entries in NODELIST.DAT or any valid wildcard string or a1 valid DECnet node address in the form area.node.
3 Examples   1.  /FROM=NODEA4	 If NODEA is listed in NODELIST.DAT then ETHERWATCH4	 will use the  corresponding  Ethernet  address  to"	 match the packet source address.   2.  /FROM=AA-00-04-00-01-044	 This  will  result in packets originating from the"	 specified address being matched.   3.  /FROM=1.44	 The "1.4" will be translated into a DECnet AA type4	 address and this will be used to match the  packet	 source address.   4.  /FROM=AA-00-04*4	 This will result in a match on any DECnet Phase IV4	 station address as the packet source address being
	 matched.   5.  /FROM=UNKNOWN4	 This  will  result  in the selection of any packet4	 whose   source   address   is   not   listed    in	 NODELIST.DAT.2 /IPID         /IPID=internal_pidB Allows  selection of packets based on the Implementation Specific" Protocol Identifier (IPID) field.B The  /IPID  qualifier  allows  selection  of packets based on theB contents of the Implementation Specific Protocol Identifier fieldB in the Ethernet packet header.  This is a sub-field of the User'sB Protocol  Identifier  field  and  should  be  specified  as   twoB hexadecimal  byte values separated by a hyphen (XX-XX) or a valid wildcard construct.
2 /NONAMES         /NONAMESB Suppresses   matching  of  Ethernet  addresses  with  names  when& displaying packet header information.B The  /NONAMES  qualifier  will  prevent ETHERWATCH from trying toB match Ethernet addresses with names from the nodelist  file  whenB it  is  processing  the  packet  header.   This results in fasterB processing and is useful when dealing with  traffic  between  two known addreses.B Although this qualifier will prevent searching the node name listB when displaying packet headers, the nodelist file will  still  beB 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.B The  /OUTPUT  qualifier  allows  the output to be directed to theB specified  file.   If  no  filename  is  given,  the  default  is) ETHERWATCH.LOG in the current directory.B 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_idB Allows   selection  of  packets  based  on  the  User's  Protocol Identifier (PID) field.B The  /PID  qualifier  allows  selection  of  packets based on theB contents of the User's Protocol Identifier field in the  EthernetB packet header.  This should be specified as five hexadecimal byteB values separated by hyphens (XX-XX-XX-XX-XX) or a valid  wildcard construct.2 /PLAYBACK         /PLAYBACK[=filespec]B Allows  processing  of  data  that has been previously recorded.  field.B The  /PLAYBACK  qualifier  allows  previously  recorded  ethernetB packet data to  be  processed.   The  default  filename  for  theB recorded  data  is  ETHERWATCH.RECORD.   This qualifier cannot be2 used with the /RECORD, /BEGIN or /END qualifiers.2 /PROTOCOL         /PROTOCOL=protocolB Allows  selection  of packets based on the Ethernet Protocol Type field.B The  /PROTOCOL qualifier allows selection of packets based on theB contents of the Ethernet Protocol  Type  field  in  the  EthernetB packet  header.   The  value  specified  can either be one of theB keywords above or can be specified as two hexadecimal byte valuesB separated  by a hyphen (XX-XX) or a valid wildcard construct. AnyB other value given in  the  command  line  will  be  used  as  the protocol to match against.3 ProtocolsB The  following  list  shows  currently available keywords and the associated protocol.,             Protocol                Keyword2	  -----------------------------------------------,              60-01                  MOPDUMP/              60-02                  MOPCONSOLE+              60-03                  DECNET(              60-04                  LAT0              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=DECNET4	 This  will result in only DECnet protocol messages4	 (60-03)  being  matched.   Using   /PROTOCOL=60-03 	 would achieve the same result.   2.  /PROTOCOL=80-414	 This  will  result  in  packets with the specified	 protocol type being matched.   3.  /PROTOCOL=60*4	 This   will   result  in  packets  with  protocols"	 beginning with 60 being matched.	2 /RECORD         /RECORD[=filespec]B Allows  recording  of  data  so  that it can be processed later.  field.B The  /RECORD  qualifier  allows  ethernet  data to be recorded inB binary format for later processing via the  /PLAYBACK  qualifier.A The default filename for the recorded data is ETHERWATCH.RECORD.2 /SSAP         /SSAP=source_sapB Allows  selection  of  packets based on the Source Service Access Point (SSAP) field.B The  /SSAP  qualifier  allows  selection  of packets based on theB contents of the Source Service Access Point field in the EthernetB packet header.  It is a single byte value and should be specifiedB as a hexadecimal byte value or a valid wildcard construct.   ThisB field  also  maps  over  the second byte of the Ethernet Protocol Type field.2 /TO         /TO=addressB Allows  selection  of  packets  based  on  the packet destination	 address.B UNKNOWN  can  be  used as the address to match and will result inB the display of all packets addressed to nodes that do  not  exist in the NODELIST.DAT file.B The  /TO  qualifier  allows  selection  of  packets  based on theB contents of the Destination Address field in the Ethernet  packetB header.   It can be specified as six two hexadecimal digit valuesB separated by hyphens (XX-XX-XX-XX-XX-XX) or a name  matching  oneB of  the entries in NODELIST.DAT or any valid wildcard string or a1 valid DECnet node address in the form area.node.
3 Examples   1.  /TO=NODEA4	 If NODEA is listed in NODELIST.DAT then ETHERWATCH4	 will use the  corresponding  Ethernet  address  to'	 match the packet destination address.   2.  /TO=AA-00-04-00-01-044	 This  will  result  in  packets  destined  for the"	 specified address being matched.   3.  /TO=1.44	 The "1.4" will be translated into a DECnet AA type4	 address and this will be used to match the  packet	 destination address.   4.  /TO=AA-00-04*4	 This will result in a match on any DECnet Phase IV4	 station address as the  packet  destination  being
	 matched.   5.  /TO=UNKNOWN4	 This  will  result  in the selection of any packet4	 whose  destination  address  is  not   listed   in	 NODELIST.DAT.2 Author2 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