CONFIG REFERENCE / config.json

V2Ray設定ファイルリファレンス

JSON構造、inboundsとoutbounds、ルーティング条件、DNS名前解決、接続ポリシー。

初回インストール、サブスクリプションの追加、システムプロキシの設定は、使い方ガイドの手順に沿って進めてください。このページでは項目ごとに設定を確認し、設定間の依存関係、例の適用範囲、変更後の検証方法を解説します。クライアントを先にインストールする場合は、クライアント配布ページへ。デスクトップではv2rayNをおすすめします。

Xray / V2Fly JSONの項目 クライアントとコアの役割

01 / STRUCTURE

JSON構造と設定の役割

クライアント設定とコア設定を分けて考える

V2Ray関連のGUIクライアントとプロキシコアは、それぞれ異なる役割を担います。v2rayN、v2rayNG、v2flyNGはサーバー管理、サブスクリプション更新、画面上の設定、起動制御を行います。コアはポートの待ち受け、接続の確立、ルーティング判定、データ処理を担当します。画面上のスイッチ一つで複数のJSON項目が生成されることもあれば、コア設定には反映されずシステムプロキシだけが変更されることもあります。トラブル時は、クライアント、OS、コアのどこで問題が起きているかを切り分け、画面の表示だけで動作を判断しないでください。

クライアントは通常、選択中のサーバーや全般設定をもとに実行用の設定を生成します。このファイルは作業用または一時フォルダーに置かれ、再起動時に再生成されることもあります。生成後のファイルを直接編集しても、変更が維持されるとは限りません。継続して有効にしたい場合は、クライアントが用意するルーティング、DNS、カスタム設定の入力欄を使ってください。入力欄の名称はクライアントの画面によって異なります。ディスク上のconfig.jsonという名前のファイルではなく、保存後に実際に使われる設定を確認しましょう。

トップレベルのオブジェクトと参照関係

基本設定は一つのオブジェクトをルートとします。inboundsとoutboundsは複数の入口・出口を定義できる配列で、routing、dns、policyはオブジェクトです。inboundsがアプリの接続をコアに渡し、routingが接続先のoutboundを選びます。outboundは直接接続するか、リモートサーバー経由で転送するかを決めます。DNSは名前解決が必要な箇所に結果を提供し、policyは特定のユーザーレベルのタイムアウトや統計動作を制御します。それぞれが独立した機能の一覧というわけではありません。

以下は、ローカルでの接続確認に使える基本設定の例です。アプリはSOCKS経由で接続し、コアは直接接続します。リモートプロキシサーバーは含みません。待ち受けアドレスやポート、アプリ側のプロキシ設定を確認する用途に適しており、リモートプロトコルの検証には使えません。実行前にポートが空いていることを確認し、使用するコアが対応する方法で読み込んでください。GUIクライアントでは、サーバーアドレス欄にJSON全体を貼り付けず、カスタム設定機能を使います。

{
  "log": {
    "loglevel": "warning"
  },
  "inbounds": [
    {
      "tag": "local-socks",
      "listen": "127.0.0.1",
      "port": 10808,
      "protocol": "socks",
      "settings": {
        "auth": "noauth",
        "udp": true
      }
    }
  ],
  "outbounds": [
    {
      "tag": "direct",
      "protocol": "freedom",
      "settings": {}
    }
  ],
  "routing": {
    "domainStrategy": "AsIs",
    "rules": []
  }
}

構文が正しくても設定が正しいとは限らない

厳密なJSONでは、キー名と文字列をダブルクォートで囲みます。真偽値はtrueまたはfalseとし、配列の最後の要素の後ろにカンマは付けません。ポートは通常数値で指定し、見た目をそろえるためにすべて文字列にする必要はありません。コメントや拡張構文を許容する設定ローダーもありますが、別のクライアントにコピーした場合は互換性が保たれないことがあります。このページの例はコメントなしのJSONとし、説明文はコードブロックの外に記載しています。

tagは設定内で参照する名前であり、プロトコル名でも、画面に表示されるサーバー名と一致させる必要がある名称でもありません。ルーティングのoutboundTagは実際のoutboundに対応させます。綴り、大文字・小文字、ハイフンも一致させてください。複雑な設定を作る際は、先にタグの対応関係を整理してからプロトコル項目を追加します。同じオブジェクト内で同名キーを重複定義しないでください。パーサーによって重複キーの扱いは異なるため、上書き手段として使うことはできません。

接続の流れに沿って読み進めると整理しやすくなります。まず入口が何を受け取るかを確認し、次に出口で接続を確立できるかを確認してから、ルーティングとDNSを設定します。最初からすべての項目を追加せず、基本の接続経路が安定した後に、オブジェクトまたはルールを一つずつ追加してください。変更前後の想定と結果を記録すれば、元に戻しやすくなり、構文エラー、参照ミス、ネットワーク障害を同じテストで混同せずに済みます。

02 / INBOUNDS

inbounds：ローカルの待ち受け

待ち受けアドレスで接続範囲が決まる

inboundsは、コアが接続を受け付ける入口を定義します。デスクトップクライアントではSOCKSやHTTPプロキシが一般的です。アプリは、指定されたアドレスとポートに対応するプロトコルで接続する必要があります。listenに127.0.0.1を指定すると、このIPv4ループバックアドレスを使って同じ端末からのみ接続できます。これはサーバーアドレスでも、リモートノードの出口アドレスでもありません。ローカルアプリだけが使う場合は、ループバックで待ち受けるほうが接続範囲を制御しやすくなります。

待ち受けアドレスを0.0.0.0にすると、すべてのローカルIPv4インターフェースで待ち受けます。システムのファイアウォールルールがすべて有効になるわけではなく、ネットワーク上の他の端末から必ず接続できるという意味でもありません。LANから接続する必要がある場合は、端末のアドレス、ファイアウォールの受信ルール、ネットワーク分離、認証設定も確認してください。ループバックアドレスはアクセスを開始する端末自身を指します。スマートフォンからPCのプロキシを使う場合、スマートフォン側のループバックアドレスではなく、PCのLAN内アドレスを指定します。

SOCKSとHTTPの使い分け

以下の例は、基本設定のinbounds配列と置き換えて使います。二つの入口はポートとタグを分け、outboundとroutingは既存の設定を引き継ぎます。SOCKS入口ではUDPを有効にしていますが、アプリ側も対応する方法でUDPプロキシを利用する必要があります。HTTP入口はHTTPプロキシの設定だけが可能なアプリ向けです。入口を二つ用意しても、同じアプリが自動的に切り替えて使うわけではありません。

[
  {
    "tag": "local-socks",
    "listen": "127.0.0.1",
    "port": 10808,
    "protocol": "socks",
    "settings": {
      "auth": "noauth",
      "udp": true
    },
    "sniffing": {
      "enabled": true,
      "destOverride": ["http", "tls"]
    }
  },
  {
    "tag": "local-http",
    "listen": "127.0.0.1",
    "port": 10809,
    "protocol": "http",
    "settings": {}
  }
]
項目役割確認ポイント
listenローカルの待ち受けアドレスループバックかLAN接続か
port待ち受けポートポートの使用状況と接続元の設定
protocol入口のプロトコルSOCKSとHTTPを混同しない
tag入口のタグルーティング条件から参照
sniffingプロトコルと宛先情報の検出ドメイン判定が必要か

sniffingはDNSの代わりではない

sniffingは、HTTPのホスト名やTLSハンドシェイクのサーバー名など、一部の接続データからドメインの手掛かりを取得します。すべての接続で元のドメインを復元できるわけではなく、アプリの通信内容を復号する機能でもありません。有効にした後の宛先処理は、コアが対応する具体的な項目にも左右されます。「sniffingを有効にすれば、すべてのドメインルールに一致する」とは限りません。接続先がすでにIPアドレスになっている場合は、まずアプリ側の名前解決方法を確認してください。

destOverrideは、宛先の上書きに使用できるプロトコル種別を指定します。宛先の上書きと、ルーティング判定だけに使う処理は同じではありません。この動作を制御する追加項目を提供するコアもありますが、拡張項目をすべてのコアにそのまま適用できるわけではありません。元の宛先アドレスが必要なサービスや、同じIP上で特殊な接続処理を行う場合は、sniffingの変更後に個別に検証してください。必要性が明確でなければ、検出対象を最小限にし、目的のない設定項目を増やさないようにします。

ポート、システムプロキシ、通信の取り込み方法

ポート使用中のエラーは待ち受け開始時に発生し、リモートサーバーの稼働状況とは関係ありません。重複起動しているクライアントを終了し、実行中のプロセスが使っているポートを確認してから、変更するか判断します。inboundsのポートを変えた場合は、ブラウザー、開発ツール、システムプロキシに設定されたポートも合わせて変更してください。コアだけを変更し、システムプロキシに古いアドレスが残っていると、アプリの接続が拒否されます。この場合、サブスクリプションを何度更新しても解決しません。

システムプロキシは、OSの設定に従うアプリにプロキシ入口を使うよう伝える機能であり、すべてのアプリの通信がコアを通るとは限りません。TUN方式の取り込みには仮想インターフェース、システムルート、権限も関わるため、SOCKS inboundsを追加するだけでは代用できません。Androidクライアントのシステム通信の取り込みも、クライアントとプラットフォームの仕組みが連携して行います。通信がコアに入っているかどうかは、画面上のシステムプロキシスイッチだけでなく、実際の接続ログで確認してください。

入口を検証するときは、テストアプリとアクセス可能な既知の宛先を一つずつ決めます。まず接続が記録されるかを確認し、その後、想定したoutboundが選ばれているかを見ます。接続記録がない場合は、アプリがプロキシを使っているか、アドレスとプロトコルが正しいか、古い設定が残っていないかを確認します。記録がある場合は、outboundとroutingの確認に進みます。初回設定の手順はv2rayNの初期設定ガイドも参照してください。

03 / OUTBOUNDS

outbounds：プロトコルとタグ

outboundが次の接続先を決める

outboundsは、コアが受け取った接続をどう処理するかを決めます。freedomは宛先へ直接接続し、blackholeは接続を遮断します。VLESSなどのプロキシプロトコルは、設定されたリモートサーバーへ接続を転送します。outboundは個々のルーティングルールではありません。同じoutboundを複数のルールから参照でき、一つのルールで複数のドメインを判定して同じ出口を選ぶこともできます。プロトコルの設定と通信の分類を分けて管理できます。

ルーティングルールに一致しない場合、一般的な設定ではoutbounds配列の先頭がデフォルトの出口になります。そのため、配列の順序には意味があります。directを先頭に置くことは、表示順の変更にとどまらず、ルールに一致しないすべての通信の処理を変える可能性があります。設定を作る際は、まずデフォルトの動作を決めてから例外ルールを追加してください。デフォルトでプロキシを使う場合は、利用可能なプロキシoutboundを先頭に置きます。デフォルトで直接接続する場合は、directを先頭に残します。

直接接続と遮断は個別に確認できる

以下の配列は、直接接続と遮断の動作確認に使えます。基本設定のoutboundsと置き換えてください。二つのタグはroutingから参照でき、デフォルトは引き続き先頭のdirectです。blackholeは接続を意図的に破棄するoutboundであり、予備回線ではなく、利用可能なサーバーを自動検索するものでもありません。テスト用ドメインに適用した場合、アプリの接続が失敗するのは想定どおりです。クライアント全体の障害と判断せず、ルーティングログでルールに一致したことを確認してください。

[
  {
    "tag": "direct",
    "protocol": "freedom",
    "settings": {}
  },
  {
    "tag": "block",
    "protocol": "blackhole",
    "settings": {}
  }
]

VLESSの項目はサーバー設定と一致させる

以下はVLESS outboundオブジェクトの構造例であり、そのまま接続できる公開サーバーではありません。your-server.exampleは説明用ドメインで、例示のUUIDも書式を示すためのものです。使用時は正規に利用できるサーバー情報へ置き換えてください。このオブジェクトはTCPとTLSの設定を含み、接続先サーバーも同じ組み合わせに対応している必要があります。配列に追加しても、既存の別プロトコルのサーバーが自動的にVLESS接続を受け入れるわけではありません。

{
  "tag": "proxy",
  "protocol": "vless",
  "settings": {
    "vnext": [
      {
        "address": "your-server.example",
        "port": 443,
        "users": [
          {
            "id": "00000000-0000-4000-8000-000000000001",
            "encryption": "none",
            "level": 0
          }
        ]
      }
    ]
  },
  "streamSettings": {
    "network": "tcp",
    "security": "tls",
    "tlsSettings": {
      "serverName": "your-server.example",
      "allowInsecure": false
    }
  }
}

addressは接続先サーバーのアドレス、portはサーバーの待ち受けポート、idはプロトコル上のユーザー識別子です。VLESSユーザーオブジェクトのencryptionはトランスポートのセキュリティ層とは別の設定です。noneと指定しても、外側のTLSが無効になるわけではありません。トランスポートのセキュリティはstreamSettings.securityなどの項目で設定します。名前の似た「暗号化」関連の項目をひとまとめに考えると、設定をインポートできても接続できない原因になります。

ユーザーオブジェクトのlevelはpolicy.levelsと関連付けられますが、ノードの優先順位やルーティングルールの順序を制御するものではありません。flowなどの拡張項目は、サーバー、コア、トランスポートの組み合わせがすべて対応している場合にのみ使用します。インポートしたリンクに値が含まれていたからといって、すべてのサーバーに同じ値を設定しないでください。インポート後はアドレス、ポート、ユーザー識別子、トランスポート、セキュリティ層を確認し、クライアントが未知の項目を警告していないかも確認します。

プロトコルとクライアントは分けて選ぶ

クライアント名だけでは対応プロトコルはわかりません。デスクトップではv2rayN、Androidでは実際に必要なコアに応じてv2rayNGまたはv2flyNGを選んでください。拡張機能を使えるかどうかは、クライアントの表示名にプロトコル名があるかではなく、使用中のコアと設定の組み合わせで決まります。選び方は3つのクライアントのコアの違いを参照してください。インストール先はダウンロードページにまとめています。

outboundの障害は、サーバーに到達できない、プロトコル認証に失敗する、トランスポートのハンドシェイクに失敗する、の3つに分けて考えます。アドレスやポートの誤りは通常、基礎接続の確立時に発生します。ユーザー識別子の不一致はプロトコル処理段階、TLS名の誤りはセキュリティ層の問題です。まずログから失敗段階を判断し、該当する項目を確認してください。アドレス、ユーザー識別子、トランスポートを一度にすべて変更すると、接続が回復しても原因を特定できず、後の保守も難しくなります。

04 / STREAM SETTINGS

トランスポート方式とTLSセキュリティ層

プロトコル、トランスポート、セキュリティ層を分けて考える

プロキシプロトコルはプロキシ要求の形式を定め、トランスポート方式はデータを運ぶ経路を定めます。セキュリティ層はハンドシェイク、認証、暗号化接続を処理します。これらは通常、一つのoutboundオブジェクトに設定されますが、自由に組み合わせられるとは限りません。同じVLESSでも、サーバーごとに必要なトランスポートやセキュリティ層が異なる場合があります。別のサーバーのトランスポート設定を流用すると、プロトコル認証に進む前に接続が失敗することがあります。

streamSettings.networkでトランスポートの種類を選び、対応する設定オブジェクトで具体的な項目を指定します。TCPは比較的シンプルですが、WebSocketでは通常パスが必要で、HTTPホスト名を指定する場合もあります。リバースプロキシ経由のサーバーでは、公開ポートとパスはサーバー側の構成で決まります。クライアントに入力する各値は、サーバー側の設定に基づいて決めてください。よく使われるパスを手当たり次第に試しても、正しい値の確認にはなりません。

WebSocketの設定項目の階層

以下は、一般的なWebSocketとTLSの組み合わせを示す例です。トップレベル設定ではなく、outbound内のstreamSettings全体と置き換えてください。ドメインとパスは説明用です。addressは引き続きプロトコルのサーバーオブジェクト内にあり、実際の接続先を指定します。ここにあるホスト名、サーバー名、パスは上位層のハンドシェイクに使われます。実際の環境で異なる値が必要な場合は、一つずつ指定してください。3つが常に同じとは限りません。

{
  "network": "ws",
  "security": "tls",
  "tlsSettings": {
    "serverName": "your-server.example",
    "allowInsecure": false
  },
  "wsSettings": {
    "path": "/proxy",
    "headers": {
      "Host": "your-server.example"
    }
  }
}
項目設定階層役割
addressプロトコルのサーバーオブジェクト基礎接続の接続先を指定
serverNameTLS設定サーバー名と証明書名の検証
HostWebSocketのリクエストヘッダーHTTPバーチャルホストの選択
pathWebSocket設定サーバー側のリクエストパスに合わせる
securityトランスポート設定トランスポートのセキュリティ層を選択

証明書エラーでは名前と有効期間を確認

TLS接続では、証明書の適用対象名と有効期間が検証されます。システム時刻の大幅なずれ、サーバー名と証明書の不一致、証明書チェーンの設定漏れなどは、ハンドシェイク失敗の原因になります。証明書がドメイン名に対して発行されている場合、IPアドレスで接続しても、サーバーの指定に従って正しいサーバー名を設定する必要があります。サーバーアドレス、HTTPホスト名、証明書名は同じ値になることもありますが、役割は異なります。相互に置き換えられる項目ではありません。

allowInsecureは証明書検証の一部を省略するかどうかを制御する項目であり、証明書の設定不備を修正するものではありません。このページの例ではfalseにしています。証明書エラーが発生したら、まずシステム時刻を合わせ、サーバー名、証明書の対象範囲、サーバー側の証明書チェーンを確認してください。検証を長期間無効にすると、接続相手の認証条件が変わり、サーバー名の設定ミスも見つけにくくなります。トラブル対処の手順はTLSハンドシェイクと証明書エラーの解説を参照してください。

拡張項目と接続の多重化に関する注意点

REALITYは特定のコアが対応するセキュリティ方式であり、一般的なTLS設定の別名ではありません。サーバー名や公開鍵などの関連項目は、実際のサーバーの要件に合わせてセットで指定する必要があります。securityの文字列だけを変更しても設定できません。同様に、トランスポート名や拡張設定はコアによって異なることがあります。設定を移行する前に、実装と対応範囲を確認してください。未知の項目が表示された場合、警告された項目だけを削除して同じ動作になると思い込まないでください。

Muxは一定の条件で基礎接続を再利用する機能です。通信の振り分け機能ではなく、プロトコル設定を修正するものでもありません。有効にするかどうかは、プロトコル、サーバー側の対応、アプリの接続方式、使用中のコアの制約によって異なります。単一接続の失敗を調べる場合は、まず無効のまま基本接続が安定することを確認し、その後で個別に試してください。Muxとトランスポート自体の多重化機能を混同せず、Mux、DNS、ルーティングを同時に変えて結果を比較しないようにします。

トランスポートのトラブル対処では、同じサーバーとテスト先を使い、基礎接続、TLSハンドシェイク、トランスポートのハンドシェイク、プロキシ要求の順に確認します。接続タイムアウトでは、まずアドレスと到達性を確認します。証明書エラーが返ってきた場合は、サーバー名と証明書を確認します。WebSocketのパスが合わない場合は、リクエストの転送ルールを確認してください。ログは失敗した段階を判断する手掛かりであり、原因の確定にはサーバー側の設定とクライアントが実際に生成した設定との照合が必要です。

05 / ROUTING

routing：ルール判定と出口の選択

ルール数より順序とデフォルトの出口を確認

routing.rulesは設定順に判定され、ルールに一致すると通常は指定された出口が選ばれます。「より精密な」ドメインルールを探すために判定を続けるわけではありません。範囲の広いルールを先に置くと、後ろの細かいルールが一度も適用されないことがあります。ルールを管理するときは、まず明確な例外を記述し、次に広い範囲の分類を置き、最後にデフォルトの出口を明示してください。ルールが多くても適切にカバーできるとは限りません。順序がわかりにくいと、動作の把握も難しくなります。

一つのルール内では、通常、異なる条件項目をすべて満たす必要があります。一方、条件配列に複数の候補値がある場合は、その項目に対していずれかの値が一致すれば対象になります。たとえばinboundTagとdomainを同時に指定すると、指定した入口からの接続で、かつ宛先ドメインが条件に一致する場合に適用されます。どちらか一方を満たせばよいという意味ではありません。独立した例外を二つ表す場合は、複雑な条件を組み立てるより、二つのルールに分けたほうが確認しやすくなります。

domainStrategyとドメイン判定は別の設定

domainStrategyは、ルーティング判定の際にドメインからIPアドレスを取得するタイミングを決めます。AsIsは現在の宛先形式を維持します。IPIfNonMatchはドメインが一致しなかった場合に名前解決を試み、IPルールで判定します。IPOnDemandは判定にIP情報が必要になった時点で名前解決します。すべてのアプリにDNSを強制設定する機能ではなく、アプリですでに解決された元のドメインを復元するものでもありません。入力される宛先の形式も考慮して選んでください。

以下のオブジェクトはトップレベルのroutingと置き換えて使います。outboundsにdirectが定義されている必要があります。プライベートアドレスは条件がわかりやすいよう通常のIPネットワーク表記を使い、ドメイン例外には予約済みのサンプルドメインを使っています。どのルールにも一致しない場合は、引き続き先頭のoutboundが使われます。基本設定にdirectしかない場合、この例だけではプロキシ出口は使われません。別のデフォルト動作にするには、対応する実際に利用可能なoutboundも設定してください。

{
  "domainStrategy": "IPIfNonMatch",
  "rules": [
    {
      "type": "field",
      "ip": [
        "10.0.0.0/8",
        "172.16.0.0/12",
        "192.168.0.0/16"
      ],
      "outboundTag": "direct"
    },
    {
      "type": "field",
      "domain": [
        "full:example.com",
        "domain:example.org"
      ],
      "outboundTag": "direct"
    }
  ]
}

プレフィックスでマッチ範囲を指定

full:example.comはドメイン全体との一致に使います。domain:example.orgは該当ドメインとそのサブドメインに使います。regexp:は正規表現を指定しますが、JSON文字列内のバックスラッシュをエスケープする必要があります。プレフィックスのない文字列は、コアが定めるキーワード判定として扱われる場合があります。対象範囲が明確でない場合に、完全なドメイン指定の代わりとして使うのは避けてください。特定のホストを正確に指定するには、意味が明確なプレフィックスを優先し、実際のリクエストに応じてサブドメインを追加します。

geosite:はドメイン分類データを参照し、geoip:はIP分類データを参照します。たとえばgeosite:cnやgeoip:privateがよく使われます。オンライン検索を自動実行する指示ではありません。実行環境に対応するデータファイルがあり、必要な分類が含まれている必要があります。分類名、データの内容、更新状況も判定結果に影響します。分類が見つからない、ルールを読み込めない場合は、対象サイトではなく、データとコアの設定を確認してください。

リクエスト条件からルールをたどる

デバッグでは、入口タグ、宛先がドメインかIPか、ポート、想定する出口を記録し、先頭のルールから順に確認します。ドメインルールに一致しない場合は、コアがドメイン情報を取得できているかを確認します。IPルールに一致しない場合は、名前解決のタイミング、返されたアドレス種別、ネットワーク範囲を確認してください。根拠がないまま範囲の広いルールを追加しないでください。一時的に問題を覆い隠すだけでなく、ほかの接続の出口まで変えてしまうことがあります。

ルールの変更が影響するのは新しい接続の出口選択です。既存の長時間接続は、変更前の経路を使い続けることがあります。テスト前にアプリ内の該当接続を閉じるか、リクエストを再実行し、古い接続をルール未反映と誤認しないようにしてください。構文と優先順位の詳しい例はカスタムルーティングルールの書き方を参照してください。用語は用語集で確認できます。ドメイン分類、アドレス範囲、outboundタグの違いを整理できます。

06 / DNS

dns：名前解決の参照先と問い合わせ経路

最初に名前解決を行う場所を確認

アプリのリクエストでは、複数の場所で名前解決が行われる場合があります。アプリが宛先ドメインを解決し、OSがサーバーアドレスを解決し、コアがルーティング判定用に宛先を解決することもあれば、outboundが接続時に名前解決することもあります。トップレベルのdnsが影響するのは、内蔵リゾルバーを呼び出す箇所です。すべてのアプリのDNS要求を自動的に取り込むわけではありません。ブラウザーなどが独自の暗号化DNSを使う場合は、独自の経路で通信することがあります。コアのDNS設定を変えただけで、その動作も変わったと判断しないでください。

トラブル対処の前に、何が問題なのかを具体的にします。プロキシサーバーのドメインを解決できないのか、接続先サイトのドメインを解決できないのか。名前解決自体に失敗するのか、アドレスは返るものの接続できないのか。OSの名前解決に問題があるのか、ルーティング判定の段階だけで問題が起きているのか。それぞれ確認すべき設定が異なります。サーバードメインの名前解決はプロキシ接続の確立前に必要ですが、接続先ドメインの名前解決はローカルまたはリモートで行われる場合があります。どちらも一括りに「DNSが使えない」と判断しないでください。

hosts、servers、アドレス種別

以下はトップレベルのdnsの構造例です。hostsで説明用ドメインにドキュメント用のアドレスを割り当てています。静的マッピングの形式を示す例であり、接続可能なサービスではありません。二つの数値形式のリゾルバーアドレスは、servers配列の書き方を示しています。実際には現在のネットワークから到達でき、用途に合ったDNSリゾルバーを選んでください。このオブジェクトを設定に加えただけでなく、内蔵リゾルバーを呼び出す動作があって初めて効果を確認できます。

{
  "hosts": {
    "example.test": "192.0.2.10"
  },
  "servers": [
    "1.1.1.1",
    "8.8.8.8"
  ],
  "queryStrategy": "UseIP"
}

hostsは明確で安定した対応付けに適していますが、頻繁に変わるサービスのアドレスを長期間固定する用途には向きません。接続先は複数のアドレスを使ったり、地域ごとに振り分けたり、証明書や接続先を変更したりすることがあります。古いマッピングが通常の名前解決結果を迂回させる場合があります。トラブル対処後は一時的なマッピングを削除し、OSのhostsファイルやクライアントの別のDNS設定が上書きしていないか確認してください。そうしないと、リゾルバーを変更しても古い固定結果が使われ続けることがあります。

queryStrategyは問い合わせるアドレス種別を制御します。一般的な値はUseIP、UseIPv4、UseIPv6ですが、実際に対応している値は使用中のコアによって異なります。OSのIPv6を有効化・無効化するスイッチではありません。ネットワークにIPv6経路がない場合、IPv6アドレスが返ることとIPv6接続が成功することは別です。同様にIPv4だけを問い合わせても、プロキシサーバー自体の接続障害は解決しません。アドレス種別とルーティングが実際に使えることを確認してから、問い合わせ範囲を変更します。

DNS通信にも出口の依存関係がある

コアから送信されるDNS問い合わせの経路は、リゾルバーの種類、コアの実装、関連するルーティング設定によって異なります。通常のリモート問い合わせ、OSの名前解決、ローカルでの処理を前提とする方式が、同じ振り分け経路を通るとは限りません。暗号化DNSでは、リゾルバーのホスト名、TLS名、接続先への到達性も必要になります。問い合わせ形式が暗号化されているとわかっても、最終的にどの出口を通るかまでは判断できません。

循環依存に注意してください。たとえば、プロキシサーバーにドメイン名を使っているのに、その名前解決をまだ確立していない同じプロキシ経由にすると、接続を開始できません。暗号化DNSリゾルバーのドメイン名を、そのリゾルバー自身でしか解決できない設定も同様です。起動時に到達可能な名前解決経路を用意し、必要に応じて明示的なブートストラップDNSや、サーバー側で認められた接続アドレスを使います。DNS関連のアドレスをすべてプロキシ出口に向けて、コアが依存関係を自動解決することを期待しないでください。

症状最初に確認すぐに決めつけない
サーバードメインを名前解決できない起動時の名前解決経路、システムネットワーク接続先サイトのルーティング不良
ドメインは解決できるが接続がタイムアウトする応答アドレス、アドレス種別、出口DNSリゾルバーの障害と決めつけない
変更後も古いアドレスが返るアプリ、OS、コアのキャッシュ新しい設定が保存されていない
一部のアプリだけで問題が起きるアプリ独自の名前解決とプロキシ設定すべての通信が同じDNSを使うとは限らない

キャッシュとルーティングを合わせて確認

DNSキャッシュはアプリ、OS、コア、上流リゾルバーに保存される場合があります。設定変更後にコアを再起動しても、アプリがキャッシュや既存の接続を使い続けることがあります。テストではドメインを一つに固定し、応答アドレスと接続の出口を記録してから、キャッシュ元を個別に確認してください。複数の設定を一度に消去し、複数のリゾルバーを同時に変更すると、変更前後の結果を比較できなくなります。複数アドレスを持つサービスでは、問い合わせごとの結果の違いだけで設定が不安定とは限りません。

ドメインルールとIPルールを併用する場合、DNSはルーティングへの入力元として考えます。ドメインが先にルールに一致すれば、ローカルでの名前解決が不要な場合があります。IP判定に進むと、名前解決の結果によって出口が変わることもあります。そのため、振り分けを設計する際は「いつ名前解決するか」と「解決後にどう判定するか」を合わせて整理してください。特定のドメインの問題だけを修正する場合は、まず個別にテストしてから全体設定に広げるか判断します。

07 / POLICY & LOG

policy：接続ポリシー、ログ、統計

ユーザーレベルはポリシーの参照キー

policyは接続処理や統計に関するポリシーを定義します。levelsはユーザーレベルをキーとして設定し、プロトコルのユーザーオブジェクトにあるlevelから該当するポリシーを参照できます。このレベルはアカウントの権限順位やサーバー性能、ルーティングの優先順位を示すものではありません。該当するプロトコルと接続でそのレベルが使われて初めて、設定した動作が適用されます。参照されていないレベルに項目を追加しても、すべての接続が自動的に変わることはありません。

JSONオブジェクト内のレベルのキーは"0"のような文字列で記述します。一方、プロトコルユーザーのレベル項目は通常、数値です。名前は似ていますが、場所も型も異なります。複数のレベルを管理する場合は、それぞれを使うオブジェクトと変更目的を記録し、意味のわからない数字だけを残さないようにします。一般的なクライアント利用ではpolicyを頻繁に変える必要はありません。出どころのわからない「汎用最適化設定」を適用するより、デフォルトを保つほうがトラブルを切り分けやすくなります。

タイムアウト項目ごとに適用段階が異なる

以下は一般的なpolicy項目の例で、トップレベルのpolicyを設定する際の参考になります。数値の単位は秒で、共通の推奨値を示すものではありません。handshakeは該当するハンドシェイク段階の時間、connIdleはアイドル状態の接続、uplinkOnlyとdownlinkOnlyは一方向だけが動作している段階に関係します。すべてを同じ総接続タイムアウトと考えないでください。実際の適用箇所はプロトコルの実装にも左右されます。

{
  "levels": {
    "0": {
      "handshake": 4,
      "connIdle": 300,
      "uplinkOnly": 2,
      "downlinkOnly": 5,
      "statsUserUplink": false,
      "statsUserDownlink": false
    }
  },
  "system": {
    "statsInboundUplink": false,
    "statsInboundDownlink": false,
    "statsOutboundUplink": false,
    "statsOutboundDownlink": false
  }
}

アイドル時のタイムアウトが短すぎると、対話型ターミナル、通知接続、データのないセッションが頻繁に再接続されることがあります。長すぎると、不要な接続が長く残る場合があります。アプリには独自のハートビート、読み書きタイムアウト、再接続処理もあるため、定期的に切断される場合はアプリの設定とコアのログを合わせて確認してください。切断間隔が特定のpolicy値に近いだけで原因と決めつけないでください。ネットワーク機器やリモートサービスにも個別のタイムアウトがあります。

ハンドシェイクに失敗した場合は、時間を延ばす前にプロトコル、アドレス、セキュリティ層の設定を確認します。パラメーターの不一致は、待ち時間を延ばしても解消しません。ネットワークが実際に遅い環境では時間を延ばすことで改善する場合がありますが、再現可能なテストに基づいて判断してください。変更時は一度に一つの項目だけを変え、ハンドシェイク開始からエラーまでの段階を記録します。トランスポートのハンドシェイクより前に発生する問題に、アプリデータ段階のアイドル設定を変えても効果は期待できません。

ログレベルで記録の詳しさを調整

ログ設定はトップレベルのlogに記述し、policyの中には置きません。通常はwarningを使い、原因を調べる間だけinfoなどの詳しいレベルに変更します。以下のオブジェクトは記録の詳しさだけを設定します。ログの出力先はクライアントやコアの実行方式によって異なります。ディスク上のパスを指定していない場合、特定のフォルダーに保存されているとは限りません。まずクライアントのログ画面や、明示されたログファイルの場所を確認してください。

{
  "loglevel": "warning"
}

接続ログには宛先ドメイン、IP、入口タグ、エラー原因などが含まれることがあります。トラブル情報を公開する前に、サブスクリプションURL、ユーザー識別子、個人用のパスなど、不要な情報を削除してください。診断に必要な情報を残すには、機密性のある名前を一貫したサンプル用タグに置き換え、失敗した段階、項目の種類、タグ同士の参照関係を維持します。「接続失敗」の一行だけでは原因を示すのに不十分な場合が多く、前後の初期化やハンドシェイクの情報も重要です。

統計スイッチを有効にしても統計画面は作られない

policyの統計スイッチは、該当するカウンターを収集するかどうかを示すもので、クライアントにグラフを自動生成する機能ではありません。統計を読み取るには、コアの統計機能、インターフェース、クライアント側の対応なども必要です。ユーザー別の統計には、プロトコル上のユーザー識別情報が必要な場合があります。システム統計を有効にすれば、アプリやサーバーごとのデータを自動取得できると考えないでください。接続失敗の原因を調べるだけなら、通常はログを確認すればよく、統計機能一式を追加で有効にする必要はありません。

ログと統計は状況を把握するためのツールであり、接続成功の前提条件ではありません。policyを誤って変更すると問題が複雑になることがあります。グラフがないからといって、プロキシが動作していないとも限りません。設定後は実際のリクエストを確認し、保守上の必要に応じて記録の詳しさを選んでください。クライアントに統計機能がある場合は、既存の機能を優先し、不要な管理インターフェースを重複して公開しないようにします。詳細ログを使った調査が終わったら、通常のログレベルに戻し、不要になった診断ファイルを削除してください。

08 / APPLY & DIAGNOSE

設定の適用、サブスクリプション管理、段階的なトラブル対処

元に戻せる変更手順を先に用意する

新しい設定を適用する前に、現在動作しているクライアント設定とカスタム設定のコピーを保存し、今回変更する項目と想定する動作を記録してください。バックアップは自分で判別できる場所に置き、クライアントの一時的な実行ファイルと混同しないようにします。設定を戻すときは、サーバーの選択、システムプロキシ、ルーティングモード、DNSも考慮してください。JSONの一部だけを復元しても、クライアント全体の状態が元に戻るとは限りません。一度に変更する範囲が明確なほど、安全にロールバックできます。

実際に使われる設定には複数の層が関係する場合があります。サブスクリプションがサーバー情報を提供し、クライアントの全般設定が入口やルーティングのテンプレートを設定し、カスタム設定が一部の項目を上書きすることもあります。トラブル対処では、通常のサーバー設定と完全なカスタム設定のどちらで起動しているか、最終的な設定をどの入力欄が決めているかを確認してください。起動モードが異なると、同じ画面上のスイッチでも実行結果に反映されないことがあります。使われていないカスタムファイルを編集し続け、コアが設定を読み込んでいないと誤解しないようにします。

サブスクリプションは実行設定全体ではない

サブスクリプションは通常、サーバー情報や共有情報を配布するもので、ローカルの待ち受け、システムプロキシ、ルーティング、DNSの設定すべてを含むとは限りません。更新後にサーバー名、アドレス、オプション項目が変わる場合があり、ローカルのカスタム振り分けが維持されるかはクライアントの実装によります。サブスクリプションURL自体も慎重に扱うべき情報です。公開スクリーンショット、記事、トラブル相談に載せないでください。インポートに成功したことは、内容をクライアントが認識したことを示すだけで、すべてのサーバー設定が利用できる証拠ではありません。

複数デバイスで同期する場合は、共有するサーバー情報とデバイスごとの設定を分けて考えます。PCとスマートフォンで同じ正規のサブスクリプションを使えても、待ち受けポート、システム通信の取り込み方法、ネットワーク権限は同じとは限りません。デスクトップの実行設定全体をモバイルクライアントにそのまま適用しないでください。移行する場合は、まずサーバー情報を同期し、各デバイスで入口、ルーティング、DNSを個別に確認します。手順はサブスクリプション、共有リンク、設定エクスポートを使った同期ガイドを参照してください。

接続段階に沿って失敗箇所を特定

第1段階では設定の読み込みと起動を確認します。JSON解析エラーが出た場合は、エラー付近のクォート、カンマ、括弧を確認します。未対応項目が表示された場合は、使用中のコアと項目の対応範囲を確認します。待ち受けに失敗した場合は、ポートの使用状況と権限を確認してください。これらはすべてプロキシリクエストを送る前の問題なので、ひとまずリモートサーバーの設定を変える必要はありません。修正後はコアが起動したまま動作していることを確認し、プロセスが終了した状態でネットワークテストを続けないようにします。

第2段階ではリクエストがコアに届いているかを確認します。プロキシを使うよう明示的に設定したテストアプリから新しい接続を行い、ログを確認してください。記録がない場合は、アプリのプロキシプロトコル、ループバックアドレスとポートを確認し、システムプロキシが古い入口を参照していないか調べます。記録はあるものの出口が想定と異なる場合は、ルールの順序、入口タグ、宛先の形式を確認してください。実際のリクエスト経路を確かめずにクライアントを再インストールしても、問題の解決にはなりません。

段階よくある症状優先して確認
設定の読み込み起動直後に終了するJSON、項目の対応状況、タグの参照
待ち受け入口ポートのバインドに失敗重複プロセス、アドレス、権限
アプリからの接続リクエストが記録されないアプリのプロキシ設定とシステム通信の取り込み
出口の選択想定と異なるoutboundが選ばれるルールの順序、宛先の形式、デフォルトの出口
リモート接続の確立タイムアウトまたはハンドシェイクエラーサーバーアドレス、プロトコル、トランスポートのセキュリティ
接続先へのアクセス一部のサービスだけで問題が起きるDNS、アドレス種別、宛先ルール、アプリの動作

第3段階ではリモートサーバーと接続先を確認します。サーバーに接続できない場合は、アドレス、ポート、起動時の名前解決を確認します。ハンドシェイクに失敗する場合は、プロトコルユーザー、トランスポートのパス、証明書名を確認します。サーバーには接続できるものの一部の宛先で問題が起きる場合は、宛先のDNS、ルール、アドレス種別を確認してください。局所的なサービス障害と全体設定の問題を区別するため、複数の接続先でテストします。ただし、1回のテストで変更する条件は固定してください。一つの接続に成功しても、すべてのルールが想定どおりとは限りません。

変更後の確認と後片付け

動作確認では、少なくともローカル入口、デフォルトの出口、明示的なdirect例外、遮断する設定がある場合はそのテスト条件を確認します。遮断を設定していない場合は、確認のために追加する必要はありません。各テストでは入力条件と想定する出口を記録し、新しい接続で検証します。長時間接続やキャッシュが古い結果を保持することがあるため、新しいテストセッションを開始してください。設定が保存されたことを確認した後、クライアントを通常の方法で再起動し、実行設定が変更内容と一致しているか確認します。

最後にログレベルを通常の設定に戻し、一時的なhostsマッピングやテストルールを削除して、簡潔な変更記録を残します。初めて使う場合は、クイックスタートガイドに戻ってクライアントの基本操作を進めてください。設定項目の確認には、このページの目次に沿って参照します。設定の保守で大切なのは、スイッチを増やすことではありません。入口、名前解決、ルーティング、出口の関係を説明・検証できる状態に保ち、問題が起きたときに正確に元へ戻せることです。

クライアントをダウンロード