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/. 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
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 iffalse
. hoststxt
-
Path to
hosts.txt
file. If set totrue
then the default systemhosts.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
andqclass
- 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
andnxdomain
- The DNS status code and flags indicating if any data is available.
secure
andbogus
-
Indicates DNSSEC validation status. There are three possible combinations:
- Results are signed and validation succeeded,
secure
will betrue
. - Results are signed but validation failed,
secure
will befalse
andbogus
will be a string with an error message. - The results were not signed.
secure
will befalse
andbogus
will benil
.
- Results are signed and validation succeeded,
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.