Welcome! You're looking at the manual for
libnetdude. Thanks for reading this.
libnetdude is a library for manipulating
tcpdump trace files. You
may ask why this requires a new library. We believe that a lot of code
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
libpcap level, whose API operates at a very low level:
essentially one is given means to apply BPF filters and iterate
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
libnetdude plugins, this instantly allows other developers to use their
libnetdude provides data types and APIs for the most common situations when
libpcap trace files: trace files of arbitrary size, packets,
network protocols, packet iterators, packet filters, just to name a few.
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.
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 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
The third chapter explains
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.