Add docs for addAllowedAdditionalQType()

diff --git a/pdns/recursordist/docs/lua-config/additionals.rst b/pdns/recursordist/docs/lua-config/additionals.rst
new file mode 100644 (file)
index 0000000..56a0438
--- /dev/null
+++ b/pdns/recursordist/docs/lua-config/additionals.rst
@@ -0,0 +1,70 @@
+Adding Additional Records to Results
+====================================
+Starting with version 4.7.0, the PowerDNS Recursor has the ability to add additional records to query results.
+
+This allows clients to learn useful information without having to do an extra query.
+Examples of useful information are the related ``A`` and ``AAAA`` records to a query for an ``MX`` record:
+
+::
+
+  ;; ANSWER SECTION:
+  example.net.              86362   IN      MX      20 mx2.example.net.
+  example.net.              86362   IN      MX      10 mx1.example.net.
+
+  ;; ADDITIONAL SECTION:
+  mx1.example.net.          86368   IN      A       192.168.1.2
+  mx2.example.net.          86400   IN      A       192.168.1.3
+  mx1.example.net.          86372   IN      AAAA    2001:db8::1
+  mx2.example.net.          86374   IN      AAAA    2001:db8::2
+
+The default is that the Recursor never adds additional records to an answer it sends to the client.
+The default behavior can be changed by using the :func:`addAllowedAdditionalQType` function in the :ref:`setting-lua-config-file`.
+For each query type allowing additional record processing the Recursor has code to determine the target name to add.
+The target qtypes to add are configurable as is the mode, specifying how to retrieve the records to add.
+
+An example of a configuration:
+
+.. code-block:: Lua
+
+  addAllowedAdditionalQType(pdns.MX, {pdns.A, pdns.AAAA})
+  addAllowedAdditionalQType(pdns.NAPTR, {pdns.A, pdns.AAAA, pdns.SRV}, {mode="ResolveImmediately"})
+
+The first line specifies that additional records should be added to the results of ``MX`` queries using the default mode.
+The qtype of the records to be added are ``A`` and ``AAAA``.
+The default mode is ``CacheOnlyRequireAuth``, this mode will only look in the record cache.
+
+The second line specifies that three record types should be added to ``NAPTR`` answers.
+If needed, the Recursor will do an active resolve to retrieve these records.
+
+The modes available are:
+  * ``Ignore`` Do not do any additional processing for this qtype. This is equivalent to not calling :func:`addAllowedAdditionalQType` for the qtype.
+  * ``CacheOnly`` Look in the record cache for available records. Allow non-authoritative (learned from additional sections received from authoritative servers) records to be added.
+  * ``CacheOnlyRequireAuth`` Look in the record cache for available records. Only authoritative records will be added. These are records received from the nameservers for the specific domain.
+  * ``ResolveImmediately`` Add records from the record cache (including DNSSEC records if relevant). If no record is found in the record cache, actively try to resolve the target name/qtype. This will delay the answer to the client.
+  * ``ResolveDeferred`` Add records from the record cache (including DNSSEC records if relevant). If no record is found in the record cache and the negative cache also has no entry, schedule a background task to resolve the target name/qtype. The next time the query is processed, the cache might hold the relevant information. This mode is not implemented yet.
+
+If an additional record is not available at that time the query is stored into the packet cache the answer packet stored in the packer cache will not contain the additional record.
+Clients repeating the same question will get an answer from the packet cache if the question is still in the packet cache.
+These answers do not have the additional record, even if in the meantime the record cache has learned it.
+Clients wil only see the additional record once the packet cache entry expires and the record cache is consulted again.
+The ``ResolveImmediately`` will not have this issue, at the cost of delaying the first query to resolve the additional records needed.
+
+Configuring additional record processing
+----------------------------------------
+
+The following function is available to configure additional record processing.
+Reloading the Lua configuration will replace the current configuration with the new one.
+Calling  :func:`addAllowedAdditionalQType` multiple times with a specific qtype will replace previous calls with the same qtype.
+
+.. function:: addAllowedAdditionalQType(qtype, targets [, options ]))
+
+  .. versionadded:: 4.7.0
+
+  Allow additional processing for ``qtype``.
+
+  :param int qtype:  the qtype number to enable additional record processing for. Supported are: ``pdns.MX``, ``pdns.SRV``, ``pdns.SVCB``, ``pdns.HTTPS`` and ``pdns.NAPTR``.
+  :param targets: the target qtypes to look for when adding the additionals. For example ``{pdns.A, pdns.AAAA}``.
+  :type targets: list of qtype numbers
+  :param table options: a table of options. Currently the only option is ``mode`` having a string value. For the available modes, see above. If no mode is specified, the default ``"CacheOnlyRequireAuth"`` mode is used.
+
+

diff --git a/pdns/recursordist/docs/lua-config/index.rst b/pdns/recursordist/docs/lua-config/index.rst
index 44d04d16171145ee71254970c8f43ac4db6952e3..64543abbca2275eed73596599d81b69098a2daf9 100644 (file)
--- a/pdns/recursordist/docs/lua-config/index.rst
+++ b/pdns/recursordist/docs/lua-config/index.rst
@@ -10,5 +10,6 @@ Since version 4.0.0, the PowerDNS Recursor supports additional configuration opt
     rpz
     sortlist
     ztc
+    additionals
 
 In addition, :func:`pdnslog` together with ``pdns.loglevels`` is also supported in the Lua configuration file.