remap.config

The remap.config file (by default, located in /usr/local/etc/trafficserver/) contains mapping rules that Traffic Server uses to perform the following actions:

  • Traffic Server があるオリジンサーバーのためのリバースプロキシーとして振る舞うときに、そのオリジンサーバーへの URL リクエストを Traffic Server 上で適切な場所に対応づける

  • オリジンサーバーがクライアントを他の場所にリダイレクトするロケーションヘッダーでリクエストに応えるときに、そのクライアントが Traffic Server をバイパスしないようにロケーションヘッダーを対応づける

  • Traffic Server がオリジンサーバーにコンタクトすることなく恒久的または一時的に HTTP リクエストをリダイレクトする

HTTP リクエストのリダイレクトとリバースプロキシーの使用については リバースプロキシーと HTTP リダイレクト を参照してください。

After you modify the remap.config run the traffic_ctl config reload to apply the changes. The current configuration is replaced with the new configuration only if there are no errors in the file. Any syntax error will prevent an update. Even if syntactically correct the file is considered valid only if it has at least proxy.config.url_remap.min_rules_required rules in it. This defaults to 0, but can be set higher if it is desirable to prevent loading an empty or missing file.

フォーマット

remap.config ファイルの各行はマッピングルールを含まなければなりません。空行や # で始まる行は無視されます。各行は読みやすさのために \ を継続マーカーとして使用して複数行に分割することができます。

Traffic Server はスペースで区切られた type、target、replacement という 3 つのフィールドを認識します。 次のリストは各フィールドのフォーマットについて説明します。

type

次のうち一つを入力してください

  • map -- 届いたリクエスト URL を適切なオリジンサーバーの URL に変換します。

  • map_with_recv_port -- リクエストにあるポートの代わりにリクエストを受け取ったポートをマッピングを行うために使うことを除いて 'map' とまったく同じです。 regex 修飾子もこのタイプで使用可能です。もし存在するならば、'map_with_recv_port' によるマッピングは最初に確認されます。マッチするものがある場合、"通常" の順マッピングルールを評価することなくそれが選ばれます。

  • map_with_referer -- 'map' の拡張バージョンで、Referer ヘッダーがターゲットへのリンクを許された URL にセットされている場合にのみターゲット URL にアクセス可能な "直リンク禁止機能" を動作させるために使用されます。

  • reverse_map -- オリジンサーバーのリダイレクトレスポンス内の URL を Traffic Server を向くように変換します。

  • redirect -- オリジンサーバーにコンタクトすることなく HTTP リクエストを恒久的にリダイレクトします。恒久的なリダイレクトは、ブラウザーがブックマークの URL を更新できるようにするために(HTTP ステータスコード 301 を返すことで) URL の変更をブラウザーに通知します。

  • redirect_temporary -- オリジンサーバーにコンタクトすることなく HTTP リクエストを一時的にリダイレクトします。一時的なリダイレクトは、URL の変更が今回のリクエストに限ったものであることを(HTTP ステータスコード 307 を返すことで)ブラウザーに通知します。

    注釈

    use the regex_ prefix to indicate that the line has a regular expression (regex).

target

Enter the request ("from") URL. You can enter up to four components:

scheme://host:port/path_prefix

where scheme is http, https, ws or wss.

replacement

Enter the origin ("to") URL. You can enter up to four components:

scheme://host:port/path_prefix

where scheme is http, https, ws or wss.

注釈

A remap rule for requests that upgrade from HTTP to WebSocket still require a remap rule with the ws or wss scheme.

優先順位

Remap rules are not processed top-down, but based on an internal priority. Once these rules are executed we pick the first match based on configuration file parse order.

  1. map_with_recv_port and regex_map_with_recv_port

  2. map と regex_map と reverse_map

  3. redirect と redirect_temporary

  4. regex_redirect と regex_redirect_temporary

For each precedence group the rules are checked in two phases. If the first phase fails to find a match then the second phase is performed against the same group of rules. In the first phase the rules are checked using the host name of the request. Only rules that specify a host name can match. If there is no match in that phase, then the rules are checked again with no host name and only rules without a host will match. The result is that rules with an explicit host take precedence over rules without.

全一致

1つの / だけのマップルールはワイルドカードとして働き、あらゆるリクエストにマッチします。これは気を付けて使用すべきであり、使用は remap.config ファイルの最後で一度だけであるべきです。

map / http://all.example.com

例

次の章では remap.config のマッピングルールの例を紹介します。

リバースプロキシーマッピングルール

次の例ではターゲットや置換えでパスプレフィックスを指定しないマップルールを紹介します。

map http://www.x.com/ http://server.hoster.com/
reverse_map http://server.hoster.com/ http://www.x.com/

このルールの変換結果は次のとおりです

クライアントリクエスト

変換されたリクエスト

http://www.x.com/Widgets/index.html

http://server.hoster.com/Widgets/index.html

http://www.x.com/cgi/form/submit.sh?arg=true

http://server.hoster.com/cgi/form/submit.sh?arg=true

次の例ではターゲットでパスプレフィックスを指定したマップルールを紹介します。

map http://www.y.com/marketing/ http://marketing.y.com/
reverse_map http://marketing.y.com/ http://www.y.com/marketing/
map http://www.y.com/sales/ http://sales.y.com/
reverse_map http://sales.y.com/ http://www.y.com/sales/
map http://www.y.com/engineering/ http://engineering.y.com/
reverse_map http://engineering.y.com/ http://www.y.com/engineering/
map http://www.y.com/stuff/ http://info.y.com/
reverse_map http://info.y.com/ http://www.y.com/stuff/

これらのルールの変換結果は次のとおりです。

クライアントリクエスト

変換されたリクエスト

http://www.y.com/marketing/projects/manhattan/specs.html

http://marketing.y.com/projects/manhattan/specs.html

http://www.y.com/stuff/marketing/projects/boston/specs.html

http://info.y.com/marketing/projects/boston/specs.html

http://www.y.com/engineering/marketing/requirements.html

http://engineering.y.com/marketing/requirements.html

次の例ではルールの順番について紹介します。

map http://www.g.com/ http://external.g.com/
reverse_map http://external.g.com/ http://www.g.com/
map http://www.g.com/stuff/ http://stuff.g.com/
reverse_map http://stuff.g.com/ http://www.g.com/stuff/

これらのルールの変換結果は次のとおりです。

クライアントリクエスト

変換されたリクエスト

http://www.g.com/stuff/a.gif

http://external.g.com/stuff/a.gif

上の例では、すべての URL が 最初のルールにも 2番目のルールにもマッチするので2番目のルールが適用されることはありません。最初のルールは remap.config の中で先に出てくるので優先されます。

This is different if one rule does not have a host. For example consider these rules using the Match-All rule:

map / http://127.0.0.1:8001/
map http://example.com/dist_get_user http://127.0.0.1:8001/denied.html

These rules are set up to redirect requests to another local process. Using them will result in

クライアントリクエスト

変換されたリクエスト

http://example.com/a.gif

http://127.0.0.1:8001/a.gif

http://example.com/dist_get_user

http://127.0.0.1:8001/denied.html

For the first request the second rule host matches but the path does not and so the second rule is not selected. The first rule is then matched in the second phase when the rules are checked without a host value.

The second request is matched by the second rule even though the rules have the same base precedence. Because the first rule does not have a host it will not match in the first phase. The second rule does have a host that matches the host in the second request along with the other parts of the URL and is therefore selected in the first phase.

This will yield the same results if the rules are reversed because the rule selection happens in different phases making the order irrelevant.

map http://example.com/dist_get_user http://127.0.0.1:8001/denied.html
map / http://127.0.0.1:8001/

次の例ではターゲットと置換えでパスプレフィックスを指定するマップルールを紹介します。

map http://www.h.com/a/b/ http://server.h.com/customers/x/y
reverse_map http://server.h.com/customers/x/y/ http://www.h.com/a/b/

このルールの変換結果は次のとおりです

クライアントリクエスト

変換されたリクエスト

http://www.h.com/a/b/c/d/doc.html

http://server.h.com/customers/x/y/c/d/doc.html

http://www.h.com/a/index.html

変換失敗

次の例ではリバースマップルールを紹介します。

map http://www.x.com/ http://server.hoster.com/x/
reverse_map http://server.hoster.com/x/ http://www.x.com/

これらのルールの変換結果は次のとおりです。

クライアントリクエスト

変換されたリクエスト

http://www.x.com/Widgets

http://server.hoster.com/x/Widgets

クライアントリクエスト

オリジンサーバーヘッダー

変換されたリクエスト

http://www.x.com/Widgets

http://server.hoster.com/x/Widgets/

http://www.x.com/Widgets/

複数のサーバーのリバースプロキシーとして振る舞うとき、Traffic Server は Host: ヘッダーを送信しない古めのブラウザーに URL を示せません。解決策として、Traffic Server がホストヘッダーの無いリクエストをリダイレクトする URL を records.yaml の proxy.config.header.parse.no_host_url_redirect 変数に設定してください。

リダイレクトマッピングルール

次のルールは www.company.com へのすべての HTTP リクエストを恒久的に www.company2.com へリダイレクトします

redirect http://www.company.com/ http://www.company2.com/

次のルールは www.company.com へのすべての HTTP リクエストを 一時的に www.company2.com へリダイレクトします

redirect_temporary http://www.company1.com/ http://www.company2.com/

正規表現 (regex) リマップサポート

以下の制限のもとに、リマッピングルールに正規表現を指定することができます

  • Only the host field can contain a regex; the scheme, port, and other fields cannot. For path manipulation via regexes, use the Regex リマッププラグイン.

  • サブパターンのキャプチャ数は 9 個に制限されます。これは $0 から $9 までが置換えプレースホルダーとして使えることを意味します($0 は入力文字列全体になります)。

  • 展開文字列内の置換え数は 10 個に制限されます。

  • There is no regex_ equivalent to reverse_remap, so when using regex_map you should make sure the reverse path is clear by setting (proxy.config.url_remap.pristine_host_hdr)

例

regex_map http://x([0-9]+).z.com/ http://real-x$1.z.com/
regex_redirect http://old.(.*).z.com http://new.$1.z.com

map_with_referer

フォーマットは次のとおりです。

map_with_referer client-URL origin-server-URL redirect-URL regex1 [regex2 ...]

'redirect-URL' は RFC 2616 に従って指定されたリダイレクト先 URL であり、実行時のリダイレクト先 URL の修正のために特別なフォーマットの命令を含むことができます。すべての regex は検証されなければならない "Referer" ヘッダーの内容を記述する Perl 互換の正規表現です。実際のリクエストが "Referer" ヘッダーを持っていないかリファラーの正規表現にマッチしない場合、HTTP リクエストは 'redirect-URL' にリダイレクトされます。

At least one regular expressions must be specified in order to activate 'deep linking protection'. There are limitations for the number of referer regular expression strings - 2048. In order to enable the 'deep linking protection' feature in Traffic Server, configure records.yaml with:

1ts:
2  http:
3    referer_filter: 1

In order to enable run-time formatting for redirect URL, configure:

1ts:
2  http:
3    referer_format_redirect: 1

実行時の redirect-URL の整形が有効化された場合は次の整形シンボルが使用できます。

%r - to substitute original "Referer" header string
%f - to substitute client-URL from 'map_with_referer' record
%t - to substitute origin-server-URL from 'map_with_referer' record
%o - to substitute request URL to origin server, which was created a
     the result of a mapping operation

注意: リクエストの Referer ヘッダーが任意であると指定するために使用可能な "~*" という特別なリファラータイプがあります。もし "~*" というリファラーが map_with_referer マッピングで使用された場合、Referer ヘッダーを持つリクエストのみが妥当性を検証されます。もし "~" シンボルがリファラー正規表現より前に指定された場合は、マッチするリファラーを持つリクエストは redirectURL にリダイレクトされることを意味します。これはいわゆるネガティブリファラー一覧を作るために使用できます。もし "*" がリファラー正規表現として使用された場合、すべてのリファラーが許可されます。リファラー一覧内の様々な "*" と "~" の組み合わせは異なったフィルタリングルールを作るために使用されます。

map_with_referer の例

map_with_referer http://y.foo.bar.com/x/yy/  http://foo.bar.com/x/yy/ http://games.bar.com/new_games .*\.bar\.com www.bar-friends.com

説明: Referer ヘッダーがリクエストに含まれていなければならず、".*.bar.com" と "www.bar-friends.com" のみが許可されます。

map_with_referer http://y.foo.bar.com/x/yy/  http://foo.bar.com/x/yy/ http://games.bar.com/new_games * ~.*\.evil\.com

説明: Referer ヘッダーがリクエストに含まれていなければなりませんが、".*.evil.com" を除くすべてのリファラーが許可されます。

map_with_referer http://y.foo.bar.com/x/yy/  http://foo.bar.com/x/yy/ http://games.bar.com/error ~* * ~.*\.evil\.com

説明: Referer ヘッダーの存在は任意です。しかし Referer ヘッダーが存在する場合、".*.evil.com" からのリクエストだけは redirect-URL にリダイレクトされます。

プラグインの連鎖

プラグインは指定した順番で、結果を次へと渡しながら評価するように設定できます。(プラグインが 0 を返さない限り続き、返されると "連鎖"は切れます。)

例

map http://url/path http://url/path \
    @plugin=/etc/traffic_server/config/plugins/plugin1.so @pparam=1 @pparam=2 \
    @plugin=/etc/traffic_server/config/plugins/plugin2.so @pparam=3

これは "1" と "2" を plugin1.so に "3" を plugin2.so に渡します。

これは "1" と "2" を plugin1.so に "3" を plugin2.so に渡します。

NextHop Selection Strategies

You may configure Nexthop or Parent hierarchical caching rules by remap using the @strategy tag. See Hierarchical Caching and strategies.yaml for configuration details and examples.

ACL Filters

ACL filters can be created to control access of specific remap lines. The markup is very similar to that of ip_allow.yaml, with slight changes to accommodate remap markup.

Note: As of ATS v10.x, these filters are applied just as ip_allow.yaml, meaning once a filter matches the request, the action for that rule takes effect. In previous versions, all filters for a remap rule were evaluated, and the deny action took priority. Also, if an ACL filter matches, then ip_allow.yaml rules will not not apply to the request because the matched rule is the ACL filter.

例

map http://foo.example.com/neverpost  http://foo.example.com/neverpost @action=deny @method=post
map http://foo.example.com/onlypost  http://foo.example.com/onlypost @action=allow @method=post

map http://foo.example.com/  http://foo.example.com/ @action=deny @src_ip=1.2.3.4
map http://foo.example.com/  http://foo.example.com/ @action=allow @src_ip=127.0.0.1

map http://foo.example.com/  http://foo.example.com/ @action=allow @src_ip=10.5.2.1 @in_ip=72.209.23.4

map http://foo.example.com/  http://foo.example.com/ @action=allow @src_ip=127.0.0.1 @method=post @method=get @method=head

map http://foo.example.com/  http://foo.example.com/ @action=allow @src_ip_category=ACME_INTERNAL @method=post @method=get @method=head

Note that these ACL filters will return a 403 response if the resource is restricted.

The difference between @src_ip and @in_ip is that the @src_ip is the client ip and the in_ip is the ip address the client is connecting to (the incoming address). @src_ip_category functions like ip_category described in ip_allow.yaml. If no IP address is specified for @src_ip, @src_ip_category, or @in_ip, the filter will implicitly apply to all incoming IP addresses. This can be explicitly stated with @src_ip=all.

名前付きフィルター

名前付きフィルターは、.definefilter、.activatefilter そして .deactivatefilter というディレクティブによって作られ、マッピングのブロックに適用されます。名前付きフィルターは使用される前に .definefilter によって作成されなければなりません。一度定義された後は .activatefilter でフィルターが有効化し .deactivatefilter で無効化されるまでのすべてのマッピングで使用できます。

The @internal operator can be used to filter on whether a request is generated by Traffic Server itself, usually by a plugin. This operator is helpful for remapping internal requests without allowing access to external users. By default both internal and external requests are allowed.

In-line ACL filters take priority over named active ACL filters.

例

.definefilter disable_delete_purge @action=deny @method=delete @method=purge
.definefilter local_only @action=allow @src_ip=192.168.0.1-192.168.0.254 @src_ip=10.0.0.1-10.0.0.254

.activatefilter disable_delete_purge

map http://foo.example.com/ http://bar.example.com/

.activatefilter local_only
map http://www.example.com/admin http://internal.example.com/admin
.deactivatefilter local_only

map http://www.example.com/ http://internal.example.com/
map http://auth.example.com/ http://auth.internal.example.com/ @action=allow @internal

The filter disable_delete_purge will be applied to all of the mapping rules. (It is activated before any mappings and is never deactivated.) The filter local_only will only be applied to the second mapping.

Implict IPAllow filter

To allow control of IP Allow it is treated as an implicitly active and named filter. When this filter is active IP Allow checks are done before remap. To prevent this for specific remap rules, this filter, named "ip_allow", must be disabled. The common way of doing this would be

.deactivatefilter ip_allow
map ...
map ...
.activateefilter ip_allow

Note this entirely disables IP Allow checks for those remap rules.

追加のリマップファイルの取り込み

.include ディレクティブはマッピングルールを複数のファイルに分散できるようにします。.include ディレクティブの引数は追加のマッピングルールのためにパースされるファイル名のリストです。ファイル名が絶対パスでない場合は Traffic Server の設定ディレクトリからの相対で解決されます。

.include ディレクティブの効果はリストのファイルが親に含まれていて取り込んだ場所からパースが再開されるようなものです。これは取り込まれたファイル内で名前の付けられたフィルターはスコープ内でグローバルであり、さらなる .include ディレクティブも許されることを意味します。

注釈

取り込まれたリマップファイルは現在は設定サブシステムによって監視されていません。取り込まれたリマップファイルの変更は remap.config も変更されない限りは traffic_ctl config reload で適用されるオンラインでの設定の変更によって通知されません。

例

この例では、トップレベルの remap.config ファイルが単純に追加のマッピングルールファイルを参照しています。

.include filters.config
.include one.example.com.config two.example.com.config

filters.config は次のルールを含んでいます。

.definefilter deny_purge @action=deny @method=purge
.definefilter allow_purge @action=allow @method=purge

one.example.com.config は次のルールを含んでいます。

.activatefilter deny_purge
map http://one.example.com http://origin-one.example.com
.deactivatefilter deny_purge

two.example.com.config は次のルールを含んでいます。

.activatefilter allow_purge
map http://two.example.com http://origin-two.example.com
.deactivatefilter allow_purge