.layout 2,2
.style headers 3,1,6,7,7,1,1,9,2
.first title
.title TCPWATCH User Guide
.fill
.no autojustify
.no justify
.no number
.require "TCPWATCH.RNT"
.subtitle
.date
.page
.send toc ^^Preface
.blank 10
Preface
.blank 2
This manual is intended as a guide to the use of the TCPWATCH Utility.
.blank
.number page

.chapter ^^TCPWATCH Utility

.header level 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.
.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

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.
.blank
TCPWATCH should be invoked via a foreign command i.e. define a symbol
(in this example TCPWATCH) as follows:
.blank
.indent +8
$ TCPWATCH == "$device:[directory]TCPWATCH"
.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 TCPWATCH successfully, you will need PHY__IO privilege.
.blank
To exit TCPWATCH use Control/C.

.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 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.

.header level 1 ^^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.
.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 ^^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.

.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;/BOTH				not /BOTH
.list element;/DEVICE=device			See description.
.list element;/DISPLAY=format		ASCII
.list element;/FROM=address			*
.list element;/NONAMES			include names
.list element;/TO=address			*
.end list

.page
.header level 1 ^^/BEGIN
Specifies when TCPWATCH 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 TCPWATCH to start processing packets
at a predetermined time.  By default TCPWATCH 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 ^^/COUNT
Tells TCPWATCH 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 TCPWATCH 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 TCPWATCH 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.  This
formatting is only performed on certain TCP packets since many packets are
in a "known" format and are not "dumped".
.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 ^^/END
Specifies when TCPWATCH 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 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
.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 TCPWATCH 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 ^^/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 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.
.blank
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.
.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 TCPWATCH.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 ^^/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
TCPWATCH.RECORD.  This qualifier cannot be used with the /RECORD, /BEGIN
or /END qualifiers.
.left margin -4

.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 TCPWATCH.RECORD.
.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 TCPWATCH 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