Getting Started
PcapPlusPlus is a multi-platform C++ library for capturing, parsing and crafting of network packets. It is designed to be efficient, powerful and easy to use.
PcapPlusPlus enables decoding and forging capabilities for a large variety of network protocols. It also provides easy to use C++ wrappers for the most popular packet processing engines such as libpcap, WinPcap, Npcap (WinPcap's successor), DPDK, eBPF AF_XDP and PF_RING.
Latest version: v24.09Quick Start
This guide will help you install and build your first PcapPlusPlus application. You can find more information in the Tutorials and in the installation guide.
Please choose your platform:
- Linux
- MacOS
- Windows - MinGW
- Windows - Visual Studio
- Android
- FreeBSD
Step 1 - download PcapPlusPlus
Before downloading PcapPlusPlus make sure you have the prerequisites installed for Linux.
Pre-compiled packages are available for recent versions of Ubuntu, Fedora, RHEL and Alpine. You can find them under the v24.09 release.
Another option is using Homebrew on Linux if you have it installed on your system:
brew install pcapplusplus
If you have another Linux distribution or GCC version you'll need to build PcapPlusPlus from source. Make sure not to skip the installation part.
Step 2 - create your first app
If you downloaded a pre-compiled package go to: /path/to/your/package/example-app.
If not, download the ExampleApp source files.
Make sure you see the following files:
|-- main.cpp
|-- 1_packet.pcap
|-- CMakeLists.txt
main.cpp is the example application we'll use.
1_packet.pcap is a pcap file the app reads from.
CMakeLists.txt will help us build the app.
Step 3 - build and run your app
Configure CMake:
cmake -S . -B build -DPcapPlusPlus_ROOT=/path/to/your/package
Build the app:
cmake --build build
An executable file will be created which contains the compiled app. You can now run it and should be able to see the following output:
./example-app
Source IP is '10.0.0.138'; Dest IP is '10.0.0.1'
Step 1 - install PcapPlusPlus
Before installing PcapPlusPlus make sure you have the prerequisites installed for MacOS.
The easiest way to get PcapPlusPlus is from Homebrew:
brew install pcapplusplus
If you prefer not to use Homebrew you can also found pre-compiled packages for various versions of Xcode in the v24.09 release.
Another option is to build PcapPlusPlus from source. Make sure not to skip the installation part.
Step 2 - create your first app
If you downloaded a pre-compiled package go to: /path/to/your/package/example-app.
If you installed PcapPlusPlus using Homebrew or built from source, download the ExampleApp source files.
Make sure you see the following files:
|-- main.cpp
|-- 1_packet.pcap
|-- CMakeLists.txt
main.cpp is the example application we'll use.
1_packet.pcap is a pcap file the app reads from.
CMakeLists.txt will help us build the app.
Step 3 - build and run your app
Configure CMake:
cmake -S . -B build -DPcapPlusPlus_ROOT=/path/to/your/package
Build the app:
cmake --build build
An executable file will be created which contains the compiled app. You can now run it and should be able to see the following output:
./example-app
Source IP is '10.0.0.138'; Dest IP is '10.0.0.1'
Step 1 - install PcapPlusPlus
Before installing PcapPlusPlus make sure you have the prerequisites installed for MinGW-w64.
Pre-compiled packages are available for MinGW-w64. You can find them under the v24.09 release.
Make sure your MinGW-w64 GCC version matches the pre-compiled package. Otherwise you need to build PcapPlusPlus from source.
Step 2 - create your first app
If you downloaded a pre-compiled package go to: Drive:\path\to\your\package\example-app.
If you built it from source, download the ExampleApp source files.
Make sure you see the following files:
|-- main.cpp
|-- 1_packet.pcap
|-- CMakeLists.txt
main.cpp is the example application we'll use.
1_packet.pcap is a pcap file the app reads from.
CMakeLists.txt will help us build the app.
Step 3 - build and run your app
Configure CMake:
cmake -G "MinGW Makefiles" -S . -B build -DPcapPlusPlus_ROOT=Drive:\path\to\your\package -DPCAP_ROOT=Drive:\path\to\npcap-sdk -DPacket_ROOT=Drive:\path\to\npcap-sdk
Build the app:
cmake --build build
An executable file will be created which contains the compiled app. You can now run it and should be able to see the following output:
example-app.exe
Source IP is '10.0.0.138'; Dest IP is '10.0.0.1'
Step 1 - install PcapPlusPlus
Before installing PcapPlusPlus make sure you have the prerequisites installed for Visual Studio. Please notice that the currently supported versions of Visual Studio are 2019 and 2022.
Download the pre-compiled package for the Visual Studio version you have (VS2019 or VS2022) from the v24.09 release. Please notice there are 4 different configurations for each VS version - x64 / Win32 and Debug / Release. It's important to remember because you'll use them later.
Step 2 - create your first app
Go to: Drive:\path\to\your\package\example-app.
Make sure you see the following files:
|-- main.cpp
|-- 1_packet.pcap
|-- CMakeLists.txt
main.cpp is the example application we'll use.
1_packet.pcap is a pcap file the app reads from.
CMakeLists.txt will help us build the app.
Step 3 - build and run your app
Configure CMake:
- VS2019 - x64
- VS2019 - Win32
- VS2022 - x64
- VS2022 - Win32
cmake -A x64 -G "Visual Studio 16 2019" -S . -B build -DPcapPlusPlus_ROOT=Drive:\path\to\your\package -DPCAP_ROOT=Drive:\path\to\npcap-sdk -DPacket_ROOT=Drive:\path\to\npcap-sdk
cmake -A Win32 -G "Visual Studio 16 2019" -S . -B build -DPcapPlusPlus_ROOT=Drive:\path\to\your\package -DPCAP_ROOT=Drive:\path\to\npcap-sdk -DPacket_ROOT=Drive:\path\to\npcap-sdk
cmake -A x64 -G "Visual Studio 17 2022" -S . -B build -DPcapPlusPlus_ROOT=Drive:\path\to\your\package -DPCAP_ROOT=Drive:\path\to\npcap-sdk -DPacket_ROOT=Drive:\path\to\npcap-sdk
cmake -A Win32 -G "Visual Studio 17 2022" -S . -B build -DPcapPlusPlus_ROOT=Drive:\path\to\your\package -DPCAP_ROOT=Drive:\path\to\npcap-sdk -DPacket_ROOT=Drive:\path\to\npcap-sdk
Build the app:
- Debug
- Release
cmake --build build --config Debug
cmake --build build --config Release
An executable file will be created which contains the compiled app. You can now run it and should be able to see the following output:
example-app.exe
Source IP is '10.0.0.138'; Dest IP is '10.0.0.1'
ToyVpn
ToyVpn is an Android example app provided by Google that demonstrates Android APIs to create VPN solutions. You can read more about it in the Android documentation.
ToyVpn uses VpnService to handle incoming and outgoing network traffic, which means is has access to the network packets going through the VPN (which is otherwise not possible on non-rooted devices). This makes it a great example of how PcapPlusPlus can be used in Android apps and run on any device without special requirements such as a rooted device.
ToyVpn-PcapPlusPlus
ToyVpn-PcapPlusPlus is a version of ToyVpn that uses PcapPlusplus to gather data and metrics on the network traffic that goes through the VPN. It collects data such as packet count of different protocols (IPv4, IPv6, DNS, TLS, etc.), TCP connections, DNS requests and responses, TLS versions, TLS Server Name Indication (SNI), and more. These metrics are collected and written to the app's log. In addition to data collection, all of the network traffic is captured and saved to a pcap file that can be used for further investigation.
ToyVpn-PcapPlusPlus's README.md file contains detailed information on how to build and install the app.
PcapPlusPlus pre-compiled libraries are available in the release page: v24.09 release.
Here is a screenshot of the app:
And here is an example of the metrics collected by the app (as written to the app's log):
03-19 00:57:33.076 6085 6130 I PcapPlusPlusInterface: Packet stats:
03-19 00:57:33.076 6085 6130 I PcapPlusPlusInterface: Packets=2639
03-19 00:57:33.076 6085 6130 I PcapPlusPlusInterface: IPv4=2620
03-19 00:57:33.076 6085 6130 I PcapPlusPlusInterface: IPv6=11
03-19 00:57:33.076 6085 6130 I PcapPlusPlusInterface: TCP=2583
03-19 00:57:33.076 6085 6130 I PcapPlusPlusInterface: UDP=37
03-19 00:57:33.076 6085 6130 I PcapPlusPlusInterface: Connections=48
03-19 00:57:33.076 6085 6130 I PcapPlusPlusInterface: DNS_req=18
03-19 00:57:33.076 6085 6130 I PcapPlusPlusInterface: DNS_res=19
03-19 00:57:33.076 6085 6130 I PcapPlusPlusInterface: Top_TLS_Version=[(TLS 1.3, 27)]
03-19 00:57:33.076 6085 6130 I PcapPlusPlusInterface: TOP_SNI=[(i.ytimg.com, 4), (cdn.ampproject.org, 4), (lh5.googleusercontent.com, 2), (google.com, 2), (googleads.g.doubleclick.net, 2)]
Do I need a rooted device in order to use PcapPlusPlus in my Android app?
Not at all! Please follow this link
Using PcapPlusPlus in my app
Please follow this link
Step 1 - install PcapPlusPlus
Before installing PcapPlusPlus make sure you have the prerequisites installed for FreeBSD.
Pre-compiled packages are available for recent versions of FreeBSD. You can find them under the v24.09 release.
If you have other versions of FreeBSD you'll need to build PcapPlusPlus from source. Make sure not to skip the installation part.
Step 2 - create your first app
If you downloaded a pre-compiled package go to: /path/to/your/package/example-app.
If you built it from source download the ExampleApp source files.
Make sure you see the following files:
|-- main.cpp
|-- 1_packet.pcap
|-- CMakeLists.txt
main.cpp is the example application we'll use.
1_packet.pcap is a pcap file the app reads from.
CMakeLists.txt will help us build the app.
Step 3 - build and run your app
Configure CMake:
cmake -S . -B build -DPcapPlusPlus_ROOT=/path/to/your/package
Build the app:
cmake --build build
An executable file will be created which contains the compiled app. You can now run it and should be able to see the following output:
./example-app
Source IP is '10.0.0.138'; Dest IP is '10.0.0.1'