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

diff --git a/doc/userguide/configuration/exception-policies.rst b/doc/userguide/configuration/exception-policies.rst
index cfa81c9bd2c33873be4ad373f2f75ade06decd36..21c50eaed1d0d54a9732fdbeef80a660dca5e546 100644 (file)
--- a/doc/userguide/configuration/exception-policies.rst
+++ b/doc/userguide/configuration/exception-policies.rst
@@ -29,14 +29,14 @@ have the need to.
 
 ::
 
-   # In IPS mode, the default is drop-packet/drop-flow. To fallback to old
-   # behavior (setting each of them individually, or ignoring all), set this
-   # to ignore.
+   # Define a common behavior for all exception policies.
+   # In IPS mode, the default is drop-flow. For cases when that's not possible, the
+   # engine will fall to drop-packet. To fallback to old behavior (setting each of
+   # them individually, or ignoring all), set this to ignore.
    # All values available for exception policies can be used, and there is one
-   # extra option: auto - which means drop-packet/drop-flow in IPS mode and
-   # ignore in IDS mode).
-   # Exception policy values are: drop-packet, drop-flow, reject, bypass,
-   # pass-packet, pass-flow, ignore (disable).
+   # extra option: auto - which means drop-flow or drop-packet (as explained above)
+   # in IPS mode, and ignore in IDS mode. Exception policy values are: drop-packet,
+   # drop-flow, reject, bypass, pass-packet, pass-flow, ignore (disable).
    exception-policy: auto
 
 This value will be overwritten by specific exception policies whose settings are
@@ -46,10 +46,11 @@ Auto
 ''''
 
 **In IPS mode**, the default behavior for all exception policies is to drop
-packets and/or flows. It is possible to disable this default, by setting the
-exception policies "master switch" yaml config option to ``ignore``.
+the flow, or the packet, when the flow action is not supported. It is possible
+to disable this default, by setting the exception policies' "master switch" yaml
+config option to ``ignore``.
 
-**In IDS mode**, setting auto mode actually means disabling the
+**In IDS mode**, setting ``auto`` mode actually means disabling the
 ``master-swtich``, or ignoring the exception policies.
 
 Specific settings
@@ -79,14 +80,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>`
@@ -99,7 +101,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 fa96d04b54774ea7e2628a3a3087e4d7fed2a8be..04d5e75b7dea4904af405a3a8a469f0a6ac6567c 100644 (file)
--- a/doc/userguide/configuration/suricata-yaml.rst
+++ b/doc/userguide/configuration/suricata-yaml.rst
@@ -936,8 +936,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).
 
 ::
 
@@ -999,7 +999,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'.
 
 ::
@@ -1101,8 +1101,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
@@ -1133,7 +1133,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
@@ -1193,7 +1194,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
@@ -1209,7 +1211,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
@@ -1254,7 +1256,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 e80e8a0d72a4dcaa86278785060cab977b7eca91..da13df91a7703be0b8289222dbaf8aace062b9ec 100644 (file)
--- a/suricata.yaml.in
+++ b/suricata.yaml.in
@@ -1295,14 +1295,13 @@ legacy:
 # Exception Policies
 #
 # Define a common behavior for all exception policies.
-# In IPS mode, the default is drop-packet/drop-flow. To fallback to old
-# behavior (setting each of them individually, or ignoring all), set this
-# to ignore.
+# In IPS mode, the default is drop-flow. For cases when that's not possible, the
+# engine will fall to drop-packet. To fallback to old behavior (setting each of
+# them individually, or ignoring all), set this to ignore.
 # All values available for exception policies can be used, and there is one
-# extra option: auto - which means drop-packet/drop-flow in IPS mode and
-# ignore in IDS mode).
-# Exception policy values are: drop-packet, drop-flow, reject, bypass,
-# pass-packet, pass-flow, ignore (disable).
+# extra option: auto - which means drop-flow or drop-packet (as explained above)
+# in IPS mode, and ignore in IDS mode. Exception policy values are: drop-packet,
+# drop-flow, reject, bypass, pass-packet, pass-flow, ignore (disable).
 exception-policy: auto
 
 # IP Reputation
@@ -1352,8 +1351,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
@@ -1396,8 +1395,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