PF_RING-5.6.0/userland/snort/pfring-daq-module/README.1st

PF_RING support of snort DAQ for snort 2.9 (and later)
------------------------------------------------------


Prerequisites
-------------
Make sure you have installed:
-  snort with DAQ include files/libraries (0.6.2, 1.1.1, and 2.0). You can
   do that downloading snort and DAQ from http://www.snort.org/snort-downloads?
- cd ~/PF_RING/kernel
  sudo make install
- For best performance please use PF_RING DNA that supports both IPS and IDS mode
- make sure you have installed
  - autoconf
  - automake
  - libtool
  - all gcc toolchain

Compilation
-----------
# autoreconf -ivf
# ./configure
# make

Configure Options
-----------------
If you do not have PF_RING installed, nor in the "$HOME/PF_RING" path,
a few configure options are available:

   --with-libpfring-includes=<libpfring include directory>
   --with-pfring-kernel-includes=<pfring kernel include directory>
   --with-libpfring-libraries=<libpfring library directory>

Installation
------------
You can do:
# sudo cp .libs/daq_pfring.so /usr/local/lib/daq/
or
# sudo make install

if you want to run snort without installing it use "--daq-dir=./.libs"


Running snort in IDS mode
-------------------------
# snort --daq-dir=/usr/local/lib/daq --daq pfring --daq-mode passive -i ethX -v -e

It is possible to specify multiple interfaces by using a comma-separated list.

Running snort in IPS mode
-------------------------
# snort --daq-dir=/usr/local/lib/daq --daq pfring  -i ethX:ethY -e -Q

It is possible to specify multiple interface pairs by using a comma-separated list.

PF_RING DAQ Specific Options
----------------------------
1. Kernel Filters
   By default, PF_RING kernel filtering rules are added whenever snort's verdict
   requests to drop specific flows. If you want instead snort (and not PF_RING)
   drop packets (i.e. don't add automatically PF_RING kernel filtering rules)
   add:

   --daq-var no-kernel-filters

   Kernel filtering rules idle for more than 5 minutes are automatically removed. 
   In order to change the default timeout for idle rules do:

   --daq-var kernel-filters-idle-timeout=<seconds>

2. Socket clustering
   PF_RING allows you to distribute packets across multiple processes by using
   socket clusters. For instance two snort instances bound to the same clusterId
   receive each a subset of packets so that both can cooperatively share the load.
   In order to enable this feature do:

   --daq-var clusterid=<comma separated id list>

   where an id is a number (i.e. the clusterId), one for each interface.
   It is also possible to specify the cluster mode, with:

   --daq-var clustermode=<mode>

   where valid mode values are:
   - 2 for 2-tuple flow
   - 4 for 4-tuple flow
   - 5 for 5-tuple flow
   - 6 for 6-tuple flow

3. Bind an instance to a core
   Proper core insulation, grants snort instances not to step on each other's feet.
   In order to bind an instance to a specific core do:
   
   --daq-var bindcpu=<core id> 

4. Kernel-level forwarding in IDS mode
   If you want to forward incoming packets at kernel level while snort is running in 
   IDS mode, you can specify a destination interface for each ingress interface with:
   
   --daq-var lowlevelbridge=<comma-separated interface list>

5. Fast TX in IPS mode
   Since forwarding packets from userspace requires additional copies (thus affecting
   performances), it is possible to forward at kernel level the packets for which snort 
   gives a positive verdict:

   --daq-var fast-tx

6. Packet capture tuning
   It is possible to tune the packet capture activity specifying the poll() timeout:

   --daq-var timeout=<milliseconds>

   and the watermark (min number of incoming packets for the poll() to return):

   --daq-var watermark=<packets>


Example of Clustering + Core Binding
------------------------------------

IDS
----
snort -q --pid-path /var/run --create-pidfile -D -c /etc/snort/snort.conf -l /var/log/snort/bpbr0/instance-1 --daq-dir=/usr/local/lib/daq --daq pfring --daq-mode passive -i eth2,eth3 --daq-var lowlevelbridge=eth3,eth2 --daq-var clusterid=10,11 --daq-var bindcpu=1
snort -q --pid-path /var/run --create-pidfile -D -c /etc/snort/snort.conf -l /var/log/snort/bpbr0/instance-2 --daq-dir=/usr/local/lib/daq --daq pfring --daq-mode passive -i eth2,eth3 --daq-var lowlevelbridge=eth3,eth2 --daq-var clusterid=10,11 --daq-var bindcpu=2
snort -q --pid-path /var/run --create-pidfile -D -c /etc/snort/snort.conf -l /var/log/snort/bpbr0/instance-3 --daq-dir=/usr/local/lib/daq --daq pfring --daq-mode passive -i eth2,eth3 --daq-var lowlevelbridge=eth3,eth2 --daq-var clusterid=10,11 --daq-var bindcpu=3
snort -q --pid-path /var/run --create-pidfile -D -c /etc/snort/snort.conf -l /var/log/snort/bpbr0/instance-4 --daq-dir=/usr/local/lib/daq --daq pfring --daq-mode passive -i eth2,eth3 --daq-var lowlevelbridge=eth3,eth2 --daq-var clusterid=10,11 --daq-var bindcpu=4

IPS
----
snort -q --pid-path /var/run --create-pidfile -D -c /etc/snort/snort.conf -l /var/log/snort/bpbr0/instance-1 --daq-dir=/usr/local/lib/daq --daq pfring --daq-mode inline -i eth2:eth3 --daq-var fast-tx=1 --daq-var clusterid=10,11 --daq-var bindcpu=1
snort -q --pid-path /var/run --create-pidfile -D -c /etc/snort/snort.conf -l /var/log/snort/bpbr0/instance-2 --daq-dir=/usr/local/lib/daq --daq pfring --daq-mode inline -i eth2:eth3 --daq-var fast-tx=1 --daq-var clusterid=10,11 --daq-var bindcpu=2
snort -q --pid-path /var/run --create-pidfile -D -c /etc/snort/snort.conf -l /var/log/snort/bpbr0/instance-3 --daq-dir=/usr/local/lib/daq --daq pfring --daq-mode inline -i eth2:eth3 --daq-var fast-tx=1 --daq-var clusterid=10,11 --daq-var bindcpu=3
snort -q --pid-path /var/run --create-pidfile -D -c /etc/snort/snort.conf -l /var/log/snort/bpbr0/instance-4 --daq-dir=/usr/local/lib/daq --daq pfring --daq-mode inline -i eth2:eth3 --daq-var fast-tx=1 --daq-var clusterid=10,11 --daq-var bindcpu=4

----
Luca Deri <deri@ntop.org>
Alfredo Cardigliano <cardigliano@ntop.org>
July 2012