Нативни модули (за разработчици)

За обичайна употреба не са необходими модули. Това ръководство е за разработчици и администратори, които искат да разширят услугата в 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.