Mga Native Module (Para sa Developer)
Hindi kailangan ng mga module para sa karaniwang paggamit. Ang gabay na ito ay para sa mga developer at administrator na nais magpalawak ng mga tampok ng serbisyo sa Windows o Linux gamit ang mga native library. Ang mga module ay tumatakbo sa loob ng serbisyo nang may mga pahintulot ng serbisyo. Mag-install lamang ng mapagkakatiwalaang code at panatilihing pagmamay-ari ng administrator ang mga module file, dependency file, at configuration file.
Pag-load ng Module
Binabasa ng serbisyo ang mga *.conf file mula sa direktoryong modules.d sa tabi ng configuration file. Ang mga default na lokasyon ay ang mga sumusunod:
| Operating System | Lokasyon ng Configuration ng Module | Format ng Library |
|---|---|---|
| Linux | /etc/mudfish-dns/modules.d/ | .so |
| Windows | %ProgramData%\Mudfish DNS\modules.d\ | .dll |
Sa bawat file, isulat ang absolute path ng library nang tig-iisa bawat linya. Halimbawa, ang nilalaman ng /etc/mudfish-dns/modules.d/10-policy.conf ay ang sumusunod:
/usr/lib/mudfish-dns/modules/policy.so
Binabasa ito ayon sa pagkakasunod-sunod ng pangalan ng file, at ayon sa pagkakasunod-sunod ng linya sa loob ng bawat file. Binabalewala ang mga blangkong linya at mga linyang nagsisimula sa #. Huwag palibutan ng mga panipi (quotes) ang path, at huwag gumamit ng mga environment variable o komento sa dulo ng linya. Hindi pinoproseso ang mga ganitong ekspresyon. Maging sa Windows, isulat ang buong absolute path sa loob ng file kabilang ang mga path na may espasyo.
Pagkatapos magdagdag, magbago, o mag-alis ng module, i-restart ang serbisyo. Sa Linux, gamitin ang sumusunod na command:
sudo systemctl restart mudfish-dns.service
Sa Windows, i-restart ang serbisyong Mudfish DNS mula sa Services management. Ang Simulan ang DNS, Ihinto ang DNS, at Ilapat ang Mga Setting sa app ay hindi muling naglo-load ng mga module. Kung hindi mabasa ang configuration file, mali ang path, o magkaroon ng error sa pag-load at pag-initialize, hindi magsisimula ang serbisyo. Pinapayagan kahit wala o walang laman ang direktoryo ng module.
Habang nagde-develop, maaaring paulit-ulit na tukuyin ang argument na --module upang i-load ang mga library ayon sa pagkakasunod-sunod ng argument. Sa ganitong sitwasyon, pinapalitan nito ang awtomatikong pag-load mula sa modules.d. Binabago rin ng --config FILE ang lokasyon ng direktoryo ng module sa tabi ng configuration file. Ang --restore-dns ay nagsasagawa ng pagpapanumbalik nang hindi naglo-load ng mga module.
Pagpapatupad ng Mga Hook
Basahin ang mudfish_dns_module.h header o
i-download ang mudfish_dns_module.h.
Tinutukoy ng header na ito ang mga struct, hook, aksyon, at panuntunan sa haba ng buhay (lifetime) ng data na ginagamit sa module.
Sa gabay na ito ay ginagamit ang C ABI v2. I-expose nang panlabas ang mudfish_dns_module_init_v2(), at suriin ang MUDFISH_DNS_MODULE_ABI_V2 at ang ipinasang laki ng struct bago punan ang mga hook. Nagbabalik ito ng 0 kapag nagtagumpay ang pag-initialize.
| Hook | Kailan Tinatawag |
|---|---|
on_dns_query | Pagkatapos tanggapin ang na-parse na query, bago maghanap sa cache o magpasa (forward). |
on_dns_response | Pagkatapos mapili ang tugon, bago i-save sa cache o ibalik sa client. Dumadaan din sa hook na ito ang mga naka-cache na tugon. |
on_web_hello | Pagkatapos ng paunang pagsusuri sa HTTP Host/TLS SNI, bago kumonekta o iproseso ang paunang data. |
on_web_data | Pagkatapos basahin ang kasunod na data ng client o data ng server, bago ipasa. |
Mga Aksyon sa DNS
Ang mga v2 DNS hook ay nagbabalik ng 0 kapag matagumpay at nagtatakda ng result->action.
| Aksyon | Epekto |
|---|---|
MUDFISH_DNS_CONTINUE | Ipinagpapatuloy ang susunod na module at karaniwang pagpoproseso. |
MUDFISH_DNS_ALLOW | Tinatapos ang kasalukuyang hook chain at ipinagpapatuloy ang karaniwang DNS query o ibinabalik ang piniling tugon. |
MUDFISH_DNS_BLOCK | Nagbabalik ng REFUSED. |
MUDFISH_DNS_DROP | Itinatapon nang hindi nagpapadala ng tugon sa DNS. |
MUDFISH_DNS_ANSWER | Gumagawa ng tugon gamit ang ibinigay na IPv4/IPv6 address at TTL. |
MUDFISH_DNS_REPLACE | Ginagamit ang kumpletong DNS wire format na tugon na ibinigay ng module. |
Huwag direktang ibalik ang mga constant ng aksyon mula sa v2 DNS hook. Kung magbalik ang function ng value na hindi 0 o hindi valid ang resulta, magaganap ang SERVFAIL. Tinatapos lamang ng ALLOW ang kasalukuyang hook chain at hindi nito bina-bypass ang mga panuntunan sa domain, pahintulot sa paraan ng komunikasyon, o pagsusuri sa certificate. Ang mga resulta ng query maliban sa DROP ay dumadaan din sa response hook.
Direktang ibinabalik ng mga web hook ang MUDFISH_DNS_CONTINUE o MUDFISH_DNS_REJECT. Kung tanggihan ang web request, isasara nito ang koneksyon. Upang magamit ang mga web hook, kailangang naka-on ang proteksyon sa web, at hindi ibinibigay ang na-decrypt na nilalaman ng HTTPS.
Mga Buffer, Thread, at Cache
Ang mga input event at buffer ay read-only at valid lamang habang tumatakbo ang callback. Ang kapalit na tugon ay dapat gumamit ng memory na pagmamay-ari ng module at dapat manatiling valid hanggang sa susunod na callback o pagtatapos ng nasabing module. Huwag magbalik ng stack memory o pointer na hiniram mula sa event. Ang DNS ID, opcode, at question ng kapalit na tugon ay dapat tumugma sa orihinal na query. Ang mga callback ng isang instance ay sunod-sunod na pinapatakbo ngunit maaaring tawagin mula sa magkakaibang thread. Tapusin nang mabilis ang mga callback at huwag magpalaganap ng mga exception lampas sa hangganan ng ABI.
Ang mga ginawa, pinalitan, hinarangan, o itinapong resulta ay hindi sine-save sa cache ng host. Kahit palitan ang naka-cache na tugon, hindi mababago ang orihinal na item sa cache. Binubura ng host ang AD flag ng kapalit na tugon at hindi nagsasagawa ng DNSSEC validation o muling pagpirma (re-signing). Ang mga module na nagbabago ng nilagdaang data ay dapat direktang humawak sa mga naging invalid na lagda.
Halimbawa at Header
Nasa mga pahina sa ibaba ang buong source ng halimbawa at ang kinakailangang header. Hindi na kailangang hiwalay na i-download ang source tree ng Mudfish DNS.
| File | Nilalaman |
|---|---|
| policy.c — Halimbawa ng Patakaran sa DNS | Pagpayag, pagharang, at pagtapon ng DNS query, paggawa ng IP na tugon, at pagbabago ng address ng tugon at TTL. Kasama rin ang mga command sa pag-build at pag-test sa Linux. |
| mudfish_dns_module.h — Header ng Module | Deklarasyon ng ABI, mga signature ng hook, mga constant ng aksyon, at mga panuntunan sa pagmamay-ari ng buffer. |
Bago mag-build, i-download ang policy.c at mudfish_dns_module.h sa parehong direktoryo. Ang build command sa halimbawa ay gumagawa ng Linux .so library.