1 files changed, 77 insertions, 0 deletions
diff --git a/doc/userguide/performance/packet-capture.rst b/doc/userguide/performance/packet-capture.rst
new file mode 100644
index 0000000..d41f668
--- /dev/null
+++ b/doc/userguide/performance/packet-capture.rst
@@ -0,0 +1,77 @@
+Packet Capture
+==============
+
+Load balancing
+--------------
+
+To get the best performance, Suricata will need to run in 'workers' mode. This effectively means that there are multiple threads, each running a full packet pipeline and each receiving packets from the capture method. This means that we rely on the capture method to distribute the packets over the various threads. One critical aspect of this is that Suricata needs to get both sides of a flow in the same thread, in the correct order.
+
+The AF_PACKET and PF_RING capture methods both have options to select the 'cluster-type'. These default to 'cluster_flow' which instructs the capture method to hash by flow (5 tuple). This hash is symmetric. Netmap does not have a cluster_flow mode built-in. It can be added separately by using the "'lb' tool":https://github.com/luigirizzo/netmap/tree/master/apps/lb
+
+On multi-queue NICs, which is almost any modern NIC, RSS settings need to be considered.
+
+RSS
+---
+
+Receive Side Scaling is a technique used by network cards to distribute incoming traffic over various queues on the NIC. This is meant to improve performance but it is important to realize that it was designed for normal traffic, not for the IDS packet capture scenario. RSS using a hash algorithm to distribute the incoming traffic over the various queues. This hash is normally *not* symmetrical. This means that when receiving both sides of a flow, each side may end up in a different queue. Sadly, when deploying Suricata, this is the common scenario when using span ports or taps.
+
+The problem here is that by having both sides of the traffic in different queues, the order of processing of packets becomes unpredictable. Timing differences on the NIC, the driver, the kernel and in Suricata will lead to a high chance of packets coming in at a different order than on the wire. This is specifically about a mismatch between the two traffic directions. For example, Suricata tracks the TCP 3-way handshake. Due to this timing issue, the SYN/ACK may only be received by Suricata long after the client to server side has already started sending data. Suricata would see this traffic as invalid.
+
+None of the supported capture methods like AF_PACKET, PF_RING or NETMAP can fix this problem for us. It would require buffering and packet reordering which is expensive.
+
+To see how many queues are configured:
+
+::
+
+
+  $ ethtool -l ens2f1
+  Channel parameters for ens2f1:
+  Pre-set maximums:
+  RX:             0
+  TX:             0
+  Other:          1
+  Combined:       64
+  Current hardware settings:
+  RX:             0
+  TX:             0
+  Other:          1
+  Combined:       8
+
+Some NIC's allow you to set it into a symmetric mode. The Intel X(L)710 card can do this in theory, but the drivers aren't capable of enabling this yet (work is underway to try to address this). Another way to address is by setting a special "Random Secret Key" that will make the RSS symmetrical. See http://www.ndsl.kaist.edu/~kyoungsoo/papers/TR-symRSS.pdf (PDF).
+
+In most scenario's however, the optimal solution is to reduce the number of RSS queues to 1:
+
+Example:
+
+::
+
+
+  # Intel X710 with i40e driver:
+  ethtool -L $DEV combined 1
+
+Some drivers do not support setting the number of queues through ethtool. In some cases there is a module load time option. Read the driver docs for the specifics.
+
+
+Offloading
+----------
+
+Network cards, drivers and the kernel itself have various techniques to speed up packet handling. Generally these will all have to be disabled.
+
+LRO/GRO lead to merging various smaller packets into big 'super packets'. These will need to be disabled as they break the dsize keyword as well as TCP state tracking.
+
+Checksum offloading can be left enabled on AF_PACKET and PF_RING, but needs to be disabled on PCAP, NETMAP and others.
+
+
+
+Recommendations
+---------------
+
+Read your drivers documentation! E.g. for i40e the ethtool change of RSS queues may lead to kernel panics if done wrong.
+
+Generic: set RSS queues to 1 or make sure RSS hashing is symmetric. Disable NIC offloading.
+
+AF_PACKET: 1 RSS queue and stay on kernel <=4.2 or make sure you have >=4.4.16, >=4.6.5 or >=4.7. Exception: if RSS is symmetric cluster-type 'cluster_qm' can be used to bind Suricata to the RSS queues. Disable NIC offloading except the rx/tx csum.
+
+PF_RING: 1 RSS queue and use cluster-type 'cluster_flow'. Disable NIC offloading except the rx/tx csum.
+
+NETMAP: 1 RSS queue. There is no flow based load balancing built-in, but the 'lb' tool can be helpful. Another option is to use the 'autofp' runmode. Exception: if RSS is symmetric, load balancing is based on the RSS hash and multiple RSS queues can be used. Disable all NIC offloading.