DNS Client

Config fields

Returns nil, err if servers is missing or empty.

dns.client.parse_resolv_conf(path)

Parses a resolv.conf file and returns a config table suitable for passing directly to dns.client.new(). Defaults to /etc/resolv.conf.

Parsed directives: nameserver → servers, search/domain → search, options ndots:N → ndots, options timeout:N → timeout, options attempts:N → retries.

-- Use system resolvers
local sys = dns.client.parse_resolv_conf()
local resolver = dns.new(sys)

-- Merge with overrides
local sys = dns.client.parse_resolv_conf()
sys.timeout = 3
sys.use_tls = true
local resolver = dns.new(sys)

Returns nil, err if the file cannot be read.

resolver:resolve(qname, qtype)

Resolves qname by querying upstream servers with retry, failover, and optional caching. Follows CNAME chains (depth limit 10) and applies search list expansion based on ndots.

qtype is a record type string ("A", "AAAA", "MX") or number.

Returns a list of matching answer records on success, nil, err on failure.

local answers, err = resolver:resolve("example.com", "A")
if not answers then
    print("error: " .. err)
else
    for _, rr in ipairs(answers) do
        print(rr.rdata.address, "TTL", rr.ttl)
    end
end

resolver:query(raw_bytes)

Lower-level interface. Sends a pre-encoded DNS message, returns the decoded response. No caching, no CNAME following, no response validation.

resolver:close()

Closes transport sockets. Call when done with the resolver.

RDATA by type

Cache config

Cache API

• cache:get(qname, qtype) — returns cached records with adjusted TTLs, or nil

• cache:put(qname, qtype, records, ttl) — store records with TTL clamping

• cache:get_negative(qname, qtype) — returns negative cache entry, or nil

• cache:put_negative(qname, qtype, rcode, soa_record) — store NXDOMAIN/NODATA

• cache:sweep() — remove expired entries (in-memory: rate-limited by sweep_interval; MNEME: purge_expired)

• cache:flush() — clear all entries

• cache:lookup(qname, qtype) — combined positive+negative lookup in a single call

• cache:stats() — returns {backend, size, neg_size}

iter.ROOT_SERVERS

Table of the 13 IANA root name servers. Each entry has name (FQDN), host (IPv4), and v6 (IPv6) fields.

iter.query_server(host, qname, qtype, opts)

Send a single iterative (RD=0) query to a specific server IP. Returns the full decoded response message including all sections.

qtype may be a string ("A", "NS") or numeric code. Automatically retries over TCP on truncation (TC bit).

local iter = require("dns.iter")
local resp, err = iter.query_server("198.41.0.4", "example.com", "A")

Options: port (default 53), timeout (default 5), edns_buffer_size (default 4096, false to disable EDNS).

iter.classify(resp, qtype, qname, dnssec_mode)

Classify a decoded DNS response. Returns kind, info where kind is one of:

qname is the normalized (lowercased, trailing-dot) owner name used to match answer and CNAME records — it must be passed for the answer/cname classifications to work. dnssec_mode (boolean, default false) opts into collecting the response's DNSSEC records (RRSIG, DS, DNSKEY, NSEC, NSEC3) into info.dnssec.

local qname = dns_name.normalize("example.com")
local kind, info = iter.classify(resp, 1, qname)  -- 1 = TYPE.A
if kind == "referral" then
    print("delegated to zone:", info.zone)
    for _, ns in ipairs(info.ns) do
        local g = info.glue[ns.name]
        print("  ", ns.name, g and g.ipv4 or "(no glue)")
    end
end

iter.extract_referral(resp)

Parse referral details from a response. Returns zone, ns, glue where ns is a list of {name = "..."} tables and glue maps NS names to {ipv4 = "...", ipv6 = "..."}.

iter.trace(qname, qtype, opts)

Walk the full DNS hierarchy from root servers to authoritative answer. Returns a list of step tables, each with:

• server / server_name — IP and name of the server queried

• zone — zone this server is authoritative for

• qname / qtype — what was queried

• kind / info — classification (from classify())

• response — full decoded DNS message

• rtt_ms — round-trip time in milliseconds

local iter = require("dns.iter")
local steps, err = iter.trace("example.com", "A")
if steps then
    for i, step in ipairs(steps) do
        print(i, step.server, step.kind, step.zone, step.rtt_ms .. "ms")
    end
end

Options: timeout (default 5), max_referrals (default 30), max_cnames (default 10), max_glue_depth (default 2), root_servers (override), edns_buffer_size (default 4096), dnssec (default false).

When dnssec = true, the trace sets the EDNS DO (DNSSEC OK) bit on all queries and performs chain-of-trust validation at each step. Each returned step gains two additional fields:

• dnssec_status — "secure", "insecure", "bogus", or "indeterminate"

• dnssec_detail — human-readable explanation (e.g. "answer validated", "no DS records in referral")

Validation starts from the IANA root trust anchor (KSK 20326) and follows DS → DNSKEY → RRSIG chains down through each delegation. At each new zone, the resolver fetches the zone's DNSKEY RRset and validates it against the parent's DS records. Answer RRsets are then verified against the zone's validated keys. Wildcard-expanded records are handled correctly per RFC 4035 §5.3.4 (label count comparison and owner name reconstruction).

CNAME responses are DNSSEC-validated before following: the CNAME RRset's RRSIG is verified against the zone's validated keys. If validation fails, the CNAME is marked "bogus" and the trace aborts (the forged CNAME is not followed). For nodata/nxdomain responses, the SOA RRSIG in the authority section is cryptographically validated.

Unsigned answers from signed zones (zones with validated DNSKEY RRsets) are marked "bogus", not "insecure" — only zones without a DS chain are considered insecure.

CNAME chains restart resolution from root for the CNAME target. Glueless delegations (NS without A/AAAA glue) are resolved via a recursive sub-trace for the NS name's A record. The max_glue_depth option limits nesting depth to prevent infinite loops (default 2). The sub-trace steps are stored in info.glue_trace on the referral step that triggered them. Sub-traces inherit the parent's DNSSEC validation state.

Supported algorithms

DS digest types: SHA-1 (1), SHA-256 (2), SHA-384 (4).

Zones signed with unsupported algorithms are reported as indeterminate rather than insecure, so they can be distinguished from unsigned zones.

Validation coverage

Positive responses (answer, CNAME):

• Chain-of-trust from IANA root KSK (key tag 20326) through DS → DNSKEY → RRSIG at each delegation

• Answer RRset RRSIG verified against validated zone keys

• CNAME RRset RRSIG verified before following; bogus CNAME aborts trace

• Wildcard expansion detected via RRSIG label count (RFC 4035 §5.3.4)

• Unsigned answers from signed zones marked "bogus"

Negative responses (NXDOMAIN, NODATA):

• NSEC zones — full validation: NSEC RRSIGs verified, plus coverage checks proving the queried name doesn't exist (NXDOMAIN) or the queried type doesn't exist for that name (NODATA). NXDOMAIN also verifies no covering wildcard exists. Coverage failure → "bogus".

• NSEC3 zones — partial validation: SOA RRSIG and NSEC3 RRSIGs are both verified, but NSEC3 hash coverage is not checked. Both must pass for "secure".

• No denial records — SOA RRSIG only (fallback).

Not implemented

• NSEC3 hash coverage verification (RFC 5155 iterated hash checks)

• NSEC3 closest encloser proof via hashed owner names

• NSEC3PARAM record type (type 51)

• NSEC3 opt-out flag handling

Module API

• dnssec.ROOT_DS — IANA root KSK trust anchor (key tag 20326) as a proper RR structure with name, type, class, ttl, rdata fields

• dnssec.compute_key_tag(rdata_wire) — RFC 4034 Appendix B key tag

• dnssec.verify_rrsig(rrsig_rr, rrset, dnskey_rr) — verify a single RRSIG against an RRset using the given DNSKEY

• dnssec.verify_ds(ds_rr, dnskey_rr) — verify a DS digest matches a DNSKEY

• dnssec.validate_rrset(rrset, rrsig_list, dnskey_list) — find a valid RRSIG chain for an RRset; returns ok, err, had_unsupported

• dnssec.validate_dnskey_rrset(dnskey_records, dnskey_rrsigs, ds_records) — full DS → KSK → zone DNSKEY validation; returns ok, err, had_unsupported

• dnssec.validate_nsec_nodata(nsec_records, qname, qtype) — verify NSEC records prove NODATA (name exists, type absent); returns ok, err

• dnssec.validate_nsec_nxdomain(nsec_records, qname) — verify NSEC records prove NXDOMAIN (name covered by range, wildcard covered); returns ok, err