โมดูลเนทีฟ (สำหรับนักพัฒนา)

การใช้งานทั่วไปไม่จำเป็นต้องมีโมดูล คู่มือนี้สำหรับนักพัฒนาและผู้ดูแลระบบที่ต้องการขยายฟังก์ชันของบริการ Windows หรือ Linux ด้วยไลบรารีเนทีฟ โมดูลทำงานภายในบริการโดยใช้สิทธิ์ของบริการ ติดตั้งเฉพาะโค้ดที่เชื่อถือได้ และให้ผู้ดูแลระบบเป็นเจ้าของไฟล์โมดูล ไฟล์ที่โมดูลพึ่งพา และไฟล์ตั้งค่า

โหลดโมดูล

บริการอ่านไฟล์ *.conf จากไดเรกทอรี modules.d ที่อยู่ข้างไฟล์ตั้งค่า ตำแหน่งเริ่มต้นมีดังต่อไปนี้

ระบบปฏิบัติการ	ตำแหน่งการตั้งค่าโมดูล	รูปแบบไลบรารี
Linux	/etc/mudfish-dns/modules.d/	.so
Windows	%ProgramData%\Mudfish DNS\modules.d\	.dll

ในแต่ละไฟล์ ให้ระบุเส้นทางสัมบูรณ์ของไลบรารีหนึ่งรายการต่อบรรทัด ตัวอย่างเช่น เนื้อหาของ /etc/mudfish-dns/modules.d/10-policy.conf เป็นดังต่อไปนี้

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

อ่านไฟล์ตามลำดับชื่อ และอ่านแต่ละไฟล์ตามลำดับบรรทัด ข้ามบรรทัดว่างและบรรทัดที่เริ่มด้วย # ห้ามครอบเส้นทางด้วยเครื่องหมายอัญประกาศ หรือใช้ตัวแปรสภาพแวดล้อมและความคิดเห็นท้ายบรรทัด เพราะระบบไม่ตีความรูปแบบเหล่านี้ บน Windows ให้เขียนเส้นทางสัมบูรณ์ทั้งหมดลงในไฟล์เช่นกัน รวมถึงเส้นทางที่มีช่องว่าง

หลังเพิ่ม เปลี่ยน หรือนำโมดูลออก ให้เริ่มบริการใหม่ บน Linux ใช้คำสั่งต่อไปนี้

sudo systemctl restart mudfish-dns.service

บน Windows ให้เริ่มบริการ Mudfish DNS ใหม่จากตัวจัดการบริการ การใช้ เริ่ม DNS, หยุด DNS หรือ ใช้การตั้งค่า ในแอปจะไม่โหลดโมดูลใหม่ หากอ่านไฟล์ตั้งค่าไม่ได้ เส้นทางไม่ถูกต้อง หรือเกิดข้อผิดพลาดในการโหลดหรือเริ่มต้น บริการจะไม่เริ่มทำงาน สามารถไม่มีไดเรกทอรีโมดูลหรือมีไดเรกทอรีว่างได้

ระหว่างพัฒนา สามารถระบุอาร์กิวเมนต์ --module ซ้ำเพื่อโหลดไลบรารีตามลำดับอาร์กิวเมนต์ ซึ่งจะแทนที่การโหลดอัตโนมัติจาก modules.d ส่วน --config FILE เปลี่ยนตำแหน่งไดเรกทอรีโมดูลข้างไฟล์ตั้งค่าด้วย และ --restore-dns ดำเนินการกู้คืนโดยไม่โหลดโมดูล

พัฒนาฮุก

อ่าน เฮดเดอร์ mudfish_dns_module.h หรือ ดาวน์โหลด mudfish_dns_module.h เฮดเดอร์นี้กำหนดโครงสร้าง ฮุก การทำงาน และกฎอายุข้อมูลที่โมดูลใช้ คู่มือนี้ใช้ C ABI v2 ให้ส่งออก mudfish_dns_module_init_v2() และตรวจสอบ MUDFISH_DNS_MODULE_ABI_V2 กับขนาดโครงสร้างที่ส่งเข้ามาก่อนกำหนดฮุก คืนค่า 0 เมื่อเริ่มต้นสำเร็จ

ฮุก	จังหวะที่เรียก
on_dns_query	หลังรับคำถามที่แยกวิเคราะห์แล้ว ก่อนค้นหาในแคชหรือส่งต่อ
on_dns_response	หลังเลือกคำตอบ ก่อนบันทึกในแคชหรือส่งคืนไคลเอนต์ คำตอบจากแคชก็ผ่านฮุกนี้เช่นกัน
on_web_hello	หลังตรวจสอบ HTTP Host/TLS SNI เริ่มต้น ก่อนเชื่อมต่อหรือประมวลผลข้อมูลเริ่มต้น
on_web_data	หลังอ่านข้อมูลถัดไปจากไคลเอนต์หรือข้อมูลจากเซิร์ฟเวอร์ ก่อนส่งต่อ

การทำงานกับ DNS

ฮุก DNS v2 จะ คืนค่า 0 เมื่อสำเร็จ และกำหนด result->action

การทำงาน	ผล
MUDFISH_DNS_CONTINUE	ดำเนินการโมดูลถัดไปและการประมวลผลตามปกติต่อ
MUDFISH_DNS_ALLOW	จบชุดฮุกปัจจุบัน แล้วดำเนินการค้นหา DNS ตามปกติต่อหรือคืนคำตอบที่เลือกไว้
MUDFISH_DNS_BLOCK	คืนค่า REFUSED
MUDFISH_DNS_DROP	ทิ้งคำขอโดยไม่ส่งคำตอบ DNS
MUDFISH_DNS_ANSWER	สร้างคำตอบด้วยที่อยู่ IPv4/IPv6 และ TTL ที่ให้มา
MUDFISH_DNS_REPLACE	ใช้คำตอบ DNS ในรูปแบบ wire ที่สมบูรณ์ซึ่งโมดูลจัดเตรียมให้

อย่าคืนค่าคงที่ของการทำงานโดยตรงจากฮุก DNS v2 หากฟังก์ชันคืนค่าที่ไม่ใช่ 0 หรือผลลัพธ์ไม่ถูกต้อง จะเกิด SERVFAIL ส่วน ALLOW จบเฉพาะชุดฮุกปัจจุบัน ไม่ข้ามกฎโดเมน การตรวจสอบว่าวิธีสื่อสารได้รับอนุญาตหรือไม่ หรือการตรวจสอบใบรับรอง ผลลัพธ์คำถามทั้งหมดนอกจาก DROP จะผ่านฮุกคำตอบด้วย

ฮุกเว็บคืนค่า MUDFISH_DNS_CONTINUE หรือ MUDFISH_DNS_REJECT โดยตรง หากปฏิเสธคำขอเว็บ จะปิดการเชื่อมต่อ ต้องเปิดการปกป้องเว็บจึงจะใช้ฮุกเว็บได้ และจะไม่มีเนื้อหา HTTPS ที่ถอดรหัสแล้วให้ใช้

บัฟเฟอร์ เธรด และแคช

เหตุการณ์และบัฟเฟอร์ขาเข้าเป็นแบบอ่านอย่างเดียว และใช้ได้เฉพาะระหว่างที่ callback ทำงาน คำตอบทดแทนต้องใช้หน่วยความจำที่โมดูลเป็นเจ้าของ และต้องยังใช้ได้จนถึง callback ครั้งถัดไปของโมดูลหรือจนโมดูลสิ้นสุด ห้ามคืนหน่วยความจำบนสแตกหรือตัวชี้ที่ยืมจากเหตุการณ์ DNS ID, opcode และคำถามของคำตอบทดแทนต้องตรงกับคำถามเดิม callback ของอินสแตนซ์เดียวกันทำงานตามลำดับ แต่อาจถูกเรียกจากคนละเธรดได้ ให้ callback จบอย่างรวดเร็ว และอย่าส่งข้อยกเว้นข้ามขอบเขต ABI

ผลลัพธ์ที่สร้าง แทนที่ ปิดกั้น หรือทิ้งจะไม่บันทึกในแคชของโฮสต์ การแทนที่คำตอบจากแคชไม่เปลี่ยนรายการแคชเดิม โฮสต์จะล้างแฟล็ก AD ของคำตอบทดแทน และไม่ตรวจสอบ DNSSEC หรือลงลายเซ็นใหม่ โมดูลที่แก้ข้อมูลที่ลงลายเซ็นต้องจัดการลายเซ็นที่ใช้ไม่ได้ด้วยตนเอง

ตัวอย่างและเฮดเดอร์

หน้าด้านล่างมีซอร์สตัวอย่างทั้งหมดและเฮดเดอร์ที่จำเป็น ไม่ต้องดาวน์โหลดซอร์สของ Mudfish DNS แยกต่างหาก

ไฟล์	เนื้อหา
policy.c — ตัวอย่างนโยบาย DNS	อนุญาต ปิดกั้น หรือทิ้งคำถาม DNS สร้างคำตอบ IP เปลี่ยนที่อยู่และ TTL ในคำตอบ รวมคำสั่งบิลด์และทดสอบบน Linux
mudfish_dns_module.h — เฮดเดอร์โมดูล	การประกาศ ABI รูปแบบฟังก์ชันฮุก ค่าคงที่ของการทำงาน และกฎความเป็นเจ้าของบัฟเฟอร์

ก่อนบิลด์ ให้ดาวน์โหลด policy.c และ mudfish_dns_module.h ไว้ในไดเรกทอรีเดียวกัน คำสั่งบิลด์ในตัวอย่างสร้างไลบรารี .so สำหรับ Linux