PF_RING API
API documentation for PF_RING: high-speed packet capture, filtering and analysis framework.
pfring_ft.h File Reference

PF_RING FT library header file. More...

#include <sys/types.h>

Go to the source code of this file.

Classes

struct  __attribute__
 
struct  __attribute__
 
struct  __attribute__
 
struct  __attribute__
 
struct  __attribute__
 
struct  pfring_ft_pcap_pkthdr
 
struct  pfring_ft_ext_pkthdr
 
struct  pfring_ft_packet_metadata
 
union  pfring_ft_ip_address
 
struct  pfring_ft_ndpi_protocol
 
struct  pfring_ft_flow_key
 
struct  pfring_ft_flow_value
 
struct  pfring_ft_stats
 

Macros

#define PFRING_FT_TABLE_FLAGS_DPI   (1 << 0)
 

Typedefs

typedef void pfring_ft_table
 
typedef void pfring_ft_list
 
typedef void pfring_ft_flow
 
typedef u_int32_t pfring_ft_in4_addr
 
typedef void(* pfring_ft_export_list_func) (pfring_ft_list *flows_list, void *user)
 
typedef void(* pfring_ft_export_flow_func) (pfring_ft_flow *flow, void *user)
 
typedef void(* pfring_ft_flow_packet_func) (const u_char *data, pfring_ft_packet_metadata *metadata, pfring_ft_flow *flow, void *user)
 

Enumerations

enum  pfring_ft_action { PFRING_FT_ACTION_DEFAULT = 0, PFRING_FT_ACTION_FORWARD, PFRING_FT_ACTION_DISCARD }
 
enum  pfring_ft_direction { s2d_direction = 0, d2s_direction, NUM_DIRECTIONS }
 

Functions

pfring_ft_table * pfring_ft_create_table (u_int32_t flags, u_int32_t max_flows, u_int32_t flow_timeout)
 
void pfring_ft_destroy_table (pfring_ft_table *table)
 
void pfring_ft_set_new_flow_callback (pfring_ft_table *table, pfring_ft_export_flow_func callback, void *user)
 
void pfring_ft_set_flow_packet_callback (pfring_ft_table *table, pfring_ft_flow_packet_func callback, void *user)
 
void pfring_ft_set_flow_export_callback (pfring_ft_table *table, pfring_ft_export_flow_func callback, void *user)
 
void pfring_ft_set_flow_list_export_callback (pfring_ft_table *table, pfring_ft_export_list_func callback, void *user)
 
pfring_ft_action pfring_ft_process (pfring_ft_table *table, const u_char *packet, const pfring_ft_pcap_pkthdr *header, const pfring_ft_ext_pkthdr *ext_header)
 
int pfring_ft_housekeeping (pfring_ft_table *table, u_int32_t epoch)
 
void pfring_ft_flush (pfring_ft_table *table)
 
pfring_ft_flow * pfring_ft_list_get_next (pfring_ft_list *list)
 
pfring_ft_flow_keypfring_ft_flow_get_key (pfring_ft_flow *flow)
 
pfring_ft_flow_valuepfring_ft_flow_get_value (pfring_ft_flow *flow)
 
void pfring_ft_flow_set_action (pfring_ft_flow *flow, pfring_ft_action action)
 
void pfring_ft_flow_free (pfring_ft_flow *flow)
 
void pfring_ft_load_configuration (pfring_ft_table *table, const char *path)
 
void pfring_ft_set_shunt_protocol_by_name (pfring_ft_table *table, const char *protocol_name, u_int8_t packets)
 
void pfring_ft_set_filter_protocol_by_name (pfring_ft_table *table, const char *protocol_name, pfring_ft_action action)
 
char * pfring_ft_l7_protocol_name (pfring_ft_table *table, pfring_ft_ndpi_protocol *protocol, char *buffer, int buffer_len)
 
int pfring_ft_set_ndpi_handle (pfring_ft_table *table, struct ndpi_detection_module_struct *ndpi)
 
int pfring_ft_load_ndpi_categories (pfring_ft_table *table, const char *path)
 
pfring_ft_statspfring_ft_get_stats (pfring_ft_table *table)
 
void pfring_ft_version (char *version)
 
int pfring_ft_license (char *system_id, time_t *license_expiration, time_t *maintenance_expiration)
 
void pfring_ft_debug (void)
 

Detailed Description

PF_RING FT library header file.

Macro Definition Documentation

◆ PFRING_FT_TABLE_FLAGS_DPI

#define PFRING_FT_TABLE_FLAGS_DPI   (1 << 0)

pfring_ft_create_table() flag: enable nDPI support for L7 protocol detection

Enumeration Type Documentation

◆ pfring_ft_direction

Enumerator
s2d_direction 

Source to destination

d2s_direction 

Destination to source

Function Documentation

◆ pfring_ft_create_table()

pfring_ft_table* pfring_ft_create_table ( u_int32_t  flags,
u_int32_t  max_flows,
u_int32_t  flow_timeout 
)

Create a new flow table.

Parameters
flagsFlags to enable selected flow table features.
max_flowsMaximum number of concurrent flows the table should be able to handle (use 0 if not sure to use default settings).
flow_timeoutMaximum flow idle time (seconds) before expiration (use 0 if not sure to use default settings).
Returns
The flow table on success, NULL on failure.

◆ pfring_ft_debug()

void pfring_ft_debug ( void  )

Enable debug mode

◆ pfring_ft_destroy_table()

void pfring_ft_destroy_table ( pfring_ft_table *  table)

Destroy a flow table.

Parameters
tableThe flow table handle.

◆ pfring_ft_flow_free()

void pfring_ft_flow_free ( pfring_ft_flow *  flow)

Release a flow.

Parameters
flowThe flow handle.

◆ pfring_ft_flow_get_key()

pfring_ft_flow_key* pfring_ft_flow_get_key ( pfring_ft_flow *  flow)

Get the flow key.

Parameters
flowThe flow handle.
Returns
The flow key.

◆ pfring_ft_flow_get_value()

pfring_ft_flow_value* pfring_ft_flow_get_value ( pfring_ft_flow *  flow)

Get the flow value.

Parameters
flowThe flow handle.
Returns
The flow value.

◆ pfring_ft_flow_set_action()

void pfring_ft_flow_set_action ( pfring_ft_flow *  flow,
pfring_ft_action  action 
)

Set the flow action, to be returned by pfring_ft_process() for all packets for this flow.

Parameters
flowThe flow handle.
actionThe action.

◆ pfring_ft_flush()

void pfring_ft_flush ( pfring_ft_table *  table)

Flush all flows (usually called on program termination, before destroying the flow table).

Parameters
tableThe flow table handle.

◆ pfring_ft_get_stats()

pfring_ft_stats* pfring_ft_get_stats ( pfring_ft_table *  table)

Get flow processing statistics.

Parameters
tableThe flow table handle.
Returns
The stats struct.

◆ pfring_ft_housekeeping()

int pfring_ft_housekeeping ( pfring_ft_table *  table,
u_int32_t  epoch 
)

This should be called when there is no packet to be processed and the main loop is idle, for running housekeeping activities in the flow table.

Parameters
tableThe flow table handle.
epochThe current epoch (sec).
Returns
1 if there is more work to do, 0 if the caller can sleep a bit.

◆ pfring_ft_l7_protocol_name()

char* pfring_ft_l7_protocol_name ( pfring_ft_table *  table,
pfring_ft_ndpi_protocol protocol,
char *  buffer,
int  buffer_len 
)

Return the L7 protocol name providing the nDPI protocol ID.

Parameters
tableThe flow table handle.
protocolThe nDPI protocol ID.
bufferThe output buffer.
buffer_lenThe output buffer length.
Returns
The buffer.

◆ pfring_ft_license()

int pfring_ft_license ( char *  system_id,
time_t *  license_expiration,
time_t *  maintenance_expiration 
)

Get license info.

Parameters
system_idA buffer (32 bytes long) where system id is returned. (out)
license_expirationA pointer to a time_t where license expiration is returned. (out)
maintenance_expirationA pointer to a time_t where maintenance expiration is returned. (out)
Returns
1 if a valid license is installed, 0 otherwise.

◆ pfring_ft_list_get_next()

pfring_ft_flow* pfring_ft_list_get_next ( pfring_ft_list *  list)

Pop the next from a flow list.

Parameters
listThe flow list.
Returns
The flow if the list is not empty, NULL otherwise.

◆ pfring_ft_load_configuration()

void pfring_ft_load_configuration ( pfring_ft_table *  table,
const char *  path 
)

Load filtering/shunting rules from a configuration file. Please refer to the documentation for the file format.

Parameters
tableThe flow table handle.
pathThe configuration file path.

◆ pfring_ft_load_ndpi_categories()

int pfring_ft_load_ndpi_categories ( pfring_ft_table *  table,
const char *  path 
)

Load nDPI categories (defined by hostname) from a configuration file. Please refer to the documentation for the file format.

Parameters
tableThe flow table handle.
pathThe configuration file path.

◆ pfring_ft_process()

pfring_ft_action pfring_ft_process ( pfring_ft_table *  table,
const u_char *  packet,
const pfring_ft_pcap_pkthdr header,
const pfring_ft_ext_pkthdr ext_header 
)

Provide a raw packet to the flow table for processing. Usually the main capture loop provides all the packets to the hash table calling this function.

Parameters
tableThe flow table handle.
packetThe raw packet.
headerThe packet metadata (including length and timestamp).
ext_headerAdditional packet metadata not available in the pcap header (including hash).
Returns
The action for the packet, in case filtering rules have been specified.

◆ pfring_ft_set_filter_protocol_by_name()

void pfring_ft_set_filter_protocol_by_name ( pfring_ft_table *  table,
const char *  protocol_name,
pfring_ft_action  action 
)

Set a filtering rule for a L7 protocol.

Parameters
tableThe flow table handle.
protocol_nameThe nDPI protocol name.
actionThe action returned by pfring_ft_process() for all packets matching the protocol.

◆ pfring_ft_set_flow_export_callback()

void pfring_ft_set_flow_export_callback ( pfring_ft_table *  table,
pfring_ft_export_flow_func  callback,
void *  user 
)

Set the function to be called when a flow expires and needs to be exported. The callback should release the flow calling pfring_ft_flow_free(flow).

Parameters
tableThe flow table handle.
callbackThe callback.
userThe user data provided to the callback.

◆ pfring_ft_set_flow_list_export_callback()

void pfring_ft_set_flow_list_export_callback ( pfring_ft_table *  table,
pfring_ft_export_list_func  callback,
void *  user 
)

Set the function to be called when a some flow expires and need to be exported. This can be used as an optimised alternative to pfring_ft_set_flow_export_callback(). The callback should release all flows in the list calling pfring_ft_flow_free(flow) for each flow. It is possible to iterate all the flows in the list using pfring_ft_list_get_next().

Parameters
tableThe flow table handle.
callbackThe callback.
userThe user data provided to the callback.

◆ pfring_ft_set_flow_packet_callback()

void pfring_ft_set_flow_packet_callback ( pfring_ft_table *  table,
pfring_ft_flow_packet_func  callback,
void *  user 
)

Set the function to be called when a packet and its flow have been processed, for each packet.

Parameters
tableThe flow table handle.
callbackThe callback.
userThe user data provided to the callback.

◆ pfring_ft_set_ndpi_handle()

int pfring_ft_set_ndpi_handle ( pfring_ft_table *  table,
struct ndpi_detection_module_struct *  ndpi 
)

Set the nDPI handle. This is meant to be used for custom nDPI settings only, as FT already creates a nDPI instance internally when using PFRING_FT_TABLE_FLAGS_DPI. FT takes care of releasing the nDPI instance on pfring_ft_destroy_table.

Parameters
tableThe flow table handle.
Returns
0 on success, a negative number on failures.

◆ pfring_ft_set_new_flow_callback()

void pfring_ft_set_new_flow_callback ( pfring_ft_table *  table,
pfring_ft_export_flow_func  callback,
void *  user 
)

Set the function to be called when a new flow has been created.

Parameters
tableThe flow table handle.
callbackThe callback.
userThe user data provided to the callback.

◆ pfring_ft_set_shunt_protocol_by_name()

void pfring_ft_set_shunt_protocol_by_name ( pfring_ft_table *  table,
const char *  protocol_name,
u_int8_t  packets 
)

Set a shunt rule for a L7 protocol.

Parameters
tableThe flow table handle.
protocol_nameThe nDPI protocol name.
packetsThe number of packets before shunting the flow returning a discard action from pfring_ft_process().

◆ pfring_ft_version()

void pfring_ft_version ( char *  version)

Get the PF_RING FT version.

Parameters
versionA buffer (32 bytes long) where version is returned. (out)