Нативні модулі (для розробників)

Для звичайного використання модулі не потрібні. Цей посібник призначений для розробників і адміністраторів, які хочуть розширити функції служби 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 в один каталог. Команда збирання прикладу створює бібліотеку Linux .so.