remap.config - Traffic Server remap rules configuration file
file (by default, located in
) 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
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.
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 \
Traffic Server recognizes three space-delimited fields: type
, and replacement
. The following list describes the format
of each field.
- 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).
- Enter the origin ("from") URL. You can enter up
to four components:
- Enter the origin ("from") URL. You can enter up
to four components:
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
- map_with_recv_port and
- map and regex_map and reverse_map
- redirect and redirect_temporary
- regex_redirect and
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
The following section shows example mapping rules in the 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/
This rule results in the following translations:
The following example shows a map rule with path prefixes specified in the
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:
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.
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
The following example shows a mapping with a path prefix specified in the target
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.
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.
||Origin Server Header
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:
a solution, set the variable
file to the URL to which Traffic Server will redirect
requests without host headers.
The following rule permanently redirects all HTTP requests for
redirect http://www.company.com/ http://www.company2.com/
The following rule temporarily
redirects all HTTP requests for
redirect_temporary http://www.company1.com/ http://www.company2.com/
Regular expressions can be specified in remapping rules, with the limitations
- Only the host field can contain a regex; the
scheme, port, and other fields cannot. For path manipulation
via regexes, use the admin-plugins-regex-remap.
- 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_map you should make sure
the reverse path is clear by setting (
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
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 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
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.
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 \
will pass "1" and "2" to plugin1.so and "3" to
This will pass "1" and "2" to plugin1.so and "3"
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=184.108.40.206
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=220.127.116.11
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
The difference between @src_ip
is that the
is the client ip and the in_ip
is the ip address the
client is connecting to (the incoming address).
Named filters can be created and applied to blocks of mappings using the
, and .deactivatefilter
directives. Named filters must be defined using .definefilter
being used. Once defined, .activatefilter
can used to activate a filter
for all mappings that follow until deactivated with .deactivatefilter
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
map http://foo.example.com/ http://bar.example.com/
map http://www.example.com/admin http://internal.example.com/admin
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
will only be applied to the second mapping.
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
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.
In this example, a top-level remap.config
file simply references
additional mapping rules files
.include one.example.com.config two.example.com.config
The file filters.config
.definefilter deny_purge @action=deny @method=purge
.definefilter allow_purge @action=allow @method=purge
The file one.example.com.config
map http://one.example.com http://origin-one.example.com
The file two.example.com.config
map http://two.example.com http://origin-two.example.com