AdGuard Home: de la interfaz web al filtrado por cliente

E2Reproducido en una VM de laboratorio

Entorno aplicableProbado

Firmware

OpenWrt

Versión

25.12.6

Gestor de paquetes

apk

Equipo

PVE VM 201 / 1GB

Última prueba en laboratorio 2026-10-20Registro de pruebas

Resultado

• AdGuard Home usa el puerto 53 de OpenWrt; la interfaz web está en el 3000.
• dnsmasq pasa al 5353 y sigue sirviendo DHCP.
• Los clientes DHCP reciben 192.168.2.1 como DNS.
• Una regla de filtro personalizada bloquea un dominio de prueba mientras los nombres normales siguen resolviéndose.
• El disco de datos, la configuración de AGH y el filtro sobreviven a un reinicio.

Entorno aplicable y topología

• PVE 9.2.2 con una sola NIC; OpenWrt 25.12.6 x86_64 VM 201 (1GB de RAM, disco de datos de 2GB).
• WAN net0 en vmbr0 (DHCP); LAN net1 en un vmbr2 aislado (192.168.2.0/24).
• AGH 0.107.79 del feed apk de OpenWrt.
• No compartas un mismo puente entre dos VM de OpenWrt que ejecuten DHCP: en este laboratorio la VM 200 está en vmbr1 (192.168.1.0/24), así que la VM 201 debe usar vmbr2 (192.168.2.0/24). De lo contrario, un cliente podría recibir una asignación de la subred equivocada.

Puerto físico	Bridge de PVE	NIC virtual	Interfaz de OpenWrt	Función
nic0	vmbr0	net0	wan DHCP	upstream 192.168.50.1
—	vmbr2	net1	lan 192.168.2.1	AGH + DHCP clients

Puertos y responsabilidades

Puerto	Componente	Función
53	AdGuard Home	DNS de los clientes, filtrado, reenvío upstream
3000	AdGuard Home	interfaz web
5353	dnsmasq	DHCP y DNS local; ya no en el 53

No enlaces AGH y dnsmasq al 53 al mismo tiempo. No apuntes la opción 6 de DHCP a una dirección que no escuche en el 53.

Antes de cambiar nada

Shell del routerHaz una copia de seguridad de la configuración y prepara el disco de datos

cp /etc/config/dhcp /etc/config/dhcp.bak.$(date +%F)
cp /etc/config/adguardhome /etc/config/adguardhome.bak.$(date +%F) 2>/dev/null || true
cat /etc/config/dhcp

Conserva el acceso por consola o LAN a OpenWrt. No hagas que la única vía de administración dependa del DNS que estás cambiando.

EsperadoPuedes restaurar la configuración de dnsmasq/AGH.

Pasos mínimos

La página de bienvenida del primer arranque de AGH 0.107.79. Haz clic en Get Started para abrir el asistente de configuración. Capturado en un laboratorio temporal; está seleccionado el idioma chino.

Shell del routerInstala AGH, las herramientas del disco de datos y el soporte de fstab

apk update
apk add adguardhome block-mount e2fsprogs

e2fsprogs aporta mkfs.ext4; block-mount aporta el servicio fstab. Un mirror local de OpenWrt es válido, pero los paquetes deben seguir pasando la comprobación de firmas.

Esperadoadguardhome, block-mount y e2fsprogs están instalados.

Shell del routerFormatea y haz persistente el disco de datos

Ejecuta esto solo en un disco de datos de laboratorio que hayas confirmado que está vacío:

mkfs.ext4 -F /dev/sdb
mkdir -p /opt/agh
mount /dev/sdb /opt/agh
block info /dev/sdb

Usa el UUID que muestra block info. En LuCI, en Mount Points, establece el destino de ese disco en /opt/agh y actívalo; o busca el @mount[n] correspondiente desde la CLI:

uci show fstab
# find the @mount[n] whose uuid is <your-UUID>
uci set fstab.@mount[n].target='/opt/agh'
uci set fstab.@mount[n].enabled='1'
uci commit fstab
/etc/init.d/fstab enable
block mount
mount | grep /opt/agh

Este laboratorio usó el fstab.@mount[2] detectado automáticamente para el disco de datos de 2GB; cambiar su destino a /opt/agh y activarlo funcionó. No copies el [2]; busca el que coincida con tu UUID.

Esperado/opt/agh está en un disco separado y sobrevive al reinicio.

Shell del routerMueve dnsmasq al 5353

uci set dhcp.@dnsmasq[0].port='5353'
uci commit dhcp
/etc/init.d/dnsmasq restart
netstat -lnp | grep -E ':53|:5353'

Los clientes no pueden resolver en el 53 hasta que AGH arranque.

EsperadoEl puerto 53 queda libre y DHCP sigue funcionando.

Shell del routerInicia AGH y completa la configuración del primer arranque

uci set adguardhome.config.work_dir='/opt/agh/work'
uci commit adguardhome
mkdir -p /opt/agh/work
chown -R adguardhome:adguardhome /opt/agh /etc/adguardhome
/etc/init.d/adguardhome enable
/etc/init.d/adguardhome start
sleep 3
netstat -lnp | grep -E ':3000|:53'

Abre http://192.168.2.1:3000/ y configura:

• puerto web 3000;
• puerto DNS 53;
• un usuario y contraseña de administrador;
• DNS upstream 192.168.50.1 para este laboratorio;
• desactiva DNSSEC si el upstream no lo valida.

Si no tienes navegador, usa la API de configuración de AGH; nunca subas la contraseña de administrador a un repositorio.

EsperadoLa interfaz web es accesible en el 3000.

Shell del routerAnuncia AGH mediante DHCP

uci add_list dhcp.lan.dhcp_option='6,192.168.2.1'
uci commit dhcp
/etc/init.d/dnsmasq restart
uci show dhcp.lan | grep dhcp_option

Cambiar solo el puerto de dnsmasq puede hacer que algunos clientes dejen de recibir DNS; establece la opción 6 de forma explícita.

EsperadoLos clientes reciben 192.168.2.1 como DNS.

LuCIAñade una regla de filtro determinista

En Filters → Custom filtering rules añade:

||blocked.example^

Es un dominio de prueba reservado. Añade listas de filtros mantenidas más adelante para uso real. Verifica con nslookup, no con “la página parece rota”.

Esperadoblocked.example devuelve 0.0.0.0; los nombres normales siguen resolviéndose.

Verificación

El panel tras la configuración. Cero consultas justo después de configurar es normal; verifica primero el puerto DNS y el upstream.

Shell del routerComprueba los puertos y la resolución local

netstat -lnp | grep -E ':53|:3000|:5353'
nslookup blocked.example 192.168.2.1
nslookup openwrt.org 192.168.2.1

Esperado: blocked.example devuelve 0.0.0.0 (IPv6 también puede mostrar ::); openwrt.org devuelve una dirección real.

EsperadoAGH escucha en 53/3000; dnsmasq en 5353.

OrdenadorVerifica desde un cliente DHCP

ip addr show
ip route
cat /etc/resolv.conf
nslookup blocked.example
nslookup openwrt.org

Si el DNS del cliente no es 192.168.2.1, vuelve a la opción 6 de DHCP y al puerto de dnsmasq.

EsperadoEl cliente obtiene 192.168.2.x y DNS 192.168.2.1.

Shell del routerVuelve a verificar tras reiniciar

reboot

Después de reiniciar:

mount | grep /opt/agh
netstat -lnp | grep -E ':53|:3000'
nslookup blocked.example 192.168.2.1
nslookup openwrt.org 192.168.2.1

EsperadoEl disco de datos se monta, AGH arranca y la regla sobrevive.

Ramas de fallo y recuperación

AGH no arranca / el puerto 53 está ocupado

logread | grep -i adguard | tail -50
netstat -lnp | grep ':53'
/usr/bin/AdGuardHome --check-config -c /etc/adguardhome/adguardhome.yaml

Si dnsmasq sigue usando el 53, confirma dhcp.@dnsmasq[0].port='5353'. Si la configuración es incorrecta, restaura la copia de seguridad:

cp /etc/adguardhome/adguardhome.bak.YYYY-MM-DD /etc/adguardhome/adguardhome.yaml
/etc/init.d/adguardhome restart

Los clientes no pueden resolver nada

Devuelve temporalmente el DNS a dnsmasq:

uci set dhcp.@dnsmasq[0].port='53'
uci -q delete dhcp.lan.dhcp_option
uci commit dhcp
/etc/init.d/dnsmasq restart
/etc/init.d/adguardhome stop

Restaura primero la resolución básica y luego depura AGH capa por capa.

El disco de datos no está montado

mount | grep /opt/agh
block info /dev/sdb
logread | grep -i fstab

Revisa el UUID, el destino y el indicador enabled de fstab; monta manualmente y luego reinicia AGH.

El filtrado no funciona

La página de filtros muestra las listas de bloqueo activadas. Esta captura muestra solo las predeterminadas, sin suscripciones de terceros; añade una regla de prueba por separado.

• Confirma que el cliente realmente usa AGH como DNS.
• Confirma que la regla está en Custom filtering rules, no en una suscripción.
• Consulta a AGH directamente: nslookup blocked.example 192.168.2.1.
• El DoH del navegador o del sistema operativo puede saltarse AGH.

Prueba E2 de laboratorio (2026-10-20)

• Entorno: PVE 9.2.2 con una sola NIC; OpenWrt 25.12.6 VM 201 (1GB/disco de datos de 2GB); AGH 0.107.79.
• Puertos: AGH 53 + web 3000; dnsmasq 5353; opción 6 de DHCP 192.168.2.1.
• Cliente: DHCP 192.168.2.166/24, DNS 192.168.2.1; blocked.example → 0.0.0.0, openwrt.org → 64.226.122.113.
• Reinicio: /opt/agh montado mediante fstab; AGH, dnsmasq y las reglas de filtrado se recuperaron; la web devolvió 302.
• No probado: interacción real con la interfaz del navegador, listas de suscripción externas, clientes LAN físicos, IPv6, estabilidad a largo plazo.

Fuentes y revisión

• Este es un registro de laboratorio E2; no ha sido revisado de forma independiente ni probado en una LAN física.
• Receta: tests/recipes/agh-25.12-vm201.md; notas del entorno: docs/agh-e2-run.md.
• Actualiza testedVersions cuando cambie el paquete o la versión; no copies scripts de init entre versiones de firmware.

Registro de pruebasEstado: Reproducido en laboratorio (E2)

Entorno

PVE 9.2.2 con una sola NIC; OpenWrt 25.12.6 VM 201; AGH 0.107.79; vmbr2 192.168.2.0/24

Receta

tests/recipes/agh-25.12-vm201.md

Fecha

2026-10-20

Resultado

AGH 53 + web 3000; dnsmasq 5353; opción 6 de DHCP → 192.168.2.1; el cliente obtiene blocked.example=0.0.0.0 y openwrt.org se resuelve; fstab/reglas/servicio sobrevivieron al reinicio

Reproducido en laboratorio (E2); sin revisión independiente ni prueba en una red física. El E3 sigue necesitando hardware real.

Fuentes

• Paquete adguardhome de OpenWrt
• Documentación de AdGuard Home
• dnsmasq y DHCP en OpenWrt
• fstab / block-mount de OpenWrt