Mòduls natius (per a desenvolupadors)

L'ús habitual no requereix mòduls. Aquesta guia s'adreça a desenvolupadors i administradors que volen ampliar el servei de Windows o Linux amb biblioteques natives. Els mòduls s'executen dins del servei i amb els seus privilegis. Instal·leu només codi de confiança i manteniu els fitxers dels mòduls, les dependències i la configuració sota propietat de l'administrador.

Carregar un mòdul

El servei llegeix els fitxers *.conf del directori modules.d situat al costat del fitxer de configuració. Les ubicacions predeterminades són:

Sistema operatiu	Configuració dels mòduls	Format de biblioteca
Linux	/etc/mudfish-dns/modules.d/	.so
Windows	%ProgramData%\Mudfish DNS\modules.d\	.dll

Escriviu un camí absolut de biblioteca per línia. Per exemple, /etc/mudfish-dns/modules.d/10-policy.conf pot contenir:

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

Els fitxers es llegeixen en ordre de nom i les línies en el seu ordre dins de cada fitxer. S'ignoren les línies buides i les que comencen amb #. No utilitzeu cometes al voltant dels camins, variables d'entorn ni comentaris al final de línia: no s'interpreten. A Windows també cal escriure el camí absolut complet, encara que contingui espais.

Reinicieu el servei després d'afegir, modificar o eliminar un mòdul. A Linux:

sudo systemctl restart mudfish-dns.service

A Windows, reinicieu Mudfish DNS des de la gestió de serveis. Les opcions Inicia el DNS, Atura el DNS i Aplica la configuració de l'aplicació no recarreguen els mòduls. Si un fitxer de configuració no es pot llegir, un camí és incorrecte o falla la càrrega o la inicialització, el servei no s'inicia. Es permet que el directori de mòduls no existeixi o estigui buit.

Durant el desenvolupament podeu repetir l'argument --module per carregar biblioteques en l'ordre dels arguments. Això substitueix la càrrega automàtica de modules.d. --config FILE també modifica la ubicació del directori de mòduls al costat de la configuració. --restore-dns fa la recuperació sense carregar mòduls.

Implementar hooks

Llegiu la capçalera mudfish_dns_module.h o descarregueu mudfish_dns_module.h. La capçalera defineix les estructures, els hooks, les accions i les regles de vida útil de les dades. Aquesta guia utilitza C ABI v2. Exporteu mudfish_dns_module_init_v2() i comproveu MUDFISH_DNS_MODULE_ABI_V2 i la mida de l'estructura rebuda abans d'emplenar els hooks. Retorneu 0 si la inicialització té èxit.

Hook	Moment de la crida
on_dns_query	Després d'acceptar la consulta analitzada, abans de consultar la memòria cau o transmetre-la.
on_dns_response	Després de seleccionar la resposta, abans de desar-la a la memòria cau o retornar-la al client. Les respostes de la memòria cau també hi passen.
on_web_hello	Després de la inspecció inicial d'HTTP Host/TLS SNI, abans de connectar-se o processar les dades inicials.
on_web_data	Després de llegir dades posteriors del client o del servidor, abans de transmetre-les.

Accions DNS

Els hooks DNS v2 retornen 0 si tenen èxit i estableixen result->action.

Acció	Efecte
MUDFISH_DNS_CONTINUE	Continua amb el mòdul següent i el processament habitual.
MUDFISH_DNS_ALLOW	Acaba la cadena actual de hooks i continua la consulta DNS habitual o retorna la resposta seleccionada.
MUDFISH_DNS_BLOCK	Retorna REFUSED.
MUDFISH_DNS_DROP	Descarta la consulta sense enviar cap resposta DNS.
MUDFISH_DNS_ANSWER	Genera una resposta amb l'adreça IPv4/IPv6 i el TTL proporcionats.
MUDFISH_DNS_REPLACE	Utilitza la resposta DNS completa en format de xarxa proporcionada pel mòdul.

No retorneu directament una constant d'acció des d'un hook DNS v2. Si la funció retorna un valor diferent de 0 o el resultat no és vàlid, es produeix SERVFAIL. ALLOW només acaba la cadena actual: no evita les regles de domini, els permisos de transport ni la verificació de certificats. Tots els resultats de consulta excepte DROP també passen pels hooks de resposta.

Els hooks web retornen directament MUDFISH_DNS_CONTINUE o MUDFISH_DNS_REJECT. Rebutjar una petició web tanca la connexió. Per utilitzar-los, cal activar la protecció web; no reben contingut HTTPS desxifrat.

Memòria intermèdia, fils i memòria cau

Els esdeveniments i les memòries intermèdies d'entrada són de només lectura i només són vàlids durant la crida de retorn. Una resposta substitutiva ha d'utilitzar memòria propietat del mòdul i continuar sent vàlida fins a la següent crida de retorn del mòdul o fins que es destrueixi. No retorneu memòria de la pila ni punters prestats de l'esdeveniment. L'ID DNS, l'opcode i la pregunta de la resposta han de coincidir amb la consulta original. Les crides d'una instància s'executen seqüencialment, però poden arribar des de fils diferents. Acabeu-les ràpidament i no propagueu excepcions a través del límit de l'ABI.

Els resultats generats, substituïts, bloquejats o descartats no es desen a la memòria cau de l'amfitrió. Substituir una resposta de la memòria cau no modifica l'entrada original. L'amfitrió esborra el senyalador AD de les respostes substitutives i no valida ni torna a signar DNSSEC. Un mòdul que modifiqui dades signades ha de gestionar les signatures que deixen de ser vàlides.

Exemple i capçalera

Les pàgines següents inclouen el codi complet de l'exemple i la capçalera necessària. No cal descarregar l'arbre de codi font de Mudfish DNS.

Fitxer	Contingut
policy.c — Exemple de política DNS	Permetre, bloquejar o descartar consultes, generar respostes IP i modificar adreces i TTL. Inclou ordres de compilació i prova per a Linux.
mudfish_dns_module.h — Capçalera del mòdul	Declaracions ABI, signatures dels hooks, constants d'acció i regles de propietat de la memòria intermèdia.

Descarregueu policy.c i mudfish_dns_module.h al mateix directori abans de compilar. Les ordres de l'exemple generen una biblioteca .so de Linux.