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:

  • Map URL requests for a specific origin server to the appropriate location on Traffic Server when Traffic Server acts as a reverse proxy for that particular origin server
  • Reverse-map server location headers so that when origin servers respond to a request with a location header that redirects the client to another location, the clients do not bypass Traffic Server
  • Redirect HTTP requests permanently or temporarily without Traffic Server having to contact any origin servers

Refer to Reverse Proxy and HTTP Redirects, for information about redirecting HTTP requests and using reverse proxy.

After you modify the remap.config run the traffic_ctl config reload to apply the changes. When you apply the changes to one node in a cluster, Traffic Server automatically applies the changes to all other nodes in the cluster.

格式

remap.config 文件里的每一行必须包含一个缓存规则. 空行或以 开头的行会被忽略. 每行可以分成多行以提高可读性, 方法是使用 \ 继续标记.

Traffic Server recognizes three space-delimited fields: type, target, and replacement. The following list describes the format of each field.

type

请输入以下内容之一:

  • map – 将传入的 URL 请求转换成相应的源服务器 URL .
  • map_with_recv_port –exactly like ‘map’ except that it uses the port at which the request was received to perform the mapping instead of the port present in the request. The regex qualifier can also be used for this type. When present, ‘map_with_recv_port’ mappings are checked first. If there is a match, then it is chosen without evaluating the “regular” forward mapping rules.
  • map_with_referer – extended version of ‘map’, which can be used to activate “deep linking protection”, where target URLs are only accessible when the Referer header is set to a URL that is allowed to link to the target.
  • reverse_map – translates the URL in origin server redirect responses to point to the Traffic Server.
  • redirect – redirects HTTP requests permanently without having to contact the origin server. Permanent redirects notify the browser of the URL change (by returning an HTTP status code 301) so that the browser can update bookmarks.
  • redirect_temporary –redirects HTTP requests temporarily without having to contact the origin server. Temporary redirects notify the browser of the URL change for the current request only (by returning an HTTP status code 307).
target

Enter the origin (“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 (“from”) URL. You can enter up to four components:

scheme://host:port/path_prefix

where scheme is http, https, ws or wss.

优先级

Remap 规则不是自上而下处理的, 而是基于内部优先级. 执行这些规则后, 将根据配置文件解析顺序选取第一个匹配项.

  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

匹配-全部

用单个 / 作为通配符的映射规则, 它将匹配任何请求. 使用时需谨慎, 当然, 在 remap.config 文件的结尾只需要一次. 例子.

map / http://all.example.com

例子

下一节介绍在:file:remap.config 文件里的映射规则示例.

反向代理映射规则

The following example shows a map rule that does not specify a path prefix in the target or replacement:

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

此规则将导致以下转换:

下面的例子显示了在目标中指定的路径前缀的映射规则 The following example shows a map rule with path prefixes specified in the target:

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/

此规则将导致以下转换:

The following example shows that the order of the rules matters:

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/

These rules result in the following translation.

Client Request Translated Request
http://www.g.com/stuff/a.gif http://external.g.com/stuff/a.gif

In the above examples, the second rule is never applied because all URLs that match the second rule also match the first rule. The first rule takes precedence because it appears earlier in the remap.config file.

The following example shows a mapping with a path prefix specified in the target and replacement:

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/

This rule results in the following translation.

Client Request Translated Request
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 Translation fails

The following example shows reverse-map rules:

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

These rules result in the following translations.

Client Request Translated Request
http://www.x.com/Widgets http://server.hoster.com/x/Widgets
Client Request Origin Server Header Translated Request
http://www.x.com/Widgets http://server.hoster.com/x/Widgets/ http://www.x.com/Widgets/

When acting as a reverse proxy for multiple servers, Traffic Server is unable to route to URLs from older browsers that do not send the Host: header. As a solution, set the variable :ts:cv:`proxy.config.header.parse.no_host_url_redirect` in the records.config file to the URL to which Traffic Server will redirect requests without host headers.

Redirect Mapping Rules

The following rule permanently redirects all HTTP requests for www.company.com to www.company2.com:

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

The following rule temporarily redirects all HTTP requests for www.company1.com to www.company2.com:

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

Regular Expression (regex) Remap Support

Regular expressions can be specified in remapping rules, with the limitations below:

  • 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.
  • The number of capturing subpatterns is limited to 9. This means that $0 through $9 can be used as subtraction placeholders ($0 will be the entire input string).
  • The number of substitutions in the expansion string is limited to 10.
  • There is no regex_ equivalent to reverse_remap, so when using regex_remap you should make sure the reverse path is clear by setting (:ts:cv:`proxy.config.url_remap.pristine_host_hdr`)

Examples

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

the format of is the following:

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

‘redirect-URL’ is a redirection URL specified according to RFC 2616 and can contain special formatting instructions for run-time modifications of the resulting redirection URL. All regexes Perl compatible regular expressions, which describes the content of the “Referer” header which must be verified. In case an actual request does not have “Referer” header or it does not match with referer regular expression, the HTTP request will be redirected to ‘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.config with:

CONFIG proxy.config.http.referer_filter INT 1

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

CONFIG proxy.config.http.referer_format_redirect INT 1

When run-time formatting for redirect-URL was enabled the following format symbols can be used:

%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

Note: There is a special referer type “~*” that can be used in order to specify that the Referer header is optional in the request. If “~*” referer was used in map_with_referer mapping, only requests with Referer header will be verified for validity. If the “~” symbol was specified before referer regular expression, it means that the request with a matching referer header will be redirected to redirectURL. It can be used to create a so-called negative referer list. If “*” was used as a referer regular expression - all referers are allowed. Various combinations of “*” and “~” in a referer list can be used to create different filtering rules.

map_with_referer Examples

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

Explanation: Referer header must be in the request, only ”.*.bar.com” and “www.bar-friends.com” are allowed.

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

Explanation: Referer header must be in the request but all referers are allowed except ”.*.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

Explanation: Referer header is optional. However, if Referer header exists, only request from ”.*.evil.com” will be redirected to redirect-URL.

Plugin Chaining

Plugins can be configured to be evaluated in a specific order, passing the results from one in to the next (unless a plugin returns 0, then the “chain” is broken).

Examples

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

will pass “1” and “2” to plugin1.so and “3” to plugin2.so.

This will pass “1” and “2” to plugin1.so and “3” to 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

Examples

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

Named Filters

Named filters can be created and applied to blocks of mappings using the .definefilter, .activatefilter, and .deactivatefilter directives. Named filters must be defined using .definefilter before being used. Once defined, .activatefilter can used to activate a filter for all mappings that follow until deactivated with .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.

Examples

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

Including Additional Remap Files

The .include directive allows mapping rules to be spread across multiple files. The argument to the .include directive is a list of file names to be parsed for additional mapping rules. Unless the names are absolute paths, they are resolved relative to the Traffic Server configuration directory.

The effect of the .include directive is as if the contents of the listed files is included in the parent and parsing restarted at the point of inclusion. This means that and filters named in the included files are global in scope, and that additional .include directives are allowed.

注解

Included remap files are not currently tracked by the configuration subsystem. Changes to included remap files will not be noticed by online configuration changes applied by traffic_ctl config reload unless remap.config has also changed.

Examples

In this example, a top-level remap.config file simply references additional mapping rules files

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

The file filters.config contains

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

The file one.example.com.config contains:

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

The file two.example.com.config contains:

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