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 extensiones de navegador.

Cuándo Usarlo

• Instalar Pi-hole en una Raspberry Pi o host Linux
• Configurar Pi-hole como servidor DNS para una red doméstica
• Agregar o gestionar listas de bloqueo
• Configurar resolución DNS-over-HTTPS (DoH) upstream
• Crear registros DNS locales (ej. nas.home.lan, pi.home.lan)
• Solucionar problemas de dispositivos que pierden acceso a internet después de instalar Pi-hole
• Ejecutar Pi-hole junto con DHCP o en lugar de este

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 verifica contra las listas de bloqueo.
Los dominios bloqueados devuelven una respuesta nula — el anuncio/tracker nunca se carga.
Los dominios permitidos se reenvían a tu resolución upstream (Cloudflare, Google, etc.).

Instalación

Docker (Recomendado)

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

# docker-compose.yml
services:
  pihole:
    image: pihole/pihole:<pinned-release-tag>
    container_name: pihole
    ports:
      - "53:53/tcp"
      - "53:53/udp"
      - "80:80/tcp"          # Admin web
    environment:
      TZ: "America/New_York"
      WEBPASSWORD: "${PIHOLE_WEBPASSWORD}"   # se establece 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 <pinned-release-tag> con una etiqueta de lanzamiento actual de Pi-hole antes de implementar. Evita latest para infraestructura DNS de larga duración para que las actualizaciones sean deliberadas y revisables.

Define PIHOLE_WEBPASSWORD en un archivo .env junto a docker-compose.yml, cámbiale los 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-pi>/admin

Instalación Bare-Metal (Raspberry Pi OS / Debian / Ubuntu)

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

# 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 del instalador 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. Selecciona la interfaz de red (eth0 para cable — recomendado)
# 2. Selecciona DNS upstream (Cloudflare o deja el predeterminado — se puede cambiar después)
# 3. Confirma IP estática
# 4. Instala la interfaz de administración web (recomendado)
# 5. Anota la contraseña de administrador que se muestra al final

Apuntar tu Red a Pi-hole

# Método 1: Cambiar 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: déjalo vacío para un bloqueo estricto, o usa un segundo Pi-hole.
                 Una alternativa pública como 1.1.1.1 mejora la disponibilidad durante
                 el despliegue pero puede eludir el bloqueo porque los clientes pueden consultarla.

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

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

# Método 3: Pi-hole como servidor DHCP (reemplaza el DHCP del router)
  Admin de Pi-hole → Configuración → DHCP → Habilitar
  Deshabilita primero el DHCP en tu 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

# Admin 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 gravedad  (descarga y compila todas las listas de bloqueo)

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

# Verifica qué se está bloqueando en tiempo real:
  Panel → Registro de consultas  (flujo en vivo de consultas DNS con estado de bloqueo/permiso)

DNS-over-HTTPS Upstream

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="<pinned-version>"
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:
# Admin de Pi-hole → Configuración → DNS → DNS upstream personalizado
# Establecer a: 127.0.0.1#5053
# Desmarcar todos los demás resolvers upstream

Registros DNS Locales

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

Nota sobre el nombre 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 seguir el estándar. Evita .local para registros DNS de Pi-hole ya que entra en conflicto con mDNS/Bonjour.

# Admin 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:
  Admin de Pi-hole → DNS local → Registros CNAME
  Dominio: portainer.home.lan → Destino: pi.home.lan

Solución de Problemas

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

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

# Reiniciar DNS de Pi-hole
pihole restartdns

# Revisar registros de consultas para un dispositivo específico
pihole -t                      # Cola en vivo de todas las consultas
# O filtrar por cliente en el registro de consultas del admin web

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

Anti-Patrones

# 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 una alternativa documentada en el router para reversión durante la configuración
# MEJOR: Ejecutar dos instancias de Pi-hole para redundancia; evitar DNS público alternativo para bloqueo estricto

# MALO: Instalar Pi-hole sin una IP estática
# Si la Pi obtiene una nueva IP DHCP, todos los dispositivos pierden DNS
# BUENO: Establecer 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 DHCP del router, luego habilitar DHCP de Pi-hole

# MALO: Nunca actualizar la gravedad (listas de bloqueo)
# Se acumulan nuevos dominios de anuncios y malware — las listas desactualizadas no los detectan
# BUENO: Programar actualización semanal de gravedad: pihole -g (o habilitar en Configuración → API)

Mejores Prácticas

• Asigna a la Pi una IP estática o reserva DHCP antes de instalar Pi-hole
• Usa Pi-hole como DNS primario; para redundancia, agrega un segundo Pi-hole en lugar de un resolver público si necesitas bloqueo estricto
• Habilita DoH (DNS-over-HTTPS) con cloudflared para consultas upstream cifradas
• Establece home.lan como tu dominio local y crea registros DNS para todos tus servicios
• Revisa el registro de consultas ocasionalmente — las consultas bloqueadas te muestran qué están haciendo los dispositivos

Habilidades Relacionadas

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