libpcap Documentation

When using libpcap on the GNU/Hurd platform, be aware of the following functional limitations:

• Loopback Interface: Packet capture on the loopback network interface is not supported.
• BPF Filtering: BPF works in the kernel only if the filter length is $\le$ 31 BPF instructions and does not use BPF_MOD or BPF_XOR instructions.
• Timestamping: Packet timestamping always occurs in userland.
• Wireless: Wireless monitor mode is not supported.
• Capture Scope: Packet capture only sees packets received on the interface.
• Unsupported/Ineffective APIs:
  • pcap_set_buffer_size has no effect.
  • pcap_setdirection is not supported.
  • pcap_set_promisc has no effect.

libpcap supports filtering via the BSD Packet Filter (BPF) architecture.

• In-kernel filtering: libpcap utilizes in-kernel filtering only when the underlying interface supports BPF programs (e.g., BPF packet capture interface, Linux packet socket, and GNU/Hurd interface).
• User-space filtering: On other platforms, libpcap reads every packet into user-space and evaluates it using the filter program, which incurs higher overhead.
• Standard BPF Support: NetBSD, FreeBSD, OpenBSD, DragonFly BSD, macOS, QNX, and Solaris 11.
• Linux Support: libpcap supports many memory-mapped receive mechanisms but does not currently support eBPF mechanisms. Refer to doc/README.linux for Linux-specific details.

To compile libpcap on Debian GNU/Hurd 12, the following toolchain versions are verified to work:

• Lexer/Parser: flex 2.6.4 and GNU Bison 3.8.2
• Build System: CMake 3.25.1
• Compilers: GCC 12.2.0 and Clang 14.0.6

These tests were performed using the Debian GNU/Hurd 12 system from the 2023-06-08 snapshot.

To use libpcap with Endace DAG passive network monitoring cards on a Linux host, follow these steps:

1. Install DAG software: Install and build a recent version of the DAG software distribution from Endace.
2. Configure libpcap:
   • If DAG is installed in a standard location, the ./configure script will detect it automatically.
   • If DAG is in a custom location, use the --with-dag=DIR flag, where DIR is the root of the DAG software distribution.
3. Select Capture Type:
   • Hybrid (Default): Building without specific flags includes support for both standard Linux devices (network interfaces, USB, etc.) and DAG cards.
   • DAG-only: To build libpcap with only DAG support, use --with-pcap=dag during configuration.

CMake builds also support DAG via the INSTALL.md configuration options.

When compiling libpcap on Solaris or illumos-based systems, avoid using the native lex and yacc implementations as they are unsuitable. Instead, use flex and GNU Bison. m4 is supported on both Solaris and illumos.

General requirements:

• Use flex and GNU Bison instead of lex and yacc.
• Autoconf is compatible across all these platforms.

By default, libpcap's support for Endace DAG transmit (pcap_inject and pcap_sendpacket) is disabled. To enable this experimental feature, you must explicitly configure it during the build process.

Requirements for successful transmission:

• Packets must be Ethernet frames without FCS (the standard libpcap format).
• The DAG card's transmitting port must be configured to add a 32-bit FCS to outgoing frames (the usual default).
• pcap_activate() automatically detects the card's FCS configuration and adjusts the frame composition accordingly.

Note: Transmit support is tested on DAG 7.5G2 and DAG 9.2X2; it does not support vDAG devices.

To build libpcap on Windows, you must provide a driver and library interface, as Windows lacks a native network traffic capture mechanism. You must choose between Npcap (recommended) or WinPcap (legacy/older Windows versions).

Setup Steps:

1. Download SDK: Download the Npcap or WinPcap SDK.
2. Extract SDK: Create a folder on your C: drive (e.g., C:\npcap-sdk) and extract the SDK contents there.
3. WinPcap Specifics: If using WinPcap, place the WpdPack folder from the Developer's Kit on your C: drive (e.g., C:\WpdPack).

You can access the source code via Anonymous Git at the following URL:

git clone https://github.com/the-tcpdump-group/libpcap.git

To build libpcap from the source distribution, you must first generate the configuration files using the autogen.sh script. This script builds the configure script and config.h.in.

Note that the repository contains various platform-specific documentation files (e.g., doc/README.linux, doc/README.macos, doc/README.windows.md) which provide specific instructions for different operating systems.

libpcap requires Visual Studio 2015 or later and CMake. You can use the Chocolatey package manager to install several required tools.

Install Chocolatey GUI:

choco install -y chocolateygui

Install CMake:

choco install -y cmake

libpcap provides specialized documentation for various operating systems and hardware devices. If you are using a specific platform, refer to the corresponding README file in the doc/ directory:

• AIX: doc/README.aix
• Endace DAG devices: doc/README.dag.md
• Haiku: doc/README.haiku.md
• HP-UX: doc/README.hpux
• GNU/Hurd: doc/README.hurd.md
• Linux: doc/README.linux
• macOS: doc/README.macos
• QNX: doc/README.qnx.md
• Myricom SNF devices: doc/README.snf.md
• Solaris: doc/README.solaris.md
• Windows (with Npcap): doc/README.windows.md