Libpcap File Format

The libpcap file format is the main capture file format used in TcpDump/WinDump, Wireshark/TShark, snort, and many other networking tools.

Overview

This file format is a very basic format to save captured network data. As the libpcap library became the "de facto" standard of network capturing on UN*X, it became the "common denominator" for network capture files in the open source world (there seems to be no such thing as a "common denominator" in the commercial network capture world at all).

Libpcap, and the Windows port of libpcap, WinPcap, use the same file format.

Although it's sometimes assumed that this file format is suitable for Ethernet networks only, it can serve many different network types, examples can be found at the Wireshark's Supported Capture Media page; all listed types are handled by the libpcap file format.

The proposed file extension for libpcap based files is: .pcap

Wireshark handles all capture file I/O in the wiretap library. You'll find further details about the libpcap file format in the wiretap/libpcap.c and .h files

File Format

There are some variants of the format "in the wild", the following will only describe the commonly used format in its current version 2.4. This format version hasn't changed for quite a while (at least since libpcap 0.4 in 1998), so it's not expected to change except for the PCAPng file format mentioned below.

The one official variant of the file is a version that supports nanosecond-precision time stamps. Current releases of libpcap and WinPcap cannot read files in that format; only the version on the git trunk for libpcap can read it. Older versions of Wireshark cannot read it; current versions can read it and can show the full nanosecond-resolution time stamps.

The file has a global header containing some global information followed by zero or more records for each captured packet, looking like this:

Global Header

Packet Header

Packet Data

Packet Header

Packet Data

Packet Header

Packet Data

...

A captured packet in a capture file does not necessarily contain all the data in the packet as it appeared on the network; the capture file might contain at most the first N bytes of each packet, for some value of N. The value of N, in such a capture, is called the "snapshot length" or "snaplen" of the capture. N might be a value larger than the largest possible packet, to ensure that no packet in the capture is "sliced" short; a value of 65535 will typically be used in this case.

Record (Packet) Header

Packet Data

Libraries

It shouldn't be too hard to implement functions to read/write a libpcap file from scratch as it's a really simple file format. However, if you want to use a library for this purpose, or if you need to actually capture packets from a live network, the following libraries are available to do just this:

There are wrappers for various programming languages available (but you must have one of the above libs installed):

Note that if you write your own code, it will fail to read any capture files in the "next generation libpcap" format mentioned below. If you use libpcap, however, it will, when linked (at build time or run time) with a version of libpcap/WinPcap that can read those files, be able to read "next generation libpcap" files that don't use features not supported by the current libpcap API (such as packets from multiple interfaces with different link-layer types) as well as reading the current libpcap format. As such, you should use libpcap/WinPcap if you can, rather than writing your own code to read those files.

Drawbacks

The libpcap format is very simple, one of the reasons that it has gained such a wide usage. Unfortunately it misses a few things which would be helpful:

Future

It is widely accepted that the libpcap file format serves its purpose but lacks some useful features. There's a proposal of a next generation pcap file format available at: http://www.winpcap.org/ntar/draft/PCAP-DumpFileFormat.html. The new format supplies many of the capabilities listed in "Drawbacks" above.

This is still a proposal for quite a while now. Wireshark currently has the ability to read at least some pcap-NG files, although it doesn't support all of the capabilities of the files, and libpcap 1.1.0 and later have a limited ability to read them as well. The NTAR - Network Trace Archival and Retrieval library is currently under development. When finished it can read/write the records in that format, but not interpret them (like Wireshark does); in the future, libpcap and Wireshark will use that library and will interpret the records.

More details about the integrating of the pcapng file format into Wireshark at: Development/PcapNg

Discussion

May be, it will be better, to use the word "data block" or "block" or some other instead of "packet"

Development/LibpcapFileFormat (last edited 2013-07-29 21:59:03 by GuyHarris)