ismkdc/pihole-dot repository overview

⁠pihole-dot

pihole with native DNS-over-TLS, no sidecar needed.

Not affiliated with or endorsed by the official Pi-hole project. "Pi-hole" is a trademark of Pi-hole LLC.

Drop-in replacement for the official pihole/pihole image. Uses ismkdc/FTL-DoT⁠, a fork of pihole-FTL that adds a synchronous TCP+TLS upstream path (RFC 7858) directly inside the DNS forwarder. No unbound, no stubby, no extra container.

⁠Quick start

services:
  pihole:
    image: ismkdc/pihole-dot:latest
    network_mode: host
    environment:
      TZ: 'Europe/Istanbul'
      FTLCONF_webserver_port: 8181
      FTLCONF_dns_upstreams: 'tls://8.8.8.8#853#dns.google;tls://8.8.4.4#853#dns.google'
    volumes:
      - './etc-pihole:/etc/pihole'
    cap_add:
      - NET_ADMIN
      - SYS_TIME
    restart: unless-stopped

⁠DoT upstream format

tls://<ip>#<port>#<tls-hostname>

Semicolon-separated for multiple upstreams. Providers are also selectable as checkboxes in the web portal under Settings → DNS.

Any RFC 7858 compliant DoT server works, format is always tls://ip#port#tls-hostname.

⁠Bare-metal (no Docker)

Not using Docker? ismkdc/pihole-dot⁠ is a fork of the official pihole installer that ships FTL-DoT instead of upstream FTL:

git clone --depth 1 https://github.com/ismkdc/pihole-dot.git pihole
cd "pihole/automated install/"
sudo bash basic-install.sh

⁠Architectures

linux/amd64 · linux/arm64 · linux/arm/v7 · linux/arm/v6 · linux/riscv64

⁠Configuration

All standard pihole environment variables work unchanged. The only difference is the upstream format:

⁠How it works

FTL normally forwards DNS queries over UDP/TCP to plain resolvers. This fork adds a TCP+TLS path that activates when an upstream URL uses the tls:// scheme:

1. On first query to a tls:// upstream, a TCP connection is established to port 853 and a TLS handshake is performed (ALPN: "dot", cert verification enabled).
2. The TLS session is kept alive across queries, the handshake cost is paid once per upstream, not per query.
3. DNS messages are framed with the RFC 7858 2-byte length prefix over the TLS stream.

Key implementation detail: TLS 1.3 servers (Google, Cloudflare) send a NewSessionTicket immediately after the handshake, before the first DNS response. mbedTLS 4.x surfaces this as MBEDTLS_ERR_SSL_RECEIVED_NEW_SESSION_TICKET (-0x7B00). Without handling it, the first query after every new connection silently fails. Fixed in src/dnsmasq/tls.c by treating it as a retry signal.

⁠Source

• FTL fork: ismkdc/FTL-DoT⁠
• Docker image source: ismkdc/docker-pihole-dot⁠
• Bare-metal installer: ismkdc/pihole-dot⁠