From: Otto Moerbeek Date: Tue, 26 Mar 2024 09:27:09 +0000 (+0100) Subject: Better cross refs in docs, formatting X-Git-Tag: rec-5.1.0-alpha1~9^2~4 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=34df92e0613497276256c55e84fd2ae709555cff;p=thirdparty%2Fpdns.git Better cross refs in docs, formatting --- diff --git a/pdns/recursordist/docs/lua-config/additionals.rst b/pdns/recursordist/docs/lua-config/additionals.rst index 39d0465381..78ef01956a 100644 --- a/pdns/recursordist/docs/lua-config/additionals.rst +++ b/pdns/recursordist/docs/lua-config/additionals.rst @@ -88,6 +88,7 @@ Calling :func:`addAllowedAdditionalQType` multiple times with a specific qtype .. function:: addAllowedAdditionalQType(qtype, targets [, options ])) .. versionadded:: 4.7.0 + .. versionadded:: 5.1.0 Alternative equivalent YAML setting: :ref:`setting-yaml-recursor.allowed_additional_qtypes`. Allow additional processing for ``qtype``. @@ -96,4 +97,3 @@ Calling :func:`addAllowedAdditionalQType` multiple times with a specific qtype :type targets: list of qtype numbers :param table options: a table of options. Currently the only option is ``mode`` having an integer value. For the available modes, see above. If no mode is specified, the default ``pdns.AdditionalMode.CacheOnlyRequireAuth`` mode is used. - diff --git a/pdns/recursordist/docs/lua-config/dnssec.rst b/pdns/recursordist/docs/lua-config/dnssec.rst index f278c9af6c..421363a419 100644 --- a/pdns/recursordist/docs/lua-config/dnssec.rst +++ b/pdns/recursordist/docs/lua-config/dnssec.rst @@ -7,6 +7,7 @@ This page only documents the Lua functions for DNSSEC configuration .. function:: addTA(name, dscontent) .. versionadded:: 4.2.0 + .. versionadded:: 5.1.0 Alternative equivalent YAML setting: :ref:`setting-yaml-dnssec.trustanchors`. Adds Trust Anchor to the list of DNSSEC anchors. @@ -44,6 +45,8 @@ This page only documents the Lua functions for DNSSEC configuration .. function:: addNTA(name[, reason]) + .. versionadded:: 5.1.0 Alternative equivalent YAML setting: :ref:`setting-yaml-dnssec.negative_trustanchors`. + Adds a Negative Trust Anchor for ``name`` to the configuration. Please read :ref:`ntas` for operational information on NTAs. @@ -60,6 +63,7 @@ This page only documents the Lua functions for DNSSEC configuration .. function:: readTrustAnchorsFromFile(fname[, interval]) .. versionadded:: 4.2.0 + .. versionadded:: 5.1.0 Alternative equivalent YAML setting: :ref:`setting-yaml-dnssec.trustanchorfile` and :ref:`setting-yaml-dnssec.trustanchorfile_interval`. Reads all DS and DNSKEY records from ``fname`` (a BIND zone file) and adds these to the Trust Anchors. This function can be used to read distribution provided trust anchors, as for instance ``/usr/share/dns/root.key`` from Debian's ``dns-root-data`` package. diff --git a/pdns/recursordist/docs/lua-config/index.rst b/pdns/recursordist/docs/lua-config/index.rst index 36a3ec7a2e..ab42e99bf5 100644 --- a/pdns/recursordist/docs/lua-config/index.rst +++ b/pdns/recursordist/docs/lua-config/index.rst @@ -14,3 +14,10 @@ Since version 4.0.0, the PowerDNS Recursor supports additional configuration opt proxymapping In addition, :func:`pdnslog` together with ``pdns.loglevels`` is also supported in the Lua configuration file. + +.. note:: + Starting with version 5.1.0, the settings originally specified in a Lua config file can also be put in YAML form. + The conversion printed by ``rec_control show-yaml`` will print these settings if a Lua config file is specified in the config file being converted. + You have to choose however: either set Lua settings the old way in the Lua config file, or convert all to YAML. + If you are using YAML settings of items originally specified in the Lua config file, do not set :ref:`setting-yaml-recursor.lua_config_file` anymore. The :program:`Recursor` will check that you do not mix both configuration methods. + diff --git a/pdns/recursordist/docs/lua-config/protobuf.rst b/pdns/recursordist/docs/lua-config/protobuf.rst index 82804f0ae2..3a989da501 100644 --- a/pdns/recursordist/docs/lua-config/protobuf.rst +++ b/pdns/recursordist/docs/lua-config/protobuf.rst @@ -15,6 +15,7 @@ Protobuf export to a server is enabled using the ``protobufServer()`` directive: .. function:: protobufServer(servers [, options])) .. versionadded:: 4.2.0 + .. versionadded:: 5.1.0 Alternative equivalent YAML setting: :ref:`setting-yaml-logging.protobuf_servers`. Send protocol buffer messages to one or more servers for incoming queries and/or outgoing responses. The client address may be masked using :func:`setProtobufMasks`, for anonymization purposes. @@ -57,6 +58,7 @@ Protobuf export to a server is enabled using the ``protobufServer()`` directive: .. function:: setProtobufMasks(maskv4, maskV6) .. versionadded:: 4.2.0 + .. versionadded:: 5.1.0 Alternative equivalent YAML setting: :ref:`setting-yaml-logging.protobuf_mask_v4` and :ref:`setting-yaml-logging.protobuf_mask_v6`. :param int maskV4: network mask to apply to the client IPv4 addresses, for anonymization purposes. The default of 32 means no anonymization. :param int maskV6: Same as maskV4, but for IPv6. Defaults to 128. @@ -69,6 +71,7 @@ While :func:`protobufServer` only exports the queries sent to the recursor from .. function:: outgoingProtobufServer(servers [, options]) .. versionadded:: 4.2.0 + .. versionadded:: 5.1.0 Alternative equivalent YAML setting: :ref:`setting-yaml-logging.outgoing_protobuf_servers`. Send protocol buffer messages to one or more servers for outgoing queries and/or incoming responses. @@ -116,6 +119,7 @@ The recursor must have been built with configure ``--enable-dnstap`` to make thi .. function:: dnstapFrameStreamServer(servers, [, options]) .. versionadded:: 4.3.0 + .. versionadded:: 5.1.0 Alternative equivalent YAML setting: :ref:`setting-yaml-logging.dnstap_framestream_servers`. Send dnstap formatted message to one or more framestream servers for outgoing queries and/or incoming responses. @@ -142,6 +146,7 @@ The recursor must have been built with configure ``--enable-dnstap`` to make thi .. function:: dnstapNODFrameStreamServer(servers [, options]) .. versionadded:: 4.8.0 + .. versionadded:: 5.1.0 Alternative equivalent YAML setting: :ref:`setting-yaml-logging.dnstap_nod_framestream_servers`. Send dnstap formatted message for :ref:`Newly Observed Domain` and :ref:`Unique Domain Response`. ``Message.type`` will be set to ``CLIENT_QUERY`` for NOD and ``RESOLVER_RESPONSE`` for UDR. The concerned domain name will be attached in the ``Message.query_zone`` field. diff --git a/pdns/recursordist/docs/lua-config/proxymapping.rst b/pdns/recursordist/docs/lua-config/proxymapping.rst index 691e60dc4b..40d3834661 100644 --- a/pdns/recursordist/docs/lua-config/proxymapping.rst +++ b/pdns/recursordist/docs/lua-config/proxymapping.rst @@ -43,6 +43,7 @@ See :func:`protobufServer` on how to tune the source address logged in ``Protobu .. function:: addProxyMapping(subnet, ip [, domains]) .. versionadded:: 4.7.0 + .. versionadded:: 5.1.0 Alternative equivalent YAML setting: :ref:`setting-yaml-incoming.proxymappings`. Specify a table based mapping for a subnet. diff --git a/pdns/recursordist/docs/lua-config/rpz.rst b/pdns/recursordist/docs/lua-config/rpz.rst index dfae451256..2cabf50d4a 100644 --- a/pdns/recursordist/docs/lua-config/rpz.rst +++ b/pdns/recursordist/docs/lua-config/rpz.rst @@ -91,6 +91,8 @@ RPZ Configuration Functions --------------------------- .. function:: rpzFile(filename, settings) + .. versionadded:: 5.1.0 Alternative equivalent YAML setting: :ref:`setting-yaml-recursor.rpzs`. + Load an RPZ from disk. If multiple files are to be loaded, the zones can be distinguished by setting a ``policyName``, see below. @@ -101,11 +103,13 @@ RPZ Configuration Functions .. versionchanged:: 4.2.0 - The first parameter can be a list of addresses. + The first parameter can be a list of addresses. .. versionchanged:: 4.5.0 - This function has been renamed from ``rpzMaster``. + This function has been renamed from ``rpzMaster``. + + .. versionadded:: 5.1.0 Alternative equivalent YAML setting: :ref:`setting-yaml-recursor.rpzs`. Load an RPZ from AXFR and keep retrieving with IXFR. diff --git a/pdns/recursordist/docs/lua-config/sortlist.rst b/pdns/recursordist/docs/lua-config/sortlist.rst index ba7fc01bc1..8c19011cea 100644 --- a/pdns/recursordist/docs/lua-config/sortlist.rst +++ b/pdns/recursordist/docs/lua-config/sortlist.rst @@ -11,8 +11,12 @@ If netmasks are grouped, this means these get equal ordering. ``addSortList`` ^^^^^^^^^^^^^^^ + +.. versionadded:: 5.1.0 Alternative equivalent YAML setting: :ref:`setting-yaml-recursor.sortlists`. + ``addSortList()`` is used in the :ref:`setting-lua-config-file` and is intended to exactly mirror the semantics of the BIND sortlist option, but the syntax is slightly different. + As an example, the following BIND sortlist: .. code-block:: none @@ -31,3 +35,4 @@ Gets transformed into: In other words: each IP address is put within quotes, and are separated by commas instead of semicolons. For the rest everything is identical. + diff --git a/pdns/recursordist/docs/lua-config/ztc.rst b/pdns/recursordist/docs/lua-config/ztc.rst index 5d3c19c7b5..ca38b8e90b 100644 --- a/pdns/recursordist/docs/lua-config/ztc.rst +++ b/pdns/recursordist/docs/lua-config/ztc.rst @@ -40,6 +40,7 @@ Configuration .. function:: zoneToCache(zone, method, source [, settings ]) .. versionadded:: 4.6.0 + .. versionadded:: 5.1.0 Alternative equivalent YAML setting: :ref:`setting-yaml-recordcache.zonetocaches`. Load a zone and put it into the Recursor cache periodically. diff --git a/pdns/recursordist/rec-lua-conf.cc b/pdns/recursordist/rec-lua-conf.cc index c03b403ff6..98a8c15e88 100644 --- a/pdns/recursordist/rec-lua-conf.cc +++ b/pdns/recursordist/rec-lua-conf.cc @@ -106,15 +106,15 @@ static void parseRPZParameters(const rpzOptions_t& have, RPZTrackerParams& param } if (have.count("defpol") != 0) { params.defpol = DNSFilterEngine::Policy(); - params.defcontent = boost::get(have.at("defcontent")); params.defpol->d_kind = (DNSFilterEngine::PolicyKind)boost::get(have.at("defpol")); params.defpol->setName(params.polName); if (params.defpol->d_kind == DNSFilterEngine::PolicyKind::Custom) { + params.defcontent = boost::get(have.at("defcontent")); if (!params.defpol->d_custom) { params.defpol->d_custom = make_unique(); } params.defpol->d_custom->push_back(DNSRecordContent::make(QType::CNAME, QClass::IN, - params.defcontent)); + params.defcontent)); if (have.count("defttl") != 0) { params.defpol->d_ttl = static_cast(boost::get(have.at("defttl"))); diff --git a/pdns/recursordist/rec-main.cc b/pdns/recursordist/rec-main.cc index b47c57169f..6cacb4e66d 100644 --- a/pdns/recursordist/rec-main.cc +++ b/pdns/recursordist/rec-main.cc @@ -3322,8 +3322,8 @@ void startLuaConfigDelayedThreads(const vector& rpzs, uint64_t continue; } try { - // The get calls all return a value object here. That is essential, since we want copies so that RPZIXFRTracker gets values - // with the proper lifetime. + // RPZIXTracker uses call by value for its args. That is essential, since we want copies so + // that RPZIXFRTracker gets values with the proper lifetime. std::thread theThread(RPZIXFRTracker, rpzPrimary, generation); theThread.detach(); } diff --git a/pdns/recursordist/settings/cxxsupport.cc b/pdns/recursordist/settings/cxxsupport.cc index 71f76b1fa4..b3c335732f 100644 --- a/pdns/recursordist/settings/cxxsupport.cc +++ b/pdns/recursordist/settings/cxxsupport.cc @@ -1168,7 +1168,7 @@ void fromRustToLuaConfig(const rust::Vec& rpzs, params.defpol->d_custom = make_unique(); } params.defpol->d_custom->push_back(DNSRecordContent::make(QType::CNAME, QClass::IN, - std::string(params.defcontent))); + std::string(params.defcontent))); if (rpz.defttl != std::numeric_limits::max()) { params.defpol->d_ttl = static_cast(rpz.defttl); diff --git a/pdns/recursordist/settings/docs-new-preamble-in.rst b/pdns/recursordist/settings/docs-new-preamble-in.rst index 2e8956dfdc..564bc30b01 100644 --- a/pdns/recursordist/settings/docs-new-preamble-in.rst +++ b/pdns/recursordist/settings/docs-new-preamble-in.rst @@ -23,7 +23,7 @@ Settings on the command line are processed after the file-based settings are pro Starting with version 5.1.0, the settings originally specified in a Lua config file can also be put in YAML form. The conversion printed by ``rec_control show-yaml`` will print these settings if a Lua config file is specified in the config file being converted. You have to choose however: either set Lua settings the old way in the Lua config file, or convert all to YAML. - If you are using YAML settings of items originally specified in the Lua config file, do not set :ref:`setting-yaml-recursor.lua_config_file` any more. The :program:`Recursor` will check that you do not mix both configuration methods. + If you are using YAML settings of items originally specified in the Lua config file, do not set :ref:`setting-yaml-recursor.lua_config_file` anymore. The :program:`Recursor` will check that you do not mix both configuration methods. YAML settings file ------------------ diff --git a/pdns/recursordist/settings/table.py b/pdns/recursordist/settings/table.py index 2b036986a7..dc31702756 100644 --- a/pdns/recursordist/settings/table.py +++ b/pdns/recursordist/settings/table.py @@ -3208,7 +3208,7 @@ If this check draws the wrong conclusion, you can disable it. Sequence of trust anchors. If the sequence contains an entry for the root zone, the default root zone trust anchor is not included. If a zone appears multiple times, the entries in ``dsrecords`` are merged. ''', - 'skip-old' : 'Old style in Lua settings', + 'skip-old' : 'Equivalent Lua config in :doc:`lua-config/dnssec`', 'versionadded': '5.1.0', }, { @@ -3220,7 +3220,7 @@ If a zone appears multiple times, the entries in ``dsrecords`` are merged. 'doc' : ''' Sequence of negative trust anchors. ''', - 'skip-old' : 'Old style in Lua settings', + 'skip-old' : 'Equivalent Lua config in :doc:`lua-config/dnssec`', 'versionadded': '5.1.0', }, { @@ -3233,7 +3233,7 @@ Sequence of negative trust anchors. A path to a zone file to read trust anchors from. This can be used to read distribution provided trust anchors, as for instance ``/usr/share/dns/root.key`` from Debian's ``dns-root-data`` package. ''', - 'skip-old' : 'Old style in Lua settings', + 'skip-old' : 'Equivalent Lua config in :doc:`lua-config/dnssec`', 'versionadded': '5.1.0', }, { @@ -3245,7 +3245,7 @@ This can be used to read distribution provided trust anchors, as for instance `` 'doc' : ''' Interval (in hours) to re-read the ``trustanchorfile``. Zero disables periodic re-reads. ''', - 'skip-old' : 'Old style in Lua settings', + 'skip-old' : 'Equivalent Lua config in :doc:`lua-config/dnssec`', 'versionadded': '5.1.0', }, { @@ -3257,7 +3257,7 @@ Interval (in hours) to re-read the ``trustanchorfile``. Zero disables periodic 'doc' : ''' Sequence of outgoing protobuf servers. Currently the maximum size of this list is one. ''', - 'skip-old' : 'Old style in Lua settings', + 'skip-old' : 'Equivalent Lua config in :doc:`lua-config/protobuf`', 'versionadded': '5.1.0', }, { @@ -3269,7 +3269,7 @@ Sequence of outgoing protobuf servers. Currently the maximum size of this list i 'doc' : ''' Sequence of outgoing protobuf servers. Currently the maximum size of this list is one. ''', - 'skip-old' : 'Old style in Lua settings', + 'skip-old' : 'Equivalent Lua config in :doc:`lua-config/protobuf`', 'versionadded': '5.1.0', }, { @@ -3281,7 +3281,7 @@ Sequence of outgoing protobuf servers. Currently the maximum size of this list i 'doc' : ''' Network mask to apply to the client IPv4 addresses, for anonymization purposes. The default of 32 means no anonymization. ''', - 'skip-old' : 'Old style in Lua settings', + 'skip-old' : 'Equivalent Lua config in :doc:`lua-config/protobuf`', 'versionadded': '5.1.0', }, { @@ -3293,7 +3293,7 @@ Network mask to apply to the client IPv4 addresses, for anonymization purposes. 'doc' : ''' Network mask to apply to the client IPv6 addresses, for anonymization purposes. The default of 128 means no anonymization. ''', - 'skip-old' : 'Old style in Lua settings', + 'skip-old' : 'Equivalent Lua config in :doc:`lua-config/protobuf`', 'versionadded': '5.1.0', }, { @@ -3305,7 +3305,7 @@ Network mask to apply to the client IPv6 addresses, for anonymization purposes. 'doc' : ''' Sequence of dnstap servers. Currently the maximum size of this list is one. ''', - 'skip-old' : 'Old style in Lua settings', + 'skip-old' : 'Equivalent Lua config in :doc:`lua-config/protobuf`', 'versionadded': '5.1.0', }, { @@ -3317,7 +3317,7 @@ Sequence of dnstap servers. Currently the maximum size of this list is one. 'doc' : ''' Sequence of NOD dnstap servers. Currently the maximum size of this list is one. ''', - 'skip-old' : 'Old style in Lua settings', + 'skip-old' : 'Equivalent Lua config in :doc:`lua-config/protobuf`', 'versionadded': '5.1.0', }, { @@ -3329,7 +3329,7 @@ Sequence of NOD dnstap servers. Currently the maximum size of this list is one. 'doc' : ''' Sequence of sort lists. ''', - 'skip-old' : 'Old style in Lua settings', + 'skip-old' : 'Equivalent Lua config in :doc:`lua-config/sortlist`', 'versionadded': '5.1.0', }, { @@ -3341,7 +3341,7 @@ Sequence of sort lists. 'doc' : ''' Sequence of RPZ entries. ''', - 'skip-old' : 'Old style in Lua settings', + 'skip-old' : 'Equivalent Lua config in :doc:`lua-config/rpz`', 'versionadded': '5.1.0', }, { @@ -3353,7 +3353,7 @@ Sequence of RPZ entries. 'doc' : ''' Sequence of ZoneToCache entries ''', - 'skip-old' : 'Old style in Lua settings', + 'skip-old' : 'Equivalent Lua config in :doc:`lua-config/ztc`', 'versionadded': '5.1.0', }, { @@ -3365,7 +3365,7 @@ Sequence of ZoneToCache entries 'doc' : ''' Sequence of AllowedAdditionalQType ''', - 'skip-old' : 'Old style in Lua settings', + 'skip-old' : 'Equivalent Lua config in :doc:`lua-config/additionals`', 'versionadded': '5.1.0', }, { @@ -3377,7 +3377,7 @@ Sequence of AllowedAdditionalQType 'doc' : ''' Sequence of ProxyMapping ''', - 'skip-old' : 'Old style in Lua settings', + 'skip-old' : 'Equivalent Lua config in :doc:`lua-config/proxymapping`', 'versionadded': '5.1.0', }, ]