
tcpsplit v0.3
March 2025

Mark Allman
International Computer Science Institute
mallman@icir.org


This utility takes a libpcap packet trace and splits it into some
number of smaller traces, along TCP connection boundaries.  This
allows the breaking apart of large traces into smaller and more
manageable subsets without ending up with part of a TCP connection
in one sub-trace and part in another.

Basic usage:

usage: tcpsplit [options] readfile writespec num_files
  the "writespec" must contain a %d, indicating where to insert the file number
  options:
    --p4 X    use a prefix of X bits to split, instead of full IPv4 addresses
    --p6 X    use a prefix of X bits to split, instead of full IPv6 addresses
    -d        classify deterministically
    -h        usage instructions
    --notcp   only use IP addresses in classification, not port numbers
    --version version information

Examples:

% tcpsplit bigtrace smalltrace.%d 5

    This creates 5 sub-traces called "smalltrace.1", "smalltrace.2",
    etc. from "bigtrace".

In addition, the tool always creates a "weird" file (in this case it
would be "smalltrace.weird").  This file contains any packets that
could not successfully be classified and put into another of the
files.  Normally, this file contains no packets.

Default behavior:

  - Each TCP segment is dumped into a sub-trace based on the two IP
    addresses and two port numbers in the packet.  Each time a new
    4-tuple is detected, the file the connection will be dumped in
    is picked based on a least-frequently used scheme (in terms of
    packets / sub-trace).
 
  - Each non-TCP segment is dumped into a sub-trace based on the two
    IP addresses only.

  - Each non-IP segment is dumped into the weird file.

Options:

  - If the "--notcp" option is given then the TCP port numbers are
    never used in determining which sub-trace packets are filed
    into.  (This is useful for collecting all traffic between two
    endpoints together.)

  - If the "-d" option is given the sub-trace is chosen via a hash
    of the IPs and ports instead of the LFU scheme sketched above.
    This provides a deterministic mapping to sub-traces.

  - If the "--p4" and/or "--p6" option is given, only the high-order
    X bits of the IPs are used for classification.

  - The included "validate" script can be used to crunch the
    original trace and created sub-traces to ensure tcpsplit worked
    as intended.

Building:

  * The tool requires libpcap be installed.

  * The tool was developed under MacOS and Linux.  Running "make"
    will build tcpsplit on either of these.

Please let me know if you have tweaks or comments.



Acknowledgments
---------------
Robert Bullen - added code to grok VLAN headers
Rick Jones - tweaks for compiling under HP-UX 11.11
Jim Wyllie - signedness bug fixes
