Commit 24d494
2026-01-19 20:52:14 mb tech: updated| /dev/null .. secure pi-hole & unifi "chained dns" configuration.md | |
| @@ 0,0 1,98 @@ | |
| + | # Secure Pi-hole & UniFi "Chained DNS" Configuration |
| + | |
| + | 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. |
| + | |
| + | ## The Topology: Chained DNS |
| + | |
| + | 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. |
| + | |
| + | ```mermaid |
| + | flowchart LR |
| + | %% Nodes |
| + | Clients[Network Clients<br/>(Laptops, IoT, Phones)] |
| + | PiHole[("Pi-hole Container<br/>(Ad Blocking)")] |
| + | UniFi[("UniFi Gateway<br/>(Local Names & GeoIP)")] |
| + | Upstream["Secure Upstream DNS<br/>(Quad9 / Cloudflare)"] |
| + | Blocked[("Blocked Domains<br/>(Ads/Trackers)")] |
| + | |
| + | %% Styles |
| + | style PiHole fill:#f9f,stroke:#333,stroke-width:2px |
| + | style UniFi fill:#bbf,stroke:#333,stroke-width:2px |
| + | style Blocked fill:#ff9999,stroke:#333 |
| + | |
| + | %% Connections |
| + | Clients -- "1. DNS Query (Port 53)" --> PiHole |
| + | PiHole -- "2. Blocked?" --> Blocked |
| + | PiHole -- "3. Allowed?" --> UniFi |
| + | UniFi -- "4. Resolve External" --> Upstream |
| + | |
| + | %% Firewall Logic |
| + | subgraph LAN_Security [UniFi Firewall Rules] |
| + | direction TB |
| + | Rule1[Allow: Pi-hole to Internet:53] |
| + | Rule2[Block: All Clients to Internet:53] |
| + | end |
| + | |
| + | ``` |
| + | |
| + | --- |
| + | |
| + | ## Implementation Steps |
| + | |
| + | ### 1. Configure UniFi DHCP (LAN Settings) |
| + | |
| + | Force all network clients to use Pi-hole exclusively. |
| + | |
| + | * **Navigate to:** `UniFi Network` → `Settings` → `Networks` → `[Your LAN]`. |
| + | * **DHCP Service Management:** |
| + | * **DHCP DNS Server:** Uncheck "Auto". |
| + | * **DNS Server 1:** Enter **[Pi-hole IP Address]**. |
| + | * **DNS Server 2:** Leave **BLANK**. |
| + | * *Note: Do not add a secondary public DNS (like 8.8.8.8), or devices will bypass ad-blocking.* |
| + | |
| + | |
| + | |
| + | ### 2. Configure Pi-hole Upstream |
| + | |
| + | Tell Pi-hole to ask the UniFi router for help. This ensures local hostnames (like `printer.local`) resolve correctly. |
| + | |
| + | * **Navigate to:** `Pi-hole Admin` → `Settings` → `DNS`. |
| + | * **Upstream DNS Servers:** |
| + | * Uncheck all pre-set public providers (Google, OpenDNS, etc.). |
| + | * **Custom 1 (IPv4):** Enter **[UniFi Gateway IP]** (usually `192.168.1.1`). |
| + | |
| + | |
| + | * **Advanced Settings:** |
| + | * Enable: "Never forward non-FQDNs". |
| + | * Enable: "Never forward reverse lookups for private IP ranges". |
| + | |
| + | |
| + | |
| + | ### 3. Configure UniFi WAN (Internet Settings) |
| + | |
| + | Define where the router ultimately sends traffic. |
| + | |
| + | * **Navigate to:** `UniFi Network` → `Settings` → `Internet` → `WAN`. |
| + | * **DNS Server:** Uncheck "Auto". |
| + | * **Primary Server:** `9.9.9.9` (Quad9 - recommended for security) or `1.1.1.2` (Cloudflare - malware blocking). |
| + | * *Note: This allows the UniFi security features (Country Blocking/DNS Shield) to apply to the final outbound request.* |
| + | |
| + | --- |
| + | |
| + | ## Security: Preventing Bypass (Port 53 Redirection) |
| + | |
| + | 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. |
| + | |
| + | **Create the following rules in `Settings` → `Security` → `Traffic Rules` (or Firewall):** |
| + | |
| + | 1. **Rule Name:** `Allow Pi-hole DNS` |
| + | * **Action:** Allow |
| + | * **Source:** [Pi-hole IP Address] |
| + | * **Destination:** Port 53 (Any) |
| + | |
| + | |
| + | 2. **Rule Name:** `Block Direct DNS` |
| + | * **Action:** Block |
| + | * **Source:** All Local Networks (LAN/IoT/VLANs) |
| + | * **Destination:** Port 53 |
| + | * *Note: Since the Pi-hole is allowed in Rule 1, this blocks everyone ELSE.* |