MIHOMO / CONFIG.YAML
Clash 応用設定ガイド
通信の取り込み、名前解決、ルール判定、出口の選択を切り分けてから、該当する設定項目を変更しましょう。使い方ガイドでは、初回インストールやサブスクリプションの追加、接続確認を解説しています。このページでは、基本の接続が確認できた後に、設定の調整とトラブル対処を行います。まだインストールしていない場合は、アプリのダウンロードからOSに合ったパッケージを選んでください。各プラットフォームで推奨され、システム要件を満たすClash Plusが候補です。以下はmihomo標準の設定項目を基準にしています。クライアントの画面から各項目を設定できるかどうかは、使用するコアと設定の統合方法によって異なります。
プロキシグループの種類と出口の選び方
プロキシグループが決めるのは「ルールに一致した通信をどの出口に流すか」であり、「どの通信をこのルールに一致させるか」ではありません。Ruleモードでは、新しい接続に対してコアがrulesを上から順に照合し、一致したルールで指定されたプロキシグループに接続を渡します。グループからはノード、組み込みポリシー、別のグループを参照できますが、参照先が存在し、循環参照にならないことが条件です。たとえば、業務用グループから既定の出口グループを参照できますが、既定の出口グループから業務用グループを候補として参照することはできません。問題を調べるときは、まずルールの参照先グループを確認し、次にそのグループで現在選択されている項目を確認してください。
用途に合わせてグループの種類を選ぶ
| 種類 | 選択基準 | 用途 |
|---|---|---|
select | 手動で選択した候補を使用 | 出口を固定したい場合、トラブル対処時に要因を切り分ける場合 |
url-test | 接続テストの結果に基づいて候補を選択 | 入れ替え可能な出口が複数ある場合 |
fallback | リストの先頭にある利用可能な候補を優先 | メインの出口とバックアップを指定 |
load-balance | 指定した方式で接続を候補に振り分ける | 接続ごとに異なる出口を使ってもよい用途 |
安定した出口が必要な業務には、まずselectを使いましょう。たとえば、出口が変わるとログイン異常と判定するサービスでは、別のノードの応答速度が速くても自動で切り替えるべきではありません。メインとバックアップの回線にfallbackを使う場合は、一度の速度テストの結果ではなく、業務上の優先順位に従って候補を並べます。メイン回線が利用できないとき、新しい接続をバックアップ回線に切り替える用途に適しています。確立済みの長時間接続はシームレスに移行しないため、アプリ側で再接続や再ログインが必要になることがあります。
url-testのurlはテスト先、intervalは秒単位の間隔、toleranceはミリ秒単位の許容差です。候補間の差がわずかなときに、頻繁に切り替わるのを抑えられます。テストに成功しても、その出口からテスト先へ接続できることを示すだけで、会議、ファイル同期、特定のWebサイトも利用できるとは限りません。テスト先にすべての候補からアクセスできることを確認してください。定期的なテストは通信量と電力を消費します。同じ用途のグループごとに、同じノードを個別にテストする必要はありません。
load-balanceが振り分けるのは接続であり、1つのダウンロード内のパケットではありません。複数の接続を使うアプリでは、異なる出口が同時に使われることがあります。ハッシュ方式を使っても、接続先から見たIPアドレスが固定される保証にはなりません。まず候補が許容できる同じ範囲に属することを確認し、互いに独立した新しい接続を2つ作って振り分け結果を確かめましょう。Web操作やログイン状態の問題を調べるときは、出口を固定してください。アプリ側のセッション問題をプロキシプロトコルの障害と誤認しにくくなります。
まず組み込みポリシーでグループ参照を確認
以下は単独で読み込める最小構成の例です。サブスクリプションは不要です。既定では直接接続し、REJECTに手動で切り替えると、example.comとそのサブドメインだけを拒否します。グループの選択が反映されるかを確認するためのもので、プロキシ出口を確立する設定ではありません。すでにクライアントが同じポートを使用している場合は、別のテスト環境で実行するか、未使用のローカルポートに変更してください。
mixed-port: 7890
allow-lan: false
mode: rule
proxy-groups:
- name: ExamplePolicy
type: select
proxies:
- DIRECT
- REJECT
rules:
- DOMAIN-SUFFIX,example.com,ExamplePolicy
- MATCH,DIRECT
テストリクエストは、サンプル設定が待ち受けている入口を通す必要があります。接続ログでテストドメインがDOMAIN-SUFFIXに一致することを確認してから、ポリシーの経路にExamplePolicyが含まれているかを確認します。ポリシーを切り替えたら、対象アプリの接続を終了し、同じリクエストを新しく送信してください。ブラウザーの接続プールでは古い接続が再利用されることがあり、ページを再読み込みするだけでは新旧の結果を区別できない場合があります。ログにリクエストがまったくない場合は、グループ名やテスト設定ではなく、まず通信が取り込まれているかを調べてください。
サブスクリプションを追加した後は、グループからproxiesで特定のノード名を参照する方法と、useでノードプロバイダーを参照する方法があります。前者は候補が少なく固定の場合に、後者はサブスクリプションが定期的に更新される場合に適しています。グループに名前のフィルターを設定した場合は、更新後に候補が空になっていないか確認してください。グループ名は、その日の事業者側のノード名ではなく用途を表す名前にしましょう。サブスクリプションを変更しても候補の参照元だけを調整すればよく、業務ルールを1つずつ書き換えずに済みます。
設定を切り替えても候補が想定と異なる場合は、クライアントに前回の選択が保存されていないか、どの設定インスタンスを読み込んでいるかを確認してください。リストの順序と実行時の選択は別のものです。候補の並びだけを見て、実際の出口を判断することはできません。運用開始前に、明示的なルールに一致するドメイン、フォールバックするドメイン、バックアップ出口が必要な接続をそれぞれテストしてください。ルールの順序にまだ疑問がある場合は、GEOIP・GEOSITE・RULE-SETによる振り分けの実践ガイドもご覧ください。
ルールセットをサブスクリプションで管理
複数のドメインやIPアドレス範囲を個別に管理する場合は、ルールをrule-providersに置き、rulesからRULE-SETで参照します。プロバイダーはルール項目の取得と解析を担いますが、最終的な出口は参照元のルールで決まります。ルールセットの管理者は、メイン設定を変更せずにリストを更新できます。一方、メイン設定の参照名、照合順序、出口名は変わらないようにしてください。最初は対象が明確で範囲の限られたルールセットから始め、最初の移行であらゆる用途を1つの配布元に集約しないようにしましょう。
照合方式とファイル形式を選ぶ
behavior: domainはドメインの照合、ipcidrはIPアドレス範囲の照合に使います。classicalはルールの種類と照合対象で表します。たとえばDOMAIN-SUFFIX,example.orgのように記述します。クラシック形式のルールセットには出口名を含めず、メイン設定のRULE-SET行に出口を指定します。拡張子を変えただけでは実際のファイル形式は変わりません。format: yamlを使う場合、ルールファイルの項目はpayload配列に記述します。
リモートソースに切り替える前に、ローカルファイルで照合を確認しましょう。以下の例では、例示用ドメインをDIRECTに送り、それ以外の接続も直接接続します。そのため、出口が同じかではなく、接続ログで2つのルールを区別してください。ルールファイルはmihomoの作業ディレクトリからの相対パスに配置します。デスクトップクライアントが実行用設定を生成する場合、作業ディレクトリはサブスクリプションファイルの保存先とは異なることがあります。起動情報で確認してください。
# config.yaml に統合する。既存の rules がある場合は、ルール一覧だけを統合する。
rule-providers:
documentation:
type: file
behavior: classical
format: yaml
path: ./rules/documentation.yaml
rules:
- RULE-SET,documentation,DIRECT
- MATCH,DIRECT
# rules/documentation.yaml
payload:
- DOMAIN-SUFFIX,example.org
- DOMAIN-SUFFIX,example.net
リモート更新とルールの順序
リモート管理に切り替える場合は、プロバイダーのtypeをhttpに変更し、管理者が提示したルールファイルのurlを設定します。独立したローカルのpathを残し、intervalで更新間隔を秒単位で指定してください。複数のプロバイダーで同じキャッシュパスを共有すると、どのソースがファイルを書き込んだのか確実に区別できません。更新後は、実際に読み込まれた項目と更新日時を確認します。ブラウザーでファイルを開けても、コアが想定どおりの形式で取得できたとは限りません。ログイン画面やエラー説明が返される場合もあります。
初回起動時に利用できるキャッシュがない場合は、ルール配布元にネットワーク経由でアクセスできるかを特に確認してください。ルールファイルへのアクセスに特定の出口が必要で、その出口が同じルールセットや初期化前のノードに依存していると、起動条件が循環します。まず利用可能な設定でルールを取得して内容を確認するか、ローカルファイルで初期設定を構成してください。その後、リモート更新に使う経路を決めます。更新間隔を短くしても初回読み込みの失敗は解決しません。
ルールは上から順に照合され、最初に一致したものが適用されます。あるドメインが個別の例外ルールと広いルールセットの両方に該当する場合、記述順で結果が決まります。まず用途別の例外を記述し、次に範囲の狭いドメインセット、その後に広いアドレス範囲や地域ルールを記述して、MATCHは最後に置いてください。ルールセットの更新で追加された項目も既存の順序に従って適用されます。メイン設定に変更がないからといって、影響がないとは限りません。各リモートルールセットの適用範囲を明確にしておきましょう。
IPアドレスによる照合では、名前解決への影響も考慮してください。接続にドメイン名が含まれている場合、前方にあるIPルールの照合でDNSクエリが発生し、リモート名前解決や後続のドメインルールの調査が複雑になることがあります。すでに把握している宛先アドレスだけを照合したい場合は、対象となるIPルールまたはIP形式のルールセット参照にno-resolveを指定する方法を検討できます。ドメインを自動的にアドレスとして照合する設定ではなく、コア全体のDNSを無効にする設定でもありません。ドメイン名とIPアドレスをそれぞれテストしてから、このパラメーターを追加するか判断してください。
誤った振り分けが起きたら、失敗した接続の宛先、一致したルール、ルールセット名、出口を記録します。より上にあるルールに一致している場合は、順序または適用範囲を修正します。ルールセットに一致していない場合は、読み込み状態、項目の種類、ドメイン名が認識されているかを確認してください。ルールは正しいのに接続できない場合は、プロキシグループと出口を調べます。ロールバック用に、直前に動作していたメイン設定と対応するルールファイルを一緒に保管してください。参照設定だけを戻しても、新しいリストが読み込まれたままになることがあります。
DNSの上流サーバーと名前解決経路
DNSを調べるときは、まずどこからリクエストが送信され、どのリゾルバーに渡されるかを確認します。アプリはシステムのリゾルバーを使うことも、独自の暗号化DNSを使うこともあります。コアも必要に応じてクエリを送信します。たとえば、プロキシサーバーのドメイン名を解決する場合や、IPアドレスのルールに必要な宛先アドレスを取得する場合です。mihomoにdnsセクションを設定しても、すべてのアプリがその入口を使うわけではありません。名前解決の経路を確認するときは、ブラウザー、システム、コア、上流サーバーを分けて考え、システム設定に表示されているアドレスだけにすべてのクエリを結び付けないでください。
通常のDNSクエリ、上流サーバーの名前解決、ノードの名前解決を区別する
| 項目 | 役割 | 混同しやすい点 |
|---|---|---|
default-nameserver | ドメイン名で指定したDNS上流サーバーを名前解決する | 通常のドメインクエリで優先的に使うサーバー一覧ではない |
nameserver | 専用ポリシーが適用されない通常のクエリを処理する | 業務接続の最終的な出口は決めない |
nameserver-policy | ドメインなどの条件に応じてDNS上流サーバーを指定する | DNSクエリを照合する設定で、rulesとは別のもの |
proxy-server-nameserver | プロキシノードのサーバー名の名前解決専用 | プロキシ出口が確立する前でもアクセスできる必要がある |
まずは直接アクセスできるIPアドレスの上流サーバーで設定を動作させると、ドメイン名で指定した上流サーバー自体の名前解決という依存関係を減らせます。その後、暗号化上流サーバーやドメイン専用ポリシーを1つずつ追加してください。ノードのアドレスをドメイン名で指定し、その名前解決に未接続のノードを使う必要があると、出口の確立前に失敗します。respect-rulesを有効にする前に、mihomoの要件に従ってproxy-server-nameserverを設定し、同項目から使う出口が循環依存になっていないか確認してください。
次の例はループバックアドレスで待ち受け、コアのDNS機能を単独で確認するためのものです。直接クエリできるパブリックリゾルバーを使います。システムDNSは変更せず、この端末をLAN向けのDNSサーバーにする設定でもありません。確認段階ではredir-hostを使うと、実際のIPアドレス応答を確認しやすくなります。例に示した上流サーバーにネットワークからアクセスできることを確認してください。社内ネットワークで内部リゾルバーしか使えない場合は、管理者が指定したアドレスに置き換え、到達できないパブリックサーバーを予備として追加しないでください。
dns:
enable: true
listen: 127.0.0.1:1053
enhanced-mode: redir-host
nameserver:
- 223.5.5.5
proxy-server-nameserver:
- 223.5.5.5
dig @127.0.0.1 -p 1053 example.org A
ドメインごとにリゾルバーを指定し、通信の取り込み範囲を確認
内部ホストのレコードが組織内のリゾルバーにだけ存在する場合は、nameserver-policyを使って該当するドメインのサフィックスを内部の上流サーバーに転送し、そのリゾルバーへの経路が適切なインターフェースを通ることを確認してください。内部リゾルバーとパブリックリゾルバーを同じリストに並べても、内部と外部のクエリを分けることにはなりません。無関係な上流サーバーに内部名が送信される可能性もあります。確認には、存在が分かっている内部レコードとパブリックレコードをそれぞれ照会してください。管理画面で設定を読み込めたことだけでは、名前解決が正しいとは判断できません。
診断では3種類の結果を比較します。コアの待ち受けアドレスに直接クエリする、OSの既定のリゾルバーを使う、問題の起きているアプリで接続を再試行する、の3つです。1つ目では待ち受けと上流サーバーが基本的に動作していることを確認できます。2つ目では、システムがクエリをコアに渡しているかが分かります。3つ目で初めて、アプリが独自の名前解決やキャッシュを使っているかを確認できます。結果が異なっても、必ずしも異常ではありません。想定した経路で差を説明できるかが重要です。ブラウザー内蔵の暗号化DNSは、通常のポート53のクエリを取り込むだけでは書き換えられないことが一般的です。
DNS漏れを調べる前に、許可する名前解決経路を明確にします。たとえば、内部ドメインは組織のリゾルバー、通常の外部ドメインは指定したパブリック上流サーバー、アプリの暗号化名前解決には別の制約を適用する、といった形です。チェックサイトに表示されるのは再帰的な名前解決経路の出口であり、端末が直接接続しているサーバーのアドレスとは限りません。結果が想定と異なる場合は、システムやクライアントのクエリログと照らし合わせ、制御したリクエストを1つ送って経路を確認してください。複数のチェックサイトで同じ結果を繰り返し見るだけでは原因を特定できません。
クエリのタイムアウトと、応答はあるものの内容が違う場合は、分けて対処します。タイムアウトでは、待ち受けが起動しているか、上流サーバーに到達できるか、経路がコア自身に戻っていないかを確認してください。応答内容が違う場合は、専用ポリシー、キャッシュ、アドレスファミリー、アプリが別の名前解決経路を使っていないかを調べます。特定のアプリだけで失敗する場合は、まずそのアプリの経路を再現してください。設定項目の関係を確認するには、config.yamlの構成を詳しく解説も参照し、DNSセクションと出口ルールを逆に記述していないか確認してください。
AとAAAAをそれぞれ照会し、2つのアドレスファミリーを確認してください。DNSのIPv6応答だけを無効にしても、すべてのアプリの既存IPv6接続やシステムのルートが変わるわけではありません。反対に、インターフェースのIPv6だけを無効にしても、上流サーバーの名前解決失敗は解決しません。変更後は同じ入口からリクエストを再送信し、ドメイン名、クエリタイプ、応答結果を記録してください。DNS上流サーバー、TUN、ブラウザー設定を同時に変更すると、元に戻してもどの変更が影響したのか判断できなくなります。
TUNによる通信取り込みとFake-IPのマッピング
TUNはどの端末通信をコアに送るかを決め、Fake-IPは取り込んだドメインクエリにコアがどう応答するかを決めます。両者は連携できますが、解決する問題は異なります。システムプロキシは通常、システム設定に従うアプリだけに影響します。TUNは仮想インターフェースを通じて、より多くの通信を取り込めます。Fake-IPはドメインにマッピング用のIPアドレスを割り当てます。接続が同じコアインスタンスに届くとドメイン名に復元され、ドメインルールで判定できます。Fake-IPだけを有効にして、マッピングアドレスを使う接続がコアを迂回すると、名前解決は成功しても接続に失敗することがあります。
インターフェース、DNSの取り込み、マッピングの順に有効化
まず旧設定でコアと出口が正常に動作することを確認し、現在のデフォルトルートと既存のVPN・仮想ネットワークインターフェースを記録します。デスクトップクライアントでは通常、インターフェースの作成とルート変更の権限が必要です。モバイル端末ではOSのVPN機能から通信を取り込むため、クライアントの設定を使ってください。デスクトップ向けYAMLをそのままモバイル向けの設定手順として使わないでください。別のVPNも同時に使う場合は、使用環境に応じてどちらがデフォルトルートを管理するかを先に決め、起動順に頼らず併用できるかテストしましょう。
以下はデスクトップ環境向けの初期設定例です。動作確認済みの設定に統合してください。mixedはTUNのネットワークスタックの選択であり、mixed-portではありません。auto-routeは通信取り込みに必要なルートを設定し、auto-detect-interfaceは出口インターフェースの選択に使います。dns-hijackには、通常のDNSに該当するUDPとTCPをそれぞれ指定します。暗号化DNSが自動的にコアで解析可能な通常のクエリに変換されるわけではありません。
tun:
enable: true
stack: mixed
auto-route: true
auto-detect-interface: true
dns-hijack:
- any:53
- tcp://any:53
dns:
enable: true
enhanced-mode: fake-ip
fake-ip-range: 198.18.0.1/16
fake-ip-filter:
- '+.lan'
nameserver:
- 223.5.5.5
この例の除外項目は、該当ドメインにFake-IPを返すかどうかを決めるものです。実際に環境内で使われている内部名には実IPアドレスを返し、その名前を解決できる上流サーバーに専用の名前解決ポリシーで渡してください。除外項目を設定しても、直接接続ルールが追加されたり、実IPアドレス用に仮想インターフェースを迂回するルートが作られたりするわけではありません。社内プリンター、ファイル共有、サービス検出で問題が起きた場合は、名前解決、宛先アドレスへの実際の経路、アプリが使う検出プロトコルをそれぞれ確認してください。
通信経路に沿って問題箇所を特定
有効化した後、3種類の宛先で動作を確認します。ドメインルールを確認できるパブリックサイト、実際にアクセス可能なローカルリソース、システムプロキシ設定を使わないアプリです。パブリックサイトでは想定したルールに一致すること、ローカルリソースには必要に応じてアクセスできること、独立したアプリの接続がコアで確認できることを確かめてください。テスト前に対象アプリ独自のプロキシ設定を無効にします。別のローカルポート経由で接続されると、TUNで通信を取り込めていると誤認する可能性があります。
ドメインクエリがマッピング範囲内のアドレスを返しても、接続一覧に該当する記録がない場合は、宛先アドレスの経路とインターフェースを確認してください。特に、端末に重複するアドレス範囲がないかを調べます。別のVPNやLANに接続したときだけ問題が起きる場合は、ルートの優先順位、インターフェースの選択、アドレス範囲の競合を優先して確認しましょう。接続がコアに届いているのにドメイン名を認識できない場合は、マッピングを作成したインスタンスと接続を処理するインスタンスが同じか、アプリが古いマッピング結果を保持していないかを確認してください。
ネットワークインターフェースを切り替えた後は、自動選択が現場の要件に合うとは限りません。複数のネットワークカード、外付けアダプター、社内VPNを使う場合は、切り替え前後の実際の出口を記録し、デフォルトルートが変わったかを確認してください。アプリによっては、以前のインターフェースで確立した接続をしばらく維持するため、確立済みの長時間接続をテストに使うのは適切ではありません。取り込み範囲を限定する必要がある場合は、どのネットワークを元のインターフェースに残すかを明確にしてから、コアとプラットフォームが対応するルート設定を調整してください。対象通信と重複する可能性のあるネットワークを広範囲に除外しないでください。
端末全体がネットワークに接続できなくなった場合は、まずクライアントでTUNを無効にし、デフォルトルートとDNSの状態が戻るか確認してください。戻らない場合は、ルートを再設定しているサービスが残っていないか、別のVPNが通信を取り込んでいないかを調べます。基本のネットワークが復旧したら、TUNだけを有効にして問題を再現してください。テスト中にシステムプロキシを有効にしたり、ネットワークスタックを切り替えたり、アドレス範囲を調整したりしないでください。これらの変更は異なるレイヤーに作用するため、同時に行うと原因を特定しにくくなります。
比較のためにredir-hostに戻す場合は、アプリが以前のFake-IPをキャッシュして使い続けないよう、DNSクエリと接続の両方を新しく行ってください。比較結果には、DNS応答、ルールの一致、デフォルトルートのどれが変わったかを具体的に記録します。特定のプラットフォームだけで通信の取り込みに問題がある場合は、まず権限とVPNの状態を確認してから、よくある使用上の問題を参照してください。別のプラットフォームのシステム設定をそのまま移植しないでください。
ドメインスニッフィングと照合の範囲
ドメインスニッフィングは、宛先アドレスしか持たない接続にドメイン名の手掛かりを補う機能です。有効にする前に、通信が実際にコアに届いていることと、ドメイン名がないためにルールの照合を誤っていることを確認してください。プロキシリクエストに信頼できるドメイン名が含まれる場合やFake-IPのマッピングがある場合は、通常そのままドメインで照合できます。アプリがIPアドレスにしか接続せず、プロトコルにも認識可能な名前が含まれていない場合は、スニッフィングを有効にしても使えるドメイン名は得られません。
識別するプロトコルとポートを絞り込む
平文HTTPではリクエストヘッダーのHostからドメイン名を取得できます。TLSではハンドシェイクのSNIから取得できる場合があります。QUICでは対応するプロトコルの識別が必要で、ハンドシェイクデータや実際のネットワーク動作にも左右されます。ポートを限定すれば試行範囲は狭められますが、その通信が指定したプロトコルだと証明できるわけではありません。業務用ソフトの独自ポートをまとめてスニッフィング対象にせず、問題が起きる通信のプロトコルとポートを確認してから、対象を絞って有効にしてください。TLSスニッフィングを有効にしてもHTTPSのページ内容を読み取るわけではなく、証明書のインストールも必要ありません。
sniffer:
enable: true
parse-pure-ip: true
override-destination: false
sniff:
HTTP:
ports: [80, 8080]
TLS:
ports: [443]
QUIC:
ports: [443]
skip-domain:
- '+.lan'
ここではparse-pure-ipを有効にして、ドメイン名がない接続でも識別を試み、override-destinationを無効にしています。スニッフィングで得たドメイン名によって、元の接続先が書き換えられるのを防ぐためです。まずルールの判定に役立つかを確認し、その後、接続先を書き換える必要があるかを判断できます。この設定を万能な修正方法と考えないでください。サービスが固定アドレスで提供されている場合は、ハンドシェイクにドメイン名が含まれていても、名前解決をやり直さず元のアドレスに接続すべきことがあります。
skip-domainは、スニッフィング対象から除外したいことが分かっているドメインに使います。任意のIPアドレス範囲を除外する設定ではありません。アプリがIPアドレスを直接使う場合、処理の時点で照合できるドメイン名をコアが取得できないことがあります。このような問題では、まずプロトコルまたはポートの範囲を狭め、必要なら実際のコアの対応状況に合わせて宛先アドレスの除外項目を使ってください。存在しないドメイン名を指定して、アドレス範囲全体をスキップさせようとしないでください。ドメイン除外リストとDNSのFake-IPフィルターリストも、同じ設定として扱わないでください。
接続ログで有効化前後を比較する
テスト用ドメインには、位置が分かりやすい個別ルールをあらかじめ設定し、出口を結果の予測できるプロキシグループに一時的に固定します。スニッフィングを無効にして新しい接続を行い、宛先アドレスと一致したルールを記録します。有効にした後、同じアプリから再度接続し、ドメイン名が表示されるか、ルールが変わったか、最終的にアクセスできたかを確認してください。ログにドメイン名が追加されただけでルールが変わらない場合は、まずその名前に対する照合条件を確認します。SNIが表示されたことだけで、ドメイン振り分けが想定どおり動作したと判断しないでください。
同じIPアドレスで複数のWebサイトが提供されることがあります。接続ログに表示されるドメイン名は、その接続自体から取得したものである必要があります。同じアドレスで以前に確認した別のドメイン名をルールに流用しないでください。外側のドメイン名を取得できたとしても、それが示すのはハンドシェイクで確認された接続先にすぎない場合があり、利用者が最終的にアクセスしたサービスのホスト名と一致するとは限りません。アプリを正確に識別する必要がある場合は、元のリクエストドメインを保持できる接続方法を優先するか、名前解決と接続の両方を制御できる環境でFake-IPマッピングを使ってください。
暗号化クライアントハローによって、実際のサーバー名が隠される場合があります。また、TCPやUDPアプリの中には、最初から利用可能なドメイン名を送らないものもあります。その場合は、実際の宛先アドレスとポートに基づいて適用範囲が明確なルールを作るか、該当アプリの通信を特定の出口に送ってください。スニッフィング対象のポートをさらに広げても、存在しない名前を取得することはできず、誤認識の可能性が高まるだけです。このようなケースは「ドメイン名を観測できない」と扱い、ルールセットの管理不備と混同しないでください。
UDP通信だけで問題が再現する場合は、ブラウザーがQUICを使ったときにドメイン名を取得できているか、出口がその通信に対応しているか、失敗後にアプリがTCPに切り替えているかを切り分けてください。比較テストでは条件を1つだけ変え、切り替えるたびに新しい接続を確立します。TCPでは成功してUDPでは失敗しても、スニッフィング機能の異常とは限りません。出口のプロトコル、ルート、ファイアウォールも通信経路の前提条件です。反対に、スニッフィングでドメイン名を取得できても、パケットが出口を通過できたことを意味するわけではありません。
ログを共有する場合は、ルールの種類、プロトコル、ポート、問題が起きた順序を残し、内部ドメイン名など業務環境が分かる情報を削除してください。設定が有効だと確認できたら、テストで役立ったプロトコルとポートだけを残します。効果が特定のアプリだけに限られる場合は、再現条件と元に戻す項目を記録しましょう。クライアントの更新や設定上書きの変更後も同じ条件で比較でき、識別機能の変化か、通信の取り込み方法の変化かを見分けやすくなります。
ローカル上書きと複数サブスクリプションの統合
更新されるサブスクリプションと、長期的に管理するローカルルールは分けてください。サブスクリプションには更新されるノードを任せ、ローカルのメイン設定ではポート、プロキシグループ、ルールの順序、ログの設定を管理します。インポート済みのリモートサブスクリプション本文に直接項目を追加すると、次回の更新でリモートの内容に戻る可能性があります。クライアントの上書き機能を使う前に、対象が個別のサブスクリプション、すべての設定、生成後の実行設定のどれかを確認してください。また、リストが置き換え、先頭追加、その他の方法のどれで統合されるかも把握しておきましょう。
プロバイダーでノードの配布元を分ける
mihomoのノードプロバイダー形式に準拠したproxiesファイルを配布元として使う場合は、proxy-providersで複数の配布元を組み合わせられます。完全なサブスクリプションにはrules、dns、独自のプロキシグループが含まれることが多く、クライアントが自動的にノード専用ファイルへ分割してくれるとは限りません。インポート前にトップレベルの構造と実際の応答内容を確認してください。クライアントが完全な設定のインポートにしか対応していない場合は、明示的に用意された統合機能を使い、エクスポート後の最終設定を確認します。クライアント独自の上書き構文をコア標準の設定項目として扱わないでください。
# 両方のファイルが必要です。各ファイルには proxies リストを含むノード設定を記述します。
proxy-providers:
office:
type: file
path: ./providers/office.yaml
personal:
type: file
path: ./providers/personal.yaml
proxy-groups:
- name: Office
type: select
use: [office]
- name: Personal
type: select
use: [personal]
rules:
- DOMAIN-SUFFIX,example.org,Office
- DOMAIN-SUFFIX,example.net,Personal
- MATCH,DIRECT
この例では2つの配布元を別々の用途のグループに分けています。ドメイン名は、利用が許可され、その用途に実際に合致するものに置き換えてから接続をテストしてください。リストを整えるためだけに、すべての配布元を1つの自動選択グループに入れないでください。個人用の出口と業務用の出口では、到達できる範囲や利用条件が異なることが一般的です。混在させると、同じサイトの結果が時間によって変わり、問題の切り分けも難しくなります。複数の配布元に同名のノードがある場合は、変更されにくい配布元名を含めて区別し、画面に表示された実際の候補を確認してください。
動作するプロバイダーのリモートURLが用意されている場合は、type: httpに変更し、それぞれに別のurlとローカルキャッシュパスを設定します。配布元の更新頻度に合わせてintervalを指定してください。サブスクリプションURLにアクセス認証情報が含まれる場合があります。管理されたローカル設定またはクライアント内に保管し、公開リポジトリ、Web変換サービス、スクリーンショットに載せないでください。特定の配布元だけが利用できない場合は、まず影響を受ける用途別グループを特定します。問題を隠すために、すべてのグループを別の出口に置き換えないでください。
統合順序と最終的に有効な設定ファイルを確認
マッピングとリストでは、統合の対象が異なります。dnsを上書きする際、実装によってはマッピング全体が置き換わり、既存のドメインポリシーも失われることがあります。項目ごとに統合する実装では、以前の上流サーバーが残る場合があります。rulesにリストを追加するとき、新しいルールが既存のMATCHより後ろにあれば、決して一致しません。編集前に、全体を置き換えるのか、先頭に追加するのか、特定の項目の前に挿入するのかを明確にしてください。生成後は、編集画面で保存されたかではなく、最終ファイルを確認します。
グループ名とルールセット名を固定し、設定の別セクションから安定して参照できるようにしましょう。グループ名を変更した場合は、少なくともルールの出口と、他のグループからの参照を確認してください。ルールプロバイダー名を変更した場合は、RULE-SETと、そのセットを使うDNSポリシーも確認します。同名の項目がある場合は、どの定義を残すか先に決めてください。重複キーに対する統合ツールの偶然の動作に頼らないでください。YAMLをエディターで読み込めても、コアが想定どおりの構造を受け取っているとは限りません。
mihomoのバイナリーを単独で使う場合は、設定を読み込む前に検証コマンドを実行できます。以下のコマンドは、設定ファイルとプロバイダーの相対パスがある作業ディレクトリに移動済みで、端末にコアのコマンドがインストールされていることを前提とします。クライアントがコアを管理している場合は、クライアント標準の検証機能やログ機能を優先し、実際に使われるものと同じコアで最終設定を検証してください。テストしたファイルと実際に動作しているファイルが異なる事態を防げます。
mihomo -t -d . -f ./config.yaml
設定検証に合格しても、コアが現在の設定を受け付けられたことしか分かりません。リモートファイルの取得、各グループの候補の有無、業務通信の正しい振り分けまでは保証されません。実際に読み込んだ後、業務用、個人用、フォールバックの3種類の接続をそれぞれ試し、プロバイダーの読み込み状態、一致したルール、出口を確認してください。サブスクリプションを1回更新して同じテストを繰り返します。更新後もローカル変更と参照先が維持されて初めて、上書きの位置が適切だと判断できます。入力条件と想定結果をローカルの運用記録に残してください。
更新後に特定のグループだけが使えなくなった場合は、まず配布元でノード名が変わった、内容が空になった、項目形式が変わった可能性を確認し、その後に統合ロジックを調べます。すべてのグループに問題がある場合は、誤った基本サブスクリプションを読み込んでいないか、クライアントの更新で上書き範囲が変わっていないかを優先して確認してください。ロールバックでは、直前に動作していたメイン設定と対応するプロバイダーファイルを復元し、ルールの対象が存在することを確認してから、配布元を1つずつ戻します。長期運用では、手作業で一度直して再現条件を失うのではなく、どの入力が変わったかを特定できる状態を保つことが重要です。
外部コントローラーと実行状態
外部コントローラーはコアの管理インターフェースであり、プロキシ通信の入口ではありません。パネルから接続、ルール、グループの状態を確認できます。また、グループの選択変更、接続の切断、設定の調整ができる場合もあります。mixed-portやDNSの待ち受けポートとは役割が異なります。クライアント内蔵のパネルで足りるなら、別の待ち受けを有効にする必要はありません。独立した管理手段が必要な場合は、ループバックアドレスにバインドし、ローカルだけに保存する専用の強固なキーを設定してください。
ループバックアドレスにバインドし、認証を個別に設定
コントローラーの設定をトップレベルに統合してください。クライアントがすでに管理ポートを使用している場合は、現在の待ち受けアドレスを確認し、同じ端末上の複数のコアインスタンスがポートを取り合わないようにします。以下のキーは使い回しができないことを示すための例です。実行前に、端末上で生成した専用のランダム値に置き換えてください。allow-lan: falseは通常のプロキシ入口のLAN利用を制限できますが、コントローラー自身のループバックへのバインドや認証の代わりにはなりません。
external-controller: 127.0.0.1:9090
secret: "replace-with-local-random-value"
allow-lan: false
独立したパネルをローカルの静的リソースとして配信する場合は、使用するコアの設定方法に従ってexternal-uiを指定し、信頼できるローカル管理のパネルディレクトリを設定してください。コントローラーがパネルを提供する場合は、通常、同じ管理サービスの/ui/から開けるため、ブラウザーのオリジン間の問題を減らせます。パネルのファイルを配置していなくてもコントロールAPIは正常に動作することがあります。一方、パネルが表示されてもAPI認証に成功したとは限りません。両方を個別に確認してください。
以下のコマンドは、コアを実行している端末から認証付きの読み取り専用クエリを送信します。Bashとcurlが使える環境が対象です。キーは対話形式で入力し、コマンド本文やスクリプトファイルには保存しません。実行前にシェルのトレースが有効になっていないことを確認し、端末の録画やリクエストヘッダーを他人に渡さないでください。クライアント内蔵パネルを使う場合は、用意されている接続診断機能で代用できます。
read -rsp 'コントローラーキー:' controller_secret
printf '\n'
printf 'header = "Authorization: Bearer %s"\n' "$controller_secret" |
curl --fail --silent --show-error --config - \
http://127.0.0.1:9090/version
unset controller_secret
パネル、待ち受け、実際の設定を切り分ける
| 症状 | まず確認する項目 | 先に変更しない項目 |
|---|---|---|
| 接続が拒否される | サービスが起動しているか、接続先のアドレスとポートが現在のインスタンスに合っているか | ルールの順序とDNS |
| 認証エラーが返る | 現在のキーとパネルの接続設定が一致しているか | 待ち受け範囲 |
| APIは正常だがパネルが空白 | パネルのリソース、ブラウザーのセキュリティ制限、パネル内のAPIアドレス | コアの出口ポリシー |
| パネルにデータは表示されるが、想定したインスタンスではない | 実際の接続先アドレス、設定ファイル、バックグラウンドサービスの実行元 | モデルに依存しないその他のグループ設定 |
ローカルAPIから認証エラーが返る場合は、まず接続先のバックエンドインスタンスを間違えていないか確認し、その後でキーを入力し直します。トラブル対処のために認証を外さないでください。コマンドからは接続できるのに、ブラウザーでオリジン間通信や混在コンテンツのエラーが出る場合は、同一オリジンのローカルパネルで再確認します。Webページのスクリプトに対するセキュリティ制限はブラウザーの保護機能です。制限を無効にしたり、すべてのサイトを許可元にしたりしても解決にはなりません。特に提供元が不明なパネルを閲覧するときは、端末の管理用認証情報をそのページに入力しないでください。
コントローラーをすべてのインターフェースにバインドしたり、このポートをインターネットに転送したりしないでください。リモート管理が必要な場合は、組織で管理されているリモートデスクトップや管理経路を使い、端末上のローカルセッションからパネルを開く方法を優先します。ネットワーク側でアクセスが制限されていても、コントローラーには独立した認証を設定してください。複数のユーザーが同じ端末を使う場合は、設定ファイルのアクセス権を制限し、一般のプロキシポートと一緒にキーを他のプロセスやアカウントから読める共有ディレクトリに置かないようにします。
業務通信の問題を調べるときは、パネルを頻繁に操作するのではなく、まず状態の観察に使います。新しい接続の宛先、プロトコル、一致したルール、実際のポリシー経路を記録し、該当する項目を1つだけ変更してください。プロキシグループを切り替えた場合は、テスト接続を新しく作成します。既存のセッションでは以前の出口が使われ続けることがあります。画面上では変更が反映されても再起動後に失われる場合は、それが実行時の選択、クライアントに保存された設定、ローカルのメイン設定に書き込まれた永続的な変更のどれかを確認してください。これらを混同しないでください。
ログの詳細度も必要な範囲だけ上げてください。設定の読み込み失敗やドメイン識別の問題を調べるために短時間だけ詳細度を上げ、問題を再現したら元のレベルに戻します。接続先や個人の利用履歴を長期間蓄積しないためです。サポートを求めるときは、エラーの種類と関連部分を秘匿化した設定だけを共有し、実行設定全体を渡す必要はありません。パネルにノードとルールが表示されるのは、管理インターフェースから状態を読み取れることを示すだけです。プロキシが利用できるかどうかは、実際の接続ログと再現可能なリクエストで確認してください。
最終確認は順番に行います。アプリの通信がコアに届いていること、必要なドメインを解決または識別できること、想定したルールに一致すること、グループで利用可能な出口が選択されていることを確認してください。最後にサブスクリプションを1回更新して再読み込みし、少なくとも1つの重要なケースで状態が変わらないことを確かめます。基本の接続が確認できない場合は、使い方ガイドに戻ってインポートと接続を再確認してください。システムプロキシ、権限、ポートだけの問題であれば、よくある質問を確認すれば十分です。一度に設定全体を変更する必要はありません。