wiki:manual

3.x Online Manual

About

These wiki pages attempt to document the latest version (currently 3.2.5) of the Tcpreplay suite of tools. Because Tcpreplay changes over time, so must this document. As you might imagine, sometimes the code and these wiki pages get out of sync.

For the definative source of configuration options, please see the man pages included with Tcpreplay.

Throughout this manual, I use the long formatted options (--long-opt) rather then the short option (-l). Both get the job done, but long options are often clearer and easier to read. The man pages? list both option formats side-by-side for your reference.

Important! If you have a 1.x or 2.x version of code, then this manual is completely inaccurate and will only confuse you. In such cases, please see the documentation which came with the source code or your binary package.

Overview

Tcpreplay is a suite of utilities for UNIX systems for editing and replaying network traffic which was previously captured by tools like  tcpdump and  ethereal/ wireshark. The goal of tcpreplay is to provide the means for providing reliable and repeatible means for testing a variety of network devices such as switches, router, firewalls, network intrusion detection and prevention systems (IDS and IPS).

Tcpreplay provides the ability to classify traffic as client or server, edit packets at layers 2-4 and replay the traffic at arbitrary speeds onto a network for sniffing or through a device.

Some of the advantages of using tcpreplay over using exploit code are:

  1. Since tcpreplay emulates the victim and the attacker, you generally only need a tcpreplay box and the device under test (DUT)
  2. Tests can include background traffic of entire networks without the cost and effort of setting up dozens of hosts or costly emulators
  3. No need to have a "victim" host which needs to have the appropriate software installed, properly configured and rebuilt after compromise
  4. Virtually zero chance that a virus or trojan might escape your network and wreak havoc on your systems
  5. Uses the open standard pcap file format for which dozens of command line and GUI utilities exist
  6. Tests are fully repeatable without a complex test harnesses or network configuration
  7. Tests can be replayed at arbitrary speeds
  8. Single command-line interface to learn and integrate into test harness
  9. You only need to audit tcpreplay, rather then each and every exploit individually
  10. Actively developed and supported by it's author

Please note that tcpreplay does not support replaying traffic to a server. This is because tcpreplay is completely stateless and is unable to handle updating TCP sequence and acknowledgement numbers. If you are interested in this kind of functionality, check out flowreplay instead.

Getting Tcpreplay Installed

Basics

There are three possible ways of getting tcpreplay running on your system:

  1. Using a pre-compiled package from Debian, Darwin Ports, RPM, etc. Note: I do not provide binaries.
  2. Downloading and compiling a pre-packaged release
  3. Getting the latest code from Subversion

In each of the above three cases you will need the following dependancies:

  • Some kind of UNIX-like operating system. Linux, *BSD, Solaris, OS X and others should all work. If you find any compatibility issues with any *NIX OS, please let me know.
  •  Libpcap 0.7.2 or better required, but I recommend the latest version for best results

Optional libraries/tools:

  •  Tcpdump if you want to use the packet decoding feature
  •  Libnet 1.1.3-RC1 or better. If your OS doesn't support BPF or Linux's PF_PACKET injection then you will need libnet or a recent version of libpcap. Note: Libnet support is for historical reasons only. Due to bugs in Libnet and the fact that is seems unmaintained, I can not recommend using libnet for tcpreplay. Right now there is one case where libnet is necessary: you're not running on Linux or *BSD and you want to use tcpbridge. Right now there are limitations in the libpcap API which prevents tcpbridge from working when BPF and PF_PACKET aren't available.
  •  libdnet if you want fragroute support (Tcpreplay 3.3+)
  •  Libpcapnav if you want some advanced packet selection options
  •  GNU Autogen (v5.9.9 is STRONGLY recommended) if you want to compile code from Subversion checkouts

IMPORTANT: The directions below assume you are using a 3.4.x version of code (branches/3.4 in subversion) and not 4.x (trunk in subversion). The new 4.x version of code in trunk uses  cmake for it's build system.

To compile tcpreplay:

  1. $ ./autogen.sh (Subversion checkouts only)
  2. $ ./configure
  3. $ make
  4. # make test (Note: tcprewrite tests are currently broken on Cygwin/Win?32)
  5. # make install

Note: If you are compiling from Subversion, you'll probably need to specify --disable-local-libopts to prevent problems with miss-matched versions.

Advanced Options

There are quite a few configure time options for tcpreplay which allow you to control a lot of things. Some of the more interesting ones are:

  • --enable-debug -- useful for debugging bugs and crashes.
  • --enable-64bits -- use 64 bit counters to handle large pcap files & looping
  • --enable-libnet -- link to libnet. Note that libnet support has been deprecated due to various bugs which have not been fixed in over a year.
  • --with-libnet -- specify root path to libnet (something like --with-libnet=/usr/local)
  • --with-libpcap -- specify root path to libpcap
  • --with-tcpdump -- specify path to tcpdump executable
  • --enable-tcpreplay-edit -- compile tcpreplay with packet editing support

You can also manually select a particular method to inject packets:

  • --enable-force-pf -- force tcpreplay to use Linux's PF_PACKET to send packets
  • --enable-force-bpf -- force tcpreplay to use Free/Net?/OpenBSD or OS X's BPF interface to send packets
  • --enable-force-libnet -- force tcpreplay to use Libnet to send packets
  • --enable-force-inject -- force tcpreplay to use Libpcap's pcap_inject() API to send packets
  • --enable-force-sendpacket -- force tcpreplay to use Libpcap's pcap_sendpacket() API to send packets

If you're having compatibility issues with a system installed GNU Autogen, you may want to consider these options:

  • --disable-local-libopts -- Don't use the libopts tearoff supplied with tcpreplay (default is enabled)
  • --disable-libopts-install -- don't install the libopts library files

Special Instructions for Windows

First of all, Windows support for Tcpreplay is experimental- beta quality if you will. I don't use Windows and my only "Windows" box is via Parallels (sorta like VMWare). Hence, I do the best I can, but I'm far from a Windows expert and so if you have problems it's important that you give me as much information as possible. I strongly recommend you read the page about how to get support for Tcpreplay.

With that said, you'll need  Cygwin to compile/run tcpreplay. You'll also need to install  Winpcap the port of libpcap for Windows. For whatever reason, it seems important that you install the Winpcap files in the Cygwin root directory (/Wpdpack).

Be sure to install both the  driver/DLL files AND  developer pack. Then when you run ./configure, you'll need to specify the location for Winpcap using the --with-libpcap flag, but use all lowercase: ./configure --with-libpcap=/wpdpack. Again, not sure why you need to do this, but it seems to be necessary.

After that, for the most part things should just work. There are some caveats- a few features and make test don't work, but for the most part they seem to be pretty minor.

For more detailed instructions, see the Win32Readme.txt.

Note: I've been informed that the guile Cygwin package is broken. This horribly breaks parts of GNU Autogen- specifically the parts which allow you to build Tcpreplay via SVN. Hence, I strongly recommend grabbing a tarball release.

How Does Everything Work Together?

First, Tcpreplay is a suite of tools: tcpreplay (sends packets), tcprewrite (edits packets) and tcpprep (characterizes packets as client->server or server->client).

tcpreplay takes a pcap file and replays it as is. If you have 1 flow between two IP addresses, it will replay that. If you have 100,000 flows between 10,000 clients/servers it'll do that too. It doesn't decode the packets at any level, so it doesn't really care how many IP addresses are in the pcap. It doesn't even need to be IP traffic. If you want to send traffic on two interfaces (to send traffic through a device), tcpreplay needs to be told which packets go out which interface using a tcpprep cache file (see below)

tcprewrite edits packets, mostly at L2-L4. Things like changing MAC/IP addresses or TCP/UDP ports so your DUT will properly process the packets. Since most protocols are bi-directional, tcprewrite needs to be told when to rewrite in the other direction. Ie: if you have a HTTP session and you're rewriting the server & client IP, it needs to know when to swap the src/dst IP addresses.

tcpprep supports a variety of ways to figure out if a packet is C->S or S->C. It then generates a cache file which can be used by tcpreplay and tcprewrite to make intelligent decisions.

Need Help?

Having problems? Try asking for help on the tcpreplay-users mailing list or check out the Support section.


Next: tcpreplay