define_resolver

kumo.dns.define_resolver(NAME, CONFIG)

Since: Dev Builds Only

The functionality described in this section requires a dev build of KumoMTA. You can obtain a dev build by following the instructions in the Installation section.

This function defines an alternative resolver from the default configured via configure_resolver, and gives it a name.

The alternate resolver name can then be optionally passed as a parameter to a number of other kumo.dns functions.

The intended use case is to define an alternate resolver that points to an rbldnsd or similar specialized resolver that provides access to a DNSBL.

The NAME parameter is a string that defines the name of the alternate resolver.

The CONFIG parameter defines the parameters for the resolver. It can have one of the following shapes:

Note

This function should be called only from inside your init event handler.

Hickory with an explicit upstream

If you have rbldnsd or similar available on 10.0.0.1:53, then you might use this:

kumo.dns.define_resolver('rbl', {
  Hickory = {
    name_servers = {
      '10.0.0.1:53',
    },
  },
})

You can then query it:

local answer, reason = kumo.dns.rbl_lookup(IP, 'rbl.domain', 'rbl')

Test or static DNS

If you have fixed and locally available zone data, then you can query that explicitly:

kumo.dns.define_resolver('rbl', {
  Test = {
    zones = {
      [[
$ORIGIN rbl.domain.
1.0.0.10 30 IN A   127.0.0.2
1.0.0.10 300   TXT "Blocked for a very good reason!"
  ]],
    },
  },
})

You can then query it:

local answer, reason = kumo.dns.rbl_lookup('10.0.0.1', 'rbl.domain', 'rbl')

This mode of operation was originally intended for testing, but may prove useful in other situations.

System Default

kumo.dns.define_resolver('myresolver', 'HickorySystemConfig')

Parses the system resolver configuration and applies that to a separate instance of the hickory DNS resolver client. This is equivalent to the default resolver settings in kumomta.

Unbound with an explicit upstream

Note

We generally recommend sticking with Hickory unless you have a very good reason.

If you have rbldnsd or similar available on 10.0.0.1:53, then you might use this:

kumo.dns.define_resolver('rbl', {
  Unbound = {
    name_servers = {
      '10.0.0.1:53',
    },
  },
})

You can then query it:

local answer, reason = kumo.dns.rbl_lookup(IP, 'rbl.domain', 'rbl')

Aggregating Different Resolvers

If you have a mixture of local zone files and a remote DNS, then you can mix them together; have the local zones queried before falling back to a remote host.

In the example below, the local zone is used first before falling back to querying the upstream specified by the system.

kumo.dns.define_resolve('aggregate', {
  Aggregate = {
    -- The value of `Aggregate` here is an array style table
    -- listing out one of the CONFIG options shown in the
    -- examples above.

    -- First we have a Test setup
    Test = {
      zones = {
        [[
$ORIGIN 0.0.127.in-addr.arpa.
1 30 IN PTR localhost.
  ]],
      },
    },

    -- Then we have a system default setup
    'HickorySystemConfig',
  },
})