luaunbound

This is a binding to libunbound for Lua.

Downloading

Source can be downloaded with Mercurial from https://code.zash.se/luaunbound/.

Signed releases can be found at https://code.zash.se/dl/luaunbound/.

It is also available from luarocks and can be installed by

luarocks install luaunbound

Building

make

API

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: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 result struct.

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.