You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by jp...@apache.org on 2015/11/03 07:10:08 UTC
[32/51] trafficserver git commit: Documentation reorganization
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/admin/hierachical-caching.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/hierachical-caching.en.rst b/doc/admin/hierachical-caching.en.rst
deleted file mode 100644
index 3f71394..0000000
--- a/doc/admin/hierachical-caching.en.rst
+++ /dev/null
@@ -1,219 +0,0 @@
-.. _hierarchical-caching:
-
-Hierarchical Caching
-********************
-
-.. 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
-
- 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.
-
-.. toctree::
- :maxdepth: 2
-
-Understanding Cache Hierarchies
-===============================
-
-A cache hierarchy consists of cache levels that communicate with each
-other. Traffic Server supports several types of cache hierarchies. All
-cache hierarchies recognize the concept of *parent* and *child*. A
-parent cache is a cache higher up in the hierarchy, to which Traffic
-Server can forward requests. A child cache is a cache for which Traffic
-Server is a parent.
-
-Traffic Server supports the following hierarchical caching options:
-
-Parent Caching
-==============
-
-If a Traffic Server node cannot find a requested object in its cache,
-then it searches a parent cache (which itself can search other caches)
-before finally retrieving the object from the origin server. You can
-configure a Traffic Server node to use multiple parent caches so that
-if one parent is unavailable, the other parent caches will be checked in turn
-until either the request is serviced properly or no further parent caches are
-available and the origin server is contacted. This is called `Parent Failover`_.
-Traffic Server supports parent caching for both HTTP and HTTPS requests.
-
-If you do not want all requests to go to the parent cache, then simply configure
-Traffic Server to route certain requests (such as requests containing specific
-URLs) directly to the origin server. This may be achieved by setting parent
-proxy rules in :file:`parent.config`.
-
-The figure below illustrates a simple cache hierarchy with a Traffic
-Server node configured to use a parent cache. In the following scenario,
-a client sends a request to a Traffic Server node that is a child in the
-cache hierarchy (because it's configured to forward missed requests to a
-parent cache). The request is a cache miss, so Traffic Server then
-forwards the request to the parent cache where it is a cache hit. The
-parent sends a copy of the content to the Traffic Server, where it is
-cached and then served to the client. Future requests for this content
-can now be served directly from the Traffic Server cache (until the data
-is stale or expired).
-
-.. figure:: ../static/images/admin/cachehrc.jpg
- :align: center
- :alt: Parent caching
-
- Parent caching
-
-If the request is a cache miss on the parent, then the parent retrieves the
-content from the origin server (or from another cache, depending on the parent’s
-configuration). The parent caches the content and then sends a copy to Traffic
-Server (its child), where it is cached and served to the client.
-
-Interaction with Remap.config
------------------------------
-
-If remap rules are required (:ts:cv:`proxy.config.reverse_proxy.enabled`),
-when a request comes in to a child node, its :file:`remap.config` is evaluated before
-parent selection. This means that the client request is translated according to the
-remap rule, and therefore, any parent selection should be made against the remapped
-host name. This is true regardless of pristine host headers
-(:ts:cv:`proxy.config.url_remap.pristine_host_hdr`) being enabled or not. The parent node
-will receive the translated request (and thus needs to be configured to accept it).
-
-
-Example
-~~~~~~~
-The client makes a request to Traffic Server for http://example.com. The origin server
-for the request is http://origin.example.com; the parent node is ``parent1.example.com``,
-and the child node is configured as a reverse proxy.
-
-If the child's :file:`remap.config` contains
-
-``map http://example.com http://origin.example.com``
-
-with the child's :file:`parent.config` containing
-
-``dest_domain=origin.example.com method=get parent="parent1.example.com:80`` )
-
-and parent cache (parent1.example.com) would need to have a :file:`remap.config`
-line similar to
-
-``map http://origin.example.com http://origin.example.com``
-
-With this example, if parent1.example.com is down, the child node would automatically
-directly contact the ``origin.example.com`` on a cache miss.
-
-
-Parent Failover
----------------
-
-Traffic Server supports use of several parent caches. This ensures that
-if one parent cache is not available, another parent cache can service
-client requests.
-
-When you configure your Traffic Server to use more than one parent
-cache, Traffic Server detects when a parent is not available and sends
-missed requests to another parent cache. If you specify more than two
-parent caches, then the order in which the parent caches are queried
-depends upon the parent proxy rules configured in the :file:`parent.config`
-configuration file. By default, the parent caches are queried in the
-order they are listed in the configuration file.
-
-.. _configuring-traffic-server-to-use-a-parent-cache:
-
-Configuring Traffic Server to Use a Parent Cache
-------------------------------------------------
-
-To configure Traffic Server to use one or more parent caches, you must perform
-the configuration adjustments detailed below.
-
-.. note::
-
- You need to configure the child cache only. Assuming the parent nodes are
- configured to serve the child's origin server, no additional configuration is
- needed for the nodes acting as Traffic Server parent caches.
-
-#. Enable the parent caching option by adjusting
- :ts:cv:`proxy.config.http.parent_proxy_routing_enable` in
- :file:`records.config`. ::
-
- CONFIG proxy.config.http.parent_proxy_routing_enable INT 1
-
-#. Identify the parent cache you want to use to service missed requests. To
- use parent failover, you must identify more than one parent cache so that
- when a parent cache is unavailable, requests are sent to another parent
- cache.
-
-#. Edit :file:`parent.config` to set parent proxy rules which will specify the
- parent cache to which you want missed requests to be forwarded.
-
-The following example configures Traffic Server to route all requests
-containing the regular expression ``politics`` and the path
-``/viewpoint`` directly to the origin server (bypassing any parent
-hierarchies): ::
-
- url_regex=politics prefix=/viewpoint go_direct=true
-
-The following example configures Traffic Server to direct all missed
-requests with URLs beginning with ``http://host1`` to the parent cache
-``parent1``. If ``parent1`` cannot serve the requests, then requests are
-forwarded to ``parent2``. Because ``round-robin=true``, Traffic Server
-goes through the parent cache list in a round-robin based on client IP
-address.::
-
- dest_host=host1 scheme=http parent="parent1;parent2" round-robin=strict
-
-Run the command :option:`traffic_ctl config reload` to apply the configuration changes.
-
-.. _admin-icp-peering:
-
-ICP Peering
-===========
-
-The Internet Cache Protocol (ICP) is used by proxy caches to exchange information
-about their content. ICP query messages ask other caches if they are storing
-a particular URL; ICP response messages reply with a hit or miss answer. A
-cache exchanges ICP messages only with specific ICP peers, which are neighboring
-caches that can receive ICP messages. An ICP peer can be a sibling cache
-(which is at the same level in the hierarchy) or a parent cache (which
-is one level up in the hierarchy).
-
-If Traffic Server has ICP caching enabled, then it sends ICP queries to its
-ICP peers when the HTTP request is a cache miss. If there are no hits but parents
-exist, then a parent is selected using a round-robin policy. If no ICP parents
-exist, then Traffic Server forwards the request to its HTTP parents. If there
-are no HTTP parent caches established, then Traffic Server forwards the request
-to the origin server.
-
-If Traffic Server receives a hit message from an ICP peer, then Traffic Server
-sends the HTTP request to that peer. However, it might turn out to be a cache
-miss because the original HTTP request contains header information that is
-not communicated by the ICP query. For example, the hit might not be the requested
-alternate. If an ICP hit turns out to be a miss, then Traffic Server forwards
-the request to either its HTTP parent caches or to the origin server.
-
-To configure a Traffic Server node to be part of an ICP cache hierarchy, you
-must perform the following tasks:
-
-* Determine if the Traffic Server can receive ICP messages only, or if it can send *and* receive ICP messages.
-* Determine if Traffic Server can send messages directly to each ICP peer or send a single message on a specified multicast channel.
-* Specify the port used for ICP messages.
-* Set the ICP query timeout.
-* Identify the ICP peers (siblings and parents) with which Traffic Server can communicate.
-
-To configure Traffic Server to use an ICP cache hierarchy edit the following variables in :file:`records.config` file:
-
-* :ts:cv:`proxy.config.icp.enabled`
-* :ts:cv:`proxy.config.icp.icp_port`
-* :ts:cv:`proxy.config.icp.multicast_enabled`
-* :ts:cv:`proxy.config.icp.query_timeout`
-
-Edit :file:`icp.config` file located in the Traffic Server `config` directory:
-For each ICP peer you want to identify, enter a separate rule in the :file:`icp.config` file.
-
-Run the command :option:`traffic_ctl config reload` to apply the configuration changes.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/admin/http-proxy-caching.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/http-proxy-caching.en.rst b/doc/admin/http-proxy-caching.en.rst
deleted file mode 100644
index e95694b..0000000
--- a/doc/admin/http-proxy-caching.en.rst
+++ /dev/null
@@ -1,902 +0,0 @@
-.. _http-proxy-caching:
-
-HTTP Proxy Caching
-******************
-
-.. 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
-
- 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.
-
-HTTP proxy caching enables you to store copies of frequently-accessed web
-objects (such as documents, images, and articles) and then serve this
-information to users on demand. It improves performance and frees up
-Internet bandwidth for other tasks.
-
-.. toctree::
- :maxdepth: 2
-
-Understanding HTTP Web Proxy Caching
-====================================
-
-Internet users direct their requests to web servers all over the
-Internet. A caching server must act as a *web proxy server* so it can
-serve those requests. After a web proxy server receives requests for web
-objects, it either serves the requests or forwards them to the *origin
-server* (the web server that contains the original copy of the
-requested information). The Traffic Server proxy supports *explicit
-proxy caching*, in which the user's client software must be configured
-to send requests directly to the Traffic Server proxy. The following
-overview illustrates how Traffic Server serves a request.
-
-#. Traffic Server receives a client request for a web object.
-
-#. Using the object address, Traffic Server tries to locate the
- requested object in its object database (*cache*).
-
-#. If the object is in the cache, then Traffic Server checks to see if
- the object is fresh enough to serve. If it is fresh, then Traffic
- Server serves it to the client as a *cache hit* (see the figure
- below).
-
- .. figure:: ../static/images/admin/cache_hit.jpg
- :align: center
- :alt: A cache hit
-
- A cache hit
-
-#. If the data in the cache is stale, then Traffic Server connects to
- the origin server and checks if the object is still fresh (a
- :term:`revalidation`). If it is, then Traffic Server immediately sends
- the cached copy to the client.
-
-#. If the object is not in the cache (a *cache miss*) or if the server
- indicates the cached copy is no longer valid, then Traffic Server
- obtains the object from the origin server. The object is then
- simultaneously streamed to the client and the Traffic Server local
- cache (see the figure below). Subsequent requests for the object can
- be served faster because the object is retrieved directly from cache.
-
- .. figure:: ../static/images/admin/cache_miss.jpg
- :align: center
- :alt: A cache miss
-
- A cache miss
-
-Caching is typically more complex than the preceding overview suggests.
-In particular, the overview does not discuss how Traffic Server ensures
-freshness, serves correct HTTP alternates, and treats requests for
-objects that cannot or should not be cached. The following sections discuss
-these issues in greater detail.
-
-.. _ensuring-cached-object-freshness:
-
-Ensuring Cached Object Freshness
-================================
-
-When Traffic Server receives a request for a web object, it first tries
-to locate the requested object in its cache. If the object is in cache,
-then Traffic Server checks to see if the object is fresh enough to
-serve. For HTTP objects, Traffic Server supports optional
-author-specified expiration dates. Traffic Server adheres to these
-expiration dates; otherwise, it picks an expiration date based on how
-frequently the object is changing and on administrator-chosen freshness
-guidelines. Objects can also be revalidated by checking with the origin
-server to see if an object is still fresh.
-
-HTTP Object Freshness
----------------------
-
-Traffic Server determines whether an HTTP object in the cache is fresh
-by checking the following conditions in order:
-
-- **Checking the** ``Expires`` **or** ``max-age`` **header**
-
- Some HTTP objects contain ``Expires`` headers or ``max-age`` headers
- that explicitly define how long the object can be cached. Traffic
- Server compares the current time with the expiration time to
- determine if the object is still fresh.
-
-- **Checking the** ``Last-Modified`` **/** ``Date`` **header**
-
- If an HTTP object has no ``Expires`` header or ``max-age`` header,
- then Traffic Server can calculate a freshness limit using the
- following formula::
-
- freshness_limit = ( date - last_modified ) * 0.10
-
- where *date* is the date in the object's server response header
- and *last_modified* is the date in the ``Last-Modified`` header.
- If there is no ``Last-Modified`` header, then Traffic Server uses the
- date the object was written to cache. The value ``0.10`` (10 percent)
- can be increased or reduced to better suit your needs. Refer to
- `Modifying Aging Factor for Freshness Computations`_.
-
- The computed freshness limit is bound by a minimum and maximum value.
- Refer to `Setting Absolute Freshness Limits`_ for more information.
-
-- **Checking the absolute freshness limit**
-
- For HTTP objects that do not have ``Expires`` headers or do not have
- both ``Last-Modified`` and ``Date`` headers, Traffic Server uses a
- maximum and minimum freshness limit. Refer to
- `Setting Absolute Freshness Limits`_.
-
-- **Checking revalidate rules in** :file:`cache.config`
-
- Revalidate rules apply freshness limits to specific HTTP objects. You
- can set freshness limits for objects originating from particular
- domains or IP addresses, objects with URLs that contain specified
- regular expressions, objects requested by particular clients, and so
- on. Refer to :file:`cache.config`.
-
-Modifying Aging Factor for Freshness Computations
--------------------------------------------------
-
-If an object does not contain any expiration information, then Traffic
-Server can estimate its freshness from the ``Last-Modified`` and
-``Date`` headers. By default, Traffic Server stores an object for 10% of
-the time that elapsed since it last changed. You can increase or reduce
-the percentage according to your needs.
-
-To modify the aging factor for freshness computations:
-
-#. Change the value for :ts:cv:`proxy.config.http.cache.heuristic_lm_factor`.
-
-#. Run the :option:`traffic_ctl config reload` command to apply the configuration changes.
-
-Setting Absolute Freshness Limits
----------------------------------
-
-Some objects do not have ``Expires`` headers or do not have both
-``Last-Modified`` and ``Date`` headers. To control how long these
-objects are considered fresh in the cache, specify an *absolute
-freshness limit*.
-
-To specify an absolute freshness limit:
-
-#. Edit the variables :ts:cv:`proxy.config.http.cache.heuristic_min_lifetime`
- and :ts:cv:`proxy.config.http.cache.heuristic_max_lifetime` in
- :file:`records.config`.
-
-#. Run the :option:`traffic_ctl config reload` command to apply the configuration changes.
-
-Specifying Header Requirements
-------------------------------
-
-To further ensure freshness of the objects in the cache, configure
-Traffic Server to cache only objects with specific headers. By default,
-Traffic Server caches all objects (including objects with no headers);
-you should change the default setting only for specialized proxy
-situations. If you configure Traffic Server to cache only HTTP objects
-with ``Expires`` or ``max-age`` headers, then the cache hit rate will be
-noticeably reduced (since very few objects will have explicit expiration
-information).
-
-To configure Traffic Server to cache objects with specific headers:
-
-#. Change the value for :ts:cv:`proxy.config.http.cache.required_headers`
- in :file:`records.config`.
-
-#. Run the :option:`traffic_ctl config reload` command to apply the configuration changes.
-
-Cache-Control Headers
----------------------
-
-Even though an object might be fresh in the cache, clients or servers
-often impose their own constraints that preclude retrieval of the object
-from the cache. For example, a client might request that a object not
-be retrieved from a cache, or if it does allow cache retrieval, then it
-cannot have been cached for more than 10 minutes.
-
-Traffic Server bases the servability of a cached object on ``Cache-Control``
-headers that appear in both client requests and server responses. The following
-``Cache-Control`` headers affect whether objects are served from cache:
-
-- The ``no-cache`` header, sent by clients, tells Traffic Server that
- it should not serve any objects directly from the cache. When present in a
- client request, Traffic Server will always obtain the object from the
- origin server. You can configure Traffic Server to ignore client
- ``no-cache`` headers. Refer to `Configuring Traffic Server to Ignore Client no-cache Headers`_
- for more information.
-
-- The ``max-age`` header, sent by servers, is compared to the object
- age. If the age is less than ``max-age``, then the object is fresh
- and can be served from the Traffic Server cache.
-
-- The ``min-fresh`` header, sent by clients, is an *acceptable
- freshness tolerance*. This means that the client wants the object to
- be at least this fresh. Unless a cached object remains fresh at least
- this long in the future, it is revalidated.
-
-- The ``max-stale`` header, sent by clients, permits Traffic Server to
- serve stale objects provided they are not too old. Some browsers
- might be willing to take slightly stale objects in exchange for
- improved performance, especially during periods of poor Internet
- availability.
-
-Traffic Server applies ``Cache-Control`` servability criteria after HTTP
-freshness criteria. For example, an object might be considered fresh but will
-not be served if its age is greater than its ``max-age``.
-
-Revalidating HTTP Objects
--------------------------
-
-When a client requests an HTTP object that is stale in the cache,
-Traffic Server revalidates the object. A *revalidation* is a query to
-the origin server to check if the object is unchanged. The result of a
-revalidation is one of the following:
-
-- If the object is still fresh, then Traffic Server resets its
- freshness limit and serves the object.
-
-- If a new copy of the object is available, then Traffic Server caches
- the new object (thereby replacing the stale copy) and simultaneously
- serves the object to the client.
-
-- If the object no longer exists on the origin server, then Traffic
- Server does not serve the cached copy.
-
-- If the origin server does not respond to the revalidation query, then
- Traffic Server serves the stale object along with a
- ``111 Revalidation Failed`` warning.
-
-By default, Traffic Server revalidates a requested HTTP object in the
-cache if it considers the object to be stale. Traffic Server evaluates
-object freshness as described in `HTTP Object Freshness`_.
-You can reconfigure how Traffic Server evaluates freshness by selecting
-one of the following options:
-
-*Traffic Server considers all HTTP objects in the cache to be stale:*
- Always revalidate HTTP objects in the cache with the origin server.
-
-*Traffic Server considers all HTTP objects in the cache to be fresh:*
- Never revalidate HTTP objects in the cache with the origin server.
-
-*Traffic Server considers all HTTP objects without* ``Expires`` *or* ``Cache-control`` *headers to be stale:*
- Revalidate all HTTP objects without ``Expires`` or ``Cache-Control`` headers.
-
-To configure how Traffic Server revalidates objects in the cache, you
-can set specific revalidation rules in :file:`cache.config`.
-
-To configure revalidation options
-
-#. Edit the variable :ts:cv:`proxy.config.http.cache.when_to_revalidate`
- in :file:`records.config`.
-
-#. Run the :option:`traffic_ctl config reload` command to apply the configuration changes.
-
-.. _pushing-content-into-the-cache:
-
-Pushing Content into the Cache
-==============================
-
-Traffic Server supports the HTTP ``PUSH`` method of content delivery.
-Using HTTP ``PUSH``, you can deliver content directly into the cache
-without client requests.
-
-Configuring Traffic Server for PUSH Requests
---------------------------------------------
-
-Before you can deliver content into your cache using HTTP ``PUSH``, you
-must configure Traffic Server to accept ``PUSH`` requests.
-
-#. Edit :file:`ip_allow.config` to allow ``PUSH`` from the appropriate addresses.
-
-#. Update :ts:cv:`proxy.config.http.push_method_enabled` in
- :file:`records.config`::
-
- CONFIG proxy.config.http.push_method_enabled INT 1
-
-#. Run the command :option:`traffic_ctl config reload` to apply the configuration changes.
-
-Understanding HTTP PUSH
------------------------
-
-``PUSH`` uses the HTTP 1.1 message format. The body of a ``PUSH``
-request contains the response header and response body that you want to
-place in the cache. The following is an example of a ``PUSH`` request::
-
- PUSH http://www.company.com HTTP/1.0
- Content-length: 84
-
- HTTP/1.0 200 OK
- Content-type: text/html
- Content-length: 17
-
- <HTML>
- a
- </HTML>
-
-.. important::
-
- Your ``PUSH`` headers must include ``Content-length``, the value for which
- must include both headers and body byte counts. The value is not optional,
- and an improper (too large or too small) value will result in undesirable
- behavior.
-
-Tools that will help manage pushing
------------------------------------
-
-Traffic Server comes with a Perl script for pushing, :program:`tspush`,
-which can assist with understanding how to write scripts for pushing
-content yourself.
-
-Pinning Content in the Cache
-============================
-
-The *Cache Pinning Option* configures Traffic Server to keep certain
-HTTP objects in the cache for a specified time. You can use this option
-to ensure that the most popular objects are in cache when needed and to
-prevent Traffic Server from deleting important objects. Traffic Server
-observes ``Cache-Control`` headers and pins an object in the cache only
-if it is indeed cacheable.
-
-To set cache pinning rules:
-
-#. Enable :ts:cv:`proxy.config.cache.permit.pinning` in :file:`records.config`::
-
- CONFIG proxy.config.cache.permit.pinning INT 1
-
-#. Add a rule in :file:`cache.config` for each URL you want Traffic Server to
- pin in the cache. For example::
-
- url_regex=^https?://(www.)?apache.org/dev/ pin-in-cache=12h
-
-#. Run the command :option:`traffic_ctl config reload` to apply the configuration changes.
-
-Caching HTTP Objects
-====================
-
-When Traffic Server receives a request for a web object that is not in
-the cache, it retrieves the object from the origin server and serves it
-to the client. At the same time, Traffic Server checks if the object is
-cacheable before storing it in its cache to serve future requests.
-
-Traffic Server responds to caching directives from clients and origin
-servers, as well as directives you specify through configuration options
-and files.
-
-Client Directives
------------------
-
-By default, Traffic Server does not cache objects with the following
-request headers:
-
-- ``Authorization``
-
-- ``Cache-Control: no-store``
-
-- ``Cache-Control: no-cache``
-
- To configure Traffic Server to ignore this request header, refer to
- `Configuring Traffic Server to Ignore Client no-cache Headers`_.
-
-- ``Cookie`` (for text objects)
-
- By default, Traffic Server caches objects served in response to
- requests that contain cookies (unless the object is text). You can
- configure Traffic Server to not cache cookied content of any type,
- cache all cookied content, or cache cookied content that is of image
- type only. For more information, refer to `Caching Cookied Objects`_.
-
-Configuring Traffic Server to Ignore Client no-cache Headers
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-By default, Traffic Server strictly observes client
-``Cache-Control: no-cache`` directives. If a requested object contains a
-``no-cache`` header, then Traffic Server forwards the request to the
-origin server even if it has a fresh copy in cache. You can configure
-Traffic Server to ignore client ``no-cache`` directives such that it
-ignores ``no-cache`` headers from client requests and serves the object
-from its cache.
-
-#. Edit :ts:cv:`proxy.config.http.cache.ignore_client_no_cache` in
- :file:`records.config`. ::
-
- CONFIG proxy.config.http.cache.ignore_client_no_cache INT 1
-
-#. Run the command :option:`traffic_ctl config reload` to apply the configuration changes.
-
-Origin Server Directives
-------------------------
-
-By default, Traffic Server does not cache objects with the following response
-headers:
-
-- ``Cache-Control: no-store``
-
-- ``Cache-Control: private``
-
-- ``WWW-Authenticate``
-
- To configure Traffic Server to ignore ``WWW-Authenticate`` headers,
- refer to `Configuring Traffic Server to Ignore WWW-Authenticate Headers`_.
-
-- ``Set-Cookie``
-
-- ``Cache-Control: no-cache``
-
- To configure Traffic Server to ignore ``no-cache`` headers, refer to
- `Configuring Traffic Server to Ignore Server no-cache Headers`_.
-
-- ``Expires`` header with a value of 0 (zero) or a past date.
-
-Configuring Traffic Server to Ignore Server no-cache Headers
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-By default, Traffic Server strictly observes ``Cache-Control: no-cache``
-directives. A response from an origin server with a ``no-cache`` header
-is not stored in the cache and any previous copy of the object in the
-cache is removed. If you configure Traffic Server to ignore ``no-cache``
-headers, then Traffic Server also ignores ``no-store`` headers. The
-default behavior of observing ``no-cache`` directives is appropriate
-in most cases.
-
-To configure Traffic Server to ignore server ``no-cache`` headers:
-
-#. Edit :ts:cv:`proxy.config.http.cache.ignore_server_no_cache` in
- :file:`records.config`. ::
-
- CONFIG proxy.config.http.cache.ignore_server_no_cache INT 1
-
-#. Run the command :option:`traffic_ctl config reload` to apply the configuration changes.
-
-Configuring Traffic Server to Ignore WWW-Authenticate Headers
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-By default, Traffic Server does not cache objects that contain
-``WWW-Authenticate`` response headers. The ``WWW-Authenticate`` header
-contains authentication parameters the client uses when preparing the
-authentication challenge response to an origin server.
-
-When you configure Traffic Server to ignore origin server
-``WWW-Authenticate`` headers, all objects with ``WWW-Authenticate``
-headers are stored in the cache for future requests. However, the
-default behavior of not caching objects with ``WWW-Authenticate``
-headers is appropriate in most cases. Only configure Traffic Server to
-ignore server ``WWW-Authenticate`` headers if you are knowledgeable
-about HTTP 1.1.
-
-To configure Traffic Server to ignore server ``WWW-Authenticate``
-headers:
-
-#. Edit :ts:cv:`proxy.config.http.cache.ignore_authentication` in
- :file:`records.config`. ::
-
- CONFIG proxy.config.http.cache.ignore_authentication INT 1
-
-#. Run the command :option:`traffic_ctl config reload` to apply the configuration changes.
-
-Configuration Directives
-------------------------
-
-In addition to client and origin server directives, Traffic Server
-responds to directives you specify through configuration options and
-files.
-
-You can configure Traffic Server to do the following:
-
-- Not cache any HTTP objects. Refer to `Disabling HTTP Object Caching`_.
-
-- Cache *dynamic content*. That is, objects with URLs that end in ``.asp`` or
- contain a question mark (``?``), semicolon (``;``), or ``cgi``. For more
- information, refer to `Caching Dynamic Content`_.
-
-- Cache objects served in response to the ``Cookie:`` header. Refer to
- `Caching Cookied Objects`_.
-
-- Observe ``never-cache`` rules in :file:`cache.config`.
-
-Disabling HTTP Object Caching
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-By default, Traffic Server caches all HTTP objects except those for
-which you have set ``never-cache`` as :ref:`action rules <cache-config-format-action>`
-in :file:`cache.config`. You can disable HTTP object caching so that all HTTP
-objects are served directly from the origin server and never cached, as
-detailed below.
-
-To disable HTTP object caching manually:
-
-#. Set :ts:cv:`proxy.config.http.enabled` to ``0`` in :file:`records.config`. ::
-
- CONFIG proxy.config.http.enabled INT 0
-
-#. Run the command :option:`traffic_ctl config reload` to apply the configuration changes.
-
-Caching Dynamic Content
-~~~~~~~~~~~~~~~~~~~~~~~
-
-A URL is considered dynamic if it ends in ``.asp`` or contains a
-question mark (``?``), a semicolon (``;``), or ``cgi``. By
-default, Traffic Server caches dynamic content. You can configure the
-system to ignore dynamic looking content, although this is recommended
-only if the content is truly dynamic, but fails to advertise so with
-appropriate ``Cache-Control`` headers.
-
-To configure Traffic Server's cache behaviour in regard to dynamic
-content:
-
-#. Edit :ts:cv:`proxy.config.http.cache.cache_urls_that_look_dynamic` in
- :file:`records.config`. To disable caching, set the variable to ``0``,
- and to explicitly permit caching use ``1``. ::
-
- CONFIG proxy.config.http.cache.cache_urls_that_look_dynamic INT 0
-
-#. Run the command :option:`traffic_ctl config reload` to apply the configuration changes.
-
-Caching Cookied Objects
-~~~~~~~~~~~~~~~~~~~~~~~
-
-.. XXX This should be extended to xml as well!
-
-By default, Traffic Server caches objects served in response to requests
-that contain cookies. This is true for all types of objects except for
-text. Traffic Server does not cache cookied text content because object
-headers are stored along with the object, and personalized cookie header
-values could be saved with the object. With non-text objects, it is
-unlikely that personalized headers are delivered or used.
-
-You can reconfigure Traffic Server to:
-
-- Not cache cookied content of any type.
-
-- Cache cookied content that is of image type only.
-
-- Cache all cookied content regardless of type.
-
-To configure how Traffic Server caches cookied content:
-
-#. Edit :ts:cv:`proxy.config.http.cache.cache_responses_to_cookies` in
- :file:`records.config`.
-
-#. Run the command :option:`traffic_ctl config reload` to apply the configuration changes.
-
-Forcing Object Caching
-======================
-
-You can force Traffic Server to cache specific URLs (including dynamic
-URLs) for a specified duration, regardless of ``Cache-Control`` response
-headers.
-
-To force document caching:
-
-#. Add a rule for each URL you want Traffic Server to pin to the cache
- :file:`cache.config`::
-
- url_regex=^https?://(www.)?apache.org/dev/ ttl-in-cache=6h
-
-#. Run the command :option:`traffic_ctl config reload` to apply the configuration changes.
-
-Caching HTTP Alternates
-=======================
-
-Some origin servers answer requests to the same URL with a variety of
-objects. The content of these objects can vary widely, according to
-whether a server delivers content for different languages, targets
-different browsers with different presentation styles, or provides
-different document formats (HTML, XML). Different versions of the same
-object are termed *alternates* and are cached by Traffic Server based
-on ``Vary`` response headers. You can specify additional request and
-response headers for specific ``Content-Type`` values that Traffic Server
-will identify as alternates for caching. You can also limit the number
-of alternate versions of an object allowed in the cache.
-
-Configuring How Traffic Server Caches Alternates
-------------------------------------------------
-
-To configure how Traffic Server caches alternates:
-
-#. Edit the following variables in :file:`records.config`:
-
- - :ts:cv:`proxy.config.http.cache.enable_default_vary_headers`
- - :ts:cv:`proxy.config.http.cache.vary_default_text`
- - :ts:cv:`proxy.config.http.cache.vary_default_images`
- - :ts:cv:`proxy.config.http.cache.vary_default_other`
-
-#. Run the command :option:`traffic_ctl config reload` to apply the configuration changes.
-
-.. note::
-
- If you specify ``Cookie`` as the header field on which to vary
- in the above variables, make sure that the variable
- :ts:cv:`proxy.config.http.cache.cache_responses_to_cookies`
- is set appropriately.
-
-Limiting the Number of Alternates for an Object
------------------------------------------------
-
-You can limit the number of alternates Traffic Server can cache per
-object (the default is 3).
-
-.. important::
-
- Large numbers of alternates can affect Traffic Server
- cache performance because all alternates have the same URL. Although
- Traffic Server can look up the URL in the index very quickly, it must
- scan sequentially through available alternates in the object store.
-
-To alter the limit on the number of alternates:
-
-#. Edit :ts:cv:`proxy.config.cache.limits.http.max_alts` in :file:`records.config`. ::
-
- CONFIG proxy.config.cache.limits.http.max_alts INT 5
-
-#. Run the command :option:`traffic_ctl config reload` to apply the configuration changes.
-
-.. _using-congestion-control:
-
-Using Congestion Control
-========================
-
-The *Congestion Control* option enables you to configure Traffic
-Server to stop forwarding HTTP requests to origin servers when they
-become congested. Traffic Server then sends the client a message to
-retry the congested origin server later.
-
-To enable this option:
-
-#. Set :ts:cv:`proxy.config.http.congestion_control.enabled` to ``1`` in
- :file:`records.config`. ::
-
- CONFIG proxy.config.http.congestion_control.enabled INT 1
-
-#. Create rules in :file:`congestion.config` to specify:
-
- - Which origin servers Traffic Server tracks for congestion.
-
- - The timeouts Traffic Server uses, depending on whether a server is
- congested.
-
- - The page Traffic Server sends to the client when a server becomes
- congested.
-
- - Whether Traffic Server tracks the origin servers by IP address or by
- hostname.
-
-#. Run the command :option:`traffic_ctl config reload` to apply the configuration changes.
-
-.. _transaction-buffering-control:
-
-Using Transaction Buffering Control
-===================================
-
-By default, I/O operations are run at full speed, as fast as either Traffic
-Server, the network, or the cache can support. This can be problematic for
-large objects if the client side connection is significantly slower. In such
-cases the content will be buffered in ram while waiting to be sent to the
-client. This could potentially also happen for ``POST`` requests if the client
-connection is fast and the origin server connection slow. If very large objects
-are being used this can cause the memory usage of Traffic Server to become
-`very large <https://issues.apache.org/jira/browse/TS-1496>`_.
-
-This problem can be ameloriated by controlling the amount of buffer space used
-by a transaction. A high water and low water mark are set in terms of bytes
-used by the transaction. If the buffer space in use exceeds the high water
-mark, the connection is throttled to prevent additional external data from
-arriving. Internal operations continue to proceed at full speed until the
-buffer space in use drops below the low water mark and external data I/O is
-re-enabled.
-
-Although this is intended primarily to limit the memory usage of Traffic Server
-it can also serve as a crude rate limiter by setting a buffer limit and then
-throttling the client side connection either externally or via a transform.
-This will cause the connection to the origin server to be limited to roughly
-the client side connection speed.
-
-Traffic Server does network I/O in large chunks (32K or so) and therefore the
-granularity of transaction buffering control is limited to a similar precision.
-
-The buffer size calculations include all elements in the transaction, including
-any buffers associated with :ref:`transform plugins <transform-plugin>`.
-
-Transaction buffering control can be enabled globally by using configuration
-variables or by :c:func:`TSHttpTxnConfigIntSet` in a plugin.
-
-================= ================================================== ================================================
-Value Variable :c:func:`TSHttpTxnConfigIntSet` key
-================= ================================================== ================================================
-Enable buffering :ts:cv:`proxy.config.http.flow_control.enabled` :c:data:`TS_CONFIG_HTTP_FLOW_CONTROL_ENABLED`
-Set high water :ts:cv:`proxy.config.http.flow_control.high_water` :c:data:`TS_CONFIG_HTTP_FLOW_CONTROL_HIGH_WATER`
-Set low water :ts:cv:`proxy.config.http.flow_control.low_water` :c:data:`TS_CONFIG_HTTP_FLOW_CONTROL_LOW_WATER`
-================= ================================================== ================================================
-
-Be careful to always have the low water mark equal or less than the high water
-mark. If you set only one, the other will be set to the same value.
-
-If using :c:func:`TSHttpTxnConfigIntSet`, it must be called no later than
-:c:data:`TS_HTTP_READ_RESPONSE_HDR_HOOK`.
-
-.. _reducing-origin-server-requests:
-
-Reducing Origin Server Requests (Avoiding the Thundering Herd)
-==============================================================
-
-When an object can not be served from cache, the request will be proxied to the
-origin server. For a popular object, this can result in many near simultaneous
-requests to the origin server, potentially overwhelming it or associated
-resources. There are several features in Traffic Server that can be used to
-avoid this scenario.
-
-Read While Writer
------------------
-
-When Traffic Server goes to fetch something from origin, and upon receiving
-the response, any number of clients can be allowed to start serving the
-partially filled cache object once background_fill_completed_threshold % of the
-object has been received.
-
-While some other HTTP proxies permit clients to begin reading the response
-immediately upon the proxy receiving data from the origin server, ATS does not
-begin allowing clients to read until after the complete HTTP response headers
-have been read and processed. This is a side-effect of ATS making no
-distinction between a cache refresh and a cold cache, which prevents knowing
-whether a response is going to be cacheable.
-
-As non-cacheable responses from an origin server are generally due to that
-content being unique to different client requests, ATS will not enable
-read-while-writer functionality until it has determined that it will be able
-to cache the object.
-
-The following settings must be made in :file:`records.config` to enable
-read-while-writer functionality in ATS::
-
- CONFIG proxy.config.cache.enable_read_while_writer INT 1
- CONFIG proxy.config.http.background_fill_active_timeout INT 0
- CONFIG proxy.config.http.background_fill_completed_threshold FLOAT 0.000000
- CONFIG proxy.config.cache.max_doc_size INT 0
-
-All four configurations are required, for the following reasons:
-
-- :ts:cv:`proxy.config.cache.enable_read_while_writer` being set to ``1`` turns
- the feature on, as it is off (``0``) by default.
-
-.. _background_fill:
-
-- The background fill feature (both
- :ts:cv:`proxy.config.http.background_fill_active_timeout` and
- :ts:cv:`proxy.config.http.background_fill_completed_threshold`) should be
- allowed to kick in for every possible request. This is necessary in the event
- the writer (the first client session to request the object, which triggered
- ATS to contact the origin server) goes away. Another client session needs to
- take over the writer.
-
- As such, you should set the background fill timeouts and threshold to zero;
- this assures they never time out and are always allowed to kick in.
-
-- The :ts:cv:`proxy.config.cache.max_doc_size` should be unlimited (set to 0),
- since the object size may be unknown, and going over this limit would cause
- a disconnect on the objects being served.
-
-Once these are enabled, you have something that is very close, but not quite
-the same, to Squid's Collapsed Forwarding.
-
-In addition to the above settings, the settings :ts:cv:`proxy.config.cache.read_while_writer.max_retries`
-and :ts:cv:`proxy.config.cache.read_while_writer_retry.delay` allow to control the number
-of retries TS attempts to trigger read-while-writer until the download of first fragment
-of the object is completed::
-
- CONFIG proxy.config.cache.read_while_writer.max_retries INT 10
-
- CONFIG proxy.config.cache.read_while_writer_retry.delay INT 50
-
-.. _fuzzy-revalidation:
-
-Fuzzy Revalidation
-------------------
-
-Traffic Server can be set to attempt to revalidate an object before it becomes
-stale in cache. :file:`records.config` contains the settings::
-
- CONFIG proxy.config.http.cache.fuzz.time INT 240
- CONFIG proxy.config.http.cache.fuzz.min_time INT 0
- CONFIG proxy.config.http.cache.fuzz.probability FLOAT 0.005
-
-For every request for an object that occurs
-:ts:cv:`proxy.config.http.cache.fuzz.time` before (in the example above, 240
-seconds) the object is set to become stale, there is a small
-chance (:ts:cv:`proxy.config.http.cache.fuzz.probability` == 0.5%) that the
-request will trigger a revalidation request to the origin.
-
-.. note::
-
- When revalidation occurs, the requested object is no longer available to be
- served from cache. Subsequent requests for that object will be proxied to
- the origin.
-
-For objects getting a few requests per second, these settings would offer a
-fairly low probability of revalidating the cached object before it becomes
-stale. This feature is not typically necessary at those rates, though, since
-odds are only one or a small number of connections would hit origin upon the
-objects going stale.
-
-Once request raise rise, the same ``fuzz.probability`` leads to a greater
-chance the object may be revalidated before becoming stale. This can prevent
-multiple clients simultaneously triggering contact with the origin server
-under higher loads, as they would do if no fuzziness was employed for
-revalidations.
-
-These settings are also overridable by remap rules and via plugins, so can be
-adjusted per request if necessary.
-
-Finally, :ts:cv:`proxy.config.http.cache.fuzz.min_time` allows for
-different time periods to evaluate the probability of revalidation for small
-TTLs and large TTLs. Objects with small TTLs will start "rolling the
-revalidation dice" near the ``fuzz.min_time``, while objects with large TTLs
-would start at ``fuzz.time``.
-
-A logarithmic like function between determines the revalidation evaluation
-start time (which will be between ``fuzz.min_time`` and ``fuzz.time``). As the
-object gets closer to expiring, the window start becomes more likely. By
-default this setting is not enabled, but should be enabled anytime you have
-objects with small TTLs. Note that this option predates overridable
-configurations, so you can achieve something similar with a plugin or
-:file:`remap.config` settings.
-
-These configuration options are similar to Squid's refresh_stale_hit
-configuration option.
-
-Open Read Retry Timeout
------------------------
-
-The open read retry configurations attempt to reduce the number of concurrent
-requests to the origin for a given object. While an object is being fetched
-from the origin server, subsequent requests would wait
-:ts:cv:`proxy.config.http.cache.open_read_retry_time` milliseconds before
-checking if the object can be served from cache. If the object is still being
-fetched, the subsequent requests will retry
-:ts:cv:`proxy.config.http.cache.max_open_read_retries` times. Thus, subsequent
-requests may wait a total of (``max_open_read_retries`` x ``open_read_retry_time``)
-milliseconds before establishing an origin connection of its own. For instance,
-if they are set to ``5`` and ``10`` respectively, connections will wait up to
-50ms for a response to come back from origin from a previous request, until
-this request is allowed through.
-
-.. important::
-
- These settings are inappropriate when objects are uncacheable. In those
- cases, requests for an object effectively become serialized. The subsequent
- requests would await at least ``open_read_retry_time`` milliseconds before
- being proxied to the origin.
-
-It is advisable that this setting be used in conjunction with `Read While Writer`_
-for big (those that take longer than (``max_open_read_retries`` x
-``open_read_retry_time``) milliseconds to transfer) cacheable objects. Without
-the read-while-writer settings enabled, while the initial fetch is ongoing, not
-only would subsequent requests be delayed by the maximum time, but also, those
-requests would result in unnecessary requests to the origin server.
-
-Since ATS now supports setting these settings per-request or remap rule, you
-can configure this to be suitable for your setup much more easily.
-
-The configurations are (with defaults)::
-
- CONFIG proxy.config.http.cache.max_open_read_retries INT -1
- CONFIG proxy.config.http.cache.open_read_retry_time INT 10
-
-The defaults are such that the feature is disabled and every connection is
-allowed to go to origin without artificial delay. When enabled, you will try
-``max_open_read_retries`` times, each with an ``open_read_retry_time`` timeout.
-
-Open Write Fail Action
-----------------------
-
-In addition to the open read retry settings TS supports a new setting
-:ts:cv:`proxy.config.http.cache.open_write_fail_action` that allows to further
-reduce multiple concurrent requests hitting the origin for the same object by
-either returning a stale copy, in case of hit-stale or an error in case of cache
-miss for all but one of the requests.
-
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/admin/index.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/index.en.rst b/doc/admin/index.en.rst
deleted file mode 100644
index 44d87f9..0000000
--- a/doc/admin/index.en.rst
+++ /dev/null
@@ -1,325 +0,0 @@
-.. _admin-guide:
-
-Administrators' Guide
-**********************
-
-.. 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
-
- 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.
-
-Apache Traffic Server™ speeds Internet access, enhances website
-performance, and delivers unprecedented web hosting capabilities.
-
-Table of Contents:
-
-.. toctree::
- :maxdepth: 2
-
- getting-started.en
- http-proxy-caching.en
- reverse-proxy-http-redirects.en
- forward-proxy.en
- transparent-proxy.en
- explicit-proxy-caching.en
- session-protocol.en
- hierachical-caching.en
- configuring-cache.en
- monitoring-traffic.en
- configuring-traffic-server.en
- cluster-howto.en
- security-options.en
- working-log-files.en
- event-logging-formats.en
- traffic-server-error-messages.en
- performance-tuning.en
- faqs.en
-
-What Is Apache Traffic Server?
-==============================
-
-Global data networking has become part of everyday life: Internet users
-request billions of documents and petabytes of data, on a daily basis,
-to and from all parts of the world. Information is free, abundant, and
-accessible. Unfortunately, global data networking can also be a
-nightmare for IT professionals as they struggle with overloaded servers
-and congested networks. It can be challenging to consistently and
-reliably accommodate society’s growing data demands.
-
-Traffic Server is a high-performance web proxy cache that improves
-network efficiency and performance by caching frequently-accessed
-information at the edge of the network. This brings content physically
-closer to end users, while enabling faster delivery and reduced
-bandwidth use. Traffic Server is designed to improve content delivery
-for enterprises, Internet service providers (ISPs), backbone providers,
-and large intranets by maximizing existing and available bandwidth.
-
-Traffic Server Deployment Options
-=================================
-
-To best suit your needs, Traffic Server can be deployed in several ways:
-
-- As a web proxy cache
-- As a reverse proxy
-- In a cache hierarchy
-
-The following sections provide a summary of these Traffic Server
-deployment options. Please keep in mind that with every one of these options
-Traffic Server can be run as a *single instance*, or as a *multi-node cluster*.
-
-Traffic Server as a Web Proxy Cache
------------------------------------
-
-As a web proxy cache, Traffic Server receives user requests for web
-content as those requests travel to the destined web server (origin
-server). If Traffic Server contains the requested content, then it
-serves the content directly. If the requested content is not available
-from cache, then Traffic Server acts as a proxy: it obtains the content
-from the origin server on the user’s behalf and also keeps a copy to
-satisfy future requests.
-
-Traffic Server provides explicit proxy caching, in which the user’s
-client software must be configured to send requests directly to Traffic
-Server. Explicit proxy caching is described in the :ref:`explicit-proxy-caching`
-chapter.
-
-Traffic Server can also be employed as a transparent caching proxy server, in
-which the client software needs no special configuration or even knowledge of
-the proxy's existence. This setup is described in the :ref:`transparent-proxy`
-section.
-
-Traffic Server as a Reverse Proxy
----------------------------------
-
-As a reverse proxy, Traffic Server is configured to be the origin server
-to which the user is trying to connect (typically, the origin server’s
-advertised hostname resolves to Traffic Server, which acts as the real
-origin server). The reverse proxy feature is also called server
-acceleration. Reverse proxy is described in more detail in
-:ref:`reverse-proxy-and-http-redirects`.
-
-Traffic Server in a Cache Hierarchy
------------------------------------
-
-Traffic Server can participate in flexible cache hierarchies, in which
-Internet requests not fulfilled from one cache are routed to other
-regional caches, thereby leveraging the contents and proximity of nearby
-caches. In a hierarchy of proxy servers, Traffic Server can act either
-as a parent or a child cache to other Traffic Server systems or to
-similar caching products.
-
-Traffic Server supports ICP (Internet Cache Protocol) peering.
-Hierarchical caching is described in more detail in :ref:`admin-hierarchical-caching`.
-
-Deployment Limitations
-----------------------
-
-There are a number of deployment options that Traffic Server does not support
-right out of the box. Such functionality may be implemented in a plugin, but
-in some cases Traffic Server's internal APIs or architectural restrictions
-won't make it easy:
-
-* Load Balancing - note that there is an experimental plugin for this: :ref:`balancer-plugin`.
-
-.. XXX needs re-work: the leadin states there's "a number" of scenarios, and then only lists one -- one's a number, but not much of a list
-
-Traffic Server Components
-=========================
-
-Traffic Server consists of several components that work together to form
-a web proxy cache you can easily monitor and configure.
-
-The Traffic Server Cache
-------------------------
-
-The Traffic Server cache consists of a high-speed object database called
-the *object store*. The object store indexes objects according to URLs and
-associated headers. Using sophisticated object management, the object
-store can cache alternate versions of the same object (perhaps in a
-different language or encoding type). It can also efficiently store very
-small and very large objects, thereby minimizing wasted space. When the
-cache is full, Traffic Server removes stale data to ensure that the most
-requested objects are readily available and fresh.
-
-Traffic Server is designed to tolerate total disk failures on any of the
-cache disks. If the disk fails completely, then Traffic Server marks the
-entire disk as corrupt and continues to use remaining disks. If all of
-the cache disks fail, then Traffic Server switches to proxy-only mode.
-You can partition the cache to reserve a certain amount of disk space
-for storing data for specific protocols and origin servers. For more
-information about the cache, see :ref:`admin-configuring-the-cache`.
-
-The RAM Cache
--------------
-
-Traffic Server maintains a small RAM cache that contains extremely
-popular objects. This RAM cache serves the most popular objects as fast
-as possible and reduces load on disks, especially during temporary
-traffic peaks. You can configure the RAM cache size to suit your needs.
-For detailed information, refer to :ref:`changing-the-size-of-the-ram-cache`.
-
-The Host Database
------------------
-
-The Traffic Server host database stores the domain name server (DNS)
-entries of origin servers to which Traffic Server connects to fulfill
-user requests. This information is used to adapt future protocol
-interactions and optimize performance. Along with other information, the
-host database tracks:
-
-- DNS information (for fast conversion of hostnames to IP addresses).
-
-- The HTTP version of each host (so advanced protocol features can be
- used with hosts running modern servers).
-
-- Host reliability and availability information (so users will not wait
- for servers that are not running).
-
-The DNS Resolver
-----------------
-
-Traffic Server includes a fast, asynchronous DNS resolver to streamline
-conversion of hostnames to IP addresses. Traffic Server implements the
-DNS resolver natively by directly issuing DNS command packets rather
-than relying on slower, conventional resolver libraries. Since many DNS
-queries can be issued in parallel and a fast DNS cache maintains popular
-bindings in memory, DNS traffic is reduced.
-
-Traffic Server Processes
-------------------------
-
-Traffic Server contains three processes that work together to serve
-requests and manage, control, and monitor the health of the system.
-
-- The :program:`traffic_server` process is the transaction processing engine
- of Traffic Server. It is responsible for accepting connections,
- processing protocol requests, and serving documents from the cache or
- origin server.
-
-- The :program:`traffic_manager` process is the command and control facility
- of the Traffic Server, responsible for launching, monitoring, and
- reconfiguring the :program:`traffic_server` process. The :program:`traffic_manager`
- process is also responsible for the proxy autoconfiguration port, the
- statistics interface, cluster administration, and virtual IP
- failover.
-
- If the :program:`traffic_manager` process detects a :program:`traffic_server`
- process failure, it instantly restarts the process but also maintains
- a connection queue of all incoming requests. All incoming connections
- that arrive in the several seconds before full server restart are
- saved in the connection queue and processed in first-come,
- first-served order. This connection queueing shields users from any
- server restart downtime.
-
-- The :program:`traffic_cop` process monitors the health of both the
- :program:`traffic_server` and :program:`traffic_manager` processes. The
- :program:`traffic_cop` process periodically (several times each minute)
- queries the :program:`traffic_server` and :program:`traffic_manager`
- processes by issuing heartbeat requests to fetch synthetic web pages. In the
- event of failure (if no response is received within a timeout interval or
- if an incorrect response is received), :program:`traffic_cop` restarts the
- :program:`traffic_manager` and :program:`traffic_server` processes.
-
-The figure below illustrates the three Traffic Server processes.
-
-.. figure:: ../static/images/admin/process.jpg
- :align: center
- :alt: Illustration of the three Traffic Server Processes
-
- Illustration of the three Traffic Server Processes
-
-Administration Tools
---------------------
-
-Traffic Server offers the following administration options:
-
-- The :program:`traffic_ctl` command-line interface is a
- text-based interface from which you can monitor Traffic Server performance
- and network traffic, as well as configure the Traffic Server system. From
- Traffic Line, you can execute individual commands or script a series of
- commands in a shell.
-
-- Various configuration files enable you to configure Traffic Server
- through a simple file-editing and signal-handling interface. Any
- changes you make through Traffic Line is
- automatically made to the configuration files as well.
-
-- Finally, there is a clean C API which can be put to good use from a
- multitude of languages. The Traffic Server Admin Client demonstrates
- this for Perl.
-
-Traffic Analysis Options
-========================
-
-Traffic Server provides several options for network traffic analysis and
-monitoring:
-
-- :program:`traffic_ctl` enables you to collect and process
- statistics obtained from network traffic information.
-
-- Transaction logging enables you to record information (in a log file)
- about every request Traffic Server receives and every error it
- detects. By analyzing the log files, you can determine how many
- clients used the Traffic Server cache, how much information each of
- them requested, and what pages were most popular. You can also see
- why a particular transaction was in error and what state the Traffic
- Server was in at a particular time. For example, you can see that
- Traffic Server was restarted or that cluster communication timed out.
-
- Traffic Server supports several standard log file formats, such as
- Squid and Netscape, and its own custom format. You can analyze the
- standard format log files with off-the-shelf analysis packages. To
- help with log file analysis, you can separate log files so that they
- contain information specific to protocol or hosts.
-
-Traffic analysis options are described in more detail in :ref:`monitoring-traffic`.
-
-Traffic Server logging options are described in :ref:`working-with-log-files`.
-
-Traffic Server Security Options
-===============================
-
-Traffic Server provides numerous options that enable you to establish
-secure communication between the Traffic Server system and other
-computers on the network. Using the security options, you can do the
-following:
-
-- Control client access to the Traffic Server proxy cache.
-
-- Configure Traffic Server to use multiple DNS servers to match your
- site's security configuration. For example, Traffic Server can use
- different DNS servers, depending on whether it needs to resolve
- hostnames located inside or outside a firewall. This enables you to
- keep your internal network configuration secure while continuing to
- provide transparent access to external sites on the Internet.
-
-- Configure Traffic Server to verify that clients are authenticated
- before they can access content from the Traffic Server cache.
-
-- Secure connections in reverse proxy mode between a client and Traffic
- Server, and Traffic Server and the origin server, using the SSL
- termination option.
-
-- Control access via SSL (Secure Sockets Layer).
-
-Traffic Server security options are described in more detail in
-:ref:`security-options`.
-
-Tuning Traffic Server
-=====================
-
-Finally, this last chapter on :ref:`performance-tuning` discusses the vast
-number of options that allow administrators to optimally tune Apache Traffic
-Server for maximum performance.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/admin/monitoring-traffic.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/monitoring-traffic.en.rst b/doc/admin/monitoring-traffic.en.rst
deleted file mode 100644
index df13047..0000000
--- a/doc/admin/monitoring-traffic.en.rst
+++ /dev/null
@@ -1,109 +0,0 @@
-.. _monitoring-traffic:
-
-Monitoring Traffic
-******************
-
-.. 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
-
- 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.
-
-Traffic Server provides several options for monitoring system
-performance and analyzing network traffic.
-
-.. toctree::
- :maxdepth: 2
-
-Traffic Server Monitoring Tools
-===============================
-
-Traffic Server provides the following tools to monitor system
-performance and analyze network traffic:
-
-- Traffic Server can send email that's triggered by alarms that signal
- any detected failure conditions; refer to `Working with Traffic Manager Alarms`_.
-
-- The Traffic Line command-line interface provides an alternative
- method of viewing Traffic Server performance and network traffic
- information; refer to `Viewing Statistics from Traffic Line`_.
-
-
-Working with Traffic Manager Alarms
-===================================
-
-Traffic Server signals an alarm when it detects a problem. For example,
-the space allocated to event logs could be full or Traffic Server may
-not be able to write to a configuration file.
-
-Configuring Traffic Server to Email Alarms
-------------------------------------------
-
-To configure Traffic Server to send an email to a specific address
-whenever an alarm occurs, follow the steps below:
-
-#. Set :ts:cv:`proxy.config.alarm_email` in :file:`records.config` to the email
- address you want to receive alarm notifications. ::
-
- CONFIG proxy.config.alarm_email STRING "alerts@example.com"
-
-#. Run the command :option:`traffic_ctl config reload` to apply the configuration changes.
-
-Using a Script File for Alarms
-------------------------------
-
-Alarm messages are built into Traffic Server and cannot be changed.
-However, you can write a script file to execute certain actions when an
-alarm is signaled. Traffic Server provides a sample script file named
-``example_alarm_bin.sh`` in the ``bin`` directory which can serve as the
-basis for your custom alarm scripts.
-
-Viewing Statistics from Traffic Line
-====================================
-
-You can use the Traffic Line command-line interface to view statistics
-about Traffic Server performance and web traffic. In addition to viewing
-statistics, you can also configure, stop, and restart the Traffic Server
-system. For additional information, refer to :ref:`configure-using-traffic-line`
-and :ref:`traffic-line-commands`. You can view
-specific information about a Traffic Server node or cluster by
-specifying the variable that corresponds to the statistic you want to
-see.
-
-To view a statistic, enter the following command:::
-
- traffic_ctl metric get VARIABLE
-
-where ``variable`` is the variable representing the information you
-want to view. For a list of variables you can specify, refer to :ref:`Traffic
-Server Metrics <traffic-line-performance-statistics>`.
-
-For example, the following command displays the document hit rate for
-the Traffic Server node:::
-
- traffic_ctl metric get proxy.node.cache_hit_ratio
-
-If the Traffic Server ``bin`` directory is not in your path, then
-prepend the Traffic Line command with ``./`` (for example:
-:option:`traffic_ctl metric get` ``VARIABLE``).
-
-
-Viewing Statistics with Traffic Top
-===================================
-
-The Traffic Top program (see :program:`traffic_top`) offers a *top-like* view of
-common statistics for your Traffic Server system. You must be running
-:ref:`plugin-stats-over-httpd` for Traffic Top to function.
-
-.. XXX: We're missing docs on how to use traffic_top here.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/admin/performance-tuning.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/performance-tuning.en.rst b/doc/admin/performance-tuning.en.rst
deleted file mode 100644
index c0a6d82..0000000
--- a/doc/admin/performance-tuning.en.rst
+++ /dev/null
@@ -1,292 +0,0 @@
-.. 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
-
- 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.
-
-.. include:: ../common.defs
-
-.. _performance-tuning:
-
-Performance Tuning
-******************
-
-|ATS| in its default configuration should perform suitably for running the
-included regression test suite, but will need special attention to both its own
-configuration and the environment in which it runs to perform optimally for
-production usage.
-
-There are numerous options and strategies for tuning the performance of |TS|
-and we attempt to document as many of them as possible in the sections below.
-Because |TS| offers enough flexibility to be useful for many caching and
-proxying scenarios, which tuning strategies will be most effective for any
-given use case may differ, as well as the specific values for various
-configuration options.
-
-.. toctree::
- :maxdepth: 2
-
-Before You Start
-================
-
-One of the most important aspects of any attempt to optimize the performance
-of a |TS| installation is the ability to measure that installation's
-performance; both prior to and after any changes are made. To that end, it is
-strongly recommended that you establish some means to monitor and record a
-variety of performance metrics: request and response speed, latency, and
-throughput; memory and CPU utilization; and storage I/O operations.
-
-Attempts to tune a system without being able to compare the impact of changes
-made will at best result in haphazard, *feel good* results that may end up
-having no real world impact on your customers' experiences, and at worst may
-even result in lower performance than before you started. Additionally, in the
-all too common situation of budget constraints, having proper measurements of
-existing performance will greatly ease the process of focusing on those
-individual components that, should they require hardware expenditures or larger
-investments of employee time, have the highest potential gains relative to
-their cost.
-
-Building Traffic Server
-=======================
-
-While the default compilation settings for |TS| will produce a set of binaries
-capable of serving most caching and proxying needs, there are some build
-options worth considering in specific environments.
-
-.. TODO::
-
- - any reasons why someone wouldn't want to just go with distro packages?
- (other than "distro doesn't package versions i want")
- - list relevant build options, impact each can potentially have
-
-Hardware Tuning
-===============
-
-As with any other server software, efficient allocation of hardware resources
-will have a significant impact on |TS| performance.
-
-CPU Selection
--------------
-
-|ATS| uses a hybrid event-driven engine and multi-threaded processing model for
-handling incoming requests. As such, it is highly scalable and makes efficient
-use of modern, multicore processor architectures.
-
-.. TODO::
-
- any benchmarks showing relative req/s improvements between 1 core, 2 core,
- N core? diminishing rate of return? can't be totally linear, but maybe it
- doesn't realistically drop off within the currently available options (i.e.
- the curve holds up pretty well all the way through current four socket xeon
- 8 core systems, so given a lack of monetary constraint, adding more cores
- is a surefire performance improvement (up to the bandwidth limits), or does
- it fall off earlier, or can any modern 4 core saturate a 10G network link
- given fast enough disks?)
-
-Memory Allocation
------------------
-
-Though |TS| stores cached content within an on-disk host database, the entire
-:ref:`cache-directory` is always maintained in memory during server operation.
-Additionally, most operating systems will maintain disk caches within system
-memory. It is also possible, and commonly advisable, to maintain an in-memory
-cache of frequently accessed content.
-
-The memory footprint of the |TS| process is largely fixed at the time of server
-startup. Your |TS| systems will need at least enough memory to satisfy basic
-operating system requirements, as well as capacity for the cache directory, and
-any memory cache you wish to use. The default settings allocate roughly 10
-megabytes of RAM cache for every gigabyte of disk cache storage, though this
-setting can be adjusted manually in :file:`records.config` using the setting
-:ts:cv:`proxy.config.cache.ram_cache.size`. |TS| will, under the default
-configuration, adjust this automatically if your system does not have enough
-physical memory to accomodate the aforementioned target.
-
-Aside from the cost of physical memory, and necessary supporting hardware to
-make use of large amounts of RAM, there is little downside to increasing the
-memory allocation of your cache servers. You will see, however, no benefit from
-sizing your memory allocation larger than the sum of your content (and index
-overhead).
-
-Disk Storage
-------------
-
-Except in cases where your entire cache may fit into system memory, your cache
-nodes will eventually need to interact with their disks. While a more detailed
-discussion of storage stratification is covered in `Cache Partitioning`_ below,
-very briefly you may be able to realize gains in performance by separating
-more frequently accessed content onto faster disks (PCIe SSDs, for instance)
-while maintaining the bulk of your on-disk cache objects, which may not receive
-the same high volume of requests, on lower-cost mechanical drives.
-
-
-
-Operating System Tuning
-========================
-
-|ATS| is supported on a variety of operating systems, and as a result the tuning
-strategies available at the OS level will vary depending upon your chosen
-platform.
-
-General Recommendations
------------------------
-
-TCP Keep Alive
-~~~~~~~~~~~~~~
-
-TCP Congestion Control Settings
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Ephemeral and Reserved Ports
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Jumbo Frames
-~~~~~~~~~~~~
-
-.. TODO:: would they be useful/harmful/neutral for anything other than local forward/transparent proxies?
-
-Linux
------
-
-FreeBSD
--------
-
-OmniOS / illumos
-----------------
-
-Mac OS X
---------
-
-Traffic Server Tuning
-=====================
-
-|TS| itself, of course, has many options you may want to consider adjusting to
-achieve optimal performance in your environment. Many of these settings are
-recorded in :file:`records.config` and may be adjusted with the
-:option:`traffic_ctl config set` command line utility while the server is operating.
-
-CPU and Thread Optimization
----------------------------
-
-Thread Scaling
-~~~~~~~~~~~~~~
-
-By default, |TS| creates 1.5 threads per CPU core on the host system. This may
-be adjusted with the following settings in :file:`records.config`:
-
-* :ts:cv:`proxy.config.exec_thread.autoconfig`
-* :ts:cv:`proxy.config.exec_thread.autoconfig.scale`
-* :ts:cv:`proxy.config.exec_thread.limit`
-
-Thread Affinity
-~~~~~~~~~~~~~~~
-
-On multi-socket servers, such as Intel architectures with NUMA, you can adjust
-the thread affinity configuration to take advantage of cache pipelines and
-faster memory access, as well as preventing possibly costly thread migrations
-across sockets. This is adjusted with :ts:cv:`proxy.config.exec_thread.affinity`
-in :file:`records.config`. ::
-
- CONFIG proxy.config.exec_thread.affinity INT 1
-
-Thread Stack Size
-~~~~~~~~~~~~~~~~~
-
-:ts:cv:`proxy.config.thread.default.stacksize`
-
-.. TODO::
-
- is there ever a need to fiddle with this, outside of possibly custom developed plugins?
-
-Polling Timeout
-~~~~~~~~~~~~~~~
-
-If you are experiencing unusually or unacceptably high CPU utilization during
-idle workloads, you may consider adjusting the polling timeout with
-:ts:cv:`proxy.config.net.poll_timeout`::
-
- CONFIG proxy.config.net.poll_timeout INT 60
-
-Memory Optimization
--------------------
-
-:ts:cv:`proxy.config.thread.default.stacksize`
-:ts:cv:`proxy.config.cache.ram_cache.size`
-
-
-Disk Storage Optimization
--------------------------
-
-:ts:cv:`proxy.config.cache.force_sector_size`
-:ts:cv:`proxy.config.cache.max_doc_size`
-:ts:cv:`proxy.config.cache.target_fragment_size`
-
-Cache Partitioning
-~~~~~~~~~~~~~~~~~~
-
-Network Tuning
---------------
-
-:ts:cv:`proxy.config.net.connections_throttle`
-
-Error responses from origins are conistent and costly
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If error responses are costly for your origin server to generate, you may elect
-to have |TS| cache these responses for a period of time. The default behavior is
-to consider all of these responses to be uncacheable, which will lead to every
-client request to result in an origin request.
-
-This behavior is controlled by both enabling the feature via
-:ts:cv:`proxy.config.http.negative_caching_enabled` and setting the cache time
-(in seconds) with :ts:cv:`proxy.config.http.negative_caching_lifetime`. ::
-
- CONFIG proxy.config.http.negative_caching_enabled INT 1
- CONFIG proxy.config.http.negative_caching_lifetime INT 10
-
-SSL-Specific Options
-~~~~~~~~~~~~~~~~~~~~
-
-:ts:cv:`proxy.config.ssl.max_record_size`
-:ts:cv:`proxy.config.ssl.session_cache`
-:ts:cv:`proxy.config.ssl.session_cache.size`
-
-Thread Types
-------------
-
-Logging Configuration
----------------------
-
-.. TODO::
-
- binary vs. ascii output
- multiple log formats (netscape+squid+custom vs. just custom)
- overhead to log collation
- using direct writes vs. syslog target
-
-Plugin Tuning
-=============
-
-Common Scenarios and Pitfalls
-=============================
-
-While environments vary widely and |TS| is useful in a great number of different
-situations, there are at least some recurring elements that may be used as
-shortcuts to identifying problem areas, or realizing easier performance gains.
-
-.. TODO::
-
- - origins not sending proper expiration headers (can fix at the origin (preferable) or use proxy.config.http.cache.heuristic_(min|max)_lifetime as hacky bandaids)
- - cookies and http_auth prevent caching
- - avoid thundering herd with read-while-writer (link to section in http-proxy-caching)