=== TCPFLOW

by Jeremy Elson <jelson@circlemud.org>
and Simson L. Garfinkel <simsong@acm.org>

For the latest information on tcpflow, please see:
http://www.circlemud.org/~jelson/software/tcpflow/

Or, subscribe to the tcpflow mailing lists; see
http://sourceforge.net/mail/?group_id=8327


== What is tcpflow?

tcpflow is a program that captures data transmitted as part of TCP
connections (flows), and stores the data in a way that is convenient
for protocol analysis and debugging.  Each TCP flow is stored in its
own file. Thus, the typical TCP flow will be stored in two files, one
for each direction. tcpflow can also process stored 'tcpdump' packet
flows.

tcpflow stores all captured data in files that have names of the form:

            128.129.130.131.02345-010.011.012.013.45103

... where the contents of the above file would be data transmitted from
host 128.129.131.131 port 2345, to host 10.11.12.13 port 45103.


tcpflow is similar to 'tcpdump', in that both process packets from the
wire or from a stored file. But it's different in that it reconstructs
the actual data streams and stores each flow in a separate file for
later analysis.

tcpflow understands sequence numbers and will correctly reconstruct
data streams regardless of retransmissions or out-of-order
delivery. Version 1.0 adds support for VLAN demultiplexing. 
However, tcpflow currently does not understand IP fragments; flows
containing IP fragments will not be recorded properly.

tcpflow is based on the LBL Packet Capture Library (available at
ftp://ftp.ee.lbl.gov/libpcap.tar.Z) and therefore supports the same
rich filtering expressions that programs like 'tcpdump' support.
It should compile under most popular versions of UNIX; see the INSTALL
file for details.


== What use is it?

Jeremy Elson originally wrote this program to capture the data being
sent by various programs that use undocumented network protocols in an
attempt to reverse engineer those protocols.  RealPlayer (and most
other streaming media players), ICQ, and AOL IM are good examples of
this type of application.  It was later used for HTTP protocol
analysis.

== Bugs

Please send bug reports to simsong@acm.org.

tcpflow currently does not understand IP fragments.  Flows containing
IP fragments will not be recorded correctly.

tcpflow never frees state associated with flows that it records, so
will grow large if used to capture a very large number of flows (e.g.,
on the order of 100,000 flows or more).