Libpcap tutorial

From wiki.ucalgary.ca
Revision as of 23:10, 30 January 2011 by Locasto (talk | contribs)
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

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

Contributions

See the wiki history for this page.