Libpcap File Format

The libpcap file format is the main capture file format used in TcpDump / WinDump, snort, and many other networking tools. It is fully supported by Wireshark/TShark, but they now generate pcapng files by default.

• Libpcap File Format
  • Overview
  • File Format
  • Variants
    • Nanosecond pcap
    • "Modified" pcap
    • Nokia pcap
    • AIX
    • IXIA
  • Libraries
  • Drawbacks
  • Today and the Future
  • Discussion

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, Npcap, 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 registered IANA media type value for libpcap based files is vnd.tcpdump.pcap, as per its registration document; the primary file extension for those files, as per that document, is .pcap, with some files using .cap or .dmp. .cap is not recommended, as several other capture file formats also use that extension.

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

This format is described by the draft-ietf-opsawg-pcap Internet-Draft.

Variants

Because of the drawbacks of the pcap file format, several developers and vendors have independently extended the format to meet their needs. Some developers were kind enough to change the magic bytes from the libpcap standard; for the others, Wireshark has had to include some heuristics.

Nanosecond pcap

The one official variant of the pcap format, documented in the Internet-Draft, is a version that supports nanosecond-precision time stamps. Libpcap 1.5.0 and later, and all versions of Npcap can read files in that format; older versions of libpcap, and all versions of WinPcap, cannot read it. Older versions of Wireshark cannot read it; current versions can read it and can show the full nanosecond-resolution time stamps.

The magic bytes for this format are 0xa1b23c4d (note the final two bytes). There are no changes to the file or record headers from standard libpcap, apart from the timestamp resolution.

Authorship of this variant is credited to Ulf Lamping.

"Modified" pcap

Alexey Kuznetsov created patches to libpcap to add some extra fields to the record header. (These patches were traditionally available at http://ftp.sunet.se/pub/os/Linux/ip-routing/lbl-tools/ but are no longer available there.) Within the Wireshark source code, this format is known simply as "modified pcap."

The magic bytes for this format are 0xa1b2cd34 (note the final two bytes). The file header is otherwise the same as the standard libpcap header.

The record header is extended in the following way:

                            1                   2                   3
        0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     0 |                      Timestamp (Seconds)                      |
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     4 |            Timestamp (Microseconds or nanoseconds)            |
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     8 |                    Captured Packet Length                     |
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    12 |                    Original Packet Length                     |
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    16 |                        Interface Index                        |
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    20 |           Protocol            |  Packet Type  |    Padding    |
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    24 /                                                               /
       /                          Packet Data                          /
       /                  variable length, not padded                  /
       /                                                               /

The File Header length is 24 octets.

The meaning of the additional fields in the File Header is:

Interface Index (32 bits): an unsigned integer, giving the index, in the capturing machine's list of interfaces, of the interface on which this packet came in.

Protocol (16 bits): an unsigned integer giving the Ethernet packet type of the packet.

Packet Type (8 bits): an unsigned integer with a value that is one of:

• 0, if the packet was specifically sent to the capturing machine by somebody else;
• 1, if the packet was broadcast by somebody else;
• 2, if the packet was multicast, but not broadcast, by somebody else;
• 3, if the packet was sent to somebody else by somebody else;
• 4, if the packet was sent by the capturing machine.

In the ss990915 version of the patch (which shows up in SuSE Linux 6.3) the record header instead looks like this:

                            1                   2                   3
        0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     0 |                      Timestamp (Seconds)                      |
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     4 |            Timestamp (Microseconds or nanoseconds)            |
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     8 |                    Captured Packet Length                     |
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    12 |                    Original Packet Length                     |
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    16 |                        Interface Index                        |
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    20 |           Protocol            |  Packet Type  |     CPU 1     |
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    24 |     CPU 2     |                    Padding                    |
       +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    28 /                                                               /
       /                          Packet Data                          /
       /                  variable length, not padded                  /
       /                                                               /

The meaning of the CPU 1 and CPU 2 fields is unknown.

Nokia pcap

Some Nokia boxes (firewalls?) emit a non-standard record format. It uses the standard file header, and the record headers incorporates the standard libpcap record headers, but also add 4 extra bytes of mysterious stuff. Wireshark preserves this data when saving, but otherwise ignores it.

AIX

The libpcap library used on AIX wrote pcap files with stated version number 2.2, and used RFC 1573 "ifType" values in the header where all other variants use DLT_ values. It also has nanosecond-precision packet timestamps.

Wireshark includes some extra checks if the file version is 2.2 to determine if the file is an AIX pcap.

IXIA

IXIA's lcap file format closely resembles libpcap, but adds a length field at the end of the file header, which gives the size of all records that follow. (Wireshark ignores this number.)

The magic bytes for this format are 0x1c0001ac (hardware-generated) and 0x01c0001ab (software-generated).

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:

• libpcap: the origin of this file format (for UN*X based systems)

• Npcap: Windows based version of libpcap

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

• Net::Pcap: Perl based libpcap wrapper

• Jpcap: JAVA based libpcap wrapper

• python-libpcap: Python based libpcap wrapper

• Ruby/Pcap: Ruby based libpcap wrapper

• ... you may add a libpcap wrapper for your favourite programming language or using Google if it's still missing here ...

Note that if you write your own code, it will fail to read any capture files in the "now generic pcap" format mentioned below. If you use libpcap, however, it will, when linked (at build time or run time) with a version of libpcap/NPcap that can read those files, be able to read "now generic pcap" 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/NPcap 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:

• user comments: "shows connection breakdown starting at packet 1432"
• interface information (like the network card manufacturer)
• packet drop count (and probably other counts as well)
• ...

Today and the Future

It is widely accepted that the libpcap file format serves its purpose but lacks some useful features. There's a "now generic" pcap file format described by the draft-ietf-opsawg-pcapng Internet-Draft. The new format supplies many of the capabilities listed in "Drawbacks" above.

Wireshark currently has the ability to read and write pcapng files, and does so by default, although doesn't support all of the capabilities of the files. Libpcap 1.1.0 and later have a limited ability to read them as well, although libpcap doesn't yet supporting writing them.

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"

Imported from https://wiki.wireshark.org/Development/LibpcapFileFormat on 2020-08-11 23:12:52 UTC