Modul native (untuk pengembang)

Modul tidak diperlukan untuk penggunaan biasa. Panduan ini untuk pengembang dan administrator yang ingin memperluas layanan Windows/Linux dengan pustaka native. Modul berjalan di dalam layanan dengan hak akses layanan. Pasang hanya kode tepercaya dan pastikan berkas modul, dependensi, serta konfigurasinya tetap dimiliki administrator.

Memuat modul

Layanan membaca *.conf dalam direktori modules.d di sebelah berkas konfigurasi. Lokasi bawaan:

Sistem operasi	Lokasi konfigurasi modul	Format pustaka
Linux	/etc/mudfish-dns/modules.d/	.so
Windows	%ProgramData%\Mudfish DNS\modules.d\	.dll

Tulis satu jalur absolut pustaka per baris. Contoh isi /etc/mudfish-dns/modules.d/10-policy.conf:

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

Berkas dibaca menurut urutan nama, lalu menurut urutan baris di dalamnya. Baris kosong dan baris yang diawali # diabaikan. Jangan gunakan tanda kutip, variabel lingkungan, atau komentar di akhir baris karena tidak ditafsirkan. Pada Windows pun tulis jalur absolut lengkap, termasuk jika mengandung spasi.

Setelah menambah, mengubah, atau menghapus modul, mulai ulang layanan. Pada Linux:

sudo systemctl restart mudfish-dns.service

Pada Windows, mulai ulang layanan Mudfish DNS melalui pengelola layanan. Mulai DNS, Hentikan DNS, dan Terapkan pengaturan dalam aplikasi tidak memuat ulang modul. Layanan tidak dimulai jika konfigurasi tidak dapat dibaca, jalur salah, atau pemuatan/inisialisasi gagal. Direktori modul yang tidak ada atau kosong diperbolehkan.

Selama pengembangan, ulangi argumen --module untuk memuat pustaka menurut urutan argumen. Ini menggantikan pemuatan otomatis modules.d. --config FILE juga mengubah lokasi direktori modul di sebelah konfigurasi. --restore-dns melakukan pemulihan tanpa memuat modul.

Mengimplementasikan hook

Baca Header mudfish_dns_module.h atau unduh mudfish_dns_module.h. Header mendefinisikan struktur, hook, tindakan, dan aturan masa hidup data. Panduan ini memakai C ABI v2. Ekspor mudfish_dns_module_init_v2() dan periksa MUDFISH_DNS_MODULE_ABI_V2 serta ukuran struktur yang diberikan sebelum mengisi hook. Kembalikan 0 jika inisialisasi berhasil.

Hook	Waktu pemanggilan
on_dns_query	Setelah kueri yang telah diurai diterima, sebelum pencarian cache atau penerusan.
on_dns_response	Setelah respons dipilih, sebelum disimpan dalam cache atau dikembalikan ke klien. Respons cache juga melewati hook ini.
on_web_hello	Setelah pemeriksaan awal HTTP Host/TLS SNI, sebelum menghubungkan atau memproses data awal.
on_web_data	Setelah data lanjutan klien atau server dibaca, sebelum diteruskan.

Tindakan DNS

Hook DNS v2 mengembalikan 0 saat berhasil dan mengatur result->action.

Tindakan	Efek
MUDFISH_DNS_CONTINUE	Melanjutkan modul berikutnya dan pemrosesan biasa.
MUDFISH_DNS_ALLOW	Mengakhiri rantai hook saat ini, lalu melanjutkan kueri DNS biasa atau mengembalikan respons terpilih.
MUDFISH_DNS_BLOCK	Mengembalikan REFUSED.
MUDFISH_DNS_DROP	Membuang tanpa mengirim respons DNS.
MUDFISH_DNS_ANSWER	Membuat respons dari alamat IPv4/IPv6 dan TTL yang diberikan.
MUDFISH_DNS_REPLACE	Memakai respons DNS lengkap dalam format wire yang disediakan modul.

Jangan mengembalikan konstanta tindakan langsung dari hook DNS v2. Nilai balik bukan 0 atau hasil tidak valid menyebabkan SERVFAIL. ALLOW hanya mengakhiri rantai hook saat ini; tidak melewati aturan domain, izin transport, atau pemeriksaan sertifikat. Hasil kueri selain DROP juga melewati hook respons.

Hook web langsung mengembalikan MUDFISH_DNS_CONTINUE atau MUDFISH_DNS_REJECT. Penolakan web menutup koneksi. Hook web memerlukan perlindungan web aktif dan tidak menerima isi HTTPS yang didekripsi.

Buffer, thread, dan cache

Event input dan buffer hanya boleh dibaca dan hanya valid selama callback. Respons pengganti harus memakai memori milik modul yang tetap valid hingga callback berikutnya pada modul tersebut atau penghentian modul. Jangan mengembalikan memori stack atau pointer pinjaman dari event. ID DNS, opcode, dan pertanyaan pada respons pengganti harus cocok dengan kueri asli. Callback satu instans berjalan berurutan, tetapi dapat dipanggil dari thread berbeda. Selesaikan callback dengan cepat dan jangan biarkan exception melintasi batas ABI.

Hasil yang dibuat, diganti, diblokir, atau dibuang tidak disimpan dalam cache host. Mengganti respons cache tidak mengubah entri cache aslinya. Host menghapus flag AD pada respons pengganti dan tidak melakukan validasi atau penandatanganan ulang DNSSEC. Modul yang mengubah data bertanda tangan harus menangani sendiri tanda tangan yang menjadi tidak valid.

Contoh dan header

Halaman berikut menyediakan contoh lengkap dan header yang diperlukan. Tidak perlu mengunduh pohon sumber Mudfish DNS secara terpisah.

Berkas	Isi
policy.c — Contoh kebijakan DNS	Mengizinkan, memblokir, membuang kueri, membuat respons IP, serta mengubah alamat respons dan TTL. Termasuk perintah build dan pengujian Linux.
mudfish_dns_module.h — Header modul	Deklarasi ABI, signature hook, konstanta tindakan, dan aturan kepemilikan buffer.

Unduh policy.c dan mudfish_dns_module.h ke direktori yang sama sebelum build. Perintah contoh menghasilkan pustaka Linux .so.