Bancuh DNS

Bancuh Adblock DNS server written in Rust

Introduction

A DNS server resolves domain names into IP addresses. An adblock DNS server does the same, but intercepts queries for known ad/tracker domains and returns a null IP (0.0.0.0 / ::) instead of forwarding them — effectively blocking them at the network level for any device using the server.

bancuh-dns is a self-contained adblock DNS server written in Rust.

Key strengths:

• Easy deployment using Docker
• Low memory footprint — around 100 MB for the server plus 25–50 MB for the bundled recursor
• Automatic daily blocklist updates (configurable via UPDATE_INTERVAL)
• Custom blacklist, whitelist, and domain rewrite support
• Privacy-first: defaults to a local unbound recursive resolver with DNSSEC validation (no queries sent to public DNS)
• Optional custom forwarders (e.g. 1.1.1.1) via FORWARDERS env var

Additionally, and experimentally, the server can terminate DoT/DoH itself, rate-limit per client IP, and serve a query-log UI. See Deployment modes for when those apply — they are off by default and not used in production.

Deployment modes

bancuh-dns can run in two arrangements. Which one you pick determines which features are available and which are meaningful, so it is worth deciding up front.

Backend mode (recommended)

bancuh-dns handles plain DNS on port 53 and nothing else. A separate front-end — dnsdist-acme — terminates DoT and DoH, manages Let's Encrypt certificates, applies rate limiting, and serves query logs.

client ──▶ dnsdist-acme ──▶ bancuh-dns ──▶ unbound / FORWARDERS
           (:53 :443 :853)   (:1153)
           TLS, ACME,        filtering
           rate limit, logs

This is what the public Bancuh DNS service runs on every node, and it is the arrangement the project is tested against. Use it unless you have a specific reason not to.

In this mode, leave TLS_ENABLED, ADMIN_ENABLED and RATE_LIMIT_ENABLED unset — the front-end provides all three, and enabling them here is at best redundant and at worst harmful (see the warnings on each below).

Standalone mode (experimental)

bancuh-dns binds the public interface directly and terminates DoT/DoH itself, obtaining its own certificate over ACME.

This mode is not production-tested. Two known problems:

• UDP does not work behind a NAT-style floating/reserved IP (e.g. a DigitalOcean Reserved IP). Replies are sent from the host's primary address rather than the address the query arrived on, and clients discard them. TCP, DoT and DoH are unaffected. See #8.
• DoH supports POST only. RFC 8484 also defines a GET form (?dns=<base64url>), which browsers and some monitoring tools use. Those clients will fail.

Use it for local experimentation, or where the server has a normal, directly-bound public address and you only need DoT / POST-based DoH.

Architecture

                        ┌──────────────────────────────────────────────────┐
                        │                  bancuh-dns                      │
                        │                                                  │
 DNS/UDP (port 53)  ───▶│  Handler                                         │
 DNS/TCP (port 53)  ───▶│    0. rate limit?  ──▶ dropped   [experimental]  │
 DoT  (853) [exp.]  ───▶│    1. rewrite?     ──▶ forward alias             │
 DoH  (443) [exp.]  ───▶│    2. blocked?     ──▶ return 0.0.0.0 / ::       │
                        │    3. passthrough  ──▶ Resolver                  │
                        │    ──▶ log query   [experimental]                │
                        │                          │                       │
                        │  AdblockEngine           │                       │
                        │  (ArcSwap<DB>)           ▼                       │
                        │    blacklist      FORWARDERS set?                │
                        │    whitelist       yes ──▶ upstream IPs          │
                        │    rewrites        no  ──▶ local unbound         │
                        │                                                  │
 HTTP (8080) [exp.] ───▶│  Admin server (query logs UI + JSON API)         │
                        │                                                  │
                        │  Update loop (daily)                             │
                        │    fetch config ──▶ compile ──▶ swap DB          │
                        │                                                  │
                        │  ACME loop  [experimental, TLS_ENABLED only]     │
                        │    HTTP-01 challenge server (port 80)            │
                        │    obtain/renew cert from Let's Encrypt          │
                        └──────────────────────────────────────────────────┘

Components marked [experimental] belong to standalone mode and are disabled by default.

This is the beginning of the README. Read the rest at the original. Read the full README ↗