Creating a new context

The lunbound module has a single function, new() for creating a new context. It takes a table with configuration as single optional argument. If no argument is given the config table on the module will be used.

Config options

async

Uses threads if true or forks a process if false.

hoststxt

Path to hosts.txt file. If set to true then the default system hosts.txt file.

resolvconf

Path to resolver configuration. If set to true then the default system resolvers are used. Otherwise root hints are used.

forward

IP address of an upstream resolver(s) to use, a string or array of strings.

trusted

DNSSEC root trust anchors, a string or array of strings.

trustfile

Path to a file containing DNSSEC root trust anchors. Can be specified at compile-time (recommended for distributors).

options

Table allowing arbitrary settings from unbound.conf.

The built-in defaults are as follows:

local resolver = require"luaunbound".new({
    async = true;
    hoststxt = true;
    resolvconf = true;
});

Context methods

ctx:resolve(name, type, class)

Resolves name and returns a table with results.

ctx:resolve_async(callback, name, type, class)

Starts a query in async mode. Results are passed to the callback when the query is completed.

ctx:fd()

Returns a file descriptor that will appear readable when there are results available.

ctx:cancel(query)

Cancel a query.

ctx:cancelall()

Cancel all pending queries.

ctx:process()

Calls callbacks for all completed queries.

ctx:wait()

Blocks until all outstanding queries are completed and then calls callbacks for all completed queries.

ctx:poll()

Returns true if new results are available.

Result table

The result table closely resembles libunbounds struct ub_result.

qname, qtype and qclass

Same as arguments to resolve methods.

canonname

The canonical name if the queried name was a CNAME. Note that full CNAME chasing is done by libunbound.

rcode, havedata and nxdomain

The DNS status code and flags indicating if any data is available.

secure and bogus

Indicates DNSSEC validation status. There are three possible combinations:

• Results are signed and validation succeeded, secure will be true.
• Results are signed but validation failed, secure will be false and bogus will be a string with an error message.
• The results were not signed. secure will be false and bogus will be nil.

The actual result data will be in the array part of the result table, in the form of binary strings. It is your job to parse these into whatever form you want.