.layout 2,2 .style headers 3,1,6,7,7,1,1,9,2 .first title .title ETHERWATCH User Guide .fill .no autojustify .no justify .no number .require "ETHERWATCH.RNT" .subtitle .date .page .send toc ^^Preface .blank 10 Preface .blank 2 This manual is intended as a guide to the use of the ETHERWATCH Utility. .blank .number page .chapter ^^ETHERWATCH Utility .header level 1 ^^Description 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. .blank 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). .header level 1 ^^Usage Summary 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. .blank ETHERWATCH should be invoked via a foreign command i.e. define a symbol (in this example ETHERWATCH) as follows: .blank .indent +8 $ ETHERWATCH == "$device:[directory]ETHERWATCH" .blank Where "device" and "directory" identify the location of the image. 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. .blank In order to run ETHERWATCH successfully, you will need PHY__IO privilege. .blank To exit ETHERWATCH use Control/C. .header level 1 ^^Ethernet Packet Header Formats 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 .blank .literal 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 | | +-----------------------------------------+ .end literal .header level 1 ^^Specifying Addresses and Protocols 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 next section) 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. .blank 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). .header level 1 ^^The NODELIST.DAT File 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. .blank 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 .list .display elements "(",rl,")" .list element;a blank line, which will be ignored .list element;a comment, beginning with either an exclamation mark (!) or a semi-colon (;) .list element;an Ethernet address (with or without wildcards) followed by an equals sign (=) followed by a description (usually a node name). .end list The "descriptions" (or names, as they are referred to in later sections) 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. .blank 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. .blank An example of the contents of a NODELIST.DAT can be found in Appendix-A. .chapter ^^ETHERWATCH 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. .header level 1 ^^Summary of qualifier usage The following list shows the qualifiers and default values. .blank .list 0 " " .list element;##Qualifier Default .list element; .list element;/BEGIN=date__time See description. .list element;/BOTH not /BOTH .list element;/CONTROL=match__string * .list element;/COPID=match__string * .list element;/COUNT=packet__count See description. .list element;/DEVICE=device See description. .list element;/DISPLAY=format ASCII .list element;/DSAP=match__string * .list element;/END=date__time See description. .list element;/FROM=address * .list element;/IPID=match__string * .list element;/NONAMES include names .list element;/OUTPUT[=filespec] Output to SYS$OUTPUT. .list element;/PID=match__string * .list element;/PLAYBACK[=filespec] See description. .list element;/PROTOCOL=protocol * .list element;/RECORD[=filespec] See description. .list element;/SSAP=match__string * .list element;/TO=address * .end list .page .header level 1 ^^/BEGIN Specifies when ETHERWATCH should start processing packets. .blank .repeat 70 "__" .blank Format .blank .left margin +4 /BEGIN=date__time .left margin -4 .blank .repeat 70 "__" .blank Description .blank .left margin +4 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. .left margin -4 .page .header level 1 ^^/BOTH Selects bi-directional matching of source and destination addresses. .blank .repeat 70 "__" .blank Format .blank .left margin +4 /BOTH .left margin -4 .blank .repeat 70 "__" .blank Description .blank .left margin +4 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. .left margin -4 .blank .repeat 70 "__" .blank Examples .list .list element;/FROM=NODEA/BOTH .blank 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. .list element;/FROM=NODEA/TO=NODEB .blank This will result in only packets originating from NODEA addressed to NODEB being chosen and displayed. .list element;/FROM=NODEA/TO=NODEB/BOTH .blank By specifying /BOTH, packets originating from NODEA addressed to NODEB and packets originating from NODEB addressed to NODEA will be chosen and displayed. .end list .page .header level 1 ^^/CONTROL Allows selection of packets based on the control byte field. .blank .repeat 70 "__" .blank Format .blank .left margin +4 /CONTROL=control__code .left margin -4 .blank .repeat 70 "__" .blank Description .blank .left margin +4 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. .left margin -4 .page .header level 1 ^^/COPID Allows selection of packets based on the Company Protocol Identifier (COPID) field. .blank .repeat 70 "__" .blank Format .blank .left margin +4 /COPID=company__id .left margin -4 .blank .repeat 70 "__" .blank Description .blank .left margin +4 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. .left margin -4 .page .header level 1 ^^/COUNT Tells ETHERWATCH to stop processing after the specified number of packets. .blank .repeat 70 "__" .blank Format .blank .left margin +4 /COUNT=packet__count .left margin -4 .blank .repeat 70 "__" .blank Description .blank .left margin +4 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. .blank Specifying a value of zero will result in processing continuing until interrupted by a Control/C. .left margin -4 .page .header level 1 ^^/DEVICE The /DEVICE qualifier is used to select which Ethernet controller is to be monitored. .blank .repeat 70 "__" .blank Format .blank .left margin +4 /DEVICE=device .left margin -4 .blank .repeat 70 "__" .blank Description .blank .left margin +4 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. .left margin -4 .page .header level 1 ^^/DISPLAY Allows selection of the display format of the packet contents. .blank .repeat 70 "__" .blank Format .blank .left margin +4 /DISPLAY=option .left margin -4 .blank .repeat 70 "__" .blank Keywords .left margin +4 .list " " .list element;ALL specifies that packet data is to be displayed in ASCII and hexadecimal format. .list element;ASCII specifies that packet data is to be displayed in ASCII format only. This is the default value. .list element;BOTH is the same as ALL. .list element;FAST will result in the packet data being displayed in ASCII (using the !AF directive of the $FAO system service) with no byte counters. .list element;HEXADECIMAL specifies that the packet data is to be displayed in hexadecimal byte format. .list element;NONE will result in no packet data being displayed. Packet headers will still be displayed. .list element;TEXT is the same as ASCII. .end list .left margin -4 .repeat 70 "__" .blank Description .blank .left margin +4 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. .left margin -4 .blank .repeat 70 "__" .blank Examples .list .list element;/DISPLAY=NONE .blank 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. .list element;/DISPLAY=ALL .blank Will result in packet data being displayed in ASCII and hexadecimal byte format. .end list .page .header level 1 ^^/DSAP Allows selection of packets based on the Destination Service Access Point (DSAP) field. .blank .repeat 70 "__" .blank Format .blank .left margin +4 /DSAP=destination__sap .left margin -4 .blank .repeat 70 "__" .blank Description .blank .left margin +4 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. .left margin -4 .page .header level 1 ^^/END Specifies when ETHERWATCH should stop processing packets. .blank .repeat 70 "__" .blank Format .blank .left margin +4 /END=date__time .left margin -4 .blank .repeat 70 "__" .blank Description .blank .left margin +4 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 .left margin -4 .page .header level 1 ^^/FROM Allows selection of packets based on the packet source address. .blank .repeat 70 "__" .blank Format .blank .left margin +4 /FROM=address .left margin -4 .blank .repeat 70 "__" .blank Keywords .blank .left margin +4 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. .left margin -4 .blank .repeat 70 "__" .blank Description .blank .left margin +4 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. .left margin -4 .blank .repeat 70 "__" .blank Examples .list .list element;/FROM=NODEA .blank If NODEA is listed in NODELIST.DAT then ETHERWATCH will use the corresponding Ethernet address to match the packet source address. .list element;/FROM=AA-00-04-00-01-04 .blank This will result in packets originating from the specified address being matched. .list element;/FROM=1.4 .blank The "1.4" will be translated into a DECnet AA type address and this will be used to match the packet source address. .list element;/FROM=AA-00-04* .blank This will result in a match on any DECnet Phase IV station address as the packet source address being matched. .list element;/FROM=UNKNOWN .blank This will result in the selection of any packet whose source address is not listed in NODELIST.DAT. .end list .page .header level 1 ^^/IPID Allows selection of packets based on the Implementation Specific Protocol Identifier (IPID) field. .blank .repeat 70 "__" .blank Format .blank .left margin +4 /IPID=internal__pid .left margin -4 .blank .repeat 70 "__" .blank Description .blank .left margin +4 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. .left margin -4 .page .header level 1 ^^/NONAMES Suppresses matching of Ethernet addresses with names when displaying packet header information. .blank .repeat 70 "__" .blank Format .blank .left margin +4 /NONAMES .left margin -4 .blank .repeat 70 "__" .blank Description .blank .left margin +4 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. .blank 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. .left margin -4 .page .header level 1 ^^/OUTPUT Allows output to be directed to a file. .blank .repeat 70 "__" .blank Format .blank .left margin +4 /OUTPUT[=filespec] .left margin -4 .blank .repeat 70 "__" .blank Description .blank .left margin +4 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. .blank If a file by the same name exists, the output is appended to the existing file otherwise a new file is created. .left margin -4 .page .header level 1 ^^/PID Allows selection of packets based on the User's Protocol Identifier (PID) field. .blank .repeat 70 "__" .blank Format .blank .left margin +4 /PID=protoocl__id .left margin -4 .blank .repeat 70 "__" .blank Description .blank .left margin +4 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. .left margin -4 .page .header level 1 ^^/PLAYBACK Allows processing of data that has been previously recorded. field. .blank .repeat 70 "__" .blank Format .blank .left margin +4 /PLAYBACK[=filespec] .left margin -4 .blank .repeat 70 "__" .blank Description .blank .left margin +4 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. .left margin -4 .page .header level 1 ^^/PROTOCOL Allows selection of packets based on the Ethernet Protocol Type field. .blank .repeat 70 "__" .blank Format .blank .left margin +4 /PROTOCOL=protocol .left margin -4 .blank .repeat 70 "__" .blank Keywords .blank .left margin +4 The following list shows currently available keywords and the associated protocol. .blank .list 0 " " .list element;Protocol Keyword .list element; .list element;#60-01 MOPDUMP .list element;#60-02 MOPCONSOLE .list element;#60-03 DECNET .list element;#60-04 LAT .list element;#60-05 DIAGNOSTICS .list element;#60-07 LAVC .list element;#80-38 RBMS .list element;#80-3B VAXELN .list element;#80-3E DNS .list element;#80-40 NETBIOS .list element;#80-41 LAST .end list (Others may be added to the list in later releases.) .blank Any other value given in the command line will be used as the protocol to match against. .left margin -4 .blank .repeat 70 "__" .blank Description .blank .left margin +4 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. .left margin -4 .blank .repeat 70 "__" .blank Examples .list .list element;/PROTOCOL=DECNET .blank This will result in only DECnet protocol messages (60-03) being matched. Using /PROTOCOL=60-03 would achieve the same result. .list element;/PROTOCOL=80-41 .blank This will result in packets with the specified protocol type being matched. .list element;/PROTOCOL=60* .blank This will result in packets with protocols beginning with 60 being matched. .end list .page .header level 1 ^^/RECORD Allows recording of data so that it can be processed later. field. .blank .repeat 70 "__" .blank Format .blank .left margin +4 /RECORD[=filespec] .left margin -4 .blank .repeat 70 "__" .blank Description .blank .left margin +4 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. .left margin -4 .page .header level 1 ^^/SSAP Allows selection of packets based on the Source Service Access Point (SSAP) field. .blank .repeat 70 "__" .blank Format .blank .left margin +4 /SSAP=source__sap .left margin -4 .blank .repeat 70 "__" .blank Description .blank .left margin +4 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. .left margin -4 .page .header level 1 ^^/TO Allows selection of packets based on the packet destination address. .blank .repeat 70 "__" .blank Format .blank .left margin +4 /TO=address .left margin -4 .blank .repeat 70 "__" .blank Keywords .blank .left margin +4 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. .left margin -4 .blank .repeat 70 "__" .blank Description .blank .left margin +4 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. .left margin -4 .blank .repeat 70 "__" .blank Examples .list .list element;/TO=NODEA .blank If NODEA is listed in NODELIST.DAT then ETHERWATCH will use the corresponding Ethernet address to match the packet destination address. .list element;/TO=AA-00-04-00-01-04 .blank This will result in packets destined for the specified address being matched. .list element;/TO=1.4 .blank The "1.4" will be translated into a DECnet AA type address and this will be used to match the packet destination address. .list element;/TO=AA-00-04* .blank This will result in a match on any DECnet Phase IV station address as the packet destination being matched. .list element;/TO=UNKNOWN .blank This will result in the selection of any packet whose destination address is not listed in NODELIST.DAT. .end list .appendix ^^Sample NODELIST.DAT The following is an example of the contents of a valid NODELIST.DAT file. .blank .left margin +2 .literal $ 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 $ .end literal .left margin -2