rec: document which settings can be modified runtime in a better way

Fixes #14870

diff --git a/pdns/recursordist/docs/manpages/rec_control.1.rst b/pdns/recursordist/docs/manpages/rec_control.1.rst
index 2b1bbdf182c0152eafb7fa5b88587a8725a3502f..1dd6fd571998e750316714a35c90b84479be0ce9 100644 (file)
--- a/pdns/recursordist/docs/manpages/rec_control.1.rst
+++ b/pdns/recursordist/docs/manpages/rec_control.1.rst
@@ -211,7 +211,11 @@ reload-lua-config [*FILENAME*]
     executed, any settings changed at runtime that are not modified in this
     file, will still be active. The effects of reloading do not always take
     place immediately, as some subsystems reload and replace configuration
-    in an asynchronous way.
+    in an asynchronous way. IF YAML settings are used this command will
+    reload the runtime settable parts of the YAML settings
+
+reload-yaml
+    Reload the runtime settable parts of the YAML settings.
 
 reload-zones
     Reload authoritative and forward zones. Retains current configuration in

diff --git a/pdns/recursordist/rec_channel_rec.cc b/pdns/recursordist/rec_channel_rec.cc
index 5a53aa1fa0da925d9bf918622a0bf4e6bd44609c..bf3ff8096a3fe726701a818558920b935dc0e7c3 100644 (file)
--- a/pdns/recursordist/rec_channel_rec.cc
+++ b/pdns/recursordist/rec_channel_rec.cc
@@ -1890,6 +1890,7 @@ static RecursorControlChannel::Answer help()
           "quit-nicely                      stop the recursor daemon nicely\n"
           "reload-acls                      reload ACLS\n"
           "reload-lua-script [filename]     (re)load Lua script\n"
+          "reload-yaml                      Reload runtime settable parts of YAML settings\n"
           "reload-lua-config [filename]     (re)load Lua configuration file or equivalent YAML clauses\n"
           "reload-zones                     reload all auth and forward zones\n"
           "set-ecs-minimum-ttl value        set ecs-minimum-ttl-override\n"
@@ -1927,6 +1928,9 @@ RecursorControlChannel::Answer luaconfig(bool broadcast)
   extern std::unique_ptr<ProxyMapping> g_proxyMapping;
   if (!g_luaSettingsInYAML) {
     try {
+      if (::arg()["lua-config-file"].empty()) {
+        return {0, "No Lua or corresponding YAML configuration active\n"};
+      }
       loadRecursorLuaConfig(::arg()["lua-config-file"], proxyMapping, lci);
       activateLuaConfig(lci);
       lci = g_luaconfs.getCopy();
@@ -1992,7 +1996,7 @@ static RecursorControlChannel::Answer luaconfig(T begin, T end)
 {
   if (begin != end) {
     if (g_luaSettingsInYAML) {
-      return {1, "Unable to reload Lua script from '" + ::arg()["lua-config-file"] + " as there is no active Lua configuration\n"};
+      return {1, "Unable to reload Lua script from '" + *begin + " as there is no active Lua configuration\n"};
     }
     ::arg().set("lua-config-file") = *begin;
   }
@@ -2115,6 +2119,9 @@ RecursorControlChannel::Answer RecursorControlParser::getAnswer(int socket, cons
   if (cmd == "reload-lua-config") {
     return luaconfig(begin, end);
   }
+  if (cmd == "reload-yaml") {
+    return luaconfig(begin, end);
+  }
   if (cmd == "set-carbon-server") {
     return {0, doSetCarbonServer(begin, end)};
   }

diff --git a/pdns/recursordist/settings/docs-new-preamble-in.rst b/pdns/recursordist/settings/docs-new-preamble-in.rst
index 2587face2c597b9bda4515f26630ebc4070d0505..216e1ff5878c5cb32b8bf6a7e6040ed510b47c17 100644 (file)
--- a/pdns/recursordist/settings/docs-new-preamble-in.rst
+++ b/pdns/recursordist/settings/docs-new-preamble-in.rst
@@ -26,6 +26,8 @@ Settings on the command line are processed after the file-based settings are pro
    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.
 
+   When using YAML style for settings originally found in the Lua config file, ``rec_control reload-lua-config`` will reload parts of the YAML settings. Refer to the specific setting to learn if it is subject to reloading. Starting with version 5.2.0, the command ``rec_control reload-yaml`` can be used, which is an alias for ``rec_control reload-lua-config``.
+
 YAML settings file
 ------------------
 Please refer to e.g. `<https://docs.ansible.com/ansible/latest/reference_appendices/YAMLSyntax.html>`_

diff --git a/pdns/recursordist/settings/generate.py b/pdns/recursordist/settings/generate.py
index 052866b90ea8cf566cb27f5c5be3976ab1fb0985..66a805572b9918e5baa2265ca02b66a226cfa015 100644 (file)
--- a/pdns/recursordist/settings/generate.py
+++ b/pdns/recursordist/settings/generate.py
@@ -47,6 +47,7 @@
 #            to handle old names when converting .conf to .yml
 #   skip-old: optional if this key is present, the field will be skipped in the old style settings.
 #   versionadded: string or list of strings
+#   runtime: optional, mentions how the settings can be updated runtime (or via API) if applicable
 #
 # The above struct will generate in cxxsettings-generated.cc:
 #
@@ -701,6 +702,15 @@ def gen_oldstyle_docs(srcdir, entries):
                 file.write('- YAML setting does not exist\n\n')
             else:
                 file.write(f"- YAML setting: :ref:`setting-yaml-{section}.{entry['name']}`\n\n")
+            if 'runtime' in entry:
+                runtime = entry['runtime']
+                if not isinstance(runtime, list):
+                    runtime = [runtime]
+                for k,v in enumerate(runtime):
+                    runtime[k] = '``' + runtime[k] + '``'
+                    if v == 'reload-yaml':
+                         continue
+                file.write(f"- Runtime modifiable using ``rec_control`` {', '.join(f'{w}' for w in runtime)}\n\n")
             file.write(entry['doc'].strip())
             file.write('\n\n')
 
@@ -758,6 +768,15 @@ def gen_newstyle_docs(srcdir, argentries):
                 file.write(f"- {entry['skip-old']}\n\n")
             else:
                 file.write(f"- Old style setting: :ref:`setting-{entry['oldname']}`\n\n")
+            if 'runtime' in entry:
+                runtime = entry['runtime']
+                if not isinstance(runtime, list):
+                    runtime = [runtime]
+                for k,v in enumerate(runtime):
+                    runtime[k] = '``' + runtime[k] + '``'
+                    if v == 'reload-yaml':
+                         runtime[k] = 'since 5.2.0: ' + runtime[k]
+                file.write(f"- Runtime modifiable using ``rec_control`` {', '.join(f'{w}' for w in runtime)}\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 c8a93fdee9207b6c9910ecd26d640d2e86508185..a2aa110fac09846b5207ce3d326f97f7e168ece3 100644 (file)
--- a/pdns/recursordist/settings/table.py
+++ b/pdns/recursordist/settings/table.py
@@ -40,6 +40,7 @@ The number of records to cache in the aggressive cache. If set to a value greate
 To use this, DNSSEC processing or validation must be enabled by setting :ref:`setting-dnssec` to ``process``, ``log-fail`` or ``validate``.
  ''',
         'versionadded': '4.5.0',
+        'runtime': 'set-max-aggr-nsec-cache-size',
     },
     {
         'name' : 'aggressive_cache_min_nsec3_hit_ratio',
@@ -75,6 +76,7 @@ When the Proxy Protocol is enabled (see :ref:`setting-proxy-protocol-from`), the
 
 Note that specifying an IP address without a netmask uses an implicit netmask of /32 or /128.
  ''',
+        'runtime': ['reload-acls'],
     },
     {
         'name' : 'allow_from_file',
@@ -96,6 +98,7 @@ Overrides the :ref:`setting-allow-from` setting. Example content of th specified
  - ::1
 
  ''',
+        'runtime': ['reload-acls'],
     },
     {
         'name' : 'allow_notify_for',
@@ -108,7 +111,8 @@ Domain names specified in this list are used to permit incoming
 NOTIFY operations to wipe any cache entries that match the domain
 name. If this list is empty, all NOTIFY operations will be ignored.
  ''',
-    'versionadded': '4.6.0'
+        'versionadded': '4.6.0',
+        'runtime': ['reload-acls'],
     },
     {
         'name' : 'allow_notify_for_file',
@@ -132,7 +136,8 @@ Like :ref:`setting-allow-notify-for`, except reading a sequence of names from fi
  - example.org
 
  ''',
-    'versionadded': '4.6.0'
+        'versionadded': '4.6.0',
+        'runtime': ['reload-acls'],
     },
     {
         'name' : 'allow_notify_from',
@@ -176,7 +181,8 @@ the zone specified in the NOTIFY operation, but only if that zone (or
 one of its parents) is included in :ref:`setting-allow-notify-for`,
 :ref:`setting-allow-notify-for-file`, or :ref:`setting-forward-zones-file` with a ``allow_notify`` set to ``true``.
  ''',
-    'versionadded': '4.6.0'
+        'versionadded': '4.6.0',
+        'runtime': ['reload-acls'],
     },
     {
         'name' : 'allow_notify_from_file',
@@ -192,7 +198,8 @@ by a '#'.
         'doc-new' : '''
 Like :ref:`setting-allow-notify-from`, except reading a sequence of `Subnet`_ from file.
  ''',
-    'versionadded': '4.6.0'
+        'versionadded': '4.6.0',
+        'runtime': ['reload-acls'],
     },
     {
         'name' : 'allow_no_rd',
@@ -281,6 +288,7 @@ DNSSEC is not supported. Example:
     - zone: powerdns.com
       file: /var/zones/powerdns.com
  ''',
+        'runtime': ['reload-zones'],
     },
     {
         'name' : 'interval',
@@ -347,6 +355,7 @@ See :doc:`metrics`.
 Will send all available metrics to these servers via the carbon protocol, which is used by graphite and metronome.
 See :doc:`metrics`.
  ''',
+        'runtime': 'set-carbon-server',
     },
     {
         'name' : 'chroot',
@@ -479,7 +488,8 @@ Any servers' name suffix-matching the supplied names will never be throttled.
 .. warning::
   Most servers on the internet do not respond for a good reason (overloaded or unreachable), ``dont-throttle-names`` could make this load on the upstream server even higher, resulting in further service degradation.
  ''',
-    'versionadded': '4.2.0'
+        'versionadded': '4.2.0',
+        'runtime': ['add-dont-throttle-names', 'clear-dont-throttle-names'],
     },
     {
         'name' : 'dont_throttle_netmasks',
@@ -509,7 +519,8 @@ In this case, :ref:`setting-dont-throttle-netmasks` could be set to include ``19
 .. warning::
   Most servers on the internet do not respond for a good reason (overloaded or unreachable), ``dont-throttle-netmasks`` could make this load on the upstream server even higher, resulting in further service degradation.
  ''',
-    'versionadded': '4.2.0'
+        'versionadded': '4.2.0',
+        'runtime': ['rec_control add-dont-throttle-netmasks', 'rec_control clear-dont-throttle-netmask'],
     },
     {
         'name' : 'devonly_regression_test_mode',
@@ -688,6 +699,7 @@ On such systems not disabling some algorithms (or changing the security policy)
 Log every DNSSEC validation failure.
 **Note**: This is not logged per-query but every time records are validated as Bogus.
  ''',
+        'runtime': 'set-dnssec-log-bogus',
     },
     {
         'name' : 'dont_query',
@@ -731,7 +743,7 @@ This defaults to not using the requestor address inside RFC1918 and similar 'pri
         'doc' : '''
 Number of bits of client IPv4 address to pass when sending EDNS Client Subnet address information.
  ''',
-    'versionadded': '4.1.0'
+        'versionadded': '4.1.0',
     },
     {
         'name' : 'ipv4_cache_bits',
@@ -809,9 +821,9 @@ This setting artificially raises the TTLs of records in the ANSWER section of EC
 Setting this to a value greater than 1 technically is an RFC violation, but might improve performance a lot.
 Using a value of 0 impacts performance of TTL 0 records greatly, since it forces the recursor to contact
 authoritative servers every time a client requests them.
-Can be set at runtime using ``rec_control set-ecs-minimum-ttl 3600``.
  ''',
-        'versionchanged': ('4.5.0', 'Old versions used default 0.')
+        'versionchanged': ('4.5.0', 'Old versions used default 0.'),
+        'runtime': 'set-ecs-minimum-ttl',
     },
     {
         'name' : 'cache_limit_ttl',
@@ -988,7 +1000,8 @@ This file can be used to serve data authoritatively using :ref:`setting-export-e
 Enable the recording and logging of ref:`event traces`. This is an experimental feature and subject to change.
 Possible values are 0: (disabled), 1 (add information to protobuf logging messages) and 2 (write to log) and 3 (both).
  ''',
-    'versionadded': '4.6.0'
+        'versionadded': '4.6.0',
+        'runtime': 'set-event-trace-enabled',
     },
     {
         'name' : 'export_etc_hosts',
@@ -1097,7 +1110,8 @@ To prevent this, add a Negative Trust Anchor (NTA) for this zone in the :ref:`se
 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.
  ''',
-        'versionchanged' : ('5.2.0',  'Zones having ``notify_allowed`` set will be added to :ref:`setting-yaml-incoming.allow_notify_for`.')
+        'versionchanged' : ('5.2.0',  'Zones having ``notify_allowed`` set will be added to :ref:`setting-yaml-incoming.allow_notify_for`.'),
+        'runtime': ['reload-zones'],
     },
     {
         'name' : 'forward_zones_file',
@@ -1138,6 +1152,7 @@ The DNSSEC notes from :ref:`setting-forward-zones` apply here as well.
  ''',
      'versionchanged': [('4.0.0', '(Old style settings only) Comments are allowed, everything behind ``#`` is ignored.'),
                         ('4.6.0', '(Old style settings only) Zones prefixed with a ``^`` are added to the :ref:`setting-allow-notify-for` list. Both prefix characters can be used if desired, in any order.')],
+        'runtime': ['reload-zones'],
     },
     {
         'name' : 'forward_zones_recurse',
@@ -1152,6 +1167,7 @@ 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.
  ''',
+        'runtime': ['reload-zones'],
     },
     {
         'name' : 'gettag_needs_edns_options',
@@ -1456,6 +1472,7 @@ Maximum number of DNS record cache entries, shared by all threads since 4.4.0.
 Each entry associates a name and type with a record set.
 The size of the negative cache is 10% of this number.
  ''',
+        'runtime': 'set-max-cache-entries',
     },
     {
         'name' : 'max_ttl',
@@ -1545,6 +1562,7 @@ Maximum number of simultaneous MTasker threads, per worker thread.
         'doc' : '''
 Maximum number of Packet Cache entries. Sharded and shared by all threads since 4.9.0.
 ''',
+        'runtime': 'set-max-packetcache-entries',
     },
     {
         'name' : 'max_qperq',
@@ -1723,9 +1741,9 @@ This setting artificially raises all TTLs to be at least this long.
 Setting this to a value greater than 1 technically is an RFC violation, but might improve performance a lot.
 Using a value of 0 impacts performance of TTL 0 records greatly, since it forces the recursor to contact
 authoritative servers each time a client requests them.
-Can be set at runtime using ``rec_control set-minimum-ttl 3600``.
  ''',
-     'versionchanged': ('4.5.0', 'Old versions used default 0.')
+        'versionchanged': ('4.5.0', 'Old versions used default 0.'),
+        'runtime': 'set-minimum-ttl',
     },
     {
         'name' : 'tracking',
@@ -2399,6 +2417,7 @@ Setting this to an empty string disables secpoll.
 This makes the server authoritatively aware of: ``10.in-addr.arpa``, ``168.192.in-addr.arpa``, ``16-31.172.in-addr.arpa``, which saves load on the AS112 servers.
 Individual parts of these zones can still be loaded or forwarded.
  ''',
+        'runtime': ['reload-zones'],
     },
     {
         'name' : 'serve_rfc6303',
@@ -2412,6 +2431,7 @@ Individual parts of these zones can still be loaded or forwarded.
 :ref:`setting-serve-rfc1918` must be enabled for this option to take effect.
 ''',
         'versionadded': ['5.1.3', '5.2.0'],
+        'runtime': ['reload-zones'],
     },
     {
         'name' : 'serve_stale_extensions',
@@ -3355,6 +3375,7 @@ If a zone appears multiple times, the entries in ``dsrecords`` are merged.
         ''',
         'skip-old' : 'Equivalent Lua config in :doc:`lua-config/dnssec`',
         'versionadded': '5.1.0',
+        'runtime': ['add-ta', 'clear-ta', 'reload-lua-config', 'reload-yaml'],
     },
     {
         'name' : 'negative_trustanchors',
@@ -3367,6 +3388,7 @@ Sequence of negative trust anchors.
         ''',
         'skip-old' : 'Equivalent Lua config in :doc:`lua-config/dnssec`',
         'versionadded': '5.1.0',
+        'runtime': ['add-nta', 'clear-nta'],
     },
     {
         'name' : 'trustanchorfile',
@@ -3404,6 +3426,7 @@ Sequence of outgoing protobuf servers. Currently the maximum size of this list i
         ''',
         'skip-old' : 'Equivalent Lua config in :doc:`lua-config/protobuf`',
         'versionadded': '5.1.0',
+        'runtime': ['reload-lua-config', 'reload-yaml'],
     },
     {
         'name' : 'outgoing_protobuf_servers',
@@ -3416,6 +3439,7 @@ Sequence of outgoing protobuf servers. Currently the maximum size of this list i
         ''',
         'skip-old' : 'Equivalent Lua config in :doc:`lua-config/protobuf`',
         'versionadded': '5.1.0',
+        'runtime': ['reload-lua-config', 'reload-yaml'],
     },
     {
         'name' : 'protobuf_mask_v4',
@@ -3452,6 +3476,7 @@ Sequence of dnstap servers. Currently the maximum size of this list is one.
         ''',
         'skip-old' : 'Equivalent Lua config in :doc:`lua-config/protobuf`',
         'versionadded': '5.1.0',
+        'runtime': ['reload-lua-config', 'reload-yaml'],
     },
     {
         'name' : 'dnstap_nod_framestream_servers',
@@ -3464,6 +3489,7 @@ Sequence of NOD dnstap servers. Currently the maximum size of this list is one.
         ''',
         'skip-old' : 'Equivalent Lua config in :doc:`lua-config/protobuf`',
         'versionadded': '5.1.0',
+        'runtime': ['reload-lua-config', 'reload-yaml'],
     },
     {
         'name' : 'sortlists',
@@ -3488,6 +3514,7 @@ Sequence of RPZ entries.
         ''',
         'skip-old' : 'Equivalent Lua config in :doc:`lua-config/rpz`',
         'versionadded': '5.1.0',
+        'runtime': ['reload-lua-config', 'reload-yaml'],
     },
     {
         'name' : 'zonetocaches',
@@ -3500,6 +3527,7 @@ Sequence of ZoneToCache entries
         ''',
         'skip-old' : 'Equivalent Lua config in :doc:`lua-config/ztc`',
         'versionadded': '5.1.0',
+        'runtime': ['reload-lua-config', 'reload-yaml'],
     },
     {
         'name' : 'allowed_additional_qtypes',
@@ -3512,6 +3540,7 @@ Sequence of AllowedAdditionalQType
         ''',
         'skip-old' : 'Equivalent Lua config in :doc:`lua-config/additionals`',
         'versionadded': '5.1.0',
+        'runtime': ['reload-lua-config', 'reload-yaml'],
     },
     {
         'name' : 'proxymappings',
@@ -3524,6 +3553,7 @@ Sequence of ProxyMapping
         ''',
         'skip-old' : 'Equivalent Lua config in :doc:`lua-config/proxymapping`',
         'versionadded': '5.1.0',
+        'runtime': ['reload-lua-config', 'reload-yaml'],
     },
     {
         'name' : 'lua_start_stop_script',
@@ -3548,5 +3578,6 @@ Sequence of ForwardingCatalogZone
         ''',
         'skip-old' : 'No equivalent old style setting',
         'versionadded': '5.2.0',
+        'runtime': ['reload-lua-config', 'reload-yaml'],
     },
 ]