awg-dash/docs/adr/005-dns-dnsmasq.md

005. DNS: встроенный dnsmasq и перехват порта 53

• Статус: принято
• Контекст/issue: #15, #26

Контекст

DNS-based split-tunnel требует знать, какие IP принадлежат доменам из списка. Если клиенты сами резолвят домены (свой DNS, DoH, другой upstream), шлюз не узнаёт об адресах и правило не срабатывает.

Решение

В образе поднимается встроенный dnsmasq (процесс агента):

• домены из списка → ipset (через --ipset), трафик на эти адреса идёт в туннель;
• перехват порта 53 от LAN-клиентов шлюзом — устраняет DNS-утечку и лечит клиентов с ручным DNS;
• upstream-форвардинг и кэш по TTL; опция «внешний DNS» остаётся для нестандартных схем.

Альтернативы

• Отдельный DNS-контейнер — лишняя зависимость и точка отказа, ломает требование единого образа.
• Только DNS клиентов — не работает без ручной настройки каждого устройства (противоречит FR-2).

Последствия

• Порт 53 занят контейнером: в README/runbook нужно предупреждение (конфликт с локальным резольвером хоста).
• Обязательно тестировать домены с CNAME и динамическими IP (#26, #41).
• Список доменов и его размеры ограничиваются явно (валидация в API, #30).