http://git-wip-us.apache.org/repos/asf/trafficserver/blob/9fbd4201/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 683e423..73ebcd2 100644 --- a/doc/admin/reverse-proxy-http-redirects.en.rst +++ b/doc/admin/reverse-proxy-http-redirects.en.rst @@ -1,4 +1,3 @@ - .. _reverse-proxy-and-http-redirects: Reverse Proxy and HTTP Redirects @@ -6,21 +5,20 @@ Reverse Proxy and HTTP Redirects .. Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file - distributed with this work for additional information - regarding copyright ownership. The ASF licenses this file - to you under the Apache License, Version 2.0 (the - "License"); you may not use this file except in compliance - with the License. You may obtain a copy of the License at - + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, - software distributed under the License is distributed on an - "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - KIND, either express or implied. See the License for the - specific language governing permissions and limitations - under the License. + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. Reverse Proxy and HTTP Redirects ================================ @@ -32,19 +30,17 @@ appears to clients like a normal origin server. .. toctree:: :maxdepth: 2 - 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 -**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 -is trying to connect to. In a typical scenario the advertised hostname -of the origin server resolves to Traffic Server, which acts as the real -origin server. +With *forward proxy caching*, Traffic Server handles web requests to origin +servers on behalf of the clients requesting the content. *Reverse proxy +caching* (also known as *server acceleration*) 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 behave outwardly as origin server +which the client is trying to connect to. In a typical scenario the advertised +hostname of the origin server resolves to Traffic Server, which serves client +requests directly, fetching content from the true origin server when necessary. Reverse Proxy Solutions ----------------------- @@ -52,20 +48,19 @@ Reverse Proxy Solutions There are many ways to use Traffic Server as a reverse proxy. Below are a few example scenarios. -You can use Traffic Server in reverse proxy mode to: +- Offload heavily-used origin servers. -- Offload heavily-used origin servers -- Deliver content efficiently in geographically distant areas -- Provide security for origin servers that contain sensitive - information +- Deliver content efficiently in geographically distant areas. + +- Provide security for origin servers that contain sensitive information. Offloading Heavily-Used Origin Servers ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Traffic Server can absorb requests to the main origin server and improve -the speed & quality of web serving by reducing load and hot spots on +Traffic Server can accept requests on behalf of the origin server and improve +the speed and quality of web serving by reducing load and hot spots on backup origin servers. For example, a web hoster can maintain a scalable -Traffic Server serving engine with a set of low-cost, low-performance, +Traffic Server system with a set of low-cost, low-performance, less-reliable PC origin servers as backup servers. In fact, a single Traffic Server can act as the virtual origin server for multiple backup origin servers, as shown in the figure below. @@ -85,8 +80,8 @@ geographical proximity. Caches are typically easier to manage and are more cost-effective than replicating data. For example, Traffic Server can be used as a mirror site on the far side of a trans-Atlantic link to serve users without having to fetch the request and content across -expensive international connections. Unlike replication, for which -hardware must be configured to replicate all data and to handle peak +expensive, or higher latency, international connections. Unlike replication, +for which hardware must be configured to replicate all data and to handle peak capacity, Traffic Server dynamically adjusts to optimally use the serving and storing capacity of the hardware. Traffic Server is also designed to keep content fresh automatically, thereby eliminating the @@ -100,7 +95,7 @@ an origin server. If an origin server contains sensitive information that you want to keep secure inside your firewall, then you can use a Traffic Server outside the firewall as a reverse proxy for that origin server. When outside clients try to access the origin server, the -requests instead go to Traffic Server. If the desired content is *not* +requests instead go to Traffic Server. If the desired content is not sensitive, then it can be served from the cache. If the content is sensitive and not cacheable, then Traffic Server obtains the content from the origin server (the firewall allows only Traffic Server access @@ -114,12 +109,15 @@ When a browser makes a request, it normally sends that request directly to the origin server. When Traffic Server is in reverse proxy mode, it intercepts the request before it reaches the origin server. Typically, 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 +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`_. -.. 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 ================== @@ -136,25 +134,39 @@ proxy mode serves an HTTP request from a client browser. The figure above demonstrates the following steps: +.. List below should remain manually numbered, as the entries correspond to numbers in the figure above. + 1. A client browser sends an HTTP request addressed to a host called ``www.host.com`` on port 80. Traffic Server receives the request because it is acting as the origin server (the origin serverâs advertised hostname resolves to Traffic Server). -2. Traffic Server locates a map rule in the ``remap.config`` file and + +2. Traffic Server locates a map rule in the :file:`remap.config` file and remaps the request to the specified origin server (``realhost.com``). -3. Traffic Server opens an HTTP connection to the origin server. (If the request is not able to be served from cache) -4. If the request is a cache hit and the content is fresh, then Traffic - Server sends the requested object to the client from the cache. - Otherwise, Traffic Server obtains the requested object from the - origin server, sends the object to the client, and saves a copy in - its cache. + +3. If the request cannot be served from cache, Traffic Server opens a + connection to the origin server (or more likely, uses an existing + connection it has pre-established), retrieves the content, and optionally + caches it for future use. + +4. If the request was a cache hit and the content is still fresh in the cache, + or the content is now available through Traffic Server because of step 3, + Traffic Server sends the requested object to the client from the cache + directly. + +.. note:: + + Traffic Server, when updating its own cache from the origin server, will + simultaneously deliver that content to the client while updating its + cache database. The response to the client containing the requested object + will begin as soon as Traffic Server has received and processed the full + response headers from the origin server. To configure HTTP reverse proxy, you must perform the following tasks: - Create mapping rules in the :file:`remap.config` file (refer to `Creating Mapping Rules for HTTP Requests`_). :: - # remap.config map http://www.host.com http://realhost.com - Enable the reverse proxy option (refer to `Enabling HTTP Reverse Proxy`_). @@ -167,10 +179,10 @@ Handling Origin Server Redirect Responses Origin servers often send redirect responses back to browsers redirecting them to different pages. For example, if an origin server is overloaded, then it might redirect browsers to a less loaded server. -Origin servers also redirect when web pages that have moved to different +Origin servers also redirect when web pages have moved to different locations. When Traffic Server is configured as a reverse proxy, it must readdress redirects from origin servers so that browsers are redirected -to Traffic Server and *not* to another origin server. +to Traffic Server and not to another origin server. To readdress redirects, Traffic Server uses reverse-map rules. Unless you have :ts:cv:`proxy.config.url_remap.pristine_host_hdr` enabled @@ -186,23 +198,25 @@ Traffic Server uses two types of mapping rules for HTTP reverse proxy. map rule ~~~~~~~~ -A **map rule** translates the URL in client requests into the URL where +A *map rule* translates the URL in client requests into the URL where 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 :file:`remap.config` file. -For the request URL to match a target URL, the following -conditions must be true: +URLs in :file:`remap.config`. For the request URL to match a target URL, the +following conditions must be true: + +- The scheme of both URLs must be the same. -- The scheme of both URLs must be the same - The host in both URLs must be the same. If the request URL contains an unqualified hostname, then it will never match a target URL with a fully-qualified hostname. + - The ports in both URLs must be the same. If no port is specified in a URL, then the default port for the scheme of the URL is used. + - The path portion of the target URL must match a prefix of the request - URL path + URL path. If Traffic Server finds a match, then it translates the request URL into the replacement URL listed in the map rule: it sets the host and path of @@ -210,18 +224,18 @@ 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 :file:`remap.config` file. +Server applies the first mapping listed in :file:`remap.config`. reverse-map rule ~~~~~~~~~~~~~~~~ -A **reverse-map rule** translates the URL in origin server redirect -responses to point to Traffic Server so that clients are **redirected** +A *reverse-map rule* translates the URL in origin server redirect +responses to point to Traffic Server so that clients are redirected to Traffic Server instead of accessing an origin server directly. For example, if there is a directory ``/pub`` on an origin server at ``www.molasses.com`` and a client sends a request to that origin server for ``/pub``, then the origin server might reply with a redirect by -sending the Header ``Location: http://www.test.com/pub/`` to let the +sending the Header ``Location: http://realhost.com/pub/`` to let the client know that it was a directory it had requested, not a document (a common use of redirects is to normalize URLs so that clients can bookmark documents properly). @@ -233,35 +247,33 @@ hitting a wall because ``realhost.com`` actually does not resolve for the client. (E.g.: Because it's running on a port shielded by a firewall, or because it's running on a non-routable LAN IP) -Both map and reverse-map rules consist of a **target** (origin) URL and -a **replacement** (destination) URL. In a **map rule**, the target URL +Both map and reverse-map rules consist of a *target* (origin) URL and +a *replacement* (destination) URL. In a *map rule*, the target URL points to Traffic Server and the replacement URL specifies where the -original content is located. In a **reverse-map rule**, the target URL +original content is located. In a *reverse-map rule*, the target URL specifies where the original content is located and the replacement URL -points to Traffic Server. Traffic Server stores mapping rules in the -``remap.config`` file located in the Traffic Server ``config`` -directory. +points to Traffic Server. Traffic Server stores mapping rules in +:file:`remap.config` located in the Traffic Server ``config`` directory. Creating Mapping Rules for HTTP Requests ---------------------------------------- -To create mapping rules +To create mapping rules: + +#. Enter the map and reverse-map rules into :file:`remap.config`. -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. +#. Run the command :option:`traffic_line -x` to apply the configuration changes. Enabling HTTP Reverse Proxy --------------------------- -To enable HTTP reverse proxy, follow the steps below. +To enable HTTP reverse proxy: -1. Edit the following variable in :file:`records.config` +#. Edit :ts:cv:`proxy.config.reverse_proxy.enabled` in :file:`records.config`. :: - - :ts:cv:`proxy.config.reverse_proxy.enabled` + CONFIG proxy.config.reverse_proxy.enabled INT 1 -2. Run the command :option:`traffic_line -x` to apply the configuration - changes. +#. Run the command :option:`traffic_line -x` to apply the configuration changes. Setting Optional HTTP Reverse Proxy Options ------------------------------------------- @@ -270,17 +282,20 @@ Traffic Server provides several reverse proxy configuration options in :file:`records.config` that enable you to: - Configure Traffic Server to retain the client host header information - in a request during translation (:ts:cv:`proxy.config.url_remap.pristine_host_hdr`) + in a request during translation. + See :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. (: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 (:ts:cv:`proxy.config.header.parse.no_host_url_redirect`) + not listed in the mapping rules are not served. + See :ts:cv:`proxy.config.url_remap.remap_required`. -Don't forget to run the command :option:`traffic_line -x` to apply the -configuration changes. +- Specify an alternate URL to which incoming requests from older clients ,such + as ones that do not provide ``Host`` headers, are directed. + See :ts:cv:`proxy.config.header.parse.no_host_url_redirect`. + +Run the command :option:`traffic_line -x` to apply any of these configuration +changes. Redirecting HTTP Requests ========================= @@ -293,18 +308,17 @@ requests for ``www.ultraseek.com`` go directly to ``www.server1.com/products/portal/search``. You can configure Traffic Server to perform permanent or temporary -redirects. **Permanent redirects** notify the browser of the URL change -(by returning the HTTP status code **``301``**) so that the browser can -update bookmarks. **Temporary redirects** notify the browser of the URL +redirects. *Permanent redirects* notify the browser of the URL change +(by returning the HTTP status code ``301``) so that the browser can +update bookmarks. *Temporary redirects* notify the browser of the URL change for the current request only (by returning the HTTP status code -**``307``** ). +``307`` ). + +To set redirect rules: -To set redirect rules +#. For each redirect you want to set enter a mapping rule in :file:`remap.config`. -1. For each redirect you want to set enter a mapping rule in the - :file:`remap.config` file -2. Run the command :option:`traffic_line -x` to apply the configuration - changes. +#. Run the command :option:`traffic_line -x` to apply the configuration changes. Example -------
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/9fbd4201/doc/admin/security-options.en.rst ---------------------------------------------------------------------- diff --git a/doc/admin/security-options.en.rst b/doc/admin/security-options.en.rst index 3806d4f..9fc612a 100644 --- a/doc/admin/security-options.en.rst +++ b/doc/admin/security-options.en.rst @@ -11,7 +11,7 @@ Security Options "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - http://www.apache.org/licenses/LICENSE-2.0 + http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an @@ -20,18 +20,17 @@ Security Options specific language governing permissions and limitations under the License. -Traffic Server provides a number of security features. - .. _controlling-client-access-to-cache: Controlling Client Access to the Proxy Cache ============================================ -You can configure Traffic Server to allow only certain clients to use -the proxy cache by editing a configuration file. +Traffic Server can be confgiured to allow only certain clients to use +the proxy cache. -#. Add a line in :file:`ip_allow.config` for each IP address or +#. Add a line to :file:`ip_allow.config` for each IP address or range of IP addresses allowed to access Traffic Server. + #. Run the command :option:`traffic_line -x` to apply the configuration changes. @@ -40,7 +39,7 @@ the proxy cache by editing a configuration file. Configuring DNS Server Selection (Split DNS) ============================================ -The **Split DNS** option enables you to configure Traffic Server to use +The *Split DNS* option enables you to configure Traffic Server to use multiple DNS servers, as dictated by your security requirements. For example, you might configure Traffic Server to use one set of DNS servers to resolve hostnames on your internal network, while allowing @@ -48,27 +47,25 @@ DNS servers outside the firewall to resolve hosts on the Internet. This maintains the security of your intranet, while continuing to provide direct access to sites outside your organization. -To configure Split DNS, you must do the following: +To configure Split DNS: -- Specify the rules for performing DNS server selection based on the - destination domain, the destination host, or a URL regular - expression. -- Enable the **Split DNS** option. +#. Specify the rules for performing DNS server selection based on the + destination domain, the destination host, or a URL regular expression. + These rules are located in :file:`splitdns.config`. -To do this, we +#. Enable the *Split DNS* option by adjusting :ts:cv:`proxy.config.dns.splitDNS.enabled` + in :file:`records.config`. :: -#. Add rules to :file:`splitdns.config`. -#. In :file:`records.config` set the variable - :ts:cv:`proxy.config.dns.splitDNS.enabled` to ``1`` to enable split DNS. -#. Run the command :option:`traffic_line -x` to apply the configuration - changes. + CONFIG proxy.config.dns.splitDNS.enabled INT 1 + +#. Run the command :option:`traffic_line -x` to apply the configuration changes. .. _configuring-ssl-termination: Using SSL Termination ===================== -The Traffic Server **SSL termination** option enables you to secure +The Traffic Server *SSL termination* option enables you to secure connections in reverse proxy mode between a client and a Traffic Server and/or Traffic Server and an origin server. @@ -76,22 +73,22 @@ The following sections describe how to enable and configure the SSL termination option. - Enable and configure SSL termination for client/Traffic Server - connections: :ref:`client-and-traffic-server-connections` + connections: :ref:`admin-client-and-traffic-server-connections` + - Enable and configure SSL termination for Traffic Server/origin server - connections: :ref:`traffic-server-and-origin-server-connections` -- Enable and configure SSL termination for both client/Traffic Server - and Traffic Server/origin server connections: :ref:`client-and-traffic-server-connections` - :ref:`traffic-server-and-origin-server-connections`, respectively. + connections: :ref:`admin-traffic-server-and-origin-server-connections` .. _client-and-traffic-server-connections: Client and Traffic Server Connections ------------------------------------- +.. XXX sanity check/second opinions on example paths used for certs/keys below + The figure below illustrates communication between a client and Traffic Server (and between Traffic Server and an origin server) when the SSL -termination option is enabled & configured for **client/Traffic -Server connections only**. +termination option is enabled and configured for Client/Traffic +Server connections only. .. figure:: ../static/images/admin/ssl_c.jpg :align: center @@ -99,64 +96,93 @@ Server connections only**. Client and Traffic Server communication using SSL termination +.. Manual list numbering below corresponds to figure markings above. + The figure above depicts the following: -#. The client sends an HTTPS request for content. Traffic Server receives the request and performs the SSL 'handshake' to authenticate the client (depending on the authentication options configured) and determine the encryption method that will be used. If the client is allowed access, then Traffic Server checks its cache for the requested content. +1. The client sends an HTTPS request for content. Traffic Server receives the + request and performs the SSL handshake to authenticate the client (depending + on the authentication options configured) and determine the encryption + method that will be used. If the client is allowed access, then Traffic + Server checks its cache for the requested content. -#. If the request is a cache hit and the content is fresh, then Traffic Server encrypts the content and sends it to the client. The client decrypts the content (using the method determined during the handshake) and displays it. +2. If the request is a cache hit and the content is fresh, then Traffic Server + encrypts the content and sends it to the client. The client decrypts the + content (using the method determined during the handshake) and displays it. -#. If the request is a cache miss or cached content is stale, then Traffic Server communicates with the origin server via HTTP and obtains a plain text version of the content. Traffic Server saves the plain text version of the content in its cache, encrypts the content, and sends it to the client. The client decrypts and displays the content. +3. If the request is a cache miss or cached content is stale, then Traffic + Server communicates with the origin server via HTTP and obtains a plain text + version of the content. Traffic Server saves the plain text version of the + content in its cache, encrypts the content, and sends it to the client. The + client decrypts and displays the content. To configure Traffic Server to use the SSL termination option for -client/Traffic Server connections, you must do the following: +Client/Traffic Server connections, you must do the following: -- Obtain and install an SSL server certificate from a recognized +#. Obtain and install an SSL server certificate from a recognized certificate authority. The SSL server certificate contains information that enables the client to authenticate Traffic Server and exchange encryption keys. -- Configure SSL termination options: - - - Set the port number used for SSL communication using :ts:cv:`proxy.config.http.server_ports`. - - Edit :file:`ssl_multicert.config` to specify the filename and location of the - SSL certificates and private keys. - - (Optional) Configure the use of client certificates: Client - certificates are located on the client. If you configure Traffic - Server to require client certificates, then Traffic Server - verifies the client certificate during the SSL handshake that - authenticates the client. If you configure Traffic Server to *not* - require client certificates, then access to Traffic Server is - managed through other Traffic Server options that have been set - (such as rules in :file:`ip_allow.config`). - - (Optional) Configure the use of Certification Authorities (CAs). - CAs add security by verifying the identity of the person - requesting a certificate. - -In order to accomplish this, we - -#. Edit the following variables in the :ref:`records-config-ssl-termination` section of - :file:`records.config` - - - :ts:cv:`proxy.config.http.server_ports` - - :ts:cv:`proxy.config.ssl.client.certification_level` - - :ts:cv:`proxy.config.ssl.server.cert.path` - - :ts:cv:`proxy.config.ssl.server.private_key.path` - - :ts:cv:`proxy.config.ssl.CA.cert.path` + +#. Set the port number used for SSL communication using + :ts:cv:`proxy.config.http.server_ports` in :file:`records.config`. + +#. Set the appropriate base path for your SSL certificates and private keys + in :file:`records.config`. :: + + CONFIG proxy.config.ssl.server.cert.path STRING "/opt/ts/etc/ssl/certs/" + CONFIG proxy.config.ssl.server.private_key.path STRING "/opt/ts/etc/ssl/keys/" + +#. Add an entry to :file:`ssl_multicert.config` for each certificate and key + which your Traffic Server system will be using to terminate SSL connections + with clients. :: + + ip_dest=1.2.3.4 ssl_cert_name=example.com.pem + ip_dest=* ssl_cert_name=default.pem + +#. *Optional*: Configure the use of client certificates using the variable + :ts:cv:`proxy.config.ssl.client.certification_level` in :file:`records.config`. + If you configure Traffic Server to require client certificates, then Traffic + Server verifies the client certificate during the SSL handshake that + authenticates the client. If you configure Traffic Server to not require + client certificates, or if you configure certificates to be optional and the + connecting client does not present one, then access to Traffic Server is + managed through other Traffic Server options that have been set (such as + rules in :file:`ip_allow.config`). :: + + CONFIG proxy.config.ssl.client.certification_level INT 0 + + This variable permits one of the following values to be set: + + ===== ======================================================================= + Value Description + ===== ======================================================================= + ``0`` Client certificates not required. + ``1`` Client certificates optional. If present, will be used to validate. + ``2`` Client certficates required, and must validate based on configured CAs. + ===== ======================================================================= + +#. *Optional*: Configure the use of Certification Authorities (CAs). CAs add + security by verifying the identity of the person requesting a certificate. + The list of acceptable CA signers is configured with + :ts:cv:`proxy.config.ssl.CA.cert.path` in :file:`records.config`. :: + + CONFIG proxy.config.ssl.CA.cert.path STRING "/opt/CA/certs/private-ca.pem" #. Run the command :option:`traffic_line -L` to restart Traffic Server on the local node or :option:`traffic_line -M` to restart Traffic Server on all the nodes in a cluster. - -.. This numbering is ridiculous. - .. _traffic-server-and-origin-server-connections: Traffic Server and Origin Server Connections -------------------------------------------- +.. XXX sanity check/second opinions on example paths used for certs/keys below + The figure below illustrates communication between Traffic Server and an -origin server when the SSL termination option is enabled for **Traffic -Server/origin server connections**. +origin server when the SSL termination option is enabled for Traffic +Server/origin server connections. .. figure:: ../static/images/admin/ssl_os.jpg :align: center @@ -164,65 +190,73 @@ Server/origin server connections**. Traffic Server and origin server communication using SSL termination +.. Manual list numbering below corresponds to figure markings above. + The figure above depicts the following: -**Step 1:** If a client request is a cache miss or is stale, then -Traffic Server sends an HTTPS request for the content to the origin -server. The origin server receives the request and performs the SSL -handshake to authenticate Traffic Server and determine the encryption -method to be used. +1. If a client request is a cache miss or is stale, then Traffic Server sends + an HTTPS request for the content to the origin server. The origin server + receives the request and performs the SSL handshake to authenticate Traffic + Server and determine the encryption method to be used. -**Step 2:** If Traffic Server is allowed access, then the origin server -encrypts the content and sends it to Traffic Server, where it is -decrypted (using the method determined during the handshake). A plain -text version of the content is saved in the cache. +2. If Traffic Server is allowed access, then the origin server encrypts the + content and sends it to Traffic Server, where it is decrypted (using the + method determined during the handshake). A plain text version of the content + is saved in the cache, if Traffic Server deems the content cacheable. -**Step 3:** If SSL termination is enabled for client /Traffic Server -connections, then Traffic Server re-encrypts the content and sends it to -the client via HTTPS, where it is decrypted and displayed. If SSL -termination is not enabled for client/Traffic Server connections, then -Traffic Server sends the plain text version of the content to the client -via HTTP. +3. If SSL termination is enabled for Client/Traffic Server connections, then + Traffic Server re-encrypts the content and sends it to the client via HTTPS, + where it is decrypted and displayed. If SSL termination is not enabled for + Client/Traffic Server connections, then Traffic Server sends the plain text + version of the content to the client via HTTP. -To configure Traffic Server to use the SSL termination option for -Traffic Server and origin server connections, you must do the following: - -- Obtain and install an SSL client certificate from a recognized - certificate authority. The SSL client certificate contains - information that allows the origin server to authenticate Traffic - Server (the client certificate is optional). -- Configure SSL termination options: -- Enable the SSL termination option. - - - Set the port number used for SSL communication. - - Specify the filename and location of the SSL client certificate - (if you choose to use a client certificate). - - Specify the filename and location of the Traffic Server private - key (if the private key is not located in the client certificate - file). Traffic Server uses its private key during the SSL - handshake to decrypt the session encryption keys. The private key - must be stored and protected against theft. - - Configure the use of CAs. CAs allow the Traffic Server that's - acting as a client to verify the identity of the server with which - it is communicating, thereby enabling exchange of encryption keys. - -In order to accomplish this, we: - -.. This numbering is ridiculous. I need to re-read this doc with a fresh mind and re(number|order) it. - -1. Edit the following variables in the :ref:`records-config-ssl-termination` section of - :file:`records.config`: - - - :ts:cv:`proxy.config.http.server_ports` - - :ts:cv:`proxy.config.ssl.client.verify.server` - - :ts:cv:`proxy.config.ssl.client.cert.filename` - - :ts:cv:`proxy.config.ssl.client.cert.path` - - :ts:cv:`proxy.config.ssl.client.private_key.filename` - - :ts:cv:`proxy.config.ssl.client.private_key.path` - - :ts:cv:`proxy.config.ssl.client.CA.cert.filename` - - :ts:cv:`proxy.config.ssl.client.CA.cert.path` - -2. Run the command :option:`traffic_line -L` to restart Traffic Server on the +To configure Traffic Server to use the SSL termination option for Traffic Server +and origin server connections, you must do the following: + +#. Ensure first that your origin server responds properly to SSL requests, and + configure it for client certificate validation if you intend to use that as + part of your access control scheme. + + Refer to your origin server's documentation for details. If your origin + server is another Traffic Server system, then you may follow the steps + outlined in `Client and Traffic Server Connections`_ for configuring the + origin server to validate client certificates. + +#. *Optional*: Obtain and install an SSL client certificate from a recognized + certificate authority, if your origin server requires client certificate + validation for access control. Your client certificate must be signed by a + Certificate Authority recognized by your origin server. + + If you are using a client certificate, you must add its location to + :file:`records.config` in the setting :ts:cv:`proxy.config.ssl.client.cert.path` + and :ts:cv:`proxy.config.ssl.client.cert.filename`. :: + + CONFIG proxy.config.ssl.client.cert.path STRING "/opt/ts/etc/ssl/certs/" + CONFIG proxy.config.ssl.client.cert.filename STRING "client.pem" + + You must also provide the paths to the private key for this certificate, + unless the key is contained within the same file as the certificate, using + :ts:cv:`proxy.config.ssl.client.private_key.path` and + :ts:cv:`proxy.config.ssl.client.private_key.filename`. :: + + CONFIG proxy.config.ssl.client.private_key.path STRING "/opt/ts/etc/ssl/keys/" + CONFIG proxy.config.ssl.client.private_key.filename STRING "client.pem" + +#. Enable or disable, per your security policy, server SSL certificate + verification using :ts:cv:`proxy.config.ssl.client.verify.server` in + :file:`records.config`. :: + + CONFIG proxy.config.ssl.client.verify.server INT 1 + +#. Add the collection of authorized Certificate Authorities to the Traffic + Server configuration in :file:`records.config` using the settings + :ts:cv:`proxy.config.ssl.client.CA.cert.path` and + :ts:cv:`proxy.config.ssl.client.CA.cert.filename`. :: + + CONFIG proxy.config.ssl.client.CA.cert.path STRING "/opt/ts/etc/ssl/certs/" + CONFIG proxy.config.ssl.client.CA.cert.filename STRING "CAs.pem" + +#. Run the command :option:`traffic_line -L` to restart Traffic Server on the local node or :option:`traffic_line -M` to restart Traffic Server on all the nodes in a cluster. http://git-wip-us.apache.org/repos/asf/trafficserver/blob/9fbd4201/doc/admin/session-protocol.en.rst ---------------------------------------------------------------------- diff --git a/doc/admin/session-protocol.en.rst b/doc/admin/session-protocol.en.rst index 84d7040..25d00b0 100644 --- a/doc/admin/session-protocol.en.rst +++ b/doc/admin/session-protocol.en.rst @@ -1,3 +1,8 @@ +.. _session-protocol: + +Session Protocol +**************** + .. Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information @@ -5,9 +10,9 @@ to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - + http://www.apache.org/licenses/LICENSE-2.0 - + Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY @@ -15,19 +20,15 @@ specific language governing permissions and limitations under the License. -.. _session-protocol: - -Session Protocol -**************** - -Traffic Server supports some session level protocols in place or on -top of HTTP. These can be provided by a plugin -(:ref:`see <new-protocol-plugins>`) or be one that is supported -directly by Traffic Server. Currently the -`SPDY <http://www.chromium.org/spdy>`_ protocol is the only one current -supported but it is planned to support HTTP 2 when that is finalized. +Traffic Server supports some session level protocols in place of, or on top of. + HTTP. These can be provided by a plugin (see :ref:`new-protocol-plugins`) or +be one that is supported directly by Traffic Server. The +`SPDY <http://www.chromium.org/spdy>`_ protocol is the only one currently +supported, but it is planned to support HTTP 2 when that is finalized. -Session protocols are specified by explicit names, based on the `NPN <https://technotes.googlecode.com/git/nextprotoneg.html>`_ names. The core supported names are +Session protocols are specified by explicit names, based on the +`NPN <https://technotes.googlecode.com/git/nextprotoneg.html>`_ names. The +core supported names are: * ``http/0.9`` * ``http/1.0`` @@ -38,18 +39,21 @@ Session protocols are specified by explicit names, based on the `NPN <https://te * ``spdy/3`` * ``spdy/3.1`` -The ``http/2`` value is currently not functional but included for future use. ``spdy/1`` and ``spdy/2`` are obsolete but are include for completeness. +The ``http/2`` value is not currently functional, but is included for future +use. Both ``spdy/1`` and ``spdy/2`` are obsolete, but are include for +completeness. -The session protocols supported on a proxy port are a subset of these values. For convenience some psuedo-values are defined in terms of these fundamental protocols. +The session protocols supported on a proxy port are a subset of these values. +For convenience some pseudo-values are defined in terms of these fundamental +protocols: * ``http`` means ``http/0.9``, ``http/1.0``, and ``http/1.1`` * ``spdy`` means ``spdy/3`` and ``spdy/3.1``. * ``http2`` means ``http/2`` -Each proxy port can be -configured in :ts:cv:`proxy.config.http.server_ports` to support a subset of -these session protocols. For TLS enabled connections this -configuration controls which protocols are offered by NPN. For non-TLS -proxy ports protocol sniffing is used to determine which protocol is -being used by the client. If the detected protocol is not supported -for that proxy port the connection is dropped. +Each proxy port can be configured in :ts:cv:`proxy.config.http.server_ports` +to support a subset of these session protocols. For TLS enabled connections this +configuration controls which protocols are offered by NPN. Protocol sniffing is +use for non-TLS proxy ports to determine which protocol is being used by the +client. If the detected protocol is not supported for that proxy port the +connection is dropped. http://git-wip-us.apache.org/repos/asf/trafficserver/blob/9fbd4201/doc/admin/traffic-server-error-messages.en.rst ---------------------------------------------------------------------- diff --git a/doc/admin/traffic-server-error-messages.en.rst b/doc/admin/traffic-server-error-messages.en.rst index 01586c2..d26b85e 100644 --- a/doc/admin/traffic-server-error-messages.en.rst +++ b/doc/admin/traffic-server-error-messages.en.rst @@ -34,7 +34,7 @@ Traffic Server Process Fatal ============================ ``Accept port is not between 1 and 65535. Please check configuration`` - The port specified in the :file:`records.config` file that accepts + The port specified in :file:`records.config` that accepts incoming HTTP requests is not valid. ``Self loop is detected in parent proxy configuration`` @@ -66,7 +66,7 @@ Traffic Server Warnings ``Log format symbol <symbol name> not found`` Custom log format references a field symbol that does not exist. - Refer to :ref:`event-logging-formats`. + Refer to :ref:`admin-event-logging-formats`. ``Missing field for field marker`` Error reading a log buffer. @@ -84,7 +84,7 @@ Traffic Server Warnings replaced. ``No cache disks specified in storage.config file: cache disabled`` - The Traffic Server ``storage.config`` file does not list any cache + The Traffic Server :file:`storage.config` file does not list any cache disks; Traffic Server is running in proxy-only mode. You must add the disks you want to use for the cache to :file:`storage.config`. @@ -143,9 +143,9 @@ Traffic Server returns detailed error messages to browser clients when there are problems with the HTTP transactions requested by the browser. These Traffic Server response messages correspond to standard HTTP response codes, but provide more information. A list of the more -frequently-encountered HTTP response codes is provided in :ref:`standard-http-response-messages`. -You can customize the Traffic Server response messages (typically in -proxy/config/body_factory/default/, but set by +frequently encountered HTTP response codes is provided in :ref:`standard-http-response-messages`. +You can customize the Traffic Server response messages (typically in +``proxy/config/body_factory/default/``, but set by :ts:cv:`proxy.config.body_factory.template_sets_dir`). The following table lists the hard-coded Traffic Server HTTP messages, @@ -311,63 +311,30 @@ Standard HTTP Response Messages The following standard HTTP response messages are provided for your information. -``200`` - OK - -``202`` - Accepted - -``204`` - No Content - -``206`` - Partial Content - -``300`` - Multiple Choices - -``301`` - Moved Permanently - -``302`` - Found - -``303`` - See Other - -``304`` - Not Modified - -``400`` - Bad Request - -``401`` - Unauthorized; retry - -``403`` - Forbidden - -``404`` - Not Found - -``405`` - Method Not Allowed - -``406`` - Not acceptable - -``408`` - Request Timeout - -``500`` - Internal server error - -``501`` - Not Implemented - -``502`` - Bad Gateway - -``504`` - Gateway Timeout - +======== =================================== +Code Description +======== =================================== +``200`` OK +``202`` Accepted +``204`` No Content +``206`` Partial Content +``300`` Multiple Choices +``301`` Moved Permanently +``302`` Found +``303`` See Other +``304`` Not Modified +``400`` Bad Request +``401`` Unauthorized; retry +``403`` Forbidden +``404`` Not Found +``405`` Method Not Allowed +``406`` Not Acceptable +``408`` Request Timeout +``500`` Internal Server Error +``501`` Not Implemented +``502`` Bad Gateway +``504`` Gateway Timeout +======== =================================== + +More detail can be found in `RFC2616 <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html>`_ +which defines the full range of standardized HTTP/1.1 response codes. http://git-wip-us.apache.org/repos/asf/trafficserver/blob/9fbd4201/doc/admin/transparent-proxy.en.rst ---------------------------------------------------------------------- diff --git a/doc/admin/transparent-proxy.en.rst b/doc/admin/transparent-proxy.en.rst index 2a2eb5c..74ae56f 100644 --- a/doc/admin/transparent-proxy.en.rst +++ b/doc/admin/transparent-proxy.en.rst @@ -5,21 +5,20 @@ Transparent Proxying .. Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file - distributed with this work for additional information - regarding copyright ownership. The ASF licenses this file - to you under the Apache License, Version 2.0 (the - "License"); you may not use this file except in compliance - with the License. You may obtain a copy of the License at - + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, - software distributed under the License is distributed on an - "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY - KIND, either express or implied. See the License for the - specific language governing permissions and limitations - under the License. + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. .. toctree:: :maxdepth: 2 @@ -32,8 +31,8 @@ Transparent Proxying Transparent Proxying is the ability of a proxy (such as ATS) to intercept connections between clients and servers without being visible. -The general network structure that will be used in this documentation -looks like this -- +The general network structure that will be used in this documentation is +shown in the following figure. .. figure:: ../static/images/admin/ats-basic-traffic.png :align: center @@ -41,16 +40,16 @@ looks like this -- ATS basic traffic flow of Transparent Proxy -There must be a gateway device through which passes all network traffic +There must be a gateway device through which all network traffic passes from the client to the Internet (or external cloud). The gateway is responsible for effectively splicing ATS in to selected streams of that -traffic. Each traffic stream is split in to two, with ATS terminating +traffic. Each traffic stream is split in two, with ATS terminating both sides. That is, stream green-1, red-2, is split in to the green connection and the red connection. Note that ATS may or may not be on the gateway system, the redirected traffic can flow over other network infrastructure. -Because ATS uses two connections transparency can be set independently +Because ATS uses two connections, transparency can be set independently on the client and origin server (Internet / external cloud) side. We will define what is generally called "transparent proxy" as two aspects, *inbound transparency* and *outbound transparency*. @@ -62,31 +61,37 @@ proxy that is transparent to connections that are outbound from the proxy, i.e. a connection initiated by the proxy to an origin server (red-2). -In most treatments these two types of transparency are treated as -unitarily but that is not required. This implementation supports -transparency independently on the two (client, origin server) sides -(`use cases <half-transparency-use-cases>`_. +In most situations these two types of transparency are combined, but that is +not required. Traffic Server supports transparency independently on the two +sides. `Half-Transparency Use Cases <half-transparency-use-cases>`_ provides +additional detail. + +.. important:: -It is critical to note that any transparency requires specialized -routing and cannot be done solely by configuring ATS. ATS transparency -also requires support from the Linux kernel and therefore currently only -works on sufficiently recent Linux kernels that support the following -features -- + It is critical to note that any transparency requires specialized + routing and cannot be done solely by configuring ATS. ATS transparency + also requires support from the Linux kernel and therefore currently only + works on sufficiently recent Linux kernels that support the following + features: -- TPROXY -- POSIX capabilities + - TPROXY + - POSIX capabilities -In addition the specialized routing will require using ``iptables`` and -in some cases ``ebtables``. + In addition the specialized routing will require using ``iptables`` and + in some cases ``ebtables``. Standard build procedures should work for transparency support but if not consult these :ref:`more detailed instructions <building-ats-for-transparency>` -Transparency is configured per server port not globally. This is done +Transparency is configured per server port, not globally. This is done via the configuration values :ts:cv:`proxy.config.http.server_ports`. In addition, :ts:cv:`proxy.config.reverse_proxy.enabled` must be enabled if the client side is transparent. That should be fixed in a future patch. +.. XXX has that been fixed? + +.. XXX revisit section below + In the first case use the attribute character (replacing the default 'X')
