@bobfrankston/dnslookup

dnslookup

Raw DNS query CLI and Node.js library that builds and sends UDP packets directly per RFC 1035. No dependencies beyond Node.js. Useful for debugging DNS servers (e.g., Unifi, Pi-hole) by seeing exactly what's happening at the protocol level.

By design this is a thin wrapper over the wire protocol: no caching, no retries, no fallback chains. v4 transport only (the DNS server endpoint must be IPv4), but AAAA records are fully supported.

Install

npm install -g @bobfrankston/dnslookup

Usage

dnslookup <hostname> [hostname2 ...] [options]

Options

Flag	Description
-t <type>	Record type: A, NS, CNAME, SOA, PTR, MX, TXT, AAAA, ANY (default: A)
-s <server>	DNS server IP (default: system DNS)
-x	Hex dump of query and response packets
-v	Verbose: show authority and additional sections
-detail	Force detailed output (default for single name)
-table	Force table output (default for multiple names)
--timeout <ms>	Query timeout in ms (default: 5000)

Single name (detail mode)

$ dnslookup rmf39.aaz.lt

── DNS Query ──
  Server:   172.20.0.1:53
  Name:     rmf39.aaz.lt
  Type:     A (1)

  RTT:      9.67ms
  Response: 46 bytes

── Response Header ──
  ID:       0x37bf
  Flags:    0x8180 [QR RD RA]
  Status:   NoError
  Counts:   Questions=1 Answers=1 Authority=0 Additional=0

── Answers (1) ──
  rmf39.aaz.lt                   43m28s     A      108.26.220.160

── Result ──
  A   108.26.220.160

Multiple names (table mode)

$ dnslookup rmf39 rmf39.aaz.lt example.com google.com

Name                 Server      Type       RTT       TTL  Status
rmf39                172.20.0.1  A       10.1ms         -  NXDOMAIN
rmf39.aaz.lt         172.20.0.1  A        1.6ms    43m36s  Found       108.26.220.160
example.com          172.20.0.1  A       25.6ms      5m0s  Found       104.18.26.120
                                                                       104.18.27.120
google.com           172.20.0.1  A       20.1ms     3m10s  Found       142.250.217.14

Compare DNS servers

dnslookup myhost -s 172.20.0.1
dnslookup myhost -s 8.8.8.8
dnslookup myhost -s 10.255.255.254   # WSL DNS proxy

Hex dump for packet inspection

dnslookup example.com -x

API

Install as a regular dependency and import:

npm install @bobfrankston/dnslookup

import { lookup, lookupx, runQuery, QType } from "@bobfrankston/dnslookup";

lookup(hostname, options?) → Promise<string[]>

Simplest case. Returns an array of address strings (DNS may legitimately return multiple). Throws on transport failure or DNS error (NXDOMAIN, ServerFailure, …).

await lookup("google.com");                              // ["142.250.190.238"]
await lookup("google.com", { type: "AAAA" });            // ["2607:f8b0:..."]
await lookup("example.com", { server: "8.8.8.8", timeout: 2000 });

lookupx(hostname, options?) → Promise<LookupExtended>

Extended form: returns the same address list plus the diagnostic detail you'd see in the CLI's detail view (server, RTT, response size, header ID/flags/status, section counts, full record arrays). Throws only on transport failure; DNS errors come back as status (e.g. "NXDOMAIN") with addresses: [].

const r = await lookupx("google.com");
// r.addresses     -> ["142.250.190.238"]
// r.server        -> "172.20.0.1"
// r.type          -> "A"
// r.rtt           -> 17.28
// r.flagNames     -> ["QR", "RD", "RA"]
// r.status        -> "NoError"
// r.counts        -> { questions: 1, answers: 1, authority: 0, additional: 1 }
// r.answers       -> [{ name, type, typeName, ttl, rdata, rdataRaw, ... }]

runQuery(hostname, server, qtype, timeout) → Promise<QueryResult>

Lowest-level entry point. Returns the full parsed response (header, answers, authority, additional, RTT, raw query/response packets). Does not throw on DNS errors — failures are reported via the status and error fields. Use QType.A / QType.AAAA / etc. for qtype.

Options (LookupOptions)

Field	Type	Default	Notes
server	string	first system resolver (dns.getServers()[0])	Must be an IPv4 address
type	"A" | "AAAA" | "NS" | "CNAME" | "SOA" | "PTR" | "MX" | "TXT" | "ANY"	"A"	Same set as the -t CLI flag
timeout	number (ms)	5000

Exports

lookup, lookupx, runQuery, QType, QTypeName, and the types LookupOptions, LookupExtended, QueryResult, DnsRecord, DnsHeader.

How it works

• Constructs raw DNS query packets per RFC 1035
• Sends via UDP to port 53 using node:dgram
• Parses response including DNS name compression (pointer offsets)
• Supports record types: A, AAAA, MX, CNAME, NS, SOA, TXT, PTR
• Zero runtime dependencies

License

MIT