homelab-pihole-dns

Homelab Pi-hole DNS

Pi-hole es un bloqueador de anuncios DNS a nivel de red que se ejecuta en una Raspberry Pi o cualquier host Linux. Cada dispositivo de tu red obtiene bloqueo automático de anuncios y dominios maliciosos, sin necesidad de una extensión de navegador.

Cuándo Usarlo

• Instalando Pi-hole en una Raspberry Pi o host Linux
• Configurando Pi-hole como servidor DNS para una red doméstica
• Agregando o gestionando listas de bloqueo
• Configurando resolutores ascendentes DNS-over-HTTPS (DoH)
• Creando registros DNS locales (ej. nas.home.lan, pi.home.lan)
• Solucionando problemas de dispositivos que pierden acceso a Internet después de instalar Pi-hole
• Ejecutando Pi-hole junto con DHCP o en su lugar

Cómo Funciona Pi-hole

Flujo normal (sin Pi-hole):
  Dispositivo → solicita ads.tracker.com → ISP DNS → IP real → se cargan anuncios

Con Pi-hole:
  Dispositivo → solicita ads.tracker.com → Pi-hole DNS → bloqueado (devuelve 0.0.0.0) → sin anuncio

Todas las consultas DNS pasan primero por Pi-hole.
Pi-hole las compara contra las listas de bloqueo.
Los dominios bloqueados devuelven una respuesta nula: el anuncio/rastreador nunca se carga.
Los dominios permitidos se reenvían a tu resolutor ascendente (Cloudflare, Google, etc.).

Instalación

Docker (Recomendado)

Docker es la forma más sencilla de instalar Pi-hole y facilita las actualizaciones y las copias de seguridad.

# docker-compose.yml
services:
  pihole:
    image: pihole/pihole:<etiqueta-de-versión-fijada>
    container_name: pihole
    ports:
      - "53:53/tcp"
      - "53:53/udp"
      - "80:80/tcp"          # Administración web
    environment:
      TZ: "America/New_York"
      WEBPASSWORD: "${PIHOLE_WEBPASSWORD}"   # configurado mediante archivo .env o secreto
      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              # solo necesario si Pi-hole servirá DHCP

Reemplaza <etiqueta-de-versión-fijada> con una etiqueta de lanzamiento actual de Pi-hole antes de desplegar. Evita latest para infraestructura DNS de larga duración para que las actualizaciones sean deliberadas y revisables.

Establece PIHOLE_WEBPASSWORD en un archivo .env junto a docker-compose.yml, cambia sus permisos a 600 y mantenlo fuera de git: no pongas la contraseña directamente en el archivo compose.

Accede a la administración web en: http://<ip-de-la-pi>/admin

Instalación Directa (Raspberry Pi OS / Debian / Ubuntu)

Pi-hole requiere una IP estática antes de instalarlo.

# Paso 1: Asignar una IP estática (editar /etc/dhcpcd.conf en Pi OS)
sudo nano /etc/dhcpcd.conf
# Agregar al 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

# Paso 2: Descargar e inspeccionar el instalador antes de ejecutarlo.
# Prefiere el paquete o la ruta de instalación documentada por Pi-hole para tu SO/versión.
curl -sSL https://install.pi-hole.net -o pi-hole-install.sh
less pi-hole-install.sh   # revisar antes de continuar

# Paso 3: Ejecutar
bash pi-hole-install.sh

# Sigue el instalador interactivo:
# 1. Seleccionar interfaz de red (eth0 para cableada — recomendada)
# 2. Seleccionar DNS ascendente (Cloudflare o dejar por defecto — se puede cambiar después)
# 3. Confirmar IP estática
# 4. Instalar la interfaz de administración web (recomendado)
# 5. Anotar la contraseña de administrador que se muestra al final

Apuntando tu Red a Pi-hole

# Método 1: Cambiar el DNS en la configuración DHCP del router (recomendado)
  Interfaz de administración del router → Configuración DHCP → Servidor DNS
  DNS primario: 192.168.3.2  (IP de Pi-hole)
  DNS secundario: dejar vacío para bloqueo estricto, o usar un segundo Pi-hole.
                 Un fallback público como 1.1.1.1 mejora la disponibilidad durante
                 el despliegue, pero puede eludir el bloqueo porque los clientes podrían consultarlo.

  Todos los dispositivos obtienen Pi-hole como DNS automáticamente en la próxima renovación de DHCP.
  Forzar renovación: reconectar Wi-Fi o ejecutar 'sudo dhclient -r && sudo dhclient' en Linux

# Método 2: DNS por dispositivo (útil para probar antes del despliegue en toda la red)
  Windows: Panel de control → Adaptador de red → Propiedades de IPv4 → configurar DNS manualmente
  macOS: Configuración del Sistema → Red → Detalles → DNS → configurar manualmente
  Linux: /etc/resolv.conf o NetworkManager

# Método 3: Pi-hole como servidor DHCP (reemplaza el DHCP del router)
  Administración de Pi-hole → Configuración → DHCP → Habilitar
  Deshabilita primero el DHCP del router: dos servidores DHCP en la misma red causan conflictos
  Ventaja: la resolución de nombres de host funciona automáticamente (los dispositivos registran sus nombres)

Gestión de Listas de Bloqueo

# Administración de Pi-hole → Listas de anuncios → Agregar nueva lista de anuncios

# Listas de bloqueo recomendadas:
  https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts
  # predeterminada: más de 200k dominios

  https://blocklistproject.github.io/Lists/malware.txt
  # dominios de malware

  https://blocklistproject.github.io/Lists/tracking.txt
  # rastreo/telemetría

# Después de agregar una lista:
  Herramientas → Actualizar Gravity (descarga y compila todas las listas de bloqueo)

# Si un sitio está bloqueado que no debería (falso positivo):
  Administración de Pi-hole → Lista blanca → Agregar dominio
  Ejemplo: api.my-legitimate-service.com

# Ver qué se está bloqueando en tiempo real:
  Panel → Registro de consultas (transmisión en vivo de consultas DNS con estado de bloqueo/permitido)

DNS-over-HTTPS Ascendente

DNS-over-HTTPS cifra tus consultas DNS para que tu ISP no pueda ver qué sitios resuelves.

# Instalar cloudflared (proxy DoH de Cloudflare).
# Prefiere el repositorio de paquetes de Cloudflare para verificación automática de paquetes firmados.
# Si descargas un binario directamente, fija una versión y verifica su suma de verificación.
CLOUDFLARED_VERSION="<versión-fijada>"
curl -LO "https://github.com/cloudflare/cloudflared/releases/download/${CLOUDFLARED_VERSION}/cloudflared-linux-arm64"
# Verifica la suma de verificación/firma de las notas de lanzamiento de Cloudflare antes de instalar.
sudo mv cloudflared-linux-arm64 /usr/local/bin/cloudflared
sudo chmod +x /usr/local/bin/cloudflared

# Crear configuración de 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

# Crear servicio systemd
sudo cloudflared service install
sudo systemctl start cloudflared
sudo systemctl enable cloudflared

# Ahora apunta Pi-hole al proxy DoH local:
# Administración de Pi-hole → Configuración → DNS → DNS ascendente personalizado
# Establecer en: 127.0.0.1#5053
# Desmarcar todos los demás resolutores ascendentes

Registros DNS Locales

Haz que tus servicios sean accesibles por nombre (ej. nas.home.lan, grafana.home.lan).

Nota sobre nombres de dominio: .home.lan se usa ampliamente en homelabs y funciona en la práctica. El sufijo reservado por el IETF para uso local es .home.arpa (RFC 8375) — úsalo para cumplir con el estándar. Evita .local para registros DNS de Pi-hole, ya que entra en conflicto con mDNS/Bonjour.

# Administración de Pi-hole → DNS Local → Registros DNS

  Dominio              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

# Desde cualquier dispositivo de tu red:
  ping nas.home.lan        → 192.168.30.10
  http://grafana.home.lan  → tu panel de Grafana

# Para subdominios, agrega un CNAME:
  Administración de Pi-hole → DNS Local → Registros CNAME
  Dominio: portainer.home.lan → Destino: pi.home.lan

Solución de Problemas

# Pi-hole bloqueando algo que no debería
pihole -q example.com          # Verificar si el dominio está bloqueado y en qué lista
pihole -w example.com          # Agregar a lista blanca inmediatamente

# DNS no resuelve en absoluto
pihole status                  # Verificar si pihole-FTL se está ejecutando
dig @192.168.3.2 google.com   # Probar DNS directamente contra Pi-hole

# Reiniciar DNS de Pi-hole
pihole restartdns

# Ver registros de consultas para un dispositivo específico
pihole -t                      # Seguimiento en vivo de todas las consultas
# O filtrar por cliente en el Registro de consultas de la administración web

# Actualizar gravity de Pi-hole (refrescar listas de bloqueo)
pihole -g

Antipatrones

# MALO: Depender de un solo Pi-hole sin una ruta de recuperación
# Si Pi-hole se bloquea o la Pi pierde energía, el DNS puede dejar de funcionar
# BUENO: Mantener un fallback documentado en el router para retroceder durante la configuración
# MEJOR: Ejecutar dos instancias de Pi-hole para redundancia; evitar DNS público de respaldo para bloqueo estricto

# MALO: Instalar Pi-hole sin una IP estática
# Si la Pi obtiene una nueva IP por DHCP, todos los dispositivos pierden DNS
# BUENO: Configurar IP estática primero, luego instalar Pi-hole

# MALO: Habilitar DHCP de Pi-hole sin deshabilitar primero el DHCP del router
# Dos servidores DHCP en la misma red entregan IPs conflictivas
# BUENO: Deshabilitar el DHCP del router, luego habilitar el DHCP de Pi-hole

# MALO: Nunca actualizar gravity (listas de bloqueo)
# Se acumulan nuevos dominios de anuncios y malware; las listas desactualizadas los pasan por alto
# BUENO: Programar actualización semanal de gravity: pihole -g (o habilitar en Configuración → API)

Buenas Prácticas

• Asignar a la Pi una IP estática o reserva DHCP antes de instalar Pi-hole
• Usar Pi-hole como DNS primario; para redundancia, agregar un segundo Pi-hole en lugar de un resolutor público si necesitas bloqueo estricto
• Habilitar DoH (DNS-over-HTTPS) con cloudflared para consultas ascendentes cifradas
• Configurar home.lan como tu dominio local y crear registros DNS para todos tus servicios
• Revisar el Registro de consultas ocasionalmente: las consultas bloqueadas te muestran lo que hacen los dispositivos

Habilidades Relacionadas

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