rec: better explain how the `recurse` field works in various contexts

diff --git a/pdns/recursordist/settings/docs-new-preamble-in.rst b/pdns/recursordist/settings/docs-new-preamble-in.rst
index 1881cbe6a91da669b0fc62914043a6e8b3ee72ca..db3a01069885ab37dc1cac4bbb9bf6bf57af3f7b 100644 (file)
--- a/pdns/recursordist/settings/docs-new-preamble-in.rst
+++ b/pdns/recursordist/settings/docs-new-preamble-in.rst
@@ -161,10 +161,10 @@ A forward zone is defined as:
   forwarders:
     - Socket Address
     - ...
-  recurse: Boolean, default false
+  recurse: Boolean, default false (only relevant in a forwarding file)
   notify_allowed: Boolean, default false
 
-An example of a ``forward_zones`` entry, which consists of a sequence of `Forward Zone`_ entries:
+An example of a ``forward_zones_file`` contents, which consists of a sequence of `Forward Zone`_ entries:
 
 .. code-block:: yaml
 
@@ -179,6 +179,11 @@ An example of a ``forward_zones`` entry, which consists of a sequence of `Forwar
     recurse: true
     notify_allowed: true
 
+.. note::
+
+  The ``recurse`` field is relevant only in a ``Foward Zone`` clause in a forwarding file.
+  It has a fixed value in the context of :ref:`setting-yaml-recursor.forward_zones` and :ref:`setting-yaml-recursor.forward_zones_recurse`.
+
 Starting with version 5.1.0, names can be used if
 :ref:`setting-yaml-recursor.system_resolver_ttl` is set.
 The names will be resolved using the system resolver and an automatic refresh of the forwarding zones will happen if a name starts resolving to a new address.

diff --git a/pdns/recursordist/settings/table.py b/pdns/recursordist/settings/table.py
index d289666918e11336e4c3a0ca0f17a497d0e61d01..d3fbc671d04e0b5fc62abd2533bcd16bda2575f6 100644 (file)
--- a/pdns/recursordist/settings/table.py
+++ b/pdns/recursordist/settings/table.py
@@ -1101,14 +1101,20 @@ Multiple IP addresses can be specified and port numbers other than 53 can be con
 Forwarded queries have the ``recursion desired (RD)`` bit set to ``0``, meaning that this setting is intended to forward queries to authoritative servers.
 If an ``NS`` record set for a subzone of the forwarded zone is learned, that record set will be used to determine addresses for name servers of the subzone.
 This allows e.g. a forward to a local authoritative server holding a copy of the root zone, delegations received from that server will work.
+To forward to a recursive resolver use :ref:`setting-yaml-recursor.forward_zones_recurse`.
 
-**Note**: When an ``NS`` record for a subzone is learned and the IP address for that nameserver is included in the IP ranges in :ref:`setting-dont-query`,
-SERVFAIL is returned.
+.. warning::
+  When using DNSSEC validation (which is default), forwards to non-delegated (e.g. internal) zones that have a DNSSEC signed parent zone will validate as ``Bogus``.
+  To prevent this, add a Negative Trust Anchor (NTA) for this zone in the :ref:`setting-lua-config-file` with :func:`addNTA`.
+  If this forwarded zone is signed, instead of adding NTA, add the DS record to the :ref:`setting-lua-config-file` usinf :fun:adTA`.
+  See the :doc:`dnssec` information.
+  When using trust anchors listend in YAML, use the :ref:`setting-yaml-dnssec.trustanchors` and :ref:`setting-yaml-dnssec.negative_trustanchors` clauses.
 
-**IMPORTANT**: When using DNSSEC validation (which is default), forwards to non-delegated (e.g. internal) zones that have a DNSSEC signed parent zone will validate as Bogus.
-To prevent this, add a Negative Trust Anchor (NTA) for this zone in the :ref:`setting-lua-config-file` with ``addNTA('your.zone', 'A comment')``.
-If this forwarded zone is signed, instead of adding NTA, add the DS record to the :ref:`setting-lua-config-file`.
-See the :doc:`dnssec` information.
+.. note::
+  The ``recurse`` field of a `Forward Zone`_ is fixed to ``false`` in the context of :ref:`setting-yaml-recursor.forward_zones`.
+
+.. note::
+  When an ``NS`` record for a subzone is learned and the IP address for that nameserver is included in the IP ranges in :ref:`setting-dont-query`, SERVFAIL is returned.
  ''',
         'versionchanged' : ('5.2.0',  'Zones having ``notify_allowed`` set will be added to :ref:`setting-yaml-incoming.allow_notify_for`.'),
         'runtime': ['reload-zones'],
@@ -1133,7 +1139,7 @@ Zones prefixed with a ``+`` are treated as with
 The DNSSEC notes from :ref:`setting-forward-zones` apply here as well.
  ''',
     'doc-new' : '''
-        Same as :ref:`setting-forward-zones`, parsed from a file as a sequence of `ZoneForward`.
+        Same as :ref:`setting-forward-zones`, parsed from a file as a sequence of `Forward Zone`_.
 
 .. code-block:: yaml
 
@@ -1161,10 +1167,20 @@ The DNSSEC notes from :ref:`setting-forward-zones` apply here as well.
         'default' : '',
         'help' : 'Zones for which we forward queries with recursion bit, comma separated domain=ip pairs',
         'doc' : '''
-Like regular :ref:`setting-forward-zones`, but forwarded queries have the ``recursion desired (RD)`` bit set to ``1``, meaning that this setting is intended to forward queries to other recursive servers.
+Like regular :ref:`setting-forward-zones`, but forwarded queries have the ``recursion desired (RD)`` bit set to ``1``, meaning that this setting is intended to forward queries to other recursive resolvers.
 In contrast to regular forwarding, the rule that delegations of the forwarded subzones are respected is not active.
 This is because we rely on the forwarder to resolve the query fully.
 
+See :ref:`setting-forward-zones` for additional options (such as supplying multiple recursive servers) and an important note about DNSSEC.
+ ''',
+        'doc-new' : '''
+Like regular :ref:`setting-forward-zones`, but forwarded queries have the ``recursion desired (RD)`` bit set to ``1``, meaning that this setting is intended to forward queries to other recursive resolvers.
+In contrast to regular forwarding, the rule that delegations of the forwarded subzones are respected is not active.
+This is because we rely on the forwarder to resolve the query fully.
+
+.. note::
+  The `recurse` field of a `Forward Zone`_ is fixed to ``true`` in the context of :ref:`setting-yaml-recursor.forward_zones_recurse`.
+
 See :ref:`setting-forward-zones` for additional options (such as supplying multiple recursive servers) and an important note about DNSSEC.
  ''',
         'runtime': ['reload-zones'],