Hands-on Lab

Pi-hole en Docker: sinkhole DNS para bloquear anuncios en toda la red

17 de julio de 2026 3 min

0 / 8

Chuleta

¿Te ha servido? No te pierdas el próximo lab

0:00 / 0:00

Publicamos el puerto 53 en TCP y UDP —el DNS usa ambos protocolos, UDP para consultas normales y TCP cuando la respuesta no cabe en un datagrama— y el 80 para el panel web. TZ pone las marcas de tiempo del registro en tu huso horario, FTLCONF_webserver_api_password fija la contraseña del panel (v6 sustituyó la vieja WEBPASSWORD), FTLCONF_dns_listeningMode=ALL hace que escuche en cualquier interfaz, no solo en localhost dentro del contenedor, y FTLCONF_dns_upstreams declara a qué resolvedores reenviar lo que no esté bloqueado: sin esa variable, Pi-hole no reenvía nada.

docker run -d --name pihole -p 53:53/tcp -p 53:53/udp -p 80:80/tcp -e TZ='Europe/Madrid' -e FTLCONF_webserver_api_password='changeme' -e FTLCONF_dns_listeningMode='ALL' -e FTLCONF_dns_upstreams='1.1.1.1;8.8.8.8' pihole/pihole:2026.07.2

Lo hice yo

Comprobamos que el contenedor está healthy, no solo running: la comprobación interna de Pi-hole hace una consulta dig contra sí mismo (pi.hole), así que 'healthy' confirma que el motor DNS de FTL ya responde consultas, no únicamente que el proceso arrancó.

timeout 90 bash -c 'until [ "$(docker inspect -f "{{.State.Health.Status}}" pihole 2>/dev/null)" = "healthy" ]; do sleep 2; done; echo healthy'

Gravity es el proceso que descarga la lista de bloqueo por defecto y la compila en una base de datos local que FTL consulta en cada petición. Lo ejecutamos explícitamente para tener la lista fresca antes de comprobar el bloqueo, aunque el contenedor ya la descarga solo en el primer arranque.

docker exec pihole pihole -g

Lo hice yo

Confirmamos que gravity realmente cargó dominios reales: un recuento de seis cifras demuestra que la base de bloqueo no está vacía, antes de fiarnos de que un dominio concreto vaya a bloquearse.

docker exec pihole pihole-FTL sqlite3 /etc/pihole/gravity.db "SELECT COUNT(DISTINCT domain) FROM vw_gravity;"

Un dominio normal, que no está en ninguna lista de bloqueo, se reenvía tal cual a los resolvedores upstream (1.1.1.1 y 8.8.8.8) y vuelve con su IP real. Esta es la línea base con la que vamos a contrastar el siguiente paso.

dig +noall +answer +time=5 @127.0.0.1 wikipedia.org A

Lo hice yo

doubleclick.net está en la lista de bloqueo por defecto —la propia documentación de Pi-hole lo usa como ejemplo canónico— así que en vez de reenviar la consulta, FTL responde ella misma con 0.0.0.0. El dispositivo recibe una respuesta DNS válida, pero que no apunta a ninguna parte: el anuncio nunca llega a pedirse.

dig +noall +answer +time=5 @127.0.0.1 doubleclick.net A

Lo hice yo

v6 guarda cada consulta en una base SQLite, pihole-FTL.db, en vez del fichero de texto de versiones anteriores. status=1 significa bloqueada por gravity, status=2 reenviada y status=3 servida desde caché: en la salida verás la consulta a doubleclick.net bloqueada junto a wikipedia.org reenviada. Es el mismo dato que alimenta la página Query Log del panel.

docker exec pihole pihole-FTL sqlite3 /etc/pihole/pihole-FTL.db "SELECT datetime(timestamp,'unixepoch') AS ts, domain, status FROM queries ORDER BY id DESC LIMIT 5;"

Lo hice yo

No podemos grabar el panel web en este entorno, pero comprobamos que el servidor que lo sirve responde: un 200 confirma que el login está accesible en el puerto 80 y protegido por la contraseña que fijamos con FTLCONF_webserver_api_password. Detrás de ese login vive el dashboard, con las mismas cifras que acabamos de sacar por línea de comandos.

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1/admin/

Lo hice yo

pihole status es el equivalente en una línea a mirar el semáforo del dashboard: confirma que el DNS está escuchando y que el bloqueo está activo, sin necesidad de abrir el navegador ni consultar la base de datos a mano.

docker exec pihole pihole status

Lo hice yo

Al ser un contenedor de usar y tirar, lo eliminamos junto con su proceso al terminar: docker rm -f para el contenedor si sigue en marcha y lo borra en el mismo paso. No creamos ningún volumen con nombre, así que no queda nada persistente que limpiar aparte.

docker rm -f pihole

Lo hice yo

Confirmamos la limpieza: el filtro por nombre no devuelve ninguna línea, lo que demuestra que el contenedor pihole ya no existe, ni en marcha ni detenido.

docker ps -a --filter name=pihole --format '{{.Names}}'

¿Te ha sido útil este lab? Puntúalo:

Click to rate this post!

[Total: 0 Average: 0]

Qué hace Pi-hole en la práctica

Pi-hole no es un bloqueador de anuncios de navegador: es un resolvedor DNS. Todo dispositivo de tu red que use su dirección como servidor DNS pasa cada consulta por gravity, la lista compilada de dominios de publicidad y rastreo. Si el dominio está en la lista, Pi-hole responde con 0.0.0.0 en vez de reenviar la pregunta a Internet; si no lo está, la reenvía a un resolvedor real (en este lab, 1.1.1.1 y 8.8.8.8) y te devuelve la respuesta legítima. Por eso el bloqueo funciona igual en el navegador, en una app del móvil o en el firmware de una smart TV: no depende de una extensión instalada por dispositivo.

Por qué el contenedor necesita las variables FTLCONF_*

La versión 6 sustituyó variables de entorno como WEBPASSWORD por el prefijo FTLCONF_, que mapea directamente a las claves del fichero de configuración de FTL. En este lab fijamos la contraseña del panel con FTLCONF_webserver_api_password, abrimos el DNS a cualquier interfaz con FTLCONF_dns_listeningMode=ALL y, algo que se olvida a menudo, declaramos los resolvedores upstream con FTLCONF_dns_upstreams: sin esa variable Pi-hole no reenvía nada.

Complementa otras piezas de tu stack self-hosted

Ya vimos cómo instalar Pi-hole con Docker paso a paso y, si buscas una alternativa con su propio cifrado DNS-over-HTTPS integrado, repasa cómo instalar AdGuard Home con Docker. Encontrarás más piezas de infraestructura casera en la categoría Herramientas y el resto de procedimientos comprobados de principio a fin en nuestros laboratorios prácticos.

Referencias oficiales

Para el detalle de cada variable de entorno consulta el repositorio oficial de docker-pi-hole, para el comportamiento exacto del modo de bloqueo NULL la documentación de FTLDNS, y para las versiones publicadas de la imagen el repositorio en Docker Hub.

Preguntas frecuentes

¿Qué es Pi-hole y cómo bloquea anuncios a nivel de DNS?

Pi-hole es un resolvedor DNS que actúa como sinkhole: compara cada consulta con sus listas de dominios de publicidad y rastreo (gravity) y, si coincide, responde él mismo en lugar de reenviarla a Internet. El dispositivo nunca llega a contactar con el servidor del anuncio, así que este no llega a cargar, en cualquier app o dispositivo que use ese DNS.

¿Por qué un dominio bloqueado resuelve a 0.0.0.0 en lugar de fallar?

0.0.0.0 es el modo de bloqueo por defecto de Pi-hole, llamado NULL: es una dirección que ningún servicio real usa, así que la petición del navegador o la app falla al instante en lugar de quedarse esperando un tiempo de espera agotado. Es una respuesta rápida y predecible, no un error de red.

¿Hay que cambiar el DNS del router para bloquear anuncios en todos los dispositivos?

Para un bloqueo verdaderamente de toda la red, sí: apuntas el DNS del router a la IP del contenedor de Pi-hole y cada dispositivo que se conecte lo hereda automáticamente por DHCP. En este lab publicamos el puerto 53 y lo consultamos directamente con dig porque el contenedor no tiene una red de router real a la que apuntar.

¿Puedo ver el registro de consultas sin entrar al panel web?

Sí: Pi-hole v6 guarda cada consulta en una base SQLite (pihole-FTL.db) que puedes leer con pihole-FTL sqlite3 desde la línea de comandos, junto con el estado de cada una (bloqueada, reenviada o servida desde caché). El panel web solo visualiza esos mismos datos.

Chuleta

docker run -d --name pihole -p 53:53/tcp -p 53:53/udp -p 80:80/tcp -e TZ='Europe/Madrid' -e FTLCONF_webserver_api_password='changeme' -e FTLCONF_dns_listeningMode='ALL' -e FTLCONF_dns_upstreams='1.1.1.1;8.8.8.8' pihole/pihole:2026.07.2

```
docker exec pihole pihole -g
```

dig +noall +answer +time=5 @127.0.0.1 wikipedia.org A

dig +noall +answer +time=5 @127.0.0.1 doubleclick.net A

docker exec pihole pihole-FTL sqlite3 /etc/pihole/pihole-FTL.db "SELECT datetime(timestamp,'unixepoch') AS ts, domain, status FROM queries ORDER BY id DESC LIMIT 5;"

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1/admin/

```
docker exec pihole pihole status
```
```
docker rm -f pihole
```

¿Te ha servido? No te pierdas el próximo lab

Suscríbete a la newsletter

Qué hace Pi-hole en la práctica

Por qué el contenedor necesita las variables FTLCONF_*

Complementa otras piezas de tu stack self-hosted

Referencias oficiales

Preguntas frecuentes

¿Qué es Pi-hole y cómo bloquea anuncios a nivel de DNS?

¿Por qué un dominio bloqueado resuelve a 0.0.0.0 en lugar de fallar?

¿Hay que cambiar el DNS del router para bloquear anuncios en todos los dispositivos?

¿Puedo ver el registro de consultas sin entrar al panel web?

Chuleta