You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by ig...@apache.org on 2013/08/18 20:46:04 UTC
[2/2] git commit: cleanup Reverse Proxy Configuration
cleanup Reverse Proxy Configuration
clean up links and formatting in the Reverse Proxy documentation as well
as in the remap.config reference documentation.
Project: http://git-wip-us.apache.org/repos/asf/trafficserver/repo
Commit: http://git-wip-us.apache.org/repos/asf/trafficserver/commit/a9ca0bbb
Tree: http://git-wip-us.apache.org/repos/asf/trafficserver/tree/a9ca0bbb
Diff: http://git-wip-us.apache.org/repos/asf/trafficserver/diff/a9ca0bbb
Branch: refs/heads/master
Commit: a9ca0bbb3b6a4644fe5c68add414a43215b54cd3
Parents: 6341c32
Author: Igor Galić <i....@brainsware.org>
Authored: Sun Aug 18 20:45:13 2013 +0200
Committer: Igor Galić <i....@brainsware.org>
Committed: Sun Aug 18 20:45:13 2013 +0200
----------------------------------------------------------------------
doc/admin/reverse-proxy-http-redirects.en.rst | 68 ++++-----
doc/reference/configuration/remap.config.en.rst | 140 ++++++++++---------
2 files changed, 99 insertions(+), 109 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a9ca0bbb/doc/admin/reverse-proxy-http-redirects.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/reverse-proxy-http-redirects.en.rst b/doc/admin/reverse-proxy-http-redirects.en.rst
index a2c1f55..007c504 100644
--- a/doc/admin/reverse-proxy-http-redirects.en.rst
+++ b/doc/admin/reverse-proxy-http-redirects.en.rst
@@ -29,8 +29,6 @@ As a reverse proxy cache, Traffic Server serves requests on behalf of
origin servers. Traffic Server is configured in such a way that it
appears to clients like a normal origin server.
-This chapter discusses the following topics:
-
.. toctree::
:maxdepth: 2
@@ -40,7 +38,7 @@ Understanding Reverse Proxy Caching
With **forward proxy caching**, Traffic Server handles web requests to
distant origin servers on behalf of the clients requesting the content.
-**Reverse proxy caching** (also known as \*\*server acceleration \*\*or
+**Reverse proxy caching** (also known as **server acceleration** or
**virtual web hosting**) is different because Traffic Server acts as a
proxy cache on behalf of the origin servers that store the content.
Traffic Server is configured to be *the* origin server which the client
@@ -119,11 +117,9 @@ this is done by setting up the DNS entry for the origin server (i.e.,
the origin server's 'advertised' hostname) so it resolves to the Traffic
Server IP address. When Traffic Server is configured as the origin
server, the browser connects to Traffic Server rather than the origin
-server. For additional information, see `HTTP Reverse
-Proxy <#HTTPReverseProxy>`_.
+server. For additional information, see `HTTP Reverse Proxy`_.
-**Note:** To avoid a DNS conflict, the origin server’s hostname and its
-advertised hostname must not be the same.
+.. note: To avoid a DNS conflict, the origin server’s hostname and its advertised hostname must not be the same.
HTTP Reverse Proxy
==================
@@ -156,17 +152,15 @@ The figure above demonstrates the following steps:
To configure HTTP reverse proxy, you must perform the following tasks:
-- Create mapping rules in the ``remap.config`` file (refer to `Creating
- Mapping Rules for HTTP
- Requests <#CreatingMappingRulesHTTPRequests>`_).
+- Create mapping rules in the :file:`remap.config` file (refer to `Creating
+ Mapping Rules for HTTP Requests`_). ::
- :::text # remap.config map http://www.host.com http://realhost.com
+ # remap.config
+ map http://www.host.com http://realhost.com
-- Enable the reverse proxy option (refer to `Enabling HTTP Reverse
- Proxy <#EnablingHTTPReverseProxy>`_).
+- Enable the reverse proxy option (refer to `Enabling HTTP Reverse Proxy`_).
-In addition to the tasks above, you can also `Set Optional HTTP Reverse
-Proxy Options <#SettingOptionalHTTPReverseProxyOptions>`_.
+In addition to the tasks above, you can also `Setting Optional HTTP Reverse Proxy Options`_.
Handling Origin Server Redirect Responses
-----------------------------------------
@@ -180,11 +174,10 @@ readdress redirects from origin servers so that browsers are redirected
to Traffic Server and *not* to another origin server.
To readdress redirects, Traffic Server uses reverse-map rules. Unless
-you have
-`proxy.config.url_remap.pristine_host_hdr <configuration-files/records.config#proxy.config.url_remap.pristine_host_hdr>`_
-enabled (the default) you should generally set up a reverse-map rule for
-each map rule.d To create reverse-map rules, refer to `Using Mapping
-Rules for HTTP Requests <#UsingMappingRulesHTTPRequests>`_.
+you have :ts:cv:`proxy.config.url_remap.pristine_host_hdr` enabled
+(the default) you should generally set up a reverse-map rule for
+each map rule. To create reverse-map rules, refer to `Using Mapping
+Rules for HTTP Requests`_.
Using Mapping Rules for HTTP Requests
-------------------------------------
@@ -199,8 +192,8 @@ the content is located. When Traffic Server is in reverse proxy mode and
receives an HTTP client request, it first constructs a complete request
URL from the relative URL and its headers. Traffic Server then looks for
a match by comparing the complete request URL with its list of target
-URLs in the ```remap.config`` <../configuration-files/remap.config>`_
-file. For the request URL to match a target URL, the following
+URLs in the :file:`remap.config` file.
+For the request URL to match a target URL, the following
conditions must be true:
- The scheme of both URLs must be the same
@@ -218,8 +211,7 @@ the request URL to match the replacement URL. If the URL contains path
prefixes, then Traffic Server removes the prefix of the path that
matches the target URL path and substitutes it with the path from the
replacement URL. If two mappings match a request URL, then Traffic
-Server applies the first mapping listed in the
-```remap.config`` <configuration-files/remap.config>`_ file.
+Server applies the first mapping listed in the :file:`remap.config` file.
reverse-map rule
~~~~~~~~~~~~~~~~
@@ -256,8 +248,7 @@ Creating Mapping Rules for HTTP Requests
To create mapping rules
-1. Enter the map and reverse-map rules into the
- ```remap.config`` <configuration-files/remap.config>`_ file
+1. Enter the map and reverse-map rules into the :file`remap.config` file
2. Run the command :option:`traffic_line -x` to apply the configuration
changes.
@@ -266,10 +257,9 @@ Enabling HTTP Reverse Proxy
To enable HTTP reverse proxy, follow the steps below.
-1. Edit the following variable in
- `:file:`records.config` <configuration-files/records.config>`_
+1. Edit the following variable in :file:`records.config`
- - `*``proxy.config.reverse_proxy.enabled``* <configuration-files/records.config#proxy.config.reverse_proxy.enabled>`_
+ - :ts:cv:`proxy.config.reverse_proxy.enabled`
2. Run the command :option:`traffic_line -x` to apply the configuration
changes.
@@ -278,21 +268,17 @@ Setting Optional HTTP Reverse Proxy Options
-------------------------------------------
Traffic Server provides several reverse proxy configuration options in
-`:file:`records.config` <configuration-files/records.config>`_ that
-enable you to:
+:file:`records.config` that enable you to:
- Configure Traffic Server to retain the client host header information
- in a request during translation
- (`*``proxy.config.url_remap.pristine_host_hdr``* <configuration-files/records.config#proxy.config.url_remap.pristine_host_hdr>`_)
+ in a request during translation (:ts:cv:`proxy.config.url_remap.pristine_host_hdr`)
- Configure Traffic Server to serve requests only to the origin servers
listed in the mapping rules. As a result, requests to origin servers
- not listed in the mapping rules are not served.
- (`*``proxy.config.url_remap.remap_required``* <configuration-files/records.config#proxy.config.url_remap.remap_required>`_)
+ not listed in the mapping rules are not served. (:ts:cv:`proxy.config.url_remap.remap_required`)
- Specify an alternate URL to which incoming requests from older
clients (i.e., ones that do not provide ``Host`` headers) are
- directed
- (`*``proxy.config.header.parse.no_host_url_reedirect``* <configuration-files/records.config#proxy.config.header.parse.no_host_url_redirect>`_)
+ directed (:ts:cv:`proxy.config.header.parse.no_host_url_redirect`)
Don't forget to run the command :option:`traffic_line -x` to apply the
configuration changes.
@@ -317,16 +303,16 @@ change for the current request only (by returning the HTTP status code
To set redirect rules
1. For each redirect you want to set enter a mapping rule in the
- ```remap.config`` <../configuration-files/remap.config>`_ file
+ :file:`remap.config` file
2. Run the command :option:`traffic_line -x` to apply the configuration
changes.
-**Example**
+Example
+-------
The following permanently redirects all HTTP requests for
-``www.server1.com`` to ``www.server2.com``:
+``www.server1.com`` to ``www.server2.com``: ::
-::
redirect http://www.server1.com http://www.server2.com
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a9ca0bbb/doc/reference/configuration/remap.config.en.rst
----------------------------------------------------------------------
diff --git a/doc/reference/configuration/remap.config.en.rst b/doc/reference/configuration/remap.config.en.rst
index 188f32b..ad274be 100644
--- a/doc/reference/configuration/remap.config.en.rst
+++ b/doc/reference/configuration/remap.config.en.rst
@@ -37,8 +37,7 @@ uses to perform the following actions:
- Redirect HTTP requests permanently or temporarily without Traffic
Server having to contact any origin servers
-Refer to `Reverse Proxy and HTTP
-Redirects <../reverse-proxy-http-redirects>`_, for information about
+Refer to :ref:`reverse-proxy-and-http-redirects`, for information about
redirecting HTTP requests and using reverse proxy.
After you modify the :file:`remap.config` run the
@@ -49,12 +48,16 @@ the changes to all other nodes in the cluster.
Format
======
-Each line in the :file:`remap.config` file must contain a mapping rule.
+Each line in the :file:`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.
+``target``, and ``replacement``. The following list describes the format of each field.
+
+.. _remap-config-format-type:
-*``type``* {#type}
+``type``
Enter one of the following:
- ``map`` --translates an incoming request URL to the appropriate
@@ -73,26 +76,28 @@ of each field.
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).
+ .. note: use the ``regex_`` prefix to indicate that the line has a regular expression (regex).
-*``target``* {#target}
- Enter the origin ("from") URL. You can enter up to four components:
+.. _remap-config-format-target:
- ::
+``target``
+ Enter the origin ("from") URL. You can enter up to four components: ::
scheme://host:port/path_prefix
- where *``scheme``* is ``http``.
+ where ``scheme`` is ``http``.
-*``replacement``* {#replacement}
- Enter the origin ("from") URL. You can enter up to four components:
+.. _remap-config-format-replacement:
- ::
+``replacement``
+ Enter the origin ("from") URL. You can enter up to four components: ::
scheme://host:port/path_prefix
- where *``scheme``* can be ``http`` or ``https``.
+ where ``scheme`` can be ``http`` or ``https``.
+
+
+.. _remap-config-precedence:
Precedence
==========
@@ -106,35 +111,31 @@ priority
4. ``regex_redirect`` and ``regex_redirect_temporary``
Examples
-========
+--------
The following section shows example mapping rules in the
:file:`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:
-
-::
+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
----------------\|-------------------
-``http://www.x.com/Widgets/index.html`` \|
-``http://server.hoster.com/Widgets/index.html``
-``http://www.x.com/cgi/form/submit.sh?arg=true`` \|
-``http://server.hoster.com/cgi/form/submit.sh?arg=true``
+================================================ ========================================================
+Client Request Translated Request
+================================================ ========================================================
+``http://www.x.com/Widgets/index.html`` ``http://server.hoster.com/Widgets/index.html``
+``http://www.x.com/cgi/form/submit.sh?arg=true`` ``http://server.hoster.com/cgi/form/submit.sh?arg=true``
+================================================ ========================================================
The following example shows a map rule with path prefixes specified in
-the target:
-
-::
+the target: ::
map http://www.y.com/marketing/ http://marketing.y.com/
reverse_map http://marketing.y.com/ http://www.y.com/marketing/
@@ -147,18 +148,15 @@ the target:
These rules result in the following translations:
-Client Request \| Translated Request
----------------\|-------------------
-``http://www.y.com/marketing/projects/manhattan/specs.html`` \|
-``http://marketing.y.com/projects/manhattan/specs.html``
-``http://www.y.com/stuff/marketing/projects/boston/specs.html`` \|
-``http://info.y.com/marketing/projects/boston/specs.html``
-``http://www.y.com/engineering/marketing/requirements.html`` \|
-``http://engineering.y.com/marketing/requirements.html``
+=============================================================== ==========================================================
+Client Request Translated Request
+=============================================================== ==========================================================
+``http://www.y.com/marketing/projects/manhattan/specs.html`` ``http://marketing.y.com/projects/manhattan/specs.html``
+``http://www.y.com/stuff/marketing/projects/boston/specs.html`` ``http://info.y.com/marketing/projects/boston/specs.html``
+``http://www.y.com/engineering/marketing/requirements.html`` ``http://engineering.y.com/marketing/requirements.html``
+=============================================================== ==========================================================
-The following example shows that the order of the rules matters:
-
-::
+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/
@@ -167,9 +165,11 @@ The following example shows that the order of the rules matters:
These rules result in the following translation.
-Client Request \| Translated Request
----------------\|------------------- ``http://www.g.com/stuff/a.gif`` \|
-``http://external.g.com/stuff/a.gif``
+================================ =====================================
+Client Request Translated Request
+================================ =====================================
+``http://www.g.com/stuff/a.gif`` ``http://external.g.com/stuff/a.gif``
+================================ =====================================
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
@@ -184,11 +184,12 @@ the target and replacement::
This rule results in the following translation.
-Client Request \| Translated Request
----------------\|-------------------
-``http://www.h.com/a/b/c/d/doc.html`` \|
-``http://server.h.com/customers/x/y/c/d/doc.html``
-``http://www.h.com/a/index.html`` \| ``Translation fails``
+===================================== ==================================================
+Client Request Translated Request
+===================================== ==================================================
+``http://www.h.com/a/b/c/d/doc.html`` ``http://server.h.com/customers/x/y/c/d/doc.html``
+``http://www.h.com/a/index.html`` ``Translation fails``
+===================================== ==================================================
The following example shows reverse-map rules::
@@ -197,41 +198,41 @@ The following example shows reverse-map rules::
These rules result in the following translations.
-Client Request \| Translated Request
----------------\|------------------- ``http://www.x.com/Widgets`` \|
-``http://server.hoster.com/x/Widgets`` \|
+================================ =====================================
+Client Request Translated Request
+================================ =====================================
+``http://www.x.com/Widgets`` ``http://server.hoster.com/x/Widgets``
+================================ =====================================
-Client Request \| Origin server Header \| Translated Header
----------------\|----------------------\|-------------------
-``http://www.x.com/Widgets`` \| ``http://server.hoster.com/x/Widgets/``
-\| ``http://www.x.com/Widgets/``
+================================ ======================================= =============================
+Client Request Origin Server Header Translated Request
+================================ ======================================= =============================
+``http://www.x.com/Widgets`` ``http://server.hoster.com/x/Widgets/`` ``http://www.x.com/Widgets/``
+================================ ======================================= =============================
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
-:file:`records.config` file to the URL to which Traffic Server will redirect
+``Host:`` header. As a solution, set the variable :ts:cv:`proxy.config.header.parse.no_host_url_redirect`
+in the :file:`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``:
-
-::
+``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``:
-
-::
+``www.company1.com`` to ``www.company2.com``: ::
redirect_temporary http://www.company1.com/ http://www.company2.com/
+.. _remap-config-regex:
+
Regular Expression (regex) Remap Support
========================================
@@ -247,8 +248,7 @@ limitations below:
- The number of substitutions in the expansion string is limited to 10.
- There is no ``regex_`` equivalent to ``reverse_remap``, so when using
``regex_remap`` you should make sure the reverse path is clear by
- setting
- (`*``proxy.config.url_remap.pristine_host_hdr``* <../configuration-files/records.config#proxy.config.url_remap.pristine_host_hdr>`_)
+ setting (:ts:cv:`proxy.config.url_remap.pristine_host_hdr`)
Examples
--------
@@ -258,6 +258,8 @@ 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
+.. _remap-config-plugin-chaining:
+
Plugin Chaining
===============
@@ -276,6 +278,8 @@ 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
+.. _remap-config-named-filters:
+
Named Filters
=============