How to monitor Pi-hole from outside your network

Why Pi-hole is a special case

Most services fail in isolation. Pi-hole fails and takes name resolution with it, so your other monitoring cannot resolve anything either. Pi-hole is upstream of your ability to be told about Pi-hole.

• FTL crashes or is killed by the out of memory reaper. Clients hang instead of failing fast, which reads as slow internet rather than broken DNS.
• The SD card in a Raspberry Pi wears out, and Pi-hole answers from memory for a while before stopping in a hard to diagnose way.
• A DHCP change hands out a different DNS server, so Pi-hole is fine, nobody is using it, and your ad blocking silently stopped weeks ago.
• Upstream resolvers become unreachable. Pi-hole is up, the API is up, and every query returns SERVFAIL.

A check that only proves the web interface loads will stay green through most of those.

The v6 API is not the v5 API

This trips people up constantly. Pi-hole v6 replaced lighttpd and PHP with an embedded FTL web server and an entirely new REST API. The old GET /admin/api.php?status endpoint, and the ?auth= query string key with it, no longer work. Any guide telling you to check api.php was written for v5.

The current API is rooted at /api and documents itself: your Pi-hole serves interactive docs at /api/docs matching the exact version you are running.

Authentication is a session flow. POST to /api/auth with a JSON body containing your password, or an application password generated in the web interface, and you get back a session id and a CSRF token. Send that session id on later requests, most conveniently as an X-FTL-SID header. If no password is set, requests need no authentication at all.

Stats and blocking endpoints return 401 without a valid session, so an unauthenticated check against them measures only the error path. The v6 web server also binds port 80 by default and falls back to 8080 when something already holds 80, which is common after a v5 upgrade.

Never expose port 53

It is tempting to point a DNS check at your home address. Do not. An open resolver is abused for amplification and reflection attacks within hours of being found, and Pi-hole guidance is explicit about the risk. The same goes for publishing the admin interface.

External DNS checks are the right tool for your public domain records, where the authoritative servers are meant to be public. For an internal resolver, the correct direction of travel is outward.

The heartbeat recipe, gated on a real lookup

Run a cron job on the Pi-hole host that queries itself and only reports in when the lookup succeeds. That tests what Pi-hole exists to do, rather than what is easiest to check:

*/2 * * * * dig +short +time=2 +tries=1 @127.0.0.1 example.com > /dev/null \
  && curl -fsS -m 10 https://undownable.com/ping/your-monitor-id > /dev/null

If FTL is dead, dig fails and the ping never happens. The heartbeat monitor raises an incident once the expected interval elapses, from infrastructure that does not depend on your DNS.

For a stricter version that fails on an empty answer rather than only on a dig error:

*/2 * * * * test -n "$(dig +short @127.0.0.1 example.com)" \
  && curl -fsS -m 10 https://undownable.com/ping/your-monitor-id > /dev/null

Put the cron entry on the Pi-hole host itself. A heartbeat from another machine conflates a Pi-hole failure with a network failure between the two boxes.

Run two, monitor both

If you have a second Pi-hole for redundancy, give it its own heartbeat. Redundant DNS fails nastily: the secondary quietly dies, the primary covers, and months later the primary reboots and the whole house loses DNS.

Alerting when DNS itself is broken

This is the part people get wrong. An alert path that needs a DNS lookup on your network does not work during the outage. External delivery sidesteps that, because resolution happens on our side:

• ntfy, hosted or self hosted with an access token starting with tk_ sent as a bearer token, stored encrypted. Self hosting is fine as long as it is not behind the Pi-hole that just died.
• Telegram, which depends on nothing of yours: not your DNS, not your router, not your power.
• Email as the fallback, because it still lands on a phone with cellular data.

Use a confirmation threshold of two so a gravity update or a scheduled FTL restart does not page you.