~ubuntu-branches/ubuntu/wily/trafficserver/wily

# Using remap.config allows you to accomplish two things:

#

#  1) Rewrite a URL (from the client) before sending it to the Origin Server.

#  2) Protect the proxy server, to only allow certain requests.

#

#  With the default configurations, at least one remap rule is required. This

#  can be relaxed with the following configuration in records.config:

#

#   CONFIG proxy.config.url_remap.remap_required INT 0

#

# Be aware, doing so makes the proxy a generic, open-relay!

#

#  The format is: 

#      <map_type> client-URL origin-server-URL <tag_value> <filtering>

#

# Where client-URL and origin-server-URL are both of the format

#    <scheme>://<host>:<port>/<path_prefix> 

#

#  The <tag_value> directive is optional and can be different for different

#  types of <map_type>. The <filtering arguments> are optional ACL-like

#  arguments unique for each remap rule

#

#  Six different types of mappings are possible:

#     map

#     map_with_referer

#     map_with_recv_port

#     reverse_map

#     redirect

#     redirect_temporary

#

#  client-URL are rewritten into the origin-server-URL. The user agent will see

#  the page on the remapped URL, but will not be notified of the address

#  change.

#

#  The 'map_with_referer' is an extended version of 'map', which can be used to

#  activate the so-called "deep linking protection" feature available in

#  Apache Traffic Server.

#

#  The 'map_with_recv_port' is 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. 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.

#

#  The 'reverse_map' mapping is used to rewrite location headers sent by the

#  origin server.  The 'redirect' mapping creates a permanent redirect message

#  and informs the browser of the URL change.

#

#    map          http://www.example.com/      http://server1.example.com/

#    reverse_map  http://server1.example.com/  http://www.example.com/

#    redirect   http://www.oldserver.com/    http://www.newserver.com

#  In order to use "deep linking protection" Traffic Server's feature, the

#  'map_with_referer' mapping scheme must be used. In general, 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 redirect0URL, 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.

#

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

#    @action=allow|deny

#    @src_ip=IP-address

#    @method=HTTP method string (CONNECT|DELETE|GET|HEAD|ICP_QUERY|OPTIONS|POST|PURGE|PUT|TRACE|PUSH)

#    @plugin=<plugin_path>

#    @pparam=<plugin_param>

#  Example:

#    map http://foo.cow.com/ http://bar.cow.com @src_ip=10.72.118.51-10.72.118.62 @method=GET @method=DELETE @src_ip=192.168.0.1-192.168.0.254 @action=allow @method=PUT

#

#

# ToDo: This has to be documented.

#  Regex support: Regular expressions can be specified in the rules with the

#  1) Only the host field can have regexes - the scheme, port and other

#     fields cannot.

#  2) The number of capturing sub-patterns is limited to 9;

#     this means $0 through $9 can be used as substitution place holders ($0

#     will be the entire input string)

#  3) The number of substitutions in the expansion string is limited to 10.