Homelab Pi-hole DNS

Pi-hole é um bloqueador de anúncios DNS para toda a rede que roda em um Raspberry Pi ou qualquer host Linux. Todos os dispositivos na sua rede obtêm bloqueio automático de domínios de anúncios e malware — sem necessidade de extensão de navegador.

Quando Usar

• Instalar o Pi-hole em um Raspberry Pi ou host Linux
• Configurar o Pi-hole como servidor DNS para uma rede doméstica
• Adicionar ou gerenciar listas de bloqueio
• Configurar resolutores upstream DNS-over-HTTPS (DoH)
• Criar registros DNS locais (ex: nas.home.lan, pi.home.lan)
• Solucionar problemas de dispositivos que perdem acesso à internet após a instalação do Pi-hole
• Executar o Pi-hole junto ou em vez do DHCP

Como o Pi-hole Funciona

Normal flow (without Pi-hole):
  Device → requests ads.tracker.com → ISP DNS → real IP → ads load

With Pi-hole:
  Device → requests ads.tracker.com → Pi-hole DNS → blocked (returns 0.0.0.0) → no ad

All DNS queries go through Pi-hole first.
Pi-hole checks against blocklists.
Blocked domains return a null response — the ad/tracker never loads.
Allowed domains get forwarded to your upstream resolver (Cloudflare, Google, etc.).

Instalação

Docker (Recomendado)

Docker é a maneira mais fácil de instalar o Pi-hole e torna as atualizações e backups simples.

# docker-compose.yml
services:
  pihole:
    image: pihole/pihole:<pinned-release-tag>
    container_name: pihole
    ports:
      - "53:53/tcp"
      - "53:53/udp"
      - "80:80/tcp"          # Web admin
    environment:
      TZ: "America/New_York"
      WEBPASSWORD: "${PIHOLE_WEBPASSWORD}"   # set via .env file or secret
      PIHOLE_DNS_: "1.1.1.1;1.0.0.1"
      DNSMASQ_LISTENING: "all"
    volumes:
      - "./etc-pihole:/etc/pihole"
      - "./etc-dnsmasq.d:/etc/dnsmasq.d"
    restart: unless-stopped
    cap_add:
      - NET_ADMIN              # only needed if Pi-hole will serve DHCP

Substitua <pinned-release-tag> por uma tag de lançamento atual do Pi-hole antes de implantar. Evite latest para infraestrutura DNS de longa duração, para que as atualizações sejam deliberadas e revisáveis.

Defina PIHOLE_WEBPASSWORD em um arquivo .env ao lado de docker-compose.yml, conceda permissão a ele com 600, e mantenha-o fora do git — não coloque a senha diretamente no arquivo compose.

Acesse a administração web em: http://<pi-ip>/admin

Instalação Bare-Metal (Raspberry Pi OS / Debian / Ubuntu)

O Pi-hole requer um IP estático antes da instalação.

# Step 1: Assign a static IP (edit /etc/dhcpcd.conf on Pi OS)
sudo nano /etc/dhcpcd.conf
# Add at the bottom:
interface eth0
static ip_address=192.168.3.2/24
static routers=192.168.3.1
static domain_name_servers=192.168.3.1

# Step 2: Download and inspect the installer before running it.
# Prefer the package or installer path documented by Pi-hole for your OS/version.
curl -sSL https://install.pi-hole.net -o pi-hole-install.sh
less pi-hole-install.sh   # review before proceeding

# Step 3: Run
bash pi-hole-install.sh

# Follow the interactive installer:
# 1. Select network interface (eth0 for wired — recommended)
# 2. Select upstream DNS (Cloudflare or leave default — can change later)
# 3. Confirm static IP
# 4. Install the web admin interface (recommended)
# 5. Note the admin password shown at the end

Apontando Sua Rede para o Pi-hole

# Method 1: Change DNS in your router DHCP settings (recommended)
  Router admin UI → DHCP Settings → DNS Server
  Primary DNS: 192.168.3.2  (Pi-hole IP)
  Secondary DNS: leave blank for strict blocking, or use a second Pi-hole.
                 A public fallback such as 1.1.1.1 improves availability during
                 rollout but can bypass blocking because clients may query it.

  All devices get Pi-hole as DNS automatically on next DHCP renewal.
  Force renewal: reconnect Wi-Fi or run 'sudo dhclient -r && sudo dhclient' on Linux

# Method 2: Per-device DNS (useful for testing before network-wide rollout)
  Windows: Control Panel → Network Adapter → IPv4 Properties → set DNS manually
  macOS: System Settings → Network → Details → DNS → set manually
  Linux: /etc/resolv.conf or NetworkManager

# Method 3: Pi-hole as DHCP server (replaces router DHCP)
  Pi-hole admin → Settings → DHCP → Enable
  Disable DHCP on your router first — two DHCP servers on the same network cause conflicts
  Advantage: hostname resolution works automatically (devices register their names)

Gerenciamento de Listas de Bloqueio

# Admin do Pi-hole → Adlists → Adicionar nova adlist

# Listas de bloqueio recomendadas:
  https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts
  # padrão — 200k+ domínios


…