Module native (pentru dezvoltatori)

Utilizarea obișnuită nu necesită module. Acest ghid se adresează dezvoltatorilor și administratorilor care extind serviciul Windows sau Linux cu biblioteci native. Modulele rulează în interiorul serviciului, cu privilegiile acestuia. Instalați numai cod de încredere și păstrați fișierele modulelor, dependențele și configurația în proprietatea administratorului.

Încărcarea unui modul

Serviciul citește fișierele *.conf din directorul modules.d aflat lângă fișierul de configurare. Locațiile implicite sunt:

Sistem	Configurația modulelor	Format bibliotecă
Linux	/etc/mudfish-dns/modules.d/	.so
Windows	%ProgramData%\Mudfish DNS\modules.d\	.dll

În fiecare fișier, introduceți câte o cale absolută de bibliotecă pe linie. De exemplu, /etc/mudfish-dns/modules.d/10-policy.conf poate conține:

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

Fișierele sunt citite în ordinea numelor, iar liniile în ordinea din fiecare fișier. Liniile goale și cele care încep cu # sunt ignorate. Nu folosiți ghilimele în jurul căilor, variabile de mediu sau comentarii la sfârșitul liniei: acestea nu sunt interpretate. Și în Windows trebuie introdusă calea absolută completă, inclusiv dacă are spații.

După adăugarea, modificarea sau eliminarea unui modul, reporniți serviciul. În Linux:

sudo systemctl restart mudfish-dns.service

În Windows, reporniți serviciul Mudfish DNS din administrarea serviciilor. Pornește DNS, Oprește DNS și Aplică setările din aplicație nu reîncarcă modulele. Dacă fișierul de configurare nu poate fi citit, calea este greșită sau încărcarea ori inițializarea eșuează, serviciul nu pornește. Absența directorului de module sau un director gol sunt permise.

În timpul dezvoltării, puteți repeta argumentul --module pentru încărcarea bibliotecilor în ordinea argumentelor, înlocuind încărcarea automată din modules.d. --config FILE schimbă și locația directorului de module de lângă configurație. --restore-dns efectuează restabilirea fără încărcarea modulelor.

Implementarea hook-urilor

Consultați antetul mudfish_dns_module.h sau descărcați mudfish_dns_module.h. Antetul definește structurile, hook-urile, acțiunile și regulile de durată de viață a datelor. Acest ghid folosește C ABI v2. Exportați mudfish_dns_module_init_v2() și verificați MUDFISH_DNS_MODULE_ABI_V2 și dimensiunea structurii primite înainte de completarea hook-urilor. Returnați 0 la inițializarea reușită.

Hook	Momentul apelării
on_dns_query	După acceptarea interogării parsate, înainte de consultarea cache-ului sau transmitere.
on_dns_response	După selectarea răspunsului, înainte de stocarea în cache sau returnarea către client. Și răspunsurile din cache trec prin acest hook.
on_web_hello	După verificarea inițială HTTP Host/TLS SNI, înainte de conectare sau procesarea datelor inițiale.
on_web_data	După citirea datelor ulterioare de la client sau server, înainte de transmitere.

Acțiuni DNS

Hook-urile DNS v2 returnează 0 la succes și setează result->action.

Acțiune	Efect
MUDFISH_DNS_CONTINUE	Continuă cu următorul modul și procesarea obișnuită.
MUDFISH_DNS_ALLOW	Încheie lanțul curent de hook-uri și continuă interogarea DNS obișnuită sau returnează răspunsul selectat.
MUDFISH_DNS_BLOCK	Returnează REFUSED.
MUDFISH_DNS_DROP	Elimină cererea fără răspuns DNS.
MUDFISH_DNS_ANSWER	Generează un răspuns cu adresa IPv4/IPv6 și TTL-ul furnizate.
MUDFISH_DNS_REPLACE	Folosește răspunsul DNS complet în format de rețea furnizat de modul.

Nu returnați direct constantele acțiunilor din hook-urile DNS v2. O valoare de retur diferită de 0 sau un rezultat nevalid produce SERVFAIL. ALLOW încheie numai lanțul curent; nu ocolește regulile de domeniu, permisiunile metodelor de transport sau verificarea certificatelor. Rezultatele interogărilor, cu excepția DROP, trec și prin hook-urile de răspuns.

Hook-urile web returnează direct MUDFISH_DNS_CONTINUE sau MUDFISH_DNS_REJECT. Respingerea unei cereri web închide conexiunea. Hook-urile web necesită protecția web activată și nu primesc conținut HTTPS decriptat.

Buffere, fire de execuție și cache

Evenimentele și bufferele de intrare sunt doar pentru citire și valabile numai în timpul callback-ului. Răspunsurile de înlocuire trebuie să folosească memorie deținută de modul, valabilă până la următorul callback al modulului sau la distrugere. Nu returnați memorie de pe stivă sau pointeri împrumutați din eveniment. ID-ul DNS, opcode-ul și întrebarea din răspunsul înlocuit trebuie să corespundă interogării originale. Callback-urile unei instanțe rulează secvențial, dar pot fi apelate din fire diferite. Încheiați-le rapid și nu propagați excepții peste limita ABI.

Rezultatele generate, înlocuite, blocate sau eliminate nu sunt stocate în cache-ul gazdei. Înlocuirea unui răspuns din cache nu modifică intrarea originală. Gazda șterge indicatorul AD din răspunsurile înlocuite și nu verifică sau resemnează DNSSEC. Modulele care modifică date semnate trebuie să gestioneze semnăturile invalidate.

Exemplu și antet

Paginile următoare conțin exemplul complet și antetul necesar. Nu trebuie să descărcați separat arborele sursă Mudfish DNS.

Fișier	Conținut
policy.c — exemplu de politică DNS	Permiterea, blocarea și eliminarea interogărilor, generarea răspunsurilor IP, modificarea adreselor și TTL-ului. Include comenzi de compilare și testare Linux.
mudfish_dns_module.h — antetul modulului	Declarații ABI, semnături de hook-uri, constante de acțiune și reguli de proprietate a bufferelor.

Înainte de compilare, descărcați policy.c și mudfish_dns_module.h în același director. Comanda exemplului generează o bibliotecă Linux .so.