lilpacks/recall

1.1 Config file location

RECALL reads config JSON from:

1. RECALL_CONFIG_FILE environment variable, if set

2. /etc/recall/config.json otherwise

1.2 Minimal config

{
  "ip": "127.0.0.1",
  "port": 5353
}

This starts RECALL on port 5353, performing full iterative resolution from IANA root servers on cache misses and caching results in memory.

To enable persistent caching with MNEME (embedded database):

{
  "ip": "127.0.0.1",
  "port": 5353,
  "cache": { "mneme": true }
}

The MNEME database file defaults to /var/cache/recall/dns.mneme.

1.3 Test query

dig @127.0.0.1 -p 5353 example.com A

2.1 Top-level config

2.2 Cache config (cache)

Cache config is passed to dns.cache.new(). Backend priority: MNEME (if mneme = true) > in-memory.

2.3 Forward zones config (forward_zones)

Map of zone names to zone configuration objects:

{
  "forward_zones": {
    "internal.corp.": {
      "servers": ["10.0.0.10", "10.0.0.11"],
      "timeout": 3
    },
    "dev.example.com.": {
      "servers": ["10.120.0.10:5353"],
      "timeout": 2,
      "retries": 3
    },
    "secure.corp.": {
      "servers": ["1.1.1.1", "1.0.0.1"],
      "use_tls": true,
      "server_name": "cloudflare-dns.com"
    }
  }
}

Per-zone fields:

Server entries support port specification as "host:port" strings or {"host": "10.120.0.10", "port": 5353} tables. When use_tls is enabled, servers default to port 853 instead of 53.

Forward zone queries use dns.client with RD=1 (recursive requests to the configured forwarders), not iterative resolution. Each zone gets its own dns.client instance sharing the global cache. Zone matching is longest-match: if both corp. and dev.corp. are configured, queries for app.dev.corp. route to the dev.corp. forwarder.

{
  "forward_zones": {
    ".": {
      "servers": ["1.1.1.1", "1.0.0.1"],
      "use_tls": true,
      "server_name": "cloudflare-dns.com"
    }
  }
}

2.4 Scripting config (scripting)

{
  "scripting": {
    "enabled": true,
    "scripts_dir": "/etc/recall/scripts",
    "subdomains": ["dyn.example.com."],
    "cache_ttl": 60,
    "script_cache_ttl": 300
  }
}

Scripting is independent of the cache backend — it works with both the in-memory cache and MNEME.

See section 7 for the scripting API.

2.5 Rate limit config (rate_limit)

{
  "rate_limit": {
    "enabled": true,
    "queries_per_second": 50,
    "burst": 100,
    "cleanup_interval": 15,
    "max_buckets": 50000
  }
}

The per-IP token bucket governs UDP queries and per-query throughput on established TCP connections. TCP connections are additionally limited structurally by max_tcp_connections (global) and max_tcp_per_ip (per source IP). See section 5 for details.

Auto-compaction

MNEME's copy-on-write B-tree accumulates free pages as DNS records expire and get replaced. RECALL periodically checks the free-page ratio (free_pages / page_count) and compacts when it exceeds compact_threshold (default 0.5). Compaction rewrites the database to a new file, reclaiming space, then atomically replaces the original. The minimum interval between compaction checks is compact_interval seconds (default 3600).

4.1 Process model

Manager forks a single listener process. The listener runs inside lev.run(), using epoll-based async I/O with Lua coroutines for concurrency. UDP queries are received in a main loop and each query spawns a detached coroutine for processing. TCP connections are accepted in a dedicated coroutine and each accepted connection spawns its own handler coroutine. All upstream DNS queries (iterative resolution, forward zones) use LEV transports (dns.transport.udp, dns.transport.tcp). MNEME caching is embedded — no network I/O for cache operations.

4.2 Query validation

The handler validates each incoming query before resolution. Checks run in order:

1. Decode failure → silently dropped (no response)

2. Not a query (QR=1) → silently dropped

3. Non-standard opcode (OPCODE != 0) → NOTIMP

4. EDNS version > 0 → BADVERS (extended rcode via OPT record)

5. Empty question section → FORMERR

6. Non-IN class (qclass != 1) → REFUSED

7. Invalid domain name → FORMERR

4.3 Query routing

Queries that pass validation are routed through resolution paths in order:

1. Scripted subdomains — if qname matches a configured scripting subdomain

2. Forward zones — if qname matches a configured forward zone (longest match)

3. RFC1918 reverse zone guard — if qname falls under a private reverse zone (10.in-addr.arpa., 168.192.in-addr.arpa., 16-31.172.in-addr.arpa.), return NXDOMAIN with a synthetic SOA immediately instead of querying public root servers

4. Iterative resolution — full walk from IANA root servers via dns.iter.trace()

The first path that produces a result (or a definitive negative like NXDOMAIN) is used. Scripted responses that return nil fall through to forward zones, then to the RFC1918 guard, then to iterative resolution. To resolve private reverse lookups against an internal DNS server, configure a forward zone for the relevant .in-addr.arpa. zone — forward zones (step 2) take priority over the guard (step 3).

5.1 UDP rate limiting

RECALL uses a token bucket algorithm to rate-limit UDP queries per source IP. Each source IP gets an independent bucket with a configurable refill rate (queries_per_second, default 50) and capacity (burst, default 100). Packets that arrive when the bucket is empty are silently dropped — no REFUSED or SERVFAIL response is sent.

Rate limiting is checked before decoding the DNS message, minimizing CPU cost for dropped packets.

Stale buckets (idle longer than burst / queries_per_second seconds) are garbage-collected every cleanup_interval seconds (default 15).

The same per-IP token bucket is also consulted for each query received on an established TCP connection; a query that finds the bucket empty terminates the connection.

5.2 TCP connection limits

TCP connections are structurally limited (independently of the token bucket):

• Global limit (max_tcp_connections, default 100): maximum total concurrent TCP connections. New connections are closed immediately when at capacity.

• Per-IP limit (max_tcp_per_ip, default 10): maximum concurrent TCP connections from a single source IP. New connections from IPs at the limit are closed immediately.

6.1 Iterative resolver (recall.resolver)

The resolver wraps dns.iter.trace() with dns.cache for positive and negative caching.

Resolution flow:

1. Check positive cache → return on hit

2. Check negative cache → return NXDOMAIN/NODATA on hit

3. Call iter.trace(qname, qtype) → walk from root servers to authoritative answer

4. Process trace result:

   • answer: collect CNAME chain from intermediate steps, prepend to answer records, cache combined result, return

   • nxdomain: cache negative with SOA, return nil, "NXDOMAIN", soa

   • nodata: cache negative with SOA, return nil, "NODATA", soa

   • error: return nil, error_description

CNAME chain handling: when iter.trace() follows CNAMEs (restarting from root for each target), the resolver collects CNAME records from intermediate trace steps and prepends them to the final answer. Clients receive the full CNAME chain in the answer section, matching standard resolver behavior.

6.2 DNSSEC validation

When dnssec is enabled, the iterative resolver performs chain-of-trust validation from the IANA root trust anchor through each delegation to the authoritative answer. At each step, DS records from referrals are collected, DNSKEY records are fetched from zone apex servers, and RRSIG signatures are verified cryptographically.

Each resolution step receives a validation status:

Supported DNSSEC algorithms: RSA/SHA-256 (8), RSA/SHA-512 (10), ECDSA P-256 (13), ECDSA P-384 (14), ED25519 (15).

When dnssec_reject_bogus is also enabled, queries that resolve with a bogus DNSSEC status return SERVFAIL instead of the answer. This prevents clients from receiving responses that fail signature verification. Unsigned zones (insecure) are passed through normally.

DNSSEC validation adds one extra DNSKEY query per delegation level (root, TLD, authoritative zone). The validation status is logged at debug level (or warn level for bogus results).

6.3 Forward zone resolution (recall.forward)

Forward zones use dns.client instances configured with the zone's upstream servers. Queries are sent with RD=1 (recursion desired). The dns.client provides retry, failover, CNAME following, and integrated caching through the shared cache instance.

Zone matching is longest-match by label count. A query for app.dev.corp. matches dev.corp. before corp. if both are configured.

6.4 Response construction

All responses set:

• QR=1 (response), RA=1 (recursion available), AA=0 (not authoritative)

• RD echoed from query

• Question section echoed from query

• EDNS OPT echoed when client sent EDNS

Response types:

6.5 UDP truncation

When a UDP response exceeds the client's advertised EDNS buffer size (or 512 bytes without EDNS), the response is re-encoded with TC=1 set and the answer, authority, and additional sections stripped. The client is expected to retry over TCP.

7.1 Storing scripts

Scripts live in scripting.scripts_dir (default /etc/recall/scripts). Each configured subdomain loads from <scripts_dir>/<subdomain>.lua, where <subdomain> is the normalized name with its trailing dot stripped. For example, the subdomain dyn.example.com. loads from /etc/recall/scripts/dyn.example.com.lua.

mkdir -p /etc/recall/scripts
cat << EOF > /etc/recall/scripts/dyn.example.com.lua
if qtype ~= dns.TYPE.A then return nil end
local hosts = { "10.0.1.1", "10.0.1.2", "10.0.1.3" }
local idx = (os.time() % #hosts) + 1
return { dns.a_record(qname, hosts[idx], 30) }
EOF

7.2 Script environment

Scripts execute in a sandboxed environment with setfenv. Available globals:

Query context:

DNS record constructors:

All TTL arguments default to 60 seconds when omitted. The dns.TYPE table is available for type comparisons (dns.TYPE.A, dns.TYPE.AAAA, etc.).

Safe builtins:

• type, tostring, tonumber, pairs, ipairs, select, unpack, pcall, error

• string — byte, char, find, format, gmatch, gsub, len, lower, match, rep, sub, upper

• table — concat, insert, remove, sort

• math — abs, ceil, floor, max, min, random

• os — time, clock

Not available: io, os.execute, require, dofile, loadfile, loadstring, debug, coroutine.

7.3 Script return value

Scripts must return an array of record tables (as produced by the dns.*_record() constructors), or nil to fall through to forward zone / iterative resolution.

-- Return A records
return { dns.a_record(qname, "10.0.1.1", 60) }

-- Return nil to fall through
if qtype ~= dns.TYPE.A then return nil end

7.4 Script caching

Compiled script functions are cached in memory for script_cache_ttl seconds (default 300). After expiry, the script source is re-read from its file on disk and recompiled. This allows hot-reloading scripts without restarting RECALL.

Script-generated records are cached in the DNS cache for cache_ttl seconds (default 60).

7.5 Example scripts

Round-robin A records:

if qtype ~= dns.TYPE.A then return nil end
local hosts = { "10.0.1.1", "10.0.1.2", "10.0.1.3" }
local idx = (os.time() % #hosts) + 1
return { dns.a_record(qname, hosts[idx], 30) }

Wildcard subdomain routing:

if qtype ~= dns.TYPE.A then return nil end
local label = qname:match("^([^.]+)%.")
if label == "web" then
    return { dns.a_record(qname, "10.0.2.1", 60) }
elseif label == "api" then
    return { dns.a_record(qname, "10.0.2.2", 60) }
end
return nil

TXT record with timestamp:

if qtype ~= dns.TYPE.TXT then return nil end
return { dns.txt_record(qname, "generated at " .. os.time(), 10) }