REMAP.CONFIG(5)

📦
version 9.2.5 · 5 versions
, in ubuntu questing

🌸 NAME 🌸

okay bestie, so remap.config(5) is literally the Traffic Server remap rules configuration file. The remap.config file (by default, located in /usr/local/etc/trafficserver/) contains mapping rules that Traffic Server uses to perform these 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 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.

NOTE: A remap rule for requests that upgrade from HTTP to WebSocket still require a remap rule with the ws or wss 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.

  1. map_with_recv_port and regex_map_with_recv_port
  2. map and regex_map and reverse_map
  3. redirect and redirect_temporary
  4. regex_redirect and 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.

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

okay bestie, we're back and we're in the rule-ordering era, because apparently the config file is extremely opinionated about who goes first 💅✨

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 file. no cap, that's just how it is 🫶

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

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. main character rule behavior, honestly 👑

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.

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.

And when the header comes back the other way:

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; 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_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 💖

okay so this one is the deep-linking-protection girlie, and the format looks like this:

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

so <pink>redirect-URL</pink> is a redirect URL set up per RFC 2616, and it can carry special formatting instructions that get filled in at run time to build the actual redirect URL you end up sending. all those regexes? they're Perl compatible regular expressions, and they describe what has to be in the "Referer" header for the request to be considered valid. and if an actual request either has no "Referer" header at all, or its referer doesn't match the referer regular expression, the HTTP request gets redirected to <pink>redirect-URL</pink>. simple as that 💅

you need at least one regular expression specified to turn on the <rainbow>deep linking protection</rainbow>. also heads up, there's a limit on how many referer regular expression strings you can have — 2048, no more. and to actually enable deep linking protection in Traffic Server, you configure records.config with:

CONFIG proxy.config.http.referer_filter INT 1

and if you want the run-time formatting for the redirect URL, you configure:

CONFIG proxy.config.http.referer_format_redirect INT 1

once run-time formatting for <pink>redirect-URL</pink> is on, these format symbols are available to you:

%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's a special referer type <hotpink>"~"</hotpink> and it's lowkey iconic. you use it to say that the Referer header is *optional in the request. if "~*" referer is used in a map_with_referer mapping, only requests that actually have a Referer header get verified for validity. and if the "~" symbol comes before a referer regular expression, that means requests with a matching referer header get redirected to redirectURL — perfect for building a so-called negative referer list. if "*" is used as a referer regular expression, all referrers are allowed. you can mix and match "*" and "~" in a referer list however you like to cook up all sorts of 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: the Referer header has to be in the request, and 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: the Referer header has to 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: the Referer header is optional. but if the Referer header does exist, only requests from ".*.evil.com" get redirected to <pink>redirect-URL</pink>. sneaky, right? 😭

🔗 PLUGIN CHAINING 🔗

so you can configure plugins to be evaluated in a specific order, and the results pass from one into the next — unless a plugin returns 0, in which case the <red>"chain" is broken. no passing go, no collecting $200.

✨ 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. (yes bestie, that's the doc saying it twice — we keep it 💀)

🛡️ ACL FILTERS 🛡️

acl filters are how you control access to specific remap lines. the markup is very similar to ip_allow.yaml, just with slight changes to accommodate remap markup. same vibe, different font.

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. so no sneaking in, babes.

and the difference between @src_ip and @in_ip? @src_ip is the client ip, and in_ip is the ip address the client is connecting to — aka the incoming address. two totally different things, don't conflate them 🙈

🏷️ NAMED FILTERS 🏷️

named filters!! you create them and apply them to blocks of mappings using the .definefilter, .activatefilter, and .deactivatefilter directives. and yes, a named filter has to be defined with .definefilter before you use it — no manifesting a filter that doesn't exist yet. once it's defined, .activatefilter activates it for all mappings that follow, until you deactivate it with .deactivatefilter.

also the @internal operator exists, and you can use it to filter on whether a request was generated by Traffic Server itself, usually by a plugin. super helpful for remapping internal requests without letting external users anywhere near them. 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 gets applied to all of the mapping rules (it's activated before any mappings happen and is never deactivated). the filter local_only only gets applied to the second mapping. see how the scoping works? obsessed.

🫶 IMPLICT IPALLOW FILTER 🫶

to allow control of IP Allow, it's treated as an implicitly active and named filter. when this filter is active, IP Allow checks are done before remap. and if you want to prevent that for specific remap rules, you disable this filter, which is named <pink>"ip_allow". 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. like, fully. so know what you're doing, bestie 😭

🚦 NEXTHOP SELECTION STRATEGIES 🚦

you may configure Nexthop or Parent hierarchical caching rules by remap using the @strategy tag. for configuration details and examples, go see Hierarchical Caching and strategies.yaml. iykyk ✨

📂 INCLUDING ADDITIONAL REMAP FILES 📂

the .include directive lets mapping rules be spread across multiple files, which is honestly so much cleaner. the argument to .include is a list of file names to be parsed for additional mapping rules. unless the names are absolute paths, they get resolved relative to the Traffic Server configuration directory.

the effect of .include is as if the contents of the listed files were included in the parent and parsing restarted at the point of inclusion. which means filters named in the included files are global in scope, and that additional .include directives are allowed. nesting!! 🌸

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
2026, dev@trafficserver.apache.org

and that's a wrap on REMAP.CONFIG(5), bestie 🎀 you made it all the way through — main character energy fr fr. this one's from version 9.2, dated Feb 12, 2026, so if your page footer says something else, you're reading a different edition. go forth and remap responsibly 💖✨🦋

📦 where this page comes from