1 files changed, 66 insertions, 0 deletions
diff --git a/doc/userguide/performance/runmodes.rst b/doc/userguide/performance/runmodes.rst
new file mode 100644
index 0000000..4afc5d5
--- /dev/null
+++ b/doc/userguide/performance/runmodes.rst
@@ -0,0 +1,66 @@
+Runmodes
+========
+
+Suricata consists of several 'building blocks' called threads,
+thread-modules and queues.  A thread is like a process that runs on a
+computer. Suricata is multi-threaded, so multiple threads are active
+at once.  A thread-module is a part of a functionality. One module is
+for example for decoding a packet, another is the detect-module and
+another one the output-module.  A packet can be processed by more than
+one thread. The packet will then be passed on to the next thread through
+a queue. Packets will be processed by one thread at a time, but there
+can be multiple packets being processed at a time by the engine (see
+:ref:`suricata-yaml-max-pending-packets`). A thread can have one or
+more thread-modules. If they have more modules, they can only be
+active one a a time.  The way threads, modules and queues are arranged
+together is called the "Runmode".
+
+Different runmodes
+~~~~~~~~~~~~~~~~~~
+
+You can choose a runmode out of several predefined runmodes. The
+command line option ``--list-runmodes`` shows all available runmodes. All
+runmodes have a name: single, workers, autofp.
+
+Generally, the ``workers`` runmode performs the best. In this mode the
+NIC/driver makes sure packets are properly balanced over Suricata's
+processing threads. Each packet processing thread then contains the
+full packet pipeline.
+
+.. image:: runmodes/workers.png
+
+For processing PCAP files, or in case of certain IPS setups (like NFQ),
+``autofp`` is used. Here there are one or more capture threads, that
+capture the packet and do the packet decoding, after which it is passed
+on to the ``flow worker`` threads.
+
+.. image:: runmodes/autofp1.png
+
+.. image:: runmodes/autofp2.png
+
+Finally, the ``single`` runmode is the same as the ``workers`` mode,
+however there is only a single packet processing thread. This is mostly
+useful during development.
+
+.. image:: runmodes/single.png
+
+For more information about the command line options concerning the
+runmode, see :doc:`../command-line-options`.
+
+Load balancing
+~~~~~~~~~~~~~~
+
+Suricata may use different ways to load balance the packets to process
+between different threads with the configuration option `autofp-scheduler`.
+
+The default value is `hash`, which means the packet is assigned to threads
+using the 5-7 tuple hash, which is also used anyways to store the flows
+in memory.
+
+This option can also be set to
+- `ippair` : packets are assigned to threads using addresses only.
+- `ftp-hash` : same as `hash` except for flows that may be ftp or ftp-data
+so that these flows get processed by the same thread. Like so, there is no
+concurrency issue in recognizing ftp-data flows due to processing them
+before the ftp flow got processed. In case of such a flow, a variant of the
+hash is used.