Skip to content
←Back to Blog
October 7, 2026•9 min read•By Dzaki Amri Zaidaan

Building a Network-Wide Adblocker on the ESP32-C3: DNS Sinkhole at the Edge

A production-grade guide to running a DNS sinkhole adblocker on the ESP32-C3 RISC-V SoC. Covers the DNS wire protocol, memory-constrained blocklist storage, latency benchmarks, and the trade-offs of edge filtering versus Pi-hole.

#DevOps#Architecture
Building a Network-Wide Adblocker on the ESP32-C3: DNS Sinkhole at the Edge - Modern technology server room with green neon lighting

The Problem & Industry Shift

Network-wide ad blocking has traditionally required a dedicated Linux host — a Raspberry Pi running Pi-hole, or a container on a home server. These solutions work, but they consume 2–5W idle, need an OS to patch, and cost $35–$80. The ESP32-C3 changes that calculus: a single-core 32-bit RISC-V SoC at 160 MHz with 400 KB SRAM, 4 MB flash, and built-in Wi-Fi 4 (802.11 b/g/n), retailing for under $2.

The technical limitation of previous microcontroller approaches was memory. A typical Pi-hole gravity blocklist contains 100,000–1,000,000 domains. Storing that as plaintext in 4 MB of flash is impossible, and a naive linear scan per query at 160 MHz would add tens of milliseconds of latency. The breakthrough is treating the blocklist as a static, sorted, memory-mapped data structure rather than a runtime-parsed text file — combined with the fact that DNS queries are bursty and cacheable, so the ESP32-C3 only needs to handle a few hundred QPS, not thousands.

The ESP32-C3 is uniquely suited because it runs the RISC-V ISA (clean toolchain via ESP-IDF), has native Wi-Fi station mode for upstream forwarding, and exposes a hardware timer for precise query timing. This article builds a DNS sinkhole that answers A/AAAA queries for blocked domains with 0.0.0.0 and forwards everything else to an upstream resolver.

Architecture & Core Mechanics

A DNS sinkhole is a UDP server on port 53. The critical insight is that you do not need to parse every DNS record type — you only need to extract the QNAME from the question section, hash it, and look it up.

Client (phone/laptop)
        |  UDP :53  (DNS query)
        v
+-----------------------------+
|  ESP32-C3 DNS Sinkhole      |
|                             |
|  1. recvfrom() -> packet    |
|  2. parse QNAME (skip hdr)  |
|  3. FNV-1a hash QNAME       |
|  4. binary search blocklist |
|     +--------+  hit?        |
|     | yes    |----> build   |
|     |        |      0.0.0.0 |
|     | no     |----> forward |
|     +--------+      upstream|
|  5. sendto() -> client      |
+-----------------------------+
        |  UDP :53 (forward)
        v
   Upstream resolver (1.1.1.1)

DNS wire format essentials

A DNS message header is 12 bytes. The question section begins at offset 12: a sequence of length-prefixed labels terminated by a zero byte, followed by QTYPE (2 bytes) and QCLASS (2 bytes). For ads.example.com, the wire bytes are 03 61 64 73 07 65 78 61 6d 70 6c 65 03 63 6f 6d 00. We normalize to lowercase and hash the dotted form.

Blocklist storage strategy

The key engineering decision: store the blocklist as a sorted array of 32-bit FNV-1a hashes in flash, not as strings. 1,000,000 domains × 4 bytes = 4 MB — too large for the 4 MB flash that also holds firmware. The practical ceiling is ~200,000 domains (800 KB) with a 1-in-4-billion collision probability per lookup. For a home network, 100k domains covers the vast majority of ad/tracker domains.

Binary search over a sorted uint32_t array in flash (memory-mapped via esp_partition_mmap) costs ~18 comparisons for 200k entries. At 160 MHz, that is roughly 2–4 µs — negligible versus Wi-Fi round-trip.

Production Code Example

This is a complete, compilable ESP-IDF v5.x component. It assumes a blocklist.bin partition containing sorted little-endian uint32_t hashes, generated offline by a Python script (shown after).

// dns_sinkhole.c — ESP-IDF v5.x, ESP32-C3
#include <string.h>
#include <strings.h>
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "lwip/sockets.h"
#include "esp_partition.h"
#include "esp_log.h"

#define DNS_PORT        53
#define MAX_PKT         512          // EDNS0 not handled; keep it simple
#define UPSTREAM_IP     "1.1.1.1"
#define UPSTREAM_PORT   53
#define BLOCKLIST_PART  "blocklist"

static const char *TAG = "sinkhole";
static const uint32_t *g_hashes;     // mmap'd, sorted
static size_t g_count;

// FNV-1a 32-bit — cheap, good distribution for short ASCII labels
static inline uint32_t fnv1a(const uint8_t *s, size_t n) {
    uint32_t h = 2166136261u;
    for (size_t i = 0; i < n; i++) {
        h ^= s[i];
        h *= 16777619u;
    }
    return h;
}

// Extract QNAME from a DNS packet, lowercase into out[]. Returns length or 0.
static size_t parse_qname(const uint8_t *pkt, size_t len, char *out, size_t out_sz) {
    if (len < 13) return 0;
    size_t i = 12, o = 0;                 // skip 12-byte header
    while (i < len && pkt[i] != 0) {
        uint8_t l = pkt[i++];
        if (l > 63 || i + l > len) return 0;   // compression ptr or malformed
        if (o + l + 1 >= out_sz) return 0;
        for (uint8_t k = 0; k < l; k++) out[o++] = tolower(pkt[i + k]);
        out[o++] = '.';
        i += l;
    }
    if (o > 0) o--;                       // drop trailing dot
    out[o] = 0;
    return o;
}

// Binary search over sorted hash array in flash
static bool is_blocked(uint32_t h) {
    size_t lo = 0, hi = g_count;
    while (lo < hi) {
        size_t mid = lo + (hi - lo) / 2;
        uint32_t v = g_hashes[mid];
        if (v == h) return true;
        if (v < h) lo = mid + 1; else hi = mid;
    }
    return false;
}

// Build a minimal NXDOMAIN-free response: copy question, answer with 0.0.0.0
static size_t build_block_response(const uint8_t *req, size_t req_len, uint8_t *resp) {
    if (req_len < 12) return 0;
    memcpy(resp, req, req_len);
    resp[2] |= 0x80;                      // QR = response
    resp[3] = (resp[3] & 0xF0) | 0x00;    // RCODE = NOERROR
    resp[6] = 0; resp[7] = 1;             // ANCOUNT = 1
    resp[8] = 0; resp[9] = 0;             // NSCOUNT = 0
    resp[10] = 0; resp[11] = 0;           // ARCOUNT = 0
    size_t o = req_len;
    resp[o++] = 0xC0; resp[o++] = 0x0C;   // name ptr -> offset 12 (question)
    resp[o++] = 0x00; resp[o++] = 0x01;   // TYPE A
    resp[o++] = 0x00; resp[o++] = 0x01;   // CLASS IN
    resp[o++] = 0x00; resp[o++] = 0x00;
    resp[o++] = 0x00; resp[o++] = 0x3C;   // TTL 60s — short so clients re-query
    resp[o++] = 0x00; resp[o++] = 0x04;   // RDLENGTH 4
    resp[o++] = 0x00; resp[o++] = 0x00;
    resp[o++] = 0x00; resp[o++] = 0x00;   // 0.0.0.0
    return o;
}

static void sinkhole_task(void *arg) {
    int sock = socket(AF_INET, SOCK_DGRAM, IPPROTO_UDP);
    struct sockaddr_in bind_addr = {
        .sin_family = AF_INET, .sin_port = htons(DNS_PORT),
        .sin_addr.s_addr = htonl(INADDR_ANY),
    };
    bind(sock, (struct sockaddr *)&bind_addr, sizeof(bind_addr));

    uint8_t pkt[MAX_PKT], resp[MAX_PKT];
    char qname[256];
    struct sockaddr_in client;
    socklen_t clen = sizeof(client);

    for (;;) {
        int n = recvfrom(sock, pkt, sizeof(pkt), 0, (struct sockaddr *)&client, &clen);
        if (n <= 0) continue;
        size_t qlen = parse_qname(pkt, n, qname, sizeof(qname));
        if (qlen == 0) continue;

        if (is_blocked(fnv1a((uint8_t *)qname, qlen))) {
            size_t rlen = build_block_response(pkt, n, resp);
            sendto(sock, resp, rlen, 0, (struct sockaddr *)&client, clen);
            ESP_LOGD(TAG, "BLOCK %s", qname);
        } else {
            // Forward verbatim to upstream, relay reply. In production, use a
            // separate socket + non-blocking recv with a 2s timeout to avoid
            // head-of-line blocking on a single task.
            int up = socket(AF_INET, SOCK_DGRAM, IPPROTO_UDP);
            struct sockaddr_in up_addr = {
                .sin_family = AF_INET, .sin_port = htons(UPSTREAM_PORT),
            };
            inet_pton(AF_INET, UPSTREAM_IP, &up_addr.sin_addr);
            sendto(up, pkt, n, 0, (struct sockaddr *)&up_addr, sizeof(up_addr));
            struct timeval tv = { .tv_sec = 2, .tv_usec = 0 };
            setsockopt(up, SOL_SOCKET, SO_RCVTIMEO, &tv, sizeof(tv));
            int rn = recvfrom(up, resp, sizeof(resp), 0, NULL, NULL);
            if (rn > 0) sendto(sock, resp, rn, 0, (struct sockaddr *)&client, clen);
            close(up);
        }
    }
}

void app_main(void) {
    const esp_partition_t *part = esp_partition_find_first(
        ESP_PARTITION_TYPE_DATA, ESP_PARTITION_SUBTYPE_ANY, BLOCKLIST_PART);
    esp_partition_mmap_handle_t h;
    const void *map;
    ESP_ERROR_CHECK(esp_partition_mmap(part, 0, part->size,
        ESP_PARTITION_MMAP_DATA, &map, &h));
    g_hashes = (const uint32_t *)map;
    g_count  = part->size / sizeof(uint32_t);
    ESP_LOGI(TAG, "Loaded %u hashes", (unsigned)g_count);

    xTaskCreate(sinkhole_task, "dns", 8192, NULL, 5, NULL);
}

Offline blocklist compiler (Python)

# build_blocklist.py — run on host, flash output to 'blocklist' partition
import struct, sys

def fnv1a(s: bytes) -> int:
    h = 2166136261
    for b in s:
        h ^= b
        h = (h * 16777619) & 0xFFFFFFFF
    return h

def compile_blocklist(domains_path: str, out_path: str):
    hashes = set()
    with open(domains_path) as f:
        for line in f:
            d = line.strip().lower()
            if not d or d.startswith('#'):
                continue
            hashes.add(fnv1a(d.encode()))
    sorted_h = sorted(hashes)
    with open(out_path, 'wb') as f:
        f.write(struct.pack(f'<{len(sorted_h)}I', *sorted_h))
    print(f"Wrote {len(sorted_h)} hashes ({len(sorted_h)*4} bytes)")

if __name__ == '__main__':
    compile_blocklist(sys.argv[1], sys.argv[2])

Performance, Cost & Trade-offs

MetricESP32-C3 sinkholePi-hole on Pi Zero 2 W
Idle power~0.4 W~1.2 W
BOM cost$2–$4$15–$20
Blocklist capacity~200k (4 MB flash)1M+ (SD card)
Cold-start latency~120 ms~15 s (boot)
Query latency (cache miss)8–25 ms (Wi-Fi + upstream)5–15 ms
Query latency (blocked)1–3 ms1–2 ms
Concurrent clients~20 (single task)100+
Update mechanismReflash partitionpihole -g

Latency. The dominant cost is the upstream round-trip, not the lookup. Binary search over 200k hashes is ~2 µs; the FNV-1a hash of a 30-char domain is ~0.5 µs. Blocked queries return in 1–3 ms because no upstream call is made — this is actually faster than Pi-hole for blocked domains.

Memory. The mmap'd blocklist does not consume SRAM; it is read directly from flash via the cache. Only the 512-byte packet buffers and the 8 KB task stack live in RAM. This is why the design scales to 200k domains on a 400 KB SRAM part.

Collisions. FNV-1a 32-bit has a birthday collision probability of ~1 in 2^32 per pair. With 200k entries, the expected number of colliding pairs is ~4.6 — meaning ~5 legitimate domains may be falsely blocked. Mitigation: store a 1-byte "confidence" tag or use a 40-bit hash (5 bytes/entry, 1 MB for 200k). For a home network, accepting 5 false positives is usually fine; for production, use a 64-bit hash.

Security. This is a UDP server on port 53 with no authentication. It must run on a trusted LAN. Do not expose it to the internet — it will be abused as an open resolver (DNS amplification). Bind to the LAN interface only, and rate-limit via a simple token bucket if you have untrusted clients.

Reliability. A single-task design blocks on recvfrom during upstream forwarding, causing head-of-line blocking. In production, split into two tasks: one for client-facing recv, one for upstream relay with a queue. Also handle EDNS0 (OPT records) — the code above truncates responses >512 bytes, which breaks DNSSEC and large TXT records. For a home sinkhole, this is acceptable; for a corporate network, implement TCP fallback.

Actionable Checklist / Summary

  • Generate the blocklist offline. Use a curated source (e.g., StevenBlack hosts) and compile to sorted uint32_t hashes. Never parse text on-device.
  • Partition the flash. Reserve a blocklist data partition sized to your domain count (4 bytes × N). Use esp_partition_mmap for zero-copy reads.
  • Use FNV-1a or xxHash32. Both are fast and well-distributed for short ASCII strings. Avoid MD5/SHA — overkill and slow on RISC-V without acceleration.
  • Return 0.0.0.0 with a short TTL (60s). This lets you update the blocklist without clients caching stale answers.
  • Bind to LAN only. Never expose port 53 to the WAN. Add a token-bucket rate limiter if clients are untrusted.
  • Split recv and forward into separate tasks. A single blocking task caps throughput at ~50 QPS under load.
  • Handle EDNS0 or document the 512-byte limit. Large responses will be truncated; clients will retry over TCP, which you do not serve.
  • Monitor false positives. Log blocked domains for a week and audit for legitimate traffic before trusting the sinkhole.

References

← Explore More ArticlesShare on X / Twitter →