LATWATCH User Guide CONTENTS Preface CHAPTER 1 LATWATCH Utility 1.1 Description . . . . . . . . . . . . . . . . . . . 1-1 1.2 Usage Summary . . . . . . . . . . . . . . . . . . 1-1 1.3 Specifying Addresses and Protocols . . . . . . . . 1-2 1.4 The NODELIST.DAT File . . . . . . . . . . . . . . 1-2 CHAPTER 2 LATWATCH Qualifiers 2.1 Summary of qualifier usage . . . . . . . . . . . . 2-1 2.2 /BEGIN . . . . . . . . . . . . . . . . . . . . . . 2-2 2.3 /BOTH . . . . . . . . . . . . . . . . . . . . . . 2-3 2.4 /COUNT . . . . . . . . . . . . . . . . . . . . . . 2-4 2.5 /DEVICE . . . . . . . . . . . . . . . . . . . . . 2-5 2.6 /DISPLAY . . . . . . . . . . . . . . . . . . . . . 2-6 2.7 /END . . . . . . . . . . . . . . . . . . . . . . . 2-8 2.8 /FROM . . . . . . . . . . . . . . . . . . . . . . 2-9 2.9 /MESSAGE_TYPE . . . . . . . . . . . . . . . . . 2-11 2.10 /NONAMES . . . . . . . . . . . . . . . . . . . . 2-13 2.11 /OUTPUT . . . . . . . . . . . . . . . . . . . . 2-14 2.12 /PLAYBACK . . . . . . . . . . . . . . . . . . . 2-15 2.13 /RECORD . . . . . . . . . . . . . . . . . . . . 2-16 2.14 /TO . . . . . . . . . . . . . . . . . . . . . . 2-17 APPENDIX A Sample NODELIST.DAT LATWATCH User Guide Preface This manual is intended as a guide to the use of the LATWATCH Utility. 2 CHAPTER 1 LATWATCH Utility 1.1 Description The LATWATCH 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 will process only LAT packets. 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). 1.2 Usage Summary LATWATCH allows you to monitor traffic based on Ethernet address (either source, destination or both) and LAT message type. 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. LATWATCH should be invoked via a foreign command i.e. define a symbol (in this example LATWATCH) as follows: $ LATWATCH == "$device:[directory]LATWATCH" Where "device" and "directory" identify the location of the image. You should also define a logical LATWATCHER 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 LATWATCH successfully, you will need PHY_IO privilege. To exit LATWATCH use Control/C. 1-1 LATWATCH Utility Specifying Addresses and Protocols 1.3 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 LATWATCH 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. 1.4 The NODELIST.DAT File When starting up, LATWATCH 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. 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). 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. 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. An example of the contents of a NODELIST.DAT can be found in Appendix-A. 1-2 CHAPTER 2 LATWATCH 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. Matching of address fields is done on character strings, thus allowing the use of standard VMS wildcard constructs using the % and * wildcard characters. Matching of LAT message types is done on the binary value found in the LAT packet. Multiple message type can be specified on the /MESSAGE_TYPE qualifier. 2.1 Summary of qualifier usage The following list shows the qualifiers and default values. Qualifier Default /BOTH not /BOTH /DEVICE=device See description. /DISPLAY=format ASCII /FROM=address * /MESSAGE_TYPE=type_list * /NONAMES include names /TO=address * 2-1 LATWATCH Qualifiers /BEGIN 2.2 /BEGIN Specifies when LATWATCH should start processing packets. ______________________________________________________________________ Format /BEGIN=date_time ______________________________________________________________________ Description The /BEGIN qualifier can be used to get LATWATCH to start processing packets at a predetermined time. By default LATWATCH will start processing packets immediately. 2-2 LATWATCH Qualifiers /BOTH 2.3 /BOTH Selects bi-directional matching of source and destination addresses. ______________________________________________________________________ Format /BOTH ______________________________________________________________________ Description 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. ______________________________________________________________________ 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-3 LATWATCH Qualifiers /COUNT 2.4 /COUNT Tells LATWATCH to stop processing after the specified number of packets. ______________________________________________________________________ Format /COUNT=packet_count ______________________________________________________________________ Description The /COUNT qualifier specifies the number of packets that should be processed by LATWATCH 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-4 LATWATCH Qualifiers /DEVICE 2.5 /DEVICE The /DEVICE qualifier is used to select which Ethernet controller is to be monitored. ______________________________________________________________________ Format /DEVICE=device ______________________________________________________________________ Description 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 LATWATCH terminates with an error. 2-5 LATWATCH Qualifiers /DISPLAY 2.6 /DISPLAY Allows selection of the display format of the packet contents. ______________________________________________________________________ Format /DISPLAY=option ______________________________________________________________________ Keywords 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. ______________________________________________________________________ Description 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. This formatting is only performed on certain LAT packets since many packets are in a "known" format and are not "dumped". ______________________________________________________________________ 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 2-6 LATWATCH Qualifiers /DISPLAY 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-7 LATWATCH Qualifiers /END 2.7 /END Specifies when LATWATCH should stop processing packets. ______________________________________________________________________ Format /END=date_time ______________________________________________________________________ Description The /END qualifier can be used to get LATWATCH to stop processing packets at a predetermined time. By default LATWATCH will stop processing packets after 30 minutes unless overridden by the /COUNT qualifier. The /END qualifier cannot be used with the /COUNT qualifier 2-8 LATWATCH Qualifiers /FROM 2.8 /FROM Allows selection of packets based on the packet source address. ______________________________________________________________________ Format /FROM=address ______________________________________________________________________ Keywords 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. ______________________________________________________________________ Description 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. ______________________________________________________________________ Examples 1. /FROM=NODEA If NODEA is listed in NODELIST.DAT then LATWATCH 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 2-9 LATWATCH Qualifiers /FROM 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-10 LATWATCH Qualifiers /MESSAGE_TYPE 2.9 /MESSAGE_TYPE Allows selection of packets based on the LAT message type. ______________________________________________________________________ Format /MESSAGE_TYPE=type_list ______________________________________________________________________ Keywords The following list shows available keywords. Keyword RUN_MESSAGE (same as TYPE0) START_MESSAGE (same as TYPE1) STOP_MESSAGE (same as TYPE2) COMMAND_MESSSAGE (same as TYPE12) STATUS_MESSSAGE (same as TYPE13) SERVICE_MESSAGE (same as TYPE10) SOLICIT_MESSAGE (same as TYPE14) RESPONSE_MESSAGE (same as TYPE15) UNKNOWN Includes all types NOT listed above. ALL Will include all message types. TYPEn Where n is in the range 0 to 15. ______________________________________________________________________ Description The /MESSAGE_TYPE qualifier allows selection of packets based on the contents of the LAT message type field in the LAT packet header. The value specified can either be one of the keywords above or a list of multiple keywords separated by commas and enclosed in parentheses. ______________________________________________________________________ Examples 1. /MESSAGE_TYPE=START This will result in only those START messages being selected i.e. messages requesting the establishment of a LAT virtual circuit. Using /PROTOCOL=60-03 would achieve the same result. 2-11 LATWATCH Qualifiers /MESSAGE_TYPE 2. /MESSAGE_TYPE=(SOLICIT,RESPONSE) This will result in packets related to the soliciting of information from a master node and the response from the master node. 2-12 LATWATCH Qualifiers /NONAMES 2.10 /NONAMES Suppresses matching of Ethernet addresses with names when displaying packet header information. ______________________________________________________________________ Format /NONAMES ______________________________________________________________________ Description The /NONAMES qualifier will prevent LATWATCH 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 LATWATCH starts and you will still be able to specify names on the /FROM and /TO qualifiers. 2-13 LATWATCH Qualifiers /OUTPUT 2.11 /OUTPUT Allows output to be directed to a file. ______________________________________________________________________ Format /OUTPUT[=filespec] ______________________________________________________________________ Description The /OUTPUT qualifier allows the output to be directed to the specified file. If no filename is given, the default is LATWATCH.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-14 LATWATCH Qualifiers /PLAYBACK 2.12 /PLAYBACK Allows processing of data that has been previously recorded. field. ______________________________________________________________________ Format /PLAYBACK[=filespec] ______________________________________________________________________ Description The /PLAYBACK qualifier allows previously recorded ethernet packet data to be processed. The default filename for the recorded data is LATWATCH.RECORD. This qualifier cannot be used with the /RECORD, /BEGIN or /END qualifiers. 2-15 LATWATCH Qualifiers /RECORD 2.13 /RECORD Allows recording of data so that it can be processed later. field. ______________________________________________________________________ Format /RECORD[=filespec] ______________________________________________________________________ Description 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-16 LATWATCH Qualifiers /TO 2.14 /TO Allows selection of packets based on the packet destination address. ______________________________________________________________________ Format /TO=address ______________________________________________________________________ Keywords 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. ______________________________________________________________________ Description 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. ______________________________________________________________________ Examples 1. /TO=NODEA If NODEA is listed in NODELIST.DAT then LATWATCH 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. 2-17 LATWATCH Qualifiers /TO 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-18 APPENDIX A Sample NODELIST.DAT 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 A-1 Sample NODELIST.DAT ! 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 $ A-2