Natívne moduly (pre vývojárov)

Na bežné používanie moduly nepotrebujete. Táto príručka je pre vývojárov a správcov, ktorí chcú rozšíriť službu na Windowse alebo Linuxe natívnou knižnicou. Moduly bežia vnútri služby s jej oprávneniami. Inštalujte iba dôveryhodný kód a zabezpečte, aby súbory modulov, závislostí a konfigurácie vlastnil správca.

Načítanie modulu

Služba číta súbory *.conf z adresára modules.d vedľa konfiguračného súboru. Predvolené umiestnenia:

Operačný systém	Umiestnenie konfigurácie modulov	Formát knižnice
Linux	/etc/mudfish-dns/modules.d/	.so
Windows	%ProgramData%\Mudfish DNS\modules.d\	.dll

Do každého súboru zapíšte absolútne cesty ku knižniciam, jednu na riadok. Napríklad obsah /etc/mudfish-dns/modules.d/10-policy.conf:

/usr/lib/mudfish-dns/modules/policy.so

Súbory sa čítajú podľa názvu a riadky v nich v poradí. Prázdne riadky a riadky začínajúce # sa ignorujú. Cesty nedávajte do úvodzoviek a nepoužívajte premenné prostredia ani komentáre na konci riadka; takéto zápisy sa nevyhodnocujú. Aj na Windowse zapíšte do súboru celú absolútnu cestu vrátane prípadných medzier.

Po pridaní, zmene alebo odstránení modulu reštartujte službu. Na Linuxe použite:

sudo systemctl restart mudfish-dns.service

Na Windowse reštartujte službu Mudfish DNS v správe služieb. Spustiť DNS, Zastaviť DNS ani Použiť nastavenia v aplikácii moduly znova nenačíta. Ak sa nedá prečítať konfigurácia, cesta je nesprávna alebo zlyhá načítanie či inicializácia, služba sa nespustí. Chýbajúci alebo prázdny adresár modulov je povolený.

Počas vývoja môžete opakovane zadať argument --module a načítať knižnice v poradí argumentov. Tým nahradíte automatické načítanie z modules.d. --config FILE mení aj umiestnenie adresára modulov vedľa konfiguračného súboru. --restore-dns vykoná obnovu bez načítania modulov.

Implementácia hákov

Prečítajte si hlavičku mudfish_dns_module.h alebo stiahnite mudfish_dns_module.h. Hlavička definuje štruktúry, háky, akcie a pravidlá životnosti údajov. Táto príručka používa C ABI v2. Exportujte mudfish_dns_module_init_v2() a pred vyplnením hákov overte MUDFISH_DNS_MODULE_ABI_V2 aj odovzdanú veľkosť štruktúry. Pri úspešnej inicializácii vráťte 0.

Hák	Okamih volania
on_dns_query	Po prijatí rozparsovanej požiadavky, pred kontrolou vyrovnávacej pamäte alebo odoslaním.
on_dns_response	Po výbere odpovede, pred uložením do vyrovnávacej pamäte alebo vrátením klientovi. Prechádzajú ním aj odpovede z vyrovnávacej pamäte.
on_web_hello	Po úvodnej kontrole HTTP Host/TLS SNI, pred pripojením alebo spracovaním úvodných údajov.
on_web_data	Po načítaní ďalších údajov klienta alebo servera, pred ich odoslaním.

Akcie DNS

Háky DNS v2 pri úspechu vracajú 0 a nastavujú result->action.

Akcia	Účinok
MUDFISH_DNS_CONTINUE	Pokračuje ďalším modulom a bežným spracovaním.
MUDFISH_DNS_ALLOW	Ukončí aktuálny reťazec hákov a pokračuje bežným vyhľadávaním DNS alebo vráti vybranú odpoveď.
MUDFISH_DNS_BLOCK	Vráti REFUSED.
MUDFISH_DNS_DROP	Zahodí požiadavku bez odoslania odpovede DNS.
MUDFISH_DNS_ANSWER	Vytvorí odpoveď zo zadanej IPv4/IPv6 adresy a TTL.
MUDFISH_DNS_REPLACE	Použije úplnú odpoveď DNS v prenosovom formáte dodanú modulom.

Z háku DNS v2 nevracajte priamo konštantu akcie. Nenulová návratová hodnota alebo neplatný výsledok spôsobí SERVFAIL. ALLOW ukončuje iba aktuálny reťazec hákov; neobchádza pravidlá domén, povolenia prenosových spôsobov ani kontrolu certifikátu. Výsledky požiadaviek okrem DROP prechádzajú aj hákom odpovede.

Webové háky priamo vracajú MUDFISH_DNS_CONTINUE alebo MUDFISH_DNS_REJECT. Odmietnutie webovej požiadavky ukončí spojenie. Webové háky vyžadujú zapnutú ochranu webu a neposkytujú dešifrovaný obsah HTTPS.

Buffery, vlákna a vyrovnávacia pamäť

Vstupné udalosti a buffery sú iba na čítanie a platia iba počas callbacku. Náhradná odpoveď musí používať pamäť vlastnenú modulom a zostať platná do jeho nasledujúceho callbacku alebo ukončenia. Nevracajte pamäť zásobníka ani ukazovatele požičané z udalosti. DNS ID, opcode a otázka náhradnej odpovede musia zodpovedať pôvodnej požiadavke. Callbacky jednej inštancie bežia postupne, ale môžu byť volané z rôznych vlákien. Dokončite ich rýchlo a neprenášajte výnimky cez hranicu ABI.

Vytvorené, nahradené, blokované a zahodené výsledky sa neukladajú do vyrovnávacej pamäte hostiteľa. Nahradenie odpovede z vyrovnávacej pamäte nemení pôvodnú položku. Hostiteľ vymaže príznak AD náhradnej odpovede a nevykonáva overovanie ani nové podpisovanie DNSSEC. Modul upravujúci podpísané údaje musí sám spracovať zneplatnené podpisy.

Príklad a hlavička

Nasledujúce stránky obsahujú celý zdroj príkladu aj potrebnú hlavičku. Zdrojový strom Mudfish DNS nemusíte sťahovať samostatne.

Súbor	Obsah
policy.c — príklad politiky DNS	Povolenie, blokovanie a zahodenie požiadaviek DNS, tvorba IP odpovedí, zmena adresy a TTL odpovede. Obsahuje aj príkazy zostavenia a testovania pre Linux.
mudfish_dns_module.h — hlavička modulu	Deklarácie ABI, signatúry hákov, konštanty akcií a pravidlá vlastníctva bufferov.

Pred zostavením stiahnite policy.c aj mudfish_dns_module.h do rovnakého adresára. Príkaz príkladu vytvorí knižnicu .so pre Linux.