innodb
inode
installable
+Internic
interop
interoperability
interoperation
--- /dev/null
+.. _ztc:
+
+Zone to Cache
+-------------
+
+Zone to Cache is a function to load a zone to the Recursor cache periodically or once at startup.
+This allows the Recursor to have an always hot cache for these zones.
+The zone to cache can be retrieved via zone transfer (AXFR format) or read from a zone file retrieved via http, https or a local file.
+
+Example
+^^^^^^^
+To load the root zone from Internic into the recursor once at startup and when the Lua config is reloaded:
+
+.. code-block:: Lua
+
+ zoneToCache(".", "url", 'https://www.internic.net/domain/root.zone', { refreshPeriod = 0 })
+
+Configuration
+^^^^^^^^^^^^^
+.. function:: zoneToCache(zone, method, source [, settings ])
+
+ .. versionadded:: 4.6.0
+
+ Load a zone and put it into the Recursor cache periodically.
+
+ :param str zone: The name of the zone to load
+ :param str method: One of ``"axfr"``, ``"url"`` or ``"file"``
+ :param str source: A string representing an IP address (when using the ``axfr`` method), URL (when using the ``url`` method) or path name (when using the ``file`` method)
+ :param table settings: A table of settings, see below
+
+
+Zone to Cache settings
+^^^^^^^^^^^^^^^^^^^^^^
+
+These options can be set in the ``settings`` of :func:`zoneToCache`.
+
+timeout
+~~~~~~~
+The maximum time (in seconds) a retrieval using the ``axfr`` or ``url`` method may take.
+Default is 20 seconds.
+
+tsigname
+~~~~~~~~
+The name of the TSIG key to authenticate to the server when using the ``axfr`` method
+When this is set, `tsigalgo`_ and `tsigsecret`_ must also be set.
+
+tsigalgo
+~~~~~~~~
+The name of the TSIG algorithm (like 'hmac-md5') used
+
+tsigsecret
+~~~~~~~~~~
+Base64 encoded TSIG secret
+
+refreshPeriod
+~~~~~~~~~~~~~
+An integer describing the interval (in seconds) to wait between retrievals.
+A value of zero means the retrieval is done once at startup and on Lua configuration reload.
+By default, the refresh value is 86400 (24 hours).
+
+retryOnErrorPeriod
+~~~~~~~~~~~~~~~~~~
+An integer describing the interval (in seconds) to wait before retrying a failed transfer.
+By default 60 is used.
+
+maxReceivedMBytes
+~~~~~~~~~~~~~~~~~
+The maximum size in megabytes of an update via the ``axfr`` or ``url`` methods, to prevent resource exhaustion.
+The default value of 0 means no restriction.
+
+localAddress
+~~~~~~~~~~~~
+The source IP address to use when transferring using the ``axfr`` or ``url`` methods.
+When unset, :ref:`setting-query-local-address` is used.
+
To determine a good value for the :ref:`setting-tcp-fast-open` setting, watch the ``TCPFastOpenListenOverflow`` metric.
If this value increases often, the value might be too low for your traffic, but note that increasing it will use kernel resources.
+Running with a local root zone
+-----------------------------
+Running with a local root zone as described in :rfc:`8806` can help reduce traffic to the root servers and reduce response times for clients.
+Since 4.6.0 PowerDNS Recursor supports two ways of doing this.
+
+Running a local Authoritative Server for the root zone
+
+- The first method is to have a local Authoritative Server that has a copy of the root zone and forward queries to it.
+ Setting up an PowerDNS Authoritative Server to serve a copy of the root zone looks like:
+
+ pdnsutil create-secondary-zone . ip1 ip2
+
+ where ``ip1`` and ``ip2`` are servers willing to serve an AXFR for the root zone; :rfc:`8806` contains a list of candidates in appendix A. The Authoritative Server will periodically make sure its copy of the root zone is up-to-date.
+ The next step is to configure a forward zone to the IP ``ip`` of the Authoritative Server in the settings file or the Recursor:
+
+ forward-zones=.=ip
+
+ The Recursor will use the Authoritative Server to ask questions about the root zone, but if it learns about delegations still follow those.
+ Multiple Recursors can use this Authoritative Server.
+
+- The second method is to cache the root zone as described in :ref:`ztc`.
+ Here each Recursor will download and fill its cache with the contents of the root zone.
+ Depending on the ``timeout`` parameter, this will be done once or periodically.
+ Refer to :ref:`ztc` for details.
Recursor Caches
---------------
struct ZoneData
{
- ZoneData(shared_ptr<Logr::Logger>& log) :
- d_log(log) {}
+ ZoneData(shared_ptr<Logr::Logger>& log, const std::string& zone) :
+ d_log(log),
+ d_zone(zone),
+ d_now(time(nullptr)) {}
// Potentially the two fields below could be merged into a single map. ATM it is not clear to me
// if that would make the code easier to read.
// Maybe use a SuffixMatchTree?
std::set<DNSName> d_delegations;
- time_t d_now;
- DNSName d_zone;
shared_ptr<Logr::Logger>& d_log;
+ DNSName d_zone;
+ time_t d_now;
bool isRRSetAuth(const DNSName& qname, QType qtype) const;
void parseDRForCache(DNSRecord& dr);
while (std::getline(stream, line)) {
lines.push_back(line);
}
+#else
+ throw std::runtime_error("url method configured but libcurl not compiled in");
#endif
return lines;
}
if (config.d_sources.size() > 1) {
d_log->info("Multiple sources not yet supported, using first");
}
- d_zone = DNSName(config.d_zone);
- d_now = time(nullptr);
// We do not do validation, it will happen on-demand if an Indeterminate record is encountered when the caches are queried
// First scan all records collecting info about delegations ans sigs
time_t refresh = config.d_retryOnError;
try {
- ZoneData data(log);
+ ZoneData data(log, config.d_zone);
data.ZoneToCache(config, configGeneration);
if (luaconfsLocal->generation != configGeneration) {
log->info("A more recent configuration has been found, stopping the old update thread");
projects / thirdparty / pdns.git / commitdiff
