Nativni moduli (za programere)

Za običnu upotrebu moduli nisu potrebni. Ovaj je vodič namijenjen programerima i administratorima koji žele proširiti funkcije usluge na Windowsu ili Linuxu nativnom bibliotekom. Moduli se izvršavaju unutar usluge s njezinim ovlastima. Instalirajte samo pouzdan kod i zadržite administratorsko vlasništvo nad datotekama modula, ovisnostima i konfiguracijskim datotekama.

Učitavanje modula

Usluga čita datoteke *.conf iz direktorija modules.d uz konfiguracijsku datoteku. Zadane lokacije su sljedeće.

Operacijski sustav	Lokacija konfiguracije modula	Format biblioteke
Linux	/etc/mudfish-dns/modules.d/	.so
Windows	%ProgramData%\Mudfish DNS\modules.d\	.dll

U svaku datoteku unesite apsolutne putanje biblioteka, po jednu u svakom retku. Primjer sadržaja /etc/mudfish-dns/modules.d/10-policy.conf:

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

Datoteke se čitaju redoslijedom naziva, a unutar datoteke redoslijedom redaka. Prazni retci i retci koji počinju s # zanemaruju se. Nemojte navoditi putanje u navodnicima niti upotrebljavati varijable okruženja ili komentare na kraju retka: oni se ne interpretiraju. I na Windowsu unesite cijelu apsolutnu putanju, uključujući putanje s razmacima.

Nakon dodavanja, promjene ili uklanjanja modula ponovno pokrenite uslugu. Na Linuxu upotrijebite:

sudo systemctl restart mudfish-dns.service

Na Windowsu ponovno pokrenite uslugu Mudfish DNS u upravljanju uslugama. Opcije Pokreni DNS, Zaustavi DNS i Primijeni postavke u aplikaciji ne učitavaju module ponovno. Ako se konfiguracijska datoteka ne može pročitati, putanja je pogrešna ili dođe do pogreške učitavanja ili inicijalizacije, usluga se neće pokrenuti. Direktorij modula smije nedostajati ili biti prazan.

Tijekom razvoja možete više puta zadati argument --module kako biste biblioteke učitali redoslijedom argumenata. To zamjenjuje automatsko učitavanje iz modules.d. --config FILE mijenja i lokaciju direktorija modula uz konfiguracijsku datoteku. --restore-dns izvodi oporavak bez učitavanja modula.

Implementacija hookova

Pročitajte zaglavlje mudfish_dns_module.h ili preuzmite mudfish_dns_module.h. Zaglavlje definira strukture, hookove, akcije i pravila životnog vijeka podataka koje moduli upotrebljavaju. Ovaj vodič upotrebljava C ABI v2. Izvezite mudfish_dns_module_init_v2() i prije popunjavanja hookova provjerite MUDFISH_DNS_MODULE_ABI_V2 te proslijeđenu veličinu strukture. Pri uspješnoj inicijalizaciji vratite 0.

Hook	Trenutak poziva
on_dns_query	Nakon prihvaćanja parsiranog upita, prije pretraživanja predmemorije ili prosljeđivanja.
on_dns_response	Nakon odabira odgovora, prije spremanja u predmemoriju ili vraćanja klijentu. I odgovori iz predmemorije prolaze kroz ovaj hook.
on_web_hello	Nakon početne provjere HTTP Host/TLS SNI, prije povezivanja ili obrade početnih podataka.
on_web_data	Nakon čitanja naknadnih podataka klijenta ili poslužitelja, prije prosljeđivanja.

DNS akcije

DNS hookovi v2 pri uspjehu vraćaju 0 i postavljaju result->action.

Akcija	Učinak
MUDFISH_DNS_CONTINUE	Nastavlja sljedećim modulom i uobičajenom obradom.
MUDFISH_DNS_ALLOW	Završava trenutačni lanac hookova i nastavlja uobičajeni DNS upit ili vraća odabrani odgovor.
MUDFISH_DNS_BLOCK	Vraća REFUSED.
MUDFISH_DNS_DROP	Odbacuje bez slanja DNS odgovora.
MUDFISH_DNS_ANSWER	Stvara odgovor s navedenom IPv4/IPv6 adresom i TTL-om.
MUDFISH_DNS_REPLACE	Upotrebljava potpuni odgovor u DNS mrežnom formatu koji pruža modul.

Nemojte izravno vraćati konstante akcija iz DNS hookova v2. Ako funkcija vrati vrijednost različitu od 0 ili je rezultat nevaljan, nastaje SERVFAIL. ALLOW završava samo trenutačni lanac hookova i ne zaobilazi pravila domena, dopuštenja načina komunikacije ni provjeru certifikata. Svi rezultati upita osim DROP prolaze i kroz hook odgovora.

Web-hookovi izravno vraćaju MUDFISH_DNS_CONTINUE ili MUDFISH_DNS_REJECT. Odbijanje web-zahtjeva zatvara vezu. Za web-hookove mora biti uključena web-zaštita; dešifrirani HTTPS sadržaj nije dostupan.

Međuspremnici, dretve i predmemorija

Ulazni događaji i međuspremnici samo su za čitanje i vrijede samo tijekom callbacka. Zamjenski odgovor mora upotrebljavati memoriju u vlasništvu modula koja ostaje valjana do sljedećeg callbacka tog modula ili njegova uništavanja. Nemojte vraćati memoriju stoga ni pokazivače posuđene iz događaja. DNS ID, opcode i pitanje zamjenskog odgovora moraju odgovarati izvornom upitu. Callbackovi jedne instance izvršavaju se serijski, ali mogu biti pozvani iz različitih dretvi. Dovršite callbackove brzo i nemojte širiti iznimke preko ABI granice.

Stvoreni, zamijenjeni, blokirani i odbačeni rezultati ne spremaju se u predmemoriju domaćina. Zamjena odgovora iz predmemorije ne mijenja izvornu stavku predmemorije. Domaćin briše zastavicu AD zamjenskog odgovora i ne provodi DNSSEC provjeru ni ponovno potpisivanje. Modul koji mijenja potpisane podatke mora sam obraditi potpise koji više nisu valjani.

Primjer i zaglavlje

Sljedeće stranice sadrže potpuni izvor primjera i potrebno zaglavlje. Nije potrebno zasebno preuzimati izvorno stablo Mudfish DNS-a.

Datoteka	Sadržaj
policy.c — primjer DNS pravila	Dopuštanje, blokiranje i odbacivanje DNS upita, stvaranje IP odgovora te promjena adrese odgovora i TTL-a. Sadrži i Linux naredbe za izgradnju i testiranje.
mudfish_dns_module.h — zaglavlje modula	ABI deklaracije, potpisi hookova, konstante akcija i pravila vlasništva nad međuspremnicima.

Prije izgradnje preuzmite policy.c i mudfish_dns_module.h u isti direktorij. Naredbe za izgradnju primjera stvaraju Linux biblioteku .so.