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