0xERR0R/blocky
Blocky
Blocky is a stateless DNS proxy that functions as a network-wide ad-blocker and content filter. It operates as a single binary or Docker container with no database or persistent state, accepting DNS queries over UDP, TCP, HTTPS, TLS, QUIC, and HTTP/3 through a unified plugin-based query pipeline. The core of the system is a client-group policy engine that assigns devices to named groups and applies per-group blocklists, allowlists, and upstream resolvers, with all configuration changes applied through hot-reloading without requiring a restart.
The project distinguishes itself through its modular, plugin-driven architecture that chains blocking, forwarding, caching, and filtering decisions in sequence. It supports DNSSEC validation to verify upstream response authenticity, and provides a YAML-driven configuration system that merges multiple files from a directory for modular setups. Blocklists and allowlists can be updated live, and the proxy includes a prefetching cache that proactively resolves frequently queried domains to reduce lookup latency.
For observability, Blocky exposes Prometheus metrics with prebuilt Grafana dashboards, logs queries to databases or CSV files, and offers a browser-based management interface for live metrics, query testing, and configuration editing. It also provides REST API endpoints and a command-line interface for programmatic control and inspection of runtime state.
Features
- Stateless - Runs as a single stateless binary with no database or persistent state, supporting x86, ARM, and MIPS architectures.
- DNS Servers - Runs a DNS proxy server that forwards queries to upstream resolvers and blocks unwanted domains using external blocklists.
- Conditional Domain Resolvers - Sends DNS queries for specific domains to designated external servers instead of the default resolver.
- DNS Blocklist Filters - Filters DNS queries against ad-block, malware, and allowlists loaded from external sources with regex and deep CNAME inspection.
- DNS Caches - Caches resolved DNS answers to speed up repeated lookups and reduce upstream traffic.
- DNS Prefetching Caches - Caches resolved DNS answers and prefetches frequently used queries to reduce lookup latency.
- Temporary Binary Execution - Operates as a single stateless binary or Docker image with no database or temporary files.
- Configuration Hot-Reloaders - Applies changes to blocklists, allowlists, and configuration without restarting by reloading rules in-memory.
- Blocklist Hot-Reloaders - Applies changes to blocklists, allowlists, and configuration without restarting the DNS proxy by reloading rules in-memory.
- Multi-Architecture Binary Deployments - Runs as a single stateless binary or Docker image on x86, ARM, and MIPS architectures.
- Single-Binary Distributions - Distributes as a single stateless binary for x86, ARM, and MIPS architectures with no external dependencies.
- Proactive Cache Prefetching - Prefetches commonly used domains by resolving and caching them before they are explicitly requested.
- DNS Forwarding Routing - Forwards DNS queries for specific domains to designated upstream servers while using default resolvers for all other traffic.
- Conditional DNS Resolvers - Forwards queries for specific domains to custom resolvers or conditional upstreams, configurable per client group.
- DNS Prefetching - Prefetches frequently used DNS queries to resolve and cache them before they are explicitly requested.
- DNS Routing Overrides - Routes DNS queries for chosen domain names to a custom or external DNS server for separate handling.
- Custom Domain Resolvers - Routes DNS queries for specific domains to designated servers while sending all other traffic through default resolvers.
- Client-Group DNS Filters - Assigns devices to named groups and applies per-group blocklists, allowlists, and upstream resolvers.
- DNS-Based Ad Blockers - Blocks unwanted DNS queries using external blocklists and allowlists to filter ads, malware, and unwanted content.
- DNS - Routes DNS queries through a chain of configurable plugins that decide forwarding, blocking, or caching based on domain, client, or list membership.
- Client-Group DNS Routers - Applies per-group allow and deny lists and upstream resolvers so different clients get tailored DNS handling.
- Per-Client DNS Routers - Applies custom allow and deny lists and upstream resolvers to different client groups like kids or smart devices.
- Per-Client DNS Blocking Rules - Applies distinct allow and deny lists to different client groups such as kids or smart home devices.
- External List-Based DNS Blockers - Blocks unwanted DNS queries by matching domains, CNAMEs, or IP addresses against external blocklists and allowlists.
- Domain Name Blocking - Blocks unwanted DNS queries by matching domains, CNAMEs, and IPs against external ad-block and malware lists.
- Domain Blocklists - Filters DNS queries against user-defined deny lists and blocks matching requests to prevent access to unwanted content.
- DNS Group Policies - Applies separate allow or deny lists and upstream resolvers to different client groups such as kids or smart home devices.
- DNS Filtering Solutions - Blocks unwanted DNS queries using external blocklists and allowlists with support for regex and CNAME inspection.
- Client-Group DNS Filters - Applies different allow or deny lists to specific client groups such as kids or smart home devices.
- DNS Query - Routes DNS queries through a configurable chain of plugins that handle blocking, forwarding, caching, and filtering in sequence.
- Stateless Architectures - Runs as a single stateless binary or Docker image with no persistent state.
- Stateless DNS Proxies - Runs as a single stateless binary or Docker image on x86, ARM, and MIPS architectures including Raspberry Pi and routers.
- Multi-Protocol Listeners - Accepts DNS queries over UDP, TCP, HTTPS, TLS, QUIC, and HTTP/3 using separate listeners that share a common resolution pipeline.
- DNS Query Monitoring - Exposes Prometheus metrics, Grafana dashboards, and logs DNS queries for monitoring.
- DNS Client Group Policies - Assigns devices to named groups and applies per-group blocklists, allowlists, and upstream resolvers.
- DNS Group Policies - Applies separate allow and deny lists and upstream resolvers per client group such as kids or smart home devices.
- Prometheus-Based Metric Exporters - Outputs DNS query logs to CSV or databases and exposes Prometheus metrics with Grafana dashboards.
- YAML - Loads and merges multiple YAML files from a directory into a single configuration tree, enabling modular and environment-specific setups.
- Docker Container Deployments - Runs the DNS proxy in a Docker container, mounting configuration, custom block and allowlists, and query log volumes including remote SAMBA shares.
- DNS-over-HTTPS Servers - Ships a DNS-over-HTTPS server that accepts encrypted queries from external clients.
- Live Blocklist Reloaders - Refreshes list-related configuration on the fly to eliminate the need for restarting the DNS proxy after blocklist changes.
- DNSSEC Response Verification - Verifies DNSSEC records from upstream resolvers to ensure the authenticity of DNS responses.
- DNSSEC Signature Validation - Verifies DNSSEC signatures from upstream resolvers to ensure response authenticity.
- Encrypted DNS Resolvers - Accepts and resolves DNS queries over encrypted transport protocols including HTTPS, TLS, QUIC, and HTTP/3.
- Multi-Protocol Resolvers - Handles DNS queries using UDP, TCP, HTTPS, TLS, QUIC, and HTTP/3 transport protocols.
- YAML - Loads and merges multiple YAML configuration files from a directory to enable modular setup for complex deployments.
- YAML Configuration Files - Uses one or more YAML configuration files for simple setup, backup, and maintenance.
- Query Logging - Records every DNS query per client and day into CSV, MySQL, MariaDB, PostgreSQL, or TimescaleDB.
- Browser-Based Interfaces - Provides a browser-based interface to control the DNS proxy, view live metrics, test queries, and edit configuration.
- Web-Based Control Panels - Provides a browser-based UI for configuration, live metrics, query testing, and analytics.
- DNS Management - Fast DNS proxy for local network ad blocking.
- 网络基础设施 - Lightweight DNS proxy for local network ad-blocking.
