Native moduler (for utviklere)

Moduler er ikke nødvendige for vanlig bruk. Denne veiledningen er for utviklere og administratorer som vil utvide Windows- eller Linux-tjenesten med native biblioteker. Modulene kjører inne i tjenesten med tjenestens rettigheter. Installer bare kode du stoler på, og sørg for at modul-, avhengighets- og konfigurasjonsfiler eies av administratoren.

Last en modul

Tjenesten leser *.conf-filer fra modules.d ved siden av konfigurasjonsfilen. Standardplasseringene er:

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

Skriv én absolutt biblioteksti per linje. For eksempel kan /etc/mudfish-dns/modules.d/10-policy.conf inneholde:

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

Filene leses i filnavnrekkefølge, og linjene i hver fil leses i rekkefølge. Tomme linjer og linjer som begynner med #, ignoreres. Ikke bruk anførselstegn rundt stier, miljøvariabler eller kommentarer på slutten av linjen; slike uttrykk tolkes ikke. På Windows skriver du også hele den absolutte stien direkte, inkludert eventuelle mellomrom.

Start tjenesten på nytt etter at du legger til, endrer eller fjerner en modul. På Linux:

sudo systemctl restart mudfish-dns.service

På Windows starter du Mudfish DNS-tjenesten på nytt i tjenestebehandleren. Start DNS, Stopp DNS og Bruk innstillinger i appen laster ikke modulene på nytt. Tjenesten starter ikke hvis en konfigurasjonsfil ikke kan leses, en sti er feil, eller lasting eller initialisering mislykkes. Det er tillatt at modulkatalogen mangler eller er tom.

Under utvikling kan du gjenta argumentet --module for å laste biblioteker i argumentrekkefølge. Dette erstatter automatisk lasting fra modules.d. --config FILE endrer også plasseringen av modulkatalogen ved siden av konfigurasjonsfilen. --restore-dns utfører gjenoppretting uten å laste moduler.

Implementer hooker

Les headeren mudfish_dns_module.h, eller last ned mudfish_dns_module.h. Headeren definerer strukturer, hooker, handlinger og regler for datalevetid. Denne veiledningen bruker C ABI v2. Eksporter mudfish_dns_module_init_v2(), og kontroller MUDFISH_DNS_MODULE_ABI_V2 og den oppgitte strukturstørrelsen før du fyller ut hookene. Returner 0 ved vellykket initialisering.

Hook	Når den kalles
on_dns_query	Etter at en tolket forespørsel er godtatt, før hurtigbufferoppslag eller videresending.
on_dns_response	Etter at et svar er valgt, før det lagres i hurtigbufferen eller returneres til klienten. Også hurtigbufrede svar går gjennom denne hooken.
on_web_hello	Etter innledende HTTP Host-/TLS SNI-kontroll, før tilkobling eller behandling av de første dataene.
on_web_data	Etter lesing av senere klientdata eller serverdata, før videresending.

DNS-handlinger

DNS-hooker i v2 returnerer 0 ved suksess og setter result->action.

Handling	Virkning
MUDFISH_DNS_CONTINUE	Fortsetter med neste modul og vanlig behandling.
MUDFISH_DNS_ALLOW	Avslutter den aktuelle hook-kjeden og fortsetter vanlig DNS-oppslag eller returnerer det valgte svaret.
MUDFISH_DNS_BLOCK	Returnerer REFUSED.
MUDFISH_DNS_DROP	Forkaster uten å sende DNS-svar.
MUDFISH_DNS_ANSWER	Lager et svar med oppgitt IPv4-/IPv6-adresse og TTL.
MUDFISH_DNS_REPLACE	Bruker modulens fullstendige svar i DNS-wireformat.

Ikke returner handlingskonstanten direkte fra en v2 DNS-hook. Hvis funksjonen returnerer noe annet enn 0, eller resultatet er ugyldig, oppstår SERVFAIL. ALLOW avslutter bare den aktuelle hook-kjeden og omgår ikke domeneregler, tillatte transportmåter eller sertifikatkontroll. Alle forespørselsresultater unntatt DROP går også gjennom svarhooken.

Webhooker returnerer MUDFISH_DNS_CONTINUE eller MUDFISH_DNS_REJECT direkte. Avvisning avslutter forbindelsen. Webbeskyttelse må være aktivert for å bruke webhooker. Dekryptert HTTPS-innhold er ikke tilgjengelig.

Buffere, tråder og hurtigbuffer

Inndatahendelser og buffere er skrivebeskyttet og bare gyldige mens callbacken kjører. Erstatningssvar må bruke minne som modulen eier, og være gyldige til modulens neste callback eller avslutning. Ikke returner stakkminne eller pekere lånt fra hendelsen. DNS-ID, opcode og spørsmål i erstatningssvaret må samsvare med den opprinnelige forespørselen. Callbacker for én instans kjøres sekvensielt, men kan kalles fra ulike tråder. Hold dem korte, og ikke la unntak krysse ABI-grensen.

Genererte, erstattede, blokkerte eller forkastede resultater lagres ikke i vertens hurtigbuffer. Erstatning av et hurtigbufret svar endrer ikke den opprinnelige hurtigbufferoppføringen. Verten fjerner AD-flagget fra erstatningssvar og utfører verken DNSSEC-validering eller ny signering. Moduler som endrer signerte data, må selv håndtere ugyldiggjorte signaturer.

Eksempel og header

Sidene nedenfor inneholder fullstendig eksempelkode og nødvendig header. Du trenger ikke laste ned Mudfish DNS-kildetreet separat.

Fil	Innhold
policy.c — DNS-policyeksempel	Tillat, blokker eller forkast DNS-forespørsler, generer IP-svar og endre svaradresser og TTL. Inkluderer bygge- og testkommandoer for Linux.
mudfish_dns_module.h — modulheader	ABI-deklarasjoner, hook-signaturer, handlingskonstanter og regler for buffereierskap.

Last ned policy.c og mudfish_dns_module.h til samme katalog før bygging. Eksemplets byggekommando lager et Linux-bibliotek i .so-format.