Sie sind auf Seite 1von 91

TCPTRACE Manual

Manikantan Ramadas
mramadas@irg.cs.ohiou.edu

24 August 2003
c 2003 Internetworking Research Group, Ohio University. All rights reserved.
Copyright
Abstract

This manual documents the general usage of the tcptrace program. tcptrace is a TCP Connection Analysis Tool
originally written by Dr.Shawn Ostermann at Ohio University. It is maintained these days by his students and members
of the Internetworking Research Group (IRG) at Ohio University.
CONTENTS

1 Preface 1

2 Getting Started 3
2.1 Installing tcptrace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.2 Using tcptrace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

3 Basic Usage 5

4 Detailed Usage 7
4.1 Detailed Stats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
4.2 RTT Stats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
4.3 CWND Stats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

5 Graphing 15
5.1 Time Sequence Graph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
5.2 Throughput Graph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
5.3 RTT Graph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
5.4 Outstanding Data Graph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
5.5 Segment Size Graph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
5.6 Time-Line Graph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
5.7 Miscellany . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

6 Filtering Connections 33
6.1 Basic Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
6.2 Advanced Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

7 Extended Options 39
7.1 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
7.2 Graphing Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
7.3 Warning Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

8 Miscellany 45
8.1 UDP Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
8.2 Real-Time Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
8.3 Packet Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
8.4 Other Miscellany . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

9 Modules 51
9.1 TRAFFIC Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
9.2 HTTP Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

i
9.3 SLICE Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
9.4 COLLIE Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
9.5 Real-Time Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
9.6 Writing Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

A Arguments QR 73

B XPLOT QR 77

C Protocol QR 79

D License 81

ii
CHAPTER

ONE

Preface

The goal of this manual is to document the tcptrace program; to explain how to get it installed, explain its capabilities,
how to get it do all it can do, what all the output it generates mean, and how they are calculated, etc. However, the
goal is not to explain the working of the TCP/IP protocol suite itself, and there are nice books that do this already.
I recommend my favorite book [?] if you need to understand the TCP/IP protocol suite better, or if commonly used
TCP/IP parlance like “SACK”, “CWND”, “pure ACK” etc., are not familiar to you.
The manual is organized into chapters with the goal of making them as modular as possible so that they can be read
independently of one another. It consists of the following chapters :

• Getting Started Explains how to get tcptrace up and running on your system, and the details from the environ-
ment that tcptrace uses.
• Basic Usage Explains the basic output generated by tcptrace .
• Detailed Usage Explains how to perform more detailed analysis, and the fields in the long output format.
• Graphing Explains the graphs that can be generated, and how to generate them.
• Filtering Connections Explains how to filter-out or filter-in the connection(s) of interest.
• Extended Options Explains what each of the extended options mean and how to turn them on/off.
• Miscellany Explains all the miscellaneous things the program can do, like minimal UDP analysis, printing out
packet details, etc.
• Modules Explains the behavior of the modules distributed with tcptrace , and briefly on how to write your own
modules.

If you are a tcptrace Power-user familiar with the program, and are just looking for the option that generates the output
you need, you might dive straight into Appendix A: Arguments Quick Reference. You may find answers to some of
your xplot related questions in Appendix B: XPLOT Quick Reference. The syntactical definitions of common protocol
headers are provided in Appendix C Protocol Quick Reference.
Finally, in a slight abuse of parlance, the terms “segments” and “packets” have been used interchangeably in the
manual. However it would be clear from context, for e.g., if we say “TCP packets” we mean “TCP segments”.
Hopefully it would not be a cause of concern.

Thanks Thanks are due to my friend Avinash S. Lakhiani for working on an earlier version of the manual and for
getting the Documentation project kick-started. Some sections of the manual have been drawn directly from his
manuscript. Thanks are also due to the Python Software Foundation for the LATEX 2ε style files from the Python
Documentation Project used for generating this manual.

1
2
CHAPTER

TWO

Getting Started

2.1 Installing tcptrace


tcptrace can be downloaded from the project web-site http://www.tcptrace.org/download.html .
Installing the stable version of tcptrace follows the typical procedure used to install most open-source software on
UNIX-based systems. Unzip and Untar the tar-ball (tcptrace-X.Y.Z.tar.gz) with the following steps :

• gunzip tcptrace-X.Y.Z.tar.gz
• tar xvf tcptrace-X.Y.Z.tar

Now, enter the tcptrace-X.Y.Z directory and install tcptrace with the following steps :

• ./configure
• make
• make install (as super-user)

You may also download cutting-edge version of tcptrace from the project’s CVS repository. Instructions for doing so
may be found in the download page at http://www.tcptrace.org/download.html .
A port of the tcptrace program has also been made to the Windows platforms. However windows ports tend only to be
made for stable releases of the program. More information on the Windows version of the program can be found in :
http://www.tcptrace.org/windows.html .

2.2 Using tcptrace


tcptrace can be run on a network dumpfile trivially as in

tcptrace dumpfile
where dumpfile is a file containing traffic captured from the network. tcptrace understands various network dump-
file formats like tcpdump, snoop, etherpeek, netm, ns, nlanr, netscout. Dumpfiles in these formats can also be com-
pressed in GnuZIP (gz), BZIP2 (bz2), or UNIX compress (Z) formats, as tcptrace can uncompress them on the fly.
tcptrace can be passed multiple command-line options to perform various tasks as explained in subsequent chapters. If
you want tcptrace to always start processing with certain command-line options, you may store them in .tcptrac-
erc file in your home directory, or set the TCPTRACEOPTS environment variable with the options. tcptrace reads the

3
.tcptracerc file and the TCPTRACEOPTS environment variable before processing options given in command-
line.
You may also use tcptrace -h to get brief descriptions of various command-line options.

4 Chapter 2. Getting Started


CHAPTER

THREE

Basic Usage

When tcptrace is run trivially on a dumpfile, it generates output similar to the following :

Beluga:/Users/mani> tcptrace tigris.dmp

1 arg remaining, starting with ’tigris.dmp’


Ostermann’s tcptrace -- version 6.4.5 -- Fri Jun 13, 2003

87 packets seen, 87 TCP packets traced


elapsed wallclock time: 0:00:00.037900, 2295 pkts/sec analyzed
trace file elapsed time: 0:00:12.180796
TCP connection info:
1: pride.cs.ohiou.edu:54735 - elephus.cs.ohiou.edu:ssh (a2b) 30> 30< (complete)
2: pride.cs.ohiou.edu:54736 - a17-112-152-32.apple.com:http (c2d) 12> 15< (complete)

In the above example, tcptrace is run on dumpfile tigris.dmp. The initial lines tell that the file tcptrace is processing
currently is tigris.dmp, the version of tcptrace running, and when it was compiled. The next line tells that a total
of 87 packets were seen in the dumpfile and all the 87 TCP packets (in this case) were traced. The next line tells
that the elapsed wallclock timei.e., the time tcptrace took to process the dumpfile, and the average speed in
packets per second taken for processing. The following line indicates the trace file elapsed time i.e., the
duration of packet capture of the dumpfile calculated as the duration between the capture of the first and last packets.
The subsequent lines indicate the two TCP connections traced from the dumpfile. The first connection was seen be-
tween machines pride.cs.ohiou.edu at TCP port 54735, and elephus.cs.ohiou.edu at TCP port ssh
(22). Similarly the second connection was seen between machines pride.cs.ohiou.edu at TCP port 54736,
and a17-112-152-32.apple.com at TCP port http (80). tcptrace uses a labeling scheme to refer to individual
connections traced. In the above example the two connections are labeled a2b and c2d respectively. For the first
connection, 30 packets were seen in the a2b direction (pride.cs.ohiou.edu ==> elephus.cs.ohiou.edu) and 30 packets
were seen in the b2a direction (elephus.cs.ohiou.edu ==> pride.cs.ohiou.edu). The two connections are reported as
complete indicating that the entire TCP connection was traced i.e., SYN and FIN segments opening and closing the
connection were traced. TCP connections may also be reported as reset if the connection was closed with an RST
segment, or unidirectional if traffic was seen flowing in only one direction.
The above brief output generated by tcptrace can also be generated with the -b option. In the above example, tcp-
trace looked up names (elephus.cs.ohiou.edu, for example) and service names (http, for example) involving a DNS
name lookup operation. Such name and service lookups can be turned off with the -n option to make tcptrace pro-
cess faster. If you need name lookups but would rather have the short names of machines (elephus instead of
elephus.cs.ohiou.edu for example), use the -s option.

5
6
CHAPTER

FOUR

Detailed Usage

4.1 Detailed Stats


tcptrace can produce detailed statistics of TCP connections from dumpfiles when given the -l or the long output
option. The -l option produces output similar to the one shown in this example.

Beluga:/Users/mani> tcptrace -l malus.dmp.gz

1 arg remaining, starting with ’malus.dmp.gz’


Ostermann’s tcptrace -- version 6.4.6 -- Tue Jul 1, 2003

32 packets seen, 32 TCP packets traced


elapsed wallclock time: 0:00:00.037948, 843 pkts/sec analyzed
trace file elapsed time: 0:00:00.404427
TCP connection info:
1 TCP connection traced:
TCP connection 1:
host a: elephus.cs.ohiou.edu:59518
host b: a17-112-152-32.apple.com:http
complete conn: yes
first packet: Thu Jul 10 19:12:54.914101 2003
last packet: Thu Jul 10 19:12:55.318528 2003
elapsed time: 0:00:00.404427
total packets: 32
filename: malus.dmp.gz
a->b: b->a:
total packets: 16 total packets: 16
ack pkts sent: 15 ack pkts sent: 16
pure acks sent: 13 pure acks sent: 2
sack pkts sent: 0 sack pkts sent: 0
dsack pkts sent: 0 dsack pkts sent: 0
max sack blks/ack: 0 max sack blks/ack: 0
unique bytes sent: 450 unique bytes sent: 18182
actual data pkts: 1 actual data pkts: 13
actual data bytes: 450 actual data bytes: 18182
rexmt data pkts: 0 rexmt data pkts: 0
rexmt data bytes: 0 rexmt data bytes: 0
zwnd probe pkts: 0 zwnd probe pkts: 0
zwnd probe bytes: 0 zwnd probe bytes: 0
outoforder pkts: 0 outoforder pkts: 0
pushed data pkts: 1 pushed data pkts: 1
SYN/FIN pkts sent: 1/1 SYN/FIN pkts sent: 1/1
req 1323 ws/ts: Y/Y req 1323 ws/ts: Y/Y

7
adv wind scale: 0 adv wind scale: 0
req sack: Y req sack: N
sacks sent: 0 sacks sent: 0
urgent data pkts: 0 pkts urgent data pkts: 0 pkts
urgent data bytes: 0 bytes urgent data bytes: 0 bytes
mss requested: 1460 bytes mss requested: 1460 bytes
max segm size: 450 bytes max segm size: 1448 bytes
min segm size: 450 bytes min segm size: 806 bytes
avg segm size: 449 bytes avg segm size: 1398 bytes
max win adv: 40544 bytes max win adv: 33304 bytes
min win adv: 5840 bytes min win adv: 33304 bytes
zero win adv: 0 times zero win adv: 0 times
avg win adv: 23174 bytes avg win adv: 33304 bytes
initial window: 450 bytes initial window: 1448 bytes
initial window: 1 pkts initial window: 1 pkts
ttl stream length: 450 bytes ttl stream length: 18182 bytes
missed data: 0 bytes missed data: 0 bytes
truncated data: 420 bytes truncated data: 17792 bytes
truncated packets: 1 pkts truncated packets: 13 pkts
data xmit time: 0.000 secs data xmit time: 0.149 secs
idletime max: 103.7 ms idletime max: 99.9 ms
throughput: 1113 Bps throughput: 44957 Bps

The initial lines of output are similar to the brief output explained in Chapter 3. The following lines indicate that the
hosts involved in the connection and their TCP port numbers are:

host a: elephus.cs.ohiou.edu:59518
host b: a17-112-152-32.apple.com:http
The following lines indicate that the connection was seen to be complete i.e., the connection was traced in its
entirety with the SYN and FIN segments of the connection observed in the dumpfile. The time at which the first and
last packets of the connection were captured is reported, followed by the lifetime of the connection, and the number
of packets seen. Then, the filename currently being processed is listed, followed by the multiple TCP statistics for the
forward (a2b) and the reverse (b2a) directions.
We explain the TCP parameter statistics in the following, for the a2b direction. Similar explanation would hold for the
b2a direction too.

• total packets The total number of packets seen.


• ack pkts sent The total number of ack packets seen (TCP segments seen with the ACK bit set).
• pure acks sent The total number of ack packets seen that were not piggy-backed with data (just the TCP
header and no TCP data payload) and did not have any of the SYN/FIN/RST flags set.
• sack pkts sent The total number of ack packets seen carrying TCP SACK [?] blocks.
• dsack pkts sent The total number of sack packets seen that carried duplicate SACK (D-SACK) [?] blocks.
• max sack blks/ack The maximum number of sack blocks seen in any sack packet.
• unique bytes sent The number of unique bytes sent, i.e., the total bytes of data sent excluding retrans-
mitted bytes and any bytes sent doing window probing.
• actual data pkts The count of all the packets with at least a byte of TCP data payload.
• actual data bytes The total bytes of data seen. Note that this includes bytes from retransmissions /
window probe packets if any.

8 Chapter 4. Detailed Usage


• rexmt data pkts The count of all the packets found to be retransmissions.
• rexmt data bytes The total bytes of data found in the retransmitted packets.
• zwnd probe pkts The count of all the window probe packets seen. (Window probe packets are typically
sent by a sender when the receiver last advertised a zero receive window, to see if the window has opened up
now).
• zwnd probe bytes The total bytes of data sent in the window probe packets.
• outoforder pkts The count of all the packets that were seen to arrive out of order.
• pushed data pkts The count of all the packets seen with the PUSH bit set in the TCP header.
• SYN/FIN pkts sent The count of all the packets seen with the SYN/FIN bits set in the TCP header respec-
tively.
• req 1323 ws/ts If the endpoint requested Window Scaling/Time Stamp options as specified in RFC
1323[?] a ‘Y’ is printed on the respective field. If the option was not requested, an ‘N’ is printed. For ex-
ample, an “N/Y” in this field means that the window-scaling option was not specified, while the Time-stamp
option was specified in the SYN segment.
Note that since Window Scaling option is sent only in SYN packets, this field is meaningful only if the connec-
tion was captured fully in the dumpfile to include the SYN packets.
• adv wind scale The window scaling factor used. Again, this field is valid only if the connection was
captured fully to include the SYN packets. Since the connection would use window scaling if and only if both
sides requested window scaling [?], this field is reset to 0 (even if a window scale was requested in the SYN
packet for this direction), if the SYN packet in the reverse direction did not carry the window scale option.
• req sack If the end-point sent a SACK permitted option in the SYN packet opening the connection, a ‘Y’ is
printed; otherwise ‘N’ is printed.
• sacks sent The total number of ACK packets seen carrying SACK information.
• urgent data pkts The total number of packets with the URG bit turned on in the TCP header.
• urgent data bytes The total bytes of urgent data sent. This field is calculated by summing the urgent
pointer offset values found in packets having the URG bit set in the TCP header.
• mss requested The Maximum Segment Size (MSS) requested as a TCP option in the SYN packet opening
the connection.
• max segm size The maximum segment size observed during the lifetime of the connection.
• min segm size The minimum segment size observed during the lifetime of the connection.
• avg segm size The average segment size observed during the lifetime of the connection calculated as the
value reported in the actual data bytes field divided by the actual data pkts reported.
• max win adv The maximum window advertisement seen. If the connection is using window scaling (both
sides negotiated window scaling during the opening of the connection), this is the maximum window-scaled
advertisement seen in the connection. For a connection using window scaling, both the SYN segments opening
the connection have to be captured in the dumpfile for this and the following window statistics to be accurate.
• min win adv The minimum window advertisement seen. This is the minimum window-scaled advertisement
seen if both sides negotiated window scaling.
• zero win adv The number of times a zero receive window was advertised.

4.1. Detailed Stats 9


• avg win adv The average window advertisement seen, calculated as the sum of all window advertisements
divided by the total number of packets seen. If the connection endpoints negotiated window scaling, this average
is calculated as the sum of all window-scaled advertisements divided by the number of window-scaled packets
seen. Note that in the window-scaled case, the window advertisements in the SYN packets are excluded since
the SYN packets themselves cannot have their window advertisements scaled, as per RFC 1323[?].
• initial window The total number of bytes sent in the initial window i.e., the number of bytes seen in the
initial flight of data before receiving the first ack packet from the other endpoint. Note that the ack packet from
the other endpoint is the first ack acknowledging some data (the ACKs part of the 3-way handshake do not
count), and any retransmitted packets in this stage are excluded.
• initial window The total number of segments (packets) sent in the initial window as explained above.
• ttl stream length The Theoretical Stream Length. This is calculated as the difference between the
sequence numbers of the SYN and FIN packets, giving the length of the data stream seen. Note that this
calculation is aware of sequence space wrap-arounds, and is printed only if the connection was complete (both
the SYN and FIN packets were seen).
• missed data The missed data, calculated as the difference between the ttl stream length and
unique bytes sent. If the connection was not complete, this calculation is invalid and an “NA” (Not
Available) is printed.
• truncated data The truncated data, calculated as the total bytes of data truncated during packet capture.
For example, with tcpdump, the snaplen option can be set to 64 (with -s option) so that just the headers of the
packet (assuming there are no options) are captured, truncating most of the packet data. In an Ethernet with
maximum segment size of 1500 bytes, this would amount to truncated data of 1500 − 64 = 1436bytes for a
packet.
• truncated packets The total number of packets truncated as explained above.
• data xmit time Total data transmit time, calculated as the difference between the times of capture of the
first and last packets carrying non-zero TCP data payload.
• idletime max Maximum idle time, calculated as the maximum time between consecutive packets seen in
the direction.
• throughput The average throughput calculated as the unique bytes sent divided by the elapsed time i.e.,
the value reported in the unique bytes sent field divided by the elapsed time (the time difference
between the capture of the first and last packets in the direction).

4.2 RTT Stats


RTT (Round-Trip Time) statistics are generated when the -r option is specified along with the -l option (Section
4.1). The following fields of output are produced along with the output generated by the -l option.

surya:/home/mani/tcptrace-manual> tcptrace -lr indica.dmp.gz

1 arg remaining, starting with ’indica.dmp.gz’


Ostermann’s tcptrace -- version 6.4.5 -- Fri Jun 13, 2003

153 packets seen, 153 TCP packets traced


elapsed wallclock time: 0:00:00.128422, 1191 pkts/sec analyzed
trace file elapsed time: 0:00:19.092645
TCP connection info:
1 TCP connection traced:
TCP connection 1:

10 Chapter 4. Detailed Usage


host a: 192.168.0.70:32791
host b: webco.ent.ohiou.edu:23
complete conn: yes
first packet: Thu Aug 29 18:54:54.782937 2002
last packet: Thu Aug 29 18:55:13.875583 2002
elapsed time: 0:00:19.092645
total packets: 153
filename: indica.dmp.gz
a->b: b->a:
total packets: 91 total packets: 62
. . . . . .
. . . . . .
throughput: 10 Bps throughput: 94 Bps

RTT samples: 48 RTT samples: 47


RTT min: 74.1 ms RTT min: 0.1 ms
RTT max: 204.0 ms RTT max: 38.8 ms
RTT avg: 108.6 ms RTT avg: 8.1 ms
RTT stdev: 44.2 ms RTT stdev: 14.7 ms

RTT from 3WHS: 75.0 ms RTT from 3WHS: 0.1 ms

RTT full_sz smpls: 1 RTT full_sz smpls: 1


RTT full_sz min: 79.5 ms RTT full_sz min: 0.1 ms
RTT full_sz max: 79.5 ms RTT full_sz max: 0.1 ms
RTT full_sz avg: 79.5 ms RTT full_sz avg: 0.1 ms
RTT full_sz stdev: 0.0 ms RTT full_sz stdev: 0.0 ms

post-loss acks: 0 post-loss acks: 0

For the following 5 RTT statistics, only ACKs for


multiply-transmitted segments (ambiguous ACKs) were
considered. Times are taken from the last instance
of a segment.
ambiguous acks: 1 ambiguous acks: 0
RTT min (last): 76.3 ms RTT min (last): 0.0 ms
RTT max (last): 76.3 ms RTT max (last): 0.0 ms
RTT avg (last): 76.3 ms RTT avg (last): 0.0 ms
RTT sdv (last): 0.0 ms RTT sdv (last): 0.0 ms
segs cum acked: 0 segs cum acked: 0
duplicate acks: 0 duplicate acks: 0
triple dupacks: 0 triple dupacks: 0
max # retrans: 1 max # retrans: 0
min retr time: 380.2 ms min retr time: 0.0 ms
max retr time: 380.2 ms max retr time: 0.0 ms
avg retr time: 380.2 ms avg retr time: 0.0 ms
sdv retr time: 0.0 ms sdv retr time: 0.0 ms

• RTT samples The total number of Round-Trip Time (RTT) samples found. tcptrace is pretty smart about
choosing only valid RTT samples. An RTT sample is found only if an ack packet is received from the other
endpoint for a previously transmitted packet such that the acknowledgment value is 1 greater than the last
sequence number of the packet. Further, it is required that the packet being acknowledged was not retransmitted,
and that no packets that came before it in the sequence space were retransmitted after the packet was transmitted.
Note : The former condition invalidates RTT samples due to the retransmission ambiguity problem, and the
latter condition invalidates RTT samples since it could be the case that the ack packet could be cumulatively
acknowledging the retransmitted packet, and not necessarily ack-ing the packet in question.

4.2. RTT Stats 11


• RTT min The minimum RTT sample seen.
• RTT max The maximum RTT sample seen.
• RTT avg The average value of RTT found, calculated straightforward-ly as the sum of all the RTT values
found divided by the total number of RTT samples.
• RTT stdev The standard deviation of the RTT samples.
• RTT from 3WHS The RTT value calculated from the TCP 3-Way Hand-Shake (connection opening) [?], as-
suming that the SYN packets of the connection were captured.
• RTT full sz smpls The total number of full-size RTT samples, calculated from the RTT samples of full-
size segments. Full-size segments are defined to be the segments of the largest size seen in the connection.
• RTT full sz min The minimum full-size RTT sample.
• RTT full sz max The maximum full-size RTT sample.
• RTT full sz avg The average full-size RTT sample.
• RTT full sz stdev The standard deviation of full-size RTT samples.
• post-loss acks The total number of ack packets received after losses were detected and a retransmission
occurred. More precisely, a post-loss ack is found to occur when an ack packet acknowledges a packet
sent (acknowledgment value in the ack pkt is 1 greater than the packet’s last sequence number), and at least
one packet occurring before the packet acknowledged, was retransmitted later. In other words, the ack packet is
received after we observed a (perceived) loss event and are recovering from it.
• ambiguous acks, RTT min, RTT max, RTT avg, RTT sdvThese fields are printed only if there
was at least one ack received that was ambiguous due to the retransmission ambiguity problem i.e., the segment
being ack-ed was retransmitted and it is impossible to determine if the ack is for the original or the retransmitted
packet. Note that these samples are not considered in the RTT samples explained above. The statistics below
are calculated from the time of capture of the last transmitted instance of the segment.
• ambiguous acks is the total number of such ambiguous acks seen. The following RTT min, RTT max,
RTT avg, RTT sdv fields represent the minimum, maximum, average, and standard deviation respectively
of the RTT samples calculated from ambiguous acks.
• segs cum acked The count of the number of segments that were cumulatively acknowledged and not di-
rectly acknowledged.
• duplicate acks The total number of duplicate acknowledgments received. An ack packet is found to be a
duplicate ack based on this definition used by 4.4 BSD Lite TCP Stack [?] :
o The ack packet has the biggest ACK (acknowledgment number) ever seen.
o The ack should be pure (carry zero tcp data payload).
o The advertised window carried in the ack packet should not change from the last window advertisement.
o There must be some outstanding data.

Note : older versions of tcptrace (until version 6.4.2) used a legacy algorithm using just the first condition
amongst the four listed above, to treat an ack as duplicate ack. This older behavior may be emulated (if necessary
at all) with the --turn off BSD dupack option.
• triple dupacks The total number of triple duplicate acknowledgments received (three duplicate acknowl-
edgments acknowledging the same segment), a condition commonly used to trigger the fast-retransmit/fast-
recovery phase of TCP.
• max # retrans The maximum number of retransmissions seen for any segment during the lifetime of the
connection.

12 Chapter 4. Detailed Usage


• min retr time The minimum time seen between any two (re)transmissions of a segment amongst all the
retransmissions seen.
• max retr time The maximum time seen between any two (re)transmissions of a segment.
• avg retr time The average time seen between any two (re)transmissions of a segment calculated from all
the retransmissions.
• sdv retr time The standard deviation of the retransmission-time samples obtained from all the retransmis-
sions.

The raw RTT samples found can also be dumped into data files with the -Z option as in

tcptrace -Z file.dmp
This generates files of the form a2b rttraw.dat and b2a rttraw.dat (for both directions of the first TCP connection
traced), c2d rttraw.dat and d2c rttraw.dat (for the second TCP connection traced) etc. in the working directory. Each
of the datafiles contain lines of the form :

seq# rtt
where seq# is the sequence number of the first byte of the segment being acknowledged (by the ack packet that
contributed this RTT sample) and rtt is the RTT value in milli-seconds of the sample. Note that only valid RTT
samples (as counted in the RTT Samples field listed above) are dumped.

4.3 CWND Stats


tcptrace reports statistics on the estimated congestion window with the -W option when used in conjunction with
the -l option. Since there is no direct way to determine the congestion window at the TCP sender, the outstanding
unacknowledged data is used to estimate the congestion window. The 4 new statistics produced by the -W option in
addition to the detailed statistics reported due to the -l option, are explained below.

surya:/home/mani/tcptrace-manual> tcptrace -lW malus.dmp.gz

1 arg remaining, starting with ’malus.dmp.gz’


Ostermann’s tcptrace -- version 6.4.6 -- Tue Jul 1, 2003

32 packets seen, 32 TCP packets traced


elapsed wallclock time: 0:00:00.026658, 1200 pkts/sec analyzed
trace file elapsed time: 0:00:00.404427
TCP connection info:
1 TCP connection traced:
TCP connection 1:
host a: elephus.cs.ohiou.edu:59518
host b: A17-112-152-32.apple.com:80
complete conn: yes
first packet: Thu Jul 10 19:12:54.914101 2003
last packet: Thu Jul 10 19:12:55.318528 2003
elapsed time: 0:00:00.404427
total packets: 32
filename: malus.dmp.gz
a->b: b->a:
total packets: 16 total packets: 16
. . . . . .

4.3. CWND Stats 13


. . . . . .
avg win adv: 22091 bytes avg win adv: 33304 bytes

max owin: 451 bytes max owin: 1449 bytes


min non-zero owin: 1 bytes min non-zero owin: 1 bytes
avg owin: 31 bytes avg owin: 1213 bytes
wavg owin: 113 bytes wavg owin: 682 bytes

initial window: 450 bytes initial window: 1448 bytes


. . . . . .
. . . . . .
throughput: 1113 Bps throughput: 44957 Bps

• max owin The maximum outstanding unacknowledged data (in bytes) seen at any point in time in the lifetime
of the connection.
• min non-zero owin The minimum (non-zero) outstanding unacknowledged data (in bytes) seen.
• avg owin The average outstanding unacknowledged data (in bytes), calculated from the sum of all the out-
standing data byte samples (in bytes) divided by the total number of samples.
• wavg owin The weighted average outstanding unacknowledged data seen. For example, if the outstanding
data (odata) was 500 bytes for the first 0.1 seconds, 1000 bytes for the next 1 second, and 2000 bytes for the
last 0.1 seconds of a connection that lasted 1.2 seconds, wavg owin= ((500 x 0.1) + (1000 x 1) + (2000 x
0.1)) / 1.2 = 1041.67 bytes an estimate closer to 1000 bytes which was the outstanding data for the most of
the lifetime of the connection. Note that the straight-forward average reported in avg owin would have been
(500+1000+2000)/1.2 = 2916.67 bytes, a value less indicative of the outstanding data observed during most of
the connection’s lifetime.

14 Chapter 4. Detailed Usage


CHAPTER

FIVE

Graphing

tcptrace can generate six different types of graphs illustrating various parameters of a TCP connection. These graphs
can be viewed with Tim Shepard’s xplot program or with the Java version of the same program called jPlot from
http://www.tcptrace.org/jPlot developed by Avinash Lakhiani.
The graphs and the options for tcptrace that generate them, are explained below. tcptrace leaves *.xpl data files in the
working directory when the graphing options are given, and the data files can be viewed with the xplot program as in

xplot a2b_tsg.xpl
tcptrace uses the same naming scheme observed in previous chapters to generate the graphs. The files a2b *.xpl
and b2a *.xpl are the graphing data files for both the directions of traffic of the first connection, the c2d *.xpl
and d2c *.xpl files are for the second connection, and so on.

5.1 Time Sequence Graph


Time Sequence graphs show the general activity and events that happen during the lifetime of a connection, and can
be generated with the -S option. These graphs are named as X2Y tsg.xpl. A sample Time Sequence graph is shown
in Figure 5.1.
The Y-axis represents sequence number space and the X-axis represents time, and the slope of this curve gives the
throughput over time. A section of this graph (zoomed in with xplot) is shown in Figure 5.2 illustrating the following
features.

• Green Line keeps track of the ACK values received from the other endpoint.
• Yellow Line tracks the receive window advertised from the other endpoint. (It is drawn at the sequence number
value corresponding to the sum of the acknowledgment number and the receive window advertised from the last
ACK packet received.)
• Little Green Ticks track the duplicate ACKs received.
• Little Yellow Ticks track the window advertisements that were the same as the last advertisement.
• White Arrows represent segments sent. The up and down arrows represent the sequence numbers of the last
and first bytes of the segment respectively.
• Red Arrows (R) represent retransmitted segments with the up and down arrows similarly representing the
sequence numbers of the last and first bytes of the segment.

Further zooming into the beginning of the connection with xplot we find Figure 5.3.
Here, the SYN marks the sequence number and the time when a SYN packet was sent.

15
Figure 5.1: Time Sequence Graph #1

16 Chapter 5. Graphing
Figure 5.2: Time Sequence Graph #2

5.1. Time Sequence Graph 17


Figure 5.3: Time Sequence Graph #3

18 Chapter 5. Graphing
The graph shown in Figure 5.4 is a section of a TCP connection being closed.

Figure 5.4: Time Sequence Graph #4

Here,

• FIN marks a FIN segment sent in the direction.


• RST IN, RST OUT: When a RST segment is sent, a RST OUT is marked in the graph, and a RST IN is
marked in the Time Sequence graph of the opposite direction of the connection.
• Little crosses (x) These are segments sent with zero TCP data payload (the down and up arrows of the segment
coincide, giving rise to a cross).

• SACK [?, ?] blocks found in ACK packets are represented as purple lines with an S on top as shown in Figure
5.5.
• PUSH segments, i.e., TCP segments sent with the PUSH flag set are represented with a Diamond in place of the
up arrow as shown in Figure 5.6.

5.1. Time Sequence Graph 19


Figure 5.5: SACK blocks

20 Chapter 5. Graphing
Figure 5.6: PUSH segments

5.1. Time Sequence Graph 21


• URGENT segments, i.e., TCP segments carrying URGENT data with the URG flag set in the TCP header are
represented with a red U on top of the segment. This is shown in Figure 5.7.

Figure 5.7: URGENT segments

• Window Probing happens when the receiver advertises a window of 0 (typically happens when the application
goes dormant and TCP holds on to the allocated window full of received data, waiting to be picked up). A
Time-Sequence graph illustrating this is shown in Figure 5.8.
The Z labels in the graph represent a window advertisement of 0 bytes received from the other endpoint. The
subsequent P labels indicate the probe packets sent by the sending endpoint to see if the window has opened up
yet.

The following other symbols also occur in Time Sequence graphs :

• O represents packets received out of order.

22 Chapter 5. Graphing
Figure 5.8: Window Probing

5.1. Time Sequence Graph 23


• HD represent Hardware Duplicates. Hardware Duplicates correspond to link layer retransmissions found when
a duplicate packet with same IPv4 identification number and TCP sequence number as a previously observed
packet is seen.
• 3 indicates that the received ack packet was the triple duplicate ack, commonly used as the threshold to trigger
the TCP fast retransmit/recovery algorithm.
• CWR / CE track Explicit Congestion Notification [?] messages received. CWR indicates that the Congestion
Window Reduced flag was set in the TCP header of the packet, while the CE flag indicates that the Congestion
Experienced code-point was found in the IP header of the packet.

5.2 Throughput Graph


Throughput graphs (named X2Y tput.xpl) are generated with the -T option. A sample throughput graph is shown in
Figure 5.9.
The graph has throughput in bytes/second on the Y-axis and time on the X-axis.

• Yellow Dots represent instantaneous throughput, defined as the size of the segment seen divided by the time
since the last segment was seen (in this direction).
• Blue Line tracks the average throughput of the connection up to that point in the life time of the connection
(total bytes seen / total seconds so far).
• Red Line tracks the throughput seen from the last few samples, calculated as the average of N previous yellow
dots. By default the line tracks the past 10 samples (N=10). However it can be changed with the -AN option.
For example giving -A5 along with the -T option calculates the throughput from the past 5 yellow dots to draw
the line.

Due to clock granularity, there tends to be a lot of banding of the dots. If you find the yellow dots annoying, you may
turn them off with the -y option.

5.3 RTT Graph


RTT (Round Trip Time) graphs (named X2Y rtt.xpl) are generated with the -R option. A sample RTT graph is shown
in Figure 5.10.
The Y-axis represents RTT in milli-seconds and the X-axis represents time. The yellow dots represent RTT samples
calculated from non-retransmitted segments, and the red line just connects the dots.

5.4 Outstanding Data Graph


Outstanding Data graphs (named X2Y owin.xpl) are generated with the -N option. A sample is shown in Figure 5.11.
The Y-axis represents the Outstanding Data in bytes and the X-axis represents time. The idea behind these graphs
to estimate the congestion window at the sender. Since this cannot be determined accurately, we use the outstanding
unacknowledged data as an estimate.

• Red Line represents instantaneous outstanding data samples at various points in the lifetime of the connection.
• Blue Line tracks the average outstanding data up to that point.
• Green Line tracks the weighted average of outstanding data up to that point, and is as explained in the calcula-
tion of the wavg owin field in Section 4.3.

24 Chapter 5. Graphing
Figure 5.9: Throughput Graph

5.4. Outstanding Data Graph 25


Figure 5.10: RTT Graph

26 Chapter 5. Graphing
Figure 5.11: Outstanding Data Graph

5.4. Outstanding Data Graph 27


5.5 Segment Size Graph
Segment size graphs (named X2Y ssize.xpl) are generated with the -F option. A sample segment size graph is shown
in Figure 5.12.

Figure 5.12: Segment Size

The Y-axis represents segment size in bytes and the X-axis represents time.

• Red Line represents the instantaneous segment size samples.


• Blue Line represents the average segment size seen up to that point.

5.6 Time-Line Graph


The goal of the Time-Line graphs is to generate graphs similar to the pretty graphs found in the book “TCP/IP Illus-
trated Volume I” by W. Richard Stevens [?], illustrating the activities of connections. The graphs can be generated
with the -L option and generates graphs named as X Y tline.xpl

28 Chapter 5. Graphing
The Time-Line graphs are still EXPERIMENTAL and are under development. The fundamental problem with gener-
ating these graphs is that the time values for the segments arriving/leaving are available only from the end where the
traffic was captured, while the time values of when the packets arrived or left at the other end have to be estimated
with some heuristic. Doing this right tends to be a hard problem taking care of conditions like retransmits, timeouts
etc. The current heuristic is a simple one of adding/subtracting 1/3rd of the rtt.
This graph provides a pictorial view of the segments being transmitted in either direction, over the duration of the
connection. The Y-axis shows increasing time going from the top to bottom of the graph. The X-axis shows the
segments being transmitted between the 2 hosts communicating. As you zoom in with xplot, more and more details
will become visible. Here is an example of a time line graph:
Following is a closeup (zoomed in with xplot):
The following features can be seen in the graph

Axis X-axis : segments being transmitted in either direction (zoom in to see the arrow heads for the correct direction)
Y-axis : running time of the connection (TOP to BOTTOM, ignoring the negative sign)
Graph Features Green Lines The green lines show the segments traveling in the direction a-¿b
Yellow Lines The yellow lines show the segments traveling in the direction b-¿a
Labels The labels alongside the segments have the following format:
TCP Flags (only if set), sequence number from:sequence number to(difference, bytes transmitted), ac-
knowledgment sequence number, advertised window, retransmit indicator (“R”), hardware duplicate in-
dicator (“HD”)
The sequence number for the first segment in either direction is absolute, while the rest are relative to the
first segment.

5.7 Miscellany
If you want to generate all the graphs, use the -G option. If you want monochrome plots, use the -M option. For the
sake of completeness, the -C option produces color plots (which of course is the default behavior).
In all the above graphs, the X-axis represents the actual time of the connection. If you want relative time with time
beginning at 0, use the -zx option while generating the graphs. The Y-axis can also be made to begin from 0 with
the -zy option. This is generally useful in Time Sequence graphs, where the sequence offset rather than the actual
sequence number values may be desired. Figure 5.4 shows a section of a Time Sequence graph generated with -zxy
option, causing both the axes to begin from 0.
If you would rather have the graphs generated be placed in a separate directory, and not clutter your working directory,
use the --output dir option. For example,

tcptrace -G --output_dir=graphs indica.dmp


would leave all the graphs in the graphs directory.
Now, if you are using the same graphs directory to store the graphs generated from another file mangifera.dmp,
the old *.xpl files from indica.dmp may get over-written by the new *.xpl files. You may wish to use the --
output prefix option to fix this. For example,

tcptrace -G --output_dir=graphs --output_prefix=mangifera_ mangifera.dmp


would generate files of the form mangifera a2b tsg.xpl in the graphs directory.
tcptrace can also call xplot internally to pop-up the graphs generated at the end of processing the dumpfile(s) with the
--xplot all files option. For example,

5.7. Miscellany 29
Figure 5.13: Time-Line Graph #1

30 Chapter 5. Graphing
Figure 5.14: Time-Line Graph #2

5.7. Miscellany 31
tcptrace -S --xplot_all_files elephus.dmp
This would pop-up all the Time Sequence graphs generated for the dumpfile elephus.dmp, which could be a lot
depending on the number of connections found. This option is meant for use when there are a few connections in
the dumpfile, unless you want your screen to be filled with xplot graphs. While using this option, any options that
need to be given to xplot for drawing the graphs can also be specified with the ‘‘--xplot args=. . .’’
option, where the ‘‘. . .’’ is the place-holder for any xplot options to be set, while calling xplot internally
from tcptrace . If multiple options are being passed to xplot, it is recommended that the entire option be enclosed in
double quotes as shown above, to protect it from being interpreted as multiple command-line arguments by your Shell.
A user-defined prefix may be added to the title of the xplot graphs if necessary, by passing the prefix in the --
xplot title prefix=’’...’’ option.

32 Chapter 5. Graphing
CHAPTER

SIX

Filtering Connections

It is commonly the case that the dumpfile captured for analysis by tcptrace has much more connections than the ones
you may be interested in. In such cases, it could be useful to pick and choose the connections of interest from the
dumpfile, and perform detailed analysis on them alone. This chapter describes how to do such connection filtering.

6.1 Basic Filtering


The -o option can be used to only look at certain connections. For example 8 TCP connections were traced in the file
rexmit.dmp.gz :

Beluga:/Users/mani/dmpfiles> tcptrace -n rexmit.dmp.gz


1 arg remaining, starting with ’rexmit.dmp.gz’
Ostermann’s tcptrace -- version 6.4.6 -- Tue Jul 1, 2003

6401 packets seen, 6401 TCP packets traced


elapsed wallclock time: 0:00:00.102161, 62656 pkts/sec analyzed
trace file elapsed time: 0:20:57.758299
TCP connection info:
1: 132.235.67.82:1321 - 132.235.67.36:9080 (a2b) 178> 113< (complete)
2: 132.235.67.82:3396 - 132.235.67.36:9119 (c2d) 1358> 1311< (complete)
3: 132.235.67.82:2525 - 132.235.67.36:9080 (e2f) 60> 18<
4: 132.235.67.82:2666 - 132.235.67.36:9119 (g2h) 910> 872< (complete) (reset)
5: 132.235.67.82:3299 - 132.235.67.36:9119 (i2j) 722> 676< (complete) (reset)
6: 132.235.67.82:3584 - 132.235.67.36:9080 (k2l) 56> 16<
7: 132.235.67.82:3640 - 132.235.67.36:9080 (m2n) 48> 14<
8: 132.235.67.82:4095 - 132.235.67.36:9080 (o2p) 40> 9<
Using the -o option with 3,5,7 as shown below, filters out only the 3rd, 5th, and 7th connections out.

Beluga:/Users/mani/dmpfiles> tcptrace -n -o3,5,7 rexmit.dmp.gz


1 arg remaining, starting with ’rexmit.dmp.gz’
Ostermann’s tcptrace -- version 6.4.6 -- Tue Jul 1, 2003

6401 packets seen, 6401 TCP packets traced


elapsed wallclock time: 0:00:00.086056, 74381 pkts/sec analyzed
trace file elapsed time: 0:20:57.758299
TCP connection info:
3: 132.235.67.82:2525 - 132.235.67.36:9080 (e2f) 60> 18<
5: 132.235.67.82:3299 - 132.235.67.36:9119 (i2j) 722> 676< (complete) (reset)
7: 132.235.67.82:3640 - 132.235.67.36:9080 (m2n) 48> 14<

33
You may use the -l option (Section 4.1) for example, to generate the detailed statistics of only these connections as
in

tcptrace -n -o3,5,7 -l rexmit.dmp.gz


Similarly graphs can be generated for the connections you are interested in alone for example, by combining both
the -o and -G options. The following example illustrates how you could specify a range of connections with the -o
option to get only the connections 1-3, 5, 7-8 from the dumpfile.

Beluga:/Users/mani/dmpfiles> tcptrace -n -o1-3,5,7-8 rexmit.dmp.gz


1 arg remaining, starting with ’rexmit.dmp.gz’
Ostermann’s tcptrace -- version 6.4.6 -- Tue Jul 1, 2003

6401 packets seen, 6401 TCP packets traced


elapsed wallclock time: 0:00:00.092103, 69498 pkts/sec analyzed
trace file elapsed time: 0:20:57.758299
TCP connection info:
1: 132.235.67.82:1321 - 132.235.67.36:9080 (a2b) 178> 113< (complete)
2: 132.235.67.82:3396 - 132.235.67.36:9119 (c2d) 1358> 1311< (complete)
3: 132.235.67.82:2525 - 132.235.67.36:9080 (e2f) 60> 18<
5: 132.235.67.82:3299 - 132.235.67.36:9119 (i2j) 722> 676< (complete) (reset)
7: 132.235.67.82:3640 - 132.235.67.36:9080 (m2n) 48> 14<
8: 132.235.67.82:4095 - 132.235.67.36:9080 (o2p) 40> 9<
You may also store the connection numbers in a data file conn.dat for example and pass it to the -o option. The -o
option opens and reads from a file if the character following the -o is not a numeral. For example, when the conn.dat
file had just the line

1-3, 6-8
it causes connections 1-3 and 6-8 alone to be filtered out.

Beluga:/Users/mani/dmpfiles> tcptrace -n -oconn.dat rexmit.dmp.gz


1 arg remaining, starting with ’rexmit.dmp.gz’
Ostermann’s tcptrace -- version 6.4.6 -- Tue Jul 1, 2003

6401 packets seen, 6401 TCP packets traced


elapsed wallclock time: 0:00:00.091752, 69764 pkts/sec analyzed
trace file elapsed time: 0:20:57.758299
TCP connection info:
1: 132.235.67.82:1321 - 132.235.67.36:9080 (a2b) 178> 113< (complete)
2: 132.235.67.82:3396 - 132.235.67.36:9119 (c2d) 1358> 1311< (complete)
3: 132.235.67.82:2525 - 132.235.67.36:9080 (e2f) 60> 18<
6: 132.235.67.82:3584 - 132.235.67.36:9080 (k2l) 56> 16<
7: 132.235.67.82:3640 - 132.235.67.36:9080 (m2n) 48> 14<
8: 132.235.67.82:4095 - 132.235.67.36:9080 (o2p) 40> 9<
Sometimes it could be useful to save only the filtered connections into a new dumpfile. This can be done with the -O
option.
The following example saves just the connections 4-6 into the file filt rexmit.dmp.

Beluga:/Users/mani/dmpfiles> tcptrace -n -o4-6 -Ofilt_rexmit.dmp rexmit.dmp.gz


1 arg remaining, starting with ’rexmit.dmp.gz’
Ostermann’s tcptrace -- version 6.4.6 -- Tue Jul 1, 2003

6401 packets seen, 6401 TCP packets traced

34 Chapter 6. Filtering Connections


elapsed wallclock time: 0:00:00.102007, 62750 pkts/sec analyzed
trace file elapsed time: 0:20:57.758299
TCP connection info:
4: 132.235.67.82:2666 - 132.235.67.36:9119 (g2h) 910> 872< (complete) (reset)
5: 132.235.67.82:3299 - 132.235.67.36:9119 (i2j) 722> 676< (complete) (reset)
6: 132.235.67.82:3584 - 132.235.67.36:9080 (k2l) 56> 16<
Ignoring certain connections alone can be done too, with the -i option. The usage of the -i option is very similar to
the -o option.
For example,

tcptrace -n -i1 rexmit.dmp.gz


ignores the first connection alone, and

tcptrace -n -i1,3-5 rexmit.dmp.gz


ignores connections 1, 3, 4, and 5. A data file containing a list of connection numbers to ignore can also be given in
the -i option (as shown above for the -o option).
The -c option is useful if you are interested in looking at only complete connections i.e., the connections for which
both the SYN and FIN segments opening and closing the connection were seen.
Finally, for some reason if you are interested in looking only at the first 200 packets found in the file for example, you
may use the -E option as in

tcptrace -n -E200 rexmit.dmp.gz


You may also begin at the 300th packet in the file for example, with the -B option as in

tcptrace -n -B300 rexmit.dmp.gz


Using both the options, lets you look at a range of packets as they occurred in the dumpfile, as in

tcptrace -n -B100 -E200 rexmit.dmp.gz

6.2 Advanced Filtering


The -f option can be used to perform more sophisticated filtering of connections, based on various parameters. The
supported filter variables are listed below :

Beluga:/Users/mani/tcptrace-manual> tcptrace -hfilter


Filter Variables:
variable name type description
----------------- -------- -----------------------
hostname STRING FQDN host name (unless -n)
portname STRING service name of the port (unless -n)
port UNSIGNED port NUMBER
mss SIGNED maximum segment size
f1323_ws BOOL 1323 window scaling requested
f1323_ts BOOL 1323 time stampts requested
fsack_req BOOL SACKs requested
window_scale BOOL window scale factor

6.2. Advanced Filtering 35


bad_behavior BOOL bad TCP behavior
data_bytes UNSIGNED bytes of data
data_segs UNSIGNED segments of data
data_segs_push UNSIGNED segments with PUSH set
unique_bytes UNSIGNED non-retransmitted bytes
rexmit_bytes UNSIGNED retransmitted bytes
rexmit_segs UNSIGNED segments w/ retransmitted data
ack_segs UNSIGNED segments containing ACK
pureack_segs UNSIGNED segments containing PURE ACK (no data/syn/fin/reset)
win_max UNSIGNED MAX window advertisement
win_min UNSIGNED MIN window advertisement
win_zero_ct UNSIGNED number of ZERO windows advertised
min_seq UNSIGNED smallest sequence number
max_seq UNSIGNED largest sequence number
num_sacks UNSIGNED number of ACKs carrying SACKs
max_sacks UNSIGNED most SACK blocks in a single ACK
segs UNSIGNED total segments
packets UNSIGNED total segments
syn_count UNSIGNED SYNs sent
fin_count UNSIGNED FINs sent
reset_count UNSIGNED RESETs sent
min_seg_size UNSIGNED smallest amount of data in a segment (not 0)
max_seg_size UNSIGNED largest amount of data in a segment
out_order_segs UNSIGNED out of order segments
sacks_sent UNSIGNED SACKs sent
ipv6_segs UNSIGNED number of IPv6 segments sent
max_idle UNSIGNED maximum idle time (usecs)
num_hw_dups UNSIGNED number of hardware-level duplicates
initwin_bytes UNSIGNED number of bytes in initial window
initwin_segs UNSIGNED number of segments in initial window
rtt_min UNSIGNED MIN round trip time (usecs)
rtt_max UNSIGNED MAX round trip time (usecs)
rtt_count UNSIGNED number of RTT samples
rtt_min_last UNSIGNED MIN round trip time (usecs) (from last rexmit)
rtt_max_last UNSIGNED MAX round trip time (usecs) (from last rexmit)
rtt_count_last UNSIGNED number of RTT samples (from last rexmit)
rtt_amback UNSIGNED number of ambiguous ACKs
rtt_cumack UNSIGNED number of cumulative ACKs
rtt_unkack UNSIGNED number of unknown ACKs
rtt_dupack UNSIGNED number of duplicate ACKs
rtt_nosample UNSIGNED ACKs that generate no valid RTT sample
rtt_triple_dupack UNSIGNED number of triple duplicate ACKs (fast rexmit)
retr_max UNSIGNED MAX rexmits of a single segment
retr_min_tm UNSIGNED MIN time until rexmit (usecs)
retr_max_tm UNSIGNED MAX time until rexmit (usecs)
trunc_bytes UNSIGNED number of bytes not in the file
trunc_segs UNSIGNED number of segments not in the file
num_zwnd_probes UNSIGNED number of zero window probes
zwnd_probe_bytes UNSIGNED number of window probe bytes
urg_data_pkts UNSIGNED Number of packets with URGENT bit set
urg_data_bytes UNSIGNED Number of bytes of urgent data
hostaddr IPADDR IP Address (v4 or v6 in standard textual notation
thruput UNSIGNED thruput (bytes/sec)
All of the variables listed above can be used for filtering purposes.
For example, consider the file tigris.dmp.gz having the following two connections:

Beluga:/Users/mani> tcptrace tigris.dmp.gz

36 Chapter 6. Filtering Connections


. . .
TCP connection info:
1: pride.cs.ohiou.edu:54735 - elephus.cs.ohiou.edu:ssh (a2b) 30> 30< (complete)
2: pride.cs.ohiou.edu:54736 - a17-112-152-32.apple.com:http (c2d) 12> 15< (complete)
The filter variable segs can be used to filter out connections having a specified amount of segments in either direction
as shown below.

Beluga:/Users/mani> tcptrace -f’segs>=30’ tigris.dmp.gz


Output filter: ((c_segs>=30)OR(s_segs>=30))
1 arg remaining, starting with ’tigris.dmp.gz’
. . .
TCP connection info:
1: pride.cs.ohiou.edu:54735 - elephus.cs.ohiou.edu:ssh (a2b) 30> 30< (complete)
Note the Output filter line in the above example. The term c segs stands for the client segs (client2server
direction) and s segs stands for the server segs (server2client direction). We filter out only those connections that had
at least 30 or more segments seen in either direction. You may specify the segments in the server2client direction alone
as in :

Beluga:/Users/mani> tcptrace -f’s_segs==15’ tigris.dmp.gz


Output filter: (s_segs==15)
. . .
TCP connection info:
2: pride.cs.ohiou.edu:54736 - a17-112-152-32.apple.com:http (c2d) 12> 15< (complete)
The “c ” and “s ” prefixes can be applied analogously for all the filter variables cited above. The prefix “b ”
meaning “both” can be applied to the variables if you want the filter to be applied to both directions. For the sake of
completeness, the prefix “e ” meaning “either” is also supported, requiring the filter variable to be applied to either
of the directions (which is of course the default case).
Boolean variables listed above can be used as flags as in

tcptrace -f’f1323_ws’ file.dmp


to filter out only those connections that had window scaling requested in their SYN segments.
The constant value to which the STRING type variables (hostname/portname) are matched need to be enclosed in
double quotes. The following example illustrates the case when we are filtering out connections for the host ele-
phus.cs.ohiou.edu and port ssh.
Beluga:/Users/mani> tcptrace -f’hostname=="elephus.cs.ohiou.edu" and portname=="ssh"’
tigris.dmp.gz
Output filter: (((c_hostname==elephus.cs.ohiou.edu)OR
(s_hostname==elephus.cs.ohiou.edu))AND((c_portname==ssh)OR(s_portname==ssh)))
. . .
TCP connection info:
1: pride.cs.ohiou.edu:54735 - elephus.cs.ohiou.edu:ssh (a2b) 30> 30< (complete)
Note that as in the example above, commonly used boolean operators AND, OR, NOT and their common synonyms
(-a, -o, &&, ——, !) can be used to combine boolean expressions. You may also use parenthesis if you are not sure of
the precedence of operators. Arithmetic operators (+, -, *, /) with their normal precedence and relational operators ( ¡,
¿, =, !=, ¡=, ¿= ) can be applied to SIGNED/UNSIGNED variables. For example, the following are valid :

tcptrace -f‘(c_segs+10) < s_segs’ file.dmp


tcptrace -f‘b_segs>10 && thruput>10000’ file.dmp
The connection numbers that passed the filtering criteria specified in the -f option are stored in a file named PF in
the working directory. Note that, if you are graphing along with the -f option with say the -G option, graphs will be

6.2. Advanced Filtering 37


generated for all the connections and not just the filtered ones. You might want to filter first with the -f option and
graph the filtered connections with the PF file later, as in :

tcptrace -oPF -G file.dmp

38 Chapter 6. Filtering Connections


CHAPTER

SEVEN

Extended Options

This chapter describes the extended options supported. These options generally offer fine-grained control of the
behavior of tcptrace , and in most cases are useful if you want to turn off the default behavior. The extended options
are used as in ---xyzblah. For every such option, there exists a ---noxyzblah that turns off the behavior
offered by the ---xyzblah option. Further, you may use just the prefix of the option, say ---xyzbl, as long as it
is unambiguous amongst all the extended options.
Note that the options explained below are labeled DEFAULT if it is the default behavior, meaning that the option
comes for free and you may use the ---no... version of the option if you need to turn it off.

7.1 General
• —res addr (DEFAULT) Resolve IP addresses to their DNS names. You may use the —nores addr to turn it
off i.e., to not resolve IP addresses.
• —res port (DEFAULT) Resolve port numbers to their service names. For example, print http for TCP port
80. Note that the -n option is equivalent to giving both the —nores addr and —nores port options.
• —checksum This option turns on checking of IP and TCP/UDP checksums. A summary is printed at the end
of the analysis, indicating the number of packets with bad IP and TCP/UDP checksums.
• —check hwdups (DEFAULT) Check for hardware duplicates i.e., duplicate IP packets with the same IPv4
identification number and TCP sequence number as a previously seen packet. Note that if turned off with the
—nocheck hwdups option, such hardware duplicates may be counted as retransmissions.
• —ns hdrs When used while processing ns2style dumpfiles, this option tells tcptrace that ns had the use-
Headers flag set to TRUE while generating the dumpfile.
• —dupack3 data This option is meaningful only if given along with the —turn off BSD dupack option
(refer to duplicate acks in Section 4.2) to turn on the legacy algorithm used by tcptrace to determine triple
duplicate acks. This option lets the third duplicate ack contain data with the legacy algorithm.
• —endpoint reuse interval=S This option can be used to change the default idle-time of 4 minutes after which
activity in the same endpoint tuple (source IP, Port; destination IP, Port) is perceived as a new connection, to S
seconds.
Though it is pretty rare to find two hosts reusing their same endpoints for a new connection between them, it has
been found that dumb devices like certain old printers tend to reuse their TCP port numbers pretty often. If you
run into such problems, you may use this option to change the default idle-time after which activity seen in the
same endpoints can be perceived as a new connection.

39
7.2 Graphing Control
The following options give fine-grained control over the graphs generated by tcptrace . You probably want to use
the --no... versions of these options if you want to turn off the behavior available by default. Also note that
unambiguous prefixes of these options work too.

• —showtitle (DEFAULT) Show the title in xplot graphs.

The following options control the appearance of various features in Time Sequence Graphs 5.1.

• —showzerolensegs (DEFAULT) Show the TCP segments carrying no data (segments that appear as white
crosses).
• —showdupack3 (DEFAULT) Show triple duplicate acks with segment labeled 3.
• —showsacks (DEFAULT) Show the purple colored SACK segments.
• —showrexmit (DEFAULT) Show the retransmissions (red segments labeled R).
• —showoutorder (DEFAULT) Show the out-of-order segments (segments labeled O).
• —showzerowindow (DEFAULT) Show the zero-window advertisements (segments labeled Z).
• —showzwndprobes (DEFAULT) Show the window-probe packets that normally follow the zero-window ad-
vertisements (segments labeled P).
• —showurg (DEFAULT) Show the segments with the TCP Urgent (URG) flag set with a U.
• —showrttdongles Show RTT Dongles on interesting acks as explained below. Note that, unlike other options
this is not turned on by default.
An ack is plotted with a RED diamond head if the ack is ambiguous due to the fact that the segment being
acknowledged was retransmitted. This is illustrated in Figure 7.1.
Notice that the ack packet that causes the green line to go up towards the right-hand end of the graph has a RED
diamond nailed on it. As can be seen in the graph, the segment that is being acknowledged by the ack packet
had been retransmitted.
An ack packet is plotted with a BLUE diamond head if the ack is ambiguous due to the fact that one of the
segments being cumulatively acknowledged by it was retransmitted. This is illustrated in Figure 7.2.
If you look closely at towards the right end of the Figure, you may notice that the green line has a blue diamond
head on the top. This is due to the fact that a segment being cumulatively acknowledged by this ack had been
retransmitted.

7.3 Warning Control


This section describes the options that control the printing of warning messages on various events. These options are
turned off by default and you need to turn them on to be notified. You may also use the -w option to turn on all of the
following options.

• —warn ooo Warn if packet capture timestamps are found to be out of order in the dumpfile. For example,
if the dumpfile is of tcpdump style, this option would cause a warning message if the PCAP timestamps of
successive packets were found decreasing.

40 Chapter 7. Extended Options


Figure 7.1: RTT Dongle (RED)

7.3. Warning Control 41


Figure 7.2: RTT Dongle (BLUE)

42 Chapter 7. Extended Options


• —warn printtrunc Warn if a packet captured was found too short to analyze i.e., if either the basic TCP
header(20 bytes) for TCP packets or the UDP header (8 bytes) for UDP packets was not fully captured. Note
that, this warning message typically means that the packet capture was not done requesting enough of every
packet to be captured. With tcpdump for example, this can be fixed with a suitable value to the -s snaplen
option.
• —warn printbadmbz (Warn Bad Must Be Zero) Prints a warning message if any of the 4 least significant bits
in the 13th byte of the header (that are reserved and expected to be zeroed) are found to be non zero.
• —warn printhwdups Warn if hardware duplicates (that commonly indicate link-level retransmissions) were
found for IPv4 packets. Hardware duplicates are defined to be the IPv4 packets with the same TCP sequence
number and the 16-bit IPv4 identification number of a previously seen packet.
• —warn printbadcsum This option needs to be given along with the --checksum option, and prints the
packet numbers of the packets in the dumpfile that had bad IP and TCP/UDP checksums. The following example
illustrates this :

alakhian@spider:% tcptrace --warn_printbadcsum --checksum input/bad_tcp_checksum.dmp.gz


packet 1: bad TCP checksum
1 arg remaining, starting with ’input/bad_tcp_checksum.dmp.gz’
Ostermann’s tcptrace -- version 6.2.6 -- Thu Nov 14, 2002

10 packets seen, 9 TCP packets traced


elapsed wallclock time: 0:00:00.057058, 175 pkts/sec analyzed
trace file elapsed time: 0:00:00.012379
bad IP checksums: 0
bad TCP checksums: 1
TCP connection info:
1: analex093.lerc.nasa.gov:2270 - chipper.lerc.nasa.gov:139 (a2b) 3> 6<

• —warn printbad syn fin seq Prints a warning if the SYN or FIN segments were retransmitted with a dif-
ferent sequence number from their original transmissions.

7.3. Warning Control 43


44
CHAPTER

EIGHT

Miscellany

This chapter details various miscellaneous stuff that can be done with tcptrace .

8.1 UDP Analysis


tcptrace analyzes UDP [?] traffic minimally with the -u option. The following example illustrates the same :

Beluga:/Users/mani/tcptrace-manual> tcptrace -n -u dmpfiles/udp.dmp.gz


1 arg remaining, starting with ’dmpfiles/udp.dmp.gz’
Ostermann’s tcptrace -- version 6.4.6 -- Tue Jul 1, 2003

14 packets seen, 0 TCP packets traced, 14 UDP packets traced


elapsed wallclock time: 0:00:00.023567, 594 pkts/sec analyzed
trace file elapsed time: 0:00:00.390867
no traced TCP packets
UDP connection info:
1: 132.235.3.154:46096 - 132.235.1.1:53 (a2b) 1> 1<
2: 132.235.3.154:46097 - 132.235.1.1:53 (c2d) 1> 1<
3: 132.235.3.154:46098 - 132.235.1.1:53 (e2f) 1> 1<
4: 132.235.3.154:46099 - 132.235.1.1:53 (g2h) 1> 1<
5: 132.235.19.80:2649 - 132.235.18.1:53 (i2j) 2> 2<
6: 132.235.19.80:2650 - 132.235.64.1:53 (k2l) 1> 1<
Since there is no implicit notion of connections with UDP, tcptrace groups connections from the same pair of IP
addresses and same pair of UDP ports to belong to a “connection”.
Giving the -l option along with the -u option generates more detailed statistics as shown below :

Beluga:/Users/mani/tcptrace-manual> tcptrace -nul dmpfiles/udp.dmp.gz


1 arg remaining, starting with ’dmpfiles/udp.dmp.gz’
Ostermann’s tcptrace -- version 6.4.6 -- Tue Jul 1, 2003

14 packets seen, 0 TCP packets traced, 14 UDP packets traced


elapsed wallclock time: 0:00:00.026584, 526 pkts/sec analyzed
trace file elapsed time: 0:00:00.390867
no traced TCP packets
UDP connection info:
6 UDP connections traced:
UDP connection 1:
host a: 132.235.3.154:46096
host b: 132.235.1.1:53

45
first packet: Wed Oct 31 14:11:11.046435 2001
last packet: Wed Oct 31 14:11:11.048531 2001
elapsed time: 0:00:00.002096
total packets: 2
filename: dmpfiles/udp.dmp.gz
a->b: b->a:
total packets: 1 total packets: 1
data bytes sent: 46 data bytes sent: 367
throughput: 21947 Bps throughput: 175095 Bps
================================
UDP connection 2:
. . .
The total packets field lists the total number of packets seen in the direction, while the data bytes sent field lists the
total number of bytes seen in the direction. The throughput field lists average throughput calculated as the total bytes
seen divided by the connection lifetime (the time elapsed between the first and last packets of the connection).
Analogous to the connection filtering options -o and -i used for selectively processing or ignoring TCP connections
(refer Section 6.1), options —oUDP and —iUDP options selectively process or ignore UDP connections, with the
same semantics.
The following example illustrates selecting just UDP connections 1,3,5 and storing them to file filt udp.dmp :

Beluga:/Users/mani/tcptrace-manual> tcptrace -n -u --oUDP1,3,5 -Ofilt_udp.dmp dmpfiles/udp.dmp


1 arg remaining, starting with ’dmpfiles/udp.dmp.gz’
Ostermann’s tcptrace -- version 6.4.6 -- Tue Jul 1, 2003

14 packets seen, 0 TCP packets traced, 14 UDP packets traced


elapsed wallclock time: 0:00:00.022974, 609 pkts/sec analyzed
trace file elapsed time: 0:00:00.390867
no traced TCP packets
UDP connection info:
1: 132.235.3.154:46096 - 132.235.1.1:53 (a2b) 1> 1<
3: 132.235.3.154:46098 - 132.235.1.1:53 (e2f) 1> 1<
5: 132.235.19.80:2649 - 132.235.18.1:53 (i2j) 2> 2<

8.2 Real-Time Analysis


Real-Time analysis can be done trivially by piping the output of the packet capture program, and letting tcptrace fetch
its input from stdin. With tcpdump, it can be done as in :

tcpdump -w - | tcptrace stdin


This would let tcptrace read the input from the binary output generated by tcpdump, until the process is interrupted
with say Ctrl C, for example. However, this is not really real-time in the sense that the output is generated only after
the process is interrupted, which is analogous to tcptrace printing output at the end of processing a dumpfile.
The option —continuous lets tcptrace run continuously and provides no summary of connections at the end. This
option is normally useful when used along with modules and maintains a list of active connections.
The following options can be used along with the —continuous option :

• —limit conn num Limits the number of active connections kept track of, to the default value of 50000 con-
nections to save on memory.
• —max conn num=. . . Lets you choose the maximum number of connections to be kept track of. If the

46 Chapter 8. Miscellany
maximum connection limit is reached, the least recently used connection is removed to make space for the new
connection.
• —update interval=. . . When operating in the —continuous mode, tcptrace periodically looks at the list of
live and inactive connections and updates the list removing “old” connections. The default update interval is 30
seconds, which can be changed using this option giving the update interval in seconds.
• —remove live conn interval=. . . The default interval after which a live connection is removed from the list
of live connections is 8*3600 seconds (8 hours). This option can be used to customize this interval, giving a
suitable value in seconds. Note that a TCP connection is considered live until a FIN / RST segment is seen in
the connection.
• —remove closed conn interval=. . . Once a FIN / RST segment is seen in a connection, it is moved from
the list of live connections to the list of inactive connections. The default interval (from the time at which the last
packet was seen in the connection) after which a connection is removed from the list of inactive connections is
8*60 seconds (8 minutes). This option can be used to customize this interval, giving a suitable value in seconds.

8.3 Packet Details


Printing
The -p option prints information from the Ethernet, IP, and TCP/UDP headers C for all the packets found in the
dumpfile. For example,

Beluga:/Users/mani> tcptrace -p malus.dmp.gz


produces output as shown below for all the packets found in the file malus.dmp.gz.

. . .
Packet 2
Packet Length: 74
Collected: Thu Jul 10 19:12:54.987110 2003
ETH Srce: 00:00:00:00:00:00
ETH Dest: 00:00:00:00:00:00
Type: 0x800 (IP)
IP VERS: 4
IP Srce: 17.112.152.32 (a17-112-152-32.apple.com)
IP Dest: 132.235.3.153 (elephus.cs.ohiou.edu)
Type: 0x6 (TCP)
HLEN: 20
TTL: 50
LEN: 60
ID: 32113
CKSUM: 0x9936
OFFSET: 0x4000 Don’t Fragment

TCP SPRT: 80 (http)


DPRT: 59518
FLG: -A--S- (0x12)
SEQ: 0x1fbdbe84
ACK: 0x0f455ca5
WIN: 33304
HLEN: 40
CKSUM: 0xfa0f
DLEN: 0
OPTS: 20 bytes MSS(1460) WS(0) TS(-202350942,1957864058)
Packet 3

8.3. Packet Details 47


. . .
As illustrated above, detailed information from the protocol headers of is printed for every packet. The -X option
which is set by default causes fields like SEQ, ACK to be printed in hexadecimal. You may use the -D option to print
them in decimal. Note that since this option prints loads of output for every packet, you probably want to use the -B
and/or -E options 6.1 to selectively print information on the packets of interest.
On the other hand, if you are using the -o/-i options 6.1 or the —oUDP/—iUDP 8.1 to selectively process TCP or
UDP connections respectively, you need to use the -P option (instead of the -p option) to print packet information on
the selected connections alone. For example,

tcptrace -n -o1,3 -P sirius.dmp


prints packet header information only from the packets part of TCP connections 1 and 3, found in the dumpfile
sirius.dmp.
Extracting
The -e option can be used to extract the contents (TCP data payload) of each connection into a separate data file.
For example,

Beluga:/Users/mani> tcptrace -e albus.dmp


generates files a2b contents.dat, b2a contents.dat; c2d contents.dat, d2c contents.dat if the file albus.dmp had 2
traced TCP connections. tcptrace is pretty smart in generating these contents files. It does not commit trivial mistakes
like saving retransmissions multiple times in the file for example, and is aware of sequence space wrap-arounds.
However, if you want the entire contents of the traffic, please make sure that packets are captured in their entirety (give
suitable snaplen value with tcpdump for example).

8.4 Other Miscellany


• —csv/—tsv/—sv=’. . . ’ These options can print the detailed statistics (Chapter 4) in a format that can be easily
imported into a spread-sheet program. The —csv (comma separated values) option prints out a header line
that contains the list of the fields of output to be printed depending on which of the options -l/-r/-W were given.
Each of the header fields are delimited by a comma in the header line. Subsequent lines list the detailed statistics
generated, each of which is delimited by a comma too.
The —tsv (tab separated values) option prints the detailed statistics with the fields delimited by TAB, while the
—sv=’. . . ’ option lets the user choose a string as the delimiter to be used between fields.
• -t option is useful when you are processing huge dumpfiles. It prints ticks indicating the progress in processing
the file, printing out the packet number currently being processed and the percentage of the file processed,
periodically.
• -v prints information on the version of tcptrace being run.
• -h prints help messages as shown below :

Beluga:/Users/mani> tcptrace -h
For help on specific topics, try:
-hargs tell me about the program’s arguments
-hxargs tell me about the module arguments
-hconfig tell me about the configuration of this binary
-houtput explain what the output means
-hfilter output filtering help
-hhints usage hints

48 Chapter 8. Miscellany
Version: Ostermann’s tcptrace -- version 6.4.6 -- Tue Jul 1, 2003
Compiled by ’root’ at ’Thu Jul 10 19:07:29 EDT 2003’ on machine ’pride.cs.ohiou.edu’
More specific help can be found on specific topics by giving the options -hargs, -hxargs etc., as in :

Beluga:/Users/mani> tcptrace -hxargs

• -d Prints debug information on the program. It is probably not useful unless you are tracking a bug in the
program. Multiple -d options can be given to get more and more debug information.
• -q Make the program quiet and print no output. This option is useful if you are interested only in the output
generated by the modules.

8.4. Other Miscellany 49


50
CHAPTER

NINE

Modules

tcptrace comes with a plugin module architecture so that users can develop their own modules to do more sophisticated
analysis pertinent to their needs. This chapter describes the modules distributed with tcptrace namely, TRAFFIC,
HTTP, SLICE, RTTGRAPH, COLLIE, and REAL-TIME, and uses the REAL-TIME module to explain how to
write your own modules.

9.1 TRAFFIC Module


We have seen in the earlier chapters that tcptrace can generate detailed statistics and graphs from a dumpfile on a per
connection basis. The goal of the traffic module is to raise the level of abstraction and present statistics on a per
port basis, and for the entire traffic found in the dumpfile.
The traffic module can be invoked as follows :

tcptrace -xtraffic‘‘[ARGS]’’ <dumpfile>


where the field ARGS represents any arguments to be sent to the traffic module, and are explained in the following.
When the traffic module is invoked without any arguments as in :

surya:/home/mani> tcptrace -xtraffic sack_city.dmp.gz


mod_traffic: characterizing traffic
1 arg remaining, starting with ’sack_city.dmp.gz’
Ostermann’s tcptrace -- version 6.4.7 -- Fri Aug 1, 2003

28427 packets seen, 28427 TCP packets traced


elapsed wallclock time: 0:00:00.649954, 43736 pkts/sec analyzed
trace file elapsed time: 1:22:34.149090
Dumping port statistics into file traffic_byport.dat
Dumping overall statistics into file traffic_stats.dat
Plotting performed at 15.000 second intervals
it generates two data files traffic stats.dat and traffic byport.dat.
The traffic stats.dat file has statistics on the entire traffic found from the dumpfile and looks as in :

Overall Statistics over 4954 seconds (1:22:34.149090):


12531375 ttl bytes sent, 2529.547 bytes/second
8590918 ttl non-rexmit bytes sent, 1734.138 bytes/second
3940457 ttl rexmit bytes sent, 795.409 bytes/second
28427 packets sent, 5.738 packets/second
19 connections opened, 0.004 conns/second

51
59 dupacks sent, 0.012 dupacks/second
3015 rexmits sent, 0.609 rexmits/second
average RTT: 78.268 msecs
From the above, we can notice that the traffic module prints the total time the dumpfile lasted; the total (ttl) number
of bytes sent, average bytes sent per second; the total number of retransmitted and non-retransmitted bytes and the
average bytes (retransmitted and non-retransmitted) per second; the total number of packets, connections, duplicate
acks (dupacks) and retransmits (rexmits) seen (along with their respective averages seen per second) and finally the
average RTT found from all the RTT samples. Note that the average RTT includes RTT samples found that were
ambiguous too (Total samples = RTT samples + ambiguous acks as explained in Section 4.2.
The traffic byport.dat file looks as in :

Overall totals by port


TOTAL bytes: 12531375 pkts: 28427 conns: 19 tput: 2529 B/s
Port 22 bytes: 892552 pkts: 10324 conns: 1 tput: 180 B/s
Port 5002 bytes: 11638823 pkts: 18103 conns: 18 tput: 2349 B/s
. . .
listing per-port statistics on the bytes, packets, connections, and the observed throughput.
The -p option to the traffic module lets it gather statistics only on certain ports of interest.
For example :

tcptrace -xtraffic’’-p80’’ rubeus.dmp


prints statistics for just web connections (TCP port 80), while

tcptrace -xtraffic’’-p1-1024’’ rubeus.dmp


prints statistics only for TCP connections with either of the ports in the range of 1 to 1024 (inclusive).
You may also selectively ignore web traffic (port 80) but have the rest of the low port traffic as analyzed above with :

tcptrace -xtraffic’’-p1-1024,-80’’ rubeus.dmp


The following

tcptrace -xtraffic’’-p1-1024,-80-89’’ rubeus.dmp


ignores traffic destined to ports 80-89 while choosing the connections destined to the rest of the ports in the range
1-1024.
The traffic module can also generate graphs that can be read with the xplot program as explained below.

• -B option generates the bytes-per-second per port# graph (traffic bytes.xpl) for the connections ana-
lyzed by the traffic module. For example the following
surya:/home/mani> tcptrace -xtraffic’’-p22,80 -B’’ minerva.dmp
generated the graph shown in Figure 9.1 and illustrates the bytes-per-second seen on ports 22 and 80 respectively.
The traffic module plots the graphs at discrete intervals of 15 seconds on the x-axis by default. This interval
at which the graph is plotted can be altered if necessary with the -iS option, where S represents the interval S
in seconds. Note that if there a lot of ports being analyzed, your graph may have as many colors. Please zoom
into the beginning of the graphs to find out which colored line in the graph represents the port number you are
interested in.
• -P option generates similarly, the packets-per-second per port# graph (traffic packets.xpl).

52 Chapter 9. Modules
Figure 9.1: Traffic Module (-B)

9.1. TRAFFIC Module 53


Figure 9.2: Traffic Module (-T)

• -T option generates the graph (traffic data.xpl) representing the total data seen across all the connec-
tions analyzed and is illustrated in Figure 9.2. The red-line tracks the non-retransmitted data while the blue line
tracks the total data sent.
• -A option generates a graph (traffic active.xpl) of the active connections over time per port. A con-
nection is deemed active if a packet belonging to the connection was noticed in the last interval. A sample graph
is illustrated in Figure 9.3
• -O option generates the graph (traffic open.xpl) of the number of open connections over time by port.
A connection is deemed open after a packet is seen in either direction and is considered open until either a
RST segment or FIN segments (in both directions) are seen. A sample graph shown in Figure 9.4 illustrates the
number of open connections for one port (5002 in this case) over time.
• -I option generates the “instantaneous-open” graph (traffic i open.xpl) so that connections opening or
closing are plotted when they are found to do so (as opposed to graphing them only at the end of the sampling
interval as done by the -O option). The instantaneous version of the graph in Figure 9.4 is shown in Figure 9.5
• -H option generates the half-open graph (traffic halfopen.xpl) representing the number of half-open

54 Chapter 9. Modules
Figure 9.3: Traffic Module (-A)

9.1. TRAFFIC Module 55


Figure 9.4: Traffic Module (-O)

56 Chapter 9. Modules
Figure 9.5: Traffic Module (-I)

9.1. TRAFFIC Module 57


Figure 9.6: Traffic Module (-C)

connections over time per port, where a connection is deemed half-open from the time a FIN segment is seen in
one direction until the FIN segment is received from the opposite direction.

• -C option generates the open-close graph (traffic openclose.xpl). A sample graph shown in Figure
9.6 illustrates the following. The green-line tracks the number of connections open in the past interval; the
red-line tracks the number of connections closed in the past interval (either a RST segment or FIN segments in
both directions, are seen) ; the blue line tracks the total number of open connections (same as the line plotted
with the -O option).
• -Q option generates the idle (Quiet) connections over time graph (traffic idle.xpl), plotting the total
number of idle connections over time per port. A connection is deemed idle for an interval if no packets
belonging to it were seen in the interval.
• -D option generates the long-duration graph (traffic long.xpl) representing the number of connections
open for a long duration of time over time per port. The default definition of long duration is 60 seconds, which
can be changed to a user-defined S seconds by giving the option as in -DS.

58 Chapter 9. Modules
Figure 9.7: Traffic Module (-L)

• -K option generates the pureacks graph (traffic pureacks.xpl) representing the number of pureacks
seen per second over time on a per port basis.
• -L option generates the loss graph (traffic loss.xpl) representing the loss events per second seen in the
dumpfile. A sample graph is shown in Figure 9.7.
The blue-line tracks actual retransmit events per second observed in the past interval while the yellow-line tracks
the number of triple duplicate acks observed per second in the past interval.
• -R option generates the RTT graph from the RTT samples (including RTT from ambiguous acks) representing
the minimum, average, and maximum RTT values observed in the dumpfile in the past interval. A sample graph
is shown in Figure 9.8.
The green-line tracks the minimum RTT observed, the blue-line the average RTT observed, and the red-line
tracks the maximum observed RTT. Note that, you may choose to generate the graph of RTT values in the range
of interest, between 100 milli-sec and 200 milli-sec for example giving -R100-200. This would consider only
the RTT samples in the range 100-200 msecs observed in the past interval for plotting.
Note that, the -G option can be used to generate all the graphs. Further, in all the graphs that carry information
on a per port basis, a green line always tracks the total value of the statistic represented on the y-axis, summing
up the statistic of all the individual ports drawn in the graph.

9.1. TRAFFIC Module 59


Figure 9.8: Traffic Module (-R)

60 Chapter 9. Modules
9.2 HTTP Module
The HTTP module can be used to analyze web (HTTP 1.0 [?] and HTTP 1.1 [?]) traffic from dumpfiles. The module
can be run by passing in the -xhttp[P] option to tcptrace , where P represents the HTTP port number. By default, the
module looks for web traffic in the TCP well known port 80. If your dumpfile has web traffic in port number P (not
80), you may pass it in as P in the command line as shown above.
The http module implicitly has the effect of the -e option (refer Section 8.3), and extracts data found from individ-
ual connections to data files of the form X2Y contents.dat. Note that since the HTTP module needs the data
from HTTP connections, it is important that the packet contents are fully captured in dumpfiles. With tcpdump for
example, you need to ensure that an appropriate snaplen (with the -s option) value is chosen.
When the HTTP module is invoked as in

Beluga:/Users/mani> tcptrace -n -xhttp severus.dmp.gz


we get the following output.

mod_http: Capturing HTTP traffic (port 80)


1 arg remaining, starting with ’/Users/mani/dmpfiles/standard/severus.dmp.gz’
Ostermann’s tcptrace -- version 6.4.6 -- Tue Jul 1, 2003

4810 packets seen, 4810 TCP packets traced


elapsed wallclock time: 0:00:00.840086, 5725 pkts/sec analyzed
trace file elapsed time: 0:04:06.838094
TCP connection info:
1: 103.196.209.147:15414 - 151.12.146.176:80 (a2b) 1601> 2671<
2: 88.56.8.130:35457 - 199.19.215.115:80 (c2d) 1> 1<
3: . . .
. . .
19: 247.139.32.218:2349 - 80.169.50.43:80 (ak2al) 10> 11< (complete)
20: 181.246.188.179:4482 - 133.114.250.132:80 (am2an) 26> 34< (reset)
Http module output:
103.196.209.147:15414 ==> 151.12.146.176:80 (a2b)
Server Syn Time: <the epoch> (0.000)
Client Syn Time: <the epoch> (0.000)
Server Fin Time: Thu May 1 14:33:34.998156 2003 (1051814014.998)
Client Fin Time: Thu May 1 14:33:35.734937 2003 (1051814015.735)
No additional information available, beginning of connection (SYNs) were not found in trace fi
88.56.8.130:35457 ==> 199.19.215.115:80 (c2d)
. . .
. . .
88.56.8.130:35458 ==> 21.28.79.90:80 (i2j)
Server Syn Time: Thu May 1 14:29:41.695579 2003 (1051813781.696)
Client Syn Time: Thu May 1 14:29:41.657188 2003 (1051813781.657)
Server Fin Time: Thu May 1 14:30:47.963562 2003 (1051813847.964)
Client Fin Time: Thu May 1 14:30:47.924972 2003 (1051813847.925)
GET /main.asp HTTP/1.0
Response Code: 200 (OK)
Request Length: 438
Reply Length: 30730
Content Length: 30447
Content Type : text/html
Time request sent: Thu May 1 14:29:41.700691 2003 (1051813781.701)
Time reply started: Thu May 1 14:29:45.189720 2003 (1051813785.190)
Time reply ACKed: Thu May 1 14:29:46.394593 2003 (1051813786.395)
Elapsed time: 3489 ms (request to first byte sent)

9.2. HTTP Module 61


Elapsed time: 4694 ms (request to content ACKed)
GET /poll-include.asp HTTP/1.0
Response Code: 200 (OK)
Request Length: 392
Reply Length: 2038
Content Length: 1836
Content Type : text/html
Time request sent: Thu May 1 14:29:46.023979 2003 (1051813786.024)
Time reply started: Thu May 1 14:29:46.300471 2003 (1051813786.300)
Time reply ACKed: Thu May 1 14:29:49.254442 2003 (1051813789.254)
Elapsed time: 276 ms (request to first byte sent)
Elapsed time: 3230 ms (request to content ACKed)
POST /poll-include.asp HTTP/1.0
Response Code: 302 (Found)
Request Length: 496
Reply Length: 376
Content Length: 137
Content Type : text/html
Time request sent: Thu May 1 14:29:48.771677 2003 (1051813788.772)
Time reply started: Thu May 1 14:29:49.160714 2003 (1051813789.161)
Time reply ACKed: Thu May 1 14:29:50.939836 2003 (1051813790.940)
Elapsed time: 389 ms (request to first byte sent)
Elapsed time: 2168 ms (request to content ACKed)
GET /poll-include.asp HTTP/1.0
. . .
GET /img/color.gif HTTP/1.0
. . .
. . .
. . .
First, we see the regular output of tcptrace listing the 20 connections traced in the dumpfile, which is followed by the
http module output. For the first connection labeled a2b, the module lists the time the FIN segments were received
from the client and server. Since the SYN segments opening the connections were not captured in the dumpfile, the
connection is incomplete, and hence, the module does not report any detailed HTTP information. The connection
labeled i2j was complete however, and we see the times the SYN and FIN segments were received from the client
and server respectively. This is followed by various HTTP requests and responses seen in the connection : GET
/main.asp, GET /poll-include.asp, POST /poll-include.asp, ...etc., requesting (GET) or
submitting (POST) files main.asp and poll-include.asp.
Let us see the information reported as part of the GET /main.asp HTTP request.

• Response Code field displays the HTTP response code indicating the type of HTTP response received from the
server.
• Request Length tracks the total length (in bytes) of this HTTP request.
• Reply Length tracks the length of the HTTP response received from the server for this HTTP request.
• Content Length field reports the length of the response found from the Content Length field part of the
HTTP response. If the Content Length field is not found in the response, the Content Length is reported
as the length of the remaining data (after the headers) in the server-to-client data file.
• Content Type reports the content type of the data being sent in the response.
• Time request sent, Time reply started, Time reply ACKed fields, as is obvious from their names, track the
time the request was sent, the time when the first segment carrying the response was received, and when the
response was ACKed by the client, respectively. Note that the times are printed in human readable text format
along with their absolute values.

62 Chapter 9. Modules
• Elapsed time fields indicate the time elapsed between seeing the request and receiving the first byte of the
response, and the time elapsed between seeing the request and having the response ACKed.

Besides listing HTTP information for connections as specified above, the module also generates the http.times
file that lists for all the complete connections found, the time the connection was open, the times when the re-
quest/responses were received. The http.times file looks similar to the following :

conn 88.56.8.130:35458 21.28.79.90:80 i2j 2117 5 34953 5


reqrep 88.56.8.130:35458 21.28.79.90:80 i2j 1051813781.701 1051813785.190
1051813786.395 438 30730 200 GET /main.asp HTTP/1.0 text/html
reqrep 88.56.8.130:35458 21.28.79.90:80 i2j 1051813786.024 1051813786.300
1051813789.254 392 2038 200 GET /poll-include.asp HTTP/1.0 text/html
reqrep . . .
reqrep . . .
reqrep . . .
conn 231.65.90.63:63018 151.12.146.176:80 o2p 562 1 8558 1
The first line (beginning with conn) denotes the opening of a HTTP connection and lists the client and server endpoints
(IP and port # : 88.56.8.130:35458, 21.28.79.90:80), the connection label assigned to the connection
(i2j), the total request length in bytes (2117) found as the length of the file storing the contents of data from the client
to server, the total number of requests found (5), the total reply length in bytes (34953) found as the length of the
file storing the contents of data from the server to the client, and the total number of responses found (5). The first
reqrep line shown above denotes the first request/response seen as part of the first connection. This line lists first
the client and server endpoints and the connection label (i2j) assigned. The following fields list the timestamps when
the request was sent (1051813781.701), when the first byte of the response is seen (1051813785.190), and
when the response was ACKed ( 1051813786.395); the length of the request (438) and the response (30730);
the response code (200) and the method it stands for (GET), the content requested (/main.asp HTTP/1.0) and
the content type (text/html).
The http module also generates graphs for every client found in the dumpfile, plotting information on every web
connection generated by the client.
A sample graph generated for all the web connections initiated by client 88.56.8.130, is shown in Figure 9.9.
Each of the long lines in the figure represent a web connection initiated by the client and their length represents the
lifetime of the connection. The y-axis labeled URL doesn’t mean anything specific, and is just an offset that begins
from 1000 and is incremented by a constant value by the module for every web connection found in the dumpfile.
The ticks drawn below the lines represent the times when non-zero data segments were received from the server.
If we zoom into the beginning of the bottom-most connection shown in Figure 9.9, we get Figure 9.10.
The Clnt SYN and Serv SYN ticks on the line represent the times when the SYN segments were seen from the client
and server respectively. Similarly Clnt FIN and Serv FIN found towards the end of the line represent the times when
the FIN segments were seen from the client and server respectively.
In Figure 9.11, we zoom into the information printed on top of the connection lines. Each such small line segment
represents a request-response seen in the connection. We can see in this Figure, the requests formain.asp, poll-
include.asp, etc. The left diamond adjacent to the label /main.asp HTTP/1.0 represents the time when the
request was seen. The length of the small line segment found towards the right represents the time elapsed receiving
the response, with the left and right arrows representing the times when the first and last bytes of the response were re-
ceived. The diamond on the right represents the time the response was ACKed, with the text field 30447 representing
the length of the response.

9.3 SLICE Module


The SLICE module prints basic traffic statistics observed every timeslice. When the SLICE module is invoked as in :

9.3. SLICE Module 63


Figure 9.9: HTTP Module Plot #1

64 Chapter 9. Modules
Figure 9.10: HTTP Module Plot #2

9.3. SLICE Module 65


Figure 9.11: HTTP Module Plot #3

66 Chapter 9. Modules
surya:/home/mani> tcptrace -xslice rexmit.dmp.gz
it leaves a data file by name slice.dat in the working directory that looks like :

date segs bytes rexsegs rexbytes new active


--------------- -------- -------- -------- -------- -------- --------
03:00:23.813146 40 33976 3 3060 1 1
03:00:38.813146 54 50592 7 10500 0 1
03:00:53.813146 77 70612 6 9000 0 1
03:01:08.813146 29 29020 5 7500 0 1
. . .
. . .
As shown above the date field indicates the time at the end of the time slice (15 seconds by default). The subsequent
fields indicate the segments seen (segs), the total bytes of data seen (bytes), the total number of retransmitted
segments (rexsegs) and retransmitted bytes (rexbytes), the total number of new connections opened in the past
time-slice (new) and the total number of connections active in the past time-slice (active). The slice.dat file can
be used as a data file to plot a graph with the gnuplot program for example, to see how the reported characteristics
varied over time in the period of data capture of the dumpfile.
The module also allows the following options that can be passed as ARGS in -xslice’’[ARGS]’’ and given in
the command line.

• -iS if you want to change the default slice interval of 15 seconds to S seconds. Note that S can be a floating
point value if you want.
• -t[b—l—u—U] The -tb specifies the date field in brief and is the default (as shown in the above example);
-tl specifies the date in the long text format as in Fri Apr 28 03:00:23.813146 2000; -tu prints the
date as Unix timestamps as in 956905223; -tU prints the date as Unix timestamps too, but also includes the
micro-second part of the timestamp as in 956905223.813146.
• -d turns on local debugging of this module.

9.4 COLLIE Module


The COLLIE module is a simple module that can display basic information on the connections (TCP and UDP) found
in the dumpfile. A sample output is shown below.

Beluga:/Users/mani> tcptrace -xcollie alastor.dmp.gz


1 arg remaining, starting with ’alastor.dmp.gz’
Ostermann’s tcptrace -- version 6.4.6 -- Tue Jul 1, 2003

86 packets seen, 83 TCP packets traced, 2 UDP packets traced


elapsed wallclock time: 0:00:00.052520, 1637 pkts/sec analyzed
trace file elapsed time: 0:00:11.623647

Source file: alastor.dmp.gz


File modification timestamp: Wed Aug 6 18:27:22 2003
First packet: Tue Aug 5 15:34:30.680899 2003
Last packet: Tue Aug 5 15:34:42.304547 2003

TCP Connections

Session Start: Tue Aug 5 15:34:40.318839 2003

9.4. COLLIE Module 67


Session End: Tue Aug 5 15:34:40.373548 2003
Source IP address: 132.235.3.140
Source Port: 51214
Source Fully Qualified domain name: pride.cs.ohiou.edu
Destination IP address: 132.235.3.154
Destination Port: 80
Destination Fully Qualified domain name: masaka.cs.ohiou.edu
Bytes Transferred Source to Destination: 1796
Bytes Transferred Destination to Source: 17895
Packets Transferred Source to Destination: 8
Packets Transferred Destination to Source: 17

Session Start: Tue Aug 5 15:34:30.680899 2003


. . .
. . .

UDP Connections

Session Start: Tue Aug 5 15:34:40.313479 2003


Session End: Tue Aug 5 15:34:40.317724 2003
Source IP address: 132.235.3.140
Source Port: 49572
Source Fully Qualified domain name: pride.cs.ohiou.edu
Destination IP address: 132.235.64.1
Destination Port: 53
Destination Fully Qualified domain name: watson.cns.ohiou.edu
Bytes Transferred Source to Destination: 42
Bytes Transferred Destination to Source: 143
Packets Transferred Source to Destination: 1
Packets Transferred Destination to Source: 1
The collie module has the side effect of turning on UDP processing (the -u) option. As shown above, the mod-
ule prints details on the source file (alastor.dmp.gz), when it was last modified, and the times of the first and
last packets found in the file. Subsequent lines print basic information on the TCP and UDP connections traced.
The information includes the times when the first and last packet of the connection were found (Session Start,
Session Start respectively); the source and destination endpoints, the total number of bytes and packets trans-
ferred in the either direction of the connection. Note that the collie module prints the connection information in
reverse chronological order, i.e., the most recently opened connection’s information gets printed before a connection
opened earlier.
The following options are supported by the collie module and are to be supplied as ARGS in -
xcollie’’ARGS’’ to tcptrace in command line.

• -n—-l The -n option turns off printing of the labels printed at the beginning of each line ( Session Start,
Session End, Source IP address etc.), while the -l option turns on printing of the labels, which is
the default behavior.
• -d option turns on local debugging in the module.

9.5 Real-Time Module


The Real-Time module is a sample module that can be used to run tcptrace continuously, as described in Section
8.2. This module has the side effect of turning off name lookups, and turning on the —continuous option and UDP
processing internally.
A sample run of tcptrace with the module is shown below.

68 Chapter 9. Modules
elephus:/home/mramadas> tcpdump -n -w - | tcptrace -xrealtime stdin
mod_realtime: Capturing traffic
1 arg remaining, starting with ’stdin’
Ostermann’s tcptrace -- version 6.4.3 -- Sat May 17, 2003

tcpdump: listening on eth0


1060719445.161771 132.235.3.153:47240 132.235.3.154:22 new connection
1060719445.161771 132.235.3.153:47240 132.235.3.154:22 connection closes (had 1 packets)
1060719449.962521 128.156.10.12:54238 132.235.3.153:22 new connection
1060719449.962796 132.235.3.153:44883 205.188.12.92:23 new connection
1060719453.001292 132.235.3.153:47463 132.235.3.154:22 new connection
1060719475.647109 24.93.103.242:706 132.235.3.153:44860 new connection
1060719485.475633 2001:0468:0b02:0820:0208:74ff:fe40:0b81:51846 2001:1418:0013:0001::0
1060719509.995893 number of open connections is 5
1060719535.015844 132.235.194.68:80 132.235.3.153:47217 new connection
1060719535.055810 132.235.194.68:80 132.235.3.153:47218 new connection
1060719569.995794 number of open connections is 7
1060719573.996664 132.235.3.153:47500 63.111.9.162:80 new connection
1060719574.096991 132.235.3.153:47501 63.111.9.162:80 new connection
1060719574.497344 132.235.3.153:47510 202.87.41.115:80 new connection
1060719574.497398 132.235.3.153:47511 202.87.41.115:80 new connection
1060719575.240305 132.235.3.153:47510 202.87.41.115:80 connection closes (had 6 packets)
1060719575.276251 132.235.3.153:47511 202.87.41.115:80 connection closes (had 6 packets)
1060719575.883715 132.235.3.153:47520 202.87.41.119:80 new connection
1060719577.412365 132.235.3.153:47521 202.87.41.119:80 new connection

2251 packets received by filter


0 packets dropped by kernel

Terminating processing early on signal 2


Partial result after processing 2109 packets:

realtime: TCP packets - 531


realtime: UDP packets - 1431
realtime: other packets - 4
protocol: 1, number: 4
As shown above the module prints a message everytime a new connection is found opening or closing in the net-
work. Periodically (every minute), the module also prints out the number of connections open. Finally, at the end of
processing, the module prints the total number of TCP, UDP, and other packets found in the network as shown above.

9.6 Writing Modules


This section describes how to write your own plug-in modules for tcptrace . The structure definition of a module
(found in modules.h) is shown below.

struct module {
Bool module_inuse;
char *module_name;
char *module_descr;

int (*module_init) (int argc, char *argv[]);

9.6. Writing Modules 69


void (*module_read) (
struct ip *pip,/* the packet */
tcp_pair *ptp,/* info I have about this connection */
void *plast,/* pointer to last byte */
void *pmodstruct); /* module-specific structure */

void (*module_done) (void);

void (*module_usage)(void);

void (*module_newfile)(
char *filename,/* the name of the current file */
u_long filesize,/* number of bytes in file (might be compressed) */
Bool fcompressed); /* is the file compressed? */

void *(*module_newconn)(
tcp_pair *ptp); /* info I have about this connection */

void (*module_udp_read) (
struct ip *pip,/* the packet */
udp_pair *pup,/* info I have about this connection */
void *plast,/* pointer to last byte */
void *pmodstruct); /* module-specific structure */

void *(*module_udp_newconn)(
udp_pair *ptp); /* info I have about this connection */

void (*module_nontcpudp_read) (
struct ip *pip,/* the packet */
void *plast); /* pointer to last byte */

void (*module_deleteconn) (
tcp_pair *ptp,/* info I have about this connection */
void *pmodstruct); /* module-specific structure */
};
As shown above, each module definition consists of fields that store a basic description of the module followed by a
list of function pointers that need to be filled with functions specific to the module. The module inuse variable is
used by tcptrace to see if the module has been selected and is active. The module name, and module descr
fields store the name and a short description of the module and are useful for debugging purposes. The list of function
pointers that follow need to be set to appropriate module specific functions.
The function pointers and their assignments for the Real-Time module (from the modules.h file) are shown below.
These functions are defined in the mod realtime.c file.

{TRUE, /* make FALSE if you don’t want to call it at all */


"realtime", /* name of the module */
"example real-time package",/* description of the module */
realtime_init, /* routine to call to init the module */
realtime_read, /* routine to pass each TCP segment */
realtime_done, /* routine to call at program end */
realtime_usage, /* routine to call to print module usage */
NULL, /* routine to call on each new file */
realtime_newconn, /* routine to call on each new connection */
realtime_udp_read, /* routine to pass each UDP segment */
NULL, /* routine to call on each new UDP conn */
realtime_nontcpudp_read, /* routine to pass each non-tcp and non-udp

70 Chapter 9. Modules
packets*/
realtime_deleteconn}

• *module init This is the module initialization function. tcptrace passes the received command-line arguments
(int argc, char *argv[]) to all of the registered modules and the modules are expected to note the
arguments that concern them and delete them by making the corresponding argv[] pointer point to NULL. If
this function returns 1, tcptrace will treat the module as active by turning on the module inuse flag for the
module. On the other hand, if 0 is returned, the module is treated as inactive.
For example, the realtime init function assigned by the Real-Time module looks for the command-line
argument -xrealtime to decide if the module is being invoked or not and returns 1 if found, and 0 otherwise.
If you want your module mymod to be able to handle module specific arguments as in -xmymod’’ARGS’’,
look into the traffic module code in mod traffic.c for example.
• *module read This function is called for every TCP packet being processed. tcptrace supplies the IP packet
itself in host byte order (pip), the information it has about the TCP connection (ptp), a void pointer pointing
to the memory location of the last byte of the packet (plast), and a pointer to the module specific structure
previously associated with this connection (pmodstruct) in the call to *module newconn function (called
when the connection was opened). This module specific structure is useful when the module needs to store any
module-specific information that needs to be associated with the connection. A module-specific structure can
be initialized and given to tcptrace in the *module newconn function and gets returned to the module in
subsequent calls to the *module read function.
With the Real-Time module for example, tcptrace returns the rtconn structure associated with the con-
nection by the realtime newconn function when the connection was opened as the fourth argument in the
realtime read function (called for every TCP packet of the connection).
• *module done This function is called at the end when tcptrace is done processing the dumpfile(s). You might
print the end results/statistics accumulated by your module in this function.
• *module usage The function to be called to print module specific usage message. Please make sure what
command line arguments your module understands and what they mean, are printed out briefly in this function.
• *module newfile This function is called everytime tcptrace begins processing a new dumpfile. The arguments
to the function include the filename, the file size, and a boolean variable indicating if the file were compressed.
A file size value of 1 is returned if reading from stdin.
Note that the Real-Time module sets the function pointer corresponding to this function to NULL meaning
that the module does not want to be notified of the event. Similarly, you may set any of the function pointers
you are not interested in to NULL if you do not want to be notified of the corresponding event by tcptrace .
• *module newconn This function is called every time a new TCP connection is seen opening (upon seeing
the first packet of a new connection). You may initialize any module specific structure for this new connec-
tion and return its address as a void pointer. Note that the function *module newconn is called before the
*module read function so that the latter function is called on the first packet of the connection too.
See the realtime newconn for an example of how a module specific connection structure is initialized and
returned.
• *module udp read This function is called for every UDP packet seen. The arguments and their semantics are
similar to the *module read call. The arguments include the IP packet itself that was captured, the informa-
tion tcptrace keeps for this connection, a pointer to the memory location storing the last byte of the packet, and
any module specific structure returned in the previous call to the *module udp newconn function.
• *module udp newconn Similar to the *module newconn function, this function is called whenever a new
UDP connection is opened (upon seeing the first packet of the connection).
• *module nontcpudp read This function is called for every non TCP/UDP packet seen. The arguments passed
are the IP packet in itself and a pointer to the last byte of the packet.

9.6. Writing Modules 71


• *module deleteconn This function is called whenever tcptrace deletes a connection from its list of active
connections in Real-Time mode as explained in Section 8.2.

72 Chapter 9. Modules
APPENDIX

Arguments QR

This chapter Arguments Quick Reference (QR), explains briefly the options supported by tcptrace .
Basic Arguments
The following options are first read from the file $HOME/.tcptracerc (if it exists), and then from the environment
variable TCPTRACEOPTS (if it exists), and finally from the command line.
All the boolean options (options that do not take in an argument along with it) can be given with a “+” prefix that has
the effect of negating the option. For example, you may give a “+l” to not print in the long output format. This can be
useful if you store the options you always want tcptrace to use in the $HOME/.tcptracerc file or the TCPTRACEOPTS
environment variable but want to turn-off an option for this invocation of tcptrace from command line.

Output format options


-b brief output format
-l long output format
-r print rtt statistics (slower for large files)
-W report on estimated congestion window (not generally useful)
-q no output (if you just want modules output)
Graphing options
-T create throughput graph[s], (average over 10 segments, see -A)
-R create rtt sample graph[s]
-S create time sequence graph[s]
-N create owin graph[s] (_o_utstanding data on _N_etwork)
-F create segsize graph[s]
-L create time line graph[s]
-G create ALL graphs
Output format detail options
-D print in decimal
-X print in hexadecimal
-n don’t resolve host or service names (much faster)
-s use short names (list "picard.cs.ohiou.edu" as just "picard")
Connection filtering options
-iN ignore connection N (can use multiple times)
-oN[-M] only connection N (or N through M). Arg can be used many times.
If N is a file rather than a number, read list from file instead.
-c ignore non-complete connections (didn’t see syn’s and fin’s)
-BN first segment number to analyze (default 1)
-EN last segment number to analyze (default last in file)
Graphing detail options
-C produce color plot[s]
-M produce monochrome (b/w) plot[s]
-AN Average N segments for throughput graphs, default is 10
-z zero axis options
-z plot time axis from 0 rather than wall clock time (backward compat)

73
-zx plot time axis from 0 rather than wall clock time
-zy plot sequence numbers from 0 (time sequence graphs only)
-zxy plot both axes from 0
-y omit the (yellow) instantaneous throughput points in tput graph
Misc options
-Z dump raw rtt sample times to file[s]
-p print all packet contents (can be very long)
-P print packet contents for selected connections
-t ’tick’ off the packet numbers as a progress indication
-fEXPR output filtering (see -hfilter)
-v print version information and exit
-w print various warning messages
-d whistle while you work (enable debug, use -d -d for more output)
-e extract contents of each TCP stream into file
-h print help messages
-u perform (minimal) UDP analysis too
-Ofile dump matched packets to tcpdump file ’file’
+[v] reverse the setting of the -[v] flag (for booleans)
Dump File Names
Anything else in the arguments is taken to be one or more filenames.
The files can be compressed, see compress.h for configuration.
If the dump file name is ’stdin’, then we read from standard input
rather than from a file

Extended boolean options


(unambiguous prefixes also work)
--showsacks show SACK blocks on time sequence graphs (default)
--noshowsacks DON’T show SACK blocks on time sequence graphs
--showrexmit mark retransmits on time sequence graphs (default)
--noshowrexmit DON’T mark retransmits on time sequence graphs
--showoutorder mark out-of-order on time sequence graphs (default)
--noshowoutorder DON’T mark out-of-order on time sequence graphs
--showzerowindow mark zero windows on time sequence graphs (default)
--noshowzerowindow DON’T mark zero windows on time sequence graphs
--showurg mark packets with URGENT bit set on the time sequence graphs (default)
--noshowurg DON’T mark packets with URGENT bit set on the time sequence graphs
--showrttdongles mark non-RTT-generating ACKs with special symbols
--noshowrttdongles DON’T mark non-RTT-generating ACKs with special symbols (default)
--showdupack3 mark triple dupacks on time sequence graphs (default)
--noshowdupack3 DON’T mark triple dupacks on time sequence graphs
--showzerolensegs show zero length packets on time sequence graphs (default)
--noshowzerolensegs DON’T show zero length packets on time sequence graphs
--showzwndprobes show zero window probe packets on time sequence graphs (default)
--noshowzwndprobes DON’T show zero window probe packets on time sequence graphs
--showtitle show title on the graphs (default)
--noshowtitle DON’T show title on the graphs
--res_addr resolve IP addresses into names (may be slow) (default)
--nores_addr DON’T resolve IP addresses into names (may be slow)
--res_port resolve port numbers into names (default)
--nores_port DON’T resolve port numbers into names
--checksum verify IP and TCP checksums
--nochecksum DON’T verify IP and TCP checksums (default)
--dupack3_data count a duplicate ACK carrying data as a triple dupack
--nodupack3_data DON’T count a duplicate ACK carrying data as a triple dupack (default)
--check_hwdups check for ’hardware’ dups (default)
--nocheck_hwdups DON’T check for ’hardware’ dups
--warn_ooo print warnings when packets timestamps are out of order
--nowarn_ooo DON’T print warnings when packets timestamps are out of order (default
--warn_printtrunc print warnings when packets are too short to analyze

74 Appendix A. Arguments QR
--nowarn_printtrunc DON’T print warnings when packets are too short to analyze (default)
--warn_printbadmbz print warnings when MustBeZero TCP fields are NOT 0
--nowarn_printbadmbz DON’T print warnings when MustBeZero TCP fields are NOT 0 (default)
--warn_printhwdups print warnings for hardware duplicates
--nowarn_printhwdups DON’T print warnings for hardware duplicates (default)
--warn_printbadcsum print warnings when packets with bad checksums
--nowarn_printbadcsum DON’T print warnings when packets with bad checksums (default)
--warn_printbad_syn_fin_seq print warnings when SYNs or FINs rexmitted with different sequen
--nowarn_printbad_syn_fin_seq DON’T print warnings when SYNs or FINs rexmitted with differen
--dump_packet_data print all packets AND dump the TCP/UDP data
--nodump_packet_data DON’T print all packets AND dump the TCP/UDP data (default)
--continuous run continuously and don’t provide a summary
--nocontinuous DON’T run continuously and don’t provide a summary (default)
--print_seq_zero print sequence numbers as offset from initial sequence number
--noprint_seq_zero DON’T print sequence numbers as offset from initial sequence number (
--limit_conn_num limit the maximum number of connections kept at a time in real-time m
--nolimit_conn_num DON’T limit the maximum number of connections kept at a time in real-
--xplot_all_files display all generated xplot files at the end
--noxplot_all_files DON’T display all generated xplot files at the end (default)
--ns_hdrs assume that ns has the useHeaders_flag true (uses IP+TCP headers) (def
--nons_hdrs DON’T assume that ns has the useHeaders_flag true (uses IP+TCP headers
--csv display the long output as comma separated values
--nocsv DON’T display the long output as comma separated values (default)
--tsv display the long output as tab separated values
--notsv DON’T display the long output as tab separated values (default)
--turn_off_BSD_dupack turn of the BSD version of the duplicate ack handling
--noturn_off_BSD_dupack DON’T turn of the BSD version of the duplicate ack handling (default)

Extended variable options


(unambiguous prefixes also work)
--output_dir="STR" directory where all output files are placed (default: ’<NULL>’)
--output_prefix="STR" prefix all output files with this string (default: ’<NULL>’)
--xplot_title_prefix="STR" prefix to place in the titles of all xplot files (default: ’<NULL
--update_interval="STR" time interval for updates in real-time mode (default: ’<NULL>’)
--max_conn_num="STR" maximum number of connections to keep at a time in real-time mode (de
--remove_live_conn_interval="STR" idle time after which an open connection is removed in rea
--endpoint_reuse_interval="STR" time interval of inactivity after which an open connection i
--remove_closed_conn_interval="STR" time interval after which a closed connection is removed
--xplot_args="STR" arguments to pass to xplot, if we are calling xplot from here (default
--sv="STR" separator to use for long output with <STR>-separated-values (default:

Module-specific Arguments

Beluga:/Users/mani/tcptrace-manual> tcptrace -hxargs


Module http:
usage:
-xHTTP[P] print info about http traffic (on port P, default 80)
Module traffic:
usage:
-xtraffic"[ARGS]" print info about overall traffic
module argument format:
-iS set statistics interval to S (float) seconds, default 15.0
-pP include information on port P
-pP1-P2 include information on ports in the range [P1-P2]
-p-P exclude information on port P
-p-P1-P2 exclude information on ports in the range [P1-P2]
-pSPEC,SPEC commas chain together specs

75
-G generate all graphs
-A generate the ’active connections’ graph
-B generate the ’bytes per second’ graph
-C generate the ’opens and closes’ graph
-H generate the ’halfopen connections’ graph
-K generate the ’pure acKs/second’ graph
-L generate the ’losses per second’ graph
-O generate the ’open connections’ graph
-I generate the ’instantaneous open connections’ graph
-P generate the ’packets per second’ graph
-Q generate the ’idle (Quiet) connections’ graph
-R[MIN[-MAX]]generate the ’round trip time’ graph
with args, ignore samples outside MIN to MAX (in ms)
-T generate the ’total data’ graph
-D[SECS] generate the ’long duration connection’ graph
default definition of ’long’ is 60 seconds
-d enable local debugging in this module
Examples
-xtraffic" -p23" only port 23
-xtraffic" -p1-1023" only ports 1-1023
-xtraffic"-p1-1023,-10-20 -L -O" only ports 1-1023, but exclude ports 10-20
With no ports specification, all ports are gathered. With ANY
spec, all ports are initially EXCLUDED
Module slice:
usage:
-xslice"[ARGS]" print data info in slices
module argument format:
-iS set slice interval to S (float) seconds, default 15.0
-d enable local debugging in this module
-tb specify time and date ’briefly’
-tl specify time and date in long, ’Unix Format’
-tu specify time and date as a Unix timestamp (secs)
-tU specify time and date as a Unix timestamp (secs.usecs)
Module rttgraph:
usage:
-xrttgraph print info about rttgraph traffic
Module collie:
usage:
-xcollie"[-ln] provide connection summary
-l attach labels
-n no labels please
Module realtime:
usage:
-xrealtime an example module showing how to use real-time tcptrace

76 Appendix A. Arguments QR
APPENDIX

XPLOT QR

This chapter briefly explains the usage of the xplot program.


There seems to be a few other programs floating around the net by the same name. This one was written by Tim
Shepard while doing his S.M. thesis ”TCP Packet Trace Analysis” for David Clark at the MIT Laboratory for Computer
Science. The thesis can be ordered from MIT/LCS Publications. Ordering information can be obtained from +1 617
253 5851 or send mail to publications@lcs.mit.edu. Ask for MIT/LCS/TR-494. Or you can get it on the net free of
charge from ftp://ftp.lcs.mit.edu/pub/lcs-pubs/tr.outbox/MIT-LCS-TR-494.ps.gz .
You may also look at the program’s web-site http://www.xplot.org for the latest version of the program.
Basic Usage
Viewing xplot graph(s) (commonly named as files with the .xpl suffix) is as simple as saying :

xplot file1.xpl [file2.xpl {. . .} ]


You may use the Left-Mouse button to drag and select a specific area in the graph to zoom on it. You may keep
repeating this procedure to zoom in more and more to see any specific area of the graph in more and more detail.
The zoom views are stored in a stack internally, and clicking the Left-Mouse button on the graph lets you zoom-out
level by level popping out the stack. The Middle-Mouse button (clicking and dragging) lets you scroll the graph. The
Right-Mouse button closes the graph being viewed.
The -x option can be useful if you are viewing related graphs (the forward and reverse directions of a connection, for
example) to line-up the x-axes of both the graphs.
Using :

xplot -x a2b_tsg.xpl b2a_tsg.xpl


for example, sets their x-axes in sync so that, zooming in on one of the graphs, also zooms the other graph, so that you
see the same time-scales on both the graphs all the time. Similar semantics are also supported for the y-axis with the
-y option.
Generating Postscript
Clicking the Left-Mouse Button with the SHIFT key pressed, drops a postscript version of the graph being viewed in
the working directory. The postscript files are named Title.PS.# where Title is the title of the graph and # is a
serial number that gets from 0, 1, . . . used so that files do not overwritten accidentally in the working directory.
Clicking the Middle-Mouse Button with the SHIFT key pressed drops a postscript file of smaller size that is good for
including in a paper, for example. Clicking the Right-Mouse Button with the SHIFT key pressed also drops a smaller
size postscript file, but the graph is made smaller vertically.

77
78
APPENDIX

Protocol QR

The IP, TCP, and UDP protocol headers are specified here for quick reference.
Ethernet Header Structure

+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Destination | Source | Type | Data | CRC |
| Address | Address | | | |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
6 6 2 46-1500 4
IPv4 Header Structure

0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|Version| HL | DSCP |ECN| Total Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Identification |Flags| Fragment Offset |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Time to Live | Protocol | Header Checksum |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Source Address |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Destination Address |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
< Options (if any) >
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
< >
| Data |
< >
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Note that the above Figure includes the DSCP (Differentiated Services Code Point) and ECN (Explicit Congestion
Notification) bits defined in the IP header as per RFC 3168 [?].
TCP Header Structure

0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Source Port | Destination Port |

79
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Sequence Number |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Acknowledgment Number |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Header| |C|E|U|A|P|R|S|F| |
| Length| Rsrvd.|W|C|R|C|S|S|Y|I| Window Size |
| | |R|E|G|K|H|T|N|N| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| TCP Checksum | Urgent Pointer |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
< Options (if any) >
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
< >
| Data |
< >
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Note again that the above Figure includes the CWR (Congestion Window Reduced) and ECE (ECN-Echo) flag bits
defined for the TCP header as per RFC 3168 [?].
UDP Header Structure

0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Source Port | Destination Port |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| UDP Length | UDP Checksum |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
< >
| Data |
< >
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

80 Appendix C. Protocol QR
APPENDIX

License

We see the following GNU Free Documentation License as the most appropriate license for copying this manual.

GNU Free Documentation License


Version 1.2, November 2002
Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
0. PREAMBLE
The purpose of this License is to make a manual, textbook, or other functional and useful document ”free” in the sense
of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either
commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit
for their work, while not being considered responsible for modifications made by others.
This License is a kind of ”copyleft”, which means that derivative works of the document must themselves be free in the
same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.
We have designed this License in order to use it for manuals for free software, because free software needs free
documentation: a free program should come with manuals providing the same freedoms that the software does. But
this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter
or whether it is published as a printed book. We recommend this License principally for works whose purpose is
instruction or reference.
1. APPLICABILITY AND DEFINITIONS
This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder
saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license,
unlimited in duration, to use that work under the conditions stated herein. The ”Document”, below, refers to any such
manual or work. Any member of the public is a licensee, and is addressed as ”you”. You accept the license if you
copy, modify or distribute the work in a way requiring permission under copyright law.
A ”Modified Version” of the Document means any work containing the Document or a portion of it, either copied
verbatim, or with modifications and/or translated into another language.
A ”Secondary Section” is a named appendix or a front-matter section of the Document that deals exclusively with the
relationship of the publishers or authors of the Document to the Document’s overall subject (or to related matters) and
contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of
mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical
connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position
regarding them.
The ”Invariant Sections” are certain Secondary Sections whose titles are designated, as being those of Invariant Sec-
tions, in the notice that says that the Document is released under this License. If a section does not fit the above

81
definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant
Sections. If the Document does not identify any Invariant Sections then there are none.
The ”Cover Texts” are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the
notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a
Back-Cover Text may be at most 25 words.
A ”Transparent” copy of the Document means a machine-readable copy, represented in a format whose specification
is available to the general public, that is suitable for revising the document straightforwardly with generic text editors
or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor,
and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input
to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has
been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not
Transparent if used for any substantial amount of text. A copy that is not ”Transparent” is called ”Opaque”.
Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, La-
TeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript
or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque
formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML
for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript
or PDF produced by some word processors for output purposes only.
The ”Title Page” means, for a printed book, the title page itself, plus such following pages as are needed to hold,
legibly, the material this License requires to appear in the title page. For works in formats which do not have any
title page as such, ”Title Page” means the text near the most prominent appearance of the work’s title, preceding the
beginning of the body of the text.
A section ”Entitled XYZ” means a named subunit of the Document whose title either is precisely XYZ or contains
XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section
name mentioned below, such as ”Acknowledgements”, ”Dedications”, ”Endorsements”, or ”History”.) To ”Preserve
the Title” of such a section when you modify the Document means that it remains a section ”Entitled XYZ” according
to this definition.
The Document may include Warranty Disclaimers next to the notice which states that this License applies to the
Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards
disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on
the meaning of this License.
2. VERBATIM COPYING
You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that
this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced
in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical
measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may
accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow
the conditions in section 3.
You may also lend copies, under the same conditions stated above, and you may publicly display copies.
3. COPYING IN QUANTITY
If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering
more than 100, and the Document’s license notice requires Cover Texts, you must enclose the copies in covers that
carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the
back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover
must present the full title with all words of the title equally prominent and visible. You may add other material on the
covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and
satisfy these conditions, can be treated as verbatim copying in other respects.

82 Appendix D. License
If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as
fit reasonably) on the actual cover, and continue the rest onto adjacent pages.
If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a
machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-
network location from which the general network-using public has access to download using public-standard network
protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must
take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent
copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque
copy (directly or through your agents or retailers) of that edition to the public.
It is requested, but not required, that you contact the authors of the Document well before redistributing any large
number of copies, to give them a chance to provide you with an updated version of the Document.
4. MODIFICATIONS
You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above,
provided that you release the Modified Version under precisely this License, with the Modified Version filling the role
of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of
it. In addition, you must do these things in the Modified Version:
A. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous
versions (which should, if there were any, be listed in the History section of the Document). You may use the same title
as a previous version if the original publisher of that version gives permission. B. List on the Title Page, as authors,
one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with
at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they
release you from this requirement. C. State on the Title page the name of the publisher of the Modified Version, as
the publisher. D. Preserve all the copyright notices of the Document. E. Add an appropriate copyright notice for your
modifications adjacent to the other copyright notices. F. Include, immediately after the copyright notices, a license
notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in
the Addendum below. G. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts
given in the Document’s license notice. H. Include an unaltered copy of this License. I. Preserve the section Entitled
”History”, Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the
Modified Version as given on the Title Page. If there is no section Entitled ”History” in the Document, create one
stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing
the Modified Version as stated in the previous sentence. J. Preserve the network location, if any, given in the Document
for public access to a Transparent copy of the Document, and likewise the network locations given in the Document
for previous versions it was based on. These may be placed in the ”History” section. You may omit a network location
for a work that was published at least four years before the Document itself, or if the original publisher of the version
it refers to gives permission. K. For any section Entitled ”Acknowledgements” or ”Dedications”, Preserve the Title of
the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or
dedications given therein. L. Preserve all the Invariant Sections of the Document, unaltered in their text and in their
titles. Section numbers or the equivalent are not considered part of the section titles. M. Delete any section Entitled
”Endorsements”. Such a section may not be included in the Modified Version. N. Do not retitle any existing section
to be Entitled ”Endorsements” or to conflict in title with any Invariant Section. O. Preserve any Warranty Disclaimers.
If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and
contain no material copied from the Document, you may at your option designate some or all of these sections as
invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version’s license notice. These
titles must be distinct from any other section titles.
You may add a section Entitled ”Endorsements”, provided it contains nothing but endorsements of your Modified
Version by various parties–for example, statements of peer review or that the text has been approved by an organization
as the authoritative definition of a standard.
You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover
Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one
of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already

83
includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you
are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the
previous publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity
for or to assert or imply endorsement of any Modified Version.
5. COMBINING DOCUMENTS
You may combine the Document with other documents released under this License, under the terms defined in section
4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the
original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice,
and that you preserve all their Warranty Disclaimers.
The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be
replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make
the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or
publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list
of Invariant Sections in the license notice of the combined work.
In the combination, you must combine any sections Entitled ”History” in the various original documents, forming one
section Entitled ”History”; likewise combine any sections Entitled ”Acknowledgements”, and any sections Entitled
”Dedications”. You must delete all sections Entitled ”Endorsements”.
6. COLLECTIONS OF DOCUMENTS
You may make a collection consisting of the Document and other documents released under this License, and replace
the individual copies of this License in the various documents with a single copy that is included in the collection,
provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.
You may extract a single document from such a collection, and distribute it individually under this License, provided
you insert a copy of this License into the extracted document, and follow this License in all other respects regarding
verbatim copying of that document.
7. AGGREGATION WITH INDEPENDENT WORKS
A compilation of the Document or its derivatives with other separate and independent documents or works, in or on
a volume of a storage or distribution medium, is called an ”aggregate” if the copyright resulting from the compilation
is not used to limit the legal rights of the compilation’s users beyond what the individual works permit. When the
Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not
themselves derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less
than one half of the entire aggregate, the Document’s Cover Texts may be placed on covers that bracket the Document
within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must
appear on printed covers that bracket the whole aggregate.
8. TRANSLATION
Translation is considered a kind of modification, so you may distribute translations of the Document under the terms
of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders,
but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant
Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty
Disclaimers, provided that you also include the original English version of this License and the original versions of
those notices and disclaimers. In case of a disagreement between the translation and the original version of this License
or a notice or disclaimer, the original version will prevail.
If a section in the Document is Entitled ”Acknowledgements”, ”Dedications”, or ”History”, the requirement (section
4) to Preserve its Title (section 1) will typically require changing the actual title.
9. TERMINATION

84 Appendix D. License
You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License.
Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate
your rights under this License. However, parties who have received copies, or rights, from you under this License will
not have their licenses terminated so long as such parties remain in full compliance.
10. FUTURE REVISIONS OF THIS LICENSE
The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time
to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new
problems or concerns. See http://www.gnu.org/copyleft/.
Each version of the License is given a distinguishing version number. If the Document specifies that a particular
numbered version of this License ”or any later version” applies to it, you have the option of following the terms and
conditions either of that specified version or of any later version that has been published (not as a draft) by the Free
Software Foundation. If the Document does not specify a version number of this License, you may choose any version
ever published (not as a draft) by the Free Software Foundation.
ADDENDUM: How to use this License for your documents
To use this License in a document you have written, include a copy of the License in the document and put the
following copyright and license notices just after the title page:
Copyright (c) YEAR YOUR NAME. Permission is granted to copy, distribute and/or modify this document under
the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software
Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is
included in the section entitled ”GNU Free Documentation License”.
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the ”with...Texts.” line with this:
with the Invariant Sections being LIST THEIR TITLES, with the Front-Cover Texts being LIST, and with the Back-
Cover Texts being LIST.
If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alterna-
tives to suit the situation.
If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel
under your choice of free software license, such as the GNU General Public License, to permit their use in free
software.

85