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 and PF_RING.

v21.11 Release

---

Quick 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

Step 1 - install PcapPlusPlus

Before installing PcapPlusPlus make sure you have the prerequisites installed for Linux.

Pre-compiled packages are available for recent versions of Ubuntu, Fedora and CentOS. You can find them under the v21.11 release. After downloading and extracting the archive file go to: /path/to/your/package/ and run the installation script:

./install.sh

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 you built it from source go to: /path/to/pcapplusplus/source/Tutorials/Tutorial-HelloWorld.

Make sure you see the following files:

 |-- main.cpp
 |-- 1_packet.pcap

main.cpp is the example application we'll use.

1_packet.pcap is a pcap file the app reads from.

Step 3 - create a Makefile

If you downloaded a pre-compiled package you can find a Makefile in /path/to/your/package/example-app. This Makefile is already configured.

If you built it from source:

• go to /path/to/pcapplusplus/source/Tutorials/Tutorial-HelloWorld
• rename Makefile.non_windows to Makefile

Step 4 - build and run your app

Run make to build the app:

$ make

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:

Source IP is '10.0.0.138'; Dest IP is '10.0.0.1'

MacOS

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 MacOS and Xcode in the v21.11 release. After downloading and extracting the archive file go to: /path/to/your/package/ and run the installation script:

./install.sh

Another option is to build PcapPlusPlus from source. Make sure not to skip the installation part.

Step 2 - create your first app

If you installed PcapPlusPlus using Homebrew go to the Hello World tutorial on GitHub and get the files in that directory.

If you downloaded a pre-compiled package go to: /path/to/your/package/example-app.

If you built it from source go to: /path/to/pcapplusplus/source/Tutorials/Tutorial-HelloWorld.

Make sure you see the following files:

 |-- main.cpp
 |-- 1_packet.pcap

main.cpp is the example application we'll use.

1_packet.pcap is a pcap file the app reads from.

Step 3 - create a Makefile

If you downloaded a pre-compiled package you can find a Makefile in /path/to/your/package/example-app. This Makefile is already configured.

If you built it from source or downloaded it from GitHub:

• go to the directory of the tutorial /path/to/pcapplusplus/source/Tutorials/Tutorial-HelloWorld
• rename Makefile.non_windows to Makefile

Step 4 - build and run your app

Run make to build the app:

$ make

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:

Source IP is '10.0.0.138'; Dest IP is '10.0.0.1'

Windows - MinGW

Step 1 - install PcapPlusPlus

Before installing PcapPlusPlus make sure you have the prerequisites installed for MinGW32 or MinGW-w64.

If you have MinGW with GCC version 5.3.0 or MinGW-w64 with GCC version 6.3.0 you can download a pre-compiled package from the v21.11 release.

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 go to: Drive:\path\to\pcapplusplus\source\Tutorials\Tutorial-HelloWorld.

Make sure you see the following files:

 |-- main.cpp
 |-- 1_packet.pcap

main.cpp is the example application we'll use.

1_packet.pcap is a pcap file the app reads from.

Step 3 - create a Makefile

If you downloaded a pre-compiled package you can find a Makefile in Drive:\path\to\your\package\example-app. This Makefile is already configured.

If you built it from source:

• go to Drive:\path\to\pcapplusplus\source\Tutorials\Tutorial-HelloWorld
• rename Makefile.windows to Makefile

Step 4 - build and run your app

Run make to build the app:

C:\path\to\example\app>mingw32-make.exe

An .exe file will be created which contains the compiled app. You can now run it and should be able to see the following output:

Source IP is '10.0.0.138'; Dest IP is '10.0.0.1'

Windows - Visual Studio

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 2015, 2017 and 2019.

Download the pre-compiled package for the Visual Studio version you have (VS2015, VS2017 or VS2019) from the v21.11 release.

Step 2 - create your first app

Go to: Drive:\path\to\your\package\ExampleProject.

You can find the following files there:

 |-- main.cpp
 |-- 1_packet.pcap
 |-- ExampleProject.sln
 |-- ExampleProject.vcxproj
 |-- ExampleProject.vcxproj.filters
 |-- PcapPlusPlusPropertySheet.props

main.cpp is the example application we'll use.

1_packet.pcap is a pcap file the app reads from.

ExampleProject.sln, ExampleProject.vcxproj, ExampleProject.vcxproj.filters are the Visual Studio solution/project files.

PcapPlusPlusPropertySheet.props is the PcapPlusPlus properties file.

Step 3 - configure your solution

Edit the PcapPlusPlusPropertySheet.props file in the following way:

• Set the value of the PcapPlusPlusHome XML node to the folder where PcapPlusPlus binaries package is located (the one you downloaded)
• Set the value of the PcapSdkHome XML node to the folder where WinPcap Developer's Pack / Npcap SDK is located
• Set the value of the PThreadWin32Home node to the folder where pthread-win32 is located

Step 4 - build and run your app

You can now open ExampleProject.sln in Visual Studio and build it in the various available configurations (x86/x64 and debug/release).

The .exe file will be created under ExampleProject\Debug\x86 or ExampleProject\Debug\x64 or ExampleProject\Release\x86 or ExampleProject\Release\x64 (according to the chosen configuration). You can now run it and should be able to see the following output:

Source IP is '10.0.0.138'; Dest IP is '10.0.0.1'

Android

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: v21.11 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

FreeBSD

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 v21.11 release. After downloading and extracting the archive file go to: /path/to/your/package/ and run the installation script:

sudo ./install.sh

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 go to: /path/to/pcapplusplus/source/Tutorials/Tutorial-HelloWorld.

Make sure you see the following files:

 |-- main.cpp
 |-- 1_packet.pcap

main.cpp is the example application we'll use.

1_packet.pcap is a pcap file the app reads from.

Step 3 - create a Makefile

If you downloaded a pre-compiled package you can find a Makefile in /path/to/your/package/example-app. This Makefile is already configured.

If you built it from source:

• go to /path/to/pcapplusplus/source/Tutorials/Tutorial-HelloWorld
• rename Makefile.non_windows to Makefile

Step 4 - build and run your app

Run gmake to build the app:

$ gmake

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:

Source IP is '10.0.0.138'; Dest IP is '10.0.0.1'