tcpgraph(1)

SYNOPSIS
tcpgraph

DESCRIPTION
tcpgraph is a packet shell script written in Tcl/Tk. It parses snoop or tcpdump capture files and displays information about the TCP traffic. Which data is displayed can be selected by an array of buttons provided on the right hand side of the window. Each selected button represents an analysis window to be produced when subsequent TCP connections are selected.

Each analysis is provided as a separate utility, stored in a particular directory in the packet shell distribution. This is to allow the user to provide customized analysis modules to suit their needs. Those modules are stored in /opt/psh/lib/tcllib/tcpgraph, and must end in .plugin .

Standard Plug-ins

Two plug-ins are provided with the distribution currently. One provides a summary of general data about the connection. Finally, the time-sequence analysis plug-in provides a time-sequence graph to aide understanding the performance over time of a TCP connection. See How to Interpet the Plot below for details on understanding the output of this powerful plug-in.

Writing Plug-ins

Each plug-in operates by using a standard interface which tcpgraph provides. First, all Tcl code in a plug-in must be contained in Tcl procedures. Each plug-in must supply a procedure named plugin_name, which returns a short name of the plug-in. This name is displayed besides the plug-in's select button by tcpgraph .

The analysis is done in the plug-in's procedure named plugin_main. This procedure receives one argument, a connection identifier. The connection identifier provides the necessary information to identify the connection's data in a series of global variables extracted from the trace file by tcpgraph . The connection id consists of four components, separated by underscores. The first component is the IP source address, followed by the source port, then the IP destination address and the destination port. Each IP address is represented as a dotted quad, and each port as a decimal number.

The plugin_main is responsible for creating the Tk window in which it will display its output. See conn-summary.plugin for the simplest example of how to do this.

Global Trace Data
Tcpgraph provides a series of global array variables which contain the TCP data extracted from the trace file. Each bidirectional TCP connection is treated as two one-way connections referred to as half connections. The following sections describe each variable's contents.

HalfConnSegs
This variable indicates the total number of TCP segments sent by the source to the destination for a given half connection. The index is the connection id.

HalfConnBytes
Total number of data bytes sent by the source to the destination, indexed by the connection id, is available in this array. Retransmissions are counted in this total, so for example a trace in which the source sent the same 128 byte segment eight times would have 1024 for the HalfConnBytes.

HalfConnDStart
Indexed by the connection id, followed by an underscore and the packet number of the desired packet from the indicated source to the indicated destination, this variable indicates the starting segment number. Note that this does not indicate if any data bytes are actually contained in this packet. The value is relative to the first segment for this half connection found in this capture file, not the absolute value found in the TCP packet.

HalfConnDEnd
Identical to HalfConnDStart except it indicates the segment number of the last data byte in the indicated packet. If HalfConnDEnd is equal to HalfConnDStart then no data bytes were sent with this segment. The value of this variable is relative to the first packet of this half connection.

HalfConnTime
Also indexed by the connection id followed by the underscore separated packet number, this indicates the arrival time of the packet. The time is kept as a floating point number of seconds from the beginning of the capture file.

HalfConnISS
Records the first segment number of the connection recorded by this capture file. This records the absolute segment number, not a relative segment number.

HalfConnAck
Indexed by connection id and packet number, this indicates the ack value carried by this packet.

HalfConnWin
Indexed by connection id and packet number, this indicates the window offered by this packet.

HalfConnFlags
Indexed by connection id and packet number, this indicates the flags in this packet.

How to Interpret the Plot

The packet traces are displayed as a time-sequence plot where the horizontal axis is indexed by time and the vertical axis is indexed by sequence number. As provided by the BLT package's graph command, you can zoom in or out on a plot. Click the left button, then move the mouse to the diagonal corner of the region you would like to zoom to, then click the left button again. Use the Zoom Out button to step back to a previous view of the graph. All zoom operations are kept as a stack, so you can click multiple times to back out incrementally.

Packets sent by the sender are plotted by placing a vertical line segment in time-sequence space starting at the sequence number contained in the sequence field of the packet and extending upwards for the length of the packet. An arrow is affixed to each end of the line segment (to make segments easier to recognize and make it possible to see zero-length segments). Zero length segments appear only as two arrows facing each other, which looks like the letter "X". Location relative to the horizontal axis corresponds to the timestamp on the packet in the trace. Retransmitted segments are red in color, to highlight them.

Packets sent by the receiver are plotted by extracting the acknowledgement and window fields, computing an end-of-window number by adding these two fields together, and plotting points at the location of the (time-of-packet, acknowledgement) and (time-of-packet, end-of-window) in the time-sequence space. Space between these two points can be thought of as the window and over-and-up stair steps are plotted from each of the points plotted by the previous inbound packet to the corresponding new point. The stair-step produced by plotting the acknowledgement fields is called the ack line and the region on the plot between the ack line and the line at the end of the window (the window line) can be thought of as the window. To make visible inbound packets which contain the same acknowledgement or window numbers as the previous packet, down tick marks are placed on the ack line and up tick marks window line.

Both these plots are combined to produce the time-sequence plot.

FILES

/opt/psh/bin/tcpgraph
    /opt/psh/tcllib/tcpgraph/*.plugin

SEE ALSO
snoop(1M), file(3) tcpdump(1).