tcpdump manual

TCPTRACE Manual

Manikantan [email protected]

24 August 2003

Abstract

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

CONTENTS

1 Preface 1

2 Getting Started 32.1 Installing tcptrace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32.2 Using tcptrace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

3 Basic Usage 5

4 Detailed Usage 74.1 Detailed Stats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74.2 RTT Stats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104.3 CWND Stats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

5 Graphing 155.1 Time Sequence Graph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155.2 Throughput Graph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245.3 RTT Graph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245.4 Outstanding Data Graph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245.5 Segment Size Graph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285.6 Time-Line Graph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285.7 Miscellany . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

6 Filtering Connections 336.1 Basic Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336.2 Advanced Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

7 Extended Options 397.1 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397.2 Graphing Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407.3 Warning Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

8 Miscellany 458.1 UDP Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458.2 Real-Time Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468.3 Packet Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478.4 Other Miscellany . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

9 Modules 519.1 TRAFFIC Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519.2 HTTP Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

i

9.3 SLICE Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 639.4 COLLIE Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 679.5 Real-Time Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 689.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, thegoal isnot 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 usedTCP/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 readindependently 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 UsageExplains the basic output generated by tcptrace .

• Detailed UsageExplains 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 ConnectionsExplains how to filter-out or filter-in the connection(s) of interest.

• Extended OptionsExplains 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 outpacket details, etc.

• Modules Explains the behavior of the modules distributed with tcptrace , and briefly on how to write your ownmodules.

If you are a tcptrace Power-user familiar with the program, and are just looking for the option that generates the outputyou need, you might dive straight into Appendix A: Arguments Quick Reference. You may find answers to some ofyour xplot related questions in Appendix B: XPLOT Quick Reference. The syntactical definitions of common protocolheaders 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 themanual. 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 forgetting the Documentation project kick-started. Some sections of the manual have been drawn directly from hismanuscript. Thanks are also due to the Python Software Foundation for the LATEX 2ε style files from the PythonDocumentation Project used for generating this manual.

1

CHAPTER

TWO

Getting Started

2.1 Installing tcptrace

tcptrace can be downloaded from the project web-sitehttp://www.tcptrace.org/download.html .

Installing the stable version of tcptrace follows the typical procedure used to install most open-source software onUNIX-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 somay be found in the download page athttp://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 bemade 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

wheredumpfile 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. Ifyou 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 theTCPTRACEOPTSenvironment variable with the options. tcptrace reads the

3

.tcptracerc file and theTCPTRACEOPTSenvironment variable before processing options given in command-line.

You may also usetcptrace -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 tracedelapsed wallclock time: 0:00:00.037900, 2295 pkts/sec analyzedtrace file elapsed time: 0:00:12.180796TCP 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 dumpfiletigris.dmp . The initial lines tell that the file tcptrace is processingcurrently istigris.dmp , the version of tcptrace running, and when it was compiled. The next line tells that a totalof 87 packets were seen in the dumpfile and all the 87 TCP packets (in this case) were traced. The next line tellsthat theelapsed wallclock time i.e., the time tcptrace took to process the dumpfile, and the average speed inpackets per second taken for processing. The following line indicates thetrace file elapsed time i.e., theduration 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 machinespride.cs.ohiou.edu at TCP port54735 , andelephus.cs.ohiou.edu at TCP portssh(22). Similarly the second connection was seen between machinespride.cs.ohiou.edu at TCP port54736 ,anda17-112-152-32.apple.com at TCP porthttp (80). tcptrace uses a labeling scheme to refer to individualconnections traced. In the above example the two connections are labeleda2b andc2d respectively. For the firstconnection, 30 packets were seen in the a2b direction (pride.cs.ohiou.edu ==> elephus.cs.ohiou.edu) and 30 packetswere seen in the b2a direction (elephus.cs.ohiou.edu ==> pride.cs.ohiou.edu). The two connections are reported ascomplete indicating that the entire TCP connection was traced i.e., SYN and FIN segments opening and closing theconnection were traced. TCP connections may also be reported asreset if the connection was closed with an RSTsegment, orunidirectional 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 DNSname 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 ofelephus.cs.ohiou.edu for example), use the-s option.

5

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 outputoption. 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 tracedelapsed wallclock time: 0:00:00.037948, 843 pkts/sec analyzedtrace file elapsed time: 0:00:00.404427TCP connection info:1 TCP connection traced:TCP connection 1:host a: elephus.cs.ohiou.edu:59518host b: a17-112-152-32.apple.com:httpcomplete conn: yesfirst packet: Thu Jul 10 19:12:54.914101 2003last packet: Thu Jul 10 19:12:55.318528 2003elapsed time: 0:00:00.404427total packets: 32filename: malus.dmp.gz

a->b: b->a:total packets: 16 total packets: 16ack pkts sent: 15 ack pkts sent: 16pure acks sent: 13 pure acks sent: 2sack pkts sent: 0 sack pkts sent: 0dsack pkts sent: 0 dsack pkts sent: 0max sack blks/ack: 0 max sack blks/ack: 0unique bytes sent: 450 unique bytes sent: 18182actual data pkts: 1 actual data pkts: 13actual data bytes: 450 actual data bytes: 18182rexmt data pkts: 0 rexmt data pkts: 0rexmt data bytes: 0 rexmt data bytes: 0zwnd probe pkts: 0 zwnd probe pkts: 0zwnd probe bytes: 0 zwnd probe bytes: 0outoforder pkts: 0 outoforder pkts: 0pushed data pkts: 1 pushed data pkts: 1SYN/FIN pkts sent: 1/1 SYN/FIN pkts sent: 1/1req 1323 ws/ts: Y/Y req 1323 ws/ts: Y/Y

7

adv wind scale: 0 adv wind scale: 0req sack: Y req sack: Nsacks sent: 0 sacks sent: 0urgent data pkts: 0 pkts urgent data pkts: 0 pktsurgent data bytes: 0 bytes urgent data bytes: 0 bytesmss requested: 1460 bytes mss requested: 1460 bytesmax segm size: 450 bytes max segm size: 1448 bytesmin segm size: 450 bytes min segm size: 806 bytesavg segm size: 449 bytes avg segm size: 1398 bytesmax win adv: 40544 bytes max win adv: 33304 bytesmin win adv: 5840 bytes min win adv: 33304 byteszero win adv: 0 times zero win adv: 0 timesavg win adv: 23174 bytes avg win adv: 33304 bytesinitial window: 450 bytes initial window: 1448 bytesinitial window: 1 pkts initial window: 1 pktsttl stream length: 450 bytes ttl stream length: 18182 bytesmissed data: 0 bytes missed data: 0 bytestruncated data: 420 bytes truncated data: 17792 bytestruncated packets: 1 pkts truncated packets: 13 pktsdata xmit time: 0.000 secs data xmit time: 0.149 secsidletime max: 103.7 ms idletime max: 99.9 msthroughput: 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 thehosts involved in the connection and their TCP port numbers are:

host a: elephus.cs.ohiou.edu:59518host b: a17-112-152-32.apple.com:http

The following lines indicate that the connection was seen to becomplete i.e., the connection was traced in itsentirety with the SYN and FIN segments of the connection observed in the dumpfile. The time at which the first andlast packets of the connection were captured is reported, followed by the lifetime of the connection, and the numberof packets seen. Then, the filename currently being processed is listed, followed by the multiple TCP statistics for theforward (a2b) and the reverse (b2a) directions.

We explain the TCP parameter statistics in the following, for the a2b direction. Similar explanation would hold for theb2a 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 TCPheader 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 thisincludes 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 typicallysent by a sender when the receiver last advertised a zero receive window, to see if the window has opened upnow).

• 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 RFC1323[?] 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-stampoption 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 wascaptured fully to include the SYN packets. Since the connection would use window scaling if and only if bothsides requested window scaling [?], this field is reset to 0 (even if a window scale was requested in the SYNpacket 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’ isprinted; 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 urgentpointer 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 openingthe 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 thevalue reported in theactual data bytes field divided by theactual data pkts reported.

• max win adv The maximum window advertisement seen. If the connection is using window scaling (bothsides negotiated window scaling during the opening of the connection), this is the maximum window-scaledadvertisement seen in the connection. For a connection using window scaling, both the SYN segments openingthe 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 advertisementseen 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 advertisementsdivided by the total number of packets seen. If the connection endpoints negotiated window scaling, this averageis calculated as the sum of all window-scaled advertisements divided by the number of window-scaled packetsseen. Note that in the window-scaled case, the window advertisements in the SYN packets are excluded sincethe 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 theinitial flight of data before receiving the first ack packet from the other endpoint. Note that the ack packet fromthe other endpoint is the first ack acknowledgingsome data (the ACKs part of the 3-way handshake do notcount), 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 thesequence numbers of the SYN and FIN packets, giving the length of the data stream seen. Note that thiscalculation is aware of sequence space wrap-arounds, and is printed only if the connection was complete (boththe SYN and FIN packets were seen).

• missed data The missed data, calculated as the difference between thettl stream length andunique bytes sent . If the connection was not complete, this calculation is invalid and an “NA” (NotAvailable) is printed.

• truncated data The truncated data, calculated as the total bytes of data truncated during packet capture.For example, withtcpdump, the snaplen option can be set to 64 (with -s option) so that just the headers of thepacket (assuming there are no options) are captured, truncating most of the packet data. In an Ethernet withmaximum segment size of 1500 bytes, this would amount to truncated data of1500 − 64 = 1436bytes for apacket.

• 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 thefirst and last packets carrying non-zero TCP data payload.

• idletime max Maximum idle time, calculated as the maximum time between consecutive packets seen inthe direction.

• throughput The average throughput calculated as the unique bytes sent divided by the elapsed time i.e.,the value reported in theunique bytes sent field divided by theelapsed time (the time differencebetween 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 (Section4.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 tracedelapsed wallclock time: 0:00:00.128422, 1191 pkts/sec analyzedtrace file elapsed time: 0:00:19.092645TCP connection info:1 TCP connection traced:TCP connection 1:


host a: 192.168.0.70:32791host b: webco.ent.ohiou.edu:23complete conn: yesfirst packet: Thu Aug 29 18:54:54.782937 2002last packet: Thu Aug 29 18:55:13.875583 2002elapsed time: 0:00:19.092645total packets: 153filename: indica.dmp.gz

a->b: b->a:total packets: 91 total packets: 62

. . . . . .

. . . . . .throughput: 10 Bps throughput: 94 Bps

RTT samples: 48 RTT samples: 47RTT min: 74.1 ms RTT min: 0.1 msRTT max: 204.0 ms RTT max: 38.8 msRTT avg: 108.6 ms RTT avg: 8.1 msRTT 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: 1RTT full_sz min: 79.5 ms RTT full_sz min: 0.1 msRTT full_sz max: 79.5 ms RTT full_sz max: 0.1 msRTT full_sz avg: 79.5 ms RTT full_sz avg: 0.1 msRTT 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 formultiply-transmitted segments (ambiguous ACKs) wereconsidered. Times are taken from the last instanceof a segment.

ambiguous acks: 1 ambiguous acks: 0RTT min (last): 76.3 ms RTT min (last): 0.0 msRTT max (last): 76.3 ms RTT max (last): 0.0 msRTT avg (last): 76.3 ms RTT avg (last): 0.0 msRTT sdv (last): 0.0 ms RTT sdv (last): 0.0 mssegs cum acked: 0 segs cum acked: 0duplicate acks: 0 duplicate acks: 0triple dupacks: 0 triple dupacks: 0max # retrans: 1 max # retrans: 0min retr time: 380.2 ms min retr time: 0.0 msmax retr time: 380.2 ms max retr time: 0.0 msavg retr time: 380.2 ms avg retr time: 0.0 mssdv 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 aboutchoosing only valid RTT samples. An RTT sample is found only if an ack packet is received from the otherendpoint for a previously transmitted packet such that the acknowledgment value is 1 greater than the lastsequence 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 thelatter condition invalidates RTT samples since it could be the case that the ack packet could be cumulativelyacknowledging 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 maxThe maximum RTT sample seen.

• RTT avg The average value of RTT found, calculated straightforward-ly as the sum of all the RTT valuesfound divided by the total number of RTT samples.

• RTT stdev The standard deviation of the RTT samples.

• RTT from 3WHSThe 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 retransmissionoccurred. More precisely, apost-loss ack is found to occur when an ack packet acknowledges a packetsent (acknowledgment value in the ack pkt is 1 greater than the packet’s last sequence number), and at leastone packet occurring before the packet acknowledged, was retransmitted later. In other words, the ack packet isreceived after we observed a (perceived) loss event and are recovering from it.

• ambiguous acks, RTT min, RTT max, RTT avg, RTT sdv These fields are printed only if therewas at least one ack received that was ambiguous due to the retransmission ambiguity problem i.e., the segmentbeing ack-ed was retransmitted and it is impossible to determine if the ack is for the original or the retransmittedpacket. Note that these samples are not considered in theRTT samples explained above. The statistics beloware 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 followingRTT min, RTT max,RTT avg, RTT sdv fields represent the minimum, maximum, average, and standard deviation respectivelyof 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 aduplicate 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 besome outstanding data.

Note : older versions of tcptrace (until version 6.4.2) used a legacy algorithm using just the first conditionamongst the four listed above, to treat an ack as duplicate ack. This older behavior may be emulated (if necessaryat 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 theconnection.


• min retr time The minimum time seen between any two (re)transmissions of a segment amongst all theretransmissions 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 allthe retransmissions.

• sdv retr time The standard deviation of the retransmission-time samples obtained from all the retransmis-sions.

The rawRTT 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 a2brttraw.dat and b2arttraw.dat (for both directions of the first TCP connectiontraced), c2drttraw.dat and d2crttraw.dat (for the second TCP connection traced) etc. in the working directory. Eachof the datafiles contain lines of the form :

seq# rtt

whereseq# is the sequence number of the first byte of the segment being acknowledged (by the ack packet thatcontributed this RTT sample) andrtt is the RTT value in milli-seconds of the sample. Note that only valid RTTsamples (as counted in theRTT 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 withthe -l option. Since there is no direct way to determine the congestion window at the TCP sender, the outstandingunacknowledged data is used to estimate the congestion window. The 4 new statistics produced by the-W option inaddition 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 tracedelapsed wallclock time: 0:00:00.026658, 1200 pkts/sec analyzedtrace file elapsed time: 0:00:00.404427TCP connection info:1 TCP connection traced:TCP connection 1:host a: elephus.cs.ohiou.edu:59518host b: A17-112-152-32.apple.com:80complete conn: yesfirst packet: Thu Jul 10 19:12:54.914101 2003last packet: Thu Jul 10 19:12:55.318528 2003elapsed time: 0:00:00.404427total packets: 32filename: 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 bytesmin non-zero owin: 1 bytes min non-zero owin: 1 bytesavg owin: 31 bytes avg owin: 1213 byteswavg 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 lifetimeof 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 outstandingdata (odata) was 500 bytes for the first 0.1 seconds, 1000 bytes for the next 1 second, and 2000 bytes for thelast 0.1 seconds of a connection that lasted 1.2 seconds,wavg owin = ((500 x 0.1) + (1000 x 1) + (2000 x0.1)) / 1.2 = 1041.67 bytes an estimate closer to 1000 bytes which was the outstanding data for the most ofthe lifetime of the connection. Note that the straight-forward average reported inavg owin would have been(500+1000+2000)/1.2 = 2916.67 bytes, a value less indicative of the outstanding data observed during most ofthe connection’s lifetime.


CHAPTER

FIVE

Graphing

tcptrace can generate six different types of graphs illustrating various parameters of a TCP connection. These graphscan be viewed with Tim Shepard’s xplot program or with the Java version of the same program called jPlot fromhttp://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 theworking 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 filesa2b *.xplandb2a *.xpl are the graphing data files for both the directions of traffic of the first connection, thec2d *.xplandd2c *.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 canbe generated with the-S option. These graphs are named as X2Ytsg.xpl. A sample Time Sequence graph is shownin Figure 5.1.

The Y-axis represents sequence number space and the X-axis represents time, and the slope of this curve gives thethroughput over time. A section of this graph (zoomed in with xplot) is shown in Figure 5.2 illustrating the followingfeatures.

• 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 numbervalue corresponding to the sum of the acknowledgment number and the receive window advertised from the lastACK 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 lastand first bytes of the segment respectively.

• Red Arrows (R) represent retransmitted segments with the up and down arrows similarly representing thesequence 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, theSYN 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


5.1. Time Sequence Graph 17

The graph shown in Figure 5.4 is a section of a TCP connection being closed.


Here,

• FIN marks a FIN segment sent in the direction.

• RST IN, RST OUT: When a RST segment is sent, aRST OUT is marked in the graph, and aRST IN ismarked 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 segmentcoincide, giving rise to a cross).

• SACK [?, ?] blocks found in ACK packets are represented as purple lines with anS on top as shown in Figure5.5.

• PUSHsegments, i.e., TCP segments sent with the PUSH flag set are represented with a Diamond in place of theup arrow as shown in Figure 5.6.


Figure 5.5: SACK blocks


Figure 5.6: PUSH segments


• URGENT segments, i.e., TCP segments carrying URGENT data with the URG flag set in the TCP header arerepresented with a redU 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 applicationgoes dormant and TCP holds on to the allocated window full of received data, waiting to be picked up). ATime-Sequence graph illustrating this is shown in Figure 5.8.

TheZ labels in the graph represent a window advertisement of 0 bytes received from the other endpoint. ThesubsequentP labels indicate the probe packets sent by the sending endpoint to see if the window has opened upyet.

The following other symbols also occur in Time Sequence graphs :

• O represents packets received out of order.


Figure 5.8: Window Probing


• HD represent Hardware Duplicates. Hardware Duplicates correspond to link layer retransmissions found whena duplicate packet with same IPv4 identification number and TCP sequence number as a previously observedpacket is seen.

• 3 indicates that the received ack packet was the triple duplicate ack, commonly used as the threshold to triggerthe TCP fast retransmit/recovery algorithm.

• CWR / CE track Explicit Congestion Notification [?] messages received. CWR indicates that the CongestionWindow Reduced flag was set in the TCP header of the packet, while the CE flag indicates that the CongestionExperienced code-point was found in the IP header of the packet.

5.2 Throughput Graph

Throughput graphs (named X2Ytput.xpl) are generated with the-T option. A sample throughput graph is shown inFigure 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 timesince 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 yellowdots. 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 drawthe line.

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

5.3 RTT Graph

RTT (Round Trip Time) graphs (named X2Yrtt.xpl) are generated with the-R option. A sample RTT graph is shownin Figure 5.10.

The Y-axis represents RTT in milli-seconds and the X-axis represents time. The yellow dots represent RTT samplescalculated from non-retransmitted segments, and the red line just connects the dots.

5.4 Outstanding Data Graph

Outstanding Data graphs (named X2Yowin.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 graphsto estimate the congestion window at the sender. Since this cannot be determined accurately, we use the outstandingunacknowledged 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 thewavg owin field in Section 4.3.


Figure 5.9: Throughput Graph

5.4. Outstanding Data Graph 25

Figure 5.10: RTT Graph


Figure 5.11: Outstanding Data Graph

5.4. Outstanding Data Graph 27

5.5 Segment Size Graph

Segment size graphs (named X2Yssize.xpl) are generated with the-F option. A sample segment size graph is shownin 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 generatedwith the-L option and generates graphs named as XY tline.xpl


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 thetraffic was captured, while the time values of when the packets arrived or left at the other end have to be estimatedwith some heuristic. Doing thisright tends to be a hard problem taking care of conditions like retransmits, timeoutsetc. 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 theconnection. The Y-axis shows increasing time going from the top to bottom of the graph. The X-axis shows thesegments being transmitted between the 2 hosts communicating. As you zoom in with xplot, more and more detailswill 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 LinesThe 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), sequencenumber from:sequencenumber to(difference, bytes transmitted), ac-knowledgmentsequencenumber, 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 thefirst 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 thesake 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 timebeginning at 0, use the-zx option while generating the graphs. The Y-axis can also be made to begin from 0 withthe -zy option. This is generally useful in Time Sequence graphs, where the sequence offset rather than the actualsequence number values may be desired. Figure 5.4 shows a section of a Time Sequence graph generated with-zxyoption, 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 thegraphs directory.

Now, if you are using the samegraphs directory to store the graphs generated from another filemangifera.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 formmangifera a2b tsg.xpl in thegraphs 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


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 dumpfileelephus.dmp , which could be a lotdepending on the number of connections found. This option is meant for use when there are a few connections inthe dumpfile, unless you want your screen to be filled with xplot graphs. While using this option, any options thatneed 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 internallyfrom tcptrace . If multiple options are being passed to xplot, it is recommended that the entire option be enclosed indouble 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.


CHAPTER

SIX

Filtering Connections

It is commonly the case that the dumpfile captured for analysis by tcptrace has much more connections than the onesyou may be interested in. In such cases, it could be useful to pick and choose the connections of interest from thedumpfile, 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 toonly look at certain connections. For example 8 TCP connections were traced in the filerexmit.dmp.gz :

Beluga:/Users/mani/dmpfiles> tcptrace -n rexmit.dmp.gz1 arg remaining, starting with ’rexmit.dmp.gz’Ostermann’s tcptrace -- version 6.4.6 -- Tue Jul 1, 2003


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.gz1 arg remaining, starting with ’rexmit.dmp.gz’Ostermann’s tcptrace -- version 6.4.6 -- Tue Jul 1, 2003


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 asin

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 boththe -o and-G options. The following example illustrates how you could specify a range of connections with the-ooption to get only the connections1-3, 5, 7-8 from the dumpfile.

Beluga:/Users/mani/dmpfiles> tcptrace -n -o1-3,5,7-8 rexmit.dmp.gz1 arg remaining, starting with ’rexmit.dmp.gz’Ostermann’s tcptrace -- version 6.4.6 -- Tue Jul 1, 2003


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 fileconn.dat for example and pass it to the-o option. The-ooption opens and reads from a file if the character following the-o is not a numeral. For example, when the conn.datfile 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.gz1 arg remaining, starting with ’rexmit.dmp.gz’Ostermann’s tcptrace -- version 6.4.6 -- Tue Jul 1, 2003


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-Ooption.

The following example saves just the connections 4-6 into the filefilt rexmit.dmp .

Beluga:/Users/mani/dmpfiles> tcptrace -n -o4-6 -Ofilt_rexmit.dmp rexmit.dmp.gz1 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 analyzedtrace file elapsed time: 0:20:57.758299TCP 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 tothe-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 inthe-i option (as shown above for the-o option).

The -c option is useful if you are interested in looking at onlycompleteconnections i.e., the connections for whichboth 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, youmay 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. Thesupported filter variables are listed below :

Beluga:/Users/mani/tcptrace-manual> tcptrace -hfilterFilter Variables:

variable name type description----------------- -------- -----------------------hostname STRING FQDN host name (unless -n)portname STRING service name of the port (unless -n)port UNSIGNED port NUMBERmss SIGNED maximum segment sizef1323_ws BOOL 1323 window scaling requestedf1323_ts BOOL 1323 time stampts requestedfsack_req BOOL SACKs requestedwindow_scale BOOL window scale factor

6.2. Advanced Filtering 35

bad_behavior BOOL bad TCP behaviordata_bytes UNSIGNED bytes of datadata_segs UNSIGNED segments of datadata_segs_push UNSIGNED segments with PUSH setunique_by tes UNSIGNED non-retransmitted bytesrexmit_bytes UNSIGNED retransmitted bytesrexmit_segs UNSIGNED segments w/ retransmitted dataack_segs UNSIGNED segments containing ACKpureack_segs UNSIGNED segments containing PURE ACK (no data/syn/fin/reset)win_max UNSIGNED MAX window advertisementwin_min UNSIGNED MIN window advertisementwin_zero_ct UNSIGNED number of ZERO windows advertisedmin_seq UNSIGNED smallest sequence numbermax_seq UNSIGNED largest sequence numbernum_sacks UNSIGNED number of ACKs carrying SACKsmax_sacks UNSIGNED most SACK blocks in a single ACKsegs UNSIGNED total segmentspackets UNSIGNED total segmentssyn_count UNSIGNED SYNs sentfin_count UNSIGNED FINs sentreset_count UNSIGNED RESETs sentmin_seg_size UNSIGNED smallest amount of data in a segment (not 0)max_seg_size UNSIGNED largest amount of data in a segmentout_order_segs UNSIGNED out of order segmentssacks_sent UNSIGNED SACKs sentipv6_segs UNSIGNED number of IPv6 segments sentmax_idle UNSIGNED maximum idle time (usecs)num_hw_dups UNSIGNED number of hardware-level duplicatesinitwin_bytes UNSIGNED number of bytes in initial windowinitwin_segs UNSIGNED number of segments in initial windowrtt_min UNSIGNED MIN round trip time (usecs)rtt_max UNSIGNED MAX round trip time (usecs)rtt_count UNSIGNED number of RTT samplesrtt_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 ACKsrtt_cumack UNSIGNED number of cumulative ACKsrtt_unkack UNSIGNED number of unknown ACKsrtt_dupack UNSIGNED number of duplicate ACKsrtt_nosample UNSIGNED ACKs that generate no valid RTT samplertt_triple_dupack UNSIGNED number of triple duplicate ACKs (fast rexmit)retr_max UNSIGNED MAX rexmits of a single segmentretr_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 filetrunc_segs UNSIGNED number of segments not in the filenum_zwnd_probes UNSIGNED number of zero window probeszwnd_probe_bytes UNSIGNED number of window probe bytesurg_data_pkts UNSIGNED Number of packets with URGENT bit seturg_data_bytes UNSIGNED Number of bytes of urgent datahostaddr IPADDR IP Address (v4 or v6 in standard textual notationthruput UNSIGNED thruput (bytes/sec)

All of the variables listed above can be used for filtering purposes.

For example, consider the filetigris.dmp.gz having the following two connections:

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


. . .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 variablesegs can be used to filter out connections having a specified amount of segments in either directionas shown below.

Beluga:/Users/mani> tcptrace -f’segs>=30’ tigris.dmp.gzOutput 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 theOutput filter line in the above example. The term csegs stands for the client segs (client2serverdirection) and ssegs stands for the server segs (server2client direction). We filter out only those connections that hadat least 30 or more segments seen in either direction. You may specify the segments in the server2client direction aloneas in :

Beluga:/Users/mani> tcptrace -f’s_segs==15’ tigris.dmp.gzOutput 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 ofcompleteness, the prefix “e ” meaning “either” is also supported, requiring the filter variable to be applied to eitherof 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 indouble quotes. The following example illustrates the case when we are filtering out connections for the hostele-phus.cs.ohiou.edu and portssh .

Beluga:/Users/mani> tcptrace -f’hostname=="elephus.cs.ohiou.edu" and portname=="ssh"’tigris.dmp.gzOutput 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 ofthe 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.dmptcptrace -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 namedPF inthe 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 andgraph the filtered connections with thePF file later, as in :

tcptrace -oPF -G file.dmp


CHAPTER

SEVEN

Extended Options

This chapter describes the extended options supported. These options generally offer fine-grained control of thebehavior of tcptrace , and in most cases are useful if you want to turn off the default behavior. The extended optionsare used as in---xyzblah . For every such option, there exists a---noxyzblah that turns off the behavioroffered by the---xyzblah option. Further, you may use just the prefix of the option, say---xyzbl , as long as itis unambiguous amongst all the extended options.

Note that the options explained below are labeledDEFAULT if it is the default behavior, meaning that the optioncomes 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 itoff i.e., tonot resolve IP addresses.

• —res port (DEFAULT) Resolve port numbers to their service names. For example, printhttp for TCP port80. Note that the-n option is equivalent to giving both the—nores addr and—nores port options.

• —checksumThis option turns on checking of IP and TCP/UDP checksums. A summary is printed at the endof 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 IPv4identification 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 thatns had theuse-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 toduplicate acks in Section 4.2) to turn on the legacy algorithm used by tcptrace to determine tripleduplicate 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 whichactivity in the same endpoint tuple (source IP, Port; destination IP, Port) is perceived as a new connection, toSseconds.

Though it is pretty rare to find two hosts reusing their same endpoints for a new connection between them, it hasbeen found that dumb devices like certain old printers tend to reuse their TCP port numbers pretty often. If yourun into such problems, you may use this option to change the default idle-time after which activity seen in thesame 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 usethe --no... versions of these options if you want to turn off the behavior available by default. Also note thatunambiguous 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 whitecrosses).

• —showdupack3 (DEFAULT) Show triple duplicate acks with segment labeled3.

• —showsacks (DEFAULT)Show the purple colored SACK segments.

• —showrexmit (DEFAULT) Show the retransmissions (red segments labeledR).

• —showoutorder (DEFAULT) Show the out-of-order segments (segments labeledO).

• —showzerowindow (DEFAULT) Show the zero-window advertisements (segments labeledZ).

• —showzwndprobes (DEFAULT)Show the window-probe packets that normally follow the zero-window ad-vertisements (segments labeledP).

• —showurg (DEFAULT) Show the segments with the TCP Urgent (URG) flag set with aU.

• —showrttdonglesShow RTT Dongles on interesting acks as explained below. Note that, unlike other optionsthis isnot 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 beingacknowledged 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 REDdiamond nailed on it. As can be seen in the graph, the segment that is being acknowledged by the ack packethad been retransmitted.

An ack packet is plotted with a BLUE diamond head if the ack is ambiguous due to the fact that one of thesegments 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 diamondhead on the top. This is due to the fact that a segment being cumulatively acknowledged by this ack had beenretransmitted.

7.3 Warning Control

This section describes the options that control the printing of warning messages on various events. These options areturned 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 thefollowing options.

• —warn ooo Warn if packet capture timestamps are found to be out of order in the dumpfile. For example,if the dumpfile is oftcpdump style, this option would cause a warning message if the PCAP timestamps ofsuccessive 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 TCPheader(20 bytes) for TCP packets or the UDP header (8 bytes) for UDP packets was not fully captured. Notethat, this warning message typically means that the packet capture was not done requesting enough of everypacket to be captured. Withtcpdump for example, this can be fixed with a suitable value to the-s snaplenoption.

• —warn printbadmbz (Warn Bad Must Be Zero) Prints a warning message if any of the 4 least significant bitsin 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) werefound for IPv4 packets. Hardware duplicates are defined to be the IPv4 packets with the same TCP sequencenumber 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 thepacket numbers of the packets in the dumpfile that had bad IP and TCP/UDP checksums. The following exampleillustrates this :

alakhian@spider:% tcptrace --warn_printbadcsum --checksum input/bad_tcp_checksum.dmp.gzpacket 1: bad TCP checksum1 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 tracedelapsed wallclock time: 0:00:00.057058, 175 pkts/sec analyzedtrace file elapsed time: 0:00:00.012379bad IP checksums: 0bad TCP checksums: 1TCP connection info:

1: analex093.lerc.nasa.gov:2270 - chipper.lerc.nasa.gov:139 (a2b) 3> 6<

• —warn printbad syn fin seqPrints 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

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.gz1 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 tracedelapsed wallclock time: 0:00:00.023567, 594 pkts/sec analyzedtrace file elapsed time: 0:00:00.390867no traced TCP packetsUDP 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 IPaddresses 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.gz1 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 tracedelapsed wallclock time: 0:00:00.026584, 526 pkts/sec analyzedtrace file elapsed time: 0:00:00.390867no traced TCP packetsUDP connection info:6 UDP connections traced:UDP connection 1:host a: 132.235.3.154:46096host b: 132.235.1.1:53

45

first packet: Wed Oct 31 14:11:11.046435 2001last packet: Wed Oct 31 14:11:11.048531 2001elapsed time: 0:00:00.002096total packets: 2filename: dmpfiles/udp.dmp.gz

a->b: b->a:total packets: 1 total packets: 1data bytes sent: 46 data bytes sent: 367throughput: 21947 Bps throughput: 175095 Bps

================================UDP connection 2:

. . .

The total packetsfield lists the total number of packets seen in the direction, while thedata bytes sentfield lists thetotal number of bytes seen in the direction. Thethroughput field lists average throughput calculated as the total bytesseen 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 thesame semantics.

The following example illustrates selecting just UDP connections 1,3,5 and storing them to filefilt udp.dmp :

Beluga:/Users/mani/tcptrace-manual> tcptrace -n -u --oUDP1,3,5 -Ofilt_udp.dmp dmpfiles/udp.dmp.gz1 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 tracedelapsed wallclock time: 0:00:00.022974, 609 pkts/sec analyzedtrace file elapsed time: 0:00:00.390867no traced TCP packetsUDP 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 fetchits input fromstdin . With tcpdump , it can be done as in :

tcpdump -w - | tcptrace stdin

This would let tcptrace read the input from the binary output generated bytcpdump , until the process is interruptedwith sayCtrl C , for example. However, this is not really real-time in the sense that the output is generated only afterthe 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. Thisoption is normally useful when used along with modules and maintains a list of active connections.

The following options can be used along with the—continuousoption :

• —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 newconnection.

• —update interval=. . . When operating in the—continuousmode, tcptrace periodically looks at the list oflive and inactive connections and updates the list removing “old” connections. The default update interval is 30seconds, 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 listof live connections is 8*3600 seconds (8 hours). This option can be used to customize this interval, giving asuitable value in seconds. Note that a TCP connection is considered live until a FIN / RST segment is seen inthe connection.

• —remove closed conn interval=. . . Once a FIN / RST segment is seen in a connection, it is moved fromthe list of live connections to the list of inactive connections. The default interval (from the time at which the lastpacket was seen in the connection) after which a connection is removed from the list of inactive connections is8*60 seconds (8 minutes). This option can be used to customize this interval, giving a suitable value in seconds.

8.3 Packet Details

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

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

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

. . .Packet 2Packet Length: 74Collected: Thu Jul 10 19:12:54.987110 2003ETH Srce: 00:00:00:00:00:00ETH Dest: 00:00:00:00:00:00

Type: 0x800 (IP)IP VERS: 4IP 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: 50LEN: 60

ID: 32113CKSUM: 0x9936

OFFSET: 0x4000 Don’t Fragment

TCP SPRT: 80 (http)DPRT: 59518

FLG: -A--S- (0x12)SEQ: 0x1fbdbe84ACK: 0x0f455ca5WIN: 33304

HLEN: 40CKSUM: 0xfa0f

DLEN: 0OPTS: 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 optionwhich is set by default causes fields likeSEQ, ACKto be printed in hexadecimal. You may use the-D option to printthem in decimal. Note that since this option prints loads of output for every packet, you probably want to use the-Band/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 orUDP connections respectively, you need to use the-P option (instead of the-p option) to print packet information onthe 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 dumpfilesirius.dmp .

ExtractingThe-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 a2bcontents.dat, b2acontents.dat; c2dcontents.dat, d2ccontents.dat if the filealbus.dmp had 2traced TCP connections. tcptrace is pretty smart in generating these contents files. It does not commit trivial mistakeslike 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 (givesuitable snaplen value withtcpdump for example).

8.4 Other Miscellany

• —csv/—tsv/—sv=’. . . ’ These options can print the detailed statistics (Chapter 4) in a format that can be easilyimported into a spread-sheet program. The—csv (comma separated values) option prints out a header linethat 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 statisticsgenerated, each of which is delimited by a comma too.

The—tsv (tab separated values) option prints the detailed statistics with the fields delimited byTAB , 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 processingthe 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 -hFor 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, 2003Compiled 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, -hxargsetc., 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 theprogram. 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 outputgenerated by the modules.

8.4. Other Miscellany 49

CHAPTER

NINE

Modules

tcptrace comes with a plugin module architecture so that users can develop their own modules to do more sophisticatedanalysis pertinent to their needs. This chapter describes the modules distributed with tcptrace namely,TRAFFIC,HTTP, SLICE, RTTGRAPH, COLLIE, and REAL-TIME , and uses theREAL-TIME module to explain how towrite 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 perconnection basis. The goal of thetraffic module is to raise the level of abstraction and present statistics on a perport basis, and for the entire traffic found in the dumpfile.

The traffic module can be invoked as follows :

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

where the fieldARGSrepresents any arguments to be sent to thetraffic module, and are explained in the following.

When thetraffic module is invoked without any arguments as in :

surya:/home/mani> tcptrace -xtraffic sack_city.dmp.gzmod_traffic: characterizing traffic1 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 tracedelapsed wallclock time: 0:00:00.649954, 43736 pkts/sec analyzedtrace file elapsed time: 1:22:34.149090Dumping port statistics into file traffic_byport.datDumping overall statistics into file traffic_stats.datPlotting performed at 15.000 second intervals

it generates two data filestraffic stats.dat andtraffic 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/second8590918 ttl non-rexmit bytes sent, 1734.138 bytes/second3940457 ttl rexmit bytes sent, 795.409 bytes/second28427 packets sent, 5.738 packets/second19 connections opened, 0.004 conns/second

51

59 dupacks sent, 0.012 dupacks/second3015 rexmits sent, 0.609 rexmits/secondaverage RTT: 78.268 msecs

From the above, we can notice that thetraffic module prints the total time the dumpfile lasted; the total (ttl) numberof bytes sent, average bytes sent per second; the total number of retransmitted and non-retransmitted bytes and theaverage bytes (retransmitted and non-retransmitted) per second; the total number of packets, connections, duplicateacks (dupacks) and retransmits (rexmits) seen (along with their respective averages seen per second) and finally theaverage RTT found from all the RTT samples. Note that the average RTT includes RTT samples found that wereambiguous too (Total samples = RTT samples + ambiguous acks as explained in Section 4.2.

The traffic byport.dat file looks as in :

Overall totals by portTOTAL bytes: 12531375 pkts: 28427 conns: 19 tput: 2529 B/sPort 22 bytes: 892552 pkts: 10324 conns: 1 tput: 180 B/sPort 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 thetraffic 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 range1-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 thetraffic 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.Thetraffic module plots the graphs at discrete intervals of 15 seconds on the x-axis by default. This intervalat which the graph is plotted can be altered if necessary with the-iS option, where S represents the interval Sin seconds. Note that if there a lot of ports being analyzed, your graph may have as many colors. Please zoominto the beginning of the graphs to find out which colored line in the graph represents the port number you areinterested 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 linetracks 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 graphis 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 aRST segment or FIN segments (in both directions) are seen. A sample graph shown in Figure 9.4 illustrates thenumber 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 orclosing are plotted when they are found to do so (as opposed to graphing them only at the end of the samplinginterval 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


Figure 9.3: Traffic Module (-A)


Figure 9.4: Traffic Module (-O)


Figure 9.5: Traffic Module (-I)


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 inone 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 Figure9.6 illustrates the following. The green-line tracks the number of connections open in the past interval; thered-line tracks the number of connections closed in the past interval (either a RST segment or FIN segments inboth directions, are seen) ; the blue line tracks the total number of open connections (same as the line plottedwith the-O option).

• -Q option generates the idle (Quiet) connections over time graph (traffic idle.xpl ), plotting the totalnumber of idle connections over time per port. A connection is deemed idle for an interval if no packetsbelonging to it were seen in the interval.

• -D option generates the long-duration graph (traffic long.xpl ) representing the number of connectionsopen for a long duration of time over time per port. The default definition of long duration is 60 seconds, whichcan be changed to a user-defined S seconds by giving the option as in-DS .


Figure 9.7: Traffic Module (-L)

• -K option generates the pureacks graph (traffic pureacks.xpl ) representing the number of pureacksseen 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 thedumpfile. 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 tracksthe 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) representingthe minimum, average, and maximum RTT values observed in the dumpfile in the past interval. A sample graphis shown in Figure 9.8.

The green-line tracks the minimum RTT observed, the blue-line the average RTT observed, and the red-linetracks the maximum observed RTT. Note that, you may choose to generate the graph of RTT values in the rangeof interest, between 100 milli-sec and 200 milli-sec for example giving-R100-200. This would consider onlythe 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 informationon a per port basis, a green line always tracks the total value of the statistic represented on the y-axis, summingup the statistic of all the individual ports drawn in the graph.


Figure 9.8: Traffic Module (-R)


9.2 HTTP Module

The HTTP module can be used to analyze web (HTTP 1.0 [?] and HTTP 1.1 [?]) traffic from dumpfiles. The modulecan be run by passing in the-xhttp[P] option to tcptrace , whereP represents the HTTP port number. By default, themodule looks for web traffic in the TCP well known port 80. If your dumpfile has web traffic in port number P (not80), you may pass it in as P in the command line as shown above.

Thehttp 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 formX2Y contents.dat . Note that since the HTTP module needs the datafrom HTTP connections, it is important that the packet contents are fully captured in dumpfiles. Withtcpdump forexample, you need to ensure that an appropriatesnaplen (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


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 file.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.0Response Code: 200 (OK)Request Length: 438Reply Length: 30730Content Length: 30447Content Type : text/htmlTime 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: 392Reply Length: 2038Content Length: 1836Content Type : text/htmlTime 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.0Response Code: 302 (Found)Request Length: 496Reply Length: 376Content Length: 137Content Type : text/htmlTime 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 thehttp module output. For the first connection labeleda2b , the module lists the time the FIN segments were receivedfrom the client and server. Since the SYN segments opening the connections were not captured in the dumpfile, theconnection is incomplete, and hence, the module does not report any detailed HTTP information. The connectionlabeledi2j was complete however, and we see the times the SYN and FIN segments were received from the clientand 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) orsubmitting (POST) filesmain.asp and poll-include.asp .

Let us see the information reported as part of theGET /main.asp HTTP request.

• Response Codefield displays the HTTP response code indicating the type of HTTP response received from theserver.

• Request Lengthtracks 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 theContent Length field part of theHTTP response. If theContent Length field is not found in the response, theContent Length is reportedas 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 ACKedfields, as is obvious from their names, track thetime the request was sent, the time when the first segment carrying the response was received, and when theresponse was ACKed by the client, respectively. Note that the times are printed in human readable text formatalong with their absolute values.


• Elapsed timefields indicate the time elapsed between seeing the request and receiving the first byte of theresponse, 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 thehttp.timesfile that lists for all the complete connections found, the time the connection was open, the times when the re-quest/responses were received. Thehttp.times file looks similar to the following :

conn 88.56.8.130:35458 21.28.79.90:80 i2j 2117 5 34953 5reqrep 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/htmlreqrep 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/htmlreqrep . . .reqrep . . .reqrep . . .conn 231.65.90.63:63018 151.12.146.176:80 o2p 562 1 8558 1

The first line (beginning withconn ) 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 clientto server, the total number of requests found (5), the total reply length in bytes (34953) found as the length of thefile storing the contents of data from the server to the client, and the total number of responses found (5). The firstreqrep line shown above denotes the first request/response seen as part of the first connection. This line lists firstthe client and server endpoints and the connection label (i2j) assigned. The following fields list the timestamps whenthe request was sent (1051813781.701 ), when the first byte of the response is seen (1051813785.190 ), andwhen 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 ) andthe content type (text/html ).

The http module also generates graphs for every client found in the dumpfile, plotting information on every webconnection generated by the client.

A sample graph generated for all the web connections initiated by client88.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 thelifetime of the connection. The y-axis labeled URL doesn’t mean anything specific, and is just an offset that beginsfrom 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.

TheClnt SYN andServ SYNticks on the line represent the times when the SYN segments were seen from the clientand server respectively. SimilarlyClnt FIN andServ FIN found towards the end of the line represent the times whenthe 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 segmentrepresents 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 therequest was seen. The length of the small line segment found towards the right represents the time elapsed receivingthe 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 field30447 representingthe length of the response.

9.3 SLICE Module

TheSLICE module prints basic traffic statistics observed every timeslice. When theSLICE module is invoked as in :

9.3. SLICE Module 63

Figure 9.9: HTTP Module Plot #1



9.3. SLICE Module 65

surya:/home/mani> tcptrace -xslice rexmit.dmp.gz

it leaves a data file by nameslice.dat in the working directory that looks like :

date segs bytes rexsegs rexbytes new active--------------- -------- -------- -------- -------- -------- --------03:00:23.813146 40 33976 3 3060 1 103:00:38.813146 54 50592 7 10500 0 103:00:53.813146 77 70612 6 9000 0 103: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 subsequentfields indicate the segments seen (segs ), the total bytes of data seen (bytes ), the total number of retransmittedsegments (rexsegs ) and retransmitted bytes (rexbytes ), the total number of new connections opened in the pasttime-slice (new) and the total number of connections active in the past time-slice (active ). Theslice.dat file canbe used as a data file to plot a graph with thegnuplot program for example, to see how the reported characteristicsvaried 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 inthe command line.

• -iS if you want to change the default slice interval of 15 seconds to S seconds. Note that S can be a floatingpoint 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 inFri Apr 28 03:00:23.813146 2000 ; -tu prints thedate as Unix timestamps as in956905223 ; -tU prints the date as Unix timestamps too, but also includes themicro-second part of the timestamp as in956905223.813146 .

• -d turns on local debugging of this module.

9.4 COLLIE Module

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

Beluga:/Users/mani> tcptrace -xcollie alastor.dmp.gz1 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 tracedelapsed wallclock time: 0:00:00.052520, 1637 pkts/sec analyzedtrace file elapsed time: 0:00:11.623647

Source file: alastor.dmp.gzFile modification timestamp: Wed Aug 6 18:27:22 2003First packet: Tue Aug 5 15:34:30.680899 2003Last 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 2003Source IP address: 132.235.3.140Source Port: 51214Source Fully Qualified domain name: pride.cs.ohiou.eduDestinati on IP address: 132.235.3.154Destination Port: 80Destination Fully Qualified domain name: masaka.cs.ohiou.eduBytes Transferred Source to Destination: 1796Bytes Transferred Destination to Source: 17895Packets Transferred Source to Destination: 8Packets 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 2003Session End: Tue Aug 5 15:34:40.317724 2003Source IP address: 132.235.3.140Source Port: 49572Source Fully Qualified domain name: pride.cs.ohiou.eduDestination IP address: 132.235.64.1Destination Port: 53Destination Fully Qualified domain name: watson.cns.ohiou.eduBytes Transferred Source to Destination: 42Bytes Transferred Destination to Source: 143Packets Transferred Source to Destination: 1Packets 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 andlast 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 thecollie module prints the connection information inreverse chronological order, i.e., the most recently opened connection’s information gets printed before a connectionopened earlier.

The following options are supported by thecollie 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 isthe 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 Section8.2. This module has the side effect of turning off name lookups, and turning on the—continuousoption and UDPprocessing internally.

A sample run of tcptrace with the module is shown below.


elephus:/home/mramadas> tcpdump -n -w - | tcptrace -xrealtime stdinmod_realtime: Capturing traffic1 arg remaining, starting with ’stdin’Ostermann ’s tcptrace -- version 6.4.3 -- Sat May 17, 2003

tcpdump: listening on eth01060719445.161771 132.235.3.153:47240 132.235.3.154:22 new connection1060719445.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 connection1060719449.962796 132.235.3.153:44883 205.188.12.92:23 new connection1060719453.001292 132.235.3.153:47463 132.235.3.154:22 new connection1060719475.647109 24.93.103.242:706 132.235.3.153:44860 new connection1060719485.475633 2001:0468:0b02:0820:0208:74ff:fe40:0b81:51846 2001:1418:0013:0001::0025:1060719509.995893 number of open connections is 51060719535.015844 132.235.194.68:80 132.235.3.153:47217 new connection1060719535.055810 132.235.194.68:80 132.235.3.153:47218 new connection1060719569.995794 number of open connections is 71060719573.996664 132.235.3.153:47500 63.111.9.162:80 new connection1060719574.096991 132.235.3.153:47501 63.111.9.162:80 new connection1060719574.497344 132.235.3.153:47510 202.87.41.115:80 new connection1060719574.497398 132.235.3.153:47511 202.87.41.115:80 new connection1060719575.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 connection1060719577.412365 132.235.3.153:47521 202.87.41.119:80 new connection

2251 packets received by filter0 packets dropped by kernel

Terminating processing early on signal 2Partial result after processing 2109 packets:

realtime: TCP packets - 531realtime: UDP packets - 1431realtime: 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 ofprocessing, 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 inmodules.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 alist of function pointers that need to be filled with functions specific to the module. Themodule inuse variable isused by tcptrace to see if the module has been selected and is active. Themodule name, and module descrfields store the name and a short description of the module and are useful for debugging purposes. The list of functionpointers that follow need to be set to appropriate module specific functions.

The function pointers and their assignments for the Real-Time module (from themodules.h file) are shown below.These functions are defined in themod 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


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 thearguments that concern them and delete them by making the corresponding argv[] pointer point to NULL. Ifthis function returns 1, tcptrace will treat the module as active by turning on themodule inuse flag for themodule. On the other hand, if 0 is returned, the module is treated as inactive.

For example, therealtime init function assigned by the Real-Time module looks for the command-lineargument-xrealtime to decide if the module is being invoked or not and returns 1 if found, and 0 otherwise.If you want your modulemymodto be able to handle module specific arguments as in-xmymod’’ARGS’’ ,look into thetraffic module code inmod traffic.c for example.

• *module read This function is called for every TCP packet being processed. tcptrace supplies the IP packetitself in host byte order (pip ), the information it has about the TCP connection (ptp ), a void pointer pointingto the memory location of the last byte of the packet (plast ), and a pointer to the module specific structurepreviously associated with this connection (pmodstruct ) in the call to*module newconn function (calledwhen the connection was opened). This module specific structure is useful when the module needs to store anymodule-specific information that needs to be associated with the connection. A module-specific structure canbe initialized and given to tcptrace in the*module newconn function and gets returned to the module insubsequent calls to the*module read function.

With the Real-Time module for example, tcptrace returns thertconn structure associated with the con-nection by therealtime newconn function when the connection was opened as the fourth argument in therealtime read function (called for every TCP packet of the connection).

• *module doneThis function is called at the end when tcptrace is done processing the dumpfile(s). You mightprint the end results/statistics accumulated by your module in this function.

• *module usageThe function to be called to print module specific usage message. Please make sure whatcommand 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 argumentsto 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 theReal-Time module sets the function pointer corresponding to this function to NULL meaningthat the module does not want to be notified of the event. Similarly, you may set any of the function pointersyou 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 seeingthe 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 therealtime newconn for an example of how a module specific connection structure is initialized andreturned.

• *module udp read This function is called for every UDP packet seen. The arguments and their semantics aresimilar 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, andany module specific structure returned in the previous call to the*module udp newconn function.

• *module udp newconnSimilar to the*module newconn function, this function is called whenever a newUDP 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 passedare the IP packet in itself and a pointer to the last byte of the packet.

9.6. Writing Modules 71

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


APPENDIX

A

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 environmentvariable 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 hasthe effect of negating the option. For example, you may give a “+l” tonot print in the long output format. This can beuseful if you store the options you always want tcptrace to use in the $HOME/.tcptracerc file or the TCPTRACEOPTSenvironment 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 graphMisc 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 NamesAnything 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 sequence--nowarn_printbad_syn_fin_seq DON’T print warnings when SYNs or FINs rexmitted with different--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 (default)--limit_conn_num limit the maximum number of connections kept at a time in real-time mode--nolimit_conn_num DON’T limit the maximum number of connections kept at a time in real-time--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) (default)--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 (default:--remove_live_conn_interval="STR" idle time after which an open connection is removed in real-time--endpoint_reuse_interval="STR" time interval of inactivity after which an open connection is--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 -hxargsModule http:

usage:-xHTTP[P] print info about http traffic (on port P, default 80)

Module traffic:usage:

-xtraffic"[ARGS]" print info about overall trafficmodule 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 ANYspec, all ports are initially EXCLUDED

Module slice:usage:

-xslice"[ARGS]" print data info in slicesmodule 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 trafficModule 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

B

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 TimShepard while doing his S.M. thesis ”TCP Packet Trace Analysis” for David Clark at the MIT Laboratory for ComputerScience. The thesis can be ordered from MIT/LCS Publications. Ordering information can be obtained from +1 617253 5851 or send mail to [email protected]. Ask for MIT/LCS/TR-494. Or you can get it on the net free ofcharge fromftp://ftp.lcs.mit.edu/pub/lcs-pubs/tr.outbox/MIT-LCS-TR-494.ps.gz .

You may also look at the program’s web-sitehttp://www.xplot.org for the latest version of the program.

Basic UsageViewing 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 keeprepeating 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-outlevel by level popping out the stack. The Middle-Mouse button (clicking and dragging) lets you scroll the graph. TheRight-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, forexample) 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 yousee 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 PostscriptClicking the Left-Mouse Button with theSHIFT key pressed, drops a postscript version of the graph being viewed inthe working directory. The postscript files are namedTitle.PS.# whereTitle is the title of the graph and # is aserial number that gets from 0, 1, . . . used so that files do not overwritten accidentally in the working directory.

Clicking the Middle-Mouse Button with theSHIFT key pressed drops a postscript file of smaller size that is good forincluding in a paper, for example. Clicking the Right-Mouse Button with theSHIFT key pressed also drops a smallersize postscript file, but the graph is made smaller vertically.

77

APPENDIX

C

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 30 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 CongestionNotification) bits defined in the IP header as per RFC 3168 [?].

TCP Header Structure

0 1 2 30 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 theCWR(Congestion Window Reduced) andECE(ECN-Echo) flag bitsdefined for the TCP header as per RFC 3168 [?].

UDP Header Structure

0 1 2 30 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

D

License

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

GNU Free Documentation LicenseVersion 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 senseof freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, eithercommercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get creditfor 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 thesame 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 freedocumentation: a free program should come with manuals providing the same freedoms that the software does. Butthis License is not limited to software manuals; it can be used for any textual work, regardless of subject matteror whether it is published as a printed book. We recommend this License principally for works whose purpose isinstruction 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 holdersaying 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 suchmanual or work. Any member of the public is a licensee, and is addressed as ”you”. You accept the license if youcopy, 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 copiedverbatim, 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 therelationship of the publishers or authors of the Document to the Document’s overall subject (or to related matters) andcontains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook ofmathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historicalconnection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political positionregarding 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 InvariantSections. 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 thenotice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and aBack-Cover Text may be at most 25 words.

A ”Transparent” copy of the Document means a machine-readable copy, represented in a format whose specificationis available to the general public, that is suitable for revising the document straightforwardly with generic text editorsor (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 inputto text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, hasbeen arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is notTransparent 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, PostScriptor PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaqueformats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XMLfor which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScriptor 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 anytitle page as such, ”Title Page” means the text near the most prominent appearance of the work’s title, preceding thebeginning of the body of the text.

A section ”Entitled XYZ” means a named subunit of the Document whose title either is precisely XYZ or containsXYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific sectionname mentioned below, such as ”Acknowledgements”, ”Dedications”, ”Endorsements”, or ”History”.) To ”Preservethe Title” of such a section when you modify the Document means that it remains a section ”Entitled XYZ” accordingto this definition.

The Document may include Warranty Disclaimers next to the notice which states that this License applies to theDocument. These Warranty Disclaimers are considered to be included by reference in this License, but only as regardsdisclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect onthe meaning of this License.

2. VERBATIM COPYING

You may copy and distribute the Document in any medium, either commercially or noncommercially, provided thatthis License, the copyright notices, and the license notice saying this License applies to the Document are reproducedin all copies, and that you add no other conditions whatsoever to those of this License. You may not use technicalmeasures to obstruct or control the reading or further copying of the copies you make or distribute. However, you mayaccept compensation in exchange for copies. If you distribute a large enough number of copies you must also followthe 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, numberingmore than 100, and the Document’s license notice requires Cover Texts, you must enclose the copies in covers thatcarry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on theback cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front covermust present the full title with all words of the title equally prominent and visible. You may add other material on thecovers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document andsatisfy 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 asfit 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 amachine-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 networkprotocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you musttake reasonably prudent steps, when you begin distributionof Opaque copies in quantity, to ensure that this Transparentcopy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaquecopy (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 largenumber 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 roleof the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy ofit. 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 previousversions (which should, if there were any, be listed in the History section of the Document). You may use the same titleas 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 withat least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless theyrelease you from this requirement. C. State on the Title page the name of the publisher of the Modified Version, asthe publisher. D. Preserve all the copyright notices of the Document. E. Add an appropriate copyright notice for yourmodifications adjacent to the other copyright notices. F. Include, immediately after the copyright notices, a licensenotice giving the public permission to use the Modified Version under the terms of this License, in the form shown inthe Addendum below. G. Preserve in that license notice the full lists of Invariant Sections and required Cover Textsgiven 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 theModified Version as given on the Title Page. If there is no section Entitled ”History” in the Document, create onestating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describingthe Modified Version as stated in the previous sentence. J. Preserve the network location, if any, given in the Documentfor public access to a Transparent copy of the Document, and likewise the network locations given in the Documentfor previous versions it was based on. These may be placed in the ”History” section. You may omit a network locationfor a work that was published at least four years before the Document itself, or if the original publisher of the versionit refers to gives permission. K. For any section Entitled ”Acknowledgements” or ”Dedications”, Preserve the Title ofthe section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/ordedications given therein. L. Preserve all the Invariant Sections of the Document, unaltered in their text and in theirtitles. 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 sectionto 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 andcontain no material copied from the Document, you may at your option designate some or all of these sections asinvariant. To do this, add their titles to the list of Invariant Sections in the Modified Version’s license notice. Thesetitles must be distinct from any other section titles.

You may add a section Entitled ”Endorsements”, provided it contains nothing but endorsements of your ModifiedVersion by various parties–for example, statements of peer review or that the text has been approved by an organizationas 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-CoverText, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and oneof 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 youare acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from theprevious 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 publicityfor 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 section4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of theoriginal 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 bereplaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, makethe title of each such section unique by adding at the end of it, in parentheses, the name of the original author orpublisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the listof 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 onesection 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 replacethe 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, providedyou insert a copy of this License into the extracted document, and follow this License in all other respects regardingverbatim 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 ona volume of a storage or distribution medium, is called an ”aggregate” if the copyright resulting from the compilationis not used to limit the legal rights of the compilation’s users beyond what the individual works permit. When theDocument is included in an aggregate, this License does not apply to the other works in the aggregate which are notthemselves 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 lessthan one half of the entire aggregate, the Document’s Cover Texts may be placed on covers that bracket the Documentwithin the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they mustappear 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 termsof 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 InvariantSections. You may include a translation of this License, and all the license notices in the Document, and any WarrantyDisclaimers, provided that you also include the original English version of this License and the original versions ofthose notices and disclaimers. In case of a disagreement between the translation and the original version of this Licenseor a notice or disclaimer, the original version will prevail.

If a section in the Document is Entitled ”Acknowledgements”, ”Dedications”, or ”History”, the requirement (section4) 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 terminateyour rights under this License. However, parties who have received copies, or rights, from you under this License willnot 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 timeto time. Such new versions will be similar in spirit to the present version, but may differ in detail to address newproblems 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 particularnumbered version of this License ”or any later version” applies to it, you have the option of following the terms andconditions either of that specified version or of any later version that has been published (not as a draft) by the FreeSoftware Foundation. If the Document does not specify a version number of this License, you may choose any versionever 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 thefollowing 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 underthe terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free SoftwareFoundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license isincluded 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 parallelunder your choice of free software license, such as the GNU General Public License, to permit their use in freesoftware.

85

tcpdump manual

Documents