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:

records:
  http:
    referer_filter: 1

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

records:
  http:
    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

In-line Filter

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

Actions

As is the case with ip_allow.yaml rules, each ACL filter takes one of a number of actions. They are specified as @action=<action>, such as @action=add_allow. There are four possible actions:

• allow: This behaves like the allow action in ip_allow.yaml in which a list of allowed methods are provided. Any request with a method in the list is allowed, while any request with a method not in the list is denied. The exception to this is if proxy.config.url_remap.acl_behavior_policy is set to 0. In this case, the allow action is a synonym for add_allow, described below.

• add_allow: This action adds a list of allowed methods to whatever other methods are allowed in a subsequently matched ACL filter or ip_allow.yaml rule. Thus, if an add_allow ACL filter specifies the POST method, and a subsequently matching ip_allow.yaml rule allows the GET and HEAD methods, then any requests that have POST, GET, or HEAD methods will be allowed while all others will be denied.

• deny: This behaves like the deny action in ip_allow.yaml in which a list of denied methods are provided. Any request with a method in the list is denied, while any request with a method not in the list is allowed. The exception to this is if proxy.config.url_remap.acl_behavior_policy is set to 0. In this case, the deny action is a synonym for add_deny, described below.

• add_deny: This action adds a list of denied methods to whatever other methods are denied in a subsequently matched ACL filter or ip_allow.yaml rule. Thus, if an add_deny ACL filter specifies the POST method, and a matching ip_allow.yaml rule allows the GET, HEAD, and POST methods, then this ACL filter effectively removes POST from the allowed method list. Thus only requests with the GET and HEAD methods will be allowed.

例

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.

例

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

Special Filter and ip_allow Named Filter

If ip_allow.yaml has a "deny all" filter, it is treated as a special filter that is applied before remapping for optimizaion. To control this for specific remap rules, a named filter called ip_allow is pre-defined. This named filter is activated implicitly in default. To stop applying the special rule, disable the ip_allow filter as shown below.

# ip_allow.yaml
ip_allow:
   - apply: in
     ip_addrs: 198.51.100.0/24
     action: deny
     method: ALL

# remap.config
.deactivatefilter ip_allow
map ...
map ...
.activatefilter ip_allow

Note this entirely disables ip_allow.yaml checks for those remap rules.

Evaluation Order and Matching Policy

Traffic Server evaluates multiple ACL filters in the following order:

1. Special "deny all" filter in ip_allow.yaml

2. In-line Filter in remap.config

3. Named Filters in remap.config

4. Filters in ip_allow.yaml

When a matching ACL filter is found, Traffic Server stops processing subsequent ACL filters.

Note that step 1 happens at the start of the connection before any transactions are processed, unlike the other rules here. This is an optimization: if literally all requests are denied for a source IP address via an ip_allow.yaml rule, then there is no need to process any content from that IP for the connection at all, so the connection is simply denied at the start.

注釈

Prior to Traffic Server 10.x, Traffic Server traversed all matched ACL filters by IP and "deny" action had priority.

ACL Action Behavior Changes for 10.x

Before Traffic Server 10.x, ACL filters used the same action names as ip_allow.yaml (allow and deny) but these actions behaved differently.

• As described in ip_allow.yaml, for any transaction matching an ip_allow.yaml rule whose action is allow, any request with a method in the allow list will be accepted, while all other methods are denied. deny actions instead list methods which are denied, while all other methods are implicitly allowed.

• These same action names for ACL filters, on the other hand, functioned essentially additively in nature. For instance, an allow ACL filter action would list a set of methods which would be allowed in addition to any other allowed methods specified by ip_allow.yaml rules. Similarly, a deny ACL filter action would list a set of methods which would be denied in addition to any other denied methods specified by ip_allow.yaml rules.

This difference in behavior lead at times to confusion as users would expect the two actions having the same name to behave the same across the ACL filter and ip_allow.yaml rule systems.

For Traffic Server 10.x, a few action naming changes are being done to disambiguate the behavior of ip_allow.yaml and remap ACL filter actions. The following new action names are introduced:

• add_allow: this ACL filter action name, new to Traffic Server 10.x, behaves like allow used to behave for ACL filters pre Traffic Server 10.x: that is, it adds methods which are allowed to the ip_allow.yaml rule otherwise matched for the given transaction.

• add_deny: this ACL filter action name, new to Traffic Server 10.x, behaves like deny used to behave for ACL filters pre Traffic Server 10.x: that is, it adds methods which are denied the ip_allow.yaml rule otherwise matched for the given transaction.

• set_allow: this is an entirely new ACL filter action being introduced in Traffic Server 10.x. The new set_allow action creates a remap filter that behaves like an ip_allow.yaml rule with an allow action. All requests with a method in the list will be allowed, requests with methods not in the list will be denied, and no other filters or ip_allow.yaml rules will be applied. To demonstrate the consistency between this action and how it acts like the corresponding ip_allow.yaml rule action, the set_allow action is also introduced for ip_allow.yaml rules and its behavior is identical to the allow ip_allow.yaml rule action for pre Traffic Server 10.x releases.

• set_deny: this is an entirely new ACL filter action being introduced in Traffic Server 10.x. The new set_deny action creates a remap filter that behaves like an ip_allow.yaml rule with a deny action. All requests with a method in the list will be denied, requests with methods not in the list will be allowed, and no other filters or ip_allow.yaml rules will be applied. To demonstrate the consistency between this action and how it acts like the corresponding ip_allow.yaml rule action, the set_deny action is also introduced for ip_allow.yaml rules and its behavior is identical to the deny ip_allow.yaml rule action for pre Traffic Server 10.x releases.

The behavior of the Traffic Server 9.x allow and deny actions are configurable via proxy.config.url_remap.acl_behavior_policy. This configuration is described in the next two sections, but in short, by default the allow and deny actions behave like they did in Traffic Server 9.x in order to provide backwards compatibility and avoid surprises for people upgrading to Traffic Server 10.x.

Legacy Policy

This is the default ACL action policy and it is configured by setting proxy.config.url_remap.acl_behavior_policy to 0. With this policy, ACL filter allow and deny actions behave like they did pre Traffic Server 10.x: they additively add allowed or denied methods for transactions. Functionally, this means that with this set to 0, allow is a synonym for add_allow and deny is a synonym for add_deny. Because of this, an organization can easily, and incrementally prepare for the new ACL filter action behavior by transitioning a rule one at a time by simply replacing allow with add_allow and deny with add_deny. Once all actions are transitioned, an organization can then switch to the modern policy.

As mentioned above, the legacy and modern ACL filter action policies described in these two sections configure how Traffic Server will respond to the older allow and deny actions. set_allow, set_deny, add_allow, and add_deny actions are not affected by this configuration and they behave the same between the two policies.

Consider a filter like the following:

map http://www.example.com/ http://internal.example.com/ @action=deny @method=POST

The implicit @src_ip is all client IP addresses, so this filter will match on any POST request matched by this remap rule from any client and its action will be to deny such POST requests. For all other methods, the filter will not take effect, thus allowing other active ACL filters or an ip_allow.yaml rule to determine the action to take for any other transaction.

With the legacy policy being described here, this filter acts identically with an add_deny action. Thus, the above rule is identical to:

map http://www.example.com/ http://internal.example.com/ @action=add_deny @method=POST

注釈

This policy's behavior is similar to Traffic Server 9.x and older, but employs a "first match wins" policy.

And just to be complete, here is a rule using the new set_allow action:

map http://www.example.com/ http://internal.example.com/ @action=set_allow @method=GET @method=HEAD

This is a new type of rule that could not be added pre Traffic Server 10.x. It behaves like a corresponding ip_allow.yaml allow action rule like this would have behaved in Traffic Server 9.x. This rule will allow only GET and HEAD requests to the internal.example.com origin while all requests with any other method will be rejected. No other ACL filters or ip_allow.yaml rules will apply for this target.

Modern Policy

As described above in the section "ACL Action Behavior Changes for 10.x", we are moving away from the old allow and deny actions are transitioning to the new set_allow and set_deny and add_allow and add_deny actions. Setting proxy.config.url_remap.acl_behavior_policy to 1 enables the "modern" policy for organizations who have made this transition to these new ACL filter names. With this modern policy set, the use of allow and deny actions will be detected as an accidental and fatal error with a message requesting the user to convert to the new action names. This policy will be the default in Traffic Server 11.x. This is the only behavioral difference between the two policies.

Thus, consider a filter like the following (the exact same as the first example in the legacy section above):

map http://www.example.com/ http://internal.example.com/ @action=deny @method=POST

Note that this uses the old deny action. With the modern policy, this will be detected as a fatal error and Traffic Server will not start with this configuration and the user will be expected to convert this to an ACL filter using either the add_deny or the set_deny actions. The same will happen with an @action=allow action.

Again, set_allow, set_deny, add_allow, and add_deny actions all act the same between modern and legacy behavior configurations, so the examples for those above for the legacy configuration also apply identically to the modern configuration.

Upgrade Notes

As explained above, for 10.x, by default proxy.config.url_remap.acl_behavior_policy is set to 0 to maintain ACL filter action backwards compatibility with Traffic Server 9.x and older remap.config files. This means that ACL filter actions allow and deny behave additively like add_allow and add_deny just like they did for 9.x and older. This is to ease the transition to the modern ACL filter behavior.

When an organization is ready to upgrade to the modern ACL filter action behavior, they need to ensure that they transitioned all of their allow and deny ip_allow.yaml rules and remap.config ACL filter actions to either add_allow and add_deny or set_allow and set_deny actions. To maintain 9.x behavior, this simply means replacing allow with add_allow and deny with add_deny. In case it is helpful, tools/remap/convert_remap_actions_to_10x is provided to do this replacement programmatically. Once all rules are updated, the organization can then switch to the modern policy by setting proxy.config.url_remap.acl_behavior_policy to 1. proxy.config.url_remap.acl_behavior_policy will be removed in 11.x and the modern policy will be the default and only behavior.

Example of ACL filter combinations

As described above, the new add_allow and add_deny actions behave the same in both legacy and modern ACL filter policies: they add to underlying ip_allow.yaml rules methods that are either allowed or denied, respectively. The difference in behavior with these policies is how allow and deny actions behave. To help ensure that the behaviors between these two modes is understood, this section walks through examples of differences between these two policies for allow and deny actions.

This is an example of in-line filter, named filters in remap.config, and ip_allow.yaml.

# ip_allow.yaml
ip_allow:
   - apply: in
     ip_addrs: [0/0, ::/0]
     action: deny
     method: [PURGE, PUSH]

# remap.config
.definefilter named-filter-1 @action=allow @method=HEAD
.definefilter named-filter-2 @action=deny @method=DELETE

.activatefilter named-filter-1
.activatefilter named-filter-2

map http://www.example.com/ http://internal.example.com/ @action=deny @method=POST

With the "Legacy" policy, the evaluation applied from left to right until match is found:

Method	In-line Filter	Named Filter 1	Named Filter 2	ip_allow.yaml	result
GET	-	-	-	allow (implicit)	allowed (200)
POST	deny	-	-	allow (implicit)	denied (403)
HEAD	-	allow	-	allow (implicit)	allowed (200)
DELETE	-	-	deny	allow (implicit)	denied (403)
PURGE	-	-	-	deny	denied (403)
PUSH	-	-	-	deny	denied (403)

With the "Modern" policy, the ip_allow.yaml rule as well as all of the filter rules would trigger a fatal error message and Traffic Server would not start. The user would need to transition to set_allow, set_deny, add_allow, and add_deny actions.

So let's try a set of conversions like that and consider the following updated example:

# ip_allow.yaml
ip_allow:
   - apply: in
     ip_addrs: [0/0, ::/0]
     action: set_deny
     method: [PURGE, PUSH]

# remap.config
.definefilter named-filter-1 @action=add_allow @method=HEAD
.definefilter named-filter-2 @action=add_deny @method=DELETE

.activatefilter named-filter-1
.activatefilter named-filter-2

map http://www.example.com/ http://internal.example.com/ @action=set_deny @method=POST

In this case, we changed the ip_allow.yaml rule to use set_deny instead of deny. This makes it function as it did before in the previous example. Also, we changed the two named filter actions to add_allow and add_deny. Again, this makes them function as they did in legacy mode. Finally, we changed the in-line filter action to set_deny which changes its behavior to be like that of an ip_allow.yaml rule: it will deny all POST requests and allow all other requests.

Method	In-line Filter	Named Filter 1	Named Filter 2	ip_allow.yaml	result
GET	allow	-	-	allow (implicit)	allowed (200)
POST	deny	-	-	allow (implicit)	denied (403)
HEAD	allow	allow	-	allow (implicit)	allowed (200)
DELETE	allow	-	deny	allow (implicit)	allowed (200)
PURGE	allow	-	-	deny	allowed (200)
PUSH	allow	-	-	deny	allowed (200)

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

.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