xref: /freebsd/contrib/tcpdump/README.md (revision 3c602fabf9b894ff79f08a80cbb7ad3b1eb84e62)
1*3c602fabSXin LI# tcpdump
2*3c602fabSXin LI
3*3c602fabSXin LI[![Build
4*3c602fabSXin LIStatus](https://travis-ci.org/the-tcpdump-group/tcpdump.png)](https://travis-ci.org/the-tcpdump-group/tcpdump)
5*3c602fabSXin LI
6*3c602fabSXin LITCPDUMP 4.x.y
7*3c602fabSXin LINow maintained by "The Tcpdump Group"
8*3c602fabSXin LISee 		www.tcpdump.org
9*3c602fabSXin LI
10*3c602fabSXin LIPlease send inquiries/comments/reports to:
11*3c602fabSXin LI
12*3c602fabSXin LI* tcpdump-workers@lists.tcpdump.org
13*3c602fabSXin LI
14*3c602fabSXin LIAnonymous Git is available via:
15*3c602fabSXin LI
16*3c602fabSXin LI	git clone git://bpf.tcpdump.org/tcpdump
17*3c602fabSXin LI
18*3c602fabSXin LIPlease submit patches by forking the branch on GitHub at:
19*3c602fabSXin LI
20*3c602fabSXin LI*	http://github.com/the-tcpdump-group/tcpdump/tree/master
21*3c602fabSXin LI
22*3c602fabSXin LIand issuing a pull request.
23*3c602fabSXin LI
24*3c602fabSXin LIformerly from 	Lawrence Berkeley National Laboratory
25*3c602fabSXin LI		Network Research Group <tcpdump@ee.lbl.gov>
26*3c602fabSXin LI		ftp://ftp.ee.lbl.gov/old/tcpdump.tar.Z (3.4)
27*3c602fabSXin LI
28*3c602fabSXin LIThis directory contains source code for tcpdump, a tool for network
29*3c602fabSXin LImonitoring and data acquisition.  This software was originally
30*3c602fabSXin LIdeveloped by the Network Research Group at the Lawrence Berkeley
31*3c602fabSXin LINational Laboratory.  The original distribution is available via
32*3c602fabSXin LIanonymous ftp to `ftp.ee.lbl.gov`, in `tcpdump.tar.Z`.  More recent
33*3c602fabSXin LIdevelopment is performed at tcpdump.org, http://www.tcpdump.org/
34*3c602fabSXin LI
35*3c602fabSXin LITcpdump uses libpcap, a system-independent interface for user-level
36*3c602fabSXin LIpacket capture.  Before building tcpdump, you must first retrieve and
37*3c602fabSXin LIbuild libpcap, also originally from LBL and now being maintained by
38*3c602fabSXin LItcpdump.org; see http://www.tcpdump.org/ .
39*3c602fabSXin LI
40*3c602fabSXin LIOnce libpcap is built (either install it or make sure it's in
41*3c602fabSXin LI`../libpcap`), you can build tcpdump using the procedure in the `INSTALL.txt`
42*3c602fabSXin LIfile.
43*3c602fabSXin LI
44*3c602fabSXin LIThe program is loosely based on SMI's "etherfind" although none of the
45*3c602fabSXin LIetherfind code remains.  It was originally written by Van Jacobson as
46*3c602fabSXin LIpart of an ongoing research project to investigate and improve tcp and
47*3c602fabSXin LIinternet gateway performance.  The parts of the program originally
48*3c602fabSXin LItaken from Sun's etherfind were later re-written by Steven McCanne of
49*3c602fabSXin LILBL.  To insure that there would be no vestige of proprietary code in
50*3c602fabSXin LItcpdump, Steve wrote these pieces from the specification given by the
51*3c602fabSXin LImanual entry, with no access to the source of tcpdump or etherfind.
52*3c602fabSXin LI
53*3c602fabSXin LIOver the past few years, tcpdump has been steadily improved by the
54*3c602fabSXin LIexcellent contributions from the Internet community (just browse
55*3c602fabSXin LIthrough the `CHANGES` file).  We are grateful for all the input.
56*3c602fabSXin LI
57*3c602fabSXin LIRichard Stevens gives an excellent treatment of the Internet protocols
58*3c602fabSXin LIin his book *"TCP/IP Illustrated, Volume 1"*. If you want to learn more
59*3c602fabSXin LIabout tcpdump and how to interpret its output, pick up this book.
60*3c602fabSXin LI
61*3c602fabSXin LISome tools for viewing and analyzing tcpdump trace files are available
62*3c602fabSXin LIfrom the Internet Traffic Archive:
63*3c602fabSXin LI
64*3c602fabSXin LI* http://www.sigcomm.org/ITA/
65*3c602fabSXin LI
66*3c602fabSXin LIAnother tool that tcpdump users might find useful is tcpslice:
67*3c602fabSXin LI
68*3c602fabSXin LI* https://github.com/the-tcpdump-group/tcpslice
69*3c602fabSXin LI
70*3c602fabSXin LIIt is a program that can be used to extract portions of tcpdump binary
71*3c602fabSXin LItrace files. See the above distribution for further details and
72*3c602fabSXin LIdocumentation.
73*3c602fabSXin LI
74*3c602fabSXin LIProblems, bugs, questions, desirable enhancements, etc. should be sent
75*3c602fabSXin LIto the address "tcpdump-workers@lists.tcpdump.org".  Bugs, support
76*3c602fabSXin LIrequests, and feature requests may also be submitted on the GitHub issue
77*3c602fabSXin LItracker for tcpdump at:
78*3c602fabSXin LI
79*3c602fabSXin LI* https://github.com/the-tcpdump-group/tcpdump/issues
80*3c602fabSXin LI
81*3c602fabSXin LISource code contributions, etc. should be sent to the email address
82*3c602fabSXin LIabove or submitted by forking the branch on GitHub at:
83*3c602fabSXin LI
84*3c602fabSXin LI* http://github.com/the-tcpdump-group/tcpdump/tree/master
85*3c602fabSXin LI
86*3c602fabSXin LIand issuing a pull request.
87*3c602fabSXin LI
88*3c602fabSXin LICurrent versions can be found at www.tcpdump.org.
89*3c602fabSXin LI
90*3c602fabSXin LI - The TCPdump team
91*3c602fabSXin LI
92*3c602fabSXin LIoriginal text by: Steve McCanne, Craig Leres, Van Jacobson
93*3c602fabSXin LI
94*3c602fabSXin LI-------------------------------------
95*3c602fabSXin LI```
96*3c602fabSXin LIThis directory also contains some short awk programs intended as
97*3c602fabSXin LIexamples of ways to reduce tcpdump data when you're tracking
98*3c602fabSXin LIparticular network problems:
99*3c602fabSXin LI
100*3c602fabSXin LIsend-ack.awk
101*3c602fabSXin LI	Simplifies the tcpdump trace for an ftp (or other unidirectional
102*3c602fabSXin LI	tcp transfer).  Since we assume that one host only sends and
103*3c602fabSXin LI	the other only acks, all address information is left off and
104*3c602fabSXin LI	we just note if the packet is a "send" or an "ack".
105*3c602fabSXin LI
106*3c602fabSXin LI	There is one output line per line of the original trace.
107*3c602fabSXin LI	Field 1 is the packet time in decimal seconds, relative
108*3c602fabSXin LI	to the start of the conversation.  Field 2 is delta-time
109*3c602fabSXin LI	from last packet.  Field 3 is packet type/direction.
110*3c602fabSXin LI	"Send" means data going from sender to receiver, "ack"
111*3c602fabSXin LI	means an ack going from the receiver to the sender.  A
112*3c602fabSXin LI	preceding "*" indicates that the data is a retransmission.
113*3c602fabSXin LI	A preceding "-" indicates a hole in the sequence space
114*3c602fabSXin LI	(i.e., missing packet(s)), a "#" means an odd-size (not max
115*3c602fabSXin LI	seg size) packet.  Field 4 has the packet flags
116*3c602fabSXin LI	(same format as raw trace).  Field 5 is the sequence
117*3c602fabSXin LI	number (start seq. num for sender, next expected seq number
118*3c602fabSXin LI	for acks).  The number in parens following an ack is
119*3c602fabSXin LI	the delta-time from the first send of the packet to the
120*3c602fabSXin LI	ack.  A number in parens following a send is the
121*3c602fabSXin LI	delta-time from the first send of the packet to the
122*3c602fabSXin LI	current send (on duplicate packets only).  Duplicate
123*3c602fabSXin LI	sends or acks have a number in square brackets showing
124*3c602fabSXin LI	the number of duplicates so far.
125*3c602fabSXin LI
126*3c602fabSXin LI	Here is a short sample from near the start of an ftp:
127*3c602fabSXin LI		3.00    0.20   send . 512
128*3c602fabSXin LI		3.20    0.20    ack . 1024  (0.20)
129*3c602fabSXin LI		3.20    0.00   send P 1024
130*3c602fabSXin LI		3.40    0.20    ack . 1536  (0.20)
131*3c602fabSXin LI		3.80    0.40 * send . 0  (3.80) [2]
132*3c602fabSXin LI		3.82    0.02 *  ack . 1536  (0.62) [2]
133*3c602fabSXin LI	Three seconds into the conversation, bytes 512 through 1023
134*3c602fabSXin LI	were sent.  200ms later they were acked.  Shortly thereafter
135*3c602fabSXin LI	bytes 1024-1535 were sent and again acked after 200ms.
136*3c602fabSXin LI	Then, for no apparent reason, 0-511 is retransmitted, 3.8
137*3c602fabSXin LI	seconds after its initial send (the round trip time for this
138*3c602fabSXin LI	ftp was 1sec, +-500ms).  Since the receiver is expecting
139*3c602fabSXin LI	1536, 1536 is re-acked when 0 arrives.
140*3c602fabSXin LI
141*3c602fabSXin LIpacketdat.awk
142*3c602fabSXin LI	Computes chunk summary data for an ftp (or similar
143*3c602fabSXin LI	unidirectional tcp transfer). [A "chunk" refers to
144*3c602fabSXin LI	a chunk of the sequence space -- essentially the packet
145*3c602fabSXin LI	sequence number divided by the max segment size.]
146*3c602fabSXin LI
147*3c602fabSXin LI	A summary line is printed showing the number of chunks,
148*3c602fabSXin LI	the number of packets it took to send that many chunks
149*3c602fabSXin LI	(if there are no lost or duplicated packets, the number
150*3c602fabSXin LI	of packets should equal the number of chunks) and the
151*3c602fabSXin LI	number of acks.
152*3c602fabSXin LI
153*3c602fabSXin LI	Following the summary line is one line of information
154*3c602fabSXin LI	per chunk.  The line contains eight fields:
155*3c602fabSXin LI	   1 - the chunk number
156*3c602fabSXin LI	   2 - the start sequence number for this chunk
157*3c602fabSXin LI	   3 - time of first send
158*3c602fabSXin LI	   4 - time of last send
159*3c602fabSXin LI	   5 - time of first ack
160*3c602fabSXin LI	   6 - time of last ack
161*3c602fabSXin LI	   7 - number of times chunk was sent
162*3c602fabSXin LI	   8 - number of times chunk was acked
163*3c602fabSXin LI	(all times are in decimal seconds, relative to the start
164*3c602fabSXin LI	of the conversation.)
165*3c602fabSXin LI
166*3c602fabSXin LI	As an example, here is the first part of the output for
167*3c602fabSXin LI	an ftp trace:
168*3c602fabSXin LI
169*3c602fabSXin LI	# 134 chunks.  536 packets sent.  508 acks.
170*3c602fabSXin LI	1       1       0.00    5.80    0.20    0.20    4       1
171*3c602fabSXin LI	2       513     0.28    6.20    0.40    0.40    4       1
172*3c602fabSXin LI	3       1025    1.16    6.32    1.20    1.20    4       1
173*3c602fabSXin LI	4       1561    1.86    15.00   2.00    2.00    6       1
174*3c602fabSXin LI	5       2049    2.16    15.44   2.20    2.20    5       1
175*3c602fabSXin LI	6       2585    2.64    16.44   2.80    2.80    5       1
176*3c602fabSXin LI	7       3073    3.00    16.66   3.20    3.20    4       1
177*3c602fabSXin LI	8       3609    3.20    17.24   3.40    5.82    4       11
178*3c602fabSXin LI	9       4097    6.02    6.58    6.20    6.80    2       5
179*3c602fabSXin LI
180*3c602fabSXin LI	This says that 134 chunks were transferred (about 70K
181*3c602fabSXin LI	since the average packet size was 512 bytes).  It took
182*3c602fabSXin LI	536 packets to transfer the data (i.e., on the average
183*3c602fabSXin LI	each chunk was transmitted four times).  Looking at,
184*3c602fabSXin LI	say, chunk 4, we see it represents the 512 bytes of
185*3c602fabSXin LI	sequence space from 1561 to 2048.  It was first sent
186*3c602fabSXin LI	1.86 seconds into the conversation.  It was last
187*3c602fabSXin LI	sent 15 seconds into the conversation and was sent
188*3c602fabSXin LI	a total of 6 times (i.e., it was retransmitted every
189*3c602fabSXin LI	2 seconds on the average).  It was acked once, 140ms
190*3c602fabSXin LI	after it first arrived.
191*3c602fabSXin LI
192*3c602fabSXin LIstime.awk
193*3c602fabSXin LIatime.awk
194*3c602fabSXin LI	Output one line per send or ack, respectively, in the form
195*3c602fabSXin LI		<time> <seq. number>
196*3c602fabSXin LI	where <time> is the time in seconds since the start of the
197*3c602fabSXin LI	transfer and <seq. number> is the sequence number being sent
198*3c602fabSXin LI	or acked.  I typically plot this data looking for suspicious
199*3c602fabSXin LI	patterns.
200*3c602fabSXin LI
201*3c602fabSXin LI
202*3c602fabSXin LIThe problem I was looking at was the bulk-data-transfer
203*3c602fabSXin LIthroughput of medium delay network paths (1-6 sec.  round trip
204*3c602fabSXin LItime) under typical DARPA Internet conditions.  The trace of the
205*3c602fabSXin LIftp transfer of a large file was used as the raw data source.
206*3c602fabSXin LIThe method was:
207*3c602fabSXin LI
208*3c602fabSXin LI  - On a local host (but not the Sun running tcpdump), connect to
209*3c602fabSXin LI    the remote ftp.
210*3c602fabSXin LI
211*3c602fabSXin LI  - On the monitor Sun, start the trace going.  E.g.,
212*3c602fabSXin LI      tcpdump host local-host and remote-host and port ftp-data >tracefile
213*3c602fabSXin LI
214*3c602fabSXin LI  - On local, do either a get or put of a large file (~500KB),
215*3c602fabSXin LI    preferably to the null device (to minimize effects like
216*3c602fabSXin LI    closing the receive window while waiting for a disk write).
217*3c602fabSXin LI
218*3c602fabSXin LI  - When transfer is finished, stop tcpdump.  Use awk to make up
219*3c602fabSXin LI    two files of summary data (maxsize is the maximum packet size,
220*3c602fabSXin LI    tracedata is the file of tcpdump tracedata):
221*3c602fabSXin LI      awk -f send-ack.awk packetsize=avgsize tracedata >sa
222*3c602fabSXin LI      awk -f packetdat.awk packetsize=avgsize tracedata >pd
223*3c602fabSXin LI
224*3c602fabSXin LI  - While the summary data files are printing, take a look at
225*3c602fabSXin LI    how the transfer behaved:
226*3c602fabSXin LI      awk -f stime.awk tracedata | xgraph
227*3c602fabSXin LI    (90% of what you learn seems to happen in this step).
228*3c602fabSXin LI
229*3c602fabSXin LI  - Do all of the above steps several times, both directions,
230*3c602fabSXin LI    at different times of day, with different protocol
231*3c602fabSXin LI    implementations on the other end.
232*3c602fabSXin LI
233*3c602fabSXin LI  - Using one of the Unix data analysis packages (in my case,
234*3c602fabSXin LI    S and Gary Perlman's Unix|Stat), spend a few months staring
235*3c602fabSXin LI    at the data.
236*3c602fabSXin LI
237*3c602fabSXin LI  - Change something in the local protocol implementation and
238*3c602fabSXin LI    redo the steps above.
239*3c602fabSXin LI
240*3c602fabSXin LI  - Once a week, tell your funding agent that you're discovering
241*3c602fabSXin LI    wonderful things and you'll write up that research report
242*3c602fabSXin LI    "real soon now".
243*3c602fabSXin LI```
244