doc/firewall: update hooks & configuration examples

doc/userguide/configuration/suricata-yaml.rst

@@ -2773,10 +2773,10 @@ Suricata as a Firewall options (experimental)
 
 It is possible to run Suricata as a firewall.
 Please read :ref:`Firewall Mode Design <firewall mode design>` before using this.
-The existing yaml configuration options are listed below. If the engine is run
-in firewall mode, dedicated stats counters will be added to the stats logs.
+The existing yaml configuration options are listed below. For more examples on default policy configuration by app-layer hook, check :ref:`firewall examples-default policies-http`.
 
-To see the stats reported for the firewall mode, refer to :ref:`firewall mode stats`.
+If the engine is run in firewall mode, dedicated stats counters will be added to
+the stats logs. To see the stats reported for the firewall mode, refer to :ref:`firewall mode stats`.
 
 ::
 
@@ -2792,6 +2792,18 @@ To see the stats reported for the firewall mode, refer to :ref:`firewall mode st
      #rule-files:
      #  - firewall.rules
 
+     # Default policies
+     #
+     # Choose a default policy for each firewall hook.
+     # It is also possible to specify policies by app-layer protocol.
+     # DNS example: Drop and alert on all DNS requests that are not allowed in firewall.rules, accept all responses.
+     #
+     #policies:
+     #  packet-filter: ["drop:packet"]
+     #  dns:
+     #    request-started: ["accept:hook"]
+     #    request-complete: ["drop:flow", "alert"]
+     #    response-started: ["accept:tx"]
 
 Engine analysis and profiling
 -----------------------------

doc/userguide/firewall/firewall-example.rst

@@ -55,9 +55,14 @@ The HTTP rules need to ``accept`` each state::
 
 Each state needs an ``accept`` rule. Each state is evaluated at least once.
 
+.. _firewall examples-default policies-http:
+
 HTTP example with partially using default policies
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+In the example below: the config auto accepts various hooks, leaving just ``http1:request_line``,
+``http1:request_headers`` and ``http1:response_line`` for the ruleset to accept.
+
 ::
 
     firewall:
@@ -109,9 +114,6 @@ HTTP example with partially using default policies
     accept:hook http1:response_line any any -> any any ( \
             http.stat_code; content:"200"; sid:201;)
 
-Explanation: the config auto accepts various hooks, leaving just ``http1:request_line``,
-``http1:request_headers`` and ``http1:response_line`` for the ruleset to accept.
-
 
 TLS SNI with complex TCP rules
 ------------------------------