TCPTRACE Manual

Manikantan Ramadas mramadas@irg.cs.ohiou.edu

24 August 2003

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

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

.

. . . . . . . . . . . . . . . .1 UDP Analysis . . . . . . . . . . . . . . . . . . . 39 7. . . . . . . . . . . . . . . . . 45 45 46 47 48 9 Modules 51 9.CONTENTS 1 Preface 2 Getting Started 2. . . . . . . . . . . . . . . . . . 4. . . . . . . . . . . . . . . . . . . . . . . . . . .2 Using tcptrace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4 Outstanding Data Graph 5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2 Graphing Control . . . . . . . . . .1 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6 Time-Line Graph . . . . . . .2 Real-Time Analysis 8. . . . . . 51 9. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2 HTTP Module . . . . . . . . . . . . . . . .1 Installing tcptrace . . . . . . 8. . . . . . . . . . .3 RTT Graph . . . . . . . . . . . . . . 40 8 Miscellany 8. . . . 35 7 Extended Options 39 7. .3 Packet Details . . . . . . . . . . 4. . . . .3 Warning Control . . . . . . . . . . .1 Detailed Stats . . . .5 Segment Size Graph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5. . . . . . . . . . . . . . . . . . . . .2 RTT Stats . . . . . . . . . . . . . . .1 Basic Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 Basic Usage 4 Detailed Usage 4. . . . . . . . . . 61 i . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2 Throughput Graph . . . . .7 Miscellany . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 6. . . . . . . . . . . . . . . . . . 5 Graphing 5. . . . . . . . . . 5. . . . . . . . . . . . . . . 1 3 3 3 5 7 7 10 13 15 15 24 24 24 28 28 29 6 Filtering Connections 33 6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1 TRAFFIC Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1 Time Sequence Graph . . . . . . . . . . . . . 5. . . . 40 7. . . . .2 Advanced Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4 Other Miscellany . . . . . . . . 8. . . . . . . . . . . . . .3 CWND Stats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . .9. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4 9. . . .3 9. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5 9. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 67 68 69 73 77 79 81 A Arguments QR B XPLOT QR C Protocol QR D License ii . . . . . . . . . . . . . . . . . . . . . . . COLLIE Module Real-Time Module Writing Modules . . . . . . . . . . . . . . . . . . . . .6 SLICE Module . . .

However. and there are nice books that do this already.. “pure ACK” etc. However it would be clear from context. explain its capabilities.. are not familiar to you. • Miscellany Explains all the miscellaneous things the program can do. the terms “segments” and “packets” have been used interchangeably in the manual. and the fields in the long output format. I recommend my favorite book [?] if you need to understand the TCP/IP protocol suite better.g. in a slight abuse of parlance. 1 . The manual is organized into chapters with the goal of making them as modular as possible so that they can be read independently of one another. the goal is not to explain the working of the TCP/IP protocol suite itself. like minimal UDP analysis. The syntactical definitions of common protocol headers are provided in Appendix C Protocol Quick Reference. and how to generate them. • Filtering Connections Explains how to filter-out or filter-in the connection(s) of interest. Some sections of the manual have been drawn directly from his A manuscript. • Basic Usage Explains the basic output generated by tcptrace . how to get it do all it can do. Hopefully it would not be a cause of concern. and the details from the environment that tcptrace uses. You may find answers to some of your xplot related questions in Appendix B: XPLOT Quick Reference. • Detailed Usage Explains how to perform more detailed analysis. etc. and briefly on how to write your own modules. for e. you might dive straight into Appendix A: Arguments Quick Reference. • Modules Explains the behavior of the modules distributed with tcptrace . • Extended Options Explains what each of the extended options mean and how to turn them on/off. if we say “TCP packets” we mean “TCP segments”. etc. Thanks Thanks are due to my friend Avinash S. • Graphing Explains the graphs that can be generated.CHAPTER ONE Preface The goal of this manual is to document the tcptrace program. If you are a tcptrace Power-user familiar with the program. Finally. and are just looking for the option that generates the output you need. “CWND”. or if commonly used TCP/IP parlance like “SACK”. and how they are calculated. what all the output it generates mean. Lakhiani for working on an earlier version of the manual and for getting the Documentation project kick-started. Thanks are also due to the Python Software Foundation for the LTEX 2ε style files from the Python Documentation Project used for generating this manual. to explain how to get it installed. It consists of the following chapters : • Getting Started Explains how to get tcptrace up and running on your system. printing out packet details.

2 .

2 Using tcptrace tcptrace can be run on a network dumpfile trivially as in tcptrace dumpfile where dumpfile is a file containing traffic captured from the network.tcptracerc file in your home directory. However windows ports tend only to be made for stable releases of the program.Y. tcptrace can be passed multiple command-line options to perform various tasks as explained in subsequent chapters. etherpeek.tcptrace.org/windows.Z. tcptrace understands various network dumpfile formats like tcpdump.tcptrace.1 Installing tcptrace tcptrace can be downloaded from the project web-site http://www. you may store them in .Z. More information on the Windows version of the program can be found in : http://www. tcptrace reads the 3 .tar Now. ns. nlanr.Z directory and install tcptrace with the following steps : • .Y. Instructions for doing so may be found in the download page at http://www.tar.CHAPTER TWO Getting Started 2. A port of the tcptrace program has also been made to the Windows platforms.html .org/download. snoop. or set the TCPTRACEOPTS environment variable with the options.Y. netm.gz • tar xvf tcptrace-X.html .org/download. or UNIX compress (Z) formats. as tcptrace can uncompress them on the fly. BZIP2 (bz2).Y.Z./configure • make • make install (as super-user) You may also download cutting-edge version of tcptrace from the project’s CVS repository. If you want tcptrace to always start processing with certain command-line options.html .gz) with the following steps : • gunzip tcptrace-X. netscout. enter the tcptrace-X.tar. Installing the stable version of tcptrace follows the typical procedure used to install most open-source software on UNIX-based systems. 2. Dumpfiles in these formats can also be compressed in GnuZIP (gz). Unzip and Untar the tar-ball (tcptrace-X.tcptrace.

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

and when it was compiled.cs.cs. 30 packets were seen in the a2b direction (pride.ohiou.dmp. for example) and service names (http. and a17-112-152-32.cs.edu ==> pride.dmp 1 arg remaining. TCP connections may also be reported as reset if the connection was closed with an RST segment.edu at TCP port ssh (22).ohiou. tcptrace is run on dumpfile tigris.037900.edu for example).ohiou.180796 TCP connection info: 1: pride. use the -s option.. it generates output similar to the following : Beluga:/Users/mani> tcptrace tigris.edu. or unidirectional if traffic was seen flowing in only one direction.cs. 5 .e.dmp’ Ostermann’s tcptrace -. starting with ’tigris.apple. tcptrace looked up names (elephus. The next line tells that a total of 87 packets were seen in the dumpfile and all the 87 TCP packets (in this case) were traced. The following line indicates the trace file elapsed time i. 2295 pkts/sec analyzed trace file elapsed time: 0:00:12.ohiou. the time tcptrace took to process the dumpfile. 87 TCP packets traced elapsed wallclock time: 0:00:00.cs.edu:54736 .edu).edu ==> elephus. 2003 87 packets seen. SYN and FIN segments opening and closing the connection were traced.ohiou.com at TCP port http (80).ohiou. The next line tells that the elapsed wallclock timei.ohiou. The initial lines tell that the file tcptrace is processing currently is tigris.cs.cs.e.cs.com:http (c2d) 30> 12> 30< 15< (complete) (complete) In the above example.edu at TCP port 54736.dmp. In the above example the two connections are labeled a2b and c2d respectively. If you need name lookups but would rather have the short names of machines (elephus instead of elephus.CHAPTER THREE Basic Usage When tcptrace is run trivially on a dumpfile.ohiou. and the average speed in packets per second taken for processing.ohiou. Such name and service lookups can be turned off with the -n option to make tcptrace process faster. the version of tcptrace running.edu at TCP port 54735. tcptrace uses a labeling scheme to refer to individual connections traced.edu) and 30 packets were seen in the b2a direction (elephus. The above brief output generated by tcptrace can also be generated with the -b option.4. Similarly the second connection was seen between machines pride.e.cs..ohiou. the duration of packet capture of the dumpfile calculated as the duration between the capture of the first and last packets.cs.elephus.ohiou.a17-112-152-32.5 -. for example) involving a DNS name lookup operation.edu:ssh (a2b) 2: pride.cs.edu:54735 . The first connection was seen between machines pride. The two connections are reported as complete indicating that the entire TCP connection was traced i. In the above example. The subsequent lines indicate the two TCP connections traced from the dumpfile.apple.cs.Fri Jun 13.version 6.ohiou. For the first connection. and elephus..

6 .

32 TCP packets traced elapsed wallclock time: 0:00:00.4. 843 pkts/sec analyzed trace file elapsed time: 0:00:00.gz 1 arg remaining.6 -.318528 2003 elapsed time: 0:00:00.com:http complete conn: yes first packet: Thu Jul 10 19:12:54.914101 2003 last packet: Thu Jul 10 19:12:55.gz’ Ostermann’s tcptrace -.Tue Jul 1.cs.404427 total packets: 32 filename: malus.version 6.dmp.gz a->b: b->a: total packets: 16 total packets: ack pkts sent: 15 ack pkts sent: pure acks sent: 13 pure acks sent: sack pkts sent: 0 sack pkts sent: dsack pkts sent: 0 dsack pkts sent: max sack blks/ack: 0 max sack blks/ack: unique bytes sent: 450 unique bytes sent: actual data pkts: 1 actual data pkts: actual data bytes: 450 actual data bytes: rexmt data pkts: 0 rexmt data pkts: rexmt data bytes: 0 rexmt data bytes: zwnd probe pkts: 0 zwnd probe pkts: zwnd probe bytes: 0 zwnd probe bytes: outoforder pkts: 0 outoforder pkts: pushed data pkts: 1 pushed data pkts: SYN/FIN pkts sent: 1/1 SYN/FIN pkts sent: req 1323 ws/ts: Y/Y req 1323 ws/ts: 16 16 2 0 0 0 18182 13 18182 0 0 0 0 0 1 1/1 Y/Y 7 . The -l option produces output similar to the one shown in this example.CHAPTER FOUR Detailed Usage 4.edu:59518 host b: a17-112-152-32.dmp.037948.1 Detailed Stats tcptrace can produce detailed statistics of TCP connections from dumpfiles when given the -l or the long output option. 2003 32 packets seen.apple. Beluga:/Users/mani> tcptrace -l malus. starting with ’malus.ohiou.404427 TCP connection info: 1 TCP connection traced: TCP connection 1: host a: elephus.dmp.

the total bytes of data sent excluding retransmitted bytes and any bytes sent doing window probing. and the number of packets seen. the connection was traced in its entirety with the SYN and FIN segments of the connection observed in the dumpfile.9 44957 pkts bytes bytes bytes bytes bytes bytes bytes times bytes bytes pkts bytes bytes bytes pkts secs ms Bps The initial lines of output are similar to the brief output explained in Chapter 3.. followed by the lifetime of the connection. • 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.apple. • total packets The total number of packets seen. The time at which the first and last packets of the connection were captured is reported. i. Detailed Usage . • unique bytes sent The number of unique bytes sent.edu:59518 a17-112-152-32. 8 Chapter 4. followed by the multiple TCP statistics for the forward (a2b) and the reverse (b2a) directions. • sack pkts sent The total number of ack packets seen carrying TCP SACK [?] blocks.e.com:http The following lines indicate that the connection was seen to be complete i. the filename currently being processed is listed.149 99.cs. Note that this includes bytes from retransmissions / window probe packets if any. for the a2b direction.e. The following lines indicate that the hosts involved in the connection and their TCP port numbers are: host a: host b: elephus.7 1113 pkts bytes bytes bytes bytes bytes bytes bytes times bytes bytes pkts bytes bytes bytes pkts secs ms Bps adv wind scale: req sack: sacks sent: urgent data pkts: urgent data bytes: mss requested: max segm size: min segm size: avg segm size: max win adv: min win adv: zero win adv: avg win adv: initial window: initial window: ttl stream length: missed data: truncated data: truncated packets: data xmit time: idletime max: throughput: 0 N 0 0 0 1460 1448 806 1398 33304 33304 0 33304 1448 1 18182 0 17792 13 0. • dsack pkts sent The total number of sack packets seen that carried duplicate SACK (D-SACK) [?] blocks. We explain the TCP parameter statistics in the following.000 103.ohiou. • ack pkts sent The total number of ack packets seen (TCP segments seen with the ACK bit set). • max sack blks/ack The maximum number of sack blocks seen in any sack packet. Then. Similar explanation would hold for the b2a direction too..adv wind scale: req sack: sacks sent: urgent data pkts: urgent data bytes: mss requested: max segm size: min segm size: avg segm size: max win adv: min win adv: zero win adv: avg win adv: initial window: initial window: ttl stream length: missed data: truncated data: truncated packets: data xmit time: idletime max: throughput: 0 Y 0 0 0 1460 450 450 449 40544 5840 0 23174 450 1 450 0 420 1 0. • pure acks sent The total number of ack packets seen that were not piggy-backed with data (just the TCP header and no TCP data payload) and did not have any of the SYN/FIN/RST flags set.

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

• avg win adv The average window advertisement seen. starting with ’indica. Note that the ack packet from the other endpoint is the first ack acknowledging some data (the ACKs part of the 3-way handshake do not count).dmp. as per RFC 1323[?]. giving the length of the data stream seen. this calculation is invalid and an “NA” (Not Available) is printed. • truncated data The truncated data. If the connection endpoints negotiated window scaling.e.092645 TCP connection info: 1 TCP connection traced: TCP connection 1: 10 Chapter 4. • idletime max Maximum idle time.128422. truncating most of the packet data. 4. • throughput The average throughput calculated as the unique bytes sent divided by the elapsed time i. and is printed only if the connection was complete (both the SYN and FIN packets were seen). this would amount to truncated data of 1500 − 64 = 1436bytes for a packet. calculated as the total bytes of data truncated during packet capture. with tcpdump. the snaplen option can be set to 64 (with -s option) so that just the headers of the packet (assuming there are no options) are captured.5 -.e..version 6. calculated as the difference between the times of capture of the first and last packets carrying non-zero TCP data payload. 1191 pkts/sec analyzed trace file elapsed time: 0:00:19. Note that this calculation is aware of sequence space wrap-arounds.gz’ Ostermann’s tcptrace -. In an Ethernet with maximum segment size of 1500 bytes.1). • missed data The missed data. and any retransmitted packets in this stage are excluded.Fri Jun 13. Detailed Usage .4. • data xmit time Total data transmit time. the value reported in the unique bytes sent field divided by the elapsed time (the time difference between the capture of the first and last packets in the direction). • truncated packets The total number of packets truncated as explained above. calculated as the sum of all window advertisements divided by the total number of packets seen. 153 TCP packets traced elapsed wallclock time: 0:00:00. For example. The following fields of output are produced along with the output generated by the -l option. the window advertisements in the SYN packets are excluded since the SYN packets themselves cannot have their window advertisements scaled. surya:/home/mani/tcptrace-manual> tcptrace -lr indica. 2003 153 packets seen. calculated as the maximum time between consecutive packets seen in the direction. • ttl stream length The Theoretical Stream Length. the number of bytes seen in the initial flight of data before receiving the first ack packet from the other endpoint.dmp.gz 1 arg remaining. calculated as the difference between the ttl stream length and unique bytes sent. this average is calculated as the sum of all window-scaled advertisements divided by the number of window-scaled packets seen. This is calculated as the difference between the sequence numbers of the SYN and FIN packets. Note that in the window-scaled case. • initial window The total number of bytes sent in the initial window i. If the connection was not complete..2 RTT Stats RTT (Round-Trip Time) statistics are generated when the -r option is specified along with the -l option (Section 4. • initial window The total number of segments (packets) sent in the initial window as explained above.

1 0.0 0.0 0.2 ms max retr time: avg retr time: 380.0 0 ms ms ms ms ms ms ms ms post-loss acks: post-loss acks: For the following 5 RTT statistics.5 79. .168. Note : The former condition invalidates RTT samples due to the retransmission ambiguity problem. RTT Stats 11 .7 ms ms ms ms ms ms ms ms RTT from 3WHS: RTT RTT RTT RTT RTT full_sz full_sz full_sz full_sz full_sz smpls: min: max: avg: stdev: 75. and not necessarily ack-ing the packet in question. . . tcptrace is pretty smart about choosing only valid RTT samples.ent. and the latter condition invalidates RTT samples since it could be the case that the ack packet could be cumulatively acknowledging the retransmitted packet. ambiguous acks: 1 ambiguous acks: RTT min (last): 76.092645 total packets: 153 filename: indica.0 ms sdv retr time: 0 0. .1 204.0 0.2 RTT RTT RTT RTT RTT samples: min: max: avg: stdev: 62 94 Bps 47 0.875583 2002 elapsed time: 0:00:19.0 0 0 0 0 0. .6 44.0.2 ms min retr time: max retr time: 380.0 0.0 ms 1 79.1 0. .0 108.5 79. .0 ms RTT sdv (last): segs cum acked: 0 segs cum acked: duplicate acks: 0 duplicate acks: triple dupacks: 0 triple dupacks: max # retrans: 1 max # retrans: min retr time: 380.0 ms ms ms ms ms ms ms ms • RTT samples The total number of Round-Trip Time (RTT) samples found.3 ms RTT max (last): RTT avg (last): 76.8 8.70:32791 host b: webco.gz a->b: b->a: total packets: 91 total packets: .1 38.5 0.0 0.3 ms RTT avg (last): RTT sdv (last): 0.dmp. it is required that the packet being acknowledged was not retransmitted. . Times are taken from the last instance of a segment. 4. Further. and that no packets that came before it in the sequence space were retransmitted after the packet was transmitted.0 0.1 0.1 ms 1 0. only ACKs for multiply-transmitted segments (ambiguous ACKs) were considered. throughput: 10 Bps throughput: RTT RTT RTT RTT RTT samples: min: max: avg: stdev: 48 74.edu:23 complete conn: yes first packet: Thu Aug 29 18:54:54.0 0 RTT from 3WHS: RTT RTT RTT RTT RTT full_sz full_sz full_sz full_sz full_sz smpls: min: max: avg: stdev: 0. .host a: 192.1 14. An RTT sample is found only if an ack packet is received from the other endpoint for a previously transmitted packet such that the acknowledgment value is 1 greater than the last sequence number of the packet.2 ms avg retr time: sdv retr time: 0. . .3 ms RTT min (last): RTT max (last): 76.ohiou.782937 2002 last packet: Thu Aug 29 18:55:13.2.

4 BSD Lite TCP Stack [?] : o The ack packet has the biggest ACK (acknowledgment number) ever seen. • RTT full sz stdev The standard deviation of full-size RTT samples. Detailed Usage . • ambiguous acks.. calculated from the RTT samples of fullsize segments. An ack packet is found to be a duplicate ack based on this definition used by 4. and at least one packet occurring before the packet acknowledged. • RTT max The maximum RTT sample seen. This older behavior may be emulated (if necessary at all) with the --turn off BSD dupack option.e. calculated straightforward-ly as the sum of all the RTT values found divided by the total number of RTT samples. Note : older versions of tcptrace (until version 6. The statistics below are calculated from the time of capture of the last transmitted instance of the segment. • segs cum acked The count of the number of segments that were cumulatively acknowledged and not directly acknowledged. • RTT avg The average value of RTT found. In other words. • ambiguous acks is the total number of such ambiguous acks seen. RTT max. The following RTT min. RTT min.2) used a legacy algorithm using just the first condition amongst the four listed above.4. RTT avg. RTT sdv fields represent the minimum. and standard deviation respectively of the RTT samples calculated from ambiguous acks. assuming that the SYN packets of the connection were captured. Full-size segments are defined to be the segments of the largest size seen in the connection. • post-loss acks The total number of ack packets received after losses were detected and a retransmission occurred. a post-loss ack is found to occur when an ack packet acknowledges a packet sent (acknowledgment value in the ack pkt is 1 greater than the packet’s last sequence number). • max # retrans The maximum number of retransmissions seen for any segment during the lifetime of the connection. o The advertised window carried in the ack packet should not change from the last window advertisement. to treat an ack as duplicate ack. • RTT from 3WHS The RTT value calculated from the TCP 3-Way Hand-Shake (connection opening) [?]. RTT avg. maximum. Note that these samples are not considered in the RTT samples explained above. • RTT full sz min The minimum full-size RTT sample. • duplicate acks The total number of duplicate acknowledgments received. • RTT full sz smpls The total number of full-size RTT samples.• RTT min The minimum RTT sample seen. the ack packet is received after we observed a (perceived) loss event and are recovering from it. • RTT full sz max The maximum full-size RTT sample. o There must be some outstanding data. 12 Chapter 4. • triple dupacks The total number of triple duplicate acknowledgments received (three duplicate acknowledgments acknowledging the same segment). the segment being ack-ed was retransmitted and it is impossible to determine if the ack is for the original or the retransmitted packet. RTT max. average. a condition commonly used to trigger the fast-retransmit/fastrecovery phase of TCP. RTT sdvThese fields are printed only if there was at least one ack received that was ambiguous due to the retransmission ambiguity problem i. was retransmitted later. • RTT full sz avg The average full-size RTT sample. o The ack should be pure (carry zero tcp data payload). • RTT stdev The standard deviation of the RTT samples. More precisely.

dat (for the second TCP connection traced) etc. 32 TCP packets traced elapsed wallclock time: 0:00:00. in the working directory.gz a->b: b->a: total packets: 16 total packets: . . .com:80 complete conn: yes first packet: Thu Jul 10 19:12:54.3.404427 TCP connection info: 1 TCP connection traced: TCP connection 1: host a: elephus. . • max retr time The maximum time seen between any two (re)transmissions of a segment.914101 2003 last packet: Thu Jul 10 19:12:55.apple. Note that only valid RTT samples (as counted in the RTT Samples field listed above) are dumped. 2003 32 packets seen.026658.6 -.4.dmp This generates files of the form a2b rttraw.404427 total packets: 32 filename: malus. are explained below.cs. • sdv retr time The standard deviation of the retransmission-time samples obtained from all the retransmissions.gz 1 arg remaining.• min retr time The minimum time seen between any two (re)transmissions of a segment amongst all the retransmissions seen. 16 4. 4.318528 2003 elapsed time: 0:00:00. • avg retr time The average time seen between any two (re)transmissions of a segment calculated from all the retransmissions.gz’ Ostermann’s tcptrace -.dat (for both directions of the first TCP connection traced). Each of the datafiles contain lines of the form : seq# rtt where seq# is the sequence number of the first byte of the segment being acknowledged (by the ack packet that contributed this RTT sample) and rtt is the RTT value in milli-seconds of the sample. starting with ’malus. .version 6. The raw RTT samples found can also be dumped into data files with the -Z option as in tcptrace -Z file. CWND Stats 13 . c2d rttraw.ohiou.dmp. 1200 pkts/sec analyzed trace file elapsed time: 0:00:00.dat and b2a rttraw.3 CWND Stats tcptrace reports statistics on the estimated congestion window with the -W option when used in conjunction with the -l option. the outstanding unacknowledged data is used to estimate the congestion window.dmp.dmp. Since there is no direct way to determine the congestion window at the TCP sender.Tue Jul 1. surya:/home/mani/tcptrace-manual> tcptrace -lW malus.dat and d2c rttraw.edu:59518 host b: A17-112-152-32. The 4 new statistics produced by the -W option in addition to the detailed statistics reported due to the -l option. .

Detailed Usage . . .2 = 2916. . if the outstanding data (odata) was 500 bytes for the first 0. For example. .2 seconds. . throughput: 22091 bytes 451 1 31 113 bytes bytes bytes bytes . . 1000 bytes for the next 1 second. .2 = 1041. • avg owin The average outstanding unacknowledged data (in bytes). . .1) + (1000 x 1) + (2000 x 0. . throughput: 33304 bytes 1449 1 1213 682 bytes bytes bytes bytes 450 bytes 1448 bytes 1113 Bps 44957 Bps • max owin The maximum outstanding unacknowledged data (in bytes) seen at any point in time in the lifetime of the connection. .1)) / 1. a value less indicative of the outstanding data observed during most of the connection’s lifetime. calculated from the sum of all the outstanding data byte samples (in bytes) divided by the total number of samples. • min non-zero owin The minimum (non-zero) outstanding unacknowledged data (in bytes) seen. and 2000 bytes for the last 0. • wavg owin The weighted average outstanding unacknowledged data seen. Note that the straight-forward average reported in avg owin would have been (500+1000+2000)/1. ..1 seconds.67 bytes.67 bytes an estimate closer to 1000 bytes which was the outstanding data for the most of the lifetime of the connection. wavg owin= ((500 x 0. . 14 Chapter 4. avg win adv: max owin: min non-zero owin: avg owin: wavg owin: initial window: . . avg win adv: max owin: min non-zero owin: avg owin: wavg owin: initial window: .1 seconds of a connection that lasted 1.

CHAPTER FIVE Graphing tcptrace can generate six different types of graphs illustrating various parameters of a TCP connection. and the slope of this curve gives the throughput over time. A section of this graph (zoomed in with xplot) is shown in Figure 5.xpl and d2c *. A sample Time Sequence graph is shown in Figure 5. the SYN marks the sequence number and the time when a SYN packet was sent.1 Time Sequence Graph Time Sequence graphs show the general activity and events that happen during the lifetime of a connection. 5. the c2d *. and the data files can be viewed with the xplot program as in xplot a2b_tsg.org/jPlot developed by Avinash Lakhiani. These graphs can be viewed with Tim Shepard’s xplot program or with the Java version of the same program called jPlot from http://www. (It is drawn at the sequence number value corresponding to the sum of the acknowledgment number and the receive window advertised from the last ACK packet received. • Red Arrows (R) represent retransmitted segments with the up and down arrows similarly representing the sequence numbers of the last and first bytes of the segment.xpl data files in the working directory when the graphing options are given. tcptrace leaves *.3.xpl. The files a2b *. and so on. • White Arrows represent segments sent. These graphs are named as X2Y tsg. Further zooming into the beginning of the connection with xplot we find Figure 5. • Little Yellow Ticks track the window advertisements that were the same as the last advertisement. The Y-axis represents sequence number space and the X-axis represents time. • Green Line keeps track of the ACK values received from the other endpoint.tcptrace.xpl and b2a *. • Yellow Line tracks the receive window advertised from the other endpoint.xpl are the graphing data files for both the directions of traffic of the first connection.xpl tcptrace uses the same naming scheme observed in previous chapters to generate the graphs. The graphs and the options for tcptrace that generate them.) • Little Green Ticks track the duplicate ACKs received. are explained below. The up and down arrows represent the sequence numbers of the last and first bytes of the segment respectively.1. Here. 15 .2 illustrating the following features.xpl files are for the second connection. and can be generated with the -S option.

1: Time Sequence Graph #1 16 Chapter 5. Graphing .Figure 5.

Figure 5. Time Sequence Graph 17 .2: Time Sequence Graph #2 5.1.

3: Time Sequence Graph #3 18 Chapter 5.Figure 5. Graphing .

4 is a section of a TCP connection being closed. Figure 5. • RST IN. • PUSH segments. giving rise to a cross). • Little crosses (x) These are segments sent with zero TCP data payload (the down and up arrows of the segment coincide. • FIN marks a FIN segment sent in the direction. a RST OUT is marked in the graph. i. and a RST IN is marked in the Time Sequence graph of the opposite direction of the connection. RST OUT: When a RST segment is sent. ?] blocks found in ACK packets are represented as purple lines with an S on top as shown in Figure 5. Time Sequence Graph 19 .The graph shown in Figure 5.4: Time Sequence Graph #4 Here.5. • SACK [?.6.e. TCP segments sent with the PUSH flag set are represented with a Diamond in place of the up arrow as shown in Figure 5.1.. 5.

5: SACK blocks 20 Chapter 5.Figure 5. Graphing .

6: PUSH segments 5.1. Time Sequence Graph 21 .Figure 5.

A Time-Sequence graph illustrating this is shown in Figure 5. The Z labels in the graph represent a window advertisement of 0 bytes received from the other endpoint.8. 22 Chapter 5.7: URGENT segments • Window Probing happens when the receiver advertises a window of 0 (typically happens when the application goes dormant and TCP holds on to the allocated window full of received data. This is shown in Figure 5. TCP segments carrying URGENT data with the URG flag set in the TCP header are represented with a red U on top of the segment..e. i. The subsequent P labels indicate the probe packets sent by the sending endpoint to see if the window has opened up yet. Figure 5. Graphing . waiting to be picked up).7. The following other symbols also occur in Time Sequence graphs : • O represents packets received out of order.• URGENT segments.

Time Sequence Graph 23 .8: Window Probing 5.Figure 5.1.

A sample RTT graph is shown in Figure 5. • Green Line tracks the weighted average of outstanding data up to that point.xpl) are generated with the -T option.xpl) are generated with the -R option.xpl) are generated with the -N option. Due to clock granularity. 5.3 RTT Graph RTT (Round Trip Time) graphs (named X2Y rtt. By default the line tracks the past 10 samples (N=10). you may turn them off with the -y option. we use the outstanding unacknowledged data as an estimate. A sample throughput graph is shown in Figure 5. • Blue Line tracks the average outstanding data up to that point. 5. calculated as the average of N previous yellow dots.• HD represent Hardware Duplicates.3.11. Since this cannot be determined accurately. If you find the yellow dots annoying. • 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). For example giving -A5 along with the -T option calculates the throughput from the past 5 yellow dots to draw the line. CWR indicates that the Congestion Window Reduced flag was set in the TCP header of the packet. Hardware Duplicates correspond to link layer retransmissions found when a duplicate packet with same IPv4 identification number and TCP sequence number as a previously observed packet is seen. The graph has throughput in bytes/second on the Y-axis and time on the X-axis. 5. and the red line just connects the dots. while the CE flag indicates that the Congestion Experienced code-point was found in the IP header of the packet. • CWR / CE track Explicit Congestion Notification [?] messages received. • 3 indicates that the received ack packet was the triple duplicate ack. • Red Line tracks the throughput seen from the last few samples. Graphing . there tends to be a lot of banding of the dots. defined as the size of the segment seen divided by the time since the last segment was seen (in this direction). • Yellow Dots represent instantaneous throughput. The Y-axis represents the Outstanding Data in bytes and the X-axis represents time.9.2 Throughput Graph Throughput graphs (named X2Y tput. The idea behind these graphs to estimate the congestion window at the sender. A sample is shown in Figure 5.4 Outstanding Data Graph Outstanding Data graphs (named X2Y owin. The Y-axis represents RTT in milli-seconds and the X-axis represents time. However it can be changed with the -AN option.10. commonly used as the threshold to trigger the TCP fast retransmit/recovery algorithm. 24 Chapter 5. and is as explained in the calculation of the wavg owin field in Section 4. The yellow dots represent RTT samples calculated from non-retransmitted segments. • Red Line represents instantaneous outstanding data samples at various points in the lifetime of the connection.

Outstanding Data Graph 25 .Figure 5.9: Throughput Graph 5.4.

10: RTT Graph 26 Chapter 5. Graphing .Figure 5.

4. Outstanding Data Graph 27 .11: Outstanding Data Graph 5.Figure 5.

xpl 28 Chapter 5.5. The graphs can be generated with the -L option and generates graphs named as X Y tline.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 Illustrated Volume I” by W. Graphing . Richard Stevens [?]. illustrating the activities of connections. • Blue Line represents the average segment size seen up to that point. • Red Line represents the instantaneous segment size samples.12.12: Segment Size The Y-axis represents segment size in bytes and the X-axis represents time. 5.xpl) are generated with the -F option. A sample segment size graph is shown in Figure 5. Figure 5.5 Segment Size Graph Segment size graphs (named X2Y ssize.

For example.7. the X-axis represents the actual time of the connection.xpl files. causing both the axes to begin from 0.xpl in the graphs directory. hardware duplicate indicator (“HD”) The sequence number for the first segment in either direction is absolute. ignoring the negative sign) Graph Features Green Lines The green lines show the segments traveling in the direction a-¿b Yellow Lines The yellow lines show the segments traveling in the direction b-¿a Labels The labels alongside the segments have the following format: TCP Flags (only if set). As you zoom in with xplot. If you want monochrome plots. 5. bytes transmitted). You may wish to use the -output prefix option to fix this. For example. This is generally useful in Time Sequence graphs. use the --output dir option. if you are using the same graphs directory to store the graphs generated from another file mangifera.dmp may get over-written by the new *. For the sake of completeness.dmp would leave all the graphs in the graphs directory. use the -G option. retransmit indicator (“R”). more and more details will become visible. Now.dmp would generate files of the form mangifera a2b tsg.dmp. The fundamental problem with generating these graphs is that the time values for the segments arriving/leaving are available only from the end where the traffic was captured. use the -zx option while generating the graphs. The Y-axis can also be made to begin from 0 with the -zy option. This graph provides a pictorial view of the segments being transmitted in either direction.The Time-Line graphs are still EXPERIMENTAL and are under development.4 shows a section of a Time Sequence graph generated with -zxy option. In all the above graphs. If you want relative time with time beginning at 0. The Y-axis shows increasing time going from the top to bottom of the graph. For example.xpl files from indica. the old *. 5. The X-axis shows the segments being transmitted between the 2 hosts communicating. while the time values of when the packets arrived or left at the other end have to be estimated with some heuristic.7 Miscellany If you want to generate all the graphs. 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. where the sequence offset rather than the actual sequence number values may be desired. The current heuristic is a simple one of adding/subtracting 1/3rd of the rtt. timeouts etc. over the duration of the connection. while the rest are relative to the first segment. sequence number from:sequence number to(difference. Doing this right tends to be a hard problem taking care of conditions like retransmits. If you would rather have the graphs generated be placed in a separate directory. advertised window. use the -M option. tcptrace -G --output_dir=graphs --output_prefix=mangifera_ mangifera. 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. Figure 5. acknowledgment sequence number. the -C option produces color plots (which of course is the default behavior). tcptrace -G --output_dir=graphs indica. and not clutter your working directory. Miscellany 29 .

13: Time-Line Graph #1 30 Chapter 5.Figure 5. Graphing .

Miscellany 31 .14: Time-Line Graph #2 5.7.Figure 5.

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

36:9119 (g2h) 910> 872< 5: 132.132.gz’ Ostermann’s tcptrace -. and perform detailed analysis on them alone.67. 6.36:9080 (e2f) 60> 18< 5: 132. Beluga:/Users/mani/dmpfiles> tcptrace -n -o3.102161.235.67.82:3640 .dmp.235.67.235.132. 6401 TCP packets traced elapsed wallclock time: 0:00:00.235.235.36:9080 (o2p) 40> 9< (complete) (complete) (complete) (complete) (reset) (reset) Using the -o option with 3.1 Basic Filtering The -o option can be used to only look at certain connections.67.67.67.6 -.67.67.132. In such cases.235.5.gz 1 arg remaining.82:3640 .7 as shown below.36:9119 (i2j) 722> 676< 6: 132. 2003 6401 packets seen.235.235.dmp.132.version 6. filters out only the 3rd.dmp.version 6.82:3299 .gz 1 arg remaining.82:2525 .7 rexmit.Tue Jul 1.235.4. starting with ’rexmit.67.235.82:4095 .67. 6401 TCP packets traced elapsed wallclock time: 0:00:00.gz’ Ostermann’s tcptrace -.235.235. This chapter describes how to do such connection filtering.235.132.dmp.67.82:2525 .36:9080 (m2n) 48> 14< 8: 132.4.235. 2003 6401 packets seen.67.36:9080 (a2b) 178> 113< 2: 132.235. For example 8 TCP connections were traced in the file rexmit.132.6 -.235.67.36:9119 (i2j) 722> 676< (complete) 7: 132.235.67.67.CHAPTER SIX Filtering Connections It is commonly the case that the dumpfile captured for analysis by tcptrace has much more connections than the ones you may be interested in.235.82:3299 . and 7th connections out.82:3396 .235.67.67.235.086056.67.132.758299 TCP connection info: 1: 132.132.36:9080 (m2n) 48> 14< (reset) 33 .235.67.5.dmp.235.82:2666 . it could be useful to pick and choose the connections of interest from the dumpfile.36:9080 (e2f) 60> 18< 4: 132. starting with ’rexmit.67. 5th.Tue Jul 1.67. 74381 pkts/sec analyzed trace file elapsed time: 0:20:57.132.67.82:3584 .36:9119 (c2d) 1358> 1311< 3: 132.758299 TCP connection info: 3: 132. 62656 pkts/sec analyzed trace file elapsed time: 0:20:57.gz : Beluga:/Users/mani/dmpfiles> tcptrace -n rexmit.132.36:9080 (k2l) 56> 16< 7: 132.82:1321 .132.

67. Filtering Connections .67.gz 1 arg remaining.dat rexmit.092103.235.132.67.67.36:9080 (m2n) 48> 14< 8: 132.67.67.235.67.82:3396 .36:9119 (c2d) 1358> 1311< (complete) 3: 132.67.4.36:9080 (a2b) 178> 113< (complete) 2: 132.82:4095 .dmp. by combining both the -o and -G options.235.36:9119 (c2d) 1358> 1311< (complete) 3: 132.dmp.gz 1 arg remaining.dmp.67.dmp.4. 2003 6401 packets seen. The following example saves just the connections 4-6 into the file filt rexmit. Beluga:/Users/mani/dmpfiles> tcptrace -n -o1-3.82:2525 .67.67. The -o option opens and reads from a file if the character following the -o is not a numeral.version 6. Beluga:/Users/mani/dmpfiles> tcptrace -n -oconn.235. This can be done with the -O option.235.82:4095 . The following example illustrates how you could specify a range of connections with the -o option to get only the connections 1-3.235.36:9080 (k2l) 56> 16< 7: 132.235.235.132.gz’ Ostermann’s tcptrace -.dat file had just the line 1-3.36:9080 (m2n) 48> 14< 8: 132.dmp.5. Beluga:/Users/mani/dmpfiles> tcptrace -n -o4-6 -Ofilt_rexmit.6 -.Tue Jul 1. 7-8 from the dumpfile.gz’ Ostermann’s tcptrace -.7 -l rexmit.82:3396 . 6401 TCP packets traced 34 Chapter 6.235.Tue Jul 1.67.67.dat for example and pass it to the -o option.091752.235. to generate the detailed statistics of only these connections as in tcptrace -n -o3.version 6. starting with ’rexmit.67.Tue Jul 1.132.82:1321 .132.132.67.235.235.235. 6401 TCP packets traced elapsed wallclock time: 0:00:00.132. 6-8 it causes connections 1-3 and 6-8 alone to be filtered out.gz’ Ostermann’s tcptrace -.82:1321 . starting with ’rexmit.82:3299 .67. 69498 pkts/sec analyzed trace file elapsed time: 0:20:57.132.67.67.132.235.82:3584 .67.132.36:9080 (o2p) 40> 9< (reset) You may also store the connection numbers in a data file conn.67.dmp rexmit.1) for example.36:9080 (e2f) 60> 18< 6: 132.758299 TCP connection info: 1: 132.82:3640 .5.758299 TCP connection info: 1: 132.235. when the conn.version 6.132. 6401 TCP packets traced elapsed wallclock time: 0:00:00.67.235.235. For example.235.82:3640 . 2003 6401 packets seen.36:9080 (o2p) 40> 9< Sometimes it could be useful to save only the filtered connections into a new dumpfile.dmp.4.36:9080 (a2b) 178> 113< (complete) 2: 132.7-8 rexmit.6 -.235. 69764 pkts/sec analyzed trace file elapsed time: 0:20:57.132.67. 5.gz 1 arg remaining.gz Similarly graphs can be generated for the connections you are interested in alone for example.dmp.235.235.235.dmp.36:9080 (e2f) 60> 18< 5: 132.132.67. 2003 6401 packets seen. starting with ’rexmit.36:9119 (i2j) 722> 676< (complete) 7: 132.6 -.You may use the -l option (Section 4.82:2525 .235.235.67.

dmp.235.2.67.-------. Advanced Filtering 35 .758299 TCP connection info: 4: 132. lets you look at a range of packets as they occurred in the dumpfile.gz ignores the first connection alone.67. For example.235. The supported filter variables are listed below : Beluga:/Users/mani/tcptrace-manual> tcptrace -hfilter Filter Variables: variable name type description ----------------.67.67.82:2666 .235.36:9119 (i2j) 722> 676< (complete) 6: 132.gz Using both the options.3-5 rexmit.gz ignores connections 1.132.dmp. tcptrace -n -i1 rexmit. and tcptrace -n -i1.82:3299 . The -c option is useful if you are interested in looking at only complete connections i.102007.dmp. based on various parameters. 3.gz 6.67.235. A data file containing a list of connection numbers to ignore can also be given in the -i option (as shown above for the -o option).2 Advanced Filtering The -f option can be used to perform more sophisticated filtering of connections.235.e. you may use the -E option as in tcptrace -n -E200 rexmit.36:9080 (k2l) 56> 16< (reset) (reset) Ignoring certain connections alone can be done too. 4. the connections for which both the SYN and FIN segments opening and closing the connection were seen. Finally.elapsed wallclock time: 0:00:00.dmp..132. The usage of the -i option is very similar to the -o option.36:9119 (g2h) 910> 872< (complete) 5: 132.82:3584 .dmp. for some reason if you are interested in looking only at the first 200 packets found in the file for example. as in tcptrace -n -B100 -E200 rexmit.----------------------hostname STRING FQDN host name (unless -n) portname STRING service name of the port (unless -n) port UNSIGNED port NUMBER mss SIGNED maximum segment size f1323_ws BOOL 1323 window scaling requested f1323_ts BOOL 1323 time stampts requested fsack_req BOOL SACKs requested window_scale BOOL window scale factor 6. 62750 pkts/sec analyzed trace file elapsed time: 0:20:57.67.235.gz You may also begin at the 300th packet in the file for example. with the -B option as in tcptrace -n -B300 rexmit. with the -i option.132. and 5.

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

ohiou.elephus.com:http (c2d) 30> 12> 30< 15< (complete) (complete) The filter variable segs can be used to filter out connections having a specified amount of segments in either direction as shown below.2.com:http (c2d) 12> 15< (complete) The “c ” and “s ” prefixes can be applied analogously for all the filter variables cited above. the prefix “e ” meaning “either” is also supported. NOT and their common synonyms (-a. . You may specify the segments in the server2client direction alone as in : Beluga:/Users/mani> tcptrace -f’s_segs==15’ tigris.gz Output filter: (((c_hostname==elephus.edu:ssh (a2b) 30> 30< (complete) Note the Output filter line in the above example. Beluga:/Users/mani> tcptrace -f’hostname=="elephus.ohiou. Note that.ohiou.edu:54736 . .dmp. Beluga:/Users/mani> tcptrace -f’segs>=30’ tigris.edu:54735 . The prefix “b ” meaning “both” can be applied to the variables if you want the filter to be applied to both directions.cs.gz Output filter: ((c_segs>=30)OR(s_segs>=30)) 1 arg remaining. We filter out only those connections that had at least 30 or more segments seen in either direction.a17-112-152-32.cs.cs.ohiou. For example. starting with ’tigris. You may also use parenthesis if you are not sure of the precedence of operators.dmp The connection numbers that passed the filtering criteria specified in the -f option are stored in a file named PF in the working directory. requiring the filter variable to be applied to either of the directions (which is of course the default case).dmp to filter out only those connections that had window scaling requested in their SYN segments.ohiou.cs. Boolean variables listed above can be used as flags as in tcptrace -f’f1323_ws’ file.edu:54735 . ——. !) can be used to combine boolean expressions. =.edu:54736 . graphs will be 6.cs.cs.ohiou. . For the sake of completeness. . .ohiou. the following are valid : tcptrace -f‘(c_segs+10) < s_segs’ file.ohiou.cs. TCP connection info: 1: pride. TCP connection info: 2: pride. . /) with their normal precedence and relational operators ( ¡. &&. The constant value to which the STRING type variables (hostname/portname) are matched need to be enclosed in double quotes. commonly used boolean operators AND. OR. .dmp tcptrace -f‘b_segs>10 && thruput>10000’ file. if you are graphing along with the -f option with say the -G option.elephus. The following example illustrates the case when we are filtering out connections for the host elephus.edu" and portname=="ssh"’ tigris.edu)OR (s_hostname==elephus.cs.ohiou.edu:ssh (a2b) 2: pride. -o.gz’ .edu:ssh (a2b) 30> 30< (complete) Note that as in the example above.apple.ohiou.cs. !=.edu))AND((c_portname==ssh)OR(s_portname==ssh))) . ¿. The term c segs stands for the client segs (client2server direction) and s segs stands for the server segs (server2client direction).a17-112-152-32. ¡=. Advanced Filtering 37 . .gz Output filter: (s_segs==15) .dmp.dmp.edu:54735 .ohiou.elephus. ¿= ) can be applied to SIGNED/UNSIGNED variables.cs. -.dmp.ohiou.cs. TCP connection info: 1: pride. Arithmetic operators (+..edu and port ssh.apple. TCP connection info: 1: pride.cs. *.

as in : tcptrace -oPF -G file.generated for all the connections and not just the filtered ones. Filtering Connections . You might want to filter first with the -f option and graph the filtered connections with the PF file later.dmp 38 Chapter 6.

..CHAPTER SEVEN Extended Options This chapter describes the extended options supported. meaning that the option comes for free and you may use the ---no. This option lets the third duplicate ack contain data with the legacy algorithm. Note that the options explained below are labeled DEFAULT if it is the default behavior.. The extended options are used as in ---xyzblah. Port. you may use just the prefix of the option. such hardware duplicates may be counted as retransmissions. 7. to S seconds. For every such option. You may use the —nores addr to turn it off i. Though it is pretty rare to find two hosts reusing their same endpoints for a new connection between them. • —check hwdups (DEFAULT) Check for hardware duplicates i. to not resolve IP addresses. • —dupack3 data This option is meaningful only if given along with the —turn off BSD dupack option (refer to duplicate acks in Section 4. there exists a ---noxyzblah that turns off the behavior offered by the ---xyzblah option.e. If you run into such problems.2) to turn on the legacy algorithm used by tcptrace to determine triple duplicate acks. For example. Port) is perceived as a new connection. this option tells tcptrace that ns had the useHeaders flag set to TRUE while generating the dumpfile. • —endpoint reuse interval=S This option can be used to change the default idle-time of 4 minutes after which activity in the same endpoint tuple (source IP. indicating the number of packets with bad IP and TCP/UDP checksums. A summary is printed at the end of the analysis.e. you may use this option to change the default idle-time after which activity seen in the same endpoints can be perceived as a new connection. Further. it has been found that dumb devices like certain old printers tend to reuse their TCP port numbers pretty often. duplicate IP packets with the same IPv4 identification number and TCP sequence number as a previously seen packet. • —res port (DEFAULT) Resolve port numbers to their service names. and in most cases are useful if you want to turn off the default behavior.. destination IP. print http for TCP port 80. Note that the -n option is equivalent to giving both the —nores addr and —nores port options. • —ns hdrs When used while processing ns2style dumpfiles. • —checksum This option turns on checking of IP and TCP/UDP checksums. Note that if turned off with the —nocheck hwdups option. These options generally offer fine-grained control of the behavior of tcptrace . 39 . say ---xyzbl. version of the option if you need to turn it off.1 General • —res addr (DEFAULT) Resolve IP addresses to their DNS names. as long as it is unambiguous amongst all the extended options.

you may notice that the green line has a blue diamond head on the top. • —warn ooo Warn if packet capture timestamps are found to be out of order in the dumpfile. An ack packet is plotted with a BLUE diamond head if the ack is ambiguous due to the fact that one of the segments being cumulatively acknowledged by it was retransmitted.3 Warning Control This section describes the options that control the printing of warning messages on various events. the segment that is being acknowledged by the ack packet had been retransmitted. • —showsacks (DEFAULT) Show the purple colored SACK segments. You may also use the -w option to turn on all of the following options. The following options control the appearance of various features in Time Sequence Graphs 5. • —showzerolensegs (DEFAULT) Show the TCP segments carrying no data (segments that appear as white crosses). If you look closely at towards the right end of the Figure.2 Graphing Control The following options give fine-grained control over the graphs generated by tcptrace . this option would cause a warning message if the PCAP timestamps of successive packets were found decreasing. As can be seen in the graph. unlike other options this is not turned on by default. Note that.2.7. • —showtitle (DEFAULT) Show the title in xplot graphs. Extended Options . Also note that unambiguous prefixes of these options work too. 40 Chapter 7. versions of these options if you want to turn off the behavior available by default. • —showrexmit (DEFAULT) Show the retransmissions (red segments labeled R). • —showdupack3 (DEFAULT) Show triple duplicate acks with segment labeled 3. • —showoutorder (DEFAULT) Show the out-of-order segments (segments labeled O). • —showzwndprobes (DEFAULT) Show the window-probe packets that normally follow the zero-window advertisements (segments labeled P)..1. This is illustrated in Figure 7. • —showurg (DEFAULT) Show the segments with the TCP Urgent (URG) flag set with a U. An ack is plotted with a RED diamond head if the ack is ambiguous due to the fact that the segment being acknowledged was retransmitted. This is due to the fact that a segment being cumulatively acknowledged by this ack had been retransmitted. • —showrttdongles Show RTT Dongles on interesting acks as explained below.1. • —showzerowindow (DEFAULT) Show the zero-window advertisements (segments labeled Z).. You probably want to use the --no. 7. For example. This is illustrated in Figure 7. These options are turned off by default and you need to turn them on to be notified. if the dumpfile is of tcpdump style. Notice that the ack packet that causes the green line to go up towards the right-hand end of the graph has a RED diamond nailed on it.

Figure 7.3. Warning Control 41 .1: RTT Dongle (RED) 7.

Extended Options .2: RTT Dongle (BLUE) 42 Chapter 7.Figure 7.

Note that. 9 TCP packets traced elapsed wallclock time: 0:00:00. if either the basic TCP header(20 bytes) for TCP packets or the UDP header (8 bytes) for UDP packets was not fully captured. starting with ’input/bad_tcp_checksum. • —warn printhwdups Warn if hardware duplicates (that commonly indicate link-level retransmissions) were found for IPv4 packets.057058.dmp.gz packet 1: bad TCP checksum 1 arg remaining.. Warning Control 43 .6 -. 2002 10 packets seen.lerc.• —warn printtrunc Warn if a packet captured was found too short to analyze i. • —warn printbadcsum This option needs to be given along with the --checksum option. The following example illustrates this : alakhian@spider:% tcptrace --warn_printbadcsum --checksum input/bad_tcp_checksum. Hardware duplicates are defined to be the IPv4 packets with the same TCP sequence number and the 16-bit IPv4 identification number of a previously seen packet.gz’ Ostermann’s tcptrace -.lerc.nasa.012379 bad IP checksums: 0 bad TCP checksums: 1 TCP connection info: 1: analex093. With tcpdump for example.Thu Nov 14. and prints the packet numbers of the packets in the dumpfile that had bad IP and TCP/UDP checksums.e. this can be fixed with a suitable value to the -s snaplen option. 7.nasa.3. 175 pkts/sec analyzed trace file elapsed time: 0:00:00.version 6.gov:139 (a2b) 3> 6< • —warn printbad syn fin seq Prints a warning if the SYN or FIN segments were retransmitted with a different sequence number from their original transmissions.dmp.2. this warning message typically means that the packet capture was not done requesting enough of every packet to be captured.gov:2270 . • —warn printbadmbz (Warn Bad Must Be Zero) Prints a warning message if any of the 4 least significant bits in the 13th byte of the header (that are reserved and expected to be zeroed) are found to be non zero.chipper.

44

CHAPTER

EIGHT

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

8.1

UDP Analysis

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

Beluga:/Users/mani/tcptrace-manual> tcptrace -n -u dmpfiles/udp.dmp.gz 1 arg remaining, starting with ’dmpfiles/udp.dmp.gz’ Ostermann’s tcptrace -- version 6.4.6 -- Tue Jul 1, 2003 14 packets seen, 0 TCP packets traced, 14 UDP packets traced elapsed wallclock time: 0:00:00.023567, 594 pkts/sec analyzed trace file elapsed time: 0:00:00.390867 no traced TCP packets UDP connection info: 1: 132.235.3.154:46096 - 132.235.1.1:53 (a2b) 1> 1< 2: 132.235.3.154:46097 - 132.235.1.1:53 (c2d) 1> 1< 3: 132.235.3.154:46098 - 132.235.1.1:53 (e2f) 1> 1< 4: 132.235.3.154:46099 - 132.235.1.1:53 (g2h) 1> 1< 5: 132.235.19.80:2649 - 132.235.18.1:53 (i2j) 2> 2< 6: 132.235.19.80:2650 - 132.235.64.1:53 (k2l) 1> 1<

Since there is no implicit notion of connections with UDP, tcptrace groups connections from the same pair of IP addresses and same pair of UDP ports to belong to a “connection”. Giving the -l option along with the -u option generates more detailed statistics as shown below :

Beluga:/Users/mani/tcptrace-manual> tcptrace -nul dmpfiles/udp.dmp.gz 1 arg remaining, starting with ’dmpfiles/udp.dmp.gz’ Ostermann’s tcptrace -- version 6.4.6 -- Tue Jul 1, 2003 14 packets seen, 0 TCP packets traced, 14 UDP packets traced elapsed wallclock time: 0:00:00.026584, 526 pkts/sec analyzed trace file elapsed time: 0:00:00.390867 no traced TCP packets UDP connection info: 6 UDP connections traced: UDP connection 1: host a: 132.235.3.154:46096 host b: 132.235.1.1:53

45

first packet: Wed Oct 31 14:11:11.046435 2001 last packet: Wed Oct 31 14:11:11.048531 2001 elapsed time: 0:00:00.002096 total packets: 2 filename: dmpfiles/udp.dmp.gz a->b: b->a: total packets: 1 total packets: data bytes sent: 46 data bytes sent: throughput: 21947 Bps throughput: ================================ UDP connection 2: . . .

1 367 175095 Bps

The total packets field lists the total number of packets seen in the direction, while the data bytes sent field lists the total number of bytes seen in the direction. The throughput field lists average throughput calculated as the total bytes seen divided by the connection lifetime (the time elapsed between the first and last packets of the connection). Analogous to the connection filtering options -o and -i used for selectively processing or ignoring TCP connections (refer Section 6.1), options —oUDP and —iUDP options selectively process or ignore UDP connections, with the same semantics. The following example illustrates selecting just UDP connections 1,3,5 and storing them to file filt udp.dmp :

Beluga:/Users/mani/tcptrace-manual> tcptrace -n -u --oUDP1,3,5 -Ofilt_udp.dmp dmpfiles/udp.dmp 1 arg remaining, starting with ’dmpfiles/udp.dmp.gz’ Ostermann’s tcptrace -- version 6.4.6 -- Tue Jul 1, 2003 14 packets seen, 0 TCP packets traced, 14 UDP packets traced elapsed wallclock time: 0:00:00.022974, 609 pkts/sec analyzed trace file elapsed time: 0:00:00.390867 no traced TCP packets UDP connection info: 1: 132.235.3.154:46096 - 132.235.1.1:53 (a2b) 1> 1< 3: 132.235.3.154:46098 - 132.235.1.1:53 (e2f) 1> 1< 5: 132.235.19.80:2649 - 132.235.18.1:53 (i2j) 2> 2<

8.2

Real-Time Analysis

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

This would let tcptrace read the input from the binary output generated by tcpdump, until the process is interrupted with say Ctrl C, for example. However, this is not really real-time in the sense that the output is generated only after the process is interrupted, which is analogous to tcptrace printing output at the end of processing a dumpfile. The option —continuous lets tcptrace run continuously and provides no summary of connections at the end. This option is normally useful when used along with modules and maintains a list of active connections. The following options can be used along with the —continuous option : • —limit conn num Limits the number of active connections kept track of, to the default value of 50000 connections to save on memory. • —max conn num=. . . 46 Lets you choose the maximum number of connections to be kept track of. If the Chapter 8. Miscellany

Note that a TCP connection is considered live until a FIN / RST segment is seen in the connection. 8. the least recently used connection is removed to make space for the new connection. . This option can be used to customize this interval. Packet Details 47 . IP. giving a suitable value in seconds.3. For example. • —remove closed conn interval=. This option can be used to customize this interval. which can be changed using this option giving the update interval in seconds. . • —remove live conn interval=. .153 (elephus. The default interval after which a live connection is removed from the list of live connections is 8*3600 seconds (8 hours).235.(0x12) 0x1fbdbe84 0x0f455ca5 33304 40 0xfa0f 0 20 bytes MSS(1460) WS(0) TS(-202350942. When operating in the —continuous mode.apple.112. Packet 2 Packet Length: 74 Collected: Thu Jul 10 19:12:54.cs. and TCP/UDP headers C for all the packets found in the dumpfile.3 Packet Details Printing The -p option prints information from the Ethernet. .maximum connection limit is reached.gz. Once a FIN / RST segment is seen in a connection. .gz produces output as shown below for all the packets found in the file malus. . The default update interval is 30 seconds. The default interval (from the time at which the last packet was seen in the connection) after which a connection is removed from the list of inactive connections is 8*60 seconds (8 minutes).32 (a17-112-152-32. tcptrace periodically looks at the list of live and inactive connections and updates the list removing “old” connections.1957864058) 8. . • —update interval=. it is moved from the list of live connections to the list of inactive connections.edu) Type: 0x6 (TCP) HLEN: 20 TTL: 50 LEN: 60 ID: 32113 CKSUM: 0x9936 OFFSET: 0x4000 Don’t Fragment TCP SPRT: DPRT: FLG: SEQ: ACK: WIN: HLEN: CKSUM: DLEN: OPTS: Packet 3 80 (http) 59518 -A--S.987110 2003 ETH Srce: 00:00:00:00:00:00 ETH Dest: 00:00:00:00:00:00 Type: 0x800 (IP) IP VERS: 4 IP Srce: 17.dmp. . .dmp. giving a suitable value in seconds.152. Beluga:/Users/mani> tcptrace -p malus.3.com) IP Dest: 132.ohiou.

. . .

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

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

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

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

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

8.4

Other Miscellany

• —csv/—tsv/—sv=’. . . ’ These options can print the detailed statistics (Chapter 4) in a format that can be easily imported into a spread-sheet program. The —csv (comma separated values) option prints out a header line that contains the list of the fields of output to be printed depending on which of the options -l/-r/-W were given. Each of the header fields are delimited by a comma in the header line. Subsequent lines list the detailed statistics generated, each of which is delimited by a comma too. The —tsv (tab separated values) option prints the detailed statistics with the fields delimited by TAB, while the —sv=’. . . ’ option lets the user choose a string as the delimiter to be used between fields. • -t option is useful when you are processing huge dumpfiles. It prints ticks indicating the progress in processing the file, printing out the packet number currently being processed and the percentage of the file processed, periodically. • -v prints information on the version of tcptrace being run. • -h prints help messages as shown below :
Beluga:/Users/mani> tcptrace -h For help on specific topics, try: -hargs tell me about the program’s arguments -hxargs tell me about the module arguments -hconfig tell me about the configuration of this binary -houtput explain what the output means -hfilter output filtering help -hhints usage hints

48

Chapter 8. Miscellany

Version: Ostermann’s tcptrace -- version 6.4.6 -- Tue Jul 1, 2003 Compiled by ’root’ at ’Thu Jul 10 19:07:29 EDT 2003’ on machine ’pride.cs.ohiou.edu’

More specific help can be found on specific topics by giving the options -hargs, -hxargs etc., as in :
Beluga:/Users/mani> tcptrace -hxargs

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

8.4. Other Miscellany

49

50

738 packets/second 19 connections opened. 2529. 0. and uses the REAL-TIME module to explain how to write your own modules.gz mod_traffic: characterizing traffic 1 arg remaining.149090 Dumping port statistics into file traffic_byport. 43736 pkts/sec analyzed trace file elapsed time: 1:22:34. and are explained in the following.4. 2003 28427 packets seen. COLLIE.dmp. The goal of the traffic module is to raise the level of abstraction and present statistics on a per port basis. and REAL-TIME.547 bytes/second 8590918 ttl non-rexmit bytes sent. The traffic stats.1 TRAFFIC Module We have seen in the earlier chapters that tcptrace can generate detailed statistics and graphs from a dumpfile on a per connection basis.CHAPTER NINE Modules tcptrace comes with a plugin module architecture so that users can develop their own modules to do more sophisticated analysis pertinent to their needs. 9. starting with ’sack_city.dat Dumping overall statistics into file traffic_stats.004 conns/second 51 . The traffic module can be invoked as follows : tcptrace -xtraffic‘‘[ARGS]’’ <dumpfile> where the field ARGS represents any arguments to be sent to the traffic module.649954. and for the entire traffic found in the dumpfile. 795. 1734.dat Plotting performed at 15.409 bytes/second 28427 packets sent. HTTP. SLICE.7 -.gz’ Ostermann’s tcptrace -.dat.000 second intervals it generates two data files traffic stats.Fri Aug 1. RTTGRAPH. TRAFFIC.dmp.version 6. 5. 28427 TCP packets traced elapsed wallclock time: 0:00:00.149090): 12531375 ttl bytes sent.dat and traffic byport.138 bytes/second 3940457 ttl rexmit bytes sent.dat file has statistics on the entire traffic found from the dumpfile and looks as in : Overall Statistics over 4954 seconds (1:22:34. This chapter describes the modules distributed with tcptrace namely. When the traffic module is invoked without any arguments as in : surya:/home/mani> tcptrace -xtraffic sack_city.

Note that the average RTT includes RTT samples found that were ambiguous too (Total samples = RTT samples + ambiguous acks as explained in Section 4. your graph may have as many colors.dmp ignores traffic destined to ports 80-89 while choosing the connections destined to the rest of the ports in the range 1-1024. 0. For example the following surya:/home/mani> tcptrace -xtraffic’’-p22. 52 Chapter 9. connections. duplicate acks (dupacks) and retransmits (rexmits) seen (along with their respective averages seen per second) and finally the average RTT found from all the RTT samples. average bytes sent per second. The traffic module plots the graphs at discrete intervals of 15 seconds on the x-axis by default.268 msecs From the above. 0. we can notice that the traffic module prints the total time the dumpfile lasted.012 dupacks/second 3015 rexmits sent. while tcptrace -xtraffic’’-p1-1024’’ rubeus. the total number of retransmitted and non-retransmitted bytes and the average bytes (retransmitted and non-retransmitted) per second. .xpl).-80’’ rubeus. Note that if there a lot of ports being analyzed. .-80-89’’ rubeus. and the observed throughput. For example : tcptrace -xtraffic’’-p80’’ rubeus. packets. the packets-per-second per port# graph (traffic packets.dat file looks as in : Overall totals by port TOTAL bytes: Port 22 bytes: Port 5002 bytes: . Please zoom into the beginning of the graphs to find out which colored line in the graph represents the port number you are interested in. 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. The traffic byport. • -P option generates similarly. the total (ttl) number of bytes sent.xpl) for the connections analyzed by the traffic module.1 and illustrates the bytes-per-second seen on ports 22 and 80 respectively.dmp prints statistics only for TCP connections with either of the ports in the range of 1 to 1024 (inclusive).59 dupacks sent. The -p option to the traffic module lets it gather statistics only on certain ports of interest. connections. where S represents the interval S in seconds.dmp The following tcptrace -xtraffic’’-p1-1024.dmp prints statistics for just web connections (TCP port 80). The traffic module can also generate graphs that can be read with the xplot program as explained below.80 -B’’ minerva.609 rexmits/second average RTT: 78. the total number of packets. 12531375 892552 11638823 pkts: pkts: pkts: 28427 10324 18103 conns: conns: conns: 19 1 18 tput: tput: tput: 2529 B/s 180 B/s 2349 B/s listing per-port statistics on the bytes. • -B option generates the bytes-per-second per port# graph (traffic bytes. This interval at which the graph is plotted can be altered if necessary with the -iS option.dmp generated the graph shown in Figure 9. Modules .2.

TRAFFIC Module 53 .Figure 9.1: Traffic Module (-B) 9.1.

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

3: Traffic Module (-A) 9.Figure 9. TRAFFIC Module 55 .1.

Figure 9. Modules .4: Traffic Module (-O) 56 Chapter 9.

Figure 9.5: Traffic Module (-I) 9. TRAFFIC Module 57 .1.

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

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

Modules .Figure 9.8: Traffic Module (-R) 60 Chapter 9.

218:2349 .asp HTTP/1.gz we get the following output.56. HTTP Module 61 .dmp.189720 2003 (1051813785.6 -.000) Server Fin Time: Thu May 1 14:33:34.56.924972 2003 (1051813847.196. .209.2.146. .735) No additional information available.19.0 Response Code: 200 (OK) Request Length: 438 Reply Length: 30730 Content Length: 30447 Content Type : text/html Time request sent: Thu May 1 14:29:41. you need to ensure that an appropriate snaplen (with the -s option) value is chosen. where P represents the HTTP port number. .90:80 (i2j) Server Syn Time: Thu May 1 14:29:41.215. 19: 247.246.395) Elapsed time: 3489 ms (request to first byte sent) 9.132:80 (am2an) 26> 34< (reset) Http module output: 103. you may pass it in as P in the command line as shown above.115:80 (c2d) 1> 1< 3: .701) Time reply started: Thu May 1 14:29:45. .19.4. it is important that the packet contents are fully captured in dumpfiles. .215.130:35457 ==> 199.28. 2003 4810 packets seen.130:35457 .79.43:80 (ak2al) 10> 11< (complete) 20: 181.840086.151. 4810 TCP packets traced elapsed wallclock time: 0:00:00.925) GET /main.963562 2003 (1051813847.695579 2003 (1051813781. By default.209.gz’ Ostermann’s tcptrace -.3).8.250. beginning of connection (SYNs) were not found in trace fi 88.12. The http module implicitly has the effect of the -e option (refer Section 8.114.190) Time reply ACKed: Thu May 1 14:29:46.179:4482 .dat.176:80 (a2b) Server Syn Time: <the epoch> (0.version 6.139. The module can be run by passing in the -xhttp[P] option to tcptrace . With tcpdump for example.964) Client Fin Time: Thu May 1 14:30:47.115:80 (c2d) . 5725 pkts/sec analyzed trace file elapsed time: 0:04:06. .188.2 HTTP Module The HTTP module can be used to analyze web (HTTP 1. .176:80 (a2b) 1601> 2671< 2: 88. . When the HTTP module is invoked as in Beluga:/Users/mani> tcptrace -n -xhttp severus.dmp.000) Client Syn Time: <the epoch> (0.657) Server Fin Time: Thu May 1 14:30:47.32.146.8. If your dumpfile has web traffic in port number P (not 80).0 [?] and HTTP 1. .147:15414 ==> 151.12.9.696) Client Syn Time: Thu May 1 14:29:41.56.394593 2003 (1051813786.130:35458 ==> 21. the module looks for web traffic in the TCP well known port 80.998156 2003 (1051814014.657188 2003 (1051813781.199.147:15414 .Tue Jul 1.998) Client Fin Time: Thu May 1 14:33:35. .8. and extracts data found from individual connections to data files of the form X2Y contents.80.169.700691 2003 (1051813781. Note that since the HTTP module needs the data from HTTP connections. mod_http: Capturing HTTP traffic (port 80) 1 arg remaining.196.734937 2003 (1051814015.838094 TCP connection info: 1: 103. 88. starting with ’/Users/mani/dmpfiles/standard/severus.133.1 [?]) traffic from dumpfiles.50.

etc. respectively.300471 2003 Time reply ACKed: Thu May 1 14:29:49. Time reply started. . and hence.254442 2003 Elapsed time: 276 ms (request to first byte sent) Elapsed time: 3230 ms (request to content ACKed) POST /poll-include. POST /poll-include.asp. This is followed by various HTTP requests and responses seen in the connection : GET /main. • Response Code field displays the HTTP response code indicating the type of HTTP response received from the server.. . (1051813786.gif HTTP/1.0 Response Code: 200 (OK) Request Length: 392 Reply Length: 2038 Content Length: 1836 Content Type : text/html Time request sent: Thu May 1 14:29:46. the time when the first segment carrying the response was received. GET /img/color.Elapsed time: 4694 ms (request to content ACKed) GET /poll-include. . the module does not report any detailed HTTP information.771677 2003 Time reply started: Thu May 1 14:29:49. . • Content Type reports the content type of the data being sent in the response.161) (1051813790.0 Response Code: 302 (Found) Request Length: 496 Reply Length: 376 Content Length: 137 Content Type : text/html Time request sent: Thu May 1 14:29:48. . • Request Length tracks the total length (in bytes) of this HTTP request. and we see the times the SYN and FIN segments were received from the client and server respectively. GET /poll-include. . 62 Chapter 9. • Reply Length tracks the length of the HTTP response received from the server for this HTTP request.asp HTTP request.asp. . Let us see the information reported as part of the GET /main.940) First. we see the regular output of tcptrace listing the 20 connections traced in the dumpfile.160714 2003 Time reply ACKed: Thu May 1 14:29:50. . The connection labeled i2j was complete however. . the Content Length is reported as the length of the remaining data (after the headers) in the server-to-client data file.asp HTTP/1.300) (1051813789. the connection is incomplete. For the first connection labeled a2b. Time reply ACKed fields.asp.024) (1051813786. Since the SYN segments opening the connections were not captured in the dumpfile.asp and poll-include.0 . • Time request sent. which is followed by the http module output. and when the response was ACKed by the client. .939836 2003 Elapsed time: 389 ms (request to first byte sent) Elapsed time: 2168 ms (request to content ACKed) GET /poll-include. requesting (GET) or submitting (POST) files main.asp HTTP/1.772) (1051813789. If the Content Length field is not found in the response.. the module lists the time the FIN segments were received from the client and server. .asp.023979 2003 Time reply started: Thu May 1 14:29:46. track the time the request was sent. • Content Length field reports the length of the response found from the Content Length field part of the HTTP response.254) (1051813788. Modules . Note that the times are printed in human readable text format along with their absolute values.0 .asp HTTP/1.. as is obvious from their names.

65. This line lists first the client and server endpoints and the connection label (i2j) assigned. we get Figure 9. Each such small line segment represents a request-response seen in the connection. the connection label assigned to the connection (i2j). etc. is shown in Figure 9. the module also generates the http.asp HTTP/1. . and when the response was ACKed ( 1051813786.28.9.90:80 i2j 1051813781.130:35458 21. The first reqrep line shown above denotes the first request/response seen as part of the first connection.130. The diamond on the right represents the time the response was ACKed. The y-axis labeled URL doesn’t mean anything specific. The Clnt SYN and Serv SYN ticks on the line represent the times when the SYN segments were seen from the client and server respectively. reqrep .024 1051813786.90:80 i2j 1051813786. the time the connection was open. the times when the request/responses were received. the total request length in bytes (2117) found as the length of the file storing the contents of data from the client to server. The left diamond adjacent to the label /main.3. the total number of requests found (5). conn 231.asp HTTP/1.9. Besides listing HTTP information for connections as specified above.254 392 2038 200 GET /poll-include. and the total number of responses found (5).56.79. and the time elapsed between seeing the request and having the response ACKed.79. 21. pollinclude. we zoom into the information printed on top of the connection lines.times file looks similar to the following : conn 88. Each of the long lines in the figure represent a web connection initiated by the client and their length represents the lifetime of the connection.395).701).asp.• Elapsed time fields indicate the time elapsed between seeing the request and receiving the first byte of the response.146.130:35458 21.asp. . the total reply length in bytes (34953) found as the length of the file storing the contents of data from the server to the client.0 represents the time when the request was seen.28. SLICE Module 63 . 9.56. Similarly Clnt FIN and Serv FIN found towards the end of the line represent the times when the FIN segments were seen from the client and server respectively. the length of the request (438) and the response (30730).0) and the content type (text/html).130:35458. A sample graph generated for all the web connections initiated by client 88. reqrep .90:80 i2j 2117 5 34953 5 reqrep 88. with the text field 30447 representing the length of the response.63:63018 151. the requests formain. . If we zoom into the beginning of the bottom-most connection shown in Figure 9.56.0 text/html reqrep .8.11. The http.0 text/html reqrep 88.3 SLICE Module The SLICE module prints basic traffic statistics observed every timeslice.56. and is just an offset that begins from 1000 and is incremented by a constant value by the module for every web connection found in the dumpfile.79.130:35458 21.10.12.8.79.190 1051813786. In Figure 9. the response code (200) and the method it stands for (GET).8. We can see in this Figure.90:80).395 438 30730 200 GET /main.176:80 o2p 562 1 8558 1 The first line (beginning with conn) denotes the opening of a HTTP connection and lists the client and server endpoints (IP and port # : 88.8. The ticks drawn below the lines represent the times when non-zero data segments were received from the server.28. The length of the small line segment found towards the right represents the time elapsed receiving the response. with the left and right arrows representing the times when the first and last bytes of the response were received.28.300 1051813789.asp HTTP/1.times file that lists for all the complete connections found. When the SLICE module is invoked as in : 9.701 1051813785. plotting information on every web connection generated by the client. .56.8.90. The following fields list the timestamps when the request was sent (1051813781.asp HTTP/1. The http module also generates graphs for every client found in the dumpfile. when the first byte of the response is seen (1051813785. . .190). the content requested (/main.

Figure 9. Modules .9: HTTP Module Plot #1 64 Chapter 9.

10: HTTP Module Plot #2 9.Figure 9.3. SLICE Module 65 .

Figure 9.11: HTTP Module Plot #3 66 Chapter 9. Modules .

813146 2000 -tu prints the . date as Unix timestamps as in 956905223.813146 77 70612 6 9000 0 1 03:01:08. .Tue Jul 1.dat in the working directory that looks like : date segs bytes rexsegs rexbytes new active --------------. -tl specifies the date in the long text format as in Fri Apr 28 03:00:23. to see how the reported characteristics varied over time in the period of data capture of the dumpfile.6 -. .-------. 9.dat file can be used as a data file to plot a graph with the gnuplot program for example.4. . The module also allows the following options that can be passed as ARGS in -xslice’’[ARGS]’’ and given in the command line.-------. Beluga:/Users/mani> tcptrace -xcollie alastor. the total bytes of data seen (bytes).4 COLLIE Module The COLLIE module is a simple module that can display basic information on the connections (TCP and UDP) found in the dumpfile.version 6. Note that S can be a floating point value if you want. 83 TCP packets traced. .304547 2003 TCP Connections Session Start: Tue Aug 5 15:34:40. The slice. • -iS if you want to change the default slice interval of 15 seconds to S seconds. 2 UDP packets traced elapsed wallclock time: 0:00:00.813146 40 33976 3 3060 1 1 03:00:38.813146 54 50592 7 10500 0 1 03:00:53.-------03:00:23.-------. 1637 pkts/sec analyzed trace file elapsed time: 0:00:11. As shown above the date field indicates the time at the end of the time slice (15 seconds by default). but also includes the micro-second part of the timestamp as in 956905223. .-------.dmp. the total number of new connections opened in the past time-slice (new) and the total number of connections active in the past time-slice (active).gz it leaves a data file by name slice.318839 2003 9.-------.gz File modification timestamp: Wed Aug 6 18:27:22 2003 First packet: Tue Aug 5 15:34:30. COLLIE Module 67 . 2003 86 packets seen. The subsequent fields indicate the segments seen (segs). the total number of retransmitted segments (rexsegs) and retransmitted bytes (rexbytes). • -t[b—l—u—U] The -tb specifies the date field in brief and is the default (as shown in the above example).4. -tU prints the date as Unix timestamps too.052520.dmp.gz 1 arg remaining.surya:/home/mani> tcptrace -xslice rexmit. starting with ’alastor.813146.dmp.623647 Source file: alastor.gz’ Ostermann’s tcptrace -. A sample output is shown below.dmp.680899 2003 Last packet: Tue Aug 5 15:34:42.813146 29 29020 5 7500 0 1 . • -d turns on local debugging of this module.

).e.ohiou.5 Real-Time Module The Real-Time module is a sample module that can be used to run tcptrace continuously.235.3. i.edu Bytes Transferred Source to Destination: 1796 Bytes Transferred Destination to Source: 17895 Packets Transferred Source to Destination: 8 Packets Transferred Destination to Source: 17 Session Start: Tue Aug . • -d option turns on local debugging in the module.ohiou. when it was last modified. The information includes the times when the first and last packet of the connection were found (Session Start.. 68 Chapter 9. as described in Section 8. 9. the total number of bytes and packets transferred in the either direction of the connection.edu Destination IP address: 132.3.313479 2003 Session End: Tue Aug 5 15:34:40.dmp. the most recently opened connection’s information gets printed before a connection opened earlier.2.ohiou. which is the default behavior.140 Source Port: 49572 Source Fully Qualified domain name: pride.1 Destination Port: 53 Destination Fully Qualified domain name: watson.373548 2003 Source IP address: 132. .edu Destination IP address: 132. This module has the side effect of turning off name lookups. the source and destination endpoints. Session End. . Note that the collie module prints the connection information in reverse chronological order.154 Destination Port: 80 Destination Fully Qualified domain name: masaka.gz). .64. Source IP address etc.235.cs.680899 2003 The collie module has the side effect of turning on UDP processing (the -u) option. As shown above. while the -l option turns on printing of the labels. A sample run of tcptrace with the module is shown below. the module prints details on the source file (alastor. Subsequent lines print basic information on the TCP and UDP connections traced.cns.ohiou. . Modules .edu Bytes Transferred Source to Destination: 42 Bytes Transferred Destination to Source: 143 Packets Transferred Source to Destination: 1 Packets Transferred Destination to Source: 1 5 15:34:30.3.235. and the times of the first and last packets found in the file.235. and turning on the —continuous option and UDP processing internally.140 Source Port: 51214 Source Fully Qualified domain name: pride. The following options are supported by the collie module and are to be supplied as ARGS in xcollie’’ARGS’’ to tcptrace in command line. . Session Start respectively). UDP Connections Session Start: Tue Aug 5 15:34:40.317724 2003 Source IP address: 132.cs. • -n—-l The -n option turns off printing of the labels printed at the beginning of each line ( Session Start.cs.Session End: Tue Aug 5 15:34:40.

h) is shown below.41.188.41.153:47463 132.531 realtime: UDP packets .235.41.153:47521 202.235.154:22 new connection 132.3.3.162:80 new connection 132.115:80 new connection 132.235.235.elephus:/home/mramadas> tcpdump -n -w .055810 1060719569.115:80 connection closes (had 6 packets) 132.153:22 new connection 132. 9.3.3.156. char *argv[]).87.235.4 protocol: 1.235.235.12:54238 132.3.3.68:80 132.153:47510 202.153:44860 new connection 2001:0468:0b02:0820:0208:74ff:fe40:0b81:51846 2001:1418:0013:0001::0 number of open connections is 5 132. struct module { Bool module_inuse.103.235.235.1431 realtime: other packets .235. int (*module_init) (int argc.015844 1060719535.3.3.3.111.12.| tcptrace -xrealtime stdin mod_realtime: Capturing traffic 1 arg remaining. the module also prints out the number of connections open.3.162:80 new connection 132. at the end of processing.235. 9.3.92:23 new connection 132.497344 1060719574.995893 1060719535.497398 1060719575.153:47218 new connection number of open connections is 7 132.161771 1060719449.9.235.3.87.240305 1060719575.194.4.68:80 132.9.119:80 new connection 132.153:47217 new connection 132.111.235.235. Finally.10.41. 2003 tcpdump: listening 1060719445. starting with ’stdin’ Ostermann’s tcptrace -.41. the module prints the total number of TCP.153:47240 132. UDP.87.41.475633 1060719509.153:47501 63.235.194.153:47510 202.87.3.235.3.153:47511 202.Sat May 17.235.6.235.161771 1060719445.3.276251 1060719575.3.096991 1060719574.995794 1060719573.883715 1060719577.87. and other packets found in the network as shown above.93.235.962796 1060719453.115:80 connection closes (had 6 packets) 132.87.235.6 Writing Modules This section describes how to write your own plug-in modules for tcptrace . The structure definition of a module (found in modules.3.119:80 new connection 2251 packets received by filter 0 packets dropped by kernel Terminating processing early on signal 2 Partial result after processing 2109 packets: realtime: TCP packets .153:47240 132.412365 on eth0 132.647109 1060719485.153:47520 202. Writing Modules 69 .version 6.153:47511 202.154:22 new connection 24. char *module_descr. char *module_name.235.962521 1060719449.3 -. number: 4 As shown above the module prints a message everytime a new connection is found opening or closing in the network.154:22 connection closes (had 1 packets) 128.996664 1060719574. Periodically (every minute).242:706 132.3.115:80 new connection 132.3.153:44883 205.153:47500 63.001292 1060719475.

each module definition consists of fields that store a basic description of the module followed by a list of function pointers that need to be filled with functions specific to the module./* number of bytes in file (might be compressed) */ Bool fcompressed). /* is the file compressed? */ void *(*module_newconn)( tcp_pair *ptp). void (*module_usage)(void). /* routine to call on each new file */ realtime_newconn. /* name of the module */ "example real-time package"./* info I have about this connection */ void *plast. As shown above./* the name of the current file */ u_long filesize. /* routine to pass each non-tcp and non-udp 70 Chapter 9. /* routine to pass each UDP segment */ NULL. {TRUE. /* module-specific structure */ void *(*module_udp_newconn)( udp_pair *ptp).c file. /* routine to call to print module usage */ NULL. The module name. /* routine to pass each TCP segment */ realtime_done. /* make FALSE if you don’t want to call it at all */ "realtime". and module descr fields store the name and a short description of the module and are useful for debugging purposes. /* pointer to last byte */ void (*module_deleteconn) ( tcp_pair *ptp./* the packet */ udp_pair *pup./* info I have about this connection */ void *plast. The list of function pointers that follow need to be set to appropriate module specific functions./* pointer to last byte */ void *pmodstruct). The function pointers and their assignments for the Real-Time module (from the modules. /* info I have about this connection */ void (*module_nontcpudp_read) ( struct ip *pip. Modules . /* routine to call on each new UDP conn */ realtime_nontcpudp_read. /* module-specific structure */ void (*module_done) (void).void (*module_read) ( struct ip *pip. These functions are defined in the mod realtime./* info I have about this connection */ void *pmodstruct)./* pointer to last byte */ void *pmodstruct).h file) are shown below. /* routine to call at program end */ realtime_usage./* the packet */ void *plast). /* module-specific structure */ }./* the packet */ tcp_pair *ptp. /* routine to call to init the module */ realtime_read. void (*module_newfile)( char *filename. /* info I have about this connection */ void (*module_udp_read) ( struct ip *pip./* description of the module */ realtime_init. /* routine to call on each new connection */ realtime_udp_read. The module inuse variable is used by tcptrace to see if the module has been selected and is active.

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

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

(average over 10 segments. 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. All the boolean options (options that do not take in an argument along with it) can be given with a “+” prefix that has the effect of negating the option. For example. explains briefly the options supported by tcptrace .APPENDIX A Arguments QR This chapter Arguments Quick Reference (QR).ohiou. 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. Basic Arguments The following options are first read from the file $HOME/. default is 10 -z zero axis options -z plot time axis from 0 rather than wall clock time (backward compat) 73 .edu" as just "picard") Connection filtering options -iN ignore connection N (can use multiple times) -oN[-M] only connection N (or N through M). and then from the environment variable TCPTRACEOPTS (if it exists). and finally from the command line. If N is a file rather than a number. This can be useful if you store the options you always want tcptrace to use in the $HOME/.tcptracerc (if it exists). you may give a “+l” to not print in the long output format.cs. Arg can be used many times. 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].tcptracerc file or the TCPTRACEOPTS environment variable but want to turn-off an option for this invocation of tcptrace from command line.

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

default 15. default 80) Module traffic: usage: -xtraffic"[ARGS]" print info about overall traffic module argument format: -iS set statistics interval to S (float) seconds. if we are calling xplot from here (default --sv="STR" separator to use for long output with <STR>-separated-values (default: Module-specific Arguments Beluga:/Users/mani/tcptrace-manual> tcptrace -hxargs Module http: usage: -xHTTP[P] print info about http traffic (on port P.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.--nowarn_printtrunc DON’T print warnings when packets are too short to analyze (default) --warn_printbadmbz print warnings when MustBeZero TCP fields are NOT 0 --nowarn_printbadmbz DON’T print warnings when MustBeZero TCP fields are NOT 0 (default) --warn_printhwdups print warnings for hardware duplicates --nowarn_printhwdups DON’T print warnings for hardware duplicates (default) --warn_printbadcsum print warnings when packets with bad checksums --nowarn_printbadcsum DON’T print warnings when packets with bad checksums (default) --warn_printbad_syn_fin_seq print warnings when SYNs or FINs rexmitted with different sequen --nowarn_printbad_syn_fin_seq DON’T print warnings when SYNs or FINs rexmitted with differen --dump_packet_data print all packets AND dump the TCP/UDP data --nodump_packet_data DON’T print all packets AND dump the TCP/UDP data (default) --continuous run continuously and don’t provide a summary --nocontinuous DON’T run continuously and don’t provide a summary (default) --print_seq_zero print sequence numbers as offset from initial sequence number --noprint_seq_zero DON’T print sequence numbers as offset from initial sequence number ( --limit_conn_num limit the maximum number of connections kept at a time in real-time m --nolimit_conn_num DON’T limit the maximum number of connections kept at a time in real--xplot_all_files display all generated xplot files at the end --noxplot_all_files DON’T display all generated xplot files at the end (default) --ns_hdrs assume that ns has the useHeaders_flag true (uses IP+TCP headers) (def --nons_hdrs DON’T assume that ns has the useHeaders_flag true (uses IP+TCP headers --csv display the long output as comma separated values --nocsv DON’T display the long output as comma separated values (default) --tsv display the long output as tab separated values --notsv DON’T display the long output as tab separated values (default) --turn_off_BSD_dupack turn of the BSD version of the duplicate ack handling --noturn_off_BSD_dupack DON’T turn of the BSD version of the duplicate ack handling (default) Extended variable options (unambiguous prefixes also work) --output_dir="STR" directory where all output files are placed (default: ’<NULL>’) --output_prefix="STR" prefix all output files with this string (default: ’<NULL>’) --xplot_title_prefix="STR" prefix to place in the titles of all xplot files (default: ’<NULL --update_interval="STR" time interval for updates in real-time mode (default: ’<NULL>’) --max_conn_num="STR" maximum number of connections to keep at a time in real-time mode (de --remove_live_conn_interval="STR" idle time after which an open connection is removed in rea --endpoint_reuse_interval="STR" time interval of inactivity after which an open connection i --remove_closed_conn_interval="STR" time interval after which a closed connection is removed --xplot_args="STR" arguments to pass to xplot.SPEC commas chain together specs 75 .

-10-20 -L -O" only ports 1-1023. 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. Arguments QR . but exclude ports 10-20 With no ports specification. default 15.0 -d enable local debugging in this module -tb specify time and date ’briefly’ -tl specify time and date in long.-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.usecs) Module rttgraph: usage: -xrttgraph print info about rttgraph traffic Module collie: usage: -xcollie"[-ln] provide connection summary -l attach labels -n no labels please Module realtime: usage: -xrealtime an example module showing how to use real-time tcptrace 76 Appendix A. all ports are initially EXCLUDED Module slice: usage: -xslice"[ARGS]" print data info in slices module argument format: -iS set slice interval to S (float) seconds. With ANY spec. ’Unix Format’ -tu specify time and date as a Unix timestamp (secs) -tU specify time and date as a Unix timestamp (secs. all ports are gathered.

Using : xplot -x a2b_tsg. The -x option can be useful if you are viewing related graphs (the forward and reverse directions of a connection. used so that files do not overwritten accidentally in the working directory. and clicking the Left-Mouse button on the graph lets you zoom-out level by level popping out the stack.# where Title is the title of the graph and # is a serial number that gets from 0. zooming in on one of the graphs. This one was written by Tim Shepard while doing his S.mit. You may keep repeating this procedure to zoom in more and more to see any specific area of the graph in more and more detail. .mit. You may also look at the program’s web-site http://www.PS. 77 . The postscript files are named Title.org for the latest version of the program.} ] You may use the Left-Mouse button to drag and select a specific area in the graph to zoom on it. Or you can get it on the net free of charge from ftp://ftp. but the graph is made smaller vertically.edu. The zoom views are stored in a stack internally. .outbox/MIT-LCS-TR-494. for example) to line-up the x-axes of both the graphs. Clicking the Right-Mouse Button with the SHIFT key pressed also drops a smaller size postscript file.gz . so that you see the same time-scales on both the graphs all the time. sets their x-axes in sync so that.lcs. There seems to be a few other programs floating around the net by the same name. Generating Postscript Clicking the Left-Mouse Button with the SHIFT key pressed. . Ask for MIT/LCS/TR-494. The Right-Mouse button closes the graph being viewed. .APPENDIX B XPLOT QR This chapter briefly explains the usage of the xplot program. Basic Usage Viewing xplot graph(s) (commonly named as files with the .ps.xpl b2a_tsg. Similar semantics are also supported for the y-axis with the -y option. The thesis can be ordered from MIT/LCS Publications.xpl {. 1. . drops a postscript version of the graph being viewed in the working directory.xpl for example. Clicking the Middle-Mouse Button with the SHIFT key pressed drops a postscript file of smaller size that is good for including in a paper.xpl [file2. Ordering information can be obtained from +1 617 253 5851 or send mail to publications@lcs. also zooms the other graph.M.edu/pub/lcs-pubs/tr.xplot. thesis ”TCP Packet Trace Analysis” for David Clark at the MIT Laboratory for Computer Science.xpl suffix) is as simple as saying : xplot file1. The Middle-Mouse button (clicking and dragging) lets you scroll the graph. for example.

78 .

Ethernet Header Structure +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Destination | Source | Type | Data | CRC | | Address | Address | | | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 6 6 2 46-1500 4 IPv4 Header Structure 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |Version| HL | DSCP |ECN| Total Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Identification |Flags| Fragment Offset | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Time to Live | Protocol | Header Checksum | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Source Address | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Destination Address | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ < Options (if any) > | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ < > | Data | < > +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Note that the above Figure includes the DSCP (Differentiated Services Code Point) and ECN (Explicit Congestion Notification) bits defined in the IP header as per RFC 3168 [?].APPENDIX C Protocol QR The IP. and UDP protocol headers are specified here for quick reference. TCP. TCP Header Structure 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Source Port | Destination Port | 79 .

|W|C|R|C|S|S|Y|I| Window Size | | | |R|E|G|K|H|T|N|N| | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | TCP Checksum | Urgent Pointer | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ < Options (if any) > | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ < > | Data | < > +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Note again that the above Figure includes the CWR (Congestion Window Reduced) and ECE (ECN-Echo) flag bits defined for the TCP header as per RFC 3168 [?]. Protocol QR . UDP Header Structure 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Source Port | Destination Port | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | UDP Length | UDP Checksum | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ < > | Data | < > +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 80 Appendix C.+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Sequence Number | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Acknowledgment Number | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Header| |C|E|U|A|P|R|S|F| | | Length| Rsrvd.

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

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

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

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

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

Sign up to vote on this title
UsefulNot useful