https://github.com/0xerr0r/blocky

Fast and lightweight DNS proxy as ad-blocker for local network with many features
https://github.com/0xerr0r/blocky

ad-blocker adblock adblocker dns dns-over-https dns-server golang parental-control pihole self-hosted selfhosted

Last synced: 9 months ago
JSON representation

Fast and lightweight DNS proxy as ad-blocker for local network with many features

• Host: GitHub
• URL: https://github.com/0xerr0r/blocky
• Owner: 0xERR0R
• License: apache-2.0
• Created: 2019-11-06T09:03:31.000Z (over 6 years ago)
• Default Branch: main
• Last Pushed: 2025-05-08T04:44:52.000Z (9 months ago)
• Last Synced: 2025-05-08T20:57:20.076Z (9 months ago)
• Topics: ad-blocker, adblock, adblocker, dns, dns-over-https, dns-server, golang, parental-control, pihole, self-hosted, selfhosted
• Language: Go
• Homepage: https://0xERR0R.github.io/blocky/
• Size: 14.4 MB
• Stars: 5,313
• Watchers: 38
• Forks: 236
• Open Issues: 86
• Metadata Files:
  • Readme: README.md
  • Funding: .github/FUNDING.yml
  • License: LICENSE
  • Code of conduct: CODE_OF_CONDUCT.md

Awesome Lists containing this project

README

          
[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/0xERR0R/blocky/makefile.yml "Make")](https://github.com/0xERR0R/blocky/actions/workflows/makefile.yml)

[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/0xERR0R/blocky/release.yml "Release")](https://github.com/0xERR0R/blocky/actions/workflows/release.yml)

[![GitHub latest version](https://img.shields.io/github/v/release/0xERR0R/blocky "Latest version")](https://github.com/0xERR0R/blocky/releases)

[![GitHub Release Date](https://img.shields.io/github/release-date/0xERR0R/blocky "Latest release date")](https://github.com/0xERR0R/blocky/releases)

[![GitHub go.mod Go version](https://img.shields.io/github/go-mod/go-version/0xERR0R/blocky "Go version")](#)

[![Docker pulls](https://img.shields.io/docker/pulls/spx01/blocky "Latest version")](https://hub.docker.com/r/spx01/blocky)

[![Docker Image Size (latest)](https://img.shields.io/docker/image-size/spx01/blocky/latest)](https://hub.docker.com/r/spx01/blocky)

[![Codecov](https://img.shields.io/codecov/c/gh/0xERR0R/blocky "Code coverage")](https://codecov.io/gh/0xERR0R/blocky)

[![Codacy grade](https://img.shields.io/codacy/grade/8fcd8f8420b8419c808c47af58ed9282 "Codacy grade")](#)

[![Go Report Card](https://goreportcard.com/badge/github.com/0xERR0R/blocky)](https://goreportcard.com/report/github.com/0xERR0R/blocky)

[![Donation](https://img.shields.io/badge/buy%20me%20a%20coffee-donate-blueviolet.svg)](https://ko-fi.com/0xerr0r)



  



# Blocky

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

## Features

- **Blocking** - 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** - 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** - 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** - Supports modern DNS protocols

  - DNS over UDP and TCP

  - DNS over HTTPS (aka DoH)

  - DNS over TLS (aka DoT)

- **Security and Privacy** - Secure communication

  - Supports modern DNS extensions: DNSSEC, eDNS, ...

  - 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

  - Blocky does **NOT** collect any user data, telemetry, statistics etc.

- **Integration** - 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** - single or multiple configuration files in YAML format

  - Simple to maintain

  - Simple to backup

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

  - Stateless (no database, no temporary files)

  - Docker image with Multi-arch support

  - Single binary

  - Supports x86-64 and ARM architectures -> runs fine on Raspberry PI

  - Community supported Helm chart for k8s deployment

## Quick start

You can jump to [Installation](https://0xerr0r.github.io/blocky/latest/installation/) chapter in the documentation.

## Full documentation

You can find full documentation and configuration examples

at: [https://0xERR0R.github.io/blocky/](https://0xERR0R.github.io/blocky/)

## Contribution

Issues, feature suggestions and pull requests are welcome!

[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/G2G25XZQG)