Inbyggda moduler för utvecklare

Moduler behövs inte för vanlig användning. Denna guide är för utvecklare och administratörer som vill utöka Windows- eller Linux-tjänsten med inbyggda bibliotek. Moduler körs inuti tjänsten med dess behörigheter. Installera endast betrodd kod och låt administratören äga modulfiler, beroenden och konfigurationsfiler.

Ladda en modul

Tjänsten läser *.conf i katalogen modules.d bredvid konfigurationsfilen. Standardplatserna är:

Operativsystem	Modulkonfiguration	Biblioteksformat
Linux	/etc/mudfish-dns/modules.d/	.so
Windows	%ProgramData%\Mudfish DNS\modules.d\	.dll

Ange en absolut bibliotekssökväg per rad. Till exempel kan /etc/mudfish-dns/modules.d/10-policy.conf innehålla:

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

Filer läses i filnamnsordning och rader i ordning inom varje fil. Tomma rader och rader som börjar med # ignoreras. Använd inte citattecken runt sökvägar, miljövariabler eller kommentarer efter en sökväg; de tolkas inte. Även på Windows anges hela absoluta sökvägen direkt, inklusive eventuella blanksteg.

Starta om tjänsten efter att en modul lagts till, ändrats eller tagits bort. På Linux:

sudo systemctl restart mudfish-dns.service

På Windows startar du om tjänsten Mudfish DNS i tjänstehanteraren. Appens Starta DNS, Stoppa DNS och Tillämpa inställningar laddar inte om moduler. Tjänsten startar inte om konfigurationsfiler inte kan läsas, sökvägar är felaktiga eller laddning eller initiering misslyckas. En saknad eller tom modulkatalog är tillåten.

Under utveckling kan --module upprepas för att ladda bibliotek i argumentordning. Detta ersätter automatisk laddning från modules.d. --config FILE ändrar även platsen för modulkatalogen bredvid konfigurationsfilen. --restore-dns återställer utan att ladda moduler.

Implementera hookar

Läs headerfilen mudfish_dns_module.h eller hämta mudfish_dns_module.h. Den definierar strukturer, hookar, åtgärder och regler för datalivslängd. Guiden använder C ABI v2. Exportera mudfish_dns_module_init_v2() och kontrollera MUDFISH_DNS_MODULE_ABI_V2 och den angivna strukturstorleken innan du fyller i hookarna. Returnera 0 vid lyckad initiering.

Hook	Anropas
on_dns_query	Efter att en parsad fråga accepterats, före cachesökning eller vidarebefordran.
on_dns_response	Efter att ett svar valts, före cachning eller retur till klienten. Även cachade svar går genom denna hook.
on_web_hello	Efter den första HTTP Host/TLS SNI-kontrollen, före anslutning eller behandling av inledande data.
on_web_data	Efter läsning av efterföljande klient- eller serverdata, före vidarebefordran.

DNS-åtgärder

DNS-hookar i v2 returnerar 0 vid framgång och anger åtgärden i result->action.

Åtgärd	Effekt
MUDFISH_DNS_CONTINUE	Fortsätt med nästa modul och normal behandling.
MUDFISH_DNS_ALLOW	Avsluta aktuell hookkedja och fortsätt vanlig DNS-uppslagning eller returnera valt svar.
MUDFISH_DNS_BLOCK	Returnera REFUSED.
MUDFISH_DNS_DROP	Kasta förfrågan utan DNS-svar.
MUDFISH_DNS_ANSWER	Skapa ett svar med angiven IPv4/IPv6-adress och TTL.
MUDFISH_DNS_REPLACE	Använd modulens kompletta DNS-svar i wire-format.

Returnera inte åtgärdskonstanten direkt från en v2 DNS-hook. Ett returvärde som inte är 0 eller ett ogiltigt resultat ger SERVFAIL. ALLOW avslutar endast aktuell hookkedja och kringgår inte domänregler, transporttillstånd eller certifikatkontroller. Alla frågeresultat utom DROP går även genom svarshookarna.

Webbhookar returnerar MUDFISH_DNS_CONTINUE eller MUDFISH_DNS_REJECT direkt. Avvisning avslutar anslutningen. Webbskydd måste vara aktivt för webbhookar, och dekrypterat HTTPS-innehåll tillhandahålls inte.

Buffertar, trådar och cache

Indatahändelser och buffertar är skrivskyddade och giltiga endast under callback-anropet. Ersättningssvar måste använda minne som modulen äger och vara giltiga till modulens nästa callback eller avslutning. Returnera inte stackminne eller pekare lånade från händelsen. DNS-ID, opcode och fråga i ersättningssvaret måste motsvara originalfrågan. Callback-anrop för en instans körs sekventiellt men kan ske på olika trådar. Avsluta dem snabbt och låt inte undantag passera ABI-gränsen.

Genererade, ersatta, blockerade eller kastade resultat lagras inte i värdens cache. Att ersätta ett cachat svar ändrar inte den ursprungliga cacheposten. Värden rensar AD-flaggan i ersättningssvar och varken validerar eller signerar om DNSSEC. Moduler som ändrar signerade data måste själva hantera ogiltigförklarade signaturer.

Exempel och headerfil

Följande sidor innehåller hela exemplet och headerfilen. Du behöver inte hämta Mudfish DNS källkod separat.

Fil	Innehåll
policy.c – DNS-policyexempel	Tillåt, blockera eller kasta frågor, skapa IP-svar samt ändra svaradresser och TTL. Innehåller bygg- och testkommandon för Linux.
mudfish_dns_module.h – modulheader	ABI-deklarationer, hooksignaturer, åtgärdskonstanter och buffertägarskap.

Hämta policy.c och mudfish_dns_module.h till samma katalog före byggning. Exempelkommandot skapar ett Linux-bibliotek i .so-format.