This is a binding to libunbound for Lua.


Source can be downloaded with Mercurial from

Signed releases can be found at The latest release is currently 1.0.0.

It is also available from luarocks and can be installed by

luarocks install luaunbound

Starting with Debian 11, it is available as lua-unbound and can be installed by

apt install lua-unbound




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

Uses threads if true or forks a process if false.
Path to hosts.txt file. If set to true then the default system hosts.txt file.
Path to resolver configuration. If set to true then the default system resolvers are used. Otherwise root hints are used.
IP address of an upstream resolver(s) to use, a string or array of strings.
DNSSEC root trust anchors, a string or array of strings.
Path to a file containing DNSSEC root trust anchors. Can be specified at compile-time (recommended for distributors).
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.
Returns a file descriptor that will appear readable when there are results available.
Calls callbacks for all completed queries.
Blocks until all outstanding queries are completed and then calls callbacks for all completed queries.
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.
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.