Нативные модули (для разработчиков)
При обычном использовании модули не нужны. Это руководство предназначено для разработчиков и администраторов, расширяющих функции службы Windows или Linux с помощью нативных библиотек. Модули выполняются внутри службы с её правами. Устанавливайте только доверенный код и сохраняйте владение файлами модулей, зависимостей и настроек за администратором.
Загрузка модулей
Служба читает файлы *.conf из каталога modules.d рядом с файлом настроек. Расположения по умолчанию приведены ниже.
| Операционная система | Расположение настроек модулей | Формат библиотеки |
|---|---|---|
| Linux | /etc/mudfish-dns/modules.d/ | .so |
| Windows | %ProgramData%\Mudfish DNS\modules.d\ | .dll |
В каждом файле укажите абсолютные пути к библиотекам, по одному на строку. Например, содержимое /etc/mudfish-dns/modules.d/10-policy.conf выглядит так:
/usr/lib/mudfish-dns/modules/policy.so
Файлы читаются в порядке имён, строки внутри каждого файла — по порядку. Пустые строки и строки, начинающиеся с #, игнорируются. Не заключайте пути в кавычки, не используйте переменные окружения и комментарии в конце строки: они не интерпретируются. В Windows также указывайте полный абсолютный путь, включая пробелы, прямо в файле.
После добавления, изменения или удаления модуля перезапустите службу. В Linux используйте следующую команду.
sudo systemctl restart mudfish-dns.service
В Windows перезапустите службу Mudfish DNS через управление службами. Действия «Запустить DNS», «Остановить DNS» и «Применить настройки» в приложении не перезагружают модули. Если файл настроек недоступен для чтения, путь неверен или возникает ошибка загрузки либо инициализации, служба не запускается. Отсутствующий или пустой каталог модулей допускается.
Во время разработки можно несколько раз указать аргумент --module, чтобы загрузить библиотеки в порядке аргументов. Это заменяет автоматическую загрузку из modules.d. Параметр --config FILE также меняет расположение каталога модулей рядом с файлом настроек. Параметр --restore-dns выполняет восстановление без загрузки модулей.
Реализация хуков
Ознакомьтесь с разделом «Заголовочный файл mudfish_dns_module.h» или скачайте mudfish_dns_module.h. Этот заголовочный файл определяет структуры, хуки, действия и правила времени жизни данных модуля. В руководстве используется C ABI v2. Экспортируйте mudfish_dns_module_init_v2() и перед заполнением хуков проверьте MUDFISH_DNS_MODULE_ABI_V2 и переданный размер структуры. При успешной инициализации верните 0.
| Хук | Момент вызова |
|---|---|
on_dns_query | После принятия разобранного запроса, до поиска в кэше или передачи дальше. |
on_dns_response | После выбора ответа, до сохранения в кэш или возврата клиенту. Кэшированные ответы также проходят через этот хук. |
on_web_hello | После начальной проверки HTTP Host/TLS SNI, до подключения или обработки начальных данных. |
on_web_data | После чтения последующих данных клиента или сервера, до их передачи. |
Действия DNS
Хуки DNS v2 возвращают 0 при успехе и задают result->action.
| Действие | Эффект |
|---|---|
MUDFISH_DNS_CONTINUE | Продолжает выполнение следующих модулей и обычную обработку. |
MUDFISH_DNS_ALLOW | Завершает текущую цепочку хуков и продолжает обычный DNS-запрос либо возвращает выбранный ответ. |
MUDFISH_DNS_BLOCK | Возвращает REFUSED. |
MUDFISH_DNS_DROP | Отбрасывает запрос без отправки DNS-ответа. |
MUDFISH_DNS_ANSWER | Создаёт ответ с предоставленными адресами IPv4/IPv6 и TTL. |
MUDFISH_DNS_REPLACE | Использует полный DNS-ответ в сетевом формате, предоставленный модулем. |
Не возвращайте константу действия напрямую из хука DNS v2. Если функция возвращает ненулевое значение или результат недопустим, возникает SERVFAIL. Действие ALLOW завершает только текущую цепочку хуков и не обходит правила доменов, разрешения способов обмена и проверку сертификатов. Результаты запросов, кроме DROP, также проходят через хук ответа.
Веб-хуки напрямую возвращают MUDFISH_DNS_CONTINUE или MUDFISH_DNS_REJECT. Отклонение веб-запроса закрывает соединение. Для использования веб-хуков должна быть включена веб-защита; расшифрованное содержимое HTTPS не предоставляется.
Буферы, потоки и кэш
Входные события и буферы доступны только для чтения и действительны лишь во время обратного вызова. Заменяющий ответ должен использовать память, принадлежащую модулю, и оставаться действительным до следующего обратного вызова этого модуля или его завершения. Не возвращайте память стека или указатели, заимствованные из события. DNS ID, opcode и вопрос заменяющего ответа должны совпадать с исходным запросом. Обратные вызовы одного экземпляра выполняются последовательно, но могут вызываться из разных потоков. Завершайте их быстро и не допускайте распространения исключений через границу ABI.
Созданные, заменённые, заблокированные и отброшенные результаты не сохраняются в кэше хоста. Замена кэшированного ответа не меняет исходную запись кэша. Хост очищает флаг AD заменяющего ответа и не выполняет проверку DNSSEC или повторную подпись. Модуль, изменяющий подписанные данные, должен самостоятельно обрабатывать ставшие недействительными подписи.
Примеры и заголовочный файл
На следующих страницах приведены полные исходники примера и необходимый заголовочный файл. Отдельно скачивать дерево исходного кода Mudfish DNS не требуется.
| Файл | Содержимое |
|---|---|
| policy.c — пример политики DNS | Разрешение, блокировка и отбрасывание DNS-запросов, создание IP-ответов, изменение адресов ответа и TTL. Также содержит команды сборки и проверки в Linux. |
| mudfish_dns_module.h — заголовочный файл модуля | Объявления ABI, сигнатуры хуков, константы действий и правила владения буферами. |
Перед сборкой скачайте policy.c и mudfish_dns_module.h в один каталог. Команда сборки примера создаёт библиотеку .so для Linux.