Point an OpenWrt router at AdminKit Protective DNS
AdminKit's adminkit-dns OpenWrt package configures dnsmasq to forward LAN DNS to AdminKit's L1 Protective DNS resolvers and publishes a metadata-only snapshot of per-device connection and block activity, with device IDs hashed rather than raw MAC addresses. It is real, tested code that Netbase provides with a Protective DNS engagement.
By AdminKit team, Netbase JSC · Updated
Key takeaways
adminkit-dnsis a small OpenWrt package. It points the router’sdnsmasqat the Protective DNS resolvers from your engagement; the filtering happens in those resolvers, not on the router.- It also writes a metadata-only JSON snapshot per device: counts of DNS events and blocks over 24 hours, with the device identified by a truncated SHA-256 hash, never the raw MAC or IP.
- Netbase provides the source with a Protective DNS engagement. It is not in an OpenWrt feed, so you build it with the OpenWrt buildroot.
- Its render subcommands are plain shell functions you can run on any POSIX machine against sample files, which is how its own tests check it.
What does the adminkit-dns package do?
adminkit-dns is an OpenWrt package, not a standalone resolver — it configures dnsmasq (already a dependency of OpenWrt’s base network setup) and exposes a adminkit-dns-sync shell script with five subcommands:
| Subcommand | Reads | Writes |
|---|---|---|
render-dnsmasq SITE_SLUG DOH_URL RESOLVER_IP... | Its arguments only | A dnsmasq upstream stanza: no-resolv, one server= line per resolver, a comment with the site’s DoH URL |
collect-events LEASES_FILE DNSMASQ_LOG_FILE | dnsmasq’s query log and DHCP lease file | One tab-separated event line per classified query |
render-metadata SITE_SLUG LEASES_FILE EVENTS_FILE | The lease file and the event log | Per-device JSON: 24-hour event and block counts, last seen, last blocked name |
sync | /etc/config/adminkit-dns via uci | Runs the three steps above, then reloads dnsmasq |
sync-loop | The same config | Calls sync every poll_interval seconds |
sync-loop is what /etc/init.d/adminkit-dns (a procd service, disabled by default) runs when option enabled '1' is set. The DoH comment is there for routers or local proxies that support DNS-over-HTTPS (RFC 8484) directly; dnsmasq itself forwards plain DNS to the server= addresses.
Everything here is POSIX sh, BusyBox-ash compatible, with no third-party code and no network library — it depends only on dnsmasq, plus standard applets such as sha256sum and awk that BusyBox ships by default.
How does data flow from dnsmasq to the metadata file?
Each sync run is one pass through the same pipeline. Nothing in it sends DNS payloads anywhere; the output is a local JSON file.
LAN device --DNS query--> dnsmasq on the router --forwards--> Protective DNS resolver
|
| query log (logqueries on)
v
collect-events + /tmp/dhcp.leases (IP -> MAC)
|
v
events.tsv <epoch_ts> TAB <mac> TAB <qname> TAB <action>
|
v
render-metadata -> metadata.json (hashed device_id, counts only)
sync remembers how much of the dnsmasq log it has already read (in a small .offset file next to the event log), so repeated runs only append new events. If the log shrinks, for example after rotation, it starts again from the beginning of the new file.
How are blocked and allowed queries told apart?
collect-events looks at each query[TYPE] name from IP line in the dnsmasq log and at the single line that follows it. The rules come straight from the script:
| Line after the query | Meaning in dnsmasq | Recorded as |
|---|---|---|
config <name> is ... | Answered from local configuration, such as a blocklist entry | blocked |
/etc/hosts <name> is ... | Answered from the hosts file (a sinkhole entry) | blocked |
forwarded <name> to ... | Sent upstream to the Protective DNS resolver | allowed |
cached <name> is ... | Served from the cache of an earlier forwarded answer | allowed |
| Anything else, or a client IP with no DHCP lease | Ambiguous | Dropped, not guessed |
A short log excerpt and the events it produces look like this (illustrative and simplified; names and addresses are placeholders, and OpenWrt’s logqueries option also adds a query serial number and the client address to each line, which the matching tolerates):
dnsmasq[1234]: query[A] blocked.example from 192.168.1.50
dnsmasq[1234]: config blocked.example is 0.0.0.0
dnsmasq[1234]: query[A] www.example.com from 192.168.1.50
dnsmasq[1234]: forwarded www.example.com to 203.0.113.10
# events.tsv
1793010600 aa:bb:cc:dd:ee:01 blocked.example blocked
1793010600 aa:bb:cc:dd:ee:01 www.example.com allowed
The timestamp is the time of the collection run, not a time parsed from the syslog line, because BusyBox syslog lines carry no year. Precision is therefore bounded by poll_interval.
What does the privacy design keep out of the metadata?
render-metadata’s device_id field is sha256(site_slug + ":" + mac) truncated to 16 hex characters — not the raw MAC address or IP. The metadata it produces is a small JSON object of per-device connection/block counts and the most recently blocked domain; it never includes DNS query payload or a raw per-query client IP. This mirrors the same metadata-only design used by the Home Assistant add-on, which this package is the router-side counterpart to — useful if your router doesn’t run Home Assistant OS or doesn’t support DNS-over-HTTPS natively.
This is the output render-metadata produces from the package’s own test fixtures (two synthetic devices, a fixed clock):
{
"generated_at": "2026-10-26T10:31:00Z",
"site_slug": "home",
"devices": [
{
"device_id": "9d19fa25dc34b6b3",
"hostname": "living-room-camera",
"connections_24h": 2,
"blocked_24h": 2,
"last_seen": "2026-10-26T10:30:00Z",
"last_blocked_qname": "telemetry.vendor-example.com"
},
{
"device_id": "f374ed2a43a47da4",
"hostname": "kitchen-hub",
"connections_24h": 0,
"blocked_24h": 0,
"last_seen": "2026-10-23T09:00:00Z",
"last_blocked_qname": null
}
]
}
connections_24h counts the device’s logged DNS events in the trailing 24 hours, and blocked_24h the subset marked blocked. The hostname is whatever the device reported in its DHCP request, so if your device names themselves are sensitive, rename them in the router before enabling the package.
What has been tested, and what does it depend on?
The package’s own test suite lints its build Makefile, runs render-dnsmasq and checks the output is well-formed dnsmasq directives, runs collect-events against a sample dnsmasq log (including malformed and unmatched lines), and validates render-metadata output against a JSON schema that rejects raw MAC or IP values. There is no OpenWrt SDK/buildroot in that test environment, so make package/adminkit-dns/compile itself has not been exercised against a real router. The filtering itself happens in the resolver the package forwards to, an AdminKit L1 Protective DNS resolver that Netbase sets up and runs for your network as part of the engagement. The example configuration below uses RFC 5737 TEST-NET-3 addresses (203.0.113.10, 203.0.113.11) as explicit placeholders; replace them with the resolver addresses from your engagement — the package forwards DNS but does not filter anything on its own.
How do you build it?
Netbase provides the package’s source as part of a Protective DNS engagement (talk to our team). The package is not in an OpenWrt feed, so build it against an OpenWrt SDK/buildroot, as described in OpenWrt’s buildroot guide:
# from an OpenWrt buildroot checkout
cp -r adminkit-dns package/network/services/adminkit-dns
make package/adminkit-dns/compile
How do you configure it?
The package reads /etc/config/adminkit-dns:
config adminkit-dns 'main'
option enabled '0'
option api_url 'https://api.adminkit.net'
option api_key ''
option site_slug 'home'
list resolver '203.0.113.10' # placeholder (RFC 5737 TEST-NET-3) — set your engagement's resolver IPs
list resolver '203.0.113.11'
option poll_interval '300'
option leases_path '/tmp/dhcp.leases'
option events_path '/tmp/adminkit/events.tsv'
option dnsmasq_conf_path '/etc/dnsmasq.d/adminkit.conf'
option dnsmasq_log_path '/tmp/adminkit/dnsmasq-query.log'
option metadata_path '/tmp/adminkit/metadata.json'
For block events to appear, dnsmasq has to log its queries to the file named in dnsmasq_log_path. On OpenWrt that is two options in the dnsmasq section of /etc/config/dhcp (OpenWrt’s DHCP and DNS reference documents both; they map to dnsmasq’s --log-queries and --log-facility in the dnsmasq manual):
config dnsmasq
option logqueries '1'
option logfacility '/tmp/adminkit/dnsmasq-query.log'
Set option enabled '1' once the real resolver IPs are in place, then let /etc/init.d/adminkit-dns start the sync-loop. events_path is a TSV log of <epoch_ts>\t<mac>\t<qname>\t<action> lines (action is blocked or allowed) that sync appends to through collect-events; render-metadata works correctly with an empty or missing file, reporting zero connections. The dnsmasq manual explains why a path works in logfacility: a facility value containing a / is treated as a file name, and dnsmasq writes its log there instead of to syslog.
Will dnsmasq actually read the generated file?
Only if the file sits in a directory dnsmasq loads. dnsmasq reads extra configuration files from its --conf-dir, and OpenWrt’s DHCP and DNS reference lists the default confdir for each dnsmasq instance as /tmp/dnsmasq<instance>.d. The package’s default dnsmasq_conf_path is /etc/dnsmasq.d/adminkit.conf, which is outside that default. Before you enable the service, do one of two things:
| Option | Change | Watch out for |
|---|---|---|
| Move the generated file | Set dnsmasq_conf_path to a file inside the conf-dir your dnsmasq instance uses | The instance-specific directory name differs between routers, so check yours rather than copying a path |
| Move the conf-dir | Set option confdir '/etc/dnsmasq.d' in the dnsmasq section of /etc/config/dhcp | Any other package that drops files into the default directory stops being read |
Then restart dnsmasq and check its startup messages with logread for the upstream servers it is using. If they are still your ISP’s resolvers, dnsmasq has not picked up the no-resolv and server= lines, and LAN queries are not reaching Protective DNS.
To back the change out, set option enabled '0', delete the generated dnsmasq file and restart dnsmasq. The package does not remove that file for you, and as long as it is loaded, its no-resolv line keeps dnsmasq away from the upstream servers in its usual resolv file.
Can you try it without a router?
Because render-dnsmasq and render-metadata are pure functions of their arguments, you can run them directly against fixture files on any POSIX shell:
# writes a dnsmasq upstream stanza to stdout
adminkit-dns-sync render-dnsmasq home \
https://dns.adminkit.net/dns-query/site/home 203.0.113.10 203.0.113.11
# turns a sample dnsmasq query log into event lines
adminkit-dns-sync collect-events example-dhcp.leases example-dnsmasq.log
# writes metadata JSON built from fixture lease/event files
adminkit-dns-sync render-metadata home \
example-dhcp.leases \
example-events.tsv
The first command prints exactly this:
# Managed by adminkit-dns-sync — do not edit by hand (see /etc/config/adminkit-dns).
# AdminKit L1 Protective DNS (site: home).
# Optional DoH, if your router/a local DoH proxy supports it: https://dns.adminkit.net/dns-query/site/home
no-resolv
server=203.0.113.10
server=203.0.113.11
no-resolv tells dnsmasq to ignore the upstream servers it would otherwise read from /etc/resolv.conf, so the server= lines are the only place it forwards to. This is exactly how the package’s own test suite validates it without a real OpenWrt buildroot or device.
Where does AdminKit fit?
This package is the OpenWrt half of AdminKit Protective DNS (L1) — a filtering resolver blocking malware and C2 domains per device, deployed by changing your router’s DNS, which Netbase builds and runs for your network as a custom engagement. For small offices and technical home users running OpenWrt, it is the router side of that setup — talk to our team to scope one. See our small office solutions page for the free checks and services for a small office.
Once your router is actually forwarding LAN DNS to AdminKit’s resolvers, confirm your devices are genuinely using them rather than a resolver leaking around the new configuration — AdminKit’s DNS resolver test page shows the nslookup check for this — the same check applies whether the resolver change came from this package or from manually editing dnsmasq.conf. Devices with a hard-coded resolver, or browsers with their own DNS-over-HTTPS setting, can bypass the router entirely, so run the check from more than one device. This guide is part of AdminKit’s DNS cluster of DNS guides and tools.
This guide is general information, not a security audit of your specific network — see our disclaimer for what AdminKit's guidance does and does not commit to.
Frequently asked questions
Is this package in an OpenWrt feed I can opkg install?
No. Netbase provides the package's source as part of a Protective DNS engagement, and you build it against an OpenWrt SDK/buildroot. Talk to our team at /contact/.
Does device_id expose my devices' MAC addresses?
No. device_id is sha256(site_slug + ":" + mac) truncated to 16 hex characters — a stable, non-reversible identifier, never the raw MAC address or IP.
Where do the resolver IPs come from?
From your Protective DNS engagement: Netbase sets up and runs the L1 filtering resolver for your network and gives you its addresses. The package renders correct dnsmasq config and metadata JSON in its own tests; the example config uses RFC 5737 TEST-NET-3 placeholder addresses because filtering only happens once dnsmasq forwards to a real Protective DNS resolver.
Where does the block-event log (events_path) come from?
The package builds it from dnsmasq's own query log. With query logging turned on (option logqueries '1' and a logfacility file in /etc/config/dhcp), the collect-events subcommand reads that log, matches each client IP to a MAC through the DHCP lease file, and appends one line per query it can classify: answered locally is 'blocked', forwarded or served from cache is 'allowed'. Lines it cannot classify are dropped, not guessed. render-metadata also works with an empty or missing events file, reporting zero connections.
What if I don't want to build against a real OpenWrt SDK?
The package's shell scripts (adminkit-dns-sync) have no uci or OpenWrt-specific dependency for their render-dnsmasq/render-metadata subcommands — you can exercise them directly with fixture lease/event files on any POSIX system with sha256sum and awk, which is exactly how the package's own tests validate it.
Related tools
Want AdminKit to watch this for you?
Free checks tell you the state today. Protective DNS and monitoring tell you when it changes.
Talk to an expert
Huy Nguyen (David), Founder & CEO, Netbase JSC
Ask whether this fix applies to your setup, or get a second pair of eyes on your DNS and mail records.