tutorial

Monitoring Blocky DNS with Vigilmon

Blocky is a fast, privacy-focused DNS proxy and ad-blocker for local networks. Here's how to monitor DNS availability, upstream resolver health, blocklist refresh jobs, and query latency with Vigilmon.

Blocky is a high-performance, privacy-first DNS proxy written in Go. It blocks ads and trackers at the DNS level, forwards queries to upstream resolvers over DoT or DoH, and serves your entire network from a single binary. Because every device on your network depends on it for name resolution, a silent Blocky failure means broken internet for everyone — and you won't know until someone complains. Vigilmon gives you proactive uptime monitoring, latency tracking, and alerting so you catch problems before your users do.

What You'll Set Up

  • DNS service process availability check via the HTTP API
  • Upstream resolver connectivity monitoring (DoT/DoH uplinks)
  • Blocklist download and refresh job health via heartbeat monitors
  • HTTP API endpoint response time tracking
  • DNS-over-HTTPS endpoint availability
  • Prometheus metrics endpoint health check
  • Redis cache connectivity (if configured)

Prerequisites

  • Blocky running on a Linux server (port 53 DNS, port 4000 HTTP API, port 4001 HTTPS)
  • The Blocky HTTP API enabled in your config.yml
  • A free Vigilmon account

Step 1: Monitor the Blocky HTTP API (Core Health Check)

Blocky exposes a REST API on port 4000 that serves as the primary health signal. The /api/blocking/status endpoint returns the current blocking state and is a reliable liveness probe.

  1. Log in to vigilmon.online and click Add Monitor.
  2. Set Type to HTTP / HTTPS.
  3. Enter the URL: http://YOUR_SERVER_IP:4000/api/blocking/status
  4. Set Check interval to 1 minute.
  5. Set Expected HTTP status to 200.
  6. Click Save.

A non-200 response means Blocky's API is down or unreachable. Pair this with an alert so you're paged immediately.

Step 2: Monitor the DNS-over-HTTPS Endpoint

If you expose Blocky's DoH endpoint externally (port 4001 HTTPS or via a reverse proxy), add a dedicated monitor:

  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: https://dns.yourdomain.com/dns-query?name=example.com&type=A
  3. Expected HTTP status: 200
  4. Check interval: 2 minutes
  5. Keyword match (optional): answer — confirms the response body contains DNS answer data.
  6. Click Save.

This catches TLS certificate problems, reverse-proxy misconfigurations, and Blocky crashes that only affect the HTTPS listener.

Step 3: Monitor the Prometheus Metrics Endpoint

Blocky exposes Prometheus metrics at /metrics (port 4000 by default). Even if you don't scrape them with Prometheus, the endpoint being reachable confirms the HTTP server is fully functional:

  1. Add Monitor → HTTP / HTTPS.
  2. URL: http://YOUR_SERVER_IP:4000/metrics
  3. Expected HTTP status: 200
  4. Check interval: 5 minutes
  5. Keyword match: blocky_ — any Blocky metric name confirms the scrape is real.
  6. Save.

Step 4: Heartbeat Monitor for Blocklist Refresh Jobs

Blocky downloads blocklists on startup and refreshes them on a schedule. A failed refresh leaves stale lists in memory — new malware domains slip through. Use a Vigilmon heartbeat monitor to track refresh job execution.

Create the heartbeat

  1. Click Add Monitor → Heartbeat.
  2. Name: Blocky blocklist refresh
  3. Grace period: 25 hours (to allow daily refresh cycles with margin).
  4. Copy the unique heartbeat URL shown after saving.

Ping the heartbeat from a cron job

Blocky doesn't ping URLs natively, so wrap the refresh in a cron job that calls the Blocky refresh API and then pings Vigilmon:

# /etc/cron.d/blocky-refresh — runs daily at 03:00
0 3 * * * root curl -s -X POST http://localhost:4000/api/lists/refresh && \
  curl -s https://vigilmon.online/api/heartbeat/YOUR_HEARTBEAT_TOKEN

Replace YOUR_HEARTBEAT_TOKEN with the token from your heartbeat monitor. If the refresh API call fails, the && operator prevents the heartbeat ping — Vigilmon will alert you when the grace period expires.

Step 5: Monitor Upstream Resolver Connectivity

Blocky forwards queries to upstream resolvers (Cloudflare, Quad9, your ISP, etc.) over DoT or DoH. If all upstreams are unreachable, Blocky returns SERVFAIL for every query. Use Vigilmon to probe the upstreams Blocky depends on:

DoT upstream (port 853)

  1. Add Monitor → TCP Port.
  2. Host: 1.1.1.1 (or your configured upstream)
  3. Port: 853
  4. Check interval: 5 minutes
  5. Save.

DoH upstream (HTTPS)

  1. Add Monitor → HTTP / HTTPS.
  2. URL: https://cloudflare-dns.com/dns-query?name=example.com&type=A
  3. Expected HTTP status: 200
  4. Check interval: 5 minutes
  5. Save.

Add one monitor per critical upstream. If any go red, you know whether a Blocky failure is upstream-induced or local.

Step 6: Monitor Redis Cache Connectivity (If Configured)

Blocky can use Redis as a shared query cache across multiple instances. If Redis is misconfigured or down, cache misses spike and query latency increases. Monitor Redis with a TCP port check:

  1. Add Monitor → TCP Port.
  2. Host: localhost (or your Redis host)
  3. Port: 6379
  4. Check interval: 2 minutes
  5. Save.

Name it Redis (Blocky cache) so alerts are immediately identifiable.

Step 7: Configure Alerting

  1. In Vigilmon, go to Settings → Notifications.
  2. Add your preferred channel: email, Slack, PagerDuty, or webhook.
  3. For the core API monitor (Step 1), set alert after 1 failed check — DNS failures are user-visible immediately.
  4. For blocklist refresh and upstream monitors, set alert after 2 failed checks to reduce noise from transient hiccups.
  5. Enable recovery notifications so you know when Blocky comes back online without having to check manually.

Step 8: Build a Status Dashboard

Group all Blocky monitors into a single status page:

  1. Go to Status Pages → New Status Page.
  2. Name: DNS Infrastructure
  3. Add all monitors from this tutorial.
  4. Toggle Public if you want your team to check status without logging in.
  5. Save and copy the URL.

Bookmark the status page on your router or network management workstation so you can check DNS health at a glance.

Key Metrics to Watch

| Signal | Monitor Type | Alert Threshold | |---|---|---| | HTTP API /api/blocking/status | HTTP | Any non-200 | | DoH endpoint /dns-query | HTTP | Any non-200 | | Prometheus /metrics | HTTP | Any non-200 | | Blocklist refresh job | Heartbeat | Grace period exceeded | | Upstream DoT (port 853) | TCP | Connection refused | | Upstream DoH (HTTPS) | HTTP | Any non-200 | | Redis cache (port 6379) | TCP | Connection refused |

Conclusion

Blocky is a single point of failure for your entire network's DNS resolution. With Vigilmon you get API-level health checks, upstream resolver probes, blocklist refresh job tracking, and DoH endpoint availability monitoring — all in a few minutes of setup. When something breaks, you'll be alerted before the first user complaint arrives.

Sign up for Vigilmon — free tier includes all the monitors in this tutorial.

Monitor your app with Vigilmon

Free plan — 5 monitors, no credit card required. Up and running in 60 seconds.

Start free →
← Back to all articles