You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by zw...@apache.org on 2012/03/30 19:19:14 UTC
git commit: TS-1173 Improve the comments in remap.config
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 <le...@ogre.com>
Authored: Fri Mar 30 11:18:37 2012 -0600
Committer: Leif Hedstrom <le...@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.
#