Blocky

Blocky is a high‑performance, Go‑based DNS proxy that doubles as an ad‑blocker for entire local networks. It intercepts every DNS query on the network, applies configurable allow/deny rules sourced from external blocklists (ad‑blocking, malware, privacy), and forwards the query to upstream resolvers. The core of Blocky is a lightweight event‑driven server that can handle tens of thousands of concurrent queries while maintaining low latency, thanks to a custom LRU cache and optional pre‑fetching of popular records.

Technical Stack & Architecture

• Language: Go 1.22+, leveraging the language’s built‑in concurrency primitives (goroutine, channel) for high throughput.
• Core Libraries: Uses the standard net package for UDP/TCP, along with community DNS libraries (miekg/dns) to support advanced features like DNSSEC and EDNS.
• Data Stores: Blocky is agnostic to persistence; it can log query traffic to CSV or any SQL database (MySQL, MariaDB, PostgreSQL, Timescale). The blocklists themselves are fetched over HTTP/HTTPS and reloaded on a configurable schedule.
• Containerization: Official Docker images (spx01/blocky) are available, with a multi‑stage build that strips debugging symbols for minimal size (~35 MB). The image exposes only the required ports (53/udp, 53/tcp, 443 for DoH) and can be run behind a reverse proxy if needed.

Core Capabilities & APIs

• Fine‑grained Policy: Clients can be grouped (e.g., “Kids”, “IoT”) and each group gets its own set of allow/deny lists, upstream resolvers, and conditional forwarding rules.
• Deep CNAME Inspection: Blocky follows CNAME chains up to a configurable depth, enabling blocking of domains that disguise themselves behind aliases.
• IP‑Based Blocking: In addition to domain filtering, IP lists can be applied to responses, useful for blocking known malicious ranges.
• Extensible Resolver Configuration: Upstream resolvers are chosen randomly per query, optionally weighted, providing privacy‑enhancing load distribution.
• Metrics & Observability: Prometheus metrics are exposed on /metrics, and Grafana dashboards are bundled. Logs can be shipped to any SQL backend for long‑term analytics.

Deployment & Infrastructure

Blocky is designed for self‑hosting in LAN environments but scales to small edge deployments. It requires minimal resources: a single CPU core and 64 MB RAM are sufficient for moderate traffic. The application can be run as a systemd service or within Docker/Kubernetes; Helm charts are available in the community. Because it uses standard DNS ports, it can replace existing local resolvers (e.g., dnsmasq, Unbound) without changing client configurations. For high‑availability, a simple round‑robin load balancer can be placed in front of multiple Blocky instances.

Integration & Extensibility

Developers can hook into Blocky’s event system via webhooks or custom plugins written in Go. The plugin API exposes hooks for query reception, response generation, and metrics emission, allowing integration with third‑party services such as SIEMs or custom analytics pipelines. Additionally, the blocklist fetcher can be overridden to pull from internal registries or corporate policy servers.

Developer Experience

Configuration is expressed in a single YAML file, with clear sections for global settings, client groups, and blocklists. The documentation includes example configurations for common scenarios (e.g., blocking ads on all devices while allowing IoT to resolve to a local gateway). The open‑source community is active; contributors report issues via GitHub, and the CI pipeline guarantees high code quality (Codecov coverage > 90 %, Go Report Card ≥ A). The project’s permissive Apache‑2.0 license encourages integration into proprietary or commercial products.

Use Cases

• Home Networks: Replace dnsmasq to block ads, trackers, and malware domains while still allowing local services.
• Small Businesses: Deploy a single instance to enforce corporate DNS policies across all devices, with per‑department allowlists.
• Edge Routers: Run on a low‑power device (e.g., Raspberry Pi) to provide privacy‑enhancing DoH/DoT endpoints for local clients.
• DevOps: Integrate Blocky into CI pipelines to validate DNS responses against custom blocklists before deploying services.

Advantages Over Alternatives

Blocky offers a unique combination of lightweight Go implementation, deep CNAME inspection, and per‑client policy granularity that many DNS forwarders lack. Its native DoH/DoT support eliminates the need for separate TLS termination, while the random upstream selection enhances privacy. Because it is open source and free of telemetry, developers can audit the codebase for security compliance—a critical requirement in regulated environments. Overall, Blocky delivers high performance, flexibility, and privacy with minimal operational overhead, making it a compelling choice for developers building secure, ad‑free network infrastructures.