Nativní moduly (pro vývojáře)

Pro běžné používání nejsou moduly potřeba. Tento návod je určen vývojářům a správcům, kteří chtějí rozšířit službu pro Windows nebo Linux pomocí nativních knihoven. Moduly běží uvnitř služby s jejími oprávněními. Instalujte pouze důvěryhodný kód a zajistěte, aby soubory modulů, závislostí a konfigurace vlastnil správce.

Načtení modulu

Služba čte soubory *.conf v adresáři modules.d vedle konfiguračního souboru. Výchozí umístění jsou:

Operační systém	Umístění konfigurace modulů	Formát knihovny
Linux	/etc/mudfish-dns/modules.d/	.so
Windows	%ProgramData%\Mudfish DNS\modules.d\	.dll

Do každého souboru zadejte jednu absolutní cestu ke knihovně na řádek. Například /etc/mudfish-dns/modules.d/10-policy.conf obsahuje:

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

Soubory se čtou v pořadí názvů a uvnitř souboru v pořadí řádků. Prázdné řádky a řádky začínající # se ignorují. Nepoužívejte uvozovky kolem cest, proměnné prostředí ani komentáře na konci řádku; tyto zápisy se nevyhodnocují. I ve Windows zapisujte celou absolutní cestu, včetně případných mezer.

Po přidání, změně nebo odebrání modulu restartujte službu. V Linuxu použijte:

sudo systemctl restart mudfish-dns.service

Ve Windows restartujte službu Mudfish DNS ve správě služeb. Volby Spustit DNS, Zastavit DNS a Použít nastavení v aplikaci moduly znovu nenačítají. Pokud nelze přečíst konfigurační soubor, cesta je nesprávná nebo dojde k chybě načtení či inicializace, služba se nespustí. Chybějící nebo prázdný adresář modulů je povolen.

Při vývoji můžete opakovat argument --module a načíst knihovny v pořadí argumentů. Tím se nahradí automatické načítání z modules.d. --config FILE mění také umístění adresáře modulů vedle konfigurace. --restore-dns provede obnovu bez načítání modulů.

Implementace hooků

Přečtěte si hlavičku mudfish_dns_module.h nebo stáhněte mudfish_dns_module.h. Hlavička definuje struktury, hooky, akce a pravidla životnosti dat používaná modulem. Tento návod používá C ABI v2. Exportujte mudfish_dns_module_init_v2() a před vyplněním hooků ověřte MUDFISH_DNS_MODULE_ABI_V2 a předanou velikost struktury. Při úspěšné inicializaci vraťte 0.

Hook	Okamžik volání
on_dns_query	Po přijetí rozparsovaného dotazu, před vyhledáním v mezipaměti nebo předáním dál.
on_dns_response	Po výběru odpovědi, před uložením do mezipaměti nebo vrácením klientovi. Procházejí jím i odpovědi z mezipaměti.
on_web_hello	Po počáteční kontrole HTTP Host/TLS SNI, před připojením nebo zpracováním počátečních dat.
on_web_data	Po načtení následných dat klienta nebo serveru, před jejich předáním dál.

Akce DNS

Hooky DNS v2 vracejí při úspěchu 0 a nastavují result->action.

Akce	Účinek
MUDFISH_DNS_CONTINUE	Pokračuje dalším modulem a běžným zpracováním.
MUDFISH_DNS_ALLOW	Ukončí aktuální řetězec hooků a pokračuje běžným dotazem DNS nebo vrátí vybranou odpověď.
MUDFISH_DNS_BLOCK	Vrátí REFUSED.
MUDFISH_DNS_DROP	Zahodí požadavek bez odeslání odpovědi DNS.
MUDFISH_DNS_ANSWER	Vytvoří odpověď z poskytnuté adresy IPv4/IPv6 a TTL.
MUDFISH_DNS_REPLACE	Použije úplnou odpověď DNS v přenosovém formátu dodanou modulem.

V hooku DNS v2 nevracejte přímo konstantu akce. Nenulová návratová hodnota nebo neplatný výsledek způsobí SERVFAIL. ALLOW ukončí pouze aktuální řetězec hooků; neobchází pravidla domén, povolení způsobů přenosu ani kontroly certifikátů. Výsledky dotazů kromě DROP procházejí také hookem odpovědi.

Webové hooky přímo vracejí MUDFISH_DNS_CONTINUE nebo MUDFISH_DNS_REJECT. Odmítnutí webového požadavku ukončí spojení. Pro použití webových hooků musí být zapnutá ochrana webu; dešifrovaný obsah HTTPS není poskytován.

Buffery, vlákna a mezipaměť

Vstupní události a buffery jsou pouze pro čtení a platí jen po dobu callbacku. Náhradní odpověď musí používat paměť vlastněnou modulem a zůstat platná do dalšího callbacku tohoto modulu nebo jeho ukončení. Nevracejte paměť na zásobníku ani ukazatel vypůjčený z události. DNS ID, opcode a otázka náhradní odpovědi musí odpovídat původnímu dotazu. Callbacky jedné instance se provádějí postupně, mohou však být volány z různých vláken. Dokončujte je rychle a nenechte výjimky překročit hranici ABI.

Vytvořené, nahrazené, blokované a zahozené výsledky se neukládají do mezipaměti hostitele. Nahrazení odpovědi z mezipaměti nemění původní záznam. Hostitel u náhradních odpovědí maže příznak AD a neprovádí ověření ani nové podepsání DNSSEC. Modul upravující podepsaná data musí sám ošetřit zneplatněné podpisy.

Příklad a hlavička

Následující stránky obsahují celý příklad a potřebnou hlavičku. Není třeba samostatně stahovat zdrojový strom Mudfish DNS.

Soubor	Obsah
policy.c — příklad politiky DNS	Povolení, blokování a zahození dotazů DNS, generování IP odpovědí, změny adres a TTL. Obsahuje také příkazy sestavení a testování v Linuxu.
mudfish_dns_module.h — hlavička modulu	Deklarace ABI, signatury hooků, konstanty akcí a pravidla vlastnictví bufferů.

Před sestavením stáhněte policy.c a mudfish_dns_module.h do stejného adresáře. Příkazy v příkladu vytvářejí linuxovou knihovnu .so.