docs: clarify exception policy's supported values

As flow.memcap-policy and defrag.memcap-policy do not support flow
actions, clarify that in the documentation. Also fix some typos, and
add missing values in some places where the exception policies were
explained.

Related to
Bug #5940

(cherry picked from commit 31066c7c3b54e5a7144b68ef10b3352929a29166)

diff --git a/doc/userguide/configuration/exception-policies.rst b/doc/userguide/configuration/exception-policies.rst
index 0d82b33210a460e9cf26a944fee30b1f8fd7c94e..2d394d0df9cdd45e9eaa2c2976b212605a3038bf 100644 (file)
--- a/doc/userguide/configuration/exception-policies.rst
+++ b/doc/userguide/configuration/exception-policies.rst
@@ -40,14 +40,15 @@ Exception policies are implemented for:
    * - flow.memcap
      - memcap-policy
      - Apply policy when the memcap limit for flows is reached and no flow could
-       be freed up.
+       be freed up. Apply policy to the packet.
    * - defrag.memcap
      - memcap-policy
      - Apply policy when the memcap limit for defrag is reached and no tracker
-       could be picked up.
+       could be picked up. Apply policy to the packet.
    * - app-layer
      - error-policy
-     - Apply policy if a parser reaches an error state.
+     - Apply policy if a parser reaches an error state. Apply policy to the
+       packet and flow.
 
 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>`
@@ -60,7 +61,8 @@ are:
   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.
+- ``reject``: same as ``drop-flow``, but reject the current packet as well (see
+  ``reject`` action in Rule's :ref:`actions`).
 - ``bypass``: bypass the flow. No further inspection is done. :ref:`Bypass
   <bypass>` may be offloaded.
 - ``pass-flow``: disable payload and packet detection; stream reassembly,

diff --git a/doc/userguide/configuration/suricata-yaml.rst b/doc/userguide/configuration/suricata-yaml.rst
index 32272981ec4beee8df9cc60e74671849078629d0..62fd27ece1e492af320fb2e8947f32243037b182 100644 (file)
--- a/doc/userguide/configuration/suricata-yaml.rst
+++ b/doc/userguide/configuration/suricata-yaml.rst
@@ -937,8 +937,8 @@ Suricata discards the fragments (timeout). This occurs by default after 60
 seconds.
 
 In IPS mode, it is possible to tell the engine what to do in case the memcap for
-the defrag engine is reached: "drop-flow", "pass-flow", "bypass", "drop-packet",
-"pass-packet", or "ignore" (default behavior).
+the defrag engine is reached: "drop-packet", "pass-packet", or "ignore" (default
+behavior).
 
 ::
 
@@ -1000,7 +1000,7 @@ thread ensures that wherever possible and within the memcap. There
 will be 10000 flows prepared.
 
 In IPS mode, a memcap-policy exception policy can be set, telling Suricata
-what to do in case memcap is hit: 'drop-flow', 'pass-flow', 'bypass', 'reject',
+what to do in case memcap is hit: 'drop-packet', 'pass-packet', 'reject', or
 'ignore'.
 
 ::
@@ -1102,8 +1102,8 @@ be recognized by Suricata.
 The stream-engine has two memcaps that can be set. One for the
 stream-tracking-engine and one for the reassembly-engine. For both cases,
 in IPS mode, an exception policy (memcap-policy) can be set, telling Suricata
-what to do in case memcap is hit: 'drop-flow', 'pass-flow', 'bypass', 'reject',
-'ignore'.
+what to do in case memcap is hit: 'drop-flow', 'drop-packet', 'pass-flow',
+'pass-packet', 'bypass', 'reject', or 'ignore'.
 
 The stream-tracking-engine keeps information of the flow in
 memory. Information about the state, TCP-sequence-numbers and the TCP
@@ -1134,7 +1134,8 @@ sessions. This setup always includes a lot of information. If you want
 Suricata to check the stream from that time on, you can do so by
 setting the option 'midstream' to 'true'. The default setting is
 'false'. In IPS mode, it is possible to define a 'midstream-policy',
-indicating whether Suricata should drop, pass or bypass a midstream flow.
+indicating whether Suricata should drop-flow, drop-packet, pass-flow,
+pass-packet, reject, or bypass a midstream flow. The default is ignore.
 Normally Suricata is able to see all packets of a connection. Some networks
 make it more complicated though. Some of the network-traffic follows a
 different route than the other part, in other words: the traffic goes
@@ -1194,7 +1195,8 @@ The reassembly-engine has to keep data segments in memory in order to
 be able to reconstruct a stream. To avoid resource starvation a memcap
 is used to limit the memory used. In IPS mode, an exception policy
 (memcap-policy) can be set, telling Suricata what to do in case memcap
-is hit: 'drop-flow', 'pass-flow', 'bypass', 'reject', 'ignore'.
+is hit: 'drop-flow', 'drop-packet', 'pass-flow', 'pass-packet',  'bypass',
+'reject', or 'ignore'.
 
 Reassembling a stream is an expensive operation. With the option depth
 you can control how far into a stream reassembly is done. By default
@@ -1210,7 +1212,7 @@ adding in a random factor.
 
     reassembly:
       memcap: 256mb             # Memory reserved for stream data reconstruction (in bytes)
-      memcap-policy: ignore     # What to do when a midstream session is seen
+      memcap-policy: ignore     # What to do when memcap for reassembly is hit
       depth: 1mb                # The depth of the reassembling.
       toserver_chunk_size: 2560 # inspect raw stream in chunks of at least this size
       toclient_chunk_size: 2560 # inspect raw stream in chunks of at least
@@ -1255,7 +1257,7 @@ Application Layer Parsers
 The ``app-layer`` section holds application layer specific configurations.
 
 In IPS mode, a global exception policy accessed via the ``error-policy``
-setting can be defined to indicate what the engine should do in case if
+setting can be defined to indicate what the engine should do in case it
 encounters an app-layer error. Possible values are "drop-flow", "pass-flow",
 "bypass", "drop-packet", "pass-packet", "reject" or "ignore" (which maintains
 the default behavior).

diff --git a/suricata.yaml.in b/suricata.yaml.in
index 42ba0576d309d140f38e4871b0b62943467d73a5..78c4b1a0e7f033579bcb9267ea94ae4cae233b94 100644 (file)
--- a/suricata.yaml.in
+++ b/suricata.yaml.in
@@ -1160,8 +1160,8 @@ host-os-policy:
 
 # Defrag settings:
 
-# The memcap-policy value can be "drop-flow", "pass-flow", "bypass",
-# "drop-packet", "pass-packet", "reject" or "ignore" (which is the default).
+# The memcap-policy value can be "drop-packet", "pass-packet", "reject" or
+# "ignore" (which is the default).
 defrag:
   memcap: 32mb
   # memcap-policy: ignore
@@ -1204,8 +1204,8 @@ defrag:
 # last time seen flows.
 # The memcap can be specified in kb, mb, gb.  Just a number indicates it's
 # in bytes.
-# The memcap-policy can be "drop-flow", "pass-flow", "bypass", "drop-packet",
-# "pass-packet", "reject" or "ignore" (which is the default).
+# The memcap-policy can be "drop-packet", "pass-packet", "reject" or "ignore"
+# (which is the default).
 
 flow:
   memcap: 128mb