Native moduler (til udviklere)

Moduler er ikke nødvendige til almindelig brug. Denne vejledning er til udviklere og administratorer, som vil udvide Windows- eller Linux-tjenesten med native biblioteker. Moduler kører inde i tjenesten med dens rettigheder. Installer kun kode, du stoler på, og sørg for, at modulfiler, afhængigheder og konfigurationsfiler ejes af administratoren.

Indlæs et modul

Tjenesten læser *.conf-filer fra mappen modules.d ved siden af konfigurationsfilen. Standardplaceringerne er følgende.

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

Skriv én absolut bibliotekssti pr. linje i hver fil. For eksempel kan /etc/mudfish-dns/modules.d/10-policy.conf indeholde følgende.

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

Filer læses i filnavnsrækkefølge, og linjer læses i rækkefølge inden for filen. Tomme linjer og linjer, der starter med #, ignoreres. Brug ikke anførselstegn omkring stier, miljøvariabler eller kommentarer sidst på linjen; de fortolkes ikke. På Windows skal hele den absolutte sti også skrives direkte i filen, inklusive eventuelle mellemrum.

Genstart tjenesten efter tilføjelse, ændring eller fjernelse af moduler. Brug følgende kommando på Linux.

sudo systemctl restart mudfish-dns.service

På Windows skal du genstarte tjenesten Mudfish DNS i tjenesteadministrationen. Appens Start DNS, Stop DNS og Anvend indstillinger genindlæser ikke moduler. Tjenesten starter ikke, hvis konfigurationsfiler ikke kan læses, stier er forkerte, eller indlæsning eller initialisering fejler. En manglende eller tom modulmappe er tilladt.

Under udvikling kan du gentage argumentet --module for at indlæse biblioteker i argumentrækkefølge. Dette erstatter automatisk indlæsning fra modules.d. --config FILE ændrer også placeringen af modulmappen ved siden af konfigurationsfilen. --restore-dns udfører gendannelse uden at indlæse moduler.

Implementér hooks

Læs headeren mudfish_dns_module.h, eller download mudfish_dns_module.h. Headeren definerer strukturer, hooks, handlinger og regler for datalevetid. Denne vejledning bruger C ABI v2. Eksportér mudfish_dns_module_init_v2(), og kontrollér MUDFISH_DNS_MODULE_ABI_V2 samt den overførte strukturstørrelse, før du udfylder hooks. Returnér 0 ved vellykket initialisering.

Hook	Tidspunkt
on_dns_query	Efter at den parsede forespørgsel er accepteret, før cacheopslag eller videresendelse.
on_dns_response	Efter valg af svar, før lagring i cache eller returnering til klienten. Cachede svar passerer også denne hook.
on_web_hello	Efter indledende kontrol af HTTP Host/TLS SNI, før forbindelse eller behandling af de indledende data.
on_web_data	Efter læsning af efterfølgende klient- eller serverdata, før videresendelse.

DNS-handlinger

DNS-hooks i v2 returnerer 0 ved succes og sætter result->action.

Handling	Virkning
MUDFISH_DNS_CONTINUE	Fortsætter til næste modul og normal behandling.
MUDFISH_DNS_ALLOW	Afslutter den aktuelle hook-kæde og fortsætter normalt DNS-opslag eller returnerer det valgte svar.
MUDFISH_DNS_BLOCK	Returnerer REFUSED.
MUDFISH_DNS_DROP	Kasserer uden at sende et DNS-svar.
MUDFISH_DNS_ANSWER	Danner et svar med den angivne IPv4/IPv6-adresse og TTL.
MUDFISH_DNS_REPLACE	Bruger modulets komplette DNS-svar i wire-format.

Returnér ikke handlingskonstanter direkte fra DNS-hooks i v2. En returværdi forskellig fra 0 eller et ugyldigt resultat giver SERVFAIL. ALLOW afslutter kun den aktuelle hook-kæde og omgår ikke domæneregler, tilladelser til transportmetoder eller certifikatkontrol. Alle forespørgselsresultater undtagen DROP passerer også svarhooks.

Webhooks returnerer MUDFISH_DNS_CONTINUE eller MUDFISH_DNS_REJECT direkte. Afvisning af en webanmodning lukker forbindelsen. Webbeskyttelse skal være aktiveret for at bruge webhooks, og dekrypteret HTTPS-indhold stilles ikke til rådighed.

Buffere, tråde og cache

Inputhændelser og buffere er skrivebeskyttede og kun gyldige under callbacken. Erstatningssvar skal bruge hukommelse, som modulet ejer, og være gyldige indtil næste callback på samme modul eller dets afslutning. Returnér ikke stakhukommelse eller lånte pointere fra hændelsen. DNS-id, opcode og spørgsmål i erstatningssvaret skal svare til den oprindelige forespørgsel. Callbacks for én instans udføres sekventielt, men kan blive kaldt fra forskellige tråde. Afslut callbacks hurtigt, og lad ikke undtagelser krydse ABI-grænsen.

Genererede, erstattede, blokerede og kasserede resultater gemmes ikke i værtens cache. Erstatning af et cachet svar ændrer ikke den oprindelige cachepost. Værten rydder AD-flaget i erstatningssvar og udfører hverken DNSSEC-validering eller ny signering. Moduler, der ændrer signerede data, skal selv håndtere ugyldiggjorte signaturer.

Eksempel og header

De følgende sider indeholder den komplette eksempelkode og den nødvendige header. Du behøver ikke hente Mudfish DNS-kildetræet separat.

Fil	Indhold
policy.c – eksempel på DNS-politik	Tillad, blokér eller kassér DNS-forespørgsler, generér IP-svar, og ændr svaradresser og TTL. Indeholder også Linux-kommandoer til bygning og test.
mudfish_dns_module.h – modulheader	ABI-deklarationer, hook-signaturer, handlingskonstanter og regler for bufferejerskab.

Download policy.c og mudfish_dns_module.h til samme mappe før bygning. Eksemplets byggekommando genererer et Linux-bibliotek i .so-format.