Mô-đun native (dành cho nhà phát triển)

Việc sử dụng thông thường không cần mô-đun. Hướng dẫn này dành cho nhà phát triển và quản trị viên muốn mở rộng chức năng dịch vụ Windows hoặc Linux bằng thư viện native. Mô-đun chạy bên trong dịch vụ với quyền của dịch vụ. Chỉ cài mã đáng tin cậy và đảm bảo tệp mô-đun, các tệp phụ thuộc cùng tệp cấu hình thuộc quyền sở hữu của quản trị viên.

Tải mô-đun

Dịch vụ đọc các tệp *.conf từ thư mục modules.d nằm cạnh tệp cấu hình. Vị trí mặc định như sau.

Hệ điều hành	Vị trí cấu hình mô-đun	Định dạng thư viện
Linux	/etc/mudfish-dns/modules.d/	.so
Windows	%ProgramData%\Mudfish DNS\modules.d\	.dll

Trong mỗi tệp, ghi mỗi đường dẫn tuyệt đối đến thư viện trên một dòng. Ví dụ, nội dung /etc/mudfish-dns/modules.d/10-policy.conf như sau.

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

Các tệp được đọc theo thứ tự tên tệp, và nội dung mỗi tệp được đọc theo thứ tự dòng. Dòng trống và dòng bắt đầu bằng # bị bỏ qua. Không đặt đường dẫn trong dấu ngoặc kép, dùng biến môi trường hoặc chú thích cuối dòng; các cách viết này không được diễn giải. Trên Windows cũng cần ghi toàn bộ đường dẫn tuyệt đối vào tệp, kể cả đường dẫn có dấu cách.

Khởi động lại dịch vụ sau khi thêm, thay đổi hoặc xóa mô-đun. Trên Linux, sử dụng lệnh sau.

sudo systemctl restart mudfish-dns.service

Trên Windows, khởi động lại dịch vụ Mudfish DNS trong trình quản lý dịch vụ. Các thao tác Bắt đầu DNS, Dừng DNS và Áp dụng cài đặt trong ứng dụng không tải lại mô-đun. Dịch vụ không khởi động nếu không đọc được tệp cấu hình, đường dẫn không hợp lệ hoặc xảy ra lỗi tải hay khởi tạo. Thư mục mô-đun có thể không tồn tại hoặc để trống.

Trong quá trình phát triển, bạn có thể chỉ định đối số --module nhiều lần để tải thư viện theo thứ tự đối số. Cách này thay thế việc tự động tải modules.d. --config FILE cũng thay đổi vị trí thư mục mô-đun nằm cạnh tệp cấu hình. --restore-dns thực hiện khôi phục mà không tải mô-đun.

Triển khai hook

Đọc tệp tiêu đề mudfish_dns_module.h hoặc tải xuống mudfish_dns_module.h. Tệp tiêu đề này định nghĩa các cấu trúc, hook, hành động và quy tắc về vòng đời dữ liệu mà mô-đun sử dụng. Hướng dẫn này dùng C ABI v2. Xuất mudfish_dns_module_init_v2() và kiểm tra MUDFISH_DNS_MODULE_ABI_V2 cùng kích thước cấu trúc được truyền vào trước khi điền các hook. Trả về 0 nếu khởi tạo thành công.

Hook	Thời điểm gọi
on_dns_query	Sau khi nhận truy vấn đã phân tích, trước khi tra bộ nhớ đệm hoặc chuyển tiếp.
on_dns_response	Sau khi chọn phản hồi, trước khi lưu vào bộ nhớ đệm hoặc trả về máy khách. Phản hồi từ bộ nhớ đệm cũng đi qua hook này.
on_web_hello	Sau khi kiểm tra HTTP Host/TLS SNI ban đầu, trước khi kết nối hoặc xử lý dữ liệu ban đầu.
on_web_data	Sau khi đọc dữ liệu tiếp theo từ máy khách hoặc máy chủ, trước khi chuyển tiếp.

Hành động DNS

Hook DNS v2 trả về 0 khi thành công và đặt result->action.

Thao tác	Tác dụng
MUDFISH_DNS_CONTINUE	Tiếp tục với mô-đun tiếp theo và quá trình xử lý thông thường.
MUDFISH_DNS_ALLOW	Kết thúc chuỗi hook hiện tại rồi tiếp tục truy vấn DNS thông thường hoặc trả về phản hồi đã chọn.
MUDFISH_DNS_BLOCK	Trả về REFUSED.
MUDFISH_DNS_DROP	Loại bỏ mà không gửi phản hồi DNS.
MUDFISH_DNS_ANSWER	Tạo phản hồi bằng địa chỉ IPv4/IPv6 và TTL được cung cấp.
MUDFISH_DNS_REPLACE	Sử dụng phản hồi hoàn chỉnh ở định dạng truyền DNS do mô-đun cung cấp.

Không trả trực tiếp hằng số hành động từ hook DNS v2. Nếu hàm trả về giá trị khác 0 hoặc kết quả không hợp lệ, SERVFAIL sẽ xảy ra. ALLOW chỉ kết thúc chuỗi hook hiện tại, không bỏ qua quy tắc tên miền, quyền sử dụng phương thức truyền thông hoặc kiểm tra chứng chỉ. Mọi kết quả truy vấn ngoại trừ DROP đều đi qua hook phản hồi.

Hook web trả trực tiếp MUDFISH_DNS_CONTINUE hoặc MUDFISH_DNS_REJECT. Khi từ chối yêu cầu web, kết nối bị đóng. Để dùng hook web, bảo vệ web phải được bật; nội dung HTTPS đã giải mã không được cung cấp.

Bộ đệm, luồng và bộ nhớ đệm

Sự kiện và bộ đệm đầu vào chỉ được đọc và chỉ có hiệu lực trong thời gian thực thi callback. Phản hồi thay thế phải dùng bộ nhớ do mô-đun sở hữu và còn hiệu lực cho đến callback tiếp theo hoặc khi mô-đun đó kết thúc. Không trả về bộ nhớ trên ngăn xếp hay con trỏ mượn từ sự kiện. DNS ID, opcode và câu hỏi trong phản hồi thay thế phải khớp truy vấn ban đầu. Các callback của một thực thể chạy tuần tự nhưng có thể được gọi từ các luồng khác nhau. Hãy kết thúc callback nhanh và không để ngoại lệ lan qua ranh giới ABI.

Các kết quả được tạo, thay thế, chặn hoặc loại bỏ không được lưu vào bộ nhớ đệm của chương trình chủ. Thay thế phản hồi lấy từ bộ nhớ đệm không thay đổi mục gốc trong bộ nhớ đệm. Chương trình chủ xóa cờ AD của phản hồi thay thế và không xác minh DNSSEC hay ký lại. Mô-đun sửa đổi dữ liệu đã ký phải tự xử lý các chữ ký không còn hợp lệ.

Ví dụ và tệp tiêu đề

Các trang dưới đây cung cấp toàn bộ mã nguồn ví dụ và tệp tiêu đề cần thiết. Bạn không cần tải riêng cây mã nguồn Mudfish DNS.

Tệp	Nội dung
policy.c — ví dụ chính sách DNS	Cho phép, chặn, loại bỏ truy vấn DNS, tạo phản hồi IP, thay đổi địa chỉ và TTL trong phản hồi. Bao gồm cả lệnh biên dịch và kiểm thử trên Linux.
mudfish_dns_module.h — tệp tiêu đề mô-đun	Khai báo ABI, chữ ký hook, hằng số hành động và quy tắc sở hữu bộ đệm.

Trước khi biên dịch, tải policy.c và mudfish_dns_module.h vào cùng một thư mục. Lệnh biên dịch của ví dụ tạo thư viện .so cho Linux.