From 01037ab6cf11b316d7cb2fe2f7098067807a601d Mon Sep 17 00:00:00 2001 From: seladb Date: Fri, 6 Feb 2026 23:42:07 -0800 Subject: [PATCH 1/2] Make pcap optional --- docs/features.mdx | 12 +++++++++-- docs/install/android.mdx | 17 ++++++++++----- docs/install/freebsd.mdx | 3 ++- docs/install/linux.mdx | 5 ++--- docs/install/macos.mdx | 1 + docs/install/mingw.mdx | 27 +++++++++++++++--------- docs/install/vs.mdx | 33 ++++++++++++++++++------------ docs/tutorials/capture-packets.mdx | 2 +- 8 files changed, 65 insertions(+), 35 deletions(-) diff --git a/docs/features.mdx b/docs/features.mdx index cb617bae03..e85a9653be 100644 --- a/docs/features.mdx +++ b/docs/features.mdx @@ -84,8 +84,8 @@ int main(int argc, char* argv[]) if (parsedPacket.isPacketOfType(pcpp::IPv4)) { // extract source and dest IPs - pcpp::IPv4Address srcIP = parsedPacket.getLayerOfType()->getSrcIPv4Address(); - pcpp::IPv4Address destIP = parsedPacket.getLayerOfType()->getDstIPv4Address(); + auto srcIP = parsedPacket.getLayerOfType()->getSrcIPv4Address(); + auto destIP = parsedPacket.getLayerOfType()->getDstIPv4Address(); // print source and dest IPs std::cout @@ -171,6 +171,14 @@ while (reader->getNextPacket(rawPacket)) { } ``` +## libpcap / WinPcap / Npcap support + +[libpcap](https://www.tcpdump.org/) is the most popular packet capture engine and is supported on multiple platforms including Linux, MacOS, Android and FreeBSD. [WinPcap](https://www.winpcap.org/) is the Windows version of libpcap but it is no longer maintained and has been replaced by [Npcap](https://npcap.com/) which is a fork of WinPcap with more features and better performance. Both WinPcap and Npcap are supported on Windows. + +PcapPlusPlus provides a clean and simple C++ wrapper API for these engines and supports all of their main features such as live packet capture and sending packets to the network. In addition, PcapPlusPlus provides support for remote capture using WinPcap Remote Capture which allows you to capture packets from a remote machine running WinPcap. + +These capture engines are required by default but you can choose to build PcapPlusPlus without them and use other capture engines instead (e.g. DPDK, AF_XDP, PF_RING, etc). To build without libpcap/WinPcap/Npcap support you can use the `-DPCAPPP_USE_PCAP=OFF` CMake option. + ## DPDK support The Data Plane Development Kit (DPDK) is a set of data plane libraries and network interface controller drivers for fast packet processing, currently managed as an open-source project under the Linux Foundation. The DPDK provides a programming framework for x86, ARM, and PowerPC processors and enables faster development of high speed data packet networking applications (taken from [Wikipedia](https://en.wikipedia.org/wiki/Data_Plane_Development_Kit)). diff --git a/docs/install/android.mdx b/docs/install/android.mdx index 5c7e274be8..874666ca0e 100644 --- a/docs/install/android.mdx +++ b/docs/install/android.mdx @@ -9,16 +9,16 @@ title: Build for Android In order to build PcapPlusPlus for Android please make sure you have the following prerequisites: 1. [Android NDK](https://developer.android.com/ndk) should be installed -2. Pre-compiled `libpcap` library for Android + header files which can be downloaded from [the `libpcap-android` GitHub repo](https://github.com/seladb/libpcap-android) (for Android API versions 21-30) +2. If you want to to use libpcap and have `-DPCAPPP_USE_PCAP=ON`, you'll need pre-compiled `libpcap` library for Android + header files which can be downloaded from [the `libpcap-android` GitHub repo](https://github.com/seladb/libpcap-android) (for Android API versions 21-30) ## Build In order to build for Android a few parameters are needed: - The path of Android NDK. Let's assume it's stored in `ANDROID_NDK` -- Android API version - must be between 21 and 30. Let's assume it's stored in `API_VERSIOM` +- Android API version - must be between 21 and 30. Let's assume it's stored in `API_VERSION` - Target architecture which accepts the following values: `arm64-v8a`, `armeabi-v7a`, `x86`, `x86_64`. Let's assume it's stored in `ANDROID_ABI` -- The path of `libpcap` compiled for Android. Let's assume it's stored in `LIBPCAP_DIR` +- If you want to to use libpcap features: the path of `libpcap` compiled for Android. Let's assume it's stored in `LIBPCAP_DIR` Assuming you want to build PcapPlusPlus into a `build` directory: @@ -26,8 +26,8 @@ Assuming you want to build PcapPlusPlus into a `build` directory: cmake \ -DCMAKE_TOOLCHAIN_FILE="${ANDROID_NDK}/build/cmake/android.toolchain.cmake" \ -DANDROID_PLATFORM="${API_VERSION}" \ --DANDROID_ABI="${ABI}" \ --DPCAP_LIBRARY="${LIBPCAP_DIR}/${ABI}/${API_VERSION}/libpcap.a" \ +-DANDROID_ABI="${ANDROID_ABI}" \ +-DPCAP_LIBRARY="${LIBPCAP_DIR}/${ANDROID_ABI}/${API_VERSION}/libpcap.a" \ -DPCAP_INCLUDE_DIR="${LIBPCAP_DIR}/include/" \ -DPCAPPP_BUILD_TESTS=OFF \ -DPCAPPP_BUILD_EXAMPLES=OFF \ @@ -40,6 +40,12 @@ cmake \ ::: +:::tip NOTE 2 + +`-DPCAP_LIBRARY` and `-DPCAP_INCLUDE_DIR` are only needed if you want to use libpcap features. If you want to build without libpcap support you can use the `-DPCAPPP_USE_PCAP=OFF` CMake option and then you won't need to provide these parameters. + +::: + And then initiate the build in one of two ways: - Using CMake: @@ -65,6 +71,7 @@ The following configuration options are available (on top of CMake's built-in op | **`-DCMAKE_TOOLCHAIN_FILE=`** | Android CMake toolchain file, usuaully resides in: `${ANDROID_NDK}/build/cmake/android.toolchain.cmake`. This is a mandatory option | | **`-DANDROID_PLATFORM=`** | Android API version, must be between 21 and. . This is a mandatory option | | **`-DANDROID_ABI=`** | Android target architecture which accepts one of the following values: `arm64-v8a`, `armeabi-v7a`, `x86`, `x86_64`. This is a mandatory option | +| **`-DPCAPPP_USE_PCAP=`** | Build PcapPlusPlus with libpcap support (default value is `ON`). If you set it to `OFF` you won't need to provide `-DPCAP_LIBRARY` and `-DPCAP_INCLUDE_DIR` options and PcapPlusPlus will be built without libpcap support | | **`-DPCAP_LIBRARY=`** | The path of `libpcap.a` that is compiled for Android with the target architecture and API version, for example: `${LIBPCAP_DIR}/${ABI}/${API_VERSION}/libpcap.a`. This is a mandatory option | | **`-DPCAP_INCLUDE_DIR=`** | The path of lipbpcap include files, for example: `${LIBPCAP_DIR}/include/`. This is a mandatory option | | **`-DPCAPPP_BUILD_EXAMPLES=`** | Build PcapPlusPlus examples, in most cases should be set to `OFF`. If you want to run [PcapPlusPlus examples](../examples) on an Android device you need shell access, and for some of them you also need a rooted device. The examples will reside in `build/examples_bin` | diff --git a/docs/install/freebsd.mdx b/docs/install/freebsd.mdx index c83e8d7049..710b37d36f 100644 --- a/docs/install/freebsd.mdx +++ b/docs/install/freebsd.mdx @@ -10,7 +10,7 @@ In order to compile PcapPlusPlus on FreeBSD please make sure you have the follow 1. `git` (if not installed please run: `pkg install git`) 2. `CMake` (if not installed please run: `pkg install cmake`) -3. `libpcap` (if not installed please run: `pkg install libpcap`) +3. **Optional** `libpcap` if you want to use libpcap features such as packet capture and have `-DPCAPPP_USE_PCAP=ON` (if not installed please run: `pkg install libpcap`) ## Build @@ -47,6 +47,7 @@ The following configuration options are available (on top of CMake's built-in op | Option | Description | | :-------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| **`-DPCAPPP_USE_PCAP=`** | Build PcapPlusPlus with libpcap support (default value is `ON`) | | **`-DPCAPPP_BUILD_EXAMPLES=`** | Build PcapPlusPlus examples (default value is `ON` if building the project itself, otherwise `OFF`) | | **`-DPCAPPP_BUILD_TESTS=`** | Build PcapPlusPlus tests (default value is `ON` if building the project itself, otherwise `OFF`) | | **`-DPCAPPP_BUILD_TUTORIALS=`** | Build PcapPlusPlus tutorials. This option is only available if `DPCAPPP_BUILD_EXAMPLES=ON`. The tutorials binaries will be under `build/tutorials_bin` (default value is `OFF`) | diff --git a/docs/install/linux.mdx b/docs/install/linux.mdx index 92f73b824c..aba3a56c24 100644 --- a/docs/install/linux.mdx +++ b/docs/install/linux.mdx @@ -6,9 +6,7 @@ title: Build on Linux ## Prerequisites -In order to compile PcapPlusPlus on Linux please make sure you have the following components installed: - -1. **libpcap developers pack** - contains the libpcap library PcapPlusPlus is linking with and relevant the header files. You can download it from [http://www.tcpdump.org/#latest-release](http://www.tcpdump.org/#latest-release) or through the standard Linux package managers such as `apt-get` or `yum`: +1. **OPTIONAL** - if you want to use libpcap features such as packet capture and have `-DPCAPPP_USE_PCAP=ON` , you'll need to install **libpcap developers pack** which contains the libpcap library PcapPlusPlus is linking with and relevant the header files. You can download it from [http://www.tcpdump.org/#latest-release](http://www.tcpdump.org/#latest-release) or through the standard Linux package managers such as `apt-get` or `yum`: ```bash sudo apt-get install libpcap-dev @@ -57,6 +55,7 @@ The following configuration options are available (on top of CMake's built-in op | Option | Description | | :-------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **`-DPCAPPP_USE_PCAP=`** | Build PcapPlusPlus with libpcap support (default value is `ON`) | | **`-DPCAPPP_BUILD_EXAMPLES=`** | Build PcapPlusPlus examples (default value is `ON` if building the project itself, otherwise `OFF`) | | **`-DPCAPPP_BUILD_TESTS=`** | Build PcapPlusPlus tests (default value is `ON` if building the project itself, otherwise `OFF`) | | **`-DPCAPPP_BUILD_TUTORIALS=`** | Build PcapPlusPlus tutorials. This option is only available if `DPCAPPP_BUILD_EXAMPLES=ON`. The tutorials binaries will be under `build/tutorials_bin` (default value is `OFF`) | diff --git a/docs/install/macos.mdx b/docs/install/macos.mdx index f43d14d433..a73265ea02 100644 --- a/docs/install/macos.mdx +++ b/docs/install/macos.mdx @@ -50,6 +50,7 @@ The following configuration options are available (on top of CMake's built-in op | Option | Description | | :--------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| **`-DPCAPPP_USE_PCAP=`** | Build PcapPlusPlus with libpcap support (default value is `ON`) | | **`-DPCAPPP_BUILD_EXAMPLES=`** | Build PcapPlusPlus examples (default value is `ON` if building the project itself, otherwise `OFF`) | | **`-DPCAPPP_BUILD_TESTS=`** | Build PcapPlusPlus tests (default value is `ON` if building the project itself, otherwise `OFF`) | | **`-DPCAPPP_BUILD_TUTORIALS=`** | Build PcapPlusPlus tutorials. This option is only available if `DPCAPPP_BUILD_EXAMPLES=ON`. The tutorials binaries will be under `build/tutorials_bin` (default value is `OFF`) | diff --git a/docs/install/mingw.mdx b/docs/install/mingw.mdx index 3b3223a9fd..504986eda8 100644 --- a/docs/install/mingw.mdx +++ b/docs/install/mingw.mdx @@ -14,25 +14,31 @@ In order to compile PcapPlusPlus on Windows using MinGW-w64 you need the followi ```shell PATH=%PATH%;C:\mingw-w64\i686-8.1.0-posix-dwarf-rt_v6-rev0\mingw32\bin ``` -4. Download and install [WinPcap](https://www.winpcap.org/install/) **OR** [Npcap](https://npcap.com/#download) on your system - :::tip Note for Npcap: - If you install **Npcap** please check the `Install Npcap in WinPcap API-compatilbility mode` option during installation: +4. **OPTIONAL** If you want to use WinPcap/Npcap features such as packet capture and have `-DPCAPPP_USE_PCAP=ON`: + 1. Download and install [WinPcap](https://www.winpcap.org/install/) **OR** [Npcap](https://npcap.com/#download) on your system + :::tip Note for Npcap: + If you install **Npcap** please check the `Install Npcap in WinPcap API-compatilbility mode` option during installation: - ![Npcap-WinPcap compatilibitly](/img/install/Npcap_compatibility_mode.png) - ::: - -5. [WinPcap developer's pack](https://www.winpcap.org/devel.htm) **OR** [Npcap SDK](https://nmap.org/npcap/guide/npcap-devguide.html) - containing the `wpcap` library PcapPlusPlus is linking with plus relevant `.h` files. - 1. WinPcap developer's pack can be downloaded from here: [https://www.winpcap.org/devel.htm](https://www.winpcap.org/devel.htm) - 2. Npcap SDK can be downloaded from here: [https://nmap.org/npcap/#download](https://nmap.org/npcap/#download) + ![Npcap-WinPcap compatilibitly](/img/install/Npcap_compatibility_mode.png) + ::: + 2. Download and install [WinPcap developer's pack](https://www.winpcap.org/devel.htm) **OR** [Npcap SDK](https://nmap.org/npcap/#download) - containing the wpcap library PcapPlusPlus is linking with plus relevant `h` files. ## Build Assuming you want to build PcapPlusPlus into a `build` directory: +With WinPcap/Npcap support: + ```shell cmake -G "MinGW Makefiles" -DPCAP_ROOT= -S . -B build ``` +Without WinPcap/Npcap support: + +```shell +cmake -G "MinGW Makefiles" -DPCAPPP_USE_PCAP=OFF -S . -B build +``` + And then initiate the build in one of two ways: - Using CMake: @@ -60,7 +66,8 @@ The following configuration options are available (on top of CMake's built-in op | Option | Description | | :-------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| **`-DPCAP_ROOT=`** | Npcap SDK or WinPcap developer pack directory (mandatory option) | +| **`-DPCAPPP_USE_PCAP=`** | Build PcapPlusPlus with WinPcap/Npcap support (default value is `ON`) | +| **`-DPCAP_ROOT=`** | Npcap SDK or WinPcap developer pack directory (mandatory option if `-DPCAPPP_USE_PCAP=ON`) | | **`-DPCAPPP_BUILD_EXAMPLES=`** | Build PcapPlusPlus examples (default value is `ON` if building the project itself, otherwise `OFF`) | | **`-DPCAPPP_BUILD_TESTS=`** | Build PcapPlusPlus tests (default value is `ON` if building the project itself, otherwise `OFF`) | | **`-DPCAPPP_BUILD_TUTORIALS=`** | Build PcapPlusPlus tutorials. This option is only available if `DPCAPPP_BUILD_EXAMPLES=ON`. The tutorials binaries will be under `build\tutorials_bin` (default value is `OFF`) | diff --git a/docs/install/vs.mdx b/docs/install/vs.mdx index 337524150f..095677690a 100644 --- a/docs/install/vs.mdx +++ b/docs/install/vs.mdx @@ -12,29 +12,35 @@ In order to build PcapPlusPlus on Windows with Visual Studio you need the follow 1. A [supported version](../platforms) of Microsoft Visual Studio 2. `CMake` which can be installed from: [https://cmake.org/install/](https://cmake.org/install/) or with `pacman` if using MSYS2: `pacman -S mingw-w64-x86_64-cmake` -3. Download and install [WinPcap](https://www.winpcap.org/install/) **OR** [Npcap](https://npcap.com/#download) on your system - :::tip Note for Npcap: - If you install **Npcap** please check the `Install Npcap in WinPcap API-compatilbility mode` option during installation: - - ![Npcap-WinPcap compatilibitly](/img/install/Npcap_compatibility_mode.png) - ::: - -4. [WinPcap developer's pack](https://www.winpcap.org/devel.htm) **OR** [Npcap SDK](https://nmap.org/npcap/guide/npcap-devguide.html) - containing the wpcap library PcapPlusPlus is linking with plus relevant `h` files. - 1. WinPcap developer's pack can be downloaded from here: [https://www.winpcap.org/devel.htm](https://www.winpcap.org/devel.htm) - 2. Npcap SDK can be downloaded from here: [https://nmap.org/npcap/#download](https://nmap.org/npcap/#download) -5. In some cases you also need to download and install: +3. **OPTIONAL** If you want to use WinPcap/Npcap features such as packet capture and have `-DPCAPPP_USE_PCAP=ON`: + 1. Download and install [WinPcap](https://www.winpcap.org/install/) **OR** [Npcap](https://npcap.com/#download) on your system + :::tip Note for Npcap: + If you install **Npcap** please check the `Install Npcap in WinPcap API-compatilbility mode` option during installation: + + ![Npcap-WinPcap compatilibitly](/img/install/Npcap_compatibility_mode.png) + ::: + 2. Download and install [WinPcap developer's pack](https://www.winpcap.org/devel.htm) **OR** [Npcap SDK](https://nmap.org/npcap/#download) - containing the wpcap library PcapPlusPlus is linking with plus relevant `h` files. +4. In some cases you also need to download and install: 1. [Microsoft Visual C++ Redistributable](https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads) for your version of Visual Studio 2. [Microsoft Visual C++ 2010 Redistributable](https://www.microsoft.com/en-us/download/confirmation.aspx?id=14632) -6. OPTIONAL - download [Zstd](https://github.com/facebook/zstd/releases/latest) libraries if you wish to enable [PCAPNG streaming compression support](../features#readingwriting-pcapng-files-with-compression) +5. **OPTIONAL** - download [Zstd](https://github.com/facebook/zstd/releases/latest) libraries if you wish to enable [PCAPNG streaming compression support](../features#readingwriting-pcapng-files-with-compression) ## Build Assuming you want to build PcapPlusPlus into a `build` directory: +With WinPcap/Npcap support: + ```shell cmake -DPCAP_ROOT= -S . -B build ``` +Without WinPcap/Npcap support: + +```shell +cmake -DPCAPPP_USE_PCAP=OFF -S . -B build +``` + You can use the following CMake options to determine specific parameters: - To build for a specific (non-default) version of Visual Studio you can use the `-G` option, for example `-G "Visual Studio 16 2019"` will builf for VS 2019 @@ -72,7 +78,8 @@ The following configuration options are available (on top of CMake's built-in op | Option | Description | | :-------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| **`-DPCAP_ROOT=`** | Npcap SDK or WinPcap developer pack directory (mandatory option) | +| **`-DPCAPPP_USE_PCAP=`** | Build PcapPlusPlus with WinPcap/Npcap support (default value is `ON`) | +| **`-DPCAP_ROOT=`** | Npcap SDK or WinPcap developer pack directory (mandatory option if `-DPCAPPP_USE_PCAP=ON`) | | **`-DPCAPPP_BUILD_EXAMPLES=`** | Build PcapPlusPlus examples (default value is `ON` if building the project itself, otherwise `OFF`) | | **`-DPCAPPP_BUILD_TESTS=`** | Build PcapPlusPlus tests (default value is `ON` if building the project itself, otherwise `OFF`) | | **`-DPCAPPP_BUILD_TUTORIALS=`** | Build PcapPlusPlus tutorials. This option is only available if `DPCAPPP_BUILD_EXAMPLES=ON`. The tutorials binaries will be under `build\tutorials_bin` (default value is `OFF`) | diff --git a/docs/tutorials/capture-packets.mdx b/docs/tutorials/capture-packets.mdx index d96b6cc9c1..46d14cb603 100644 --- a/docs/tutorials/capture-packets.mdx +++ b/docs/tutorials/capture-packets.mdx @@ -7,7 +7,7 @@ title: 'Part 3: Capture/Send Packets' ## Introduction -PcapPlusPlus provides simple and easy-to-use wrappers for libpcap/WinPcap APIs for capturing and sending packets over network interfaces. These wrappers pretty much sum up in the following classes: +PcapPlusPlus provides simple and easy-to-use wrappers for libpcap/WinPcap/Npcap APIs for capturing and sending packets over network interfaces. These wrappers pretty much sum up in the following classes: - `PcapLiveDevice` - wraps libpcap functionality of capturing and sending packets and also provide information and statistics on the network interface - `WinPcapLiveDevice` - wraps WinPcap/Npcap functionality which is basically similar to libpcap but provides adjustments for Windows OS. This class inherits PcapLiveDevice and provides the necessary changes for Windows vs. Linux/MacOS/FreeBSD/Android From d89b5a17e3c78146115a289343e51d22705c0d1b Mon Sep 17 00:00:00 2001 From: seladb Date: Fri, 6 Feb 2026 23:43:49 -0800 Subject: [PATCH 2/2] Fix formatting --- docs/install/mingw.mdx | 1 + docs/install/vs.mdx | 2 ++ 2 files changed, 3 insertions(+) diff --git a/docs/install/mingw.mdx b/docs/install/mingw.mdx index 504986eda8..9504149f5c 100644 --- a/docs/install/mingw.mdx +++ b/docs/install/mingw.mdx @@ -21,6 +21,7 @@ In order to compile PcapPlusPlus on Windows using MinGW-w64 you need the followi ![Npcap-WinPcap compatilibitly](/img/install/Npcap_compatibility_mode.png) ::: + 2. Download and install [WinPcap developer's pack](https://www.winpcap.org/devel.htm) **OR** [Npcap SDK](https://nmap.org/npcap/#download) - containing the wpcap library PcapPlusPlus is linking with plus relevant `h` files. ## Build diff --git a/docs/install/vs.mdx b/docs/install/vs.mdx index 095677690a..62b9bc4ac8 100644 --- a/docs/install/vs.mdx +++ b/docs/install/vs.mdx @@ -19,7 +19,9 @@ In order to build PcapPlusPlus on Windows with Visual Studio you need the follow ![Npcap-WinPcap compatilibitly](/img/install/Npcap_compatibility_mode.png) ::: + 2. Download and install [WinPcap developer's pack](https://www.winpcap.org/devel.htm) **OR** [Npcap SDK](https://nmap.org/npcap/#download) - containing the wpcap library PcapPlusPlus is linking with plus relevant `h` files. + 4. In some cases you also need to download and install: 1. [Microsoft Visual C++ Redistributable](https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads) for your version of Visual Studio 2. [Microsoft Visual C++ 2010 Redistributable](https://www.microsoft.com/en-us/download/confirmation.aspx?id=14632)