Shadowrocket
ルールと設定リファレンス

Shadowrocketの設定ファイルは、サーバー一覧の別名ではありません。サーバー情報は「どの接続先を使うか」を示し、設定ファイルは「特定のリクエストをどう処理するか」を定めます。Subscribeから既存のサブスクリプションを更新する操作は、通常、接続情報の更新です。Configで設定を切り替えると、ルールやDNS、アドレスのマッピングなどの動作が変わることがあります。両者は関連しますが、サブスクリプションを一度更新しただけですべての設定項目が同期されるわけではありません。トラブルを調べる際は、選択中のサーバーと現在有効な設定を別々に記録し、どちらか一方だけを確認して終わらないようにしましょう。

セクション名で役割を分け、ルール行で条件を指定

一般的な .conf テキストでは、角括弧でセクション名を示します。[General]には全体設定、[Rule]には上から順に判定するルール、[Host]にはホスト名とアドレスの静的マッピング、[URL Rewrite]には表示可能なリクエストURLに対する書き換え式を記述します。ファイル内のセクションの並び順が、すべての機能の実行順を意味するわけではありません。上から順に解釈するのは、Rule内のルール一覧です。「優先度を上げる」ためにHostセクションをファイルの先頭へ移動しないでください。

[General]
dns-server = system

[Rule]
DOMAIN-SUFFIX,example.com,PROXY
IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
FINAL,PROXY

[Host]
example.com = 192.0.2.10

この例では、3つの役割を分けて示しています。GeneralではシステムDNSを選び、Ruleでは例示用ドメインとローカルネットワークのアドレスを振り分け、Hostでは例示用ホスト名を説明用に予約されたアドレスへマッピングします。ここに記載したアドレスは書式の説明用であり、実際のサービス設定には使用しないでください。URL Rewriteは基本接続に必須ではないため、この最初の例には含めていません。振り分けだけを変更したい場合は、ほかのセクションをそのままにしておき、複数の条件を同時に変えたことによる誤判定を防ぎましょう。

編集前に有効な設定を確認

Configを開いたら、名前が似たファイルを編集し始める前に、現在選択されている設定を確認してください。リモートから取得した設定、ローカルに複製した設定、一時テスト用ファイルは、似た名前でも内容が異なることがあります。既存設定のコピーで試し、見分けやすいローカル名を付けて、取得元と変更の目的を記録しておくとよいでしょう。リモート設定を再度更新したときにローカルの変更が上書きされるかどうかは、保存方法によって異なります。長期的に使うルールは、管理しやすい場所に明確に保存してください。手動変更がすべてリモート設定に統合されるとは限りません。

テキストを保存したら、Configに戻り、そのファイルが選択されていることを確認します。続いてGlobal RoutingがConfigになっているか確認してください。編集が保存されたことは、テキストが記録されたことを示すだけで、新しいリクエストがすべてその設定で処理されることを意味しません。すでに確立された接続では以前の処理結果が残る場合があるため、検証には新しいリクエストを使用してください。クライアントに解析エラーが表示された場合は、まずエラーを修正してから接続テストを行います。読み込めない設定の結果と、直前に正常だった設定の結果を混同しないでください。

テキスト形式と変更範囲の最小化

ルールでは通常、フィールドを半角カンマで区切り、オプションでは半角イコールでキーと値をつなぎます。日本語入力で入った全角カンマ、見えない空白、リッチテキストからコピーした引用符は、見た目が似ていても解析エラーの原因になることがあります。プレーンテキストで編集し、1行に1つのルールを記述してください。説明文を未知のフィールドとして行末に追加しないようにしましょう。コードブロック以外の日本語説明は設定内容ではありません。コピー時に章番号や行番号を含めないでください。

一度に変更する動作は1つに絞りましょう。たとえばDOMAINルールを1行追加し、対象ドメインで動作を確認します。DNSの変更、書き換えの追加、FINALの移動、サーバーの切り替えを同時に行うと、結果が変わっても、どの変更が影響したのか判断できません。変更前の現象、変更した行、検証結果を記録しておけば、単に「設定を最適化」と残すよりも、次回の切り戻しに役立ちます。

ドメインルールの対象は、リクエスト処理中に取得できるホスト名です。ブラウザーのアドレスバーに表示されるURL全体ではありません。DOMAINにスキーム、ポート、パスまで記述しても、通常は意図した結果になりません。たとえばexample.com配下のページが対象でも、ドメイン欄に記述するのはホスト名だけです。パスに応じてリクエストを処理したい場合は、URL Rewriteの適用条件を別途検討してください。ドメインルールにパス判定をさせることはできません。

DOMAIN：1つの完全なホスト名を指定

DOMAIN,example.com,DIRECTは、ホスト名example.comへのリクエストにDIRECTを適用する指定です。api.example.comまで自動的に対象になるわけではなく、「サイト全体のすべてのリソースを直接接続する」という意味でもありません。1つのページから、ドメイン本体、静的リソース用ドメイン、API用ドメインなどへ同時にリクエストが送られることがあります。トップページが開いても、すべてのリクエストが同じルールにマッチしたとは限りません。特定のAPIだけを処理する場合はDOMAINの範囲を確認しやすく、後から例外を解除する際にも管理しやすくなります。

[Rule]
DOMAIN,api.example.com,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
FINAL,PROXY

この例では、まずapi.example.comにDIRECTを指定し、その後でexample.comとそのサブドメインにPROXYを指定しています。例外は、対象範囲の広いサフィックスルールより前に置く必要があります。後ろに置くと、リクエストが先にサフィックスルールにマッチし、個別ルールは判定されません。結果を決めるのは行の順序であり、DOMAINというキーワードがDOMAIN-SUFFIXより本質的に「優先度が高い」わけではありません。

DOMAIN-SUFFIX：ドメインとサブドメインを対象にする

DOMAIN-SUFFIXは、同じドメイン配下をまとめて処理したい場合に適しています。DOMAIN-SUFFIX,example.com,PROXYと記述すると、example.comとそのサブドメインが対象になります。パスを付けて記述する必要はなく、先頭にアスタリスクを付ける必要もありません。サフィックスのマッチはドメインの境界に基づくため、文字列の末尾が似ているだけでマッチすると判断しないでください。管理時は本当に対象にしたいドメインの範囲を選び、行数を減らすためだけに無関係なホストまで含めないようにしましょう。

DOMAIN-KEYWORD：対象範囲が広く、管理にも注意が必要

DOMAIN-KEYWORDは、ドメインに指定した文字列が含まれるかを確認します。ページタイトル、検索語、ウェブページ本文を検索するものではありません。DOMAIN-KEYWORD,example,PROXYはキーワードによる条件を指定できますが、マッチしたホストがすべて同じサービスに属するとは限りません。キーワードが短いほど、意図していないリクエストまで対象にする可能性が高くなります。明確なドメイン一覧がある場合はDOMAINまたはDOMAIN-SUFFIXを優先し、対象範囲が広くなることを承知したうえで、必要な場合にのみキーワードルールを使いましょう。

キーワードルールは、後ろにある例外を無効にしてしまうことがあります。テストではマッチする想定のホストだけでなく、マッチしてはいけないホストも確認し、対象範囲が広がっていないか検証してください。キーワードがリモート設定由来の場合は、近くのルールやコメントも読み、関連する例外がないか確認しましょう。元の文脈を理解せずに1行だけコピーすると、限定的だった条件が広範囲に適用されるおそれがあります。

ドメインが存在しても、クライアントが取得できるとは限らない

アプリによってはIPアドレスへ直接接続したり、アプリ内で接続先を選択したりします。その場合、振り分け時に判定用のホスト名を取得できないことがあります。リクエスト記録にアドレスしか表示されない場合、すぐにDOMAIN-SUFFIXの書き間違いだと決めつけないでください。まず、リクエストがドメイン名で開始されたのか、接続先IPだけが渡されたのかを確認します。そのうえで、アドレスルールを追加するか判断しましょう。共有アドレスや動的な名前解決の環境で、IPからドメインを推測して結論を出すと誤る可能性があります。

ウェブページのリダイレクトによって、2回目のリクエストが別のホストに送られることもあります。最初のドメインが正しくマッチしても、後続のリソースには異なるポリシーが適用される場合があります。検証では、ユーザーが覚えているサイト名ではなく、リクエスト記録にある実際のホスト名を確認してください。広いルールと例外の関係を詳しく知りたい場合は、カスタムルール、マッチ順序、FINALもご覧ください。その後、この章に戻り、マッチ範囲を1つずつ絞り込んでください。

アドレスルールが判定するのは接続先アドレスであり、ウェブページの言語、利用者の所在地、サービス提供者名ではありません。リクエストが先行するドメインルールにマッチしなかった場合、アドレス条件で続けて判定できます。より前のルールにすでにマッチしていれば、後続のIP-CIDRやGEOIPが同じリクエストのポリシーを改めて選ぶことはありません。この点を理解すると、「アドレスの分類結果が想定と違う」問題と「リクエストがそもそもアドレスルールまで到達していない」問題を区別できます。

IP-CIDR：プレフィックスでIPv4の範囲を指定

CIDRは、アドレスとスラッシュの後ろに続くプレフィックス長で構成されます。プレフィックスが長いほど範囲は小さくなります。192.168.0.0/16はプライベートアドレスの範囲を示し、192.168.1.10/32は1つのIPv4アドレスだけを示します。アドレス欄にポート番号を含めたり、開始・終了アドレスをハイフンでつないだりしないでください。ローカルデバイスにDIRECTを設定する場合は、実際のデバイスアドレスとサブネットを確認します。例に特定のプライベートアドレスが記載されていても、ご自身のネットワークが同じ範囲だとは限りません。

[Rule]
IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
IP-CIDR,172.16.0.0/12,DIRECT,no-resolve
IP-CIDR6,fc00::/7,DIRECT,no-resolve
FINAL,PROXY

このルール例はプライベートアドレスのマッチを説明するもので、ローカルネットワーク全体を許可する設定ではありません。LANへのアクセスは、システムのネットワーク権限、デバイスのファイアウォール、待ち受けアドレス、ルーティングにも左右されます。DIRECTにマッチしたことは、選択中のプロキシを経由しないことを示すだけで、プリンター、ファイル共有、ローカルサービスへ必ず接続できるという意味ではありません。検証時は、対象サービスが動作しているか、同じネットワーク上の別のデバイスからアクセスできるかも確認してください。

no-resolve：このルールの判定だけを目的とした名前解決を避ける

アドレスルール末尾のno-resolveは、そのルールへのマッチを試みるためだけにドメイン名を解決することを避ける指定です。「クライアント全体のDNSを無効にする」「すでにあるアドレス情報をすべて無視する」という意味ではありません。リクエストがもともとIPを使用している場合や、処理中に利用可能なアドレスをすでに取得している場合は、該当するアドレス判定が行われることがあります。no-resolveを追加すればあらゆるDNS問題が直るわけではなく、ドメインルールを必ず優先させるスイッチでもありません。

ローカルアドレスルールにこのパラメーターを付けるのは、未解決の各ドメインについて、ローカルネットワークの判定だけを理由に余分な名前解決を発生させないためです。実際の動作は、リクエストがルール判定に入った時点で取得できている情報によって異なります。対象がドメイン名なのにローカルアドレスルールにマッチしない場合は、パラメーターをすぐ削除して偶然の変化を結論とせず、名前解決の結果とリクエスト記録を確認してください。

GEOIP：アドレスデータベースの分類であり、サービスの所属先ではない

GEOIP,CN,DIRECTは、アドレスデータベース上の地域分類に基づいてDIRECTを選択します。ここでのCNはルールのパラメーターで、「中国語のウェブページ」や「特定地域向けのサービスすべて」を意味しません。同じホストが複数のアドレスを使うことがあり、コンテンツ配信ネットワークでは、接続元のネットワークによって名前解決の結果が変わる場合もあります。アドレスごとに分類が異なることもあります。また、データベースの記録と実際のネットワーク構成には時間差がある場合があるため、GEOIPは大まかな範囲を指定する条件として使い、サービスの正確な所属を判定するものとして扱わないでください。

[Rule]
DOMAIN-SUFFIX,example.com,PROXY
GEOIP,CN,DIRECT
FINAL,PROXY

この例では、example.comはまずドメインルールで処理先が決まります。解決されたアドレスがCNに分類されても、後続のGEOIPによってDIRECTに変更されることはありません。ドメインルールにマッチしないほかのリクエストが、GEOIPで判定される可能性があります。特定のサービスに固定のポリシーを適用したい場合は、既知のホストに明確なドメインルールを設定し、残りのリクエストをGEOIPで処理すると、後から結果を説明しやすくなります。

IPv6は別途確認し、IPv4の結果をそのまま当てはめない

IPv4とIPv6は別のアドレスファミリーです。IP-CIDRを記述しただけでIPv6まで対象になるわけではありません。IPv6のプレフィックスを指定するにはIP-CIDR6を使用します。ドメインが両方のアドレスを返す場合、アプリが最終的にどちらを使うかはシステムやネットワークの条件にも左右されます。一度接続できても、その経路が利用できることを示すだけで、もう一方のアドレスファミリーも使えるとは限りません。トラブルシューティングでは、実際の接続先アドレスを記録し、ルールとネットワーク接続を個別に確認してください。

ルールの条件は「マッチするかどうか」を決め、ポリシーは「マッチした後に何をするか」を決めます。PROXY、DIRECT、REJECTはそれぞれ異なる処理結果であり、サービス品質の段階やプロトコル名ではありません。Shadowsocks、VMess、VLESS、Trojan、Hysteria2、WireGuardは接続方式を表します。いずれかのプロトコルを使っても、ルール内のPROXYに追加の優先度が生じるわけではありません。設定を管理するときは、条件、ポリシー、接続先を分けて確認し、ルールの誤りをプロトコル変更で覆い隠さないようにしましょう。

PROXY、DIRECT、REJECT

PROXYは、リクエストを現在選択されているプロキシに対応する経路へ渡します。接続が成立するかどうかは、ご自身が利用するサーバー情報、認証パラメーター、サーバーの稼働状況にも左右されます。DIRECTは接続先へ直接接続する指定ですが、システムのネットワーク制限をすべて回避する意味ではなく、DNSの動作がクライアントをオフにした場合と必ず同じになるわけでもありません。REJECTはマッチしたリクエストを拒否します。明確にブロックしたい対象に使いますが、必要なホストを拒否すると、アプリの読み込み失敗、再試行の繰り返し、一部コンテンツの欠落につながることがあります。

Global RoutingのConfig、Proxy、Directは全体の動作モードです。一方、ルール行に記述するPROXY、DIRECT、REJECTは設定内のポリシーです。大文字・小文字と意味を区別して読みましょう。特定のRuleが機能しているか確かめるには、まずConfigを選択します。Proxyに切り替えるとリクエストが通る場合、設定による振り分けや直接接続の経路に問題がある可能性は示せますが、特定の行の構文エラーを直接証明するものではありません。比較テストが終わったら、元のモードに戻してください。

USER-AGENTは取得可能なリクエストヘッダーに依存

USER-AGENTルールがマッチするのは取得できるUser-Agentの内容であり、アプリのアイコン、アプリ名、システムのプロセス名ではありません。アプリごとに異なるヘッダーを使うことがあり、アップデート後に内容が変わる場合もあります。同じヘッダーが複数のプログラムで使われることもあります。そのため、特定の文字列をアプリの恒久的な識別子とみなすのは確実ではありません。実際のリクエストヘッダーを確認し、該当するリクエストでクライアントが読み取れると確かめた場合に限り、この種のルールを使用してください。

[Rule]
USER-AGENT,ExampleClient*,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
FINAL,PROXY

ここでのExampleClientは説明用の文字列であり、実在するアプリを指すものではありません。アスタリスクはワイルドカードの範囲を表します。リクエストヘッダーを確認できない場合、このルールは想定どおりに判定できません。暗号化された接続のHTTPヘッダーは、通常の転送だけでは読み取れません。ブラウザーの開発者ツールでUser-Agentを確認できたからといって、クライアントのルール判定時にも必ず取得できるとは限りません。USER-AGENTルールを試すためだけに、証明書の信頼範囲を広げたり、不要な通信の復号を有効にしたりしないでください。

ポリシーが正しくても接続に失敗することがある

リクエスト記録にPROXYと表示されても、ルーティング先が選択されたことを確認できるだけで、リモート側で認証や名前解決が完了し、接続先に到達したことまでは示しません。次に、サーバーアドレス、ポート、認証方式、トランスポート設定が、ご自身のサービス情報と一致するか確認してください。DIRECTと表示された場合も、直接接続の経路が選ばれたことを示すだけです。ローカルネットワークから接続先へ到達できない場合、ルール名を変えてもネットワークの問題は解決しません。REJECTと表示された場合は、サーバーをテストする前に、どのルールが拒否したのか確認しましょう。

ページの一部しか読み込めない場合は、失敗したリソースと成功したリソースを分けて確認します。1つのアプリ内でも、DIRECT、PROXY、REJECTで処理されるリクエストが混在することがあります。「アプリが開く」だけではすべての動作を確認したことにならず、「アプリが開かない」だけでも1つのルールが原因だとは判断できません。実際のホスト、マッチしたルール、ポリシーを一つずつ照合し、変更が必要なのは条件の範囲、並び順、接続パラメーターのどれかを特定してください。

日常の管理では、安定したネットワーク範囲を表すためにドメイン条件やアドレス条件を優先し、USER-AGENTは明確に検証できる限られた用途にとどめてください。リクエスト内部の情報に依存するルールほど、アプリやプラットフォームをまたいで再利用する際に再検証が必要です。既存設定に見慣れないカスタムポリシー名がある場合は、まず定義と参照箇所を確認します。名前をPROXYに変更すれば同じ動作になると決めつけたり、任意の名前がクライアントに標準搭載されていると考えたりしないでください。

Ruleでは上から順に確認し、最初にマッチしたルールのポリシーを適用します。クライアントがすべてのマッチ結果を集めてから、最も具体的に見えるルールを選ぶわけではありません。完全なドメイン名、ドメインサフィックス、キーワード、アドレス範囲の間に、行順序に代わる固定の優先順位はありません。「ルールを書いたのに効かない」ときは、同じ条件を追加するのではなく、まず上にあるルールがそのリクエストをすでに処理していないか確認してください。

明確な例外は、範囲の広い条件より前に置く

example.comとそのサブドメインをPROXYにし、api.example.comだけDIRECTにする場合は、個別の例外を先に書き、その後にサフィックスの範囲を指定します。逆の順序ではapi.example.comがサフィックスルールに先にマッチし、後続のDOMAINで結果を変更できません。この原則はREJECTにも当てはまります。広い拒否ルールより前に、必要な例外を置き、予定より多くのホストを対象にしていないか確認してください。

[Rule]
DOMAIN,api.example.com,DIRECT
DOMAIN,blocked.example.com,REJECT
DOMAIN-SUFFIX,example.com,PROXY
IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
GEOIP,CN,DIRECT
FINAL,PROXY

行ごとに判定すると、api.example.comは1行目で処理が終わります。blocked.example.comは2行目で拒否され、ほかのexample.comのサブドメインは3行目でPROXYになります。プライベートアドレス宛てで、それ以前にドメインルールにマッチしていない場合は、4行目でDIRECTが選ばれることがあります。残りのリクエストはGEOIPを確認し、そこにもマッチしなければFINALに進みます。判定を追う際は、マッチさせたい行だけを見るのではなく、実際のリクエスト条件を使ってください。

FINALは最終フォールバックであり、修正用のパッチではない

FINAL,PROXYには追加のマッチ条件がなく、それ以前のルールにマッチしなかったリクエストを処理します。そのため、Ruleの末尾に配置してください。FINALを途中に置くと、その時点で残りすべてのリクエストを処理してしまい、後続の通常ルールは機能しなくなります。FINALのポリシーは利用者が選ぶ必要があります。PROXYとDIRECTでは既定の接続経路が異なるため、他の人の設定の最終行を見ただけで自分のネットワークに適していると判断しないでください。

管理しやすいRuleでは、明確なFINALを1つだけにするのがおすすめです。2つのルールセットを結合するとき、最初の設定をFINALごと2つ目の前に貼り付け、2つ目のルールの大半がマッチしなくなることがあります。結合後はすべてのFINALを探し、末尾のフォールバックを1つに整理してから、重複ルールや範囲の競合を確認してください。ファイルの長さやルール数だけで、正しく結合できたか判断しないでください。

重複ルール、競合するルール、見た目だけ整った並び順

同じ条件が重複している場合、通常は先にあるルールで結果が決まります。後ろのルールで別のポリシーを指定しても、「予備のポリシー」にはなりません。たとえば同じDOMAINをDIRECT、次にPROXYと続けて書いても、DIRECTで接続できなければ自動的にPROXYへ切り替わるわけではありません。振り分け判定は接続失敗後の再試行処理ではありません。ポリシーを変更したい場合は、後ろに期待する結果を追加するのではなく、最初にマッチするルールを修正してください。

アルファベット順にルールを並べ替えると、意味が変わることがあります。見やすい順に整理した結果、広い条件より前にあった例外が後ろへ移動する場合があります。ルール種別ごとのグループ分けにも同じ注意が必要です。一般的には、明確な例外、対象サービスのドメイン範囲、アドレス範囲、地域分類、最後にフォールバックの順にすると確認しやすくなります。ただし、これは見直しやすくするための整理例であり、すべての設定にそのまま適用する固定テンプレートではありません。

推測ではなく、マッチ結果の一覧で確認

変更前に、3〜5個のテスト対象を選びます。必ず直接接続するホスト、必ずプロキシを経由するホスト、拒否するホスト、FINALに到達する想定の対象などを含めます。それぞれについて、マッチするはずの行を書き出し、新しい接続で実際の結果を確認してください。想定と異なる場合は、条件を上から確認する前に、実際のホスト名やアドレスが想定と同じかを確認します。この方法なら、順序の誤りだけでなく、リダイレクト、リソース用ドメインの変更、アドレスファミリーの違いも見つけやすくなります。

外部ルールの参照を含む設定では、参照がどこで評価されるか、現在どのような内容かも確認が必要です。参照名が同じでも内容が変わらないとは限りません。更新によって、以前はFINALに到達していたリクエストが別の範囲にマッチすることがあります。ローカルファイルで直接確認できる行だけを見て終わらないでください。順序の詳しい例はルールの優先順位とFINALの解説をご覧ください。読み終えたら、現在有効な設定で実際の並び順を確認してください。

Generalは設定全体のオプションを扱うもので、ルールを別形式でまとめて記述する場所ではありません。DNSやネットワーク動作、プラットフォーム固有のパラメーターを設定できますが、クライアントの画面やプラットフォームの実装によって違いがあります。別の設定ファイルにある項目をすべてそのままコピーしないでください。認識されないキーと値が、目立ったエラーを起こさなかったとしても、機能している証拠にはなりません。現在のクライアントで対応を確認できる設定を使い、必要性の明確な項目を1つずつ追加してください。

DNSはまず「アドレスは何か」を解決する

DNSはホスト名をアドレスに変換し、ルールはリクエストの処理ポリシーを決定し、その後の接続段階で接続先への到達を試みます。この3つは関連していますが、同じ処理ではありません。DNSで結果を取得できても接続先へ到達できるとは限らず、PROXYにマッチしてもDNSが必ず同じ経路で処理されるとは限りません。問題が起きたら、まず「アドレスを取得できたか」、次に「どのポリシーが選ばれたか」、最後に「接続のどの段階で失敗したか」を確認します。設定全体をすぐに入れ替えるより、原因を特定しやすくなります。

[General]
dns-server = system

[Rule]
DOMAIN-SUFFIX,example.com,PROXY
GEOIP,CN,DIRECT
FINAL,PROXY

dns-server = systemはシステムDNSを使う基本例であり、あらゆるネットワークに適しているという意味ではありません。わかりやすい基準を作るため、システムが提供する名前解決を維持し、ルールが想定どおりに処理されるかだけを確認します。既存設定で別の対応DNS設定を使っている場合は、パラメーターと変更前の結果を記録し、そのうえで一時的に基本設定へ戻すか判断してください。元のGeneralの目的を把握せずに、内容をすべて削除しないでください。

名前解決の結果によってアドレスルールへの入力が変わる

同じドメインでも複数のアドレスを返すことがあり、ネットワーク上の位置やキャッシュの状態によって結果が変わる場合もあります。ドメインルールがホスト名を条件にしている場合、アドレスが変わってもドメイン条件自体は通常変わりません。一方、GEOIPとIP-CIDRはアドレス情報に直接依存するため、結果が変わるとマッチ状況に影響することがあります。テストの前後でアドレスが変わっていた場合、ポリシーの変更を直前に動かしたルールだけの影響と判断しないでください。そのときの接続先アドレスも記録する必要があります。

ブラウザー、アプリ、システム、クライアントがそれぞれキャッシュや接続状態を保持している場合もあります。DNSを変更した直後にページを一度更新しても、新しい名前解決や接続が行われるとは限りません。対象アプリの現在の通信を終了してから新しいリクエストを行い、クライアントの記録に新しい時刻と接続先が表示されるか確認してください。状態を確認せず、すべてのデータを何度も消去するのは避けましょう。キャッシュの場所がわからない場合は、現在の状態を保ってから、影響の小さい範囲で調べてください。

ローカルでの名前解決とサーバー側での名前解決を混同しない

接続方式によってはホスト名をリモート側に渡して処理する場合があり、別の経路では先にローカルでアドレスを取得する場合があります。動作はプロトコル、設定、リクエストの形式によって異なります。PROXYと表示されたからといって、すべての名前解決がサーバー側で行われるとは限りません。ローカルのDNS記録があるからといって、通信がプロキシを経由していないとも限りません。DNSリクエストそのものと、その後の接続先への通信を別々に確認してください。用途の異なる2つのリクエストを、同じ通信として扱わないようにしましょう。

ご自身が利用するサーバー情報のサーバーアドレスが、ドメイン名の場合もあります。その名前を解決できないと、クライアントはプロキシの接続先を確立できないことがあります。その場合、サービス用ドメインのルールが正確でも問題は解決しません。サーバーアドレスの名前解決から始め、次にポートと認証、最後に接続先サイトを確認します。サーバーのホスト名とサービスのホスト名を別々に記録すると、1つの問題に対して誤ったドメインルールを何度も変更するのを避けられます。

バイパス設定とDIRECTは適用される段階が異なる

Generalの一部のネットワーク除外・バイパス設定によって、特定の通信が通常のRule判定を通らないことがあります。一方、DIRECTは通信が振り分け判定に入った後に選ばれるポリシーです。リクエストが想定した記録にまったく現れない場合は、RuleにDIRECTを追加するだけでなく、システム側の通信制御や関連するバイパス設定を確認してください。具体的な項目は、現在のクライアントが対応している設定の説明に従います。この記事では、プラットフォーム固有のオプションを共通の必須項目として扱いません。

Generalを管理するときは、「システムDNSを基準にする」「既存のローカルネットワーク動作を維持する」など、各項目の目的を記録しておきましょう。用途を説明できないパラメーターは、まず元の値を残してコピー上で個別にテストします。設定の項目数を増やすためだけに、長い設定ファイルを見て一つずつ追加する必要はありません。項目が多いことが、より完全な設定を意味するわけではありません。目的を説明でき、検証でき、元に戻せることが、設定を安定して使うための基本です。基本の接続がまだ確立していない場合は、名前解決の動作を変更する前に入門ガイドに戻り、サーバーと接続を確認してください。

HostとURL Rewriteは同じ設定ファイルに記載されることがありますが、対象が異なります。Hostは指定したホスト名のアドレスマッピングを変更します。URL Rewriteは、条件に一致する表示可能なリクエストURLに書き換え動作を適用します。どちらも「ドメイン名を変えれば同じサービスにアクセスできる」という機能ではありません。接続先サーバーが該当するホスト名を受け入れるか、証明書が一致するか、アプリがリダイレクトに従うかは、実際の接続とサービスの動作によって決まります。

Host：固定マッピングには明確な用途が必要

[Host]
example.com = 192.0.2.10
api.example.com = 192.0.2.20

この例では、書式を示すために2つのホスト名をそれぞれ説明用に予約されたアドレスへマッピングしています。実際の接続には使用できません。固定Hostは、ご自身で管理するテスト環境などで使われます。アドレスの用途を確認せず、「高速化」のためにネット上で見つけたアドレスを安易に設定しないでください。ドメインが複数のバックエンドで提供されている場合、1つのアドレスに固定すると元の振り分けを回避したり、アドレス変更後も無効な接続先を参照し続けたりすることがあります。

Hostのマッピングは通常、リクエスト内のホスト名をアドレス文字列に置き換えません。リクエストには元のホスト名が使われることがあり、TLS証明書もそのドメインと一致する必要があります。ドメインを任意のサーバーにマッピングしても、そのサーバーが元のサービスを提供するようにはなりません。証明書が一致しない場合は、まずアドレスとサービスの構成を確認してください。マッピングの誤りを隠すために、証明書検証を無効にしないでください。

HostはRuleの経路選択を代替しない

ドメインに静的マッピングが設定されていても、自動的にDIRECTになるわけではありません。リクエストのポリシーは、現在のモード、利用可能なホスト名、アドレスルールを組み合わせて判定されます。自分で管理するテスト用ホストを特定のアドレスに固定し、直接接続したい場合は、目的を分けて指定してください。Hostがアドレスを設定し、RuleがDIRECTを指定します。マッピングとポリシーを別々に記述しておけば、テスト後に個別に解除でき、見落としやすい静的アドレスが残るのを防げます。

URL Rewrite：正規表現を理解してからアクションを選ぶ

[URL Rewrite]
^http://example\.com/old$ http://example.com/new 302

この例では、表示可能なプレーンHTTPのURLを完全一致で指定し、302で古いパスから新しいパスへリダイレクトします。正規表現内のドットは、エスケープしないと任意の1文字として解釈されます。先頭のキャレットと末尾のドル記号は、URL全体にマッチする範囲を制限します。この式が対象にするのは例にある古いパスだけで、クエリパラメーターや別の末尾を含むURLには自動的に適用されません。条件を広くするほど、書き換えるべきでないリクエストまで対象にしやすくなります。

302はリダイレクトを表すもので、接続先サーバー上のファイルを直接変更したり、データを恒久的に移行したりするものではありません。クライアントがリダイレクトを受け取ると後続のリクエストが発生し、そのリクエストは改めて振り分け判定を受けます。キャッシュ、アプリがリダイレクトに従うかどうか、接続先サービスの状態にも左右されます。アプリがリダイレクトを無視したり、特定のレスポンスしか受け付けなかったりする場合、ブラウザーで成功してもアプリ内のリクエストが成功するとは限りません。

HTTPSでは適用範囲の確認が必要

HTTPSではパスやHTTPヘッダーは通常暗号化されているため、通常のプロキシ転送だけでは完全なURLを直接確認できません。そのため、上記のHTTP例をHTTPSに置き換えれば必ず動作するとは限りません。暗号化通信の処理には追加の設定と信頼範囲が関係しますが、このページでは基本的な振り分けの前提とはしていません。通常のルール問題を直すためだけに、証明書の信頼範囲を広げることもおすすめしません。ドメインによる振り分けだけが必要な場合は、まずドメインルールを使用してください。

書き換えがループすることもあります。たとえば、新しいURLが別の式で古いURLに戻されたり、範囲の広い式が置換後のURLにも再度マッチしたりする場合です。テストではURLの変化と連続するレスポンスを確認し、リダイレクトが1回で終わるか確かめてください。同じ対象に作用する複数の書き換え設定を同時に有効にするのは避けましょう。各ルールの用途を説明できない場合は、コピー上で1つだけ残して動作を確認し、その後1つずつ戻してください。

解除時は3つの状態をあわせて確認

Hostを削除しても、既存の名前解決キャッシュや接続に古いアドレスが一時的に残ることがあります。URL Rewriteを削除した後も、アプリにリダイレクト結果が残る場合があります。完全に元に戻すには、設定を復元し、新しいリクエストを発生させて、実際のアドレスとパスを確認してください。問題が続いても、すぐにルールを追加し直さず、古い接続を見ているのか、新しい動作なのかを判断しましょう。本番環境に適用する前に、ご自身で管理するテスト用ホストで検証することをおすすめします。

各章の内容を組み合わせる目的は、ルール数の多いファイルを作ることではありません。重要なリクエストをどのように処理するか説明できる設定を目指します。まず必要な例外を明確にし、次に既定の処理ポリシーを決めます。DNSとHostは具体的な必要性がある場合にだけ変更し、URL Rewriteは独立して検証してください。作業前に、利用者ご自身のサブスクリプションに含まれるサーバーが少なくとも1つ正常に使えることを確認します。サーバーの問題と振り分けの問題が重なるのを防げます。

行ごとに確認しやすい設定例

[General]
dns-server = system

[Rule]
DOMAIN,api.example.com,DIRECT
DOMAIN,blocked.example.com,REJECT
DOMAIN-SUFFIX,example.com,PROXY
IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
IP-CIDR6,fc00::/7,DIRECT,no-resolve
GEOIP,CN,DIRECT
FINAL,PROXY

この例は、個別の例外、拒否対象、サフィックスの範囲、ローカルアドレス、地域分類、最後のフォールバックの構成を示します。プロキシの接続先は含まれておらず、サブスクリプションの代わりに使える接続情報でもありません。実際に適用する前に、それぞれの条件を自分の接続先に照らして確認してください。必要のない例示ルールは残す必要はありません。特にREJECTは、対象を実際に拒否する必要があると確認した場合にのみ正式な設定に追加してください。

まずファイルを確認し、次にモードを確認

1. Configで現在選択されているファイルを確認し、変更したルールがそのファイルに実際にあるか、解析エラーがないかを確認します。
2. Global RoutingをConfigに設定し、現在選択中のサーバーを記録します。1回のルールテスト中にサーバーを切り替えないでください。
3. 対象アプリの古い接続を終了してから新しいリクエストを行い、実際のホスト、接続先アドレス、マッチ条件、処理ポリシーを記録します。
4. 実際にマッチしたルールと想定した行番号を比較します。一致しない場合は上にある条件を先に確認し、一致している場合は接続、名前解決、接続先サービスを調べます。

すべての対象が同じポリシーになる場合は、まず全体モードとFINALの位置を確認してください。特定のホストだけで問題が起きる場合は、完全なドメイン名、リダイレクト後のホスト、アドレスの変化を確認します。プロキシ経由の通信全体が失敗する場合は、現在のサーバー情報とネットワーク状態から確認してください。問題の範囲ごとに確認箇所は異なります。何でもDOMAIN-SUFFIXを追加して解決しようとしないでください。

現象に応じて次の確認項目を選ぶ

Connectivity Testは接続先が応答するかを判断する補助にはなりますが、ウェブサイトへの一連のリクエストを完全に検証するものではありません。テストに成功しても、ドメインの名前解決、ルール、認証の詳細、接続先の制限によって実際のリクエストは失敗することがあります。逆に、あるテスト方法で想定どおりの結果が出なかったからといって、すべての通信が使えないとは限りません。テスト対象、テスト方法、実際のサービスでの現象を分けて記録してください。

設定の切り戻し、更新、複数デバイスでの利用

変更後は、想定どおりにマッチする対象と、影響を受けないはずの対象を少なくとも1つずつ確認してください。問題が再発した場合は、まず正常だった設定に戻し、変更によって問題が発生したことを確認してから、項目を1つずつ戻します。リモート設定の更新後も同じように確認し、追加された広範囲のルール、FINALの位置、DNSパラメーターに注意してください。ファイル名が変わっていないからといって、動作も同じとは限りません。

複数のデバイスで設定を使う場合は、まずルールの目的を引き継ぎ、各フィールドへの対応状況とネットワーク環境を確認してください。モバイル回線、家庭内LAN、デスクトップ環境では、アドレス範囲が異なることがあり、システムの通信制御機能にも違いがあります。同じテキストでも、すべてのデバイスで同じ記録になるとは限りません。設定を参考にする場合も、プラットフォーム固有の項目は改めて検証してください。各プラットフォームの入手先はダウンロードページ、基本の接続手順は入門ガイド、よくある現象はよくある質問をご覧ください。

問題の説明には必要な情報を残す

再現可能な記録には、現在のモード、選択中の設定、個人情報を伏せた関連ルール、実際のホスト名またはアドレス、想定と実際のポリシー、変更前後の差分を含めます。サブスクリプションURL、認証情報、個人情報を含むログは送らないでください。設定を見せる必要がある場合は、関連箇所だけを切り出して認証情報を削除します。リクエストの処理を行ごとに確認できる情報があれば、順序、パラメーター、接続のどこに問題があるか判断しやすくなります。

最後の確認は3つの質問に整理できます。リクエストがどの設定ファイルを使ったか、最初にどの条件へマッチしたか、マッチ後の接続がどこで失敗したか。最初の2つは設定の確認、最後の1つはネットワークと接続先の検証です。この順序で根拠を記録すれば、あらゆる問題を「ルールが効かない」と決めつけずに済み、次回の作業も設定ファイル全体を入れ替えるのではなく、確認済みの結論から再開できます。