From: Otto Moerbeek Date: Thu, 22 Feb 2024 13:11:57 +0000 (+0100) Subject: Basic docs of YAML specs of original Lua config X-Git-Tag: rec-5.1.0-alpha1~9^2~7 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=8048fc9cc42bd4021a399b64641d44bbccdf190b;p=thirdparty%2Fpdns.git Basic docs of YAML specs of original Lua config --- diff --git a/pdns/recursordist/rec-main.cc b/pdns/recursordist/rec-main.cc index e35a036025..d3b64f8509 100644 --- a/pdns/recursordist/rec-main.cc +++ b/pdns/recursordist/rec-main.cc @@ -3436,12 +3436,6 @@ void activateLuaConfig(LuaConfigItems& lci) if (lci.dsAnchors.size() > rootDSs.size()) { warnIfDNSSECDisabled("Warning: adding Trust Anchor for DNSSEC, but dnssec is set to 'off'!"); } - for (auto x : lci.dsAnchors) { - cerr << "TA: " << x.first << endl; - for (auto ds : x.second) { - cerr << " DS: " << ds.getZoneRepresentation() << endl; - } - } if (!lci.negAnchors.empty()) { warnIfDNSSECDisabled("Warning: adding Negative Trust Anchor for DNSSEC, but dnssec is set to 'off'!"); } diff --git a/pdns/recursordist/settings/docs-new-preamble-in.rst b/pdns/recursordist/settings/docs-new-preamble-in.rst index a99eb57242..2e8956dfdc 100644 --- a/pdns/recursordist/settings/docs-new-preamble-in.rst +++ b/pdns/recursordist/settings/docs-new-preamble-in.rst @@ -19,6 +19,11 @@ Settings on the command line are processed after the file-based settings are pro In a future release support for the "old-style" ``recursor.conf`` settings file will be dropped. +.. 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` any more. The :program:`Recursor` will check that you do not mix both configuration methods. YAML settings file ------------------ @@ -176,7 +181,7 @@ The refresh is done by performing the equivalent of ``rec_control reload-zones`` Auth Zone ^^^^^^^^^ -A auth zone is defined as: +An auth zone is defined as: .. code-block:: yaml @@ -193,6 +198,232 @@ An example of a ``auth_zones`` entry, consisting of a sequence of auth zones: - zone: example.net file: zones/example.net.zone + +YAML settings corresponding to Lua config items +----------------------------------------------- + +The YAML settings below were introduced in verison 5.1.0 and correspond to the +respective Lua settings. Refer to :doc:`lua-config/index`. + +TrustAnchor +^^^^^^^^^^^ +As of version 5.1.0, a trust anchor is defined as + +.. code-block:: yaml + + name: zonename + dsrecords: sequence of DS record strings in presentation format + +An example of a ``trustanchors`` sequence: + +.. code-block:: yaml + + trustanchors: + - name: example.com + dsrecords: + - 10000 8 2 a06d44b80b8f1d39a95c0b0d7c65d08458e880409bbc683457104237c7f8ec8d + +NegativeTrustAnchor +^^^^^^^^^^^^^^^^^^^ +As of version 5.1.0, a negative trust anchor is defined as + +.. code-block:: yaml + + name: zonename + reason: text + +An example of a ``negative trustanchors`` sequence: + +.. code-block:: yaml + + negative_trustanchors: + - name: example.com + reason: an example + +ProtobufServer +^^^^^^^^^^^^^^ +As of version 5.1.0, a protobuf server is defined as + +.. code-block:: yaml + + servers: [] Sequence of strings representing SocketAddress + timeout: 2 + maxQueuedEntries: 100 + reconnectWaitTime: 1 + taggedOnly: false + asyncConnect: false + logQueries: true + logResponses: true + exportTypes: [A, AAAA, CNAME] Sequence of QType names + logMappedFrom: false + +An example of a ``protobuf_servers`` entry: + +.. code-block:: yaml + + protobuf_servers: + - servers: [6.7.8.9] + timeout: 2 + maxQueuedEntries: 100 + reconnectWaitTime: 1 + taggedOnly: false + asyncConnect: false + logQueries: true + logResponses: true + exportTypes: [A, AAAA, CNAME] + logMappedFrom: false + +DNSTapFrameStreamServers +^^^^^^^^^^^^^^^^^^^^^^^^ +As of version 5.1.0, a dnstap framestream server is defined as + +.. code-block:: yaml + + servers: [] Sequence of strings representing SocketAddress or a socket path + logQueries: true + logResponses: true + bufferHint: 0 + flushTimeout: 0 + inputQueueSize: 0 + outputQueueSize: 0 + queueNotifyThreshold: 0 + reopenInterval: 0 + + +DNSTapNODFrameStreamServers +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +As of version 5.1.0, an NOD dnstap framestream server is defined as + +.. code-block:: yaml + + servers: [] Sequence of strings representing SocketAddress or a socker path + logNODs: true + logUDRs: false + bufferHint: 0 + flushTimeout: 0 + inputQueueSize: 0 + outputQueueSize: 0 + queueNotifyThreshold: 0 + reopenInterval: 0 + +SortList +^^^^^^^^ +As of version 5.1.0, a sortlist entry is defined as + +.. code-block:: yaml + + - key: Subnet + subnets: + - subnet: Subnet + order: number + +RPZ +^^^ +As of version 5.1.0, an RPZ entry is defined as + +.. code-block:: yaml + + name: name or pathname + addresses: [] Sequence of SocketAddress + defcontent: string + defpol: Custom, Drop, NXDOMAIN, NODATA Truncate or NoAction + defpolOverrideLocalData: true + defttl: number + extendedErrorCode: number + extendedErrorExtra: string + includeSOA: false + ignoreDuplicates: false + maxTTL: number + policyName: string + tags: Sequence of string + overridesGettag: true + zoneSizeHint: number + tsig: + name: string + algo: string + secret: base64string + refresh: number + maxReceivedMBytes: number + localAddress: IP address + axfrTimeout: number + dumpFile: string + seedFile: string + +If ``addresses` is empty, the ``name`` field specifies the path name of the RPZ, otherwise the ``name`` field defines the name of the RPZ. + +ZoneToCache +^^^^^^^^^^^ +As of version 5.1.0, a ZoneToCache entry is defined as + +.. code-block:: yaml + + zone: zonename + method: One of axfr, url, file + sources: [] Sequence of string, representing IP address, URL or path + timeout: 20 + tsig: + name: name of key + algo: algorithm + secret: Base64 endcoded secret + refreshPeriod: 86400 + retryOnErrorPeriod: 60 + maxReceivedMBytes: 0 Zero mean no restrcition + localAddress: local IP address to bind to. + zonemd: One of ignore, validate, require + dnssec: One of ignore, validate, require + +For example, a sequence of two ZoneToCache entries: + +.. code-block:: yaml + + zonetocaches: + - zone: . + method: url + sources: ['http://...'] + - zone: example.com + method: file + sources: ['dir/example.com.zone'] + +AllowedAdditionalQType +^^^^^^^^^^^^^^^^^^^^^^ +As of version 5.1.0, an allowed addtional qtype entry is defined as: + +.. code-block:: yaml + + qtype: string represeting a QType + targets: [] Sequence of string representing QType + mode: One of Ignore, CacheOnly, CacheOnlyRequireAuth, ResolveImmediately, ResolveDeferred, default CacheOnlyRequireAuth + +For example: + +.. code-block:: yaml + + allowed_additional_qtypes: + - qtype: MX + targets: [A, AAAA] + - qtype: NAPTR + targets: [A, AAAA, SRV] + mode: ResolveDeferred + +ProxyMapping +^^^^^^^^^^^^ +As of version 5.1.0, a proxy mapping entry is defined as: + +.. code-block:: yaml + + subnet: Subnet + address: IPAddress + domains: [] Sequence of string + +For example: + +.. code-block:: yaml + + proxymappings: + - subnet: 192.168.178.0/24 + address: 128.66.1.2 + + The YAML settings ----------------- diff --git a/pdns/recursordist/settings/generate.py b/pdns/recursordist/settings/generate.py index 4c2fc6ddd3..454bbaf08b 100644 --- a/pdns/recursordist/settings/generate.py +++ b/pdns/recursordist/settings/generate.py @@ -161,9 +161,25 @@ def get_newdoc_typename(typ): if typ == LType.ListAuthZones: return 'Sequence of `Auth Zone`_' if typ == LType.ListTrustAnchors: - return 'Sequence of `TrustAnchors`_' + return 'Sequence of `TrustAnchor`_' if typ == LType.ListNegativeTrustAnchors: - return 'Sequence of `NegativeTrustAnchors`_' + return 'Sequence of `NegativeTrustAnchor`_' + if typ == LType.ListProtobufServers: + return 'Sequence of `ProtobufServer`_' + if typ == LType.ListDNSTapFrameStreamServers: + return 'Sequence of `DNSTapFrameStreamServers`_' + if typ == LType.ListDNSTapNODFrameStreamServers: + return 'Sequence of `DNSTapNODFrameStreamServers`_' + if typ == LType.ListSortLists: + return 'Sequence of `Sortlist`_' + if typ == LType.ListRPZs: + return 'Sequence of `RPZ`_' + if typ == LType.ListZoneToCaches: + return 'Sequence of `ZoneToCache`_' + if typ == LType.ListAllowedAdditionalQTypes: + return 'Sequence of `AllowedAdditionalQType`_' + if typ == LType.ListProxyMappings: + return 'Sequence of `ProxyMapping`_' return 'Unknown' + str(typ) def get_default_olddoc_value(typ, val): @@ -734,7 +750,10 @@ def gen_newstyle_docs(argentries): else: file.write((f"- Default: " f"{get_default_newdoc_value(entry['type'], entry['default'])}\n\n")) - file.write(f"- Old style setting: :ref:`setting-{entry['oldname']}`\n\n") + if 'skip-old' in entry: + file.write(f"- {entry['skip-old']}\n\n") + else: + file.write(f"- Old style setting: :ref:`setting-{entry['oldname']}`\n\n") if 'doc-new' in entry: file.write(fixxrefs(entries, entry['doc-new'].strip())) else: diff --git a/pdns/recursordist/settings/table.py b/pdns/recursordist/settings/table.py index c70e6caea5..2b036986a7 100644 --- a/pdns/recursordist/settings/table.py +++ b/pdns/recursordist/settings/table.py @@ -3194,11 +3194,21 @@ If this check draws the wrong conclusion, you can disable it. 'section' : 'dnssec', 'type' : LType.ListTrustAnchors, 'default' : '[{name: ., dsrecords: [\'20326 8 2 e06d44b80b8f1d39a95c0b0d7c65d08458e880409bbc683457104237c7f8ec8d\']}]', - 'help' : 'XXX', - 'doc' : ''', -XXX + 'docdefault' : ''' + +.. code-block:: yaml + + - name: . + dsrecords: + - 20326 8 2 e06d44b80b8f1d39a95c0b0d7c65d08458e880409bbc683457104237c7f8ec8d + +''', + 'help' : 'Sequence of trust anchors', + 'doc' : ''' +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' : True, + 'skip-old' : 'Old style in Lua settings', 'versionadded': '5.1.0', }, { @@ -3206,11 +3216,11 @@ XXX 'section' : 'dnssec', 'type' : LType.ListNegativeTrustAnchors, 'default' : '', - 'help' : 'XXX', - 'doc' : ''', -XXX + 'help' : 'A sequence of negative trust anchors', + 'doc' : ''' +Sequence of negative trust anchors. ''', - 'skip-old' : True, + 'skip-old' : 'Old style in Lua settings', 'versionadded': '5.1.0', }, { @@ -3218,11 +3228,12 @@ XXX 'section' : 'dnssec', 'type' : LType.String, 'default' : '', - 'help' : 'XXX', - 'doc' : ''', - XXX + 'help' : 'A path to a zone file containing trust anchors', + 'doc' : ''' +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' : True, + 'skip-old' : 'Old style in Lua settings', 'versionadded': '5.1.0', }, { @@ -3230,11 +3241,11 @@ XXX 'section' : 'dnssec', 'type' : LType.Uint64, 'default' : '24', - 'help' : 'XXX', - 'doc' : ''', -XXX + 'help' : 'Interval (in hours) to read the trust anchors file', + 'doc' : ''' +Interval (in hours) to re-read the ``trustanchorfile``. Zero disables periodic re-reads. ''', - 'skip-old' : True, + 'skip-old' : 'Old style in Lua settings', 'versionadded': '5.1.0', }, { @@ -3242,11 +3253,11 @@ XXX 'section' : 'logging', 'type' : LType.ListProtobufServers, 'default' : '', - 'help' : 'XXX', - 'doc' : ''', -XXX + 'help' : 'Sequence of protobuf servers', + 'doc' : ''' +Sequence of outgoing protobuf servers. Currently the maximum size of this list is one. ''', - 'skip-old' : True, + 'skip-old' : 'Old style in Lua settings', 'versionadded': '5.1.0', }, { @@ -3254,11 +3265,11 @@ XXX 'section' : 'logging', 'type' : LType.ListProtobufServers, 'default' : '', - 'help' : 'XXX', - 'doc' : ''', -XXX + 'help' : 'List of outgoing protobuf servers', + 'doc' : ''' +Sequence of outgoing protobuf servers. Currently the maximum size of this list is one. ''', - 'skip-old' : True, + 'skip-old' : 'Old style in Lua settings', 'versionadded': '5.1.0', }, { @@ -3266,11 +3277,11 @@ XXX 'section' : 'logging', 'type' : LType.Uint64, 'default' : '32', - 'help' : 'XXX', - 'doc' : ''', -XXX + 'help' : 'Network mask to apply for client IPv4 addresses in protobuf messages', + 'doc' : ''' +Network mask to apply to the client IPv4 addresses, for anonymization purposes. The default of 32 means no anonymization. ''', - 'skip-old' : True, + 'skip-old' : 'Old style in Lua settings', 'versionadded': '5.1.0', }, { @@ -3278,11 +3289,11 @@ XXX 'section' : 'logging', 'type' : LType.Uint64, 'default' : '128', - 'help' : 'XXX', - 'doc' : ''', -XXX + 'help' : 'Network mask to apply for client IPv6 addresses in protobuf messages', + 'doc' : ''' +Network mask to apply to the client IPv6 addresses, for anonymization purposes. The default of 128 means no anonymization. ''', - 'skip-old' : True, + 'skip-old' : 'Old style in Lua settings', 'versionadded': '5.1.0', }, { @@ -3290,11 +3301,11 @@ XXX 'section' : 'logging', 'type' : LType.ListDNSTapFrameStreamServers, 'default' : '', - 'help' : 'XXX', - 'doc' : ''', -XXX + 'help' : 'Sequence of dnstap servers', + 'doc' : ''' +Sequence of dnstap servers. Currently the maximum size of this list is one. ''', - 'skip-old' : True, + 'skip-old' : 'Old style in Lua settings', 'versionadded': '5.1.0', }, { @@ -3302,11 +3313,11 @@ XXX 'section' : 'logging', 'type' : LType.ListDNSTapNODFrameStreamServers, 'default' : '', - 'help' : 'XXX', - 'doc' : ''', -XXX + 'help' : 'Sequence of NOD dnstap servers', + 'doc' : ''' +Sequence of NOD dnstap servers. Currently the maximum size of this list is one. ''', - 'skip-old' : True, + 'skip-old' : 'Old style in Lua settings', 'versionadded': '5.1.0', }, { @@ -3314,11 +3325,11 @@ XXX 'section' : 'recursor', 'type' : LType.ListSortLists, 'default' : '', - 'help' : 'XXX', - 'doc' : ''', -XXX + 'help' : 'Sequence of sort lists', + 'doc' : ''' +Sequence of sort lists. ''', - 'skip-old' : True, + 'skip-old' : 'Old style in Lua settings', 'versionadded': '5.1.0', }, { @@ -3326,11 +3337,11 @@ XXX 'section' : 'recursor', 'type' : LType.ListRPZs, 'default' : '', - 'help' : 'XXX', - 'doc' : ''', -XXX + 'help' : 'Sequence of RPZ entries', + 'doc' : ''' +Sequence of RPZ entries. ''', - 'skip-old' : True, + 'skip-old' : 'Old style in Lua settings', 'versionadded': '5.1.0', }, { @@ -3338,11 +3349,11 @@ XXX 'section' : 'recordcache', 'type' : LType.ListZoneToCaches, 'default' : '', - 'help' : 'XXX', - 'doc' : ''', -XXX + 'help' : 'Sequence of ZoneToCache entries ', + 'doc' : ''' +Sequence of ZoneToCache entries ''', - 'skip-old' : True, + 'skip-old' : 'Old style in Lua settings', 'versionadded': '5.1.0', }, { @@ -3350,11 +3361,11 @@ XXX 'section' : 'recursor', 'type' : LType.ListAllowedAdditionalQTypes, 'default' : '', - 'help' : 'XXX', - 'doc' : ''', -XXX + 'help' : 'Sequence of AllowedAdditionalQType', + 'doc' : ''' +Sequence of AllowedAdditionalQType ''', - 'skip-old' : True, + 'skip-old' : 'Old style in Lua settings', 'versionadded': '5.1.0', }, { @@ -3362,11 +3373,11 @@ XXX 'section' : 'incoming', 'type' : LType.ListProxyMappings, 'default' : '', - 'help' : 'XXX', - 'doc' : ''', -XXX + 'help' : 'Sequence of ProxyMapping', + 'doc' : ''' +Sequence of ProxyMapping ''', - 'skip-old' : True, + 'skip-old' : 'Old style in Lua settings', 'versionadded': '5.1.0', }, ]