Instalador de dnsproxy

Instalación local de AdGuard dnsproxy para Debian 12/13 y Ubuntu LTS 22.04/24.04/26.04, en x86_64 y ARM64, con systemd. El mismo procedimiento sirve para máquinas físicas y VPS.

Por defecto instala sólo el servicio en 127.0.0.1:5354, UDP y TCP. No cambia el DNS del sistema, el puerto 53, el firewall, los límites del kernel ni la configuración de otros servicios.

Instalación

Puedes descargar el instalador autoportante del repositorio público por HTTPS e instalar el servicio con este comando:

curl --fail --show-error --location --proto '=https' --proto-redir '=https' \
  --output install-dnsproxy.sh \
  'https://git.jeserga.es/jeserga/dnsproxy/raw/branch/main/install-dnsproxy.sh' &&
sudo bash install-dnsproxy.sh install --yes

Si quieres revisar el archivo antes de instalarlo, ejecuta sólo la descarga y léelo antes de usar sudo bash. Una vez descargado, no requiere acceso a este repositorio durante su ejecución. Necesita acceso HTTPS a GitHub y a los repositorios APT de la distribución.

Para consultar las opciones, simular una instalación o comprobar el servicio instalado:

bash install-dnsproxy.sh --help
bash install-dnsproxy.sh install --dry-run
sudo dnsproxyctl doctor

El instalador necesita ejecutarse desde un archivo: no se admite curl | bash. En una instalación nueva descarga la última versión estable oficial, verifica SHA-256 y prueba el candidato antes de sustituir el binario. Puedes fijar una versión con --version v0.86.0; la versión mínima es v0.86.0.

El perfil inicial usa load_balance, HTTP/3 habilitado, tiempo de espera de diez segundos, verificación TLS y agrupación de consultas idénticas. La caché y los sondeos periódicos están desactivados.

Principales, en orden escrito:

quic://dns.quad9.net:853
tls://dns.quad9.net:853
quic://dns.nextdns.io:853
quic://p0.freedns.controld.com:853
https://dns9.quad9.net/dns-query

Respaldos:

tls://p0.freedns.controld.com:853
h3://cloudflare-dns.com/dns-query
h3://dns.google/dns-query

El bootstrap utiliza 9.9.9.10:53, 149.112.112.10:53, [2620:fe::10]:53 y [2620:fe::fe:10]:53. La ausencia de conectividad IPv6 no deshabilita las respuestas AAAA.

El orden no establece prioridad: el balanceo elige un principal ponderando su latencia. Ante errores prueba otros principales; los respaldos compiten en paralelo si fallan todos.

Configuración y operaciones

La configuración está en /etc/dnsproxy: listas editables, config.yaml nativo escrito con sintaxis JSON compatible con YAML, y metadatos installer.json. Las actualizaciones conservan la configuración. No edites las unidades generadas sin reconciliar sus cambios antes de otra operación administrativa.

sudo dnsproxyctl status
sudo dnsproxyctl doctor
sudo dnsproxyctl update
sudo dnsproxyctl update --version v0.86.0
sudo dnsproxyctl auto-update enable
sudo dnsproxyctl auto-update disable
sudo dnsproxyctl rollback
sudo dnsproxyctl uninstall

Una reinstalación ordinaria no cambia versión, configuración ni reinicia el servicio. Para renovar sólo el motor desde un archivo nuevo, usa install --upgrade-installer. install --reset-defaults restablece el perfil explícitamente y conserva una copia. Para instalaciones nuevas se admiten --listen-address 127.0.0.1|::1, --listen-port, --cache, --cache-size en bytes, --timeout, --keep-warm-dot y --enable-auto-update. Las escuchas públicas están fuera del alcance de este instalador.

Las copias privadas y el estado de transacciones están en /var/lib/dnsproxy-installer. Se conserva la primera copia y las cinco operaciones correctas más recientes. Una operación fallida restaura sus archivos y comprueba la recuperación; una transacción interrumpida se recupera antes de la siguiente modificación. La desinstalación devuelve el estado inicial; si se adoptó una instalación anterior, la recupera. Las copias retienen la configuración retirada. No se eliminan dependencias APT compartidas ni la cuenta de servicio.

rollback revierte la última operación confirmada. --transaction ID permite comprobar expresamente su identificador y rechaza una operación más antigua: aplicar sólo sus diferencias sobre cambios posteriores podría mezclar configuraciones, reglas y búferes incompatibles. Las copias anteriores quedan disponibles para recuperación manual. Para revertir una desinstalación, ejecuta bash install-dnsproxy.sh rollback desde el archivo descargado.

Integración opcional del DNS del sistema

sudo dnsproxyctl integrate --mode auto --dry-run
sudo dnsproxyctl integrate --mode auto
sudo dnsproxyctl unintegrate

auto utiliza un systemd-resolved ya activo con stub utilizable o, con un archivo de resolución estático y sin conflictos, una redirección local. No instala ni habilita otro gestor DNS. Detecta enlaces administrados, dominios privados y rutas globales incompatibles; ante ambigüedad termina sin modificar la integración.

Si otro DNS ocupa 53 y no hay un resolved aprovechable, auto se detiene. El modo siguiente es una elección explícita y cambia el significado de las consultas a loopback:53:

sudo dnsproxyctl integrate --mode redirect

La redirección sólo afecta al tráfico local destinado al loopback configurado. No detiene PowerDNS, BIND, dnsmasq ni contenedores, y no abre puertos externos. Requiere un archivo /etc/resolv.conf estático, sin gestor externo ni dominios de búsqueda privados; no usa chattr. Antes de desintegrar comprueba que no se hayan realizado modificaciones posteriores.

Caché, conexiones y búferes

Para una instalación nueva con caché normal de 4 MiB:

sudo bash install-dnsproxy.sh install --cache --cache-size 4194304

También puedes editar las opciones nativas de caché en config.yaml y reiniciar el servicio. No se extienden los TTL ni se habilita caché optimista por defecto. El TTL DNS controla la vigencia de respuestas, no la duración de una conexión.

QUIC y HTTP/2 ya incorporan mantenimiento de conexiones. Para evitar parte de las reconexiones TLS por inactividad, el sondeo opcional reserva dominios bajo .invalid, con consultas distintas dirigidas al mismo upstream del mismo proceso:

sudo dnsproxyctl warmup enable --interval 6
sudo dnsproxyctl warmup disable

A seis segundos añade unas 14.400 consultas diarias por principal TLS. No sondea respaldos. Mantiene al menos una conexión disponible cuando el proveedor lo permite; no garantiza conservar todo el conjunto ni impedir cierres del servidor. Un resultado DNS del sondeo no demuestra por sí solo la salud de TLS, porque dnsproxy puede usar respaldos ante un fallo. El sondeo no reinicia el servicio.

El ajuste de máximos UDP también es explícito:

sudo dnsproxyctl tune-udp enable
sudo dnsproxyctl tune-udp disable

Eleva los máximos de recepción y envío a 7.500.000 bytes cuando son inferiores. No modifica los tamaños predeterminados de todos los sockets. Conserva los valores previos para revertir el ajuste.

Desarrollo

Edita src/*.sh y ejecuta make build; el artefacto generado se versiona para poder transferir un solo archivo. Ejecuta make check, make test y make coverage con Python 3, ShellCheck, Bats-core y kcov instalados. Las dependencias de prueba no se instalan en los servidores de destino.

Las pruebas de máquinas virtuales usan QEMU y cloud-init sin permisos root en el host. Consulta las pruebas de integración, los resultados y limitaciones y la migración. No ejecutes pruebas administrativas directamente en el equipo de desarrollo o en producción.