PF_RING User Guide
Linux High Speed Packet Capture
Version 5.4.6
Oct 2012
© 2004-12 ntop.org
1.Table of Contents
...............................................................................................................................Introduction 5
....................................................................................................What’s New with PF_RING User’s Guide? 5
................................................................................................................Welcome to PF_RING 6
................................................................................................................................................Packet Filtering 6
................................................................................................................................................Packet Journey 7
............................................................................................................................................Packet Clustering 7
...........................................................................................................PF_RING Driver Families 9
..................................................................................................................................PF_RING-aware Drivers 9
................................................................................................................................................................TNAPI 9
................................................................................................................................................................DNA 10
........................................................................................................................Libzero for DNA 11
....................................................................................................................................................DNA Cluster 11
..................................................................................................................................................DNA Bouncer 11
................................................................................................................PF_RING Installation 12
..................................................................................................................Linux Kernel Module Installation 12
....................................................................................................................Running PF_RING 13
....................................................................................................Checking PF_RING Device Configuration 13
................................................................................................................Libpfring and Libpcap Installation 14
...................................................................................................................................Application Examples 14
........................................................................................................................PF_RING Additional Modules 15
.....................................................................................PF_RING for Application Developers 17
............................................................................................................................................The PF_RING API 17
.................................................................................................................................................Return Codes 17
..............................................................................................................PF_RING Device Name Convention 17
.....................................................................................................................PF_RING: SOCKET Initialization 18
PF_RING User’s Guide v.5.4.6
2
......................................................................................................................PF_RING: Device Termination 20
................................................................................................................PF_RING: Read Incoming Packets 21
.................................................................................................................................PF_RING: Ring Clusters 26
..........................................................................................................................PF_RING: Packet Reflection 28
..........................................................................................................................PF_RING: Packet Sampling 29
.............................................................................................................................PF_RING: Packet Filtering 30
.........................................................................................................................PF_RING: Wildcard Filtering 30
...............................................................................................................................PF_RING: Hash Filtering 34
..................................................................................................................................PF_RING: BPF Filtering 37
..................................................................................................................PF_RING: In-NIC Packet Filtering 39
...............................................................................................................................PF_RING: Filtering Policy 42
....................................................................................................................PF_RING: Packet Transmission 43
.............................................................................................................PF_RING: Miscellaneous Functions 47
..........................................................................................................................The C++ PF_RING interface 68
.......................................................................................................................libzero for DNA 69
............................................................................................................................................The DNA Cluster 69
..............................................................................................................................................The Master API 69
.................................................................................................................................................The Slave API 80
................................................................................................................................................DNA Bouncer 88
..................................................................................................................................The DNA Bouncer API 88
.....................................................................................................Code Snippets for Common Use Cases 93
.........................................................................................DNA Cluster: receive a packet and put it aside 93
..........................................................................DNA Cluster: receive a packet and send it in zero-copy 94
........................................DNA Cluster: replace the default balancing function with a custom function 95
........................................DNA Cluster: replace the default balancing function with a fan-out function 96
................................DNA Cluster: send an incoming packet directly without passing through a slave 97
........................................................................................................Writing PF_RING Plugins 98
PF_RING User’s Guide v.5.4.6
3
.................................................................................................................Implementing a PF_RING Plugin 98
..............................................................................................PF_RING Plugin: Handle Incoming Packets 100
...................................................................................................PF_RING Plugin: Filter Incoming Packets 102
.....................................................................................................PF_RING Plugin: Read Packet Statistics 103
.............................................................................................................................Using a PF_RING Plugin 104
......................................................................................................PF_RING Data Structures 105
.....................................................................................PF_RING DNA On Virtual Machines 107
......................................................................................................................................BIOS Configuration 107
........................................................................................................................VMware ESX Configuration 108
.......................................................................................................................................KVM Configuration 111
PF_RING User’s Guide v.5.4.6
4
2. Introduction
PF_RING is a high speed packet capture library that turns a commodity PC into an efficient and cheap
network measurement box suitable for both packet and active traffic analysis and manipulation.
Moreover, PF_RING opens totally new markets as it enables the creation of efficient application such as
traffic balancers or packet filters in a matter of lines of codes.
This manual is divided in two parts:
•
PF_RING installation and configuration.
•
PF_RING SDK.
2.1. What’s New with PF_RING User’s Guide?
•
Release 5.4.6 (Aug 2012)
•
Updated guide to PF_RING version 5.4.6
•
Release 5.4.0 (May 2012)
•
Updated guide to PF_RING version 5.4.0
•
New libzero for zero-copy flexible packet processing on top of DNA.
•
Release 5.3.1 (March 2012)
•
Updated guide to PF_RING version 5.3.1
•
Release 5.2.1 (January 2012)
•
Updated guide to PF_RING version 5.2.1
•
New API functions for managing hardware clocks and timestamps.
•
New kernel plugin callbacks.
•
Release 5.1 (September 2011)
•
Updated guide to PF_RING version 5.1.0
•
Release 4.7.1 (July 2011)
•
Updated guide to PF_RING version 4.7.1
•
Described PF_RING modular library and some modules (DAG, DNA)
•
Release 4.6.1 (March 2011)
•
Updated guide to PF_RING version 4.6.1
•
Release 4.6 (February 2011)
•
Updated guide to PF_RING version 4.6.0.
•
Release 1.1 (January 2008)
•
Described PF_RING plugins architecture.
•
Release 1.0 (January 2008)
•
Initial PF_RING users guide.
PF_RING User’s Guide v.5.4.6
5