Point an OpenWrt router at AdminKit Protective DNS

What this package does

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 four subcommands:

• adminkit-dns-sync render-dnsmasq SITE_SLUG DOH_URL RESOLVER_IP [RESOLVER_IP ...] writes a dnsmasq upstream stanza (no-resolv plus server=<ip> lines) pointing LAN DNS at the configured resolver IPs, with a comment carrying the AdminKit DoH URL for routers or proxies that support DNS-over-HTTPS directly.
• adminkit-dns-sync render-metadata SITE_SLUG LEASES_FILE EVENTS_FILE reads dnsmasq’s DHCP lease file and a local block-event log, and emits per-device connection/block counts for the trailing 24 hours plus the most recently blocked domain.
• adminkit-dns-sync sync reads /etc/config/adminkit-dns via uci, writes both the dnsmasq conf and the metadata file, and reloads dnsmasq.
• adminkit-dns-sync sync-loop calls sync on a loop, every poll_interval seconds — this is what /etc/init.d/adminkit-dns (a procd service, disabled by default) runs when option enabled '1' is set.

Everything here is POSIX sh, BusyBox-ash compatible, with no third-party code and no network library — it depends only on dnsmasq, plus the sha256sum and awk applets BusyBox ships by default.

The privacy design: hashed device IDs, no raw MAC or payload

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 (schema: schema/metadata.schema.json) never includes DNS query payload or a raw per-query client IP either, only aggregate counts and the most recently blocked domain. 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.

What’s buildable today vs. what’s actually live

The package builds, lints and runs correctly in this environment’s tests today (there is no OpenWrt SDK/buildroot available here, so make package/adminkit-dns/compile itself has not been exercised against a real router, but the generated config and metadata logic are fully tested). What is not available yet is AdminKit’s real L1 Protective DNS resolver: the example configuration below uses RFC 5737 TEST-NET-3 addresses (203.0.113.10, 203.0.113.11) as explicit placeholders, because AdminKit has not published real resolver IPs. Set this package up to have the plumbing ready; don’t expect it to actually filter malicious DNS until AdminKit’s resolvers ship.

Build

Not yet published to an OpenWrt feed. Build against an OpenWrt SDK/buildroot:

# from an OpenWrt buildroot checkout
cp -r integrations/openwrt package/network/services/adminkit-dns
make package/adminkit-dns/compile

Configure (/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 AdminKit's real 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 metadata_path '/tmp/adminkit/metadata.json'

Set option enabled '1' once you have real resolver IPs to point at, then let /etc/init.d/adminkit-dns start the sync-loop. events_path expects a TSV log of <epoch_ts>\t<mac>\t<qname>\t<action> lines (action is blocked or allowed); the package does not generate this log itself yet, and render-metadata works correctly with an empty or missing file, reporting zero connections in the meantime.

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
integrations/openwrt/files/usr/bin/adminkit-dns-sync render-dnsmasq home \
  https://dns.adminkit.net/dns-query/site/home 203.0.113.10 203.0.113.11

# writes metadata JSON built from fixture lease/event files
integrations/openwrt/files/usr/bin/adminkit-dns-sync render-metadata home \
  integrations/openwrt/tests/fixtures/dhcp.leases \
  integrations/openwrt/tests/fixtures/events.tsv

This is exactly how the package’s own test suite validates it without a real OpenWrt buildroot or device.

Where AdminKit fits

This package is the OpenWrt half of AdminKit’s planned Protective DNS product (L1) — a managed resolver blocking malware and C2 domains per device, deployed by changing your router’s DNS. It is in early access and not live yet; this package lets small offices and technical home users running OpenWrt prepare the router side ahead of general availability. See our small office solutions page for the fuller picture of what’s free now versus planned.