Pi-hole e DNS

O Pi-hole é responsável pela resolução DNS interna do ambiente e sustenta o funcionamento do split DNS, permitindo que os serviços do homelab sejam acessados corretamente dentro da rede.

Esta página deve ser usada como referência operacional para diagnóstico de problemas de acesso.

🎯 Objetivo

fornecer resolução DNS interna estável
permitir split DNS para serviços do homelab
reduzir impacto de falhas de um único resolvedor
facilitar troubleshooting de acesso e conectividade

📋 Resumo operacional

Topologia

Componente	Primário	Backup	Endereço
Pi-hole	RPi	NAS (macvlan)	`192.168.1.11` / `192.168.1.12`
DHCP	UniFi	-	entrega DNS aos clientes

Fonte da verdade

alterações devem ser feitas primeiro no Pi-hole do RPi
sincronização entre instâncias via Nebula Sync

Dependências

UniFi DHCP distribuindo os dois DNS
registros de split DNS consistentes com o VIP do proxy
conectividade entre clientes e ambos os resolvedores

Comandos de validação

nslookup git.scultetus.dev.br
nslookup git.scultetus.dev.br 192.168.1.11
nslookup git.scultetus.dev.br 192.168.1.12
dig git.scultetus.dev.br

Limitações técnicas detalhadas

failover por múltiplos DNS não é HA imediato
cliente pode insistir no DNS primário e demorar a alternar
cache local pode mascarar correções

Última validação

20/04/2026

🧱 Arquitetura

Instâncias

Instância	Papel	Local	Observação
Pi-hole principal	DNS principal da rede	Raspberry Pi	host 24/7 (`192.168.1.11`)
Pi-hole backup	contingência / failover	NAS	macvlan (`192.168.1.12`)

Rede (macvlan)

O Pi-hole backup no NAS utiliza uma rede dedicada via Docker macvlan:

interface própria na rede (192.168.1.12)
isolamento da rede bridge padrão do Docker
evita conflito com portas (especialmente DNS/53)

Isso permite que o Pi-hole funcione como um host independente na rede.

Sincronização

Componente	Função	Observação
Nebula Sync	sincroniza configuração entre os Pi-holes	mantém listas, settings e consistência

garante consistência entre instâncias
evita divergência de bloqueios e registros locais
reduz esforço manual de manutenção

ℹ️ Alterações devem ser feitas preferencialmente no Pi-hole principal.

Integração

Componente	Papel
UniFi DHCP	distribui servidores DNS aos clientes
Pi-hole	resolve domínios internos e externos
Cloudflare	DNS autoritativo externo
Split DNS	resolve domínios internos para IP local

🌐 Padrão de resolução

Fluxo lógico

Cliente → DHCP (UniFi) → DNS recebido (Pi-hole)
                                  ↓
                           Pi-hole resolve:
                     - domínio interno → IP local
                     - domínio externo → upstream

Split DNS (comportamento esperado)

Domínio	Resultado esperado
`git.scultetus.dev.br`	IP interno (NAS)
`mantis.scultetus.dev.br`	IP interno
`portainer.scultetus.dev.br`	IP interno
`pihole.scultetus.dev.br`	IP do Pi-hole

Objetivo do split DNS

evitar hairpin NAT
reduzir latência
manter acesso consistente interno/externo
garantir que o proxy funcione corretamente

🔁 Failover DNS

Estratégia

Ordem	Servidor	Papel
1	Pi-hole no RPi	principal
2	Pi-hole no NAS	backup

Como funciona na prática

DHCP entrega múltiplos DNS
cliente decide qual usar
fallback ocorre apenas após falha percebida
caches influenciam o comportamento

Limitações

⚠️ Esse modelo não é alta disponibilidade real

troca não é imediata
alguns clientes insistem no DNS primário
falhas podem parecer intermitentes
comportamento varia por sistema operacional

⚠️ Pontos de atenção

NAS não é 24/7
split DNS incorreto gera inconsistência
cache local pode mascarar mudanças
múltiplos registros podem gerar respostas duplicadas

🧪 Troubleshooting (fluxo recomendado)

1. Verificar resolução DNS

nslookup git.scultetus.dev.br

ou:

dig git.scultetus.dev.br

2. Validar DNS específico

nslookup git.scultetus.dev.br 192.168.1.11

👉 confirma se o Pi-hole está correto

3. Verificar DNS em uso

macOS:

scutil --dns

ou:

ipconfig getpacket en0

4. Diferenciar DNS vs aplicação

curl -I http://IP_DO_SERVIÇO

👉 se isso funciona, o problema não é DNS

5. Testar hostname completo

curl -k -I https://git.scultetus.dev.br

6. Limpar cache

sudo dscacheutil -flushcache
sudo killall -HUP mDNSResponder

7. Validar qual Pi-hole respondeu

nslookup git.scultetus.dev.br

→ observar qual servidor respondeu (principal ou backup)

👉 útil para verificar comportamento de failover

🔍 Diagnóstico rápido

Sintoma	Interpretação
resolve para IP público	split DNS não aplicado
alterna IP	cache antigo
interno falha / externo funciona	DNS interno errado
resolve mas não conecta	problema no proxy
resposta dupla	conflito DNS interno + externo

🧭 Fluxo mental de diagnóstico

Resolveu o nome?
  ↓ não → DNS
  ↓ sim
Conecta no IP?
  ↓ não → serviço
  ↓ sim
HTTPS funciona?
  ↓ não → proxy / SSL / Authelia

✅ Boas práticas

manter RPi como DNS principal
configurar dois DNS no DHCP
padronizar nomes internos
revisar registros após mudanças
sempre validar DNS antes do proxy
documentar alterações relevantes

📌 Observação importante

ℹ️ O VIP 192.168.1.20 com keepalived é utilizado pelo Nginx Proxy Manager (NPM), não pelo Pi-hole.

📌 Referências rápidas

DHCP → UniFi
DNS principal → Pi-hole (RPi)
DNS backup → Pi-hole (NAS)
DNS externo → Cloudflare
Proxy → NPM (VIP + keepalived)