Native modules voor ontwikkelaars

Voor normaal gebruik zijn geen modules nodig. Deze handleiding is bedoeld voor ontwikkelaars en beheerders die de Windows- of Linux-service met native bibliotheken willen uitbreiden. Modules draaien binnen de service met de rechten van die service. Installeer alleen vertrouwde code en zorg dat modulebestanden, afhankelijkheden en configuratiebestanden eigendom van de beheerder blijven.

Een module laden

De service leest *.conf-bestanden uit de map modules.d naast het configuratiebestand. Standaardlocaties:

Systeem	Moduleconfiguratie	Bibliotheekformaat
Linux	/etc/mudfish-dns/modules.d/	.so
Windows	%ProgramData%\Mudfish DNS\modules.d\	.dll

Schrijf in elk bestand één absoluut bibliotheekpad per regel. Bijvoorbeeld in /etc/mudfish-dns/modules.d/10-policy.conf:

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

Bestanden worden op bestandsnaam gelezen en regels binnen elk bestand op volgorde. Lege regels en regels die met # beginnen worden genegeerd. Gebruik geen aanhalingstekens rond paden, omgevingsvariabelen of commentaar aan het einde van regels: deze worden niet geïnterpreteerd. Schrijf ook op Windows het volledige absolute pad in het bestand, inclusief eventuele spaties.

Herstart de service na het toevoegen, wijzigen of verwijderen van modules. Op Linux:

sudo systemctl restart mudfish-dns.service

Herstart op Windows de service Mudfish DNS via servicebeheer. DNS starten, DNS stoppen en Instellingen toepassen laden modules niet opnieuw. Bij een onleesbaar configuratiebestand, ongeldig pad of fout tijdens laden of initialiseren start de service niet. Een ontbrekende of lege modulemap is wel toegestaan.

Tijdens ontwikkeling kun je --module herhaald opgeven om bibliotheken in argumentvolgorde te laden. Dit vervangt het automatisch laden uit modules.d. --config FILE verandert ook de locatie van de modulemap naast het configuratiebestand. --restore-dns voert herstel uit zonder modules te laden.

Hooks implementeren

Lees de header mudfish_dns_module.h of download mudfish_dns_module.h. De header definieert structuren, hooks, acties en levensduurregels voor gegevens. Deze handleiding gebruikt C ABI v2. Exporteer mudfish_dns_module_init_v2() en controleer MUDFISH_DNS_MODULE_ABI_V2 en de doorgegeven structuurgrootte voordat je hooks invult. Geef bij succesvolle initialisatie 0 terug.

Hook	Moment van aanroep
on_dns_query	Na het accepteren van een geparseerd verzoek, vóór cachecontrole of doorsturen.
on_dns_response	Na het kiezen van een antwoord, vóór opslaan in de cache of terugsturen naar de client. Ook antwoorden uit de cache passeren deze hook.
on_web_hello	Na de eerste HTTP Host/TLS SNI-inspectie, vóór verbinden of verwerken van de eerste gegevens.
on_web_data	Na het lezen van verdere client- of servergegevens, vóór doorsturen.

DNS-acties

DNS-hooks van v2 geven bij succes 0 terug en stellen result->action in.

Actie	Effect
MUDFISH_DNS_CONTINUE	Ga door naar de volgende module en normale verwerking.
MUDFISH_DNS_ALLOW	Beëindig de huidige hookketen en vervolg de normale DNS-opzoeking of geef het gekozen antwoord terug.
MUDFISH_DNS_BLOCK	Geef REFUSED terug.
MUDFISH_DNS_DROP	Verwerp het verzoek zonder DNS-antwoord.
MUDFISH_DNS_ANSWER	Maak een antwoord met het opgegeven IPv4/IPv6-adres en de TTL.
MUDFISH_DNS_REPLACE	Gebruik het volledige door de module aangeleverde DNS-antwoord in wireformaat.

Geef in een v2-DNS-hook niet rechtstreeks een actieconstante terug. Een niet-nulretourwaarde of ongeldig resultaat veroorzaakt SERVFAIL. ALLOW beëindigt alleen de huidige hookketen en omzeilt geen domeinregels, toegestane transportmethoden of certificaatcontroles. Alle verzoekresultaten behalve DROP passeren ook de antwoordhooks.

Webhooks geven rechtstreeks MUDFISH_DNS_CONTINUE of MUDFISH_DNS_REJECT terug. Afwijzen sluit de verbinding. Webbescherming moet aanstaan om webhooks te gebruiken; ontsleutelde HTTPS-inhoud is niet beschikbaar.

Buffers, threads en cache

Invoerevents en buffers zijn alleen-lezen en uitsluitend geldig tijdens de callback. Vervangende antwoorden moeten geheugen van de module gebruiken dat geldig blijft tot de volgende callback van die module of het afsluiten. Geef geen stackgeheugen of geleende eventpointers terug. DNS-ID, opcode en vraag van een vervangend antwoord moeten overeenkomen met het oorspronkelijke verzoek. Callbacks van één instantie worden opeenvolgend uitgevoerd, maar kunnen op verschillende threads worden aangeroepen. Houd callbacks kort en laat geen uitzonderingen de ABI-grens passeren.

Gegenereerde, vervangen, geblokkeerde en verworpen resultaten worden niet in de hostcache opgeslagen. Een gecachet antwoord vervangen wijzigt het oorspronkelijke cache-item niet. De host wist de AD-vlag van vervangende antwoorden en voert geen DNSSEC-validatie of herondertekening uit. Modules die ondertekende gegevens wijzigen moeten zelf ongeldige handtekeningen afhandelen.

Voorbeeld en header

Deze pagina’s bevatten de volledige voorbeeldbron en header. Je hoeft de Mudfish DNS-bronboom niet apart te downloaden.

Bestand	Inhoud
policy.c — DNS-beleidsvoorbeeld	Verzoeken toestaan, blokkeren of verwerpen, IP-antwoorden genereren en antwoordadressen en TTL wijzigen. Inclusief Linux-bouw- en testopdrachten.
mudfish_dns_module.h — moduleheader	ABI-declaraties, hooksignaturen, actieconstanten en regels voor buffereigendom.

Download policy.c en mudfish_dns_module.h naar dezelfde map voordat je bouwt. De voorbeeldopdracht maakt een Linux-.so-bibliotheek.