ネイティブモジュール(開発者用)
一般的な使用にはモジュールは必要ありません。このガイドは、ネイティブライブラリでWindowsまたはLinuxサービスの機能を拡張したい開発者と管理者のためのものです。モジュールはサービス内部でサービス権限で実行されます。信頼できるコードのみをインストールし、モジュールファイル、依存ファイル、設定ファイルは管理者が所有するようにしてください。
モジュールのロード
サービスは設定ファイルと同じ場所にある modules.d ディレクトリから *.conf ファイルを読み込みます。デフォルトの場所は次のとおりです。
| オペレーティングシステム | モジュール設定位置 | ライブラリ形式 |
|---|---|---|
| Linux | /etc/mudfish-dns/modules.d/ | .so |
| Windows | %ProgramData%\Mudfish DNS\modules.d\ | .dll |
各ファイルには、ライブラリーの絶対パスを 1 行に 1 つずつ書き込んでいます。例えば
/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() をエクスポートし、フックを設定する前に ABI バージョンが MUDFISH_DNS_MODULE_ABI_V2 であることと、渡された構造体のサイズを確認してください。初期化に成功すると0を返します。
| フック | 呼び出し時点 |
|---|---|
on_dns_query | 解析された問合せを受け入れた後、キャッシュ照会や配信をする前。 |
on_dns_response | 応答が選択された後、キャッシュに保存するか、クライアントに返す前。キャッシュされた応答もこのフックを通過します。 |
on_web_hello | 初期 HTTP Host/TLS SNI 検査が終了した後、接続または初期データを処理する前。 |
on_web_data | 後続のクライアントデータまたはサーバーデータを読み取り、転送する前。 |
DNSの動作
v2 DNS フックは 成功時に 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ワイヤフォーマット応答を使用します。 |
v2 DNS フックから動作定数を直接返さないでください。関数がゼロ以外の値を返すか、結果が無効である場合 SERVFAILが発生します。 ALLOWは現在フックチェーンのみを終了し、ドメインルール、通信方法が許可されているかどうか、証明書チェックをバイパスしません。 DROPを除くクエリ結果は応答フックも経ます。
Web フックは MUDFISH_DNS_CONTINUE または MUDFISH_DNS_REJECTを直接返します。 Web要求を拒否すると、接続は終了します。 Webフックを使用するにはWeb保護がオンになっている必要があり、復号化されたHTTPSコンテンツは提供されません。
バッファ、スレッド、キャッシュ
入力イベントとバッファーは読み取り専用で、コールバックの実行中にのみ有効です。代替応答は、モジュールが所有するメモリーを使用し、そのモジュールの次のコールバックまたは終了時点まで有効でなければなりません。スタックメモリやイベントから借りたポインタを返さないでください。代替応答のDNS ID、opcode、および質問は元のクエリと一致する必要があります。あるインスタンスのコールバックは順次実行されますが、異なるスレッドで呼び出すことができます。コールバックは短く終了し、ABIの境界を超えて例外を伝播しないでください。
生成、置換、ブロック、破棄した結果はホストキャッシュに保存されません。キャッシュされた応答を置き換えても元のキャッシュエントリは変わりません。ホストは代替応答の AD フラグをクリアし、DNSSEC 検証または再署名を実行しません。署名されたデータを変更するモジュールは、無効化された署名を直接処理する必要があります。
例とヘッダー
以下のページには、サンプルソース全体と必要なヘッダーがあります。 Mudfish DNS ソースツリーを個別にダウンロードする必要はありません。
| ファイル | 内容 |
|---|---|
| policy.c — DNS ポリシーの例 | DNSクエリの許可、ブロック、破棄、IP応答の生成、応答アドレスとTTLの変更。 Linuxのビルドとテストコマンドも含まれています。 |
| mudfish_dns_module.h — モジュールヘッダー | ABI宣言、フックシグネチャ、動作定数、バッファ所有権ルール。 |
ビルド前に policy.cと mudfish_dns_module.hを同じディレクトリにダウンロードしてください。例のビルドコマンドはLinux .so ライブラリーを生成します。