# 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 -->|"DNS Query (Port 53)"| PiHole
    PiHole -->|"Blocked?"| Blocked
    PiHole -->|"Allowed?"| UniFi
    UniFi -->|"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.*