ShieldDNS is a high-performance, hardened, privacy-focused DNS solution supporting DNS-over-TLS (DoT), DNS-over-HTTPS (DoH), DNS-over-QUIC (DoQ) and standard DNS.
It features a premium Admin Dashboard with persistent SQLite-backed analytics, custom rule management, and a powerful Filtering Engine compatible with AdGuard, Pi-hole, and uBlock origin lists.
- 🔒 Secure DNS: Native support for DNS-over-TLS (DoT) (port 853), DNS-over-HTTPS (DoH) (port 443), and DNS-over-QUIC (DoQ) — zero extra setup needed.
- 📊 Persistent Analytics: SQLite-backed query history and advanced analytics (Top Blocked Domains, Top Clients).
- 🏳️ Custom Rules: Instantly allow or block individual domains via the Admin UI. Input is auto-sanitized — paste a full URL if you like!
- 🛡️ DNS Filtering: Integrated engine for blocklists with automatic updates and deduplication.
- 🔌 Protection Kill-Switch: Instantly disable all filtering via the dashboard or API.
- ⚡ Optimized Performance: Intelligent caching, prefetching, and Serve Stale support for instant responses even when upstreams are slow.
- 🔐 Secure Admin: Mandatory password protection (bcrypt) for the Admin UI on port 443.
- 📱 Modern Protocols: Perfect for Android Private DNS and standard system-wide filtering (iOS
.mobileconfigwith DoT/DoH/DoQ support). - ⚡ Live Monitoring: Real-time query log updates via Server-Sent Events (SSE).
- 🧠 Smart DNS: Automatic upstream selection based on live latency (RTT) with Broadcast Mode for ultra-low latency.
- 🌙 Dark & Light Mode: Full theme support, persisted locally per user.
- 🔄 Config Backup & Restore: One-click backup download and in-browser JSON configuration restore.
- ⚡ 1-Click Allow / Block: Directly allow or block any domain from the live Query Log table.
- 🔍 Client IP Diagnostics: Clickable Client IPs in logs with detailed GeoIP, Reverse DNS, and history preview.
- 🧹 Optimized Default Lists: Ships with a single, curated default (HaGeZi Multi Normal) for maximum protection with minimal RAM usage on any hardware — including Raspberry Pi.
I maintain this Project in my free time alongside my regular job — bug hunting, new features, and keeping up with OCI updates. Every donation helps me stay independent and dedicate more time to open-source work.
This project is and will always remain 100% free.
Donations are completely voluntary — but the more support I receive, the more time I can realistically invest into these projects. 💪
ShieldDNS is a modern, lightweight alternative to established solutions like AdGuard Home or Pi-hole. It was built with a focus on performance (CoreDNS-based) and native support for encrypted DNS (DoT/DoH).
| Feature | ShieldDNS 🛡️ | AdGuard Home | Pi-hole |
|---|---|---|---|
| Base | CoreDNS (Go) | Cloudflare Go | dnsmasq (C) |
| DoT (Port 853) | Native ✅ | Native ✅ | Requires Unbound ❌ |
| DoH (Port 443) | Native ✅ | Native ✅ | Requires cloudflared ❌ |
| DoQ (QUIC) | Native ✅ | Native ✅ | ❌ |
| Performance | Ultra-High (Go/WAL) | High | Moderate (dnsmasq) |
| Analytics | SQLite (WAL/Batching) | Internal (Local) | FTL (C/Stats) |
| Hardening | AEAD-only Ciphers | Standard | Upstream Dependent |
| Home Assistant | HA App Available | HA App Available | HA App Available |
- Pros: Incredibly performant thanks to the CoreDNS core; native DoT/DoH/DoQ support; modern security stack; transaction-safe logging via SQLite WAL; real-time SSE updates.
- Cons: Focused feature set designed for efficiency.
- Pros: Very comprehensive user interface; supports DNS-over-QUIC; integrated parental controls.
- Cons: Can be more resource-intensive with many clients; more closed architecture.
- Pros: Massive community support; runs on almost any hardware; very detailed statistics.
- Cons: Based on
dnsmasq; lacks native DoT/DoH support (often requires additional Docker containers likeunbound).
services:
shielddns:
image: ghcr.io/faserf/shielddns:latest
ports:
- "53:53/udp" # DNS (UDP)
- "53:53/tcp" # DNS (TCP)
- "853:853/tcp" # DoT
- "443:443/tcp" # Admin Dashboard (HTTPS)
environment:
- UPSTREAM_DNS=86.54.11.100, 1.1.1.1, 9.9.9.9, 8.8.8.8, 1.0.0.1 # Max 5
- UPSTREAM_DOT=unfiltered.joindns4.eu, dns.quad9.net, one.one.one.one # Max 5
- PREFER_ENCRYPTED=true
- LOG_LEVEL=info
- DATA_DIR=/etc/shielddns
volumes:
- ./ssl:/ssl
- ./data:/etc/shielddns # Persistent config, database, and listsIf you prefer the command line, use the following to build and run with persistence:
docker build -t shielddns:local .
docker run -d \
--name shielddns \
-p 53:53/udp -p 53:53/tcp \
-p 443:443/tcp -p 853:853/tcp \
-v $(pwd)/data:/etc/shielddns \
-v $(pwd)/ssl:/ssl \
shielddns:localTo ensure your configuration, query logs, and SSL certificates are saved across container updates and restarts, you must mount the following directories:
/etc/shielddns(Config, SQLite Database, Blocklists)/ssl(Your certificates, or where ShieldDNS generates fallback ones)
On many Linux systems (like Ubuntu), systemd-resolved uses port 53 by default. To use ShieldDNS, you must disable the stub listener on your host:
- Edit
/etc/systemd/resolved.confand setDNSStubListener=no. - Run
sudo ln -sf /run/systemd/resolve/resolv.conf /etc/resolv.conf. - Restart the service:
sudo systemctl restart systemd-resolved.
Oracle Cloud VMs have multiple layers of firewalls. For 2026, the recommended approach is as follows:
- OCI Console: Use the search bar to find Network Security Groups. Add ingress rules for UDP 53 and TCP 53, 443, 853.
- Host Firewall (iptables):
sudo iptables -I INPUT -p udp --dport 53 -j ACCEPT
sudo iptables -I INPUT -p tcp -m multiport --dports 53,443,853 -j ACCEPT
sudo netfilter-persistent saveShieldDNS includes a secure, granular API key system for remote monitoring and automation (e.g., Home Assistant integration).
Authenticate by sending your API key in the X-API-Key header or as a Bearer token in the Authorization header.
ShieldDNS uses a Role-Based Access Control model. Tokens can be restricted to:
read:stats: Dashboard metrics and analytics history.read:logs: Sensitive data including Query Logs and Client IPs.read:system: System terminal logs, SSL diagnostics, and backups.write:filtering: Toggle the global protection/filtering engine.read:all: Grant all read-only permissions above.
/api/health/live: Public endpoint for container liveness checks (No authentication required)./api/health/ready: System readiness check (Requiresread:systempermission).
Important
Security Guard Policy: If no API keys are defined in the Settings, all token-based authentication attempts are rejected by default.
Access the dashboard at https://your.domain/.
On your first visit, a multi-step setup wizard will guide you through:
- Security: Setting a strong administrative password (hashed with bcrypt).
- Upstream DNS: Selecting your preferred DoT and standard DNS providers.
- Protection: Choosing from a curated catalog of industry-standard blocklists.
ShieldDNS now stores your query history in a persistent SQLite database:
- Query History: View the last 100 queries or search through historical data.
- Top Blocked Domains: identify the most aggressive trackers on your network.
- Top Clients: See which devices are generating the most traffic.
- Hourly Trends: 24-hour traffic visualization shows you exactly when your network is most active.
- Live Logs: Zero-latency query streaming via Server-Sent Events (SSE).
- Client IP Diagnostics: Interactive query logs where clicking an IP reveals GeoIP location, Reverse DNS hostname, and a client-specific query history preview.
- Cache Hit Ratio: Real-time diagnostic tracker showing the percentage of queries served from the local cache.
Immediately take control of your network without managing external lists:
- Custom Blocklist: Instantly block any domain (e.g.,
tiktok.com). Paste a full URL — it's auto-sanitized to a clean domain. - Custom Allowlist: Ensure critical domains are never blocked.
- 1-Click Allow/Block: Act on any domain directly from the live Query Log without copy-pasting.
- Intelligent Caching: Large 10k entry cache reduces upstream lookups.
- IP Info Caching: In-memory caching for GeoIP and Reverse DNS lookups (cached for 24h) to ensure zero-latency UI interaction.
- Prefetching: ShieldDNS proactively refreshes popular records before they expire.
- Upstream Probing: Background health checks every 30 seconds ensure you only use healthy upstreams.
- Smart Selection: Optionally reorder upstreams dynamically to always use the lowest-latency provider.
- Data Retention: Configurable history purging (e.g., 7, 30, 90 days) for privacy and disk management.
- System Backups: One-click
.zipbackup of configuration and query history. - Config Restore: Upload a
config.jsondirectly from the Settings page to instantly restore a previous configuration. - Dark & Light Mode: Toggle the UI theme — preference is saved locally.
- Optimized Default Lists: Ships with a single curated default (HaGeZi Multi Normal). Avoids enabling multiple overlapping lists (e.g., OISD + HaGeZi + AdGuard) by default, which would triple RAM usage with near-zero added coverage.
- Streaming Blocklist Downloader: Lists are processed line-by-line via streaming (not loaded fully into RAM) — critical for low-memory hardware like Raspberry Pi 3/4.
- Structured Log Parsing: Uses CoreDNS structured log format for robust, format-change-resistant query parsing.
- Android: Go to Settings > Network > Private DNS and enter your domain (e.g.,
dns.example.com). Modern Android versions will automatically attempt DoT first. For DoQ, use a supporting app like Nebulo or Personal DNS Filter. - iOS/macOS: Download the
.mobileconfigfrom your ShieldDNS dashboard. It implements both DoT and DoH. For native DoQ, ensure you are on iOS 17+.
DNS-over-QUIC is the fastest encrypted protocol as it eliminates TCP head-of-line blocking by using UDP/443. ShieldDNS supports it natively on port 853 (UDP).
Standard "Private DNS" uses DoT. To use DoQ for superior performance on mobile data:
- Install: Google Intra or AdGuard for Android.
- Configure: In the app settings, add a custom server using the QUIC scheme:
quic://your.domain:853
For native DoQ support on modern iPhones:
- Ensure Port 853 (UDP) is open in your firewall.
- App Approach: Use DNSecure. Add a "DNS-over-QUIC" configuration and enter your domain.
- Profile Approach: The
.mobileconfiggenerated by ShieldDNS includes a DoQ payload. If you are on iOS 17+, it will automatically be available in Settings > VPN & Device Management > DNS.
If using ShieldDNS as an upstream for another server:
quic://your.domain:853
If you host ShieldDNS publicly and want to route your entire home network through it via an OpenWrt router, follow these steps:
Navigate to Network > DHCP and DNS in LuCI:
- DNS forwardings: Enter the IP of your ShieldDNS server (e.g.,
94.31.75.54). - Fallback: Add a secondary DNS server (e.g.,
1.1.1.1) as a second entry. - Strict Order: (Optional) In the Advanced Settings tab, check
Strict Orderto ensure ShieldDNS is always tried first.
To prevent devices from bypassing ShieldDNS by using hardcoded DNS servers (like 8.8.8.8), add a NAT rule under Network > Firewall > Traffic Rules > DNAT:
- Protocol:
UDP,TCP - Source zone:
lan - Destination port:
53 - Action:
DNAT - Rewrite IP: (Select your router's LAN IP)
- Rewrite port:
53
This forces all DNS traffic on your network to go through the router's DNSmasq, which then forwards it to ShieldDNS.
ShieldDNS is built for extreme reliability in production environments:
- Graceful Shutdown: SIGTERM/SIGINT handling ensures all buffered logs are flushed to SQLite and connections are closed safely, preventing data corruption.
- IPv6 Robustness: Native support for IPv6 client IP extraction using
net.SplitHostPort. - Brute-Force Protection: Intelligent rate-limiting on the
/api/loginendpoint (max 5 attempts/min/IP). - Modern TLS: Enforced AEAD-only cipher suites (TLS 1.2/1.3) for all management and DNS-over-TLS endpoints.
- Password: Use a strong, unique password for the Admin UI.
- Certificates: Use valid Let's Encrypt certificates for both DoT and the Admin UI.
- Firewall: Only expose ports 53, 443, and 853.
The preset catalog is organized by category. For most home users, the following configuration offers the best balance of protection vs. compatibility:
| Scenario | Recommended Lists |
|---|---|
| Minimal (fast, few false positives) | HaGeZi Multi (Light) |
| Balanced (recommended default ✅) | HaGeZi Multi (Normal) |
| Max Protection | HaGeZi Multi (Pro) + HaGeZi TIF |
| + Malware/Phishing | + HaGeZi TIF (Threat Intelligence) |
| + Adult Content Blocking | + OISD NSFW |
| + Regional (German) | + KADhost (German Blocklist) |
Warning
Avoid enabling multiple large lists in the same category at once (e.g., HaGeZi Normal + OISD Full + AdGuard Main). These lists overlap heavily — using all three triples your RAM consumption without adding meaningful coverage.
Tip
UI Feedback: When lists are downloading, real-time progress entries appear in the System Logs tab. On first setup with many large lists, the dashboard may take 1–2 minutes to populate blocklist data — this is normal.
To verify that your devices are correctly using ShieldDNS and that filtering is active, you can visit the following built-in test URL in your browser:
👉 http://shielddns-maleware.test
This test domain is permanently blocked at the system level regardless of which blocklists you have enabled. If ShieldDNS is working correctly, you will see the official ShieldDNS "Website Blocked" page.
Note
For the block page to be reachable by network clients, you must set the Block Page IP to your ShieldDNS server's actual IP address in the Settings or via the BLOCK_PAGE_IP environment variable.
ShieldDNS uses Go's standard testing package with a fully in-memory test environment (no Docker required).
# Run all tests
cd admin
go test ./... -v
# Run a specific test
go test ./... -run TestProcessList_StreamingMemoryEfficiency -v| Area | Test File | What's Covered |
|---|---|---|
| Blocklist streaming parser | config_test.go |
AdBlock/hosts/dnsmasq/allowlist formats, streaming line-by-line download |
| CoreDNS log parser | dns_test.go |
Structured log format, blocked detection, SSE broadcast, latency parsing |
| API handlers | main_test.go, api_test.go |
Stats, search, history, auth, token management |
| Upstream health & smart sorting | main_test.go |
Latency-based upstream ordering, Corefile generation |
| Presets integrity | presets_test.go |
Default preset list availability |
ShieldDNS has full first-class Home Assistant support:
-
Official HA Addon (run ShieldDNS directly inside Home Assistant with Ingress support): 👉 hassio-addons / ShieldDNS
-
Official HA Integration (expose ShieldDNS stats and controls as sensors/services in Home Assistant): 👉 ha-shielddns
ShieldDNS stands on the shoulders of giants. We would like to express our profound gratitude to the following projects:
- CoreDNS: The incredibly fast, flexible, and robust CNCF-hosted DNS server that powers the core naming resolution engine of ShieldDNS.
- AdGuard Home & Pi-hole: The trailblazers in network-wide ad-blocking. Their pioneering ideas, standard-setting filter list syntax, and community-driven approach deeply inspired the development and feature-set of ShieldDNS.
ShieldDNS is released under the ShieldDNS Personal & Internal Commercial License.
✅ Allowed (Free):
- Personal and home usage.
- Internal business/company usage to protect your own networks or employees.
❌ Prohibited (Without Permission):
- Commercial hosted services (e.g., offering ShieldDNS as a paid cloud service or SaaS).
- Reselling the software or packaging it into a commercial product for profit.
For the full legal text, please review the LICENSE file.