Starting up with a hot cache

This feature allows a newly started Recursor instance to request a cache dump from an already running Recursor. If such a cache dump is available, the newly started Recursor will insert the retrieved record sets into its own record cache. If no other Recursor is available to share its cache content, the newly started Recursor will continue starting up without a hot cache.

Setting up

To make cache sharing on startup useful, you need at least two Recursors instances. You also need an available NATS server. If your current environment does not have a NATS server, see the NATS website.

To enable the functionality, the Recursor needs to be configured to start the NATS cache sharing code by defining

  • lua_start_stop_script property to the value /usr/share/lua/5.1/pdns-recursor/natsspawn.lua in the recursor section of the Recursor’s config.

  • By default the Recursor will read its Plexus configuration from a file called recursornatsconf.yml in its default configuration directory. If recursor-config-name is set, the configuration will be read from the file named recursornatsconf-XYZ.yml where XYZ is the config name.

  • To override the default location of the NATS config file, set the the environment variable RECURSORNATSCONFIG to the full path of the YAML file.

The config file is using YAML syntax and must define the recursorNATSConfig. This is the example config file:

---
# This file is part of PowerDNS Recursor Plexus
#
# Example YAML config used by natsrec.lua
#
# To start using nats:
#
# 1. Add the following line to your Recursor YAML configuation file in the
#    recursor section:
#
#      lua_start_stop_script: /usr/share/lua/5.1/pdns-recursor/natsspawn.lua
#
# 2. By default Recursor will look for a file called recursornatsconf.yml in its configuration
#    directory. If a configuration name is set, it will try to read recursornatsconf-name.yml.
#    If set, the environment variable RECURSORNATSCONFIG specifies an alternate location.
#
#
recursorNATSConfig:
   natsServer:
      # The IP and port the NATS server is listening on
      host: '127.0.0.1'
      port: 4222
      # The queue group used for publishing, a single recursor from the queue group will answer
      queueGroup: 'pdns_recursor.publisher'
      # The keys below are optional
      #timeout: 1
      #username: 'user'
      #password: 'changeme'
      #tls: false
      #tls_ca_file: 'file'
      #tls_ca_path: 'path'
      #tls_certificate: 'cert'
      #tls_key: 'key'
   recordCache:
      # The subject name a recursor will use to publish and subscribe record Cache state
      subject: 'pdns_recursor.recordCache'
      # How much record sets per shard (in the recursor producing the data) to request
      perShard: 100
      # The maximum size of the protobuf message to create. You might need to increase the
      # payload limit set in the NATS server
      maxSize: 8000000
   nsSpeed:
      # The subject name a recursor will use to publish and subscribe nameserver speed dumps
      subject: 'pdns_recursor.nsSpeed'
      # The maximum size of the protobuf message to create. You might need to increase the
      # payload limit set in the NATS server
      maxSize: 8000000

The natsServer.host and natsServer.port specify the IP address and port the NATS server is listening on.

The natsServer.queueGroup parameter is used to group Recursors. A single Recursor from the group will be selected to answer a request by a newly started Recursor. It is recommended to share a queue group only with a set of Recursors that share a comparable configuration.

The recordCache.subject parameter should normally not be modified.

The recordCache.perShard and recordCache.maxSize parameters define the maximum size of the dump requested. With the example config the 100 most recently used record sets per record cache shard are requested. Since the default number of shards is 1024 the resulting maximum number of record sets is 102400.

The total size of the dump is limited to a 8 million bytes by the maxSize parameter. The Recursor producing the dump will skip remaining record sets if the dump would grow over this number.

Note that the NATS server limits the maximum payload size. As the default limit is 1 megabyte, you may need to increase the NATS server’s max_payload parameter to 8MB to allow for thes potentially large cache content transfers.

Starting with Recursor version 5.3.0, the table used to record the speeds of known authoritative servers can also be shared. The parameters nsSpeed.subject and nsSpeed.maxSize serve similar purpose as the corresponding recordCache parameters described above.