Project Awesome project awesome
♥

Ultimate DNS Shield

Self-hosted recursive DNS server using Pi-hole, Unbound and Docker on Raspberry Pi 4.

Package GitHub

Ultimate DNS Shield

Build your own private, recursive, ad-free DNS server on a Raspberry Pi.

Pi-hole + Unbound + Docker — no Google, no Cloudflare, no ISP in your DNS chain.

Licensed under CC BY-NC 4.0 — free to share with attribution, non-commercial use only. Made by Cherif Jebali

What this project does

Every DNS query you make goes somewhere. By default, that somewhere is Google (8.8.8.8), Cloudflare (1.1.1.1), or your ISP — and they log it.

This project sets up a fully self-hosted DNS stack on a Raspberry Pi 4:

  • Pi-hole — network-wide ad and tracker blocker
  • Unbound — recursive resolver that queries root nameservers directly
  • Docker — both services run in isolated containers on a private bridge network

No third-party resolver ever sees your queries.

Architecture

Your devices
    │
    ▼
Pi-hole (172.20.0.3:53)     ← blocks ads & trackers
    │
    ▼
Unbound (172.20.0.2:5335)   ← recursive resolver (no forwarding)
    │
    ▼
Root nameservers             ← authoritative source, no intermediary

Unbound is never exposed to the LAN — only Pi-hole can reach it on the internal Docker bridge network.

Requirements

  • Raspberry Pi 4 (2GB RAM or more)
  • Raspberry Pi OS Lite 64-bit (Debian Bookworm)
  • microSD card (32GB, A1 rated)
  • Ethernet connection (recommended over Wi-Fi)
  • A user account with sudo access

Quick Start

1. Clone this repo on your Pi

git clone https://github.com/cherifon/Ultimate-DNS-Shield.git
cd ultimate-dns-shield

2. Edit the configuration

nano scripts/install.sh

Change these values at the top:

TIMEZONE="Europe/Paris"           # Your timezone
PIHOLE_PASSWORD="ChangeMePlease"  # Choose a strong password
PIHOLE_DIR="$HOME/services/pihole"

3. Run the installer

sudo bash scripts/install.sh

The script automatically:

  • Updates your system
  • Installs Docker
  • Detects your architecture (ARM vs x86)
  • Writes docker-compose.yml and unbound.conf
  • Starts Pi-hole and Unbound
  • Verifies DNS is responding

4. Harden your Pi

nano scripts/security.sh
# Set LOCAL_NETWORK to your subnet (e.g. 192.168.0.0/24)

sudo bash scripts/security.sh

Configures UFW firewall, Fail2Ban, and automatic security updates.

5. Point your router to Pi-hole

In your router's admin panel, set the primary DNS server to your Pi's IP address. Every device on your network will automatically use Pi-hole.

Verify it works

# DNS resolves correctly
dig @YOUR_PI_IP google.com

# Ads are blocked (returns 0.0.0.0)
dig @YOUR_PI_IP doubleclick.net

# DNSSEC validation works
dig @YOUR_PI_IP sigfail.verteiltesysteme.net  # → SERVFAIL (correct)
dig @YOUR_PI_IP sigok.verteiltesysteme.net    # → NOERROR (correct)

Dry-run mode

All scripts support --dry-run — shows exactly what would happen without changing anything:

bash scripts/install.sh --dry-run
bash scripts/security.sh --dry-run
bash scripts/update.sh --dry-run

Update containers

Run monthly to keep Pi-hole and Unbound up to date:

bash scripts/update.sh

Repo structure

ultimate-dns-shield/
├── README.md
├── config/
│   ├── docker-compose.yml    # Ready-to-use container config
│   └── unbound.conf          # Recursive resolver config
├── scripts/
│   ├── install.sh            # Full automated installation
│   ├── security.sh           # UFW + Fail2Ban hardening
│   └── update.sh             # Update containers
└── guide/
    └── Ultimate_DNS_Shield_Guide.pdf   # Full step-by-step guide

What the guide covers

The PDF guide goes deep into every step:

  1. Introduction — how DNS works, why privacy matters
  2. Hardware guide — what you need and why
  3. Installing Raspberry Pi OS — headless setup
  4. Securing SSH — key-based auth, no passwords
  5. Installing Docker — official method, post-install
  6. Pi-hole + Unbound — architecture, config explained line by line
  7. Router configuration — DHCP DNS, testing, DNSSEC
  8. Security hardening — UFW, Fail2Ban, auto-updates
  9. Bonus — blocklists, testing commands, fallback DNS

Download the guide (PDF)

Recommended blocklists

Add these in Pi-hole under Adlists > Update Gravity:

List Description
Steven Black Gold standard, ~200k entries
Hagezi Pro Aggressive, low false positives
OISD Big Large, tuned for smart home devices

License

This project is licensed under CC BY-NC 4.0.

You are free to share and adapt this material for non-commercial purposes, as long as you give appropriate credit to Cherif Jebali.

Author

Cherif Jebali

Built as a practical project to learn Docker, Linux hardening, and DNS privacy.

Back to Raspberry Pi