Moduły natywne (dla deweloperów)

Do zwykłego użytkowania moduły nie są potrzebne. Ten przewodnik jest przeznaczony dla deweloperów i administratorów rozszerzających funkcje usługi Windows lub Linux za pomocą bibliotek natywnych. Moduły działają wewnątrz usługi z jej uprawnieniami. Instaluj tylko zaufany kod i dbaj, aby właścicielem plików modułów, zależności i konfiguracji był administrator.

Ładowanie modułu

Usługa odczytuje pliki *.conf z katalogu modules.d obok pliku konfiguracji. Domyślne lokalizacje:

System	Konfiguracja modułów	Format biblioteki
Linux	/etc/mudfish-dns/modules.d/	.so
Windows	%ProgramData%\Mudfish DNS\modules.d\	.dll

W każdym pliku podaj po jednej bezwzględnej ścieżce biblioteki w wierszu. Na przykład /etc/mudfish-dns/modules.d/10-policy.conf może zawierać:

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

Pliki są odczytywane według nazw, a ich zawartość w kolejności wierszy. Puste wiersze i wiersze zaczynające się od # są pomijane. Nie ujmuj ścieżek w cudzysłowy, nie używaj zmiennych środowiskowych ani komentarzy na końcu wiersza: nie są interpretowane. Także w Windows wpisuj pełną bezwzględną ścieżkę, również gdy zawiera spacje.

Po dodaniu, zmianie lub usunięciu modułu uruchom usługę ponownie. W Linuksie:

sudo systemctl restart mudfish-dns.service

W Windows uruchom ponownie usługę Mudfish DNS w menedżerze usług. Przyciski Uruchom DNS, Zatrzymaj DNS i Zastosuj ustawienia nie przeładowują modułów. Jeśli nie można odczytać konfiguracji, ścieżka jest błędna lub ładowanie bądź inicjalizacja zakończy się błędem, usługa nie wystartuje. Brak katalogu modułów lub pusty katalog są dozwolone.

Podczas prac deweloperskich można wielokrotnie podawać argument --module, aby ładować biblioteki w kolejności argumentów. Zastępuje to automatyczne ładowanie z modules.d. --config FILE zmienia również lokalizację katalogu modułów obok konfiguracji. --restore-dns wykonuje przywracanie bez ładowania modułów.

Implementacja hooków

Przeczytaj nagłówek mudfish_dns_module.h lub pobierz mudfish_dns_module.h. Definiuje on struktury, hooki, działania i reguły czasu życia danych. Ten przewodnik używa C ABI v2. Wyeksportuj mudfish_dns_module_init_v2() i przed uzupełnieniem hooków sprawdź MUDFISH_DNS_MODULE_ABI_V2 oraz przekazany rozmiar struktury. Przy pomyślnej inicjalizacji zwróć 0.

Hook	Moment wywołania
on_dns_query	Po przyjęciu sparsowanego zapytania, przed sprawdzeniem pamięci podręcznej lub przekazaniem dalej.
on_dns_response	Po wybraniu odpowiedzi, przed zapisaniem w pamięci podręcznej lub zwróceniem klientowi. Obejmuje także odpowiedzi z pamięci podręcznej.
on_web_hello	Po początkowym sprawdzeniu HTTP Host/TLS SNI, przed połączeniem lub przetworzeniem danych początkowych.
on_web_data	Po odczycie kolejnych danych klienta lub danych serwera, przed przekazaniem dalej.

Działania DNS

Hooki DNS v2 zwracają 0 przy powodzeniu i ustawiają result->action.

Działanie	Skutek
MUDFISH_DNS_CONTINUE	Kontynuuje kolejne moduły i zwykłe przetwarzanie.
MUDFISH_DNS_ALLOW	Kończy bieżący łańcuch hooków i kontynuuje zwykłe zapytanie DNS lub zwraca wybraną odpowiedź.
MUDFISH_DNS_BLOCK	Zwraca REFUSED.
MUDFISH_DNS_DROP	Odrzuca bez wysyłania odpowiedzi DNS.
MUDFISH_DNS_ANSWER	Tworzy odpowiedź z podanego adresu IPv4/IPv6 i TTL.
MUDFISH_DNS_REPLACE	Używa kompletnej odpowiedzi DNS w formacie transmisyjnym dostarczonej przez moduł.

Nie zwracaj stałych działań bezpośrednio z hooków DNS v2. Niezerowy wynik funkcji lub nieprawidłowy rezultat powoduje SERVFAIL. ALLOW kończy tylko bieżący łańcuch hooków i nie omija reguł domen, zezwoleń na sposoby komunikacji ani weryfikacji certyfikatów. Wyniki zapytań poza DROP przechodzą również przez hook odpowiedzi.

Hooki WWW zwracają bezpośrednio MUDFISH_DNS_CONTINUE lub MUDFISH_DNS_REJECT. Odrzucenie żądania WWW zamyka połączenie. Hooki WWW wymagają włączonej ochrony WWW i nie udostępniają odszyfrowanej treści HTTPS.

Bufory, wątki i pamięć podręczna

Zdarzenia i bufory wejściowe są tylko do odczytu i są ważne wyłącznie podczas callbacku. Odpowiedź zastępcza musi używać pamięci należącej do modułu i pozostać ważna do następnego callbacku tego modułu lub jego zamknięcia. Nie zwracaj pamięci stosu ani wskaźników pożyczonych ze zdarzenia. ID DNS, opcode i pytanie odpowiedzi zastępczej muszą odpowiadać pierwotnemu zapytaniu. Callbacki jednej instancji są wykonywane kolejno, ale mogą być wywoływane z różnych wątków. Powinny kończyć się szybko i nie propagować wyjątków przez granicę ABI.

Wyniki wygenerowane, zastąpione, zablokowane lub odrzucone nie są zapisywane w pamięci podręcznej hosta. Zastąpienie odpowiedzi z pamięci podręcznej nie zmienia pierwotnego wpisu. Host usuwa flagę AD z odpowiedzi zastępczych i nie weryfikuje ani ponownie nie podpisuje DNSSEC. Moduł zmieniający podpisane dane musi sam obsłużyć unieważnione podpisy.

Przykład i nagłówek

Poniższe strony zawierają pełne źródło przykładu i wymagany nagłówek. Nie trzeba osobno pobierać drzewa źródłowego Mudfish DNS.

Plik	Zawartość
policy.c — przykład polityki DNS	Zezwalanie, blokowanie i odrzucanie zapytań DNS, tworzenie odpowiedzi IP oraz zmiana adresów i TTL odpowiedzi. Zawiera także polecenia budowania i testowania w Linuksie.
mudfish_dns_module.h — nagłówek modułu	Deklaracje ABI, sygnatury hooków, stałe działań i reguły własności buforów.

Przed budowaniem pobierz policy.c i mudfish_dns_module.h do tego samego katalogu. Polecenie z przykładu tworzy bibliotekę .so dla Linuksa.