Zone to Cache

Zone to Cache is a function to load a zone into the Recursor cache periodically, or every time the Lua configuration is loaded, at startup and whenever rec_control reload-lua-config is issued. This allows the Recursor to have an always hot cache for these zones. The zone content 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:

zoneToCache(".", "url", "https://www.internic.net/domain/root.zone", { refreshPeriod = 0 })

DNSSEC and ZONEMD validation

Starting with version 4.7.0, the Recursor will do validation of the zone retrieved. Validation consists of two parts: DNSSEC and ZONEMD. ZONEMD is described in RFC 8976.

For the DNSSEC part, if the global dnssec setting is not off or process-no-validate and the DS record from the parent zone or trust anchor indicates the zone is DNSSEC signed, the recursor will validate the DNSKEY records of the zone. If a ZONEMD record is present, it will also validate the ZONEMD record. If no ZONEMD is present, the NSEC or NSEC3 denial of the ZONEMD record will be validated. Note that this is not a full validation of the signatures of all records. The signatures of the remaining records will be verified on-demand once the records are inserted into the cache by the Zone to Cache function.

For the ZONEMD part, if the zone has a ZONEMD record with a matching serial number, supported digest algorithm and supported scheme, the digest of the zone will be verified.

For both parts failure of validation will prevent the downloaded zone contents from being inserted into the cache. Absence of DNSSEC records is not considered a failure if the parent zone or negative trust anchor indicate the zone is Insecure. Absence of ZONEMD records is not considered a failure unless DNSSEC indicates ZONEMD records should be present. This behaviour can be tuned with the zoneToCache specific zonemd and dnssec settings described below.

Configuration

zoneToCache(zone, method, source[, settings])

New in version 4.6.0.

New in version 5.1.0: Alternative equivalent YAML setting: recordcache.zonetocaches.

Load a zone and put it into the Recursor cache periodically.

Parameters:
  • zone (str) – The name of the zone to load
  • method (str) – One of "axfr", "url" or "file"
  • source (str) – 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)
  • settings (table) – A table of settings, see below

Zone to Cache settings

These options can be set in the settings of 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 and validate the zone content with 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. For the axfr method query-local-address is used by default. The default used for url method is system dependent.

zonemd

New in version 4.7.0.

A string, possible values: ignore: ignore ZONEMD records, validate: validate ZONEMD if present, require: require valid ZONEMD record to be present. Default validate.

dnssec

New in version 4.7.0.

A string, possible values: ignore: do not do DNSSEC validation, validate: validate DNSSEC records as described above but accept an Insecure (unsigned) zone, require: require DNSSEC validation, as described above. Default validate.