====== 🛡 Pi-hole DNS & Network Ad Blocking ======

Pi-hole provides the primary **DNS, network-wide ad blocking**, and **local hostname resolution** inside the TorresVault environment.  
Two Pi-hole nodes run behind a virtual IP (VIP) for high availability, ensuring DNS services remain stable even during maintenance or reboots.

This page provides a high-level overview of the Pi-hole design, configuration, VIP behavior, and role in the broader TorresVault network.

----

===== Role in TorresVault =====

Pi-hole serves several critical functions:

  * Network-wide ad blocking  
  * Local DNS + host overrides  
  * Fast internal resolution for all `*.torresvault.com` services  
  * DNS filtering for IoT, servers, and Home Assistant  
  * Unified DNS resolver for the entire UniFi network  
  * Supports VLANs 1, 10, 20, 50, and 60  

It is the **first-hop** DNS for every device in the environment, including IoT, Kubernetes VMs (future), and internal services.

----

===== Architecture =====

Pi-hole is deployed as a **redundant pair**:

  * **Pi-hole 1** — runs on 192.168.1.2 (MAC ending in 51:24)
  * **Pi-hole 2** — runs on 192.168.1.4 (MAC ending in 38:DE)
  * **VIP (Virtual IP): 192.168.1.5** — the unified DNS endpoint

All clients point to the **VIP** so failover is seamless.

UniFi DHCP automatically hands out:

  * **Primary DNS:** 192.168.1.5  
  * **Domain:** `torresvault.com`  

This enables short-hostname access (e.g., `pve1`, `pve2`, `jellyfin`, `npm`, `in`) with no additional configuration.

----

===== What Pi-hole Resolves =====

Pi-hole acts as the internal authoritative DNS for key services:

^ Domain ^ IP Address ^
| ha.torresvault.com | 192.168.20.149 |
| hatest.torresvault.com | 192.168.20.150 |
| in.torresvault.com | 192.168.1.27 |
| jellyfin.torresvault.com | 192.168.1.86 |
| matrix.torresvault.com | 192.168.60.56 |
| megatree.torresvault.com | 192.168.60.55 |
| monitor.torresvault.com | 192.168.1.77 |
| next.torresvault.com | 192.168.1.75 |
| npm.torresvault.com | 192.168.1.99 |
| pbs.torresvault.com | 192.168.1.252 |

These DNS overrides are critical for:

  * Home Assistant integrations  
  * FPP multi-controller sync  
  * NGINX Proxy Manager  
  * Prometheus/Grafana  
  * Internal web services & dashboards  

----

===== VLAN Awareness =====

Pi-hole must respond appropriately across all VLANs:

  * VLAN 1 — Servers, Proxmox, NPM, NAS  
  * VLAN 10 — User WiFi  
  * VLAN 20 — IoT  
  * VLAN 50 — WPA3-capable IoT  
  * VLAN 60 — FPP lighting network  

Because the VIP sits on **VLAN 1**, other VLANs reach it through UniFi routing with no issue.

All VLANs use the same DNS resolver for consistency.

----

===== Ad Blocking =====

Pi-hole blocks ads, trackers, malware domains, telemetry, and known phoning-home services.

This benefits:

  * Phones  
  * TVs  
  * Tablets  
  * IoT devices  
  * Media players  
  * Browsers across the entire house  

Blocked domains reduce:

  * bandwidth usage  
  * clutter  
  * tracking  
  * device noise  

----

===== Integration With Other Systems =====

Pi-hole integrates cleanly with:

  * **Home Assistant**  
    * DNS lookups for HA → FPP, HA → Proxmox, HA → NPM  
    * Pi-hole statistics displayed via HA sensors  

  * **UniFi Network**  
    * DHCP hands out Pi-hole VIP  
    * Gateway offloads DNS workload to Pi-hole  

  * **NPM**  
    * Internal service resolution  
    * CNAME simplification  

  * **Proxmox & PBS**  
    * VM naming resolution  
    * Snapshot/backup jobs that rely on hostname lookups  

----

===== Current State =====

  * Fully functioning dual-node Pi-hole deployment  
  * VIP failover works as designed  
  * All internal services use short hostnames  
  * All VLANs properly resolve through Pi-hole  
  * Integrated into Home Assistant dashboards  

----

===== Future Enhancements =====

  * Add **DNS-based device-based filtering rules**  
  * Enable **Pi-hole → Loki / Grafana log ingestion**  
  * Expand blacklist/whitelist automation  
  * Add local DNS automation from Home Assistant  
  * Include DNS health checks in network dashboard  
  * Add backup/restore automation to TrueNAS or NPM  

----

''This page documents the Pi-hole DNS + Ad Blocking platform used inside TorresVault.''