TCPWATCH User Guide CONTENTS Preface CHAPTER 1 TCPWATCH 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 TCPWATCH 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 /NONAMES . . . . . . . . . . . . . . . . . . . . 2-11 2.10 /OUTPUT . . . . . . . . . . . . . . . . . . . . 2-12 2.11 /PLAYBACK . . . . . . . . . . . . . . . . . . . 2-13 2.12 /RECORD . . . . . . . . . . . . . . . . . . . . 2-14 2.13 /TO . . . . . . . . . . . . . . . . . . . . . . 2-15 APPENDIX A Sample NODELIST.DAT TCPWATCH User Guide Preface This manual is intended as a guide to the use of the TCPWATCH Utility. 2 CHAPTER 1 TCPWATCH Utility 1.1 Description The TCPWATCH 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 TCP/IP 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 TCPWATCH allows you to monitor traffic based on Ethernet address (either source, destination or both). 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. TCPWATCH should be invoked via a foreign command i.e. define a symbol (in this example TCPWATCH) as follows: $ TCPWATCH == "$device:[directory]TCPWATCH" 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. In order to run TCPWATCH successfully, you will need PHY_IO privilege. To exit TCPWATCH use Control/C. 1-1 TCPWATCH 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 TCPWATCH 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, TCPWATCH 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 TCPWATCH 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. 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 * /NONAMES include names /TO=address * 2-1 TCPWATCH Qualifiers /BEGIN 2.2 /BEGIN Specifies when TCPWATCH should start processing packets. ______________________________________________________________________ Format /BEGIN=date_time ______________________________________________________________________ Description The /BEGIN qualifier can be used to get TCPWATCH to start processing packets at a predetermined time. By default TCPWATCH will start processing packets immediately. 2-2 TCPWATCH 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 TCPWATCH Qualifiers /COUNT 2.4 /COUNT Tells TCPWATCH 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 TCPWATCH 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 TCPWATCH 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 TCPWATCH terminates with an error. 2-5 TCPWATCH 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 TCP 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 TCPWATCH 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 TCPWATCH Qualifiers /END 2.7 /END Specifies when TCPWATCH should stop processing packets. ______________________________________________________________________ Format /END=date_time ______________________________________________________________________ Description The /END qualifier can be used to get TCPWATCH to stop processing packets at a predetermined time. By default TCPWATCH 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 TCPWATCH 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 TCPWATCH 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 TCPWATCH 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 TCPWATCH Qualifiers /NONAMES 2.9 /NONAMES Suppresses matching of Ethernet addresses with names when displaying packet header information. ______________________________________________________________________ Format /NONAMES ______________________________________________________________________ Description The /NONAMES qualifier will prevent TCPWATCH 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 TCPWATCH starts and you will still be able to specify names on the /FROM and /TO qualifiers. 2-11 TCPWATCH Qualifiers /OUTPUT 2.10 /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 TCPWATCH.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-12 TCPWATCH Qualifiers /PLAYBACK 2.11 /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 TCPWATCH.RECORD. This qualifier cannot be used with the /RECORD, /BEGIN or /END qualifiers. 2-13 TCPWATCH Qualifiers /RECORD 2.12 /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 TCPWATCH.RECORD. 2-14 TCPWATCH Qualifiers /TO 2.13 /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 TCPWATCH 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-15 TCPWATCH 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-16 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