![]() |
PF_RING API
API documentation for PF_RING: high-speed packet capture, filtering and analysis framework.
|
PF_RING FT library header file. More...
#include <sys/types.h>Go to the source code of this file.
Classes | |
| struct | pfring_ft_flow_filter |
| 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_dir_value |
| struct | pfring_ft_flow_value |
| struct | pfring_ft_stats |
| struct | pfring_ft_export_stats |
Macros | |
| #define | FT_API_VERSION 95 |
| #define | PFRING_FT_ACTION_DEFAULT 0 |
| #define | PFRING_FT_ACTION_FORWARD 1 |
| #define | PFRING_FT_ACTION_DISCARD 2 |
| #define | PFRING_FT_ACTION_USER_1 3 |
| #define | PFRING_FT_ACTION_USER_2 4 |
| #define | PFRING_FT_ACTION_SLICE 5 |
| #define | PF_RING_FT_FLOW_FLAGS_L7_GUESS (1 << 0) |
| #define | PFRING_FT_TABLE_FLAGS_DPI (1 << 0) |
| #define | PFRING_FT_TABLE_FLAGS_DPI_EXTRA (1 << 1) |
| #define | PFRING_FT_DECODE_TUNNELS (1 << 2) |
| #define | PFRING_FT_IGNORE_HW_HASH (1 << 3) |
| #define | PFRING_FT_IGNORE_VLAN (1 << 4) |
| #define | PFRING_FT_TABLE_FLAGS_NO_GUESS (1 << 5) |
Typedefs | |
| typedef void | pfring_ft_table |
| typedef void | pfring_ft_list |
| typedef void | pfring_ft_flow |
| typedef u_int8_t | pfring_ft_action |
| 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_direction { s2d_direction = 0 , d2s_direction , PF_RING_FT_FLOW_NUM_DIRECTIONS } |
| enum | pfring_ft_flow_status { PFRING_FT_FLOW_STATUS_ACTIVE = 0 , PFRING_FT_FLOW_STATUS_IDLE_TIMEOUT , PFRING_FT_FLOW_STATUS_ACTIVE_TIMEOUT , PFRING_FT_FLOW_STATUS_END_DETECTED , PFRING_FT_FLOW_STATUS_FORCED_END , PFRING_FT_FLOW_STATUS_SLICE_TIMEOUT , PFRING_FT_FLOW_STATUS_OVERFLOW } |
Functions | |
| pfring_ft_table * | pfring_ft_create_table (u_int32_t flags, u_int32_t max_flows, u_int32_t flow_idle_timeout, u_int32_t flow_lifetime_timeout, u_int32_t user_metadata_size) |
| void | pfring_ft_destroy_table (pfring_ft_table *table) |
| void | pfring_ft_flow_set_flow_slicing (pfring_ft_table *table, u_int32_t flow_slice_timeout) |
| 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_l7_detected_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) |
| u_int64_t | pfring_ft_flow_get_id (pfring_ft_flow *flow) |
| pfring_ft_flow_key * | pfring_ft_flow_get_key (pfring_ft_flow *flow) |
| pfring_ft_flow_value * | pfring_ft_flow_get_value (pfring_ft_flow *flow) |
| struct ndpi_flow_struct * | pfring_ft_flow_get_ndpi_handle (pfring_ft_flow *flow) |
| void | pfring_ft_flow_set_action (pfring_ft_flow *flow, pfring_ft_action action) |
| pfring_ft_action | pfring_ft_flow_get_action (pfring_ft_flow *flow) |
| int | pfring_ft_flow_get_users (pfring_ft_flow *flow) |
| void | pfring_ft_flow_free (pfring_ft_flow *flow) |
| void | pfring_ft_zmq_export_configure (pfring_ft_table *table, const char *endpoint, const char *server_public_key, u_int8_t probe_mode, u_int8_t disable_compression, u_int8_t use_json) |
| void | pfring_ft_zmq_export_flow (pfring_ft_flow *flow, void *user) |
| void | pfring_ft_zmq_export_stats (pfring_ft_table *table, const char *if_name, u_int16_t if_speed, const char *if_ip, const char *management_ip) |
| void | pfring_ft_zmq_get_stats (pfring_ft_table *table, pfring_ft_export_stats *stats) |
| void | pfring_ft_set_default_action (pfring_ft_table *table, pfring_ft_action action) |
| int | pfring_ft_load_configuration (pfring_ft_table *table, const char *path) |
| int | pfring_ft_load_configuration_ext (pfring_ft_table *table, const char *path, pfring_ft_flow_filter *filter) |
| 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_all_protocols (pfring_ft_table *table, pfring_ft_action action) |
| 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) |
| u_int16_t | pfring_ft_l7_protocol_id (pfring_ft_table *table, const char *name) |
| int | pfring_ft_set_ndpi_handle (pfring_ft_table *table, struct ndpi_detection_module_struct *ndpi) |
| struct ndpi_detection_module_struct * | pfring_ft_get_ndpi_handle (pfring_ft_table *table) |
| int | pfring_ft_load_ndpi_protocols (pfring_ft_table *table, const char *path) |
| int | pfring_ft_load_ndpi_categories (pfring_ft_table *table, const char *path) |
| int | pfring_ft_is_ndpi_available () |
| pfring_ft_stats * | pfring_ft_get_stats (pfring_ft_table *table) |
| void | pfring_ft_version (char *version) |
| u_int32_t | pfring_ft_api_version () |
| int | pfring_ft_license (char *system_id, time_t *license_expiration, time_t *maintenance_expiration) |
| int | pfring_ft_set_license (const char *license_key) |
| void | pfring_ft_debug (void) |
PF_RING FT library header file.
| #define PF_RING_FT_FLOW_FLAGS_L7_GUESS (1 << 0) |
pfring_ft_flow_value.flags: detected L7 protocol is a guess.
| #define PFRING_FT_ACTION_DISCARD 2 |
Discard packet due to filter or shunt
| #define PFRING_FT_ACTION_SLICE 5 |
Slice packet headers
| #define PFRING_FT_DECODE_TUNNELS (1 << 2) |
pfring_ft_create_table() flag: decode tunnels (GTP, L2TP, CAPWAP)
| #define PFRING_FT_IGNORE_HW_HASH (1 << 3) |
pfring_ft_create_table() flag: ignore hw packet hash (e.g. when it's asymmetric leading to one flow per direction)
| #define PFRING_FT_IGNORE_VLAN (1 << 4) |
pfring_ft_create_table() flag: do not include vlan in flow key
| #define PFRING_FT_TABLE_FLAGS_DPI (1 << 0) |
pfring_ft_create_table() flag: enable nDPI support for L7 protocol detection
| #define PFRING_FT_TABLE_FLAGS_DPI_EXTRA (1 << 1) |
pfring_ft_create_table() flag: enable nDPI extra dissection (more flow metadata)
| #define PFRING_FT_TABLE_FLAGS_NO_GUESS (1 << 5) |
pfring_ft_create_table() flag: do not guess the protocol when not detected with DPI
| enum pfring_ft_direction |
| u_int32_t pfring_ft_api_version | ( | ) |
Get the PF_RING FT API version.
| pfring_ft_table * pfring_ft_create_table | ( | u_int32_t | flags, |
| u_int32_t | max_flows, | ||
| u_int32_t | flow_idle_timeout, | ||
| u_int32_t | flow_lifetime_timeout, | ||
| u_int32_t | user_metadata_size | ||
| ) |
Create a new flow table.
| flags | Flags to enable selected flow table features. |
| max_flows | Maximum number of concurrent flows the table should be able to handle (use 0 if not sure to use default settings). |
| flow_idle_timeout | Maximum flow idle time (seconds) before expiration (use 0 if not sure to use default: 30s). |
| flow_lifetime_timeout | Maximum flow duration (seconds) before expiration (use 0 if not sure to use default: 2m). |
| user_metadata_size | Size of the user metadata in pfring_ft_flow_value->user |
| void pfring_ft_debug | ( | void | ) |
Enable debug mode
| void pfring_ft_destroy_table | ( | pfring_ft_table * | table | ) |
Destroy a flow table.
| table | The flow table handle. |
| void pfring_ft_flow_free | ( | pfring_ft_flow * | flow | ) |
Release a flow.
| flow | The flow handle. |
| pfring_ft_action pfring_ft_flow_get_action | ( | pfring_ft_flow * | flow | ) |
Get the computed/actual flow action, the same returned by pfring_ft_process() for this flow.
| flow | The flow handle. |
| u_int64_t pfring_ft_flow_get_id | ( | pfring_ft_flow * | flow | ) |
Get the flow ID.
| flow | The flow handle. |
| pfring_ft_flow_key * pfring_ft_flow_get_key | ( | pfring_ft_flow * | flow | ) |
Get the flow key.
| flow | The flow handle. |
| struct ndpi_flow_struct * pfring_ft_flow_get_ndpi_handle | ( | pfring_ft_flow * | flow | ) |
Get the nDPI flow handle.
| flow | The flow handle. |
| int pfring_ft_flow_get_users | ( | pfring_ft_flow * | flow | ) |
Return the number of users for the flow (value of the reference counter). This is usually 1, unless slicing is enabled (+1 for each slice not yet released). Calling this on the slice, returns the reference counter of the master flow.
| flow | The flow handle. |
| pfring_ft_flow_value * pfring_ft_flow_get_value | ( | pfring_ft_flow * | flow | ) |
Get the flow value.
| flow | The flow handle. |
| 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.
| flow | The flow handle. |
| action | The action. |
| void pfring_ft_flow_set_flow_slicing | ( | pfring_ft_table * | table, |
| u_int32_t | flow_slice_timeout | ||
| ) |
Enable flow slicing to peridiocally export flow updates, even when the configured flow_lifetime_timeout is not reached.
| table | The flow table handle. |
| flow_slice_timeout | Maximum flow slice duration (seconds). This should be lower then flow_lifetime_timeout |
| void pfring_ft_flush | ( | pfring_ft_table * | table | ) |
Flush all flows (usually called on program termination, before destroying the flow table).
| table | The flow table handle. |
| struct ndpi_detection_module_struct * pfring_ft_get_ndpi_handle | ( | pfring_ft_table * | table | ) |
Return the nDPI handle.
| table | The flow table handle. |
| pfring_ft_stats * pfring_ft_get_stats | ( | pfring_ft_table * | table | ) |
Get flow processing statistics.
| table | The flow table handle. |
| 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.
| table | The flow table handle. |
| epoch | The current epoch (sec). |
| int pfring_ft_is_ndpi_available | ( | ) |
Check if nDPI is available.
| u_int16_t pfring_ft_l7_protocol_id | ( | pfring_ft_table * | table, |
| const char * | name | ||
| ) |
Return the nDPI L7 protocol ID providing the L7 protocol name.
| table | The flow table handle. |
| name | The 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.
| table | The flow table handle. |
| protocol | The nDPI protocol ID. |
| buffer | The output buffer. |
| buffer_len | The output buffer length. |
| int pfring_ft_license | ( | char * | system_id, |
| time_t * | license_expiration, | ||
| time_t * | maintenance_expiration | ||
| ) |
Get license info.
| system_id | A buffer (48 bytes long) where system id is returned. (out) |
| license_expiration | A pointer to a time_t where license expiration is returned. (out) |
| maintenance_expiration | A pointer to a time_t where maintenance expiration is returned. (out) |
| pfring_ft_flow * pfring_ft_list_get_next | ( | pfring_ft_list * | list | ) |
Pop the next from a flow list.
| list | The flow list. |
| int 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.
| table | The flow table handle. |
| path | The configuration file path. |
| int pfring_ft_load_configuration_ext | ( | pfring_ft_table * | table, |
| const char * | path, | ||
| pfring_ft_flow_filter * | filter | ||
| ) |
Load filtering/shunting rules from a configuration file to an external pfring_ft_flow_filter handle. Please refer to the documentation for the file format.
| table | The flow table handle. |
| path | The configuration file path. |
| filter | The destination pfring_ft_flow_filter handle. |
| 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 nDPI documentation for the file format. Example: https://github.com/ntop/nDPI/blob/dev/example/mining_hosts.txt
| table | The flow table handle. |
| path | The configuration file path. |
| int pfring_ft_load_ndpi_protocols | ( | pfring_ft_table * | table, |
| const char * | path | ||
| ) |
Load custom nDPI protocols from a configuration file. Please refer to the nDPI documentation for the file format. Example: https://github.com/ntop/nDPI/blob/dev/example/protos.txt
| table | The flow table handle. |
| path | The configuration file path. |
| 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.
| table | The flow table handle. |
| packet | The raw packet. |
| header | The packet metadata (including length and timestamp). |
| ext_header | Additional packet metadata not available in the pcap header (including hash). |
| void pfring_ft_set_default_action | ( | pfring_ft_table * | table, |
| pfring_ft_action | action | ||
| ) |
Set the default action for detected L7 protocols with no filtering rule. This can be used to 'drop all' traffic, exception made for specific protocols setting the default to PFRING_FT_ACTION_DISCARD and filter actions to PFRING_FT_ACTION_FORWARD Default: PFRING_FT_ACTION_DEFAULT
| table | The flow table handle. |
| action | The action returned by pfring_ft_process() by default. |
| void pfring_ft_set_filter_all_protocols | ( | pfring_ft_table * | table, |
| pfring_ft_action | action | ||
| ) |
Set a default action for all L7 protocols. This is usually used to reset all filtering rules by passing PFRING_FT_ACTION_DEFAULT as action.
| table | The flow table handle. |
| action | The action to set for all protocols. |
| 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.
| table | The flow table handle. |
| protocol_name | The nDPI protocol name. |
| action | The action returned by pfring_ft_process() for all packets matching the protocol. |
| 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).
| table | The flow table handle. |
| callback | The callback. |
| user | The user data provided to the 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().
| table | The flow table handle. |
| callback | The callback. |
| user | The user data provided to the 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.
| table | The flow table handle. |
| callback | The callback. |
| user | The user data provided to the callback. |
| void pfring_ft_set_l7_detected_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 and the l7 protocol has been just detected.
| table | The flow table handle. |
| callback | The callback (Note: packet/metadata may be NULL). |
| user | The user data provided to the callback. |
| int pfring_ft_set_license | ( | const char * | license_key | ) |
Install a PF_RING FT license key.
| license_key | The license key. |
| 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.
| table | The flow table handle. |
| ndpi | The nDPI handle. |
| 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.
| table | The flow table handle. |
| callback | The callback. |
| user | The user data provided to the callback. |
| 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.
| table | The flow table handle. |
| protocol_name | The nDPI protocol name. |
| packets | The number of packets before shunting the flow returning a discard action from pfring_ft_process(). |
| void pfring_ft_version | ( | char * | version | ) |
Get the PF_RING FT version.
| version | A buffer (32 bytes long) where version is returned. (out) |
| void pfring_ft_zmq_export_configure | ( | pfring_ft_table * | table, |
| const char * | endpoint, | ||
| const char * | server_public_key, | ||
| u_int8_t | probe_mode, | ||
| u_int8_t | disable_compression, | ||
| u_int8_t | use_json | ||
| ) |
Configure ZMQ flow export (see pfring_ft_zmq_export_flow)
| table | The flow table handle. |
| endpoint | The ZMQ endpoint. |
| server_public_key | The ZMQ Public encryption key (NULL for clear). |
| probe_mode | Probe mode (connect to the ZMQ collector). |
| disable_compression | Disable message compression. |
| use_json | Use JSON format (Default: TLV). |
| void pfring_ft_zmq_export_flow | ( | pfring_ft_flow * | flow, |
| void * | user | ||
| ) |
Built-in callback to be provided to pfring_ft_set_flow_export_callback for exporting flows in JSON or TLV format to ZMQ. This implements pfring_ft_export_flow_func. The ZMQ endpoint should be configure with pfring_ft_zmq_export_configure(). The callback also releases the flow calling pfring_ft_flow_free(flow). Usage: pfring_ft_set_flow_export_callback(table, pfring_ft_zmq_export_flow, table);
| flow | The flow to be exported. |
| user | The flow table handle. |
| void pfring_ft_zmq_export_stats | ( | pfring_ft_table * | table, |
| const char * | if_name, | ||
| u_int16_t | if_speed, | ||
| const char * | if_ip, | ||
| const char * | management_ip | ||
| ) |
Export stats via ZMQ
| table | The flow table handle. |
| if_name | Interface name. |
| if_speed | Interface speed (Mbps). |
| if_ip | Interface IP. |
| management_ip | Management Interface IP. |
| void pfring_ft_zmq_get_stats | ( | pfring_ft_table * | table, |
| pfring_ft_export_stats * | stats | ||
| ) |
Get ZMQ export stats
| table | The flow table handle. |
| stats | The ZMQ stats (out). |