Home A - Z
Page Index

An Otter Wiki

Blame

24d494 mb tech 2026-01-19 20:52:14
updated
1 
# Secure Pi-hole & UniFi "Chained DNS" Configuration
2
3
This guide details the optimal topology for running Pi-hole in a container alongside a UniFi Router (UDM/USG). This setup ensures ad-blocking, local hostname resolution, and maximum security by preventing DNS bypass.
4
5
## The Topology: Chained DNS
6
7
In this setup, Pi-hole is the **only** DNS server the clients know about. However, Pi-hole uses the UniFi Router as *its* upstream provider. This keeps the router "in the loop" for local device naming and security filtering.
8
9
```mermaid
10
flowchart LR
11
%% Nodes
07b034 mb tech 2026-01-19 21:33:16
updated
12
Clients["Network Clients<br/>(Laptops, IoT, Phones)"]
24d494 mb tech 2026-01-19 20:52:14
updated
13
PiHole[("Pi-hole Container<br/>(Ad Blocking)")]
14
UniFi[("UniFi Gateway<br/>(Local Names & GeoIP)")]
15
Upstream["Secure Upstream DNS<br/>(Quad9 / Cloudflare)"]
16
Blocked[("Blocked Domains<br/>(Ads/Trackers)")]
17
18
%% Styles
19
style PiHole fill:#f9f,stroke:#333,stroke-width:2px
20
style UniFi fill:#bbf,stroke:#333,stroke-width:2px
21
style Blocked fill:#ff9999,stroke:#333
22
23
%% Connections
7a4a78 mb tech 2026-01-19 21:35:37
updated mermaid
24
Clients -->|"DNS Query (Port 53)"| PiHole
25
PiHole -->|"Blocked?"| Blocked
26
PiHole -->|"Allowed?"| UniFi
27
UniFi -->|"Resolve External"| Upstream
07b034 mb tech 2026-01-19 21:33:16
updated
28
29
%% Firewall Logic
30
subgraph LAN_Security ["UniFi Firewall Rules"]
31
direction TB
32
Rule1["Allow: Pi-hole to Internet:53"]
33
Rule2["Block: All Clients to Internet:53"]
34
end
35
```
24d494 mb tech 2026-01-19 20:52:14
updated
36
---
37
38
## Implementation Steps
39
40
### 1. Configure UniFi DHCP (LAN Settings)
41
42
Force all network clients to use Pi-hole exclusively.
43
44
* **Navigate to:** `UniFi Network` → `Settings` → `Networks` → `[Your LAN]`.
45
* **DHCP Service Management:**
46
* **DHCP DNS Server:** Uncheck "Auto".
47
* **DNS Server 1:** Enter **[Pi-hole IP Address]**.
48
* **DNS Server 2:** Leave **BLANK**.
49
* *Note: Do not add a secondary public DNS (like 8.8.8.8), or devices will bypass ad-blocking.*
50
51
52
53
### 2. Configure Pi-hole Upstream
54
55
Tell Pi-hole to ask the UniFi router for help. This ensures local hostnames (like `printer.local`) resolve correctly.
56
57
* **Navigate to:** `Pi-hole Admin` → `Settings` → `DNS`.
58
* **Upstream DNS Servers:**
59
* Uncheck all pre-set public providers (Google, OpenDNS, etc.).
60
* **Custom 1 (IPv4):** Enter **[UniFi Gateway IP]** (usually `192.168.1.1`).
61
62
63
* **Advanced Settings:**
64
* Enable: "Never forward non-FQDNs".
65
* Enable: "Never forward reverse lookups for private IP ranges".
66
67
68
69
### 3. Configure UniFi WAN (Internet Settings)
70
71
Define where the router ultimately sends traffic.
72
73
* **Navigate to:** `UniFi Network` → `Settings` → `Internet` → `WAN`.
74
* **DNS Server:** Uncheck "Auto".
75
* **Primary Server:** `9.9.9.9` (Quad9 - recommended for security) or `1.1.1.2` (Cloudflare - malware blocking).
76
* *Note: This allows the UniFi security features (Country Blocking/DNS Shield) to apply to the final outbound request.*
77
78
---
79
80
## Security: Preventing Bypass (Port 53 Redirection)
81
82
Smart devices (e.g., Chromecasts, Roku) often ignore DHCP settings and try to use Google DNS (`8.8.8.8`) directly. You must block this using UniFi Firewall rules.
83
84
**Create the following rules in `Settings` → `Security` → `Traffic Rules` (or Firewall):**
85
86
1. **Rule Name:** `Allow Pi-hole DNS`
87
* **Action:** Allow
88
* **Source:** [Pi-hole IP Address]
89
* **Destination:** Port 53 (Any)
90
91
92
2. **Rule Name:** `Block Direct DNS`
93
* **Action:** Block
94
* **Source:** All Local Networks (LAN/IoT/VLANs)
95
* **Destination:** Port 53
96
* *Note: Since the Pi-hole is allowed in Rule 1, this blocks everyone ELSE.*