מודולים מקוריים למפתחים

אין צורך במודולים לשימוש רגיל. המדריך מיועד למפתחים ולמנהלים שרוצים להרחיב את שירות 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 מבצעת שחזור בלי לטעון מודולים.

מימוש hooks

קראו את הכותרת mudfish_dns_module.h או הורידו את mudfish_dns_module.h. הכותרת מגדירה מבנים, hooks, פעולות וכללי משך חיים של נתונים. המדריך משתמש ב־C ABI v2. חשפו את mudfish_dns_module_init_v2(), ובדקו את MUDFISH_DNS_MODULE_ABI_V2 ואת גודל המבנה שהתקבל לפני מילוי ה־hooks. החזירו 0 אם האתחול הצליח.

hook	מועד הקריאה
on_dns_query	לאחר קבלת שאילתה שפוענחה ולפני חיפוש במטמון או העברה.
on_dns_response	לאחר בחירת תשובה ולפני שמירה במטמון או החזרה ללקוח. גם תשובות מהמטמון עוברות כאן.
on_web_hello	לאחר בדיקת HTTP Host/TLS SNI הראשונית ולפני חיבור או עיבוד הנתונים הראשוניים.
on_web_data	לאחר קריאת נתוני לקוח נוספים או נתוני שרת ולפני העברתם.

פעולות DNS

hooks של DNS ב־v2 מחזירים 0 בהצלחה ומגדירים את result->action.

פעולה	השפעה
MUDFISH_DNS_CONTINUE	המשך למודול הבא ולעיבוד הרגיל.
MUDFISH_DNS_ALLOW	סיום שרשרת ה־hooks הנוכחית והמשך שאילתת DNS רגילה או החזרת התשובה שנבחרה.
MUDFISH_DNS_BLOCK	החזרת REFUSED.
MUDFISH_DNS_DROP	השלכה בלי שליחת תשובת DNS.
MUDFISH_DNS_ANSWER	יצירת תשובה מכתובת IPv4/IPv6 ומ־TTL שסופקו.
MUDFISH_DNS_REPLACE	שימוש בתשובת DNS מלאה בפורמט wire שסיפק המודול.

אל תחזירו קבועי פעולה ישירות מ־DNS hooks ב־v2. ערך החזרה שאינו 0 או תוצאה לא תקינה גורמים ל־SERVFAIL. הפעולה ALLOW מסיימת רק את שרשרת ה־hooks הנוכחית ואינה עוקפת כללי שמות מתחם, הרשאות שיטות תקשורת או בדיקת אישורים. כל תוצאת שאילתה מלבד DROP עוברת גם ב־hooks של התשובה.

hooks של אינטרנט מחזירים ישירות MUDFISH_DNS_CONTINUE או MUDFISH_DNS_REJECT. דחיית בקשת אינטרנט סוגרת את החיבור. כדי להשתמש בהם, הגנת האינטרנט חייבת להיות מופעלת. תוכן HTTPS מפוענח אינו מסופק.

מאגרים, תהליכונים ומטמון

אירועי הקלט והמאגרים הם לקריאה בלבד ותקפים רק בזמן ה־callback. תשובה חלופית חייבת להשתמש בזיכרון שבבעלות המודול ולהישאר תקפה עד ל־callback הבא של אותו מודול או עד לסיומו. אל תחזירו זיכרון מחסנית או מצביע מושאל מאירוע. מזהה DNS, ‏opcode והשאלה בתשובה החלופית חייבים להתאים לשאילתה המקורית. callbacks של מופע אחד רצים ברצף, אך עשויים להיקרא מתהליכונים שונים. סיימו אותם במהירות ואל תעבירו חריגות מעבר לגבול ABI.

תוצאות שנוצרו, הוחלפו, נחסמו או הושלכו אינן נשמרות במטמון המארח. החלפת תשובה מהמטמון אינה משנה את הרשומה המקורית. המארח מנקה את דגל AD בתשובות חלופיות ואינו מאמת או חותם מחדש DNSSEC. מודול שמשנה נתונים חתומים חייב לטפל בעצמו בחתימות שאינן תקפות עוד.

דוגמה וכותרת

הדפים הבאים כוללים את כל קוד הדוגמה ואת הכותרת הדרושה. אין צורך להוריד בנפרד את עץ קוד המקור של Mudfish DNS.

קובץ	תוכן
policy.c — דוגמת מדיניות DNS	היתר, חסימה והשלכה של שאילתות, יצירת תשובת IP ושינוי כתובת ו־TTL בתשובה. כולל פקודות בנייה ובדיקה ב־Linux.
mudfish_dns_module.h — כותרת המודול	הצהרות ABI, חתימות hooks, קבועי פעולה וכללי בעלות על מאגרים.

לפני הבנייה הורידו את policy.c ואת mudfish_dns_module.h לאותה תיקייה. פקודת הבנייה בדוגמה יוצרת ספריית .so ל־Linux.