userguide: add section about exception policies

This describes briefly what the exception policies are, what is the
engine's behavior, what options are available and to which parts are
they implemented.

Task #5475
Task #5515

diff --git a/doc/userguide/configuration/exception-policies.rst b/doc/userguide/configuration/exception-policies.rst
new file mode 100644 (file)
index 0000000..0d82b33
--- /dev/null
+++ b/doc/userguide/configuration/exception-policies.rst
@@ -0,0 +1,105 @@
+.. _exception policies:
+
+Exception Policies
+==================
+
+Suricata has a set of configuration variables to indicate what should the engine
+do when certain exception conditions, such as hitting a memcap, are reached.
+
+They are called Exception Policies and are configurable via suricata.yaml. If
+enabled, the engine will call them when it reaches exception states.
+
+For developers or for researching purposes, there are also simulation options
+exposed in debug mode and passed via command-line. These exist to force or
+simulate failures or errors and understand Suricata behavior under such conditions.
+
+Exception Policies
+------------------
+
+Exception policies are implemented for:
+
+.. list-table:: Exception Policy configuration variables
+   :widths: 20, 18, 62
+   :header-rows: 1
+
+   * - Config setting
+     - Policy variable
+     - Expected behavior
+   * - stream.memcap
+     - memcap-policy
+     - If a stream memcap limit is reached, call the memcap policy on the packet
+       and flow.
+   * - stream.midstream
+     - midstream-policy
+     - If a session is picked up midstream, call the memcap policy on the packet
+       and flow.
+   * - stream.reassembly.memcap
+     - memcap-policy
+     - If stream reassembly reaches memcap limit, call the memcap policy on the
+       packet and flow.
+   * - flow.memcap
+     - memcap-policy
+     - Apply policy when the memcap limit for flows is reached and no flow could
+       be freed up.
+   * - defrag.memcap
+     - memcap-policy
+     - Apply policy when the memcap limit for defrag is reached and no tracker
+       could be picked up.
+   * - app-layer
+     - error-policy
+     - Apply policy if a parser reaches an error state.
+
+To change any of these, go to the specific section in the suricata.yaml file
+(for more configuration details, check the :doc:`suricata.yaml's<suricata-yaml>`
+documentation).
+
+The possible values for the exception policies, and the resulting behaviors,
+are:
+
+- ``drop-flow``: disable inspection for the whole flow (packets, payload,
+  application layer protocol), drop the packet and all future packets in the
+  flow.
+- ``drop-packet``: drop the packet.
+- ``reject``: same as ``drop-flow``, but reject the current packet as well.
+- ``bypass``: bypass the flow. No further inspection is done. :ref:`Bypass
+  <bypass>` may be offloaded.
+- ``pass-flow``: disable payload and packet detection; stream reassembly,
+  app-layer parsing and logging still happen.
+- ``pass-packet``: disable detection, still does stream updates and app-layer
+  parsing (depeding on which policy triggered it).
+- ``ignore``: do not apply exception policies (default behavior).
+
+The *Drop*, *pass* and *reject* are similar to the rule actions described in :ref:`rule
+actions<suricata-yaml-action-order>`.
+
+Command-line Options for Simulating Exceptions
+----------------------------------------------
+
+It is also possible to force specific exception scenarios, to check engine
+behavior under failure or error conditions.
+
+The available command-line options are:
+
+- ``simulate-applayer-error-at-offset-ts``: force an applayer error in the to
+  server direction at the given offset.
+- ``simulate-applayer-error-at-offset-tc``: force an applayer error in the to
+  client direction at the given offset.
+- ``simulate-packet-loss``: simulate that the packet with the given number
+  (``pcap_cnt``) from the session was lost.
+- ``simulate-packet-tcp-reassembly-memcap``: simulate that the TCP stream
+  reassembly reached memcap for the specified packet.
+- ``simulate-packet-tcp-ssn-memcap``: simulate that the TCP session hit the
+  memcap for the specified packet.
+- ``simulate-packet-flow-memcap``: force the engine to assume that flow memcap is
+  hit at the given packet.
+- ``simulate-packet-defrag-memcap``: force Suricata to assume memcap is hit when
+  defragmenting specified packet.
+- ``simulate-alert-queue-realloc-failure``: prevent the engine from dynamically
+  growing the temporary alert queue, during alerts processing.
+
+Common abbreviations
+--------------------
+
+- applayer: application layer protocol
+- memcap: (maximum) memory capacity available
+- defrag: defragmentation

diff --git a/doc/userguide/configuration/index.rst b/doc/userguide/configuration/index.rst
index 5467d8a3fb5f90584e0cb2589fc74b65c5981094..d4891c1132f62c24c5d5a66f41cd75cc6191e363 100644 (file)
--- a/doc/userguide/configuration/index.rst
+++ b/doc/userguide/configuration/index.rst
@@ -5,6 +5,7 @@ Configuration
 
    suricata-yaml
    global-thresholds
+   exception-policies
    snort-to-suricata
    multi-tenant
    dropping-privileges

diff --git a/doc/userguide/performance/ignoring-traffic.rst b/doc/userguide/performance/ignoring-traffic.rst
index 2b1ecdb4c74f50644b370ee1986d2f594ed0f1db..0ce36d6d07e62aa7913ae69bee471f6862ea0149 100644 (file)
--- a/doc/userguide/performance/ignoring-traffic.rst
+++ b/doc/userguide/performance/ignoring-traffic.rst
@@ -78,6 +78,8 @@ after the initial handshake. By setting the `app-layer.protocols.tls.encryption-
 option to `bypass` the rest of this flow is ignored. If flow bypass is enabled,
 the bypass is done in the kernel or in hardware.
 
+.. _bypass:
+
 bypassing traffic
 -----------------
 

diff --git a/doc/userguide/rules/intro.rst b/doc/userguide/rules/intro.rst
index d3e3321b5436d151dd221f98b976dbb3cd97814d..8db71745432e8210aa7d5aca9550ed2f9bd34606 100644 (file)
--- a/doc/userguide/rules/intro.rst
+++ b/doc/userguide/rules/intro.rst
@@ -39,6 +39,8 @@ are the options.
 We will be using the above signature as an example throughout
 this section, highlighting the different parts of the signature.
 
+.. _actions:
+
 Action
 ------
 .. container:: example-rule