Módulo nativo (para desarrolladores)

No se requiere ningún módulo para uso general. Esta guía está dirigida a desarrolladores y administradores que desean ampliar la funcionalidad de los servicios de Windows o Linux con bibliotecas nativas. El módulo se ejecuta dentro de un servicio con privilegios de servicio. Instale solo código confiable y mantenga los archivos de módulo, dependencias y archivos de configuración propiedad de los administradores.

Cargar módulo

El servicio lee los archivos *.conf del directorio modules.d situado junto al archivo de configuración. Las ubicaciones predeterminadas son:

Sistema operativo	Ubicación de configuración del módulo	Formato de biblioteca
Linux	/etc/mudfish-dns/modules.d/	.so
Windows	%ProgramData%\Mudfish DNS\modules.d\	.dll

En cada archivo, escriba la ruta absoluta a la biblioteca, una por línea. Por ejemplo, el contenido de /etc/mudfish-dns/modules.d/10-policy.conf es:

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

Los archivos se leen por orden de nombre y sus líneas en orden. Se ignoran las líneas vacías y las que comienzan por #. No utilice comillas alrededor de las rutas, variables de entorno ni comentarios al final de línea: no se interpretan. En Windows también debe escribir la ruta absoluta completa, aunque contenga espacios.

Reinicie el servicio después de agregar, cambiar o quitar el módulo. En Linux, use el siguiente comando:

sudo systemctl restart mudfish-dns.service

En Windows, reinicie el servicio Mudfish DNS desde el administrador de servicios. Las opciones Iniciar DNS, Detener DNS y Aplicar configuración de la aplicación no recargan los módulos. El servicio no se inicia si no puede leer la configuración, una ruta es incorrecta o falla la carga o inicialización. Se permite que el directorio de módulos esté vacío o no exista.

Durante el desarrollo, puede especificar el argumento --module repetidamente para cargar las bibliotecas en el orden de los argumentos. En este caso reemplaza el autoload modules.d. --config FILE también cambia la ubicación del directorio del módulo junto al archivo de configuración. --restore-dns realiza la recuperación sin cargar ningún módulo.

Implementar hooks

Consulte Cabecera mudfish_dns_module.h o descargue mudfish_dns_module.h. Esta cabecera define las estructuras, los hooks, las acciones y las reglas de duración de los datos de los módulos. Esta guía utiliza la ABI C v2. Exporte mudfish_dns_module_init_v2() y compruebe MUDFISH_DNS_MODULE_ABI_V2 y el tamaño de la estructura recibida antes de rellenar los hooks. Devuelva 0 si la inicialización se completa correctamente.

Hook	Momento de la llamada
on_dns_query	Después de aceptar la consulta analizada y antes de buscar en la caché o reenviarla.
on_dns_response	Después de seleccionar una respuesta y antes de guardarla en caché o devolverla al cliente. Las respuestas de la caché también pasan por este hook.
on_web_hello	Después de completar la verificación inicial de HTTP Host/TLS SNI, pero antes de conectarse o procesar los datos iniciales.
on_web_data	Después de leer los datos posteriores del cliente o del servidor y antes de reenviarlos.

Acciones DNS

Los hooks DNS de v2 devuelven 0 si se completan correctamente y establecen result->action.

Acción	Efecto
MUDFISH_DNS_CONTINUE	Continúa con los siguientes módulos y el procesamiento normal.
MUDFISH_DNS_ALLOW	Termina la cadena de hooks actual y continúa con la consulta DNS normal o devuelve la respuesta seleccionada.
MUDFISH_DNS_BLOCK	Devuelve REFUSED.
MUDFISH_DNS_DROP	Descarta la consulta sin enviar una respuesta DNS.
MUDFISH_DNS_ANSWER	Genera una respuesta con la dirección IPv4/IPv6 y TTL proporcionados.
MUDFISH_DNS_REPLACE	Utiliza la respuesta DNS completa, en formato de transmisión, proporcionada por el módulo.

No devuelva directamente constantes de acción desde los hooks DNS de v2. Si la función devuelve un valor distinto de 0 o un resultado no válido, se produce SERVFAIL. ALLOW solo termina la cadena de hooks actual; no omite las reglas de dominio, los permisos de los métodos de comunicación ni la verificación de certificados. Los resultados de las consultas también pasan por el hook de respuesta, salvo DROP.

Los hooks web devuelven directamente MUDFISH_DNS_CONTINUE o MUDFISH_DNS_REJECT. Rechazar una solicitud web cierra la conexión. Requieren que la protección web esté activada y no reciben contenido HTTPS descifrado.

Búfers, subprocesos, caché

Los eventos y búferes de entrada son de solo lectura y solo son válidos durante la llamada al callback. Una respuesta alternativa debe utilizar memoria propiedad del módulo y permanecer válida hasta su siguiente callback o su finalización. No devuelva memoria de la pila ni punteros prestados del evento. El ID DNS, el opcode y la pregunta deben coincidir con la consulta original. Los callbacks de una instancia se ejecutan secuencialmente, aunque pueden llamarse desde distintos hilos. Deben terminar rápidamente y no propagar excepciones a través del límite de la ABI.

Los resultados de la creación, sustitución, bloqueo y descarte no se almacenan en la memoria caché del host. Reemplazar una respuesta almacenada en caché no cambia la entrada de caché original. El host borra el indicador AD en la respuesta alternativa y no realiza la validación DNSSEC ni la nueva firma. Los módulos que modifican datos firmados deben manejar ellos mismos las firmas invalidadas.

Ejemplos y cabecera

Las páginas siguientes contienen el código completo del ejemplo y la cabecera necesaria. No es necesario descargar por separado el código fuente de Mudfish DNS.

Archivo	Contenido
policy.c — Ejemplo de política DNS	Permitir, bloquear, descartar consultas DNS, generar respuestas IP, cambiar dirección de respuesta y TTL. También incluye comandos de compilación y prueba de Linux.
mudfish_dns_module.h — Cabecera del módulo	Declaraciones de la ABI, firmas de hooks, constantes de acción y reglas de propiedad de los búferes.

Antes de compilar, descargue policy.c y mudfish_dns_module.h en el mismo directorio. El comando del ejemplo genera una biblioteca .so para Linux.