2. PF_RING API

PF_RING library header file.

This header file must be included in any PF_RING-based applications.

Defines

MAX_CAPLEN
PAGE_SIZE
DEFAULT_POLL_DURATION
POLL_SLEEP_STEP
POLL_SLEEP_MIN
POLL_SLEEP_MAX
POLL_QUEUE_MIN_LEN
pfring_rwlock_t
pfring_rwlock_init
pfring_rwlock_rdlock
pfring_rwlock_wrlock
pfring_rwlock_unlock
pfring_rwlock_destroy
timespec_is_before(a, b)
likely(x)
unlikely(x)
prefetch(x)
PF_RING_ZC_SYMMETRIC_RSS

pfring_open() flag: Set the hw RSS function to symmetric mode (both directions of the same flow go to the same hw queue). Supported by ZC drivers only. This option is also available with the PF_RING-aware libpcap via the PCAP_PF_RING_ZC_RSS environment variable.

PF_RING_REENTRANT

pfring_open() flag: The device is open in reentrant mode. This is implemented by means of semaphores and it results is slightly worse performance. Use reentrant mode only for multithreaded applications.

PF_RING_LONG_HEADER

pfring_open() flag: If uset, PF_RING does not fill the field extended_hdr of struct pfring_pkthdr. If set, the extended_hdr field is also properly filled. In case you do not need extended information, set this value to 0 in order to speedup the operation.

PF_RING_PROMISC

pfring_open() flag: The device is open in promiscuous mode.

PF_RING_TIMESTAMP

pfring_open() flag: Force PF_RING to set the timestamp on received packets (usually it is not set when using zero-copy, for optimizing performance).

PF_RING_HW_TIMESTAMP

pfring_open() flag: Enable hw timestamping, when available.

PF_RING_RX_PACKET_BOUNCE

pfring_open() flag: Enable fast forwarding support (see pfring_send_last_rx_packet()).

PF_RING_ZC_FIXED_RSS_Q_0

pfring_open() flag: Set hw RSS to send all traffic to queue 0. Other queues can be selected using hw filters (ZC cards with hw filtering only).

PF_RING_STRIP_HW_TIMESTAMP

pfring_open() flag: Strip hw timestamp from the packet.

PF_RING_DO_NOT_PARSE

pfring_open() flag: Disable packet parsing also when 1-copy is used. (parsing already disabled in zero-copy)

PF_RING_DO_NOT_TIMESTAMP

pfring_open() flag: Disable packet timestamping also when 1-copy is used. (sw timestamp already disabled in zero-copy)

PF_RING_CHUNK_MODE

pfring_open() flag: Enable chunk mode operations. This mode is supported only by specific adapters and it’s not for general purpose.

PF_RING_IXIA_TIMESTAMP

pfring_open() flag: Enable ixiacom.com hardware timestamp support+stripping.

PF_RING_USERSPACE_BPF

pfring_open() flag: Force userspace bpf even with standard drivers (not only with ZC).

PF_RING_ZC_NOT_REPROGRAM_RSS

pfring_open() flag: Do not touch/reprogram hw RSS

PF_RING_VSS_APCON_TIMESTAMP

pfring_open() flag: Enable apcon.com/vssmonitoring.com hardware timestamp support+stripping.

PF_RING_ZC_IPONLY_RSS

pfring_open() flag: Compute RSS on src/dst IP only (not 4-tuple)

PF_RING_FLOW_OFFLOAD

pfring_open() flag: Enable hw flow table support when available

PF_RING_FLOW_OFFLOAD_NOUPDATES

pfring_open() flag: Do not send flow updates with PF_RING_FLOW_OFFLOAD (enable support for flows shunting only)

PF_RING_FLOW_OFFLOAD_NORAWDATA

pfring_open() flag: Do not send raw packets with PF_RING_FLOW_OFFLOAD

PF_RING_L7_FILTERING

pfring_open() flag: Enable L7 filtering support based on PF_RING FT (Flow Table with nDPI support)

PF_RING_DO_NOT_STRIP_FCS

pfring_open() flag: Do not strip the FCS (CRC), when not stripped out by the adapter (on standard adapters use this in combination with ‘ethtool -K <dev> rx-fcs on rx-all on’)

PF_RING_DNA_SYMMETRIC_RSS
PF_RING_DNA_FIXED_RSS_Q_0

Typedefs

typedef void (*pfringProcesssPacket)(const struct pfring_pkthdr *h, const u_char *p, const u_char *user_bytes)
typedef struct __pfring pfring
typedef struct pfring_if pfring_if_t

Enums

enum filtering_mode

Values:

hardware_and_software = 0
hardware_only
software_only
enum packet_slicing_level

Values:

FULL_PACKET_SLICING = 0
L2_SLICING = 2
L3_SLICING = 3
L4_SLICING = 4
enum pfring_chunk_type

Values:

PCAP_CHUNK
PCAP_NSEC_CHUNK
PCAPNG_NSEC_CHUNK
UNKNOWN_CHUNK_TYPE

Functions

pfring *pfring_open(const char *device_name, u_int32_t caplen, u_int32_t flags)

This call is used to initialize a PF_RING socket hence obtain a handle of type struct pfring that can be used in subsequent calls. Note that:

  1. you can use physical (e.g. ethX) and virtual (e.g. tapX) devices, RX-queues (e.g. ethX), and additional modules (e.g. zc:ethX, dag:dagX:Y, “multi:ethA@X;ethB@Y;ethC@Z”, “stack:ethX”).
  2. you need super-user capabilities in order to open a device.
    Return
    On success a handle is returned, NULL otherwise.
    Parameters
    • device_name: Symbolic name of the PF_RING-aware device we are attempting to open. Syntax:
      • eth0 interface eth0, all channels
      • eth0@1 interface eth0, channel 1
      • eth0,eth1 interface eth0 and eth1, all channels
      • eth0,eth1@1 interface eth0 and eth1, channel 1
      • eth0@1,5 interface eth0, channel 1 and 5
      • eth0@1-5 interface eth0, channel 1,2…5
      • eth0@1-3,5-7 interface eth0, channel 1,2,3,5,6,7 Note:
      • ’,’ and ‘-‘ are supported with standard kernel capture / drivers only
      • in case of multiple interfaces, the channels are same for all interfaces
    • caplen: Maximum packet capture len (also known as snaplen).
    • flags: It allows several options to be specified on a compact format using bitmaps (see PF_RING_* macros).

u_int8_t pfring_open_multichannel(const char *device_name, u_int32_t caplen, u_int32_t flags, pfring *ring[MAX_NUM_RX_CHANNELS])

This call is similar to pfring_open() with the exception that in case of a multi RX-queue NIC, instead of opening a single ring for the whole device, several individual rings are open (one per RX-queue).

Return
The last index of the ring array that contain a valid ring pointer.
Parameters
  • device_name: Symbolic name of the PF_RING-aware device we are attempting to open (e.g. eth0). No queue name hash to be specified, but just the main device name.
  • caplen: Maximum packet capture len (also known as snaplen).
  • flags: See pfring_open() for details.
  • ring: A pointer to an array of rings that will contain the opened ring pointers.

void pfring_shutdown(pfring *ring)

Shutdown a socket.

Parameters
  • ring: The PF_RING handle.

void pfring_config(u_short cpu_percentage)

Set the scheduler priority for the current thread.

Parameters
  • cpu_percentage: The priority.

int pfring_loop(pfring *ring, pfringProcesssPacket looper, const u_char *user_bytes, u_int8_t wait_for_packet)

Process ingress packets until pfring_breakloop() is called, or an error occurs.

Return
0 on success (pfring_breakloop()), a negative value otherwise.
Parameters
  • ring: The PF_RING handle.
  • looper: The user callback for packet processing.
  • user_bytes: The user ptr passed to the callback.
  • wait_for_packet: If 0 active wait is used to check the packet availability.

void pfring_breakloop(pfring *)

Break a receive loop (pfring_loop() or blocking pfring_recv()).

Parameters
  • ring: The PF_RING handle.

void pfring_close(pfring *ring)

This call is used to terminate an PF_RING device previously open. Note that you must always close a device before leaving an application. If unsure, you can close a device from a signal handler.

Parameters
  • ring: The PF_RING handle that we are attempting to close.

int pfring_stats(pfring *ring, pfring_stat *stats)

Read ring statistics (packets received and dropped).

Return
0 on uccess, a negative value otherwise.
Parameters
  • ring: The PF_RING handle.
  • stats: A user-allocated buffer on which stats (number of received and dropped packets) will be stored.

int pfring_recv(pfring *ring, u_char **buffer, u_int buffer_len, struct pfring_pkthdr *hdr, u_int8_t wait_for_incoming_packet)

This call returns an incoming packet when available.

Return
0 in case of no packet being received (non-blocking), 1 in case of success, -1 in case of error.
Parameters
  • ring: The PF_RING handle where we perform the check.
  • buffer: A memory area allocated by the caller where the incoming packet will be stored. Note that this parameter is a pointer to a pointer, in order to enable zero-copy implementations (buffer_len must be set to 0).
  • buffer_len: The length of the memory area above. Note that the incoming packet is cut if it is too long for the allocated area. A length of 0 indicates to use the zero-copy optimization, when available.
  • hdr: A memory area where the packet header will be copied.
  • wait_for_incoming_packet: If 0 we simply check the packet availability, otherwise the call is blocked until a packet is available. This option is also available with the PF_RING-aware libpcap via the PCAP_PF_RING_ACTIVE_POLL environment variable.

int pfring_recv_parsed(pfring *ring, u_char **buffer, u_int buffer_len, struct pfring_pkthdr *hdr, u_int8_t wait_for_incoming_packet, u_int8_t level, u_int8_t add_timestamp, u_int8_t add_hash)

Same of pfring_recv(), with additional parameters to force packet parsing.

Return
0 in case of no packet being received (non-blocking), 1 in case of success, -1 in case of error.
Parameters
  • ring:
  • buffer:
  • buffer_len:
  • hdr:
  • wait_for_incoming_packet:
  • level: The header level where to stop parsing.
  • add_timestamp: Add the timestamp.
  • add_hash: Compute an IP-based bidirectional hash.

int pfring_get_metadata(pfring *ring, u_char **metadata, u_int32_t *metadata_len)

Get metadata for the last captured packet, if any. This is usually used with ZC SPSC queues for reading packet metadata.

Return
0 if this is supported by the actual module and metadata is found, a negative error value otherwise.
Parameters
  • ring:
  • metadata: Ptr to a variable that will contain the packet metadata (out).

int pfring_set_poll_watermark(pfring *ring, u_int16_t watermark)

Whenever a user-space application has to wait until incoming packets arrive, it can instruct PF_RING not to return from poll() call unless at least “watermark” packets have been returned. A low watermark value such as 1, reduces the latency of poll() but likely increases the number of poll() calls. A high watermark (it cannot exceed 50% of the ring size, otherwise the PF_RING kernel module will top its value) instead reduces the number of poll() calls but slightly increases the packet latency. The default value for the watermark (i.e. if user-space applications do not manipulate this value via this call) is 128.

Return
0 on success, a negative value otherwise.
Parameters
  • ring: The PF_RING handle to enable.
  • watermark: The packet poll watermark.

int pfring_set_poll_watermark_timeout(pfring *ring, u_int16_t poll_watermark_timeout)

Flush ring’s queue if timeout passed. This helps to avoid situation where packets are waiting in the rings’s queue too long (e.g. low-traffic network). The default value for the timeout is 0, which disables the flushing.

Return
0 on success, a negative value otherwise.
Parameters
  • ring: The PF_RING handle.
  • poll_watermark_timeout: Milliseconds to flush ring’s queue even if watermark packets hasn’t reached yet.

int pfring_set_poll_duration(pfring *ring, u_int duration)

Set the poll timeout when passive wait is used.

Return
0 on success, a negative value otherwise.
Parameters
  • ring: The PF_RING handle to enable.
  • duration: The poll timeout in msec.

int pfring_set_tx_watermark(pfring *ring, u_int16_t watermark)

Set the number of packets that have to be enqueued in the egress queue before being sent on the wire.

Return
0 on success, a negative value otherwise.
Parameters
  • ring: The PF_RING handle to enable.
  • watermark: The tx watermark.

int pfring_add_hw_rule(pfring *ring, hw_filtering_rule *rule)

Set a specified filtering rule into the NIC. Note that no PF_RING filter is added, but only a NIC filter.

Some multi-queue modern network adapters feature “packet steering” capabilities. Using them it is possible to instruct the hardware NIC to assign selected packets to a specific RX queue. If the specified queue has an Id that exceeds the maximum queueId, such packet is discarded thus acting as a hardware firewall filter. Note: kernel packet filtering is not supported by ZC.

Return
0 on success, a negative value otherwise (e.g. the rule to be added has wrong format or if the NIC to which this ring is bound does not support hardware filters).
Parameters
  • ring: The PF_RING handle on which the rule will be added.
  • rule: The filtering rule to be set in the NIC as defined in the last chapter of this document. All rule parameters should be defined, and if set to zero they do not participate to filtering.

int pfring_remove_hw_rule(pfring *ring, u_int16_t rule_id)

Remove the specified filtering rule from the NIC.

Return
0 on success, a negative value otherwise.
Parameters
  • ring: The PF_RING handle on which the rule will be removed.
  • rule: The filtering rule to be removed from the NIC.

int pfring_set_channel_id(pfring *ring, u_int32_t channel_id)

Set the device channel id to be used.

Return
0 on success, a negative value otherwise.
Parameters
  • ring: The PF_RING handle.
  • channel_id: The channel id.

int pfring_set_channel_mask(pfring *ring, u_int64_t channel_mask)

Set the channel mask to be used for packet capture.

Return
0 on success, a negative value otherwise.
Parameters
  • ring: The PF_RING handle.
  • channel_mask: The channel mask.

int pfring_set_application_name(pfring *ring, char *name)

Tell PF_RING the name of the application (usually argv[0]) that uses this ring. This information is used to identify the application when accessing the files present in the PF_RING /proc filesystem. This is also available with the PF_RING-aware libpcap via the PCAP_PF_RING_APPNAME environment variable. Example: $ cat /proc/net/pf_ring/16614-eth0.0 | grep Name Appl. Name : pfcount

Return
0 on success, a negative value otherwise.
Parameters
  • ring: The PF_RING handle to enable.
  • name: The name of the application using this ring.

int pfring_set_application_stats(pfring *ring, char *stats)

Set custom application statistics.

Return
0 on success, a negative value otherwise.
Parameters
  • ring: The PF_RING handle.
  • stats: The application stats.

char *pfring_get_appl_stats_file_name(pfring *ring, char *path, u_int path_len)

Return the filename where the application statistics can be read.

Return
The path if success, NULL otherwise.
Parameters
  • ring: The PF_RING handle.
  • path: A user-allocated buffer on which the stats filename will be stored.
  • path_len: The path len.

int pfring_set_vlan_id(pfring *ring, u_int16_t vlan_id)

Set the VLAN Id of the packets that will be copied to this ring (RX only)

Return
0 on success, a negative value otherwise.
Parameters
  • ring: The PF_RING handle.
  • vlan_id: The vlan id to filter or 0 to accept only untagged VLAN packets

int pfring_bind(pfring *ring, char *device_name)

Bind a socket to a device.

Return
0 on success, a negative value otherwise.
Parameters
  • ring: The PF_RING handle.
  • device_name: The device name.

int pfring_send(pfring *ring, char *pkt, u_int pkt_len, u_int8_t flush_packet)

Send a raw packet (i.e. it is sent on wire as specified). This packet must be fully specified (the MAC address up) and it will be transmitted as-is without any further manipulation.

Depending on the driver being used, packet transmission happens differently:

  • Vanilla and PF_RING aware drivers: PF_RING does not accelerate the TX so the standard Linux transmission facilities are used. Do not expect speed advantage when using PF_RING in this mode.
  • ZC: line rate transmission is supported.
    Return
    The number of bytes sent if success, a negative value otherwise.
    Parameters
    • ring: The PF_RING handle on which the packet has to be sent.
    • pkt: The buffer containing the packet to send.
    • pkt_len: The length of the pkt buffer.
    • flush_packet: 1 = Flush possible transmission queues. If set to 0, you will decrease your CPU usage but at the cost of sending packets in trains and thus at larger latency.

int pfring_send_get_time(pfring *ring, char *pkt, u_int pkt_len, struct timespec *ts)

Same as pfring_send(), but this function allows to send a raw packet returning the exact time (ns) it has been sent on the wire. Note that this is available when the adapter supports tx hardware timestamping only and might affect performance.

Return
The number of bytes sent if success, a negative value otherwise.
Parameters
  • ring:
  • pkt:
  • pkt_len:
  • ts: The struct where the tx timestamp will be stored.

u_int8_t pfring_get_num_rx_channels(pfring *ring)

Returns the number of RX channels (also known as RX queues) of the ethernet interface to which this ring is bound.

Return
The number of RX channels, or 1 (default) in case this in information is unknown.
Parameters
  • ring: The PF_RING handle to query.

int pfring_set_sampling_rate(pfring *ring, u_int32_t rate)

Implement packet sampling directly into the kernel. Note that this solution is much more efficient than implementing it in user-space. Sampled packets are only those that pass all filters (if any).

Return
0 on success, a negative value otherwise.
Parameters
  • ring: The PF_RING handle on which sampling is applied.
  • rate: The sampling rate. Rate of X means that 1 packet out of X is forwarded. This means that a sampling rate of 1 disables sampling.

int pfring_set_filtering_sampling_rate(pfring *ring, u_int32_t rate)

Implement packet sampling during filtering directly into the kernel. Note that this solution is much more efficient than implementing it in user-space. Sampled packets during filtering are only those that already have been filtered out (if any).

Return
0 on success, a negative value otherwise.
Parameters
  • ring: The PF_RING handle on which filtering sampling is applied.
  • rate: The filtering sampling rate. Rate of X means 1 packet every X packets is forwarded. Rate of 0 disables sampling.

int pfring_set_packet_slicing(pfring *ring, packet_slicing_level level, u_int32_t additional_bytes)

Set packet slicing level.

Return
0 on success, a negative value otherwise.
Parameters
  • ring: The PF_RING handle on which slicing is applied, when supported.
  • level: The slicing level (disabled, L2, L3, L4, ..)
  • additional_bytes: Bytes to capture in addition to the selected layer.

int pfring_get_selectable_fd(pfring *ring)

Returns the file descriptor associated to the specified ring. This number can be used in function calls such as poll() and select() for passively waiting for incoming packets.

Return
A number that can be used as reference to this ring, in function calls that require a selectable file descriptor.
Parameters
  • ring: The PF_RING handle to query.

int pfring_set_direction(pfring *ring, packet_direction direction)

Tell PF_RING to consider only those packets matching the specified direction. If the application does not call this function, all the packets (regardless of the direction, either RX or TX) are returned.

Return
0 on success, a negative value otherwise.
Parameters
  • ring: The PF_RING handle to enable.
  • direction: The packet direction (RX, TX or both RX and TX).

int pfring_set_socket_mode(pfring *ring, socket_mode mode)

Tell PF_RING if the application needs to send and/or receive packets to/from the socket.

Return
0 on success, a negative value otherwise.
Parameters
  • ring: The PF_RING handle to enable.
  • mode: The socket mode (send, receive or both send and receive).

int pfring_set_cluster(pfring *ring, u_int clusterId, cluster_type the_type)

This call allows a ring to be added to a cluster that can spawn across address spaces. On a nuthsell when two or more sockets are clustered they share incoming packets that are balanced on a per-flow manner. This technique is useful for exploiting multicore systems of for sharing packets in the same address space across multiple threads. Clustering is also available with the PF_RING-aware libpcap via the PCAP_PF_RING_CLUSTER_ID environment variable (Round-Robin by default, per-flow via the PCAP_PF_RING_USE_CLUSTER_PER_FLOW environment variable).

Return
0 on success, a negative value otherwise.
Parameters
  • ring: The PF_RING handle to be cluster.
  • clusterId: A numeric identifier of the cluster to which the ring will be bound.
  • the_type: The cluster type (2-tuple, 4-tuple, 5-tuple, tcp only 5-tuple, 6-tuple flow or Round-Robin).

int pfring_remove_from_cluster(pfring *ring)

This call allows a ring to be removed from a previous joined cluster.

Return
0 on success, a negative value otherwise.
Parameters
  • ring: The PF_RING handle to be cluster.
  • clusterId: A numeric identifier of the cluster to which the ring will be bound.

int pfring_set_master_id(pfring *ring, u_int32_t master_id)

Set the master ring using the id (vanilla PF_RING only)

Return
0 on success, a negative value otherwise.
Parameters
  • ring: The PF_RING handle.
  • master: The master socket id.

int pfring_set_master(pfring *ring, pfring *master)

Set the master ring using the PF_RING handle (vanilla PF_RING only).

Return
0 on success, a negative value otherwise.
Parameters
  • ring: The PF_RING handle.
  • master: The master PF_RING handle.

u_int32_t pfring_get_ring_id(pfring *ring)

Return the ring id.

Return
The ring id.
Parameters
  • ring: The PF_RING handle.

u_int32_t pfring_get_num_queued_pkts(pfring *ring)

Return an estimation of the enqueued packets.

Parameters
  • ring: The PF_RING handle.

int pfring_handle_hash_filtering_rule(pfring *ring, hash_filtering_rule *rule_to_add, u_char add_rule)

Add or remove a hash filtering rule. All rule parameters should be defined in the filtering rule (no wildcards).

Return
0 on success, a negative value otherwise (e.g. the rule to be removed does not exist).
Parameters
  • ring: The PF_RING handle from which stats will be read.
  • rule_to_add: The rule that will be added/removed as defined in the last chapter of this document. All rule parameters should be defined in the filtering rule (no wildcards).
  • add_rule: If set to a positive value the rule is added, if zero the rule is removed.

int pfring_add_filtering_rule(pfring *ring, filtering_rule *rule_to_add)

Add a wildcard filtering rule to an existing ring. Each rule will have a unique rule Id across the ring (i.e. two rings can have rules with the same id).

PF_RING allows filtering packets in two ways: precise (a.k.a. hash filtering) or wildcard filtering. Precise filtering is used when it is necessary to track a precise 6-tuple connection <vlan Id, protocol, source IP, source port, destination IP, destination port>. Wildcard filtering is used instead whenever a filter can have wildcards on some of its fields (e.g. match all UDP packets regardless of their destination). If some field is set to zero it will not participate in filter calculation.

Note about packet reflection: packet reflection is the ability to bridge packets in kernel without sending them to userspace and back. You can specify packet reflection inside the filtering rules.

typedef struct { … char reflector_device_name[REFLECTOR_NAME_LEN]; … } filtering_rule;

In the reflector_device_name you need to specify a device name (e.g. eth0) on which packets matching the filter will be reflected. Make sure NOT to specify as reflection device the same device name on which you capture packets, as otherwise you will create a packet loop.

Return
0 on success, a negative value otherwise.
Parameters
  • ring: The PF_RING handle on which the rule will be added.
  • rule_to_add: The rule to add as defined in the last chapter of this document.

int pfring_remove_filtering_rule(pfring *ring, u_int16_t rule_id)

Remove a previously added filtering rule.

Return
0 on success, a negative value otherwise (e.g. the rule does not exist).
Parameters
  • ring: The PF_RING handle on which the rule will be removed.
  • rule_id: The id of a previously added rule that will be removed.

int pfring_purge_idle_hash_rules(pfring *ring, u_int16_t inactivity_sec)

Remove hash filtering rules inactive for the specified number of seconds.

Return
0 on success, a negative value otherwise.
Parameters
  • ring: The PF_RING handle on which the rules will be removed.
  • inactivity_sec: The inactivity threshold.

int pfring_purge_idle_rules(pfring *ring, u_int16_t inactivity_sec)

Remove filtering rules inactive for the specified number of seconds.

Return
0 on success, a negative value otherwise
Parameters
  • ring: The PF_RING handle on which the rules will be removed.
  • inactivity_sec: The inactivity threshold.

int pfring_get_hash_filtering_rule_stats(pfring *ring, hash_filtering_rule *rule, char *stats, u_int *stats_len)

Read statistics of a hash filtering rule.

Return
0 on success, a negative value otherwise (e.g. the rule to be removed does not exist).
Parameters
  • ring: The PF_RING handle on which the rule will be added/removed.
  • rule: The rule for which stats are read. This needs to be the same rule that has been previously added.
  • stats: A buffer allocated by the user that will contain the rule statistics. Please make sure that the buffer is large enough to contain the statistics (hash_filtering_rule_stats struct).
  • stats_len: The size (in bytes) of the stats buffer.

int pfring_get_filtering_rule_stats(pfring *ring, u_int16_t rule_id, char *stats, u_int *stats_len)

Read statistics of a hash filtering rule.

Return
0 on success, a negative value otherwise (e.g. the rule does not exist).
Parameters
  • ring: The PF_RING handle from which stats will be read.
  • rule_id: The rule id that identifies the rule for which stats are read.
  • stats: A buffer allocated by the user that will contain the rule statistics. Please make sure that the buffer is large enough to contain the statistics. Such buffer will contain number of received and dropped packets.
  • stats_len: The size (in bytes) of the stats buffer.

int pfring_toggle_filtering_policy(pfring *ring, u_int8_t rules_default_accept_policy)

Set the default filtering policy. This means that if no rule is matching the incoming packet the default policy will decide if the packet is forwarded to user space or dropped. Note that filtering rules are limited to a ring, so each ring can have a different set of rules and default policy.

Return
0 on success, a negative value otherwise.
Parameters
  • ring: The PF_RING handle on which the rule will be added/removed.
  • rules_default_accept_policy: If set to a positive value the default policy is accept (i.e. forward packets to user space), drop otherwise.

int pfring_enable_rss_rehash(pfring *ring)

Tells PF_RING to rehash incoming packets using a bi-directional hash function. This is also available with the PF_RING-aware libpcap via the PCAP_PF_RING_RSS_REHASH environment variable.

Return
0 on success, a negative value otherwise.
Parameters
  • ring: The PF_RING handle to query.

int pfring_poll(pfring *ring, u_int wait_duration)

Performs passive wait on a PF_RING socket, similar to the standard poll(), taking care of data structures synchronization.

Return
0 on success, a negative value otherwise.
Parameters
  • ring: The PF_RING socket to poll.
  • wait_duration: The poll timeout in msec.

int pfring_is_pkt_available(pfring *ring)

Check if a packet is available.

Return
1 if a packet is available, 0 if there is no packet available, a negative number in case of error.
Parameters
  • ring: The PF_RING handle.

int pfring_next_pkt_time(pfring *ring, struct timespec *ts)

This call returns the arrival time of the next incoming packet, when available.

Return
0 in case of success, a negative number in case of error.
Parameters
  • ring: The PF_RING handle where we perform the check.
  • ts: The struct where the time will be stored.

int pfring_next_pkt_raw_timestamp(pfring *ring, u_int64_t *timestamp_ns)

This call returns the raw timestamp of the next incoming packet, when available. This is available with adapters supporting rx hardware timestamping only.

Return
0 in case of success, a negative number in case of error.
Parameters
  • ring: The PF_RING handle where we perform the check.
  • timestamp_ns: Where the timestamp will be stored.

void pfring_version_noring(u_int32_t *version)

Read the ring version. Note that if the ring version is 5.6 the retuned ring version is 0x050600.

Parameters
  • version: A user-allocated buffer on which ring version will be copied.

int pfring_version(pfring *ring, u_int32_t *version)

Read the ring version. Note that if the ring version is 5.6 the retuned ring version is 0x050600.

Return
0 on success, a negative value otherwise.
Parameters
  • ring: The PF_RING handle, in case the module supports versioning.
  • version: A user-allocated buffer on which ring version will be copied.

int pfring_set_reflector_device(pfring *ring, char *device_name)

Set a reflector device to send all incoming packets. This open a new socket and packets are automatically sent using pfring_send().

Return
0 on success, a negative value otherwise.
Parameters
  • ring: The PF_RING handle.
  • device_name: The device name.

int pfring_get_bound_device_address(pfring *ring, u_char mac_address[6])

Returns the MAC address of the device bound to the socket.

Return
0 on success, a negative value otherwise.
Parameters
  • ring: The PF_RING handle to query.
  • mac_address: The memory area where the MAC address will be copied.

u_int16_t pfring_get_slot_header_len(pfring *ring)

Return the size of the PF_RING packet header (vanilla PF_RING only).

Return
The size of the packet header.
Parameters
  • ring: The PF_RING handle.

int pfring_get_bound_device_ifindex(pfring *ring, int *if_index)

Returns the interface index of the device bound to the socket.

Return
0 on success, a negative value otherwise.
Parameters
  • ring: The PF_RING handle to query.
  • if_index: The memory area where the interface index will be copied

int pfring_get_device_ifindex(pfring *ring, char *device_name, int *if_index)

Return the interface index of the provided device.

Return
0 on success, a negative value otherwise.
Parameters
  • ring: The PF_RING handle.
  • device_name: The device name.
  • if_index: The memory area for storing the interface index.

int pfring_set_virtual_device(pfring *ring, virtual_filtering_device_info *info)

Set a filtering device.

Return
0 on success, a negative value otherwise.
Parameters
  • ring: The PF_RING handle.
  • info: The filtering device info.

int pfring_loopback_test(pfring *ring, char *buffer, u_int buffer_len, u_int test_len)

This call processes packets until pfring_breakloop() is called or an error occurs.

Return
A non-negative number if pfring_breakloop() is called. A negative number in case of error.
Parameters
  • ring: The PF_RING handle.
  • looper: A callback to be called for each received packet. The parameters passed to this routine are: a pointer to a struct pfring_pkthdr, a pointer to the packet memory, and a pointer to user_bytes.
  • user_bytes: A pointer to user’s data which is passed to the callback.
  • wait_for_packet: If 0 active wait is used to check the packet availability.

int pfring_enable_ring(pfring *ring)

When a ring is created, it is not enabled (i.e. incoming packets are dropped) until the above function is called.

Return
0 on success, a negative value otherwise (e.g. the ring cannot be enabled).
Parameters
  • ring: The PF_RING handle to enable.

int pfring_disable_ring(pfring *ring)

Disable a ring.

Return
0 on success, a negative value otherwise.
Parameters
  • ring: The PF_RING handle to disable.

int pfring_set_bpf_filter(pfring *ring, char *filter_buffer)

In order to set BPF filters through the PF_RING API it’s necessary to enable (this is the default) BPF support at compile time and link PF_RING-enabled applications against the -lpcap library (it is possible to disable the BPF support with “cd userland/lib/; ./configure –disable-bpf; make” to avoid linking libpcap).

Return
0 on success, a negative value otherwise.
Parameters
  • ring: The PF_RING handle on which the filter will be set.
  • filter_buffer: The filter to set.

int pfring_remove_bpf_filter(pfring *ring)

Remove the BPF filter.

Return
0 on success, a negative value otherwise.
Parameters
  • ring: The PF_RING handle.

int pfring_set_filtering_mode(pfring *ring, filtering_mode mode)

Sets the filtering mode (software only, hardware only, both software and hardware) in order to implicitly add/remove hardware rules by means of the same API functionality used for software (wildcard and hash) rules.

Return
0 on success, a negative value otherwise.
Parameters
  • ring: The PF_RING handle on which the rule will be removed.
  • mode: The filtering mode.

int pfring_get_device_clock(pfring *ring, struct timespec *ts)

Reads the time from the device hardware clock, when the adapter supports hardware timestamping.

Return
0 on success, a negative value otherwise.
Parameters
  • ring: The PF_RING handle.
  • ts: The struct where time will be stored.

int pfring_set_device_clock(pfring *ring, struct timespec *ts)

Sets the time in the device hardware clock, when the adapter supports hardware timestamping.

Return
0 on success, a negative value otherwise.
Parameters
  • ring: The PF_RING handle.
  • ts: The time to be set.

int pfring_adjust_device_clock(pfring *ring, struct timespec *offset, int8_t sign)

Adjust the time in the device hardware clock with an offset, when the adapter supports hardware timestamping.

Return
0 on success, a negative value otherwise.
Parameters
  • ring: The PF_RING handle.
  • offset: The time offset.
  • sign: The offset sign.

void pfring_sync_indexes_with_kernel(pfring *ring)

Synchronizes the ingress ring indexes/registers with the kernel.

Parameters
  • ring: The PF_RING handle.

int pfring_send_last_rx_packet(pfring *ring, int tx_interface_id)

Send the last received packet to the specified device. This is an optimization working with standard PF_RING only.

Return
0 on success, a negative value otherwise.
Parameters
  • ring: The PF_RING handle on which the packet has been received.
  • tx_interface_id: The egress interface index.

Return the link status.

Return
1 if link is up, 0 otherwise.
Parameters
  • ring: The PF_RING handle.

int pfring_flush_tx_packets(pfring *ring)

Synchronizes the egress ring indexes/registers flushing enqueued packets.

Parameters
  • ring: The PF_RING handle.

int pfring_search_payload(pfring *ring, char *string_to_search)

Add a string to search in the packet payload (used for filtering).

Return
0 on success, a negative value otherwise.
Parameters
  • ring: The PF_RING handle.
  • string_to_search: The string to search.

int pfring_parse_pkt(u_char *pkt, struct pfring_pkthdr *hdr, u_int8_t level, u_int8_t add_timestamp, u_int8_t add_hash)

Parse a packet. It expects that the hdr memory is either zeroed or contains valid values for the current packet, in order to avoid parsing twice the same packet headers. This is implemented by controlling the l3_offset and l4_offset fields, indicating that respectively the L2 and L3 layers have been parsed when other than zero.

Return
A non-negative number indicating the topmost header level on success, a negative value otherwise.
Parameters
  • pkt: The packet buffer.
  • hdr: The header to be filled.
  • level: The header level where to stop parsing.
  • add_timestamp: Add the timestamp.
  • add_hash: Compute an IP-based bidirectional hash.

int pfring_set_if_promisc(const char *device, int set_promisc)

Set the promiscuous mode flag to a device.

Return
0 on success, a negative value otherwise.
Parameters
  • device: The device name.
  • set_promisc: The promisc flag.

int pfring_set_promisc(pfring *ring, int set_promisc)

Set the promiscuous mode to bound device.

Return
0 on success, a negative value otherwise.
Parameters
  • ring: The PF_RING handle.
  • set_promisc: The promisc flag.

char *pfring_format_numbers(double val, char *buf, u_int buf_len, u_int8_t add_decimals)

Format a number.

Return
The produced string.
Parameters
  • val: The value.
  • buf: The destination buffer.
  • buf_len: The destination buffer length.
  • add_decimals: A flag indicating whether to add decimals.

int pfring_enable_hw_timestamp(pfring *ring, char *device_name, u_int8_t enable_rx, u_int8_t enable_tx)

Enables rx and tx hardware timestamping, when the adapter supports it.

Return
0 on success, a negative value otherwise.
Parameters
  • ring: The PF_RING handle.
  • device_name: The name of the device where timestamping will be enabled.
  • enable_rx: Flag to enable rx timestamping.
  • enable_tx: Flag to enable tx timestamping.

int pfring_get_mtu_size(pfring *ring)

Return the size of the MTU.

Return
The MTU size on success, a negative value otherwise.
Parameters
  • ring: The PF_RING handle.

int pfring_get_card_settings(pfring *ring, pfring_card_settings *settings)

Return NIC settings: max packet length, num rx/tx slots (ZC only).

Return
0 on success, a negative value otherwise.
Parameters
  • ring: The PF_RING handle.
  • settings: The card settings (output).

int pfring_print_parsed_pkt(char *buff, u_int buff_len, const u_char *p, const struct pfring_pkthdr *h)

Print a packet (the header with parsing info must be provided).

Return
0 on success, a negative value otherwise.
Parameters
  • buff: The destination buffer.
  • buff_len: The destination buffer length.
  • p: The packet.
  • h: The header.

int pfring_print_pkt(char *buff, u_int buff_len, const u_char *p, u_int len, u_int caplen)

Print a packet.

Return
0 on success, a negative value otherwise.
Parameters
  • buff: The destination buffer.
  • buff_len: The destination buffer length.
  • p: The packet.
  • caplen: The packet length.

int pfring_recv_chunk(pfring *ring, void **chunk, pfring_chunk_info *chunk_info, u_int8_t wait_for_incoming_chunk)

Receive a packet chunk, if enabled via pfring_open() flag.

Return
0 on success, a negative value otherwise.
Parameters
  • ring: The PF_RING handle.
  • chunk: A buffer that will point to the received chunk. Note that the chunk format is adapter specific.
  • chunk_info: Informations about the chunk content and length.
  • wait_for_incoming_chunk: If 0 active wait is used to check the packet availability.

int pfring_set_bound_dev_name(pfring *ring, char *custom_dev_name)

Set a custom device name to which the socket is bound. This function should be called for devices that are not visible via ifconfig

Return
0 on success, a negative value otherwise.
Parameters
  • ring: The PF_RING handle.
  • custom_dev_name: The custom device name to be used for this socket.

int pfring_read_ixia_hw_timestamp(u_char *buffer, u_int32_t buffer_len, struct timespec *ts)

Reads a IXIA-formatted timestamp from an incoming packet and puts it into the timestamp variable.

Return
The length of the IXIA timestamp (hence 0 means that the timestamp has not been found).
Parameters
  • buffer: Incoming packet buffer.
  • buffer_len: Incoming packet buffer length.
  • ts: If found the hardware timestamp will be placed here

void pfring_handle_ixia_hw_timestamp(u_char *buffer, struct pfring_pkthdr *hdr)

Strip a IXIA-formatted timestamp from an incoming packet. If the timestamp is found, the hdr parameter (caplen and len fields) are decreased by the size of the timestamp.

Return
0 on success, a negative value otherwise.
Parameters
  • buffer: Incoming packet buffer.
  • hdr: This is an in/out parameter: it is used to read the original packet len, and it is updated (size decreased) if the hw timestamp is found

int pfring_read_vss_apcon_hw_timestamp(u_char *buffer, u_int32_t buffer_len, struct timespec *ts)

Reads a VSS/APCON-formatted timestamp from an incoming packet and puts it into the timestamp variable.

Return
The length of the VSS/APCON timestamp
Parameters
  • buffer: Incoming packet buffer.
  • buffer_len: Incoming packet buffer length.
  • ts: If found the hardware timestamp will be placed here

void pfring_handle_vss_apcon_hw_timestamp(u_char *buffer, struct pfring_pkthdr *hdr)

Strip an VSS/APCON-formatted timestamp from an incoming packet. If the timestamp is found, the hdr parameter (caplen and len fields) are decreased by the size of the timestamp.

Return
0 on success, a negative value otherwise.
Parameters
  • buffer: Incoming packet buffer.
  • hdr: This is an in/out parameter: it is used to read the original packet len, and it is updated (size decreased) if the hw timestamp is found

u_int32_t pfring_get_interface_speed(pfring *ring)

Get interface speed.

Return
0 if interface speed is unknown, the interface speed (Mbit/s) otherwise.
Parameters
  • ring:

pfring_if_t *pfring_findalldevs(void)

List all interfaces.

Return
The interface list.

void pfring_freealldevs(pfring_if_t *list)

Free an interface list returned by pfring_findalldevs().

Parameters
  • list: The interface list.

int pfring_parse_bpf_filter(char *filter_buffer, u_int caplen, struct pfring_bpf_program *filter)
void pfring_free_bpf_filter(struct pfring_bpf_program *filter)
u_int32_t pfring_bpf_filter(void *bpf_insn, u_char *buffer, u_int32_t caplen, u_int32_t len)
int32_t gmt_to_local(time_t t)
void pfring_thirdparty_lib_init(const char *thirdparty_lib_name, struct thirdparty_func thirdparty_function_ptr[])
struct pfring_card_settings

Public Members

u_int32_t max_packet_size
u_int32_t rx_ring_slots
u_int32_t tx_ring_slots
struct pfring_stat

Public Members

u_int64_t recv
u_int64_t drop
u_int64_t shunt
struct pfring_chunk_info

Public Members

u_int32_t length
pfring_chunk_type type
struct pfring_bpf_program

Public Members

u_int bf_len
void *bf_insns
struct pfring_if

Public Members

char *name
char *system_name
char *module
char *sn
char mac[6]
int slot
int bus
int device
int function
struct pfring_if::[anonymous] bus_id
int status
int license
struct pfring_if *next
struct __pfring

Public Members

u_int8_t initialized
u_int8_t enabled
u_int8_t long_header
u_int8_t force_timestamp
u_int8_t strip_hw_timestamp
u_int8_t disable_parsing
u_int8_t disable_timestamp
u_int8_t ixia_timestamp_enabled
u_int8_t vss_apcon_timestamp_enabled
u_int8_t chunk_mode_enabled
u_int8_t userspace_bpf
u_int8_t force_userspace_bpf
u_int32_t rss_mode
packet_direction direction
socket_mode mode
struct pfring_bpf_program userspace_bpf_filter
u_int8_t is_silicom_hw_timestamp_card
u_int8_t enable_hw_timestamp
u_int8_t last_hw_timestamp_head_offset
struct timespec last_hw_timestamp
struct __pfring::[anonymous] hw_ts
u_int8_t enabled_rx_packet_send
struct pfring_pkthdr *last_received_hdr
struct __pfring::[anonymous] tx
u_int8_t zc_device
void *priv_data
void (*close)(pfring *)
int (*stats)(pfring *, pfring_stat *)
int (*recv)(pfring *, u_char **, u_int, struct pfring_pkthdr *, u_int8_t)
int (*set_poll_watermark)(pfring *, u_int16_t)
int (*set_poll_watermark_timeout)(pfring *, u_int16_t)
int (*set_poll_duration)(pfring *, u_int)
int (*set_tx_watermark)(pfring *, u_int16_t)
int (*set_channel_id)(pfring *, u_int32_t)
int (*set_channel_mask)(pfring *, u_int64_t)
int (*set_application_name)(pfring *, char *)
int (*set_application_stats)(pfring *, char *)
char *(*get_appl_stats_file_name)(pfring *ring, char *path, u_int path_len)
int (*set_vlan_id)(pfring *, u_int16_t)
int (*bind)(pfring *, char *)
int (*send)(pfring *, char *, u_int, u_int8_t)
int (*send_get_time)(pfring *, char *, u_int, struct timespec *)
u_int8_t (*get_num_rx_channels)(pfring *)
int (*get_card_settings)(pfring *, pfring_card_settings *)
int (*set_sampling_rate)(pfring *, u_int32_t)
int (*set_filtering_sampling_rate)(pfring *, u_int32_t)
int (*set_packet_slicing)(pfring *, packet_slicing_level, u_int32_t)
int (*get_selectable_fd)(pfring *)
int (*set_direction)(pfring *, packet_direction)
int (*set_socket_mode)(pfring *, socket_mode)
int (*set_cluster)(pfring *, u_int, cluster_type)
int (*remove_from_cluster)(pfring *)
int (*set_master_id)(pfring *, u_int32_t)
int (*set_master)(pfring *, pfring *)
u_int32_t (*get_ring_id)(pfring *)
u_int32_t (*get_num_queued_pkts)(pfring *)
int (*get_hash_filtering_rule_stats)(pfring *, hash_filtering_rule *, char *, u_int *)
int (*handle_hash_filtering_rule)(pfring *, hash_filtering_rule *, u_char)
int (*purge_idle_hash_rules)(pfring *, u_int16_t)
int (*add_filtering_rule)(pfring *, filtering_rule *)
int (*remove_filtering_rule)(pfring *, u_int16_t)
int (*purge_idle_rules)(pfring *, u_int16_t)
int (*get_filtering_rule_stats)(pfring *, u_int16_t, char *, u_int *)
int (*toggle_filtering_policy)(pfring *, u_int8_t)
int (*enable_rss_rehash)(pfring *)
int (*poll)(pfring *, u_int)
int (*is_pkt_available)(pfring *)
int (*next_pkt_time)(pfring *, struct timespec *)
int (*next_pkt_raw_timestamp)(pfring *, u_int64_t *ts)
int (*version)(pfring *, u_int32_t *)
int (*get_bound_device_address)(pfring *, u_char[6])
int (*get_bound_device_ifindex)(pfring *, int *)
int (*get_device_ifindex)(pfring *, char *, int *)
u_int16_t (*get_slot_header_len)(pfring *)
int (*set_virtual_device)(pfring *, virtual_filtering_device_info *)
int (*add_hw_rule)(pfring *, hw_filtering_rule *)
int (*remove_hw_rule)(pfring *, u_int16_t)
int (*loopback_test)(pfring *, char *, u_int, u_int)
int (*enable_ring)(pfring *)
int (*disable_ring)(pfring *)
void (*shutdown)(pfring *)
int (*set_bpf_filter)(pfring *, char *)
int (*remove_bpf_filter)(pfring *)
int (*get_device_clock)(pfring *, struct timespec *)
int (*set_device_clock)(pfring *, struct timespec *)
int (*adjust_device_clock)(pfring *, struct timespec *, int8_t)
void (*sync_indexes_with_kernel)(pfring *)
int (*send_last_rx_packet)(pfring *, int)
void (*flush_tx_packets)(pfring *)
int (*register_zerocopy_tx_ring)(pfring *, pfring *)
int (*recv_chunk)(pfring *, void **, pfring_chunk_info *, u_int8_t)
int (*set_bound_dev_name)(pfring *, char *)
int (*get_metadata)(pfring *, u_char **, u_int32_t *)
u_int32_t (*get_interface_speed)(pfring *)
int8_t device_id
int8_t port_id
struct __pfring::[anonymous] rdi
filtering_mode ft_mode
pfring_device_type ft_device_type
char *buffer
char *slots
char *device_name
u_int32_t caplen
u_int16_t slot_header_len
u_int16_t mtu
u_int32_t sampling_rate
u_int32_t sampling_counter
packet_slicing_level slicing_level
u_int32_t slicing_additional_bytes
u_int8_t is_shutting_down
u_int8_t socket_default_accept_policy
int fd
int device_id
FlowSlotInfo *slots_info
u_int32_t poll_sleep
u_int16_t poll_duration
u_int8_t promisc
u_int8_t ft_enabled
u_int8_t reentrant
u_int8_t break_recv_loop
u_long num_poll_calls
pfring_rwlock_t rx_lock
pfring_rwlock_t tx_lock
u_int32_t flags
void *ft
struct sockaddr_ll sock_tx
pfring *reflector_socket
pfring *one_copy_rx_pfring
struct pfring_module_info

Public Members

char *name
int (*open)(pfring *)
pfring_if_t *(*findalldevs)(void)
struct thirdparty_func

Public Members

const char *name
void (*ptr)(void)