Basic UsageΒΆ

After installing Peafowl, it can be used by your application by specifying the appropriate compilation flags for C and C++ or by loading the pypeafowl module for Python:

C

C++

Python

Include the peafowl/peafowl.h header and add -lpeafowl flag to the linker options.

Include the peafowl/peafowl.hpp header and add -lpeafowl flag to the linker options.

import pypeafowl as pfwl

The first thing to do in your program, is creating an handle to the Peafowl library:

C

C++

Python

pfwl_state_t* handle = pfwl_init();

peafowl::Peafowl* handle = new peafowl::Peafowl();

handle = pfwl.Peafowl()

This call initializes the framework and returns an handle, which will be used for most of the framework calls. After creating the handle, you can start analyzing the network packets. As anticipated, Peafowl does not rely on any specific packet capture library, and only requires you to provide a pointer to the packet, which you can read with whatever mechanism you prefer (e.g. libpcap, etc..). To dissect the packet:

C

C++

Python

pfwl_flow_info_t* info;
pfwl_status_t status = pfwl_dissect_from_L3(handle, pkt, length, ts, info);
The parameters are:

  • The handle to the framework

  • The packet, as a pointer to the beginning of Layer 3 (IP) header

  • The packet length

  • A timestamp. By default it must specified with seconds resolution. However, this may be changed with appropriate calls (see `API Reference`_ for details).

  • The last parameter will be filled by Peafowl with the information about protocols detected at different layers and about the data and metadata carried by the different layers.

The call returns a status which provides additional information on the processing (or an error).

For example, to print the application protocol:

if(status >= PFWL_STATUS_OK){
  printf("%s\n", pfwl_get_L7_protocol_name(info.l7.protocol));
}

peafowl::DissectionInfo info = handle->dissectFromL3(pkt, ts);
The parameters are:

  • The packet, as a pointer to the beginning of Layer 3 (IP) header

  • A timestamp. By default it must specified with seconds resolution. However, this may be changed with appropriate calls (see `API Reference`_ for details).

This call returns a struct containing the status of the processing and information about protocols detected at different layers and about the data and metadata carried by the different layers.

For example, to print the application protocol:

if(!info.getStatus().isError()){
  std::cout << info.getL7().getProtocol().getName() << std::endl;
}

info = handle.dissectFromL3(pkt, ts)
The parameters are:

  • The packet, as a pointer to the beginning of Layer 3 (IP) header

  • A timestamp. By default it must specified with seconds resolution. However, this may be changed with appropriate calls (see `API Reference`_ for details).

This call returns a struct containing the status of the processing and information about protocols detected at different layers and about the data and metadata carried by the different layers.

For example, to print the application protocol:

if not info.getStatus().isError():
  print(info.getL7().getProtocol().getName())

Similar calls are available for analyzing the packet starting from the beginning of Layer 2 or Layer 4 header. For more information please refer to the `API Reference`_.

Eventually, when Peafowl is no more needed, you should deallocate the resources used by Peafowl:

C

C++

Python

pfwl_terminate(handle);

delete handle;

del handle

For a more detailed description of the aforementioned calls and for other API calls, please refer to the `API Reference`_ documentation.

Some full working examples can be found in the demo folder: