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.

フォーマット

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 を返すことで)ブラウザーに通知します。

target

オリジン("from")の URL を入力してください。4 つの構成要素を入力できます。

scheme://host:port/path_prefix

where scheme is http, https, ws or wss.

replacement

オリジン("from")の URL を入力してください。4 つの構成要素を入力できます。

scheme://host:port/path_prefix

where scheme is http, https, ws or wss.

優先順位

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 と `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.config の 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 Remap Plugin.

• サブパターンのキャプチャ数は 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' にリダイレクトされます。

'直リンク禁止機能' を動作させるためには少なくとも一つの正規表現が指定されていなければ成りません。リファラー正規表現の数には制限があり 2048 です。Traffic Server で '直リンク禁止機能' を有効化するためには records.config の次の変数を設定してください。

CONFIG proxy.config.http.referer_filter INT 1

実行時のリダイレクト先 URL の整形を有効化するには次の設定を行ってください。

CONFIG proxy.config.http.referer_format_redirect INT 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 に渡します。

Acl Filters

Acl filters can be created to control access of specific remap lines. The markup is very similar to that of ip_allow.config, with slight changes to accomodate remap markup

例

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

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).

名前付きフィルター

名前付きフィルターは、.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.

例

.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.

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

.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 dallowpurge