Tcpreplay

Tcpreplay is a suite of [GPLv3] licensed utilities for UNIX (and Windows under [Cygwin]) for editing and replaying network traffic previously captured by tools like [tcpdump] and [Wireshark]. It classifies traffic as client or server, rewrites Layer 2/3/4 headers, and replays it back onto the network through switches, routers, firewalls, NIDS and IPS's — at anywhere from a trickle up to full wire rate. Tcpreplay supports both single and dual NIC modes, for testing both sniffing and in-line devices.

Tcpreplay is used by numerous firewall, IDS, IPS, NetFlow and other networking vendors, enterprises, universities, labs and open source projects. If your organization uses Tcpreplay, please let us know who you are and what you use it for, so we can keep prioritizing the features that matter.

Since 4.0, Tcpreplay also specifically targets [IP Flow][flow]/[NetFlow] appliance testing: accurate high-rate playback timing and results reporting, Flows Per Second (fps) statistics, and flow-expiry analysis for tuning a flow product's timeout settings — up to hundreds of thousands of flows/sec, depending on the flow sizes in the pcap file.

📖 Full documentation lives at https://tcpreplay.appneta.com — a getting-started guide, a page per tool, how-to recipes, the concepts behind the suite, the man pages, and the FAQ. This README is the quick tour; the site is the reference.

• The suite
• What's new in 4.6
• Installing a release
• Building from source
  • Autotools
  • CMake
  • Performance: netmap, AF_XDP, io_uring
  • Replaying onto raw IP (L3) interfaces
  • libtcpreplay C library
  • Running the test suite
• Getting help
• Contributing
• License
• Authors

The Suite

Network playback:

• tcpreplay / tcpreplay-edit — replay pcap files at arbitrary speeds onto the network, optionally editing packets on the fly (tcpreplay-edit) or randomizing IP addresses (tcpreplay)
• tcpliveplay — replay a captured TCP session on a live network in a manner that a remote server will actually respond to (contributed by Yazan Siam, sponsored by [Cisco], for testing the full network stack up into the application — plain tcpreplay normally stays at Layer 2)

Pcap file editors and utilities:

• tcpprep — multi-pass pcap pre-processor that classifies packets as client or server and writes a cache file consumed by tcpreplay/tcprewrite
• tcprewrite — rewrites TCP/IP and Layer 2 packet headers in a pcap file
• tcpbridge — bridge two network segments using tcprewrite's rewriting logic
• tcpcapinfo — raw pcap file decoder and debugger

What's New in 4.6

• CMake is now the primary, recommended build system (autotools is still used for release tarballs)
• io_uring and AF_XDP fast-path packet injection, alongside the existing netmap support — both need less setup than netmap and no patched drivers
• libtcpreplay, a static C library for embedding the replay engine directly in your own program
• Automatic support for replaying onto raw IP (L3) interfaces like WireGuard and tun devices

See the CHANGELOG for the full release history.

Installing a Release

Download the latest release tarball (also mirrored on SourceForge), then:

tar xf tcpreplay-*.tar.xz && cd tcpreplay-*
./configure && make && sudo make install

A release tarball ships pre-generated CLI parsers and man pages, so this needs nothing beyond a C compiler and libpcap — see Building from source below only if you're working from a git checkout, or want CMake, netmap, AF_XDP or io_uring support.

More detailed platform-specific instructions are in the INSTALL file included in the tarball (same content as docs/INSTALL here).

Building From Source

Building from a git checkout requires python3 and asciidoctor (either build system) to generate the CLI option parsers and man pages from the *_opts.def files — this replaced GNU AutoGen for that purpose in 4.6 (AutoGen is EOL; these aren't). AutoGen itself is only still needed for one internal header (src/tcpedit/tcpedit_stub.h) — see scripts/autoopts/README.md. None of this is needed when building a release tarball, which ships these already generated.

Autotools

./autogen.sh   # only needed once, from a git checkout
./configure
make
sudo make install

CMake (recommended)

As of 4.6, the suite can also be built with CMake (3.16+) — the recommended and primary way to compile Tcpreplay. Autotools is still provided and used for release tarballs, but will eventually be retired, so new scripts/packaging should target CMake.

cmake -B build
cmake --build build
sudo cmake --install build

Every ./configure flag has a CMake equivalent — see the table at the top of CMakeLists.txt. A few examples:

# debug build with support for the -d option
cmake -B build -DENABLE_DEBUG=ON

# AddressSanitizer or ThreadSanitizer build
cmake -B build -DENABLE_ASAN=ON
cmake -B build -DENABLE_TSAN=ON

# custom libpcap install, static linking, custom tcpdump path
cmake -B build -DWITH_LIBPCAP=/usr/local/opt/libpcap \
               -DENABLE_STATIC_LINK=ON -DWITH_TCPDUMP=/usr/sbin/tcpdump

# force a specific packet injection method
cmake -B build -DFORCE_INJECT_PCAP_SENDPACKET=ON

# several configurations side by side
cmake -B build-debug -DENABLE_DEBUG=ON
cmake -B build-release

cmake --build build --target manpages regenerates the man pages (python3 + asciidoctor); a plain cmake --build build never touches them. VS Code users with the CMake Tools extension can just open the repository folder and pick a configure preset when prompted.