diff --git a/doc/userguide/configuration/exception-policies.rst b/doc/userguide/configuration/exception-policies.rst index 5fa8a3f8f861..a50289d9eebb 100644 --- a/doc/userguide/configuration/exception-policies.rst +++ b/doc/userguide/configuration/exception-policies.rst @@ -7,7 +7,10 @@ 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. +enabled, the engine will call them when it reaches exception states. Stats for +any applied exception policies can be found in counters related to the specific +configuration setting (:ref:`read more`). Some configuration is +available directly via the :ref:`stats settings`. 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 @@ -207,6 +210,43 @@ Notes: * Not valid means that Suricata will error out and won't start. * ``REJECT`` will make Suricata send a Reset-packet unreach error to the sender of the matching packet. +.. _eps_stats: + +Available Stats +--------------- + +There are stats counters for each supported exception policy scenario: + +.. list-table:: **Exception Policy Stats Counters** + :widths: 50 50 + :header-rows: 1 + :stub-columns: 1 + + * - Setting + - Counter + * - stream.memcap + - tcp.ssn_memcap_exception_policy + * - stream.reassembly.memcap + - tcp.reassembly_memcap_exception_policy + * - stream.midstream + - tcp.midstream_exception_policy + * - defrag.memcap + - defrag.memcap_exception_policy + * - flow.memcap + - flow.memcap_exception_policy + * - app-layer.error + - app_layer.error.exception_policy + +If a given exception policy does not apply for a setting, no related counter +is logged. + +Stats for application layer errors are available in summarized form or per +application layer protocol. As the latter is extremely verbose, by default +Suricata logs only the summary. If any further investigation is needed, it +is recommended to enable per-app-proto exception policy error counters +temporarily (for :ref:`stats configuration`). + + Command-line Options for Simulating Exceptions ---------------------------------------------- diff --git a/doc/userguide/configuration/suricata-yaml.rst b/doc/userguide/configuration/suricata-yaml.rst index 8a39bf29b1cb..75fdcd041b2b 100644 --- a/doc/userguide/configuration/suricata-yaml.rst +++ b/doc/userguide/configuration/suricata-yaml.rst @@ -317,6 +317,11 @@ the global config is documented. #decoder-events-prefix: "decoder.event" # Add stream events as stats. #stream-events: false + # Exception policy stats counters options + # (Note: if exception policy: ignore, counters are not logged) + exception-policy: + #per-app-proto-errors: false # default: false. True will log errors for + # each app-proto. Warning: VERY verbose Statistics can be `enabled` or disabled here. @@ -339,6 +344,10 @@ Similar to the `decoder-events` option, the `stream-events` option controls whether the stream-events are added as counters as well. This is disabled by default. +If any exception policy is enabled, stats counters are logged. To control +verbosity for application layer protocol errors, leave `per-app-proto-errors` +as false. + Outputs ~~~~~~~