Skip to content

Releases

ESPHole v1.0.0

Choose a tag to compare

@aguilerasmiguel aguilerasmiguel released this 28 Jul 16:51

ESPHole v1.0.0

A Pi-hole–style DNS sinkhole for the ESP32-S3. Every DNS query on your LAN passes through
it: blocklisted domains die with a black-hole answer (0.0.0.0 / ::), everything else is
forwarded to an upstream resolver and cached — and above all, the network never loses DNS even if
blocking fails
(fail-open by design).

Built spec-by-spec with strict test-driven development and on-hardware verification.

⚡ Install in ~60 seconds — no toolchain

From your browser (recommended). Plug an ESP32-S3 in over USB and click Install on the live
page — no ESP-IDF, no drivers, no build. Desktop Chrome or Edge required (Web Serial):

👉 https://aguilerasmiguel.github.io/esphole/#install

From the command line. Grab esphole-factory-esp32s3.bin below and flash it at offset 0:

esptool --chip esp32s3 write-flash 0x0 esphole-factory-esp32s3.bin

On first boot the device starts the ESPHole-XXXX Wi-Fi AP (the WPA2 key is printed on the serial
console). Join it, set your home Wi-Fi at http://192.168.4.1/, then point a client's DNS at the
device and create your admin password on first visit. Full guide in the
README.

Highlights

  • DNS core (RFC 1035 + EDNS0): UDP + TCP on :53, A/AAAA suffix blocking, upstream failover,
    cache, per-IP rate-limiting, fail-open.
  • Encrypted upstream (DoT, RFC 7858): forward over DNS-over-TLS with a fail-closed
    guarantee — it never silently falls back to plaintext.
  • Blocklists from URL: download a HOSTS list over HTTPS and rebuild in place, no reboot.
  • OTA updates with automatic rollback if a new build doesn't boot.
  • Web admin + HTTP API: challenge-response login (the password never travels the wire),
    bilingual EN/ES UI, light/dark themed redesign, per-client stats.
  • Wi-Fi provisioning: captive AP portal on first boot with a per-device WPA2 key.

Capacity & limits

The blocklist is a sorted, deduplicated PSRAM store: up to ~200,000 domains or ~5.44 MB of
domain text
, whichever fills first (~6.2 MB of the 8 MB PSRAM). That covers the big curated HOSTS
lists (e.g. StevenBlack ≈ 150 k) with headroom — deliberately not server-scale. On overflow the
extra entry is dropped and a truncated counter increments (bounded and observable, never a crash).

Known limitations

  • The optional DHCP server is NOT yet verified end-to-end on a live LAN. Its wire/lease logic is
    unit-tested and the API/UI exist, but a rogue DHCP server can hand out IPs and disrupt a real
    network. Leave it off unless you are testing on an isolated segment with the router's own DHCP
    disabled.

Hardware & verification

  • Target: ESP32-S3-N16R8 (16 MB flash, 8 MB octal PSRAM). Other S3 variants may work with
    partition tweaks.
  • Built with ESP-IDF v6.0.1. Pure-logic modules are unit-tested on the host under ASan/UBSan;
    specs 001–010 were verified on hardware (DHCP excepted, see above).

Assets

  • esphole-factory-esp32s3.bin — full merged image (bootloader + partition table + app + web UI),
    flash at offset 0x0. This is the file the command-line install above uses. The browser installer
    serves its own split app/UI images from the site.

License: MIT.