Pi-hole DNS para Homelab

O que Pi-hole DNS para Homelab faz?

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

Quando Usar

• Instalando Pi-hole em um Raspberry Pi ou host Linux
• Configurando Pi-hole como servidor DNS para uma rede doméstica
• Adicionando ou gerenciando listas de bloqueio
• Configurando resolvedores upstream DNS-over-HTTPS (DoH)
• Criando registros DNS locais (ex.: nas.home.lan, pi.home.lan)
• Solucionando problemas em dispositivos que perdem acesso à internet após a instalação do Pi-hole
• Executando Pi-hole junto com ou no lugar do DHCP

Como o Pi-hole Funciona

Fluxo normal (sem Pi-hole):
  Dispositivo → solicita ads.tracker.com → ISP DNS → IP real → anúncios carregam

Com Pi-hole:
  Dispositivo → solicita ads.tracker.com → Pi-hole DNS → bloqueado (retorna 0.0.0.0) → sem anúncio

Todas as consultas DNS passam pelo Pi-hole primeiro.
Pi-hole verifica as listas de bloqueio.
Domínios bloqueados retornam uma resposta nula — o anúncio/rastreador nunca carrega.
Domínios permitidos são encaminhados para seu resolvedor upstream (Cloudflare, Google, etc.).

Instalação

Docker (Recomendado)

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

# docker-compose.yml
services:
  pihole:
    image: pihole/pihole:<versão-fixada>
    container_name: pihole
    ports:
      - "53:53/tcp"
      - "53:53/udp"
      - "80:80/tcp"          # Admin web
    environment:
      TZ: "America/New_York"
      WEBPASSWORD: "${PIHOLE_WEBPASSWORD}"   # definido via arquivo .env ou segredo
      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              # necessário apenas se o Pi-hole servir DHCP

Substitua <versão-fixada> por uma tag de versão atual do Pi-hole antes de implantar. Evite latest para infraestrutura de 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, altere suas permissões para 600 e mantenha-o fora do git — não coloque a senha diretamente no arquivo compose.

Acesse o admin web em: http://<ip-do-pi>/admin

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

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

# Passo 1: Atribuir um IP estático (edite /etc/dhcpcd.conf no Pi OS)
sudo nano /etc/dhcpcd.conf
# Adicione no final:
interface eth0
static ip_address=192.168.3.2/24
static routers=192.168.3.1
static domain_name_servers=192.168.3.1

# Passo 2: Baixe e inspecione o instalador antes de executá-lo.
# Prefira o pacote ou caminho de instalação documentado pelo Pi-hole para seu sistema operacional/versão.
curl -sSL https://install.pi-hole.net -o pi-hole-install.sh
less pi-hole-install.sh   # revise antes de prosseguir

# Passo 3: Execute
bash pi-hole-install.sh

# Siga o instalador interativo:
# 1. Selecione a interface de rede (eth0 para cabeada — recomendado)
# 2. Selecione o DNS upstream (Cloudflare ou deixe o padrão — pode alterar depois)
# 3. Confirme o IP estático
# 4. Instale a interface de admin web (recomendado)
# 5. Anote a senha de admin mostrada no final

Apontando Sua Rede para o Pi-hole

# Método 1: Alterar DNS nas configurações de DHCP do roteador (recomendado)
  Interface de admin do roteador → Configurações de DHCP → Servidor DNS
  DNS Primário: 192.168.3.2  (IP do Pi-hole)
  DNS Secundário: deixe em branco para bloqueio estrito, ou use um segundo Pi-hole.
                 Um fallback público como 1.1.1.1 melhora a disponibilidade durante
                 a implantação, mas pode contornar o bloqueio porque os clientes podem consultá-lo.

  Todos os dispositivos recebem o Pi-hole como DNS automaticamente na próxima renovação de DHCP.
  Forçar renovação: reconecte o Wi-Fi ou execute 'sudo dhclient -r && sudo dhclient' no Linux

# Método 2: DNS por dispositivo (útil para testar antes da implantação em toda a rede)
  Windows: Painel de Controle → Adaptador de Rede → Propriedades IPv4 → definir DNS manualmente
  macOS: Configurações do Sistema → Rede → Detalhes → DNS → definir manualmente
  Linux: /etc/resolv.conf ou NetworkManager

# Método 3: Pi-hole como servidor DHCP (substitui o DHCP do roteador)
  Admin do Pi-hole → Configurações → DHCP → Ativar
  Desative o DHCP no roteador primeiro — dois servidores DHCP na mesma rede causam conflitos
  Vantagem: a resolução de nomes de host funciona automaticamente (dispositivos registram seus nomes)

Gerenciamento de Listas de Bloqueio

# Admin do Pi-hole → Listas de Anúncios → Adicionar nova lista

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

  https://blocklistproject.github.io/Lists/malware.txt
  # domínios de malware

  https://blocklistproject.github.io/Lists/tracking.txt
  # rastreamento/telemetria

# Após adicionar uma lista:
  Ferramentas → Atualizar Gravidade  (baixa e compila todas as listas de bloqueio)

# Se um site for bloqueado que não deveria ser (falso positivo):
  Admin do Pi-hole → Lista Branca → Adicionar domínio
  Exemplo: api.my-legitimate-service.com

# Verifique o que está sendo bloqueado em tempo real:
  Painel → Registro de Consultas  (fluxo de consultas DNS ao vivo com status de bloqueio/permissão)

Upstream DNS-over-HTTPS

DNS-over-HTTPS criptografa suas consultas DNS para que seu ISP não possa ver quais sites você resolve.

# Instale cloudflared (proxy DoH da Cloudflare).
# Prefira o repositório de pacotes da Cloudflare para verificação automática de pacotes assinados.
# Se você baixar um binário diretamente, fixe uma versão e verifique sua soma de verificação.
CLOUDFLARED_VERSION="<versão-fixada>"
curl -LO "https://github.com/cloudflare/cloudflared/releases/download/${CLOUDFLARED_VERSION}/cloudflared-linux-arm64"
# Verifique a soma de verificação/assinatura das notas de lançamento da Cloudflare antes de instalar.
sudo mv cloudflared-linux-arm64 /usr/local/bin/cloudflared
sudo chmod +x /usr/local/bin/cloudflared

# Crie a configuração do cloudflared
sudo mkdir -p /etc/cloudflared
sudo tee /etc/cloudflared/config.yml << EOF
proxy-dns: true
proxy-dns-port: 5053
proxy-dns-upstream:
  - https://1.1.1.1/dns-query
  - https://1.0.0.1/dns-query
EOF

# Crie o serviço systemd
sudo cloudflared service install
sudo systemctl start cloudflared
sudo systemctl enable cloudflared

# Agora aponte o Pi-hole para o proxy DoH local:
# Admin do Pi-hole → Configurações → DNS → DNS upstream personalizado
# Defina para: 127.0.0.1#5053
# Desmarque todos os outros resolvedores upstream

Registros DNS Locais

Torne seus serviços acessíveis por nome (ex.: nas.home.lan, grafana.home.lan).

Nota sobre nome de domínio: .home.lan é amplamente usado em homelabs e funciona na prática. O sufixo reservado pela IETF para uso local é .home.arpa (RFC 8375) — use isso para seguir o padrão. Evite .local para registros DNS do Pi-hole, pois entra em conflito com mDNS/Bonjour.

# Admin do Pi-hole → DNS Local → Registros DNS

  Domínio              IP
  nas.home.lan        192.168.30.10
  pi.home.lan         192.168.30.2
  grafana.home.lan    192.168.30.3
  proxmox.home.lan    192.168.30.4

# De qualquer dispositivo na sua rede:
  ping nas.home.lan        → 192.168.30.10
  http://grafana.home.lan  → seu dashboard do Grafana

# Para subdomínios, adicione um CNAME:
  Admin do Pi-hole → DNS Local → Registros CNAME
  Domínio: portainer.home.lan → Alvo: pi.home.lan

Solução de Problemas

# Pi-hole bloqueando algo que não deveria
pihole -q example.com          # Verifique se o domínio está bloqueado e qual lista
pihole -w example.com          # Coloque na lista branca imediatamente

# DNS não está resolvendo nada
pihole status                  # Verifique se pihole-FTL está em execução
dig @192.168.3.2 google.com   # Teste DNS diretamente contra o Pi-hole

# Reiniciar DNS do Pi-hole
pihole restartdns

# Verifique os registros de consulta para um dispositivo específico
pihole -t                      # Acompanhamento ao vivo de todas as consultas
# Ou filtre por cliente no Registro de Consultas do admin web

# Atualização de gravidade do Pi-hole (atualizar listas de bloqueio)
pihole -g

Anti-Padrões

# RUIM: Depender de um único Pi-hole sem um caminho de recuperação
# Se o Pi-hole travar ou o Pi perder energia, o DNS pode parar de funcionar
# BOM: Mantenha um fallback documentado no roteador para reversão durante a configuração
# MELHOR: Execute duas instâncias do Pi-hole para redundância; evite DNS público de fallback para bloqueio estrito

# RUIM: Instalar o Pi-hole sem um IP estático
# Se o Pi receber um novo IP DHCP, todos os dispositivos perdem DNS
# BOM: Defina IP estático primeiro, depois instale o Pi-hole

# RUIM: Ativar DHCP do Pi-hole sem desativar primeiro o DHCP do roteador
# Dois servidores DHCP na mesma rede distribuem IPs conflitantes
# BOM: Desative o DHCP do roteador, depois ative o DHCP do Pi-hole

# RUIM: Nunca atualizar a gravidade (listas de bloqueio)
# Novos domínios de anúncios e malware se acumulam — listas desatualizadas os perdem
# BOM: Agende atualização semanal da gravidade: pihole -g (ou ative em Configurações → API)

Melhores Práticas

• Atribua um IP estático ou reserva DHCP ao Pi antes de instalar o Pi-hole
• Use Pi-hole como DNS primário; para redundância, adicione um segundo Pi-hole em vez de um resolvedor público se precisar de bloqueio estrito
• Habilite DoH (DNS-over-HTTPS) com cloudflared para consultas upstream criptografadas
• Defina home.lan como seu domínio local e crie registros DNS para todos os seus serviços
• Revise o Registro de Consultas ocasionalmente — consultas bloqueadas mostram o que os dispositivos estão fazendo

Habilidades Relacionadas

• homelab-network-setup
• homelab-vlan-segmentation
• homelab-wireguard-vpn