パス単位の固定レスポンス
システム設定 → ゲートウェイ → パス別応答 では、特定のリバースプロキシ用サービス Host に少数のパス単位ルールを追加できます。この項目は、Host ルーティングを使うサブドメインモードでのみ編集できます。これには、グローバル IP から直接公開する サブドメインモード と、トンネル → サブドメインマッピング が含まれます。パスモード、直接接続モード、単一ファイルまたはディレクトリのレスポンスでは利用できません。Host は引き続きメインルートとして機能し、どのパスルールにも一致しないリクエストは、その Host マッピングのデフォルト Target へ送信されます。
ヘルスチェック、固定ステータスの応答、同じ Host にある一部の API だけを別のアップストリームへ転送する用途に適しています。多数のパスで複数のアプリを構成する場合は、互換性のために用意されているパスマッピングを使用し、Host ルーティング上に別のパスゲートウェイを作らないでください。
マッチング順序
api.example.com/healthz -> 固定レスポンス 200 ok
api.example.com/v2/* -> http://127.0.0.1:8080
api.example.com/other-path -> Host のデフォルト Target最初に既存のリバースプロキシ用サービス Host を選択します。認証サービスの Host と静的ファイルまたはディレクトリの Hostは選択肢に表示されません。
パスは / で始める必要がありますが、ルートパス / は設定できません。次のパスは認証、共有、内部機能のために予約されているため、設定できません。
/__で始まるパス/s/s/
各 Host では、一致方法とパスの組み合わせごとにルールを 1 つだけ作成できます。
ルールのフィールド
| フィールド | 値 | 動作 |
|---|---|---|
一致方法 | 完全一致 / 前方一致 | パス全体が一致する場合だけ、または指定したプレフィックスとその配下のパスに一致します |
アクション | リバースプロキシ / 固定レスポンス | 別のアップストリームへ転送するか、ゲートウェイから直接応答します |
認証動作 | Host を継承 / 公開アクセス / ログイン必須 | Host を継承、公開、またはこのパスの認証を必須にします |
転送先 | HTTP / HTTPS URL | リバースプロキシアクションでのみ使用します |
一致したパスを除去 | オン / オフ | /api/users を /users として転送するか、元のパスを維持します |
HTML 内のパスを書き換え | オン / オフ | ページリソースのパスにプレフィックスを補います。通常、API だけの場合は不要です |
固定レスポンスには、100～599 のステータスコード、Content-Type、本文、カスタムレスポンスヘッダーを設定できます。Connection、Content-Length、Content-Type、Transfer-Encoding、Upgrade など、転送処理に関わるヘッダーはカスタムヘッダーで上書きできません。コンテンツタイプは専用のフィールドで設定してください。
パスの認証動作
ルールはデフォルトで Host を継承 を使用し、現在の Host の ログインを必須にする と厳格な許可リストを適用します。公開アクセス を選ぶと、このパスルールに一致するリクエストだけがログインを省略し、同じ Host の他のパスは Host ポリシーを維持します。
ログイン必須 を選ぶと、公開 Host の指定パスを保護できます。Host の許可リストと高度な認証ポリシーを引き継ぎます。このようなパスを持つ Host も認証情報のサービス範囲と Cookie ドメイン互換性の確認対象になります。権限の範囲は個々のパスではなく Host 単位です。
公開 Host の /admin プレフィックスを保護すると、通常のページは公開のまま、/admin とその配下には認証が必要です。完全一致を優先し、プレフィックスは最長一致を使用します。保護パスと隣接する公開パスの両方を検証してください。
公開パスはヘルスチェック、Webhook コールバック、意図的に匿名公開する固定コンテンツに使用します。完全一致または前方一致の範囲全体に適用されるため、/api を公開すると一致する配下のパスも公開されます。範囲を狭くし、必要な権限確認がアップストリームでも有効か検証してください。
リバースプロキシアクションでは、Host の Basic 認証を自動入力 に設定した認証情報が、実際の Target へ送るリクエストに挿入されます。これは転送先サービス自身の Basic 認証を通過するためのもので、fn-knock へアクセスするユーザーのログイン認証情報ではありません。プロキシヘッダーと Host ヘッダーの維持は、実際の Target に対する共有ランタイムルールによって決まり、Host のデフォルト Target に対する設定とは異なる場合があります。固定レスポンスにはアップストリームがないため、Basic 認証、プロキシヘッダー、Host ヘッダーの維持に関するリクエストヘッダーは送信されません。
送信元がループバック、プライベートアドレス、リンクローカルアドレスの場合、認証サービスは local_exempt を返します。このため、LAN からのアクセスではログインや厳格な許可リストによる拒否が発生しないことがあります。インターネット側のポリシーは、実際の外部ネットワークから検証してください。
例
ヘルスチェック：
パス /healthz
一致 完全一致
アクション 固定レスポンス
ステータス 200
Content-Type text/plain; charset=utf-8
本文 okAPI だけを別のアップストリームへ転送：
パス /api
一致 前方一致
アクション リバースプロキシ
転送先 http://127.0.0.1:8080
一致部分を除去 オンプラットフォーム上の制約
パス別応答は、fnOS FPK、Docker、OpenWrt、Linux、Synology DSM 7 SPK、Windows で、Host ルーティングのサブドメインモードを使用している場合に利用できます。これには トンネル → サブドメインマッピング も含まれます。この機能がファイアウォールのポートを開放したり、DNS レコードを作成したり、Docker ポートを公開したりすることはありません。到達不能な Target が到達可能になることもありません。
トラブルシューティング
- Host ルーティングを使用し、サービス用 Host のレスポンス種別がリバースプロキシで、正しい Host が選択されていることを確認します。
- パスの形式、予約パス、完全一致／前方一致の設定を確認します。
- ルールの認証動作を確認し、継承の場合はリクエストが Host のログインまたは許可リストポリシーでブロックされていないか判断します。
- fn-knock の実行環境から、リバースプロキシの Target へアクセスします。
- リクエストログで、Host、パス、ルート種別、ステータスコード、アップストリームの転送先を照合します。
Host のメインルートについてはサブドメインマッピング、関連するグローバル設定についてはシステム設定を参照してください。