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.
Format¶
Each line in the remap.config
file must contain a mapping rule. Empty lines,
or lines starting with #
are ignored. Each line can be broken up into multiple
lines for better readability by using \
as continuation marker.
Traffic Server recognizes three space-delimited fields: type
,
target
, and replacement
. The following list describes the format of each field.
type
Enter one of the following:
map
–translates an incoming request URL to the appropriate origin server 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).Note
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
ishttp
,https
,ws
orwss
.
replacement
Enter the origin (“to”) URL. You can enter up to four components:
scheme://host:port/path_prefix
where
scheme
ishttp
,https
,ws
orwss
.Note
A remap rule for requests that upgrade from HTTP to WebSocket still require a remap rule with the
ws
orwss
scheme.
Precedence¶
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.
map_with_recv_port
andregex_map_with_recv_port
map
andregex_map
andreverse_map
redirect
andredirect_temporary
regex_redirect
andregex_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.
Match-All¶
A map rule with a single /
acts as a wildcard, it will match any
request. This should be use with care, and certainly only once at the
end of the remap.config file. E.g.
map / http://all.example.com
Examples¶
The following section shows example mapping rules in the
remap.config
file.
Reverse Proxy Mapping Rules¶
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/
This rule results in the following translations:
Client Request |
Translated Request |
---|---|
|
|
|
|
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/
These rules result in the following translations:
Client Request |
Translated Request |
---|---|
|
|
|
|
|
|
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 |
---|---|
|
|
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.
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
Client Request |
Translated Request |
---|---|
|
|
|
|
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/
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 |
---|---|
|
|
|
|
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 |
---|---|
|
|
Client Request |
Origin Server Header |
Translated Request |
---|---|---|
|
|
|
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 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; thescheme
,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 toreverse_remap
, so when usingregex_map
you should make sure the reverse path is clear by setting (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 referrers 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 referrers 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.yaml
, with slight changes to
accommodate 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.
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.
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.
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.
Note
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 allow_purge