remap.config

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.

scheme://host:port/path_prefix

scheme://host:port/path_prefix

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.

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.

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

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

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/

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/

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

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/

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

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

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

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

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

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

map_with_referer http://y.foo.bar.com/x/yy/  http://foo.bar.com/x/yy/ http://games.bar.com/new_games * ~.*\.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

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

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

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

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

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.

.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

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.

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.

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:

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

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

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

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

2026, dev@trafficserver.apache.org