Updated Branches: refs/heads/master dfdb6780d -> b0c93d11e
TS-1173 Improve the comments in remap.config Project: http://git-wip-us.apache.org/repos/asf/trafficserver/repo Commit: http://git-wip-us.apache.org/repos/asf/trafficserver/commit/b0c93d11 Tree: http://git-wip-us.apache.org/repos/asf/trafficserver/tree/b0c93d11 Diff: http://git-wip-us.apache.org/repos/asf/trafficserver/diff/b0c93d11 Branch: refs/heads/master Commit: b0c93d11e3e90a3a8a009d825ae59b404d816ebb Parents: dfdb678 Author: Leif Hedstrom <l...@ogre.com> Authored: Fri Mar 30 11:18:37 2012 -0600 Committer: Leif Hedstrom <l...@ogre.com> Committed: Fri Mar 30 11:18:37 2012 -0600 ---------------------------------------------------------------------- proxy/config/remap.config.default | 199 +++++++++++++++++++------------ 1 files changed, 122 insertions(+), 77 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/trafficserver/blob/b0c93d11/proxy/config/remap.config.default ---------------------------------------------------------------------- diff --git a/proxy/config/remap.config.default b/proxy/config/remap.config.default index 3eb6dde..c077377 100644 --- a/proxy/config/remap.config.default +++ b/proxy/config/remap.config.default @@ -1,32 +1,59 @@ # -# # URL Remapping Config File # -# Format is: -# <map_type> <scheme>://<host>:<port>/<path_prefix> <scheme>://<host>:<port>/<path_prefix> fromURL toURL <tag_value> <filtering arguments> -# this last <tag_value> directive is optional and can be different for different types of <map_type> -# <filtering arguments> are optional ACL-like argumens unique for each remap rule +# 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 +# argumens 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 # -# Six different types of mappings are possible -- 'map', 'map_with_referer', -# 'map_with_recv_port', 'reverse_map', 'redirect', and 'redirect_temporary'. # Each of these map types can be prefixed with the string 'regex_' to indicate # that the rule will have regular expression strings. See the last part of # this description for more information on regex support. # # The 'map' mapping is the most straightforward. Requests that match the -# from URL are changed into the to URL. The user agent will see the new -# page 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 avaialble in -# 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. +# 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 avaialble 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. +# # The 'redirect_temporary' mapping acts in the same way but tells the browser # that this redirect is only temporary. We need to map the URL in reverse # proxy mode so that user agents know to contact Traffic Server and not @@ -35,13 +62,13 @@ # For example, you can set up a reverse proxy for www.example.com with the # real content situated at server1.example.com with the rules: # -# map http://www.example.com/ http://server1.example.com/ -# reverse_map http://server1.example.com/ http://www.example.com/ +# map http://www.example.com/ http://server1.example.com/ +# reverse_map http://server1.example.com/ http://www.example.com/ # # Or you could permanently redirect users trying to access www.oldserver.com # to www.newserver.com with the following rule: # -# redirect http://www.oldserver.com/ http://www.newserver.com +# redirect http://www.oldserver.com/ http://www.newserver.com # # If the redirect is only temporary, you want to only temporarily remap the # URL. You could use the following rule to divert users away from a failed @@ -49,75 +76,93 @@ # # redirect_temporary http://broken.firm.com http://working.firm.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 'map_with_referer' is the following: -# -# map_with_referer fromURL toURL redirectURL refererRegExp1 [refererRegExp2 ... refererRegExp2] -# -# Where fromURL and toURL must be specified in the same manner as in a regular 'map'. -# redirectURL is a redirection URL specifed according to RFC 2616 and can contain -# special formatting instructions for run-time modifications of the resulting redirection URL. -# refererRegExp is a POSIX regular expression, 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 -# redirectURL. -# At least one refererRegExp 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 -# 'CONFIG proxy.config.http.referer_filter INT 1' configuration record must be specified in -# the records.config file. Without this configuration record, the 'map_with_referer' entry will be -# treated as a regular 'map' without "Referer" header validation. -# In order to enable run-time formatting for redirectURL -# 'CONFIG proxy.config.http.referer_format_redirect INT 1' must be specified in the records.config file. -# Without this configuration record redirectURL will be used 'as is' without modifications. -# However, if run-time formatting for redirectURL was enabled the following format symbols can be used: -# %r - to substitute original "Referer" header string from client's request. -# %f - to substitute fromURL from 'map_with_referer' record -# %t - to substitute toURL from 'map_with_referer' record -# %o - to substiture request URL to origin server, which was created as 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. -# -# For example, -# 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 -# Rule: Referer header must be in the request, only ".*\.bar\.com" and "www.bar-friends.com" are allowed. +# 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-serverURL redirect-URL regex1 [regex2 ...] +# +# 'redirect-URL' is a redirection URL specifed according to RFC 2616 and can +# contain special formatting instructions for run-time modifications of the +# resulting redirection URL. refererRegExp is a POSIX regular expression, +# 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 redirectURL 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 -# Rule: 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/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 # -# map_with_referer http://y.foo.bar.com/x/yy/ http://foo.bar.com/x/yy/ http://games.bar.com/error ~* * ~.*\.evil\.com -# Rule: Referer header is optional. However, if Referer header exists, only request from ".*\.evil\.com" will be redirected to redirectURL. +# Explanation: Referer header is optional. However, if Referer header exists, +# only request from ".*\.evil\.com" will be redirected to redirectURL. # # There are optional filtering arguments that can be specified at the end of the mapping definition line: # -# @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> +# @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> # # There is no limitation for the number of filtering arguments. # -# For 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 +# 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. # .defflt disable_all @action=deny @src_ip=0.0.0.1-254.254.254.254 # .defflt disable_delete_purge @action=deny @method=delete @method=purge # .useflt disable_all # .useflt disable_delete_purge # -# Regex support: Regular expressions can be specified in the rules with the +# Regex support: Regular expressions can be specified in the rules with the # following limitations: # -# 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 +# 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. #
