# Blocky

<figure>
  <img src="https://raw.githubusercontent.com/0xERR0R/blocky/main/docs/blocky.svg" width="200" />
</figure>

Blocky is a DNS proxy and ad-blocker for the local network written in Go with following features:

```mermaid
flowchart LR
    C[Client devices] -->|DNS query| B(Blocky)
    B -->|allowed query| U[Upstream resolvers]
    U -->|answer| B
    B -->|blocked domain| X[Blocked response]
    B -->|answer| C
```

## Features

- **Blocking** - :no_entry: Blocking of DNS queries with external lists (Ad-block, malware) and allowlisting

    * Definition of allow/denylists per client group (Kids, Smart home devices, etc.)
    * Periodical reload of external allow/denylists
    * Regex support
    * Blocking of request domain, response CNAME (deep CNAME inspection) and response IP addresses (against IP lists)

- **Advanced DNS configuration** - :nerd: not just an ad-blocker

    * Custom DNS resolution for certain domain names
    * Conditional forwarding to external DNS server
    * Upstream resolvers can be defined per client group

- **Performance** - :rocket: Improves speed and performance in your network

    * Customizable caching of DNS answers for queries -> improves DNS resolution speed and reduces amount of external DNS
      queries
    * Prefetching and caching of often used queries
    * Using multiple external resolver simultaneously
    * Low memory footprint

- **Various Protocols** - :computer: Supports modern DNS protocols

    * DNS over UDP and TCP
    * DNS over HTTPS (aka DoH)
    * DNS over TLS (aka DoT)
    * DNS over QUIC (aka DoQ, RFC 9250)
    * DNS over HTTPS/3 (aka DoH3, RFC 9114)

- **Security and Privacy** - :dark_sunglasses: Secure communication

    * Supports modern DNS extensions: DNSSEC, eDNS, ...
    * DNSSEC validation of upstream resolvers
    * Free configurable blocking lists - no hidden filtering etc.
    * Provides DoH Endpoint
    * Uses random upstream resolvers from the configuration - increases your privacy through the distribution of your DNS
      traffic over multiple provider
    * Open source development
    * Blocky does **NOT** collect any user data, telemetry, statistics etc.

- **Integration** - :notebook_with_decorative_cover: various integration

    * [Prometheus](https://prometheus.io/) metrics
    * Prepared [Grafana](https://grafana.com/) dashboards (Prometheus and database)
    * Logging of DNS queries per day / per client in CSV format or MySQL/MariaDB/PostgreSQL/Timescale database - easy to
      analyze
    * Various REST API endpoints
    * CLI tool

- **Simple configuration** - :baby: single or multiple configuration files in YAML format

    * Simple to maintain
    * Simple to backup

- **Simple installation/configuration** - :cloud: blocky was designed for simple installation

    * Stateless (no database, no temporary files)
    * Docker image with Multi-arch support
    * Single binary
    * Supports x86-64, ARM, and MIPS architectures -> runs fine on Raspberry PI and OpenWrt routers
    * Community supported Helm chart for k8s deployment


## Contribution

Issues, feature suggestions and pull requests are welcome! Blocky lives on :material-github:[GitHub](https://github.com/0xERR0R/blocky).

## Support Blocky :heart:

Blocky is **free, open source, and developed in my spare time** — with no telemetry, no data
collection, and no hidden filtering. **Thousands of people run Blocky; only a handful support it.**
If Blocky is useful to you, please consider chipping in — your support directly funds ongoing
development and helps keep Blocky independent and ad-free, forever. Every contribution, however
small, is hugely appreciated. Thank you! :heart:

[![Sponsor on GitHub](https://img.shields.io/badge/Sponsor-GitHub-EA4AAA?logo=githubsponsors&logoColor=white)](https://github.com/sponsors/0xERR0R)
[![Support on thanks.dev](https://img.shields.io/badge/thanks.dev-support-00A98F)](https://thanks.dev/u/gh/0xERR0R)
[![Donate on Liberapay](https://img.shields.io/badge/Liberapay-donate-F6C915?logo=liberapay&logoColor=black)](https://liberapay.com/spx01)
[![Buy me a coffee on Ko-fi](https://img.shields.io/badge/Ko--fi-donate-FF5E5B?logo=kofi&logoColor=white)](https://ko-fi.com/0xerr0r)
[![Donate via PayPal](https://img.shields.io/badge/PayPal-donate-00457C?logo=paypal&logoColor=white)](https://paypal.me/spx01)
