Natiivimoduulit kehittäjille

Tavallinen käyttö ei edellytä moduuleja. Tämä ohje on kehittäjille ja ylläpitäjille, jotka haluavat laajentaa Windows- tai Linux-palvelua natiivikirjastolla. Moduulit suoritetaan palvelun sisällä sen oikeuksilla. Asenna vain luotettavaa koodia ja pidä moduulit, riippuvuustiedostot sekä asetustiedostot ylläpitäjän omistuksessa.

Moduulin lataaminen

Palvelu lukee *.conf-tiedostot asetustiedoston vieressä olevasta modules.d-hakemistosta. Oletussijainnit ovat:

Käyttöjärjestelmä	Moduuliasetusten sijainti	Kirjastomuoto
Linux	/etc/mudfish-dns/modules.d/	.so
Windows	%ProgramData%\Mudfish DNS\modules.d\	.dll

Kirjoita kuhunkin tiedostoon kirjaston absoluuttinen polku, yksi riville. Esimerkiksi /etc/mudfish-dns/modules.d/10-policy.conf sisältää:

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

Tiedostot luetaan nimijärjestyksessä ja niiden sisällä rivijärjestyksessä. Tyhjät rivit ja #-merkillä alkavat rivit ohitetaan. Älä ympäröi polkuja lainausmerkeillä äläkä käytä ympäristömuuttujia tai rivin loppuun lisättyjä kommentteja, sillä niitä ei tulkita. Kirjoita myös Windowsissa koko absoluuttinen polku tiedostoon, vaikka siinä olisi välilyöntejä.

Käynnistä palvelu uudelleen moduulin lisäämisen, muuttamisen tai poistamisen jälkeen. Linuxissa käytä komentoa:

sudo systemctl restart mudfish-dns.service

Windowsissa käynnistä Mudfish DNS uudelleen palveluiden hallinnasta. Sovelluksen Käynnistä DNS, Pysäytä DNS ja Ota asetukset käyttöön eivät lataa moduuleja uudelleen. Jos asetustiedostoa ei voida lukea, polku on väärä tai lataus tai alustus epäonnistuu, palvelu ei käynnisty. Puuttuva tai tyhjä moduulihakemisto on sallittu.

Kehityksen aikana voit toistaa --module-argumentin ladataksesi kirjastot argumenttijärjestyksessä. Tällöin se korvaa modules.d-hakemiston automaattisen lataamisen. --config FILE muuttaa myös asetustiedoston vieressä olevan moduulihakemiston sijaintia. --restore-dns tekee palautuksen lataamatta moduuleja.

Koukkujen toteutus

Lue mudfish_dns_module.h-otsake tai lataa mudfish_dns_module.h. Se määrittää rakenteet, koukut, toiminnot ja datan elinkaarisäännöt. Tämä ohje käyttää C ABI v2:ta. Vie symboli mudfish_dns_module_init_v2() ja tarkista MUDFISH_DNS_MODULE_ABI_V2 sekä välitetty rakenteen koko ennen koukkujen täyttämistä. Palauta onnistuneesta alustuksesta 0.

Koukku	Kutsumisajankohta
on_dns_query	Jäsennetyn kyselyn hyväksymisen jälkeen, ennen välimuistihakua tai välittämistä.
on_dns_response	Vastauksen valinnan jälkeen, ennen välimuistiin tallentamista tai asiakkaalle palauttamista. Myös välimuistivastaukset kulkevat tämän koukun kautta.
on_web_hello	Alustavan HTTP Host/TLS SNI -tarkistuksen jälkeen, ennen yhteyden muodostamista tai alkudatan käsittelyä.
on_web_data	Myöhemmän asiakas- tai palvelindatan lukemisen jälkeen, ennen välittämistä.

DNS-toiminnot

v2:n DNS-koukut palauttavat onnistuessaan 0 ja asettavat result->action-arvon.

Toiminto	Vaikutus
MUDFISH_DNS_CONTINUE	Jatkaa seuraavaan moduuliin ja tavalliseen käsittelyyn.
MUDFISH_DNS_ALLOW	Lopettaa nykyisen koukkuketjun ja jatkaa tavallista DNS-kyselyä tai palauttaa valitun vastauksen.
MUDFISH_DNS_BLOCK	Palauttaa REFUSED.
MUDFISH_DNS_DROP	Hylkää lähettämättä DNS-vastausta.
MUDFISH_DNS_ANSWER	Luo vastauksen annetusta IPv4/IPv6-osoitteesta ja TTL:stä.
MUDFISH_DNS_REPLACE	Käyttää moduulin toimittamaa täydellistä DNS-vastausta siirtomuodossa.

Älä palauta toimintovakiota suoraan v2:n DNS-koukusta. Muu palautusarvo kuin 0 tai virheellinen tulos aiheuttaa SERVFAIL-vastauksen. ALLOW päättää vain nykyisen koukkuketjun eikä ohita verkkotunnussääntöjä, yhteystavan lupia tai varmenteen tarkistusta. Muut kyselytulokset kuin DROP kulkevat myös vastauskoukun kautta.

Verkkokoukut palauttavat suoraan MUDFISH_DNS_CONTINUE tai MUDFISH_DNS_REJECT. Verkkopyynnön hylkääminen sulkee yhteyden. Verkkokoukut edellyttävät verkkosuojauksen käyttöönottoa, eikä purettua HTTPS-sisältöä tarjota.

Puskurit, säikeet ja välimuisti

Syötetapahtumat ja puskurit ovat vain luettavia ja voimassa vain callback-kutsun ajan. Korvaavan vastauksen täytyy käyttää moduulin omistamaa muistia, joka pysyy voimassa moduulin seuraavaan callback-kutsuun tai tuhoamiseen asti. Älä palauta pinomuistia tai tapahtumalta lainattua osoitinta. Korvaavan vastauksen DNS ID:n, opcoden ja kysymyksen täytyy vastata alkuperäistä kyselyä. Yhden instanssin callbackit suoritetaan peräkkäin, mutta niitä voidaan kutsua eri säikeistä. Suorita ne nopeasti äläkä välitä poikkeuksia ABI-rajan yli.

Luotuja, korvattuja, estettyjä tai hylättyjä tuloksia ei tallenneta isännän välimuistiin. Välimuistivastauksen korvaaminen ei muuta alkuperäistä välimuistimerkintää. Isäntä poistaa korvaavan vastauksen AD-lipun eikä tarkista tai allekirjoita DNSSEC:iä uudelleen. Allekirjoitettua dataa muuttavan moduulin täytyy käsitellä vanhentuneet allekirjoitukset itse.

Esimerkki ja otsake

Seuraavilla sivuilla ovat koko esimerkkikoodi ja tarvittava otsake. Mudfish DNS:n lähdekoodipuuta ei tarvitse ladata erikseen.

Tiedosto	Sisältö
policy.c — DNS-käytäntöesimerkki	DNS-kyselyn salliminen, estäminen ja hylkääminen, IP-vastauksen luonti sekä vastausosoitteen ja TTL:n muuttaminen. Mukana Linuxin käännös- ja testikomennot.
mudfish_dns_module.h — moduulin otsake	ABI-määrittelyt, koukkujen allekirjoitukset, toimintovakiot ja puskurien omistussäännöt.

Lataa policy.c ja mudfish_dns_module.h samaan hakemistoon ennen kääntämistä. Esimerkin käännöskomento tuottaa Linuxin .so-kirjaston.