homelab-pihole-dns

Homelab Pi-hole DNS

O Pi-hole é um bloqueador de anúncios DNS em toda a rede que roda em um Raspberry Pi ou em qualquer host Linux. Cada dispositivo da sua rede recebe bloqueio automático de anúncios e domínios maliciosos — sem necessidade de extensões de navegador.

Quando Usar

• Instalando o Pi-hole em um Raspberry Pi ou host Linux
• Configurando o 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)
• Resolvendo problemas de dispositivos que perdem acesso à internet após a instalação do Pi-hole
• Executando o Pi-hole junto com DHCP ou em seu lugar

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 primeiro pelo Pi-hole.
O 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 o 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:<tag-de-versao-fixa>
    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 for servir DHCP

Substitua <tag-de-versao-fixa> 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, altere as permissões para 600 e mantenha 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)

O 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 instalador documentado pelo Pi-hole para seu SO/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 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: Altere o DNS nas configurações DHCP do roteador (recomendado)
  Interface de admin do roteador → Configurações DHCP → Servidor DNS
  DNS Primário: 192.168.3.2  (IP do Pi-hole)
  DNS Secundário: deixe em branco para bloqueio rigoroso, 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 DHCP.
  Renovação forçada: 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 → defina DNS manualmente
  macOS: Ajustes do Sistema → Rede → Detalhes → DNS → defina 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 → Adlists → Adicionar nova adlist

# 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 Gravity (baixa e compila todas as listas de bloqueio)

# Se um site for bloqueado indevidamente (falso positivo):
  Admin do Pi-hole → Whitelist → Adicionar domínio
  Exemplo: api.my-legitimate-service.com

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

DNS-over-HTTPS Upstream

O DNS-over-HTTPS criptografa suas consultas DNS para que sua operadora 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="<versao-fixa>"
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 como: 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 pelo IETF para uso local é .home.arpa (RFC 8375) — use esse 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 painel 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

Resolução de Problemas

# Pi-hole bloqueando algo que não deveria
pihole -q exemplo.com              # Verifique se o domínio está bloqueado e qual lista
pihole -w exemplo.com              # Adicionar à whitelist imediatamente

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

# Reiniciar DNS do Pi-hole
pihole restartdns

# Verificar logs de consultas para um dispositivo específico
pihole -t                           # Tail ao vivo de todas as consultas
# Ou filtre por cliente no Log de Consultas do admin web

# Atualização do gravity 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 de roteador documentado 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 rigoroso

# 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 o IP estático primeiro, depois instale o Pi-hole

# RUIM: Ativar o DHCP do Pi-hole sem desativar o DHCP do roteador primeiro
# 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 o gravity (listas de bloqueio)
# Novos domínios de anúncios e malware se acumulam — listas desatualizadas os perdem
# BOM: Agende uma atualização semanal do gravity: 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 o 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 rigoroso
• Ative o 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 Log de Consultas ocasionalmente — consultas bloqueadas mostram o que os dispositivos estão fazendo

Habilidades Relacionadas

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