What is libnetdude?

libnetdude is a library for manipulating libpcap/tcpdump trace files. You may ask why this requires a new library. We believe that a lot of code that uses libpcap is wasted, for two reasons:

• Developers often write monolithic, stand-alone programs that address a particular problem at the time of writing. Many of these applications are never released. Others only exist as executable programs and not as libraries that would provide far better reuse of the code.

• For lack of better alternatives, developers write their tools at the libpcap level, whose API operates at a very low level: essentially one is given means to apply BPF filters and iterate packets. That is not a bad thing — libpcap was never meant to provide higher-level features. However, so far few libraries have attempted to fill the gap between libpcap and more complex applications.

libnetdude's goal is to improve this situation. It provides abstractions on top of the libpcap paradigm that save developers a lot of time by focusing on the relevant parts of their applications. Moreover, libnetdude supports plugins (dynamically loaded libraries) that can essentially do whatever the programmer desires. When developers write their packet manipulation code as libnetdude plugins, this instantly allows other developers to use their tools.

libnetdude provides data types and APIs for the most common situations when dealing with libpcap trace files: trace files of arbitrary size, packets, network protocols, packet iterators, packet filters, just to name a few.

How does it work?

At a glance, libnetdude allows the user to edit trace files in terms of arbitrary trace areas, regions of packets in a trace file, defined by start- and end timestamps or size fractions. These areas can be conveniently iterated and modified, including insertion, modification, and deletion of packets. The filtering API allows the definition of arbitrary packet filters that cause packet iterators to report only those packets passing the currently active filters. libnetdude takes care of managing the various areas, so that the user always has a consistent view of the trace. libnetdude's packet initialization provides structured packet data as much as the installed protocol plugins permit; for all such protocols, it becomes trivially easy to obtain protocol data at a certain nesting level from a packet. No need to write protocol demuxers any more. libnetdude builds on the libpcapnav library in order to facilitate navigation in a trace file in time and space.

Read more ...

For more details, please refer to the Freenix 2004 paper on Netdude that presents the design and implementation of the entire framework.

The Rest of this Manual

The rest of this document is structured as follows: the first chapter presents the main concepts of libnetdude. The second chapter explains how to build the library, the layout of the library's files on disk and how to build programs that use libnetdude. The third chapter explains Netdude's protocols.

Code examples are not meant to be readily compilable when cut and pasted into a C file: variables are introduced when context requires them, and not all variables are meaningfully initialized. Admonitions in this manual have the following meaning:

Note: something you should be aware of.

Caution: listen up, you'll be glad you did.

Warning: forget this and we'll get upset.