Modules natifs pour développeurs

Les modules ne sont pas nécessaires pour une utilisation courante. Ce guide s’adresse aux développeurs et administrateurs souhaitant étendre le service Windows ou Linux avec une bibliothèque native. Les modules s’exécutent dans le service avec ses privilèges. Installez uniquement du code de confiance et assurez-vous que les fichiers des modules, leurs dépendances et leur configuration restent la propriété de l’administrateur.

Charger un module

Le service lit les fichiers *.conf du dossier modules.d situé à côté du fichier de configuration. Les emplacements par défaut sont :

Système	Configuration des modules	Format de bibliothèque
Linux	/etc/mudfish-dns/modules.d/	.so
Windows	%ProgramData%\Mudfish DNS\modules.d\	.dll

Chaque fichier contient un chemin absolu de bibliothèque par ligne. Exemple de contenu de /etc/mudfish-dns/modules.d/10-policy.conf :

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

Les fichiers sont lus dans l’ordre de leur nom et les entrées dans l’ordre des lignes. Les lignes vides et celles commençant par # sont ignorées. N’entourez pas les chemins de guillemets et n’utilisez ni variables d’environnement ni commentaires en fin de ligne : ces expressions ne sont pas interprétées. Sous Windows aussi, indiquez le chemin absolu complet, même s’il contient des espaces.

Après l’ajout, la modification ou la suppression d’un module, redémarrez le service. Sous Linux :

sudo systemctl restart mudfish-dns.service

Sous Windows, redémarrez Mudfish DNS depuis le gestionnaire des services. Les boutons Démarrer le DNS, Arrêter le DNS et Appliquer les paramètres ne rechargent pas les modules. Un fichier de configuration illisible, un chemin incorrect ou une erreur de chargement ou d’initialisation empêche le démarrage du service. Un dossier de modules absent ou vide est accepté.

Pendant le développement, vous pouvez répéter l’argument --module pour charger les bibliothèques dans l’ordre des arguments. Cela remplace le chargement automatique de modules.d. --config FILE modifie aussi l’emplacement du dossier de modules situé à côté du fichier de configuration. --restore-dns effectue la restauration sans charger de modules.

Implémenter les hooks

Consultez l’en-tête mudfish_dns_module.h ou téléchargez mudfish_dns_module.h. Il définit les structures, hooks, actions et règles de durée de vie des données. Ce guide utilise l’ABI C v2. Exportez mudfish_dns_module_init_v2() et vérifiez MUDFISH_DNS_MODULE_ABI_V2 ainsi que la taille de structure reçue avant de renseigner les hooks. Retournez 0 si l’initialisation réussit.

Hook	Moment de l’appel
on_dns_query	Après acceptation de la requête analysée, avant consultation du cache ou transmission.
on_dns_response	Après sélection de la réponse, avant mise en cache ou retour au client. Les réponses en cache passent aussi par ce hook.
on_web_hello	Après inspection initiale de HTTP Host/TLS SNI, avant connexion ou traitement des données initiales.
on_web_data	Après lecture des données suivantes du client ou du serveur, avant transmission.

Actions DNS

Les hooks DNS v2 retournent 0 en cas de succès et définissent result->action.

Action	Effet
MUDFISH_DNS_CONTINUE	Poursuit avec le module suivant et le traitement normal.
MUDFISH_DNS_ALLOW	Termine la chaîne de hooks courante et poursuit la résolution normale ou renvoie la réponse sélectionnée.
MUDFISH_DNS_BLOCK	Renvoie REFUSED.
MUDFISH_DNS_DROP	Abandonne la requête sans réponse DNS.
MUDFISH_DNS_ANSWER	Génère une réponse avec l’adresse IPv4/IPv6 et le TTL fournis.
MUDFISH_DNS_REPLACE	Utilise la réponse DNS complète au format réseau fournie par le module.

Ne retournez pas directement une constante d’action depuis un hook DNS v2. Une valeur de retour non nulle ou un résultat invalide entraîne SERVFAIL. ALLOW termine uniquement la chaîne courante et ne contourne ni les règles de domaine, ni les autorisations de transport, ni la vérification des certificats. Tous les résultats de requête sauf DROP passent également par les hooks de réponse.

Les hooks Web retournent directement MUDFISH_DNS_CONTINUE ou MUDFISH_DNS_REJECT. Rejeter une requête Web ferme la connexion. La protection Web doit être activée pour utiliser ces hooks ; aucun contenu HTTPS déchiffré n’est fourni.

Tampons, threads et cache

Les événements et tampons d’entrée sont en lecture seule et valides uniquement pendant le callback. Une réponse de remplacement doit utiliser une mémoire appartenant au module et rester valide jusqu’au prochain callback de ce module ou à sa destruction. Ne retournez ni mémoire de pile ni pointeur emprunté à l’événement. L’identifiant DNS, l’opcode et la question doivent correspondre à la requête initiale. Les callbacks d’une instance sont exécutés séquentiellement, mais peuvent être appelés depuis différents threads. Ils doivent se terminer rapidement et ne pas propager d’exceptions à travers la frontière ABI.

Les résultats générés, remplacés, bloqués ou abandonnés ne sont pas stockés dans le cache de l’hôte. Remplacer une réponse issue du cache ne modifie pas l’entrée originale. L’hôte efface le drapeau AD des réponses de remplacement, sans validation DNSSEC ni nouvelle signature. Un module qui modifie des données signées doit gérer lui-même les signatures devenues invalides.

Exemple et en-tête

Les pages suivantes contiennent le code complet de l’exemple et l’en-tête nécessaire. Il n’est pas nécessaire de télécharger séparément les sources de Mudfish DNS.

Fichier	Contenu
policy.c — exemple de politique DNS	Autorisation, blocage et abandon de requêtes, génération de réponses IP, modification d’adresses et de TTL. Comprend les commandes de compilation et de test Linux.
mudfish_dns_module.h — en-tête du module	Déclarations ABI, signatures des hooks, constantes d’action et règles de propriété des tampons.

Avant compilation, téléchargez policy.c et mudfish_dns_module.h dans le même dossier. La commande de l’exemple génère une bibliothèque Linux .so.