Test DNS Answers, Not Just DNS Server Availability

Define policy checks with stable fixtures

Create or choose a domain you control for the allowed test. Add a second controlled test name to the block policy. Document the expected A and AAAA behavior and the client group to which the probing host belongs. An arbitrary advertising domain can disappear or change behavior, making a monitor fail for a reason unrelated to your resolver.

The allowed test proves that resolution still works. The blocked test proves that the configured policy is enforced for that client. Using only the blocked name can miss a resolver that returns the same failure for every query.

Query the intended resolver explicitly

From the same network and client policy group as the users you want to represent, collect the response code, answer section, and timing. These BIND dig commands (opens in a new tab) illustrate the request shape; replace the documentation addresses and names with your test fixtures.

dig @192.0.2.53 blocked.monitor.example A +time=2 +tries=1
dig @192.0.2.53 allowed.monitor.example A +time=2 +tries=1
dig @192.0.2.53 blocked.monitor.example AAAA +time=2 +tries=1

Do not infer success solely from dig exiting normally: a received DNS error is still a response. Inspect the DNS result and compare the expected answer set, handling order and any deliberately allowed values. For a production script, use a DNS library or structured parser rather than searching arbitrary output for the substring 0.0.0.0.

Match the configured blocking mode

Pi-hole documents multiple blocking modes (opens in a new tab), including NULL, NXDOMAIN, and NODATA. NULL uses unspecified addresses; other modes deliberately produce different response shapes. A check written for NULL will incorrectly flag a correctly configured NXDOMAIN policy.

Keep the policy expectation under review alongside resolver configuration. If split DNS or per-client groups are intentional, test each important group separately rather than declaring one answer universally correct.

Report both failure and silence

Run the checks with a bounded total duration and send a success heartbeat only if all required assertions pass. An outside deadline should detect when the scheduled checker stops. Include the failed fixture category and response code in the alert, but avoid publishing internal hostnames or the heartbeat secret.

A Pi-hole API endpoint may provide useful supplementary state, but an API reporting that blocking is enabled does not prove a client received the expected answer. Historical API examples can also use authentication that changed between releases. Prefer the actual DNS behavior for the functional assertion and verify any API integration against the deployed version.

Finally, stop the test resolver or isolate the checker from it during a maintenance exercise. Verify that the alarm can leave through an independent resolution path; otherwise the system can correctly detect a DNS failure while being unable to tell anyone.