Native Module (für Entwickler)

Für den allgemeinen Gebrauch ist kein Modul erforderlich. Dieses Handbuch richtet sich an Entwickler und Administratoren, die die Funktionalität des Windows- oder Linux-Dienstes mit nativen Bibliotheken erweitern möchten. Das Modul läuft innerhalb eines Dienstes mit Dienstprivilegien. Installieren Sie nur vertrauenswürdigen Code und behalten Sie die Moduldateien, Abhängigkeiten und Konfigurationsdateien im Eigentum der Administratoren.

Modul laden

Der Dienst liest die Datei *.conf aus dem Verzeichnis modules.d neben der Konfigurationsdatei. Die Standardspeicherorte sind:

Betriebssystem	Modul-Einstellungsort	Bibliotheksformat
Linux	/etc/mudfish-dns/modules.d/	.so
Windows	%ProgramData%\Mudfish DNS\modules.d\	.dll

Schreiben Sie in jede Datei den absoluten Pfad zur Bibliothek, einen pro Zeile. Der Inhalt von /etc/mudfish-dns/modules.d/10-policy.conf lautet beispielsweise:

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

Liest in der Reihenfolge der Dateinamen und innerhalb jeder Datei in der Reihenfolge der Zeilen. Leerzeilen und Zeilen, die mit # beginnen, werden ignoriert. Umgeben Sie Pfade nicht mit Anführungszeichen, Umgebungsvariablen oder Kommentaren am Zeilenende. Diese Ausdrücke werden nicht interpretiert. Schreiben Sie in Windows den gesamten absoluten Pfad, einschließlich des Pfads mit Leerzeichen, in die Datei.

Starten Sie den Dienst neu, nachdem Sie Module hinzugefügt, geändert oder entfernt haben. Linux verwendet den folgenden Befehl:

sudo systemctl restart mudfish-dns.service

Starten Sie für Windows den Dienst Mudfish DNS in der Dienstverwaltung neu. DNS starten , DNS stoppen und Einstellungen anwenden in der App laden das Modul nicht neu. Der Dienst startet nicht, wenn die Einstellungsdatei nicht gelesen werden kann, der Pfad falsch ist oder ein Lade- und Initialisierungsfehler auftritt. Fehlende oder leere Modulverzeichnisse sind zulässig.

Während der Entwicklung können Sie das Argument --module wiederholt angeben, um Bibliotheken in der Reihenfolge der Argumente zu laden. In diesem Fall ersetzt es modules.d Autoload. --config FILE ändert auch den Speicherort des Modulverzeichnisses neben der Konfigurationsdatei. --restore-dns führt die Wiederherstellung durch, ohne Module zu laden.

Hook-Implementierung

Lesen Sie den mudfish_dns_module.h-Header oder laden Sie mudfish_dns_module.h herunter. Dieser Header definiert die vom Modul verwendeten Strukturen, Hooks, Aktionen und Datenlebensdauerregeln. In diesem Handbuch wird C ABI v2 verwendet. Exportieren Sie mudfish_dns_module_init_v2() nach außen und überprüfen Sie die Größe der übergebenen Struktur mit MUDFISH_DNS_MODULE_ABI_V2, bevor Sie den Hook füllen. Wenn die Initialisierung erfolgreich ist, wird 0 zurückgegeben.

Haken	Aufrufzeit
on_dns_query	Nach dem Akzeptieren der geparsten Abfrage, bevor der Cache abgefragt oder weitergeleitet wird.
on_dns_response	Nachdem eine Antwort ausgewählt wurde, bevor sie im Cache gespeichert oder an den Client zurückgegeben wird. Auch zwischengespeicherte Antworten durchlaufen diesen Hook.
on_web_hello	Nach dem ersten HTTP Host/TLS SNI Test, vor dem Verbinden oder Verarbeiten erster Daten.
on_web_data	Nach dem Lesen nachfolgender Client- oder Serverdaten, jedoch vor der Übertragung.

DNS-Betrieb

Der v2 DNS-Hook gibt bei Erfolg 0 zurück und setzt result->action.

Betrieb	Effekt
MUDFISH_DNS_CONTINUE	Setzt die normale Verarbeitung mit dem nächsten Modul fort.
MUDFISH_DNS_ALLOW	Beendet die aktuelle Hook-Kette und setzt die normale DNS-Abfrage fort oder gibt die ausgewählte Antwort zurück.
MUDFISH_DNS_BLOCK	Gibt REFUSED zurück.
MUDFISH_DNS_DROP	DNS Verwerfen ohne Senden einer Antwort.
MUDFISH_DNS_ANSWER	Erzeugt eine Antwort mit den von Ihnen angegebenen Adressen IPv4/IPv6 und TTL.
MUDFISH_DNS_REPLACE	Es nutzt die vollständige DNS-Drahtformatantwort, die vom -Modul bereitgestellt wird.

v2 DNS Aktionskonstanten nicht direkt von Hooks zurückgeben. Wenn die Funktion einen anderen Wert als 0 zurückgibt oder das Ergebnis ungültig ist, wird SERVFAIL ausgelöst. ALLOW beendet derzeit nur die Hook-Kette und umgeht keine Domänenregeln, die Akzeptanz von Kommunikationsmethoden oder die Zertifikatsprüfung. Abfrageergebnisse außer DROP durchlaufen ebenfalls einen Antwort-Hook.

Der Webhook gibt MUDFISH_DNS_CONTINUE oder MUDFISH_DNS_REJECT direkt zurück. Wenn eine Webanfrage abgelehnt wird, wird die Verbindung beendet. Für Webhooks muss der Webschutz aktiviert sein und entschlüsselte HTTPS-Inhalte sind nicht verfügbar.

Puffer, Threads, Cache

Eingabeereignisse und Puffer sind schreibgeschützt und nur während der Rückrufausführung gültig. Die Fallback-Antwort muss Speicher verwenden, der dem Modul gehört, und bis zum nächsten Rückruf oder Exit dieses Moduls gültig bleiben. Geben Sie keine Zeiger zurück, die aus dem Stapelspeicher oder Ereignissen entlehnt wurden. DNS ID, opcode, Fragen in der alternativen Antwort müssen mit der ursprünglichen Abfrage übereinstimmen. Rückrufe von einer Instanz werden nacheinander ausgeführt, können jedoch von verschiedenen Threads aufgerufen werden. Halten Sie Rückrufe kurz und verbreiten Sie keine Ausnahmen über die ABI-Grenze hinaus.

Die Ergebnisse des Erstellens, Ersetzens, Blockierens und Löschens werden nicht im Host-Cache gespeichert. Durch das Ersetzen einer zwischengespeicherten Antwort wird der ursprüngliche Cache-Eintrag nicht geändert. Der Host löscht das AD-Flag in der Ersatzantwort und führt keine DNSSEC-Überprüfung oder Neusignatur durch. Module, die signierte Daten ändern, müssen ungültige Signaturen selbst verarbeiten.

Beispiele und Überschriften

Die Seite unten enthält die vollständige Beispielquelle und die erforderlichen Kopfzeilen. Es ist nicht erforderlich, den Mudfish DNS-Quellbaum separat herunterzuladen.

Datei	Inhalt
policy.c – DNS Richtlinienbeispiel	DNS Anfragen zulassen, blockieren, verwerfen, Antwort generieren IP, Antwortadresse ändern und TTL. Enthält außerdem Linux-Build- und Testbefehle.
mudfish_dns_module.h – Modulkopf	ABI Deklarationen, Hook-Signaturen, Aktionskonstanten und Pufferbesitzregeln.

Laden Sie vor dem Erstellen policy.c und mudfish_dns_module.h in dasselbe Verzeichnis herunter. Die Build-Befehle im Beispiel erstellen die Bibliotheken Linux und .so.