Libpcap tutorial

Revision as of 23:17, 30 January 2011 by Locasto (talk | contribs) (Tutorial Task Description)
Jump to: navigation, search

A libpcap Tutorial

The PCAP library is a C language library (and has variants and translations for other languages and execution environments) that allows both customizable packet capture from the network (or a pre-recorded trace file) and packet injection into the network (or output trace file). It is mainly a library for managing the reading and writing process of packets to and from a data source. It is not particularly well-suited for arbitrary packet formulation.

Other libpcap tutorial exist; for example, see:

and pcap comes with a Unix manual page describing the various functions and flags provided by the library:

Tutorial Task Description

This tutorial will show how to use libpcap to transcribe packets from one data source to another (in a fashion similar to the effect of tcpreplay) while injecting packet content from other sources (such as a program, another trace file, or a network interface). It is assumed that this other source has formulated the packets they wish to appear in the output.

Here is a picture of what we'll build:

VEI Library Architecture

We will build a C library that has two sources of input and one output target. The first input source is a "background" PCAP file trace. The second source of input is an asynchronously-invoked function call `inject_event'. The purpose of the library is to weave these two input sources into a single output file.

The library will have an API containing three functions: initialization, start of transcription, and event injection. In this tutorial, we will build both the library and an example client of the library.

What You'll Need

You will need the following environment set up for this tutorial:

  • A Unix-style platform. This tutorial assumes Linux, specifically Fedora Core 10.
  • A text editor. I use emacs, but you can use vi, nano, pico, or something else.
  • A C compiler. I use gcc.
  • A threads package. I use pthreads.
  • A version of the libpcap library and its development package (e.g.,:
[michael@proton docs]$ yum list installed | grep pcap
jpcap.i386                          0.7-6.fc10                         @updates 
libpcap.i386                        14:0.9.8-3.fc10                    installed
libpcap-devel.i386                  14:0.9.8-3.fc10                    @fedora  
pcapdiff.noarch                     0.1-3.fc9                          @fedora  
pcapy.i386                          0.10.5-3.fc9                       @fedora  
[michael@proton docs]$ 

The Delta: What this tutorial has that others do not

This tutorial exists because I had to find out some things the "hard" way (e.g., reading the documentation). This section isn't meant to be boastful; other tutorials focus on what they focus on because this served the purpose of the author. I had a different set of requirements when I approached the task of using libpcap. Here are those things:

  • how to read and write to dumpfiles
  • the format of the PCAP savefile (particularly the record format of timestamp value plus packet structure)
  • the explanations for the data link types (needed for some of the API functions, but buried down in the man page)
  • how to structure a program to use pcap for multiple purposes at once (i.e., using pthreads to do multiple things at once, not just open an interface and sniff)
  • potential bugs in releasing dump file handles

The Tutorial

The following steps describe a set of tasks, building off how to set up the development environment to writing simple packet replay code to adding in some advanced features.

Step 0: Controlling Compilation and the Build Process

This tutorial uses a directory structure and Makefile to ease the repeated process of compiling.

Step 1: Packet Record Transcription

Step 2: Adding in Injection


See the wiki history for this page.