http://git-wip-us.apache.org/repos/asf/trafficserver/blob/9fbd4201/doc/admin/hierachical-caching.en.rst ---------------------------------------------------------------------- diff --git a/doc/admin/hierachical-caching.en.rst b/doc/admin/hierachical-caching.en.rst index 66a1a5e..69ba2cc 100644 --- a/doc/admin/hierachical-caching.en.rst +++ b/doc/admin/hierachical-caching.en.rst @@ -5,21 +5,20 @@ 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. + 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 @@ -29,7 +28,7 @@ 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 +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. @@ -42,22 +41,23 @@ 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 one or more parent caches so that -if one parent is unavailable, then another parent is availale to service -requests. This is called `Parent Failover`_. Traffic -Server will support parent caching for HTTP and HTTPS requests. +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. -**Note:** 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. Simply -set parent proxy rules in :file:`parent.config` +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 +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 @@ -69,11 +69,10 @@ is stale or expired). Parent caching -**Note:** 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. +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. Parent Failover --------------- @@ -95,23 +94,27 @@ order they are listed in the configuration file. Configuring Traffic Server to Use a Parent Cache ------------------------------------------------ -To configure Traffic Server to use one or more parent caches, you must -complete the following steps: +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. No additional configuration is + needed for the nodes acting as Traffic Server parent caches. -- Enable the parent caching option. -- 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. +#. Enable the parent caching option by adjusting + :ts:cv:`proxy.config.http.parent_proxy_routing_enable` in + :file:`records.config`. :: -.. note:: You need to configure the child cache only. No additional configuration is needed for the Traffic Server parent cache. + CONFIG proxy.config.http.parent_proxy_routing_enable INT 1 -Configure Traffic Server to use a parent cache by editing the following -variable :ts:cv:`proxy.config.http.parent_proxy_routing_enable` in :file:`records.config` file. +#. 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 the :file:`parent.config` file located in the Traffic Server ``config`` directory to set parent -proxy rules to specify the parent cache to which you want missed -requests to be forwarded; +#. 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 @@ -135,35 +138,35 @@ Run the command :option:`traffic_line -x` to apply the configuration changes. .. # ICP Peering # {#ICPPeering} -.. The Internet Cache Protocol (ICP) is used by proxy caches to exchange information +.. 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 + 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. + 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: + 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. +.. * 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: @@ -173,7 +176,7 @@ Run the command :option:`traffic_line -x` to apply the configuration changes. * :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: +.. 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_line -x` to apply the configuration changes.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/9fbd4201/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 index e305007..c29c824 100644 --- a/doc/admin/http-proxy-caching.en.rst +++ b/doc/admin/http-proxy-caching.en.rst @@ -20,7 +20,7 @@ HTTP Proxy Caching specific language governing permissions and limitations under the License. -Web proxy caching enables you to store copies of frequently-accessed web +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. @@ -32,23 +32,23 @@ 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 +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 +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. -1. Traffic Server receives a client request for a web object. +#. Traffic Server receives a client request for a web object. -2. Using the object address, Traffic Server tries to locate the - requested object in its object database (**cache**). +#. Using the object address, Traffic Server tries to locate the + requested object in its object database (*cache*). -3. If the object is in the cache, then Traffic Server checks to see if +#. 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 + Server serves it to the client as a *cache hit* (see the figure below). .. figure:: ../static/images/admin/cache_hit.jpg @@ -57,12 +57,12 @@ overview illustrates how Traffic Server serves a request. A cache hit -4. If the data in the cache is stale, then Traffic Server connects to +#. 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. -5. If the object is not in the cache (a **cache miss**) or if the server +#. 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 @@ -78,9 +78,11 @@ overview illustrates how Traffic Server serves a request. 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/should not be cached. The following sections discuss +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 ================================ @@ -98,7 +100,7 @@ HTTP Object Freshness --------------------- Traffic Server determines whether an HTTP object in the cache is fresh -by: +by checking the following conditions in order: - **Checking the** ``Expires`` **or** ``max-age`` **header** @@ -119,25 +121,26 @@ by: 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`_). + 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. + 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`_). + maximum and minimum freshness limit. Refer to + `Setting Absolute Freshness Limits`_. -- **Checking revalidate rules in the** :file:`cache.config` **file** +- **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`). + on. Refer to :file:`cache.config`. Modifying Aging Factor for Freshness Computations ------------------------------------------------- @@ -148,30 +151,27 @@ Server can estimate its freshness from the ``Last-Modified`` and 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 +To modify the aging factor for freshness computations: -1. Change the value for :ts:cv:`proxy.config.http.cache.heuristic_lm_factor`. +#. Change the value for :ts:cv:`proxy.config.http.cache.heuristic_lm_factor`. -2. Run the :option:`traffic_line -x` command to apply the configuration - changes. +#. Run the :option:`traffic_line -x` command to apply the configuration changes. -Setting absolute Freshness Limits +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 +objects are considered fresh in the cache, specify an *absolute +freshness limit*. -1. Edit the variables +To specify an absolute freshness limit: - - :ts:cv:`proxy.config.http.cache.heuristic_min_lifetime` - - :ts:cv:`proxy.config.http.cache.heuristic_max_lifetime` +#. 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`. -2. Run the :option:`traffic_line -x` command to apply the configuration - changes. +#. Run the :option:`traffic_line -x` command to apply the configuration changes. Specifying Header Requirements ------------------------------ @@ -185,40 +185,39 @@ 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 +To configure Traffic Server to cache objects with specific headers: -1. Change the value for :ts:cv:`proxy.config.http.cache.required_headers`. +#. Change the value for :ts:cv:`proxy.config.http.cache.required_headers` + in :file:`records.config`. -2. Run the :option:`traffic_line -x` command to apply the configuration - changes. - -.. _cache-control-headers: +#. Run the :option:`traffic_line -x` 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, 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: +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; - therefore, Traffic Server will always obtain the object from the + 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`_ + ``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. + 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 +- 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. @@ -228,16 +227,15 @@ affect whether objects are served from cache: 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``. +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 +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: @@ -261,47 +259,53 @@ 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. +*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 -1. Edit the following variable in :file:`records.config` +#. Edit the variable :ts:cv:`proxy.config.http.cache.when_to_revalidate` + in :file:`records.config`. - - :ts:cv:`proxy.config.http.cache.when_to_revalidate` +#. Run the :option:`traffic_line -x` command to apply the configuration changes. -2. Run the :option:`traffic_line -x` command to apply the configuration - changes. +.. _scheduling-updates-to-local-cache-content: Scheduling Updates to Local Cache Content ========================================= To further increase performance and to ensure that HTTP objects are -fresh in the cache, you can use the **Scheduled Update** option. This +fresh in the cache, you can use the *Scheduled Update* option. This configures Traffic Server to load specific objects into the cache at -scheduled times. You might find this especially beneficial in a reverse -proxy setup, where you can *preload* content you anticipate will be in -demand. +scheduled times, regardless of whether there is an active client request +for those objects at the scheduled time. You might find this especially +beneficial in a reverse proxy setup, where you can preload content you +anticipate will be in demand. + +To use the scheduled update option, you must: -To use the Scheduled Update option, you must perform the following -tasks. +- Specify the list of URLs that contain the objects you want to schedule + for update. + +- Specify the time the update should take place. + +- Specify the recursion depth for the URL. -- Specify the list of URLs that contain the objects you want to - schedule for update, -- the time the update should take place, -- and the recursion depth for the URL. - Enable the scheduled update option and configure optional retry settings. -Traffic Server uses the information you specify to determine URLs for +Traffic Server uses the information you provide to determine URLs for which it is responsible. For each URL, Traffic Server derives all recursive URLs (if applicable) and then generates a unique URL list. Using this list, Traffic Server initiates an HTTP ``GET`` for each @@ -310,53 +314,59 @@ limits for HTTP concurrency at any given time. The system logs the completion of all HTTP ``GET`` operations so you can monitor the performance of this feature. -Traffic Server also provides a **Force Immediate Update** option that +Traffic Server also provides a *Force Immediate Update* option that enables you to update URLs immediately without waiting for the specified update time to occur. You can use this option to test your scheduled -update configuration (refer to `Forcing an Immediate Update`_). +update configuration. Refer to `Forcing an Immediate Update`_. Configuring the Scheduled Update Option --------------------------------------- To configure the scheduled update option -1. Edit :file:`update.config` to - enter a line in the file for each URL you want to update. -2. Edit the following variables +#. Edit :file:`update.config` to enter a line in the file for each URL you + want to update. + +#. Adjust the following variables in :file:`records.config`: - :ts:cv:`proxy.config.update.enabled` - :ts:cv:`proxy.config.update.retry_count` - :ts:cv:`proxy.config.update.retry_interval` - :ts:cv:`proxy.config.update.concurrent_updates` -3. Run the :option:`traffic_line -x` command to apply the configuration - changes. +#. Run the :option:`traffic_line -x` command to apply the configuration changes. -Forcing an Immediate Update ---------------------------- +Forcing Immediate Updates +------------------------- -Traffic Server provides a **Force Immediate Update** option that enables +Traffic Server provides a *Force Immediate Update* option that enables you to immediately verify the URLs listed in :file:`update.config`. -The Force Immediate Update option disregards the offset hour and -interval set in :file:`update.config` and immediately updates the -URLs listed. +This option disregards the offset hour and interval set in :file:`update.config` +and immediately updates the URLs listed. + +To configure the Force Immediate Update option: + +#. Enable :ts:cv:`proxy.config.update.enabled` in :file:`records.config`:: -To configure the Force Immediate Update option + CONFIG proxy.config.update.enabled INT 1 -1. Edit the following variables +#. Enable :ts:cv:`proxy.config.update.force` in :file:`records.config`:: - - :ts:cv:`proxy.config.update.force` - - Make sure :ts:cv:`proxy.config.update.enabled` is set to 1. + CONFIG proxy.config.update.force INT 1 -2. Run the command :option:`traffic_line -x` to apply the configuration - changes. + While enabled, this overrides all normal scheduling intervals. + +#. Run the command :option:`traffic_line -x` to apply the configuration changes. .. important:: - When you enable the Force Immediate Update option, Traffic Server continually updates the URLs specified in - :file:`update.config` until you disable the option. To disable the Force Immediate Update option, set + When you enable the Force Immediate Update option, Traffic Server + continually updates the URLs specified in :file:`update.config` until you + disable the option. To disable the Force Immediate Update option, set :ts:cv:`proxy.config.update.force` to ``0`` (zero). +.. _pushing-content-into-the-cache: + Pushing Content into the Cache ============================== @@ -370,17 +380,14 @@ 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. -To configure Traffic Server to accept ``PUSH`` requests - -1. Edit :file:`ip_allow.config` to allow ``PUSH``. +#. Edit :file:`ip_allow.config` to allow ``PUSH`` from the appropriate addresses. -2. Edit the following variable in :file:`records.config`, enable - the push_method. +#. Update :ts:cv:`proxy.config.http.push_method_enabled` in + :file:`records.config`:: - - :ts:cv:`proxy.config.http.push_method_enabled` + CONFIG proxy.config.http.push_method_enabled INT 1 -3. Run the command :option:`traffic_line -x` to apply the configuration - changes. +#. Run the command :option:`traffic_line -x` to apply the configuration changes. Understanding HTTP PUSH ----------------------- @@ -402,51 +409,49 @@ place in the cache. The following is an example of a ``PUSH`` request:: .. important:: - Your header must include ``Content-length`` - ``Content-length`` must include both ``header`` and ``body byte - count``. + 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 ----------------------------------- -There is a perl script for pushing, :program:`tspush`, -which can help you understanding how to write scripts for 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 +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 +To set cache pinning rules: -1. Make sure the following variable in :file:`records.config` is set +#. Enable :ts:cv:`proxy.config.cache.permit.pinning` in :file:`records.config`:: - - :ts:cv:`proxy.config.cache.permit.pinning` + CONFIG proxy.config.cache.permit.pinning INT 1 -2. Add a rule in :file:`cache.config` for each - URL you want Traffic Server to pin in the cache. For example:: +#. 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 -3. Run the command :option:`traffic_line -x` to apply the configuration - changes. +#. Run the command :option:`traffic_line -x` to apply the configuration changes. -To Cache or Not to Cache? -========================= +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. -Caching HTTP Objects -==================== - Traffic Server responds to caching directives from clients and origin servers, as well as directives you specify through configuration options and files. @@ -454,19 +459,19 @@ and files. Client Directives ----------------- -By default, Traffic Server does *not* cache objects with the following -**request headers**: +By default, Traffic Server does not cache objects with the following +request headers: -- ``Authorization``: header +- ``Authorization`` -- ``Cache-Control: no-store`` header +- ``Cache-Control: no-store`` -- ``Cache-Control: no-cache`` header +- ``Cache-Control: no-cache`` - To configure Traffic Server to ignore the ``Cache-Control: no-cache`` - header, refer to `Configuring Traffic Server to Ignore Client no-cache Headers`_ + To configure Traffic Server to ignore this request header, refer to + `Configuring Traffic Server to Ignore Client no-cache Headers`_. -- ``Cookie``: header (for text objects) +- ``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 @@ -485,35 +490,36 @@ 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. -To configure Traffic Server to ignore client ``no-cache`` headers - -1. Edit the following variable in :file:`records.config` +#. Edit :ts:cv:`proxy.config.http.cache.ignore_client_no_cache` in + :file:`records.config`. :: - - :ts:cv:`proxy.config.http.cache.ignore_client_no_cache` + CONFIG proxy.config.http.cache.ignore_client_no_cache 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. Origin Server Directives ------------------------ -By default, Traffic Server does *not* cache objects with the following -**response headers**: +By default, Traffic Server does not cache objects with the following response +headers: -- ``Cache-Control: no-store`` header -- ``Cache-Control: private`` header -- ``WWW-Authenticate``: header +- ``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``: header -- ``Cache-Control: no-cache`` 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 value of 0 (zero) or a past date +- ``Expires`` header with a value of 0 (zero) or a past date. Configuring Traffic Server to Ignore Server no-cache Headers ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -526,12 +532,14 @@ 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 +To configure Traffic Server to ignore server ``no-cache`` headers: -#. Edit the variable :ts:cv:`proxy.config.http.cache.ignore_server_no_cache` +#. Edit :ts:cv:`proxy.config.http.cache.ignore_server_no_cache` in + :file:`records.config`. :: -#. Run the command :option:`traffic_line -x` to apply the configuration - changes. + CONFIG proxy.config.http.cache.ignore_server_no_cache INT 1 + +#. Run the command :option:`traffic_line -x` to apply the configuration changes. Configuring Traffic Server to Ignore WWW-Authenticate Headers ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -550,12 +558,14 @@ ignore server ``WWW-Authenticate`` headers if you are knowledgeable about HTTP 1.1. To configure Traffic Server to ignore server ``WWW-Authenticate`` -headers +headers: + +#. Edit :ts:cv:`proxy.config.http.cache.ignore_authentication` in + :file:`records.config`. :: -#. Edit the variable :ts:cv:`proxy.config.http.cache.ignore_authentication` + CONFIG proxy.config.http.cache.ignore_authentication INT 1 -#. Run the command :option:`traffic_line -x` to apply the configuration - changes. +#. Run the command :option:`traffic_line -x` to apply the configuration changes. Configuration Directives ------------------------ @@ -566,49 +576,54 @@ 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 +- 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 the :file:`cache.config` file. + +- 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 the :file:`cache.config` file. You can disable HTTP object -caching so that all HTTP objects are served directly from the origin -server and never cached, as detailed below. +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: -To disable HTTP object caching manually +#. Set :ts:cv:`proxy.config.http.enabled` to ``0`` in :file:`records.config`. :: -1. Set the variable :ts:cv:`proxy.config.http.enabled` to ``0``. + CONFIG proxy.config.http.enabled INT 0 -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. Caching Dynamic Content ~~~~~~~~~~~~~~~~~~~~~~~ -A URL is considered **dynamic** if it ends in **``.asp``** or contains a +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 dyanamic looking content, although this is recommended -only if the content is *truely* dyanamic, but fails to advertise so with +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 +content: -1. Edit the following variable in :file:`records.config` +#. 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``. :: - - :ts:cv:`proxy.config.http.cache.cache_urls_that_look_dynamic` + CONFIG proxy.config.http.cache.cache_urls_that_look_dynamic INT 0 -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. Caching Cookied Objects ~~~~~~~~~~~~~~~~~~~~~~~ @@ -624,16 +639,18 @@ unlikely that personalized headers are delivered or used. You can reconfigure Traffic Server to: -- *Not* cache cookied content of any type. +- 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 +To configure how Traffic Server caches cookied content: -1. Edit the variable :ts:cv:`proxy.config.http.cache.cache_responses_to_cookies` +#. Edit :ts:cv:`proxy.config.http.cache.cache_responses_to_cookies` in + :file:`records.config`. -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. Forcing Object Caching ====================== @@ -642,15 +659,14 @@ 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 +To force document caching: -1. Add a rule for each URL you want Traffic Server to pin to the cache +#. 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 -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. Caching HTTP Alternates ======================= @@ -660,27 +676,25 @@ 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 +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``\s that Traffic Server +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, follow the steps -below +To configure how Traffic Server caches alternates:: -1. Edit the following variables +1. 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` -2. Run the command :option:`traffic_line -x` to apply the configuration - changes. +2. Run the command :option:`traffic_line -x` to apply the configuration changes. .. note:: @@ -702,66 +716,82 @@ object (the default is 3). Traffic Server can look up the URL in the index very quickly, it must scan sequentially through available alternates in the object store. - To limit the number of alternates +To alter the limit on the number of alternates: + +#. Edit :ts:cv:`proxy.config.cache.limits.http.max_alts` in :file:`records.config`. :: - #. Edit the variable :ts:cv:`proxy.config.cache.limits.http.max_alts` - #. Run the command :option:`traffic_line -x` to apply the configuration changes. + CONFIG proxy.config.cache.limits.http.max_alts INT 5 +#. Run the command :option:`traffic_line -x` to apply the configuration changes. .. _using-congestion-control: Using Congestion Control ======================== -The **Congestion Control** option enables you to configure Traffic +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 use the **Congestion Control** option, you must perform the following -tasks: +To enable this option: -#. Set the variable :ts:cv:`proxy.config.http.congestion_control.enabled` to ``1`` +#. Set :ts:cv:`proxy.config.http.congestion_control.enabled` to ``1`` in + :file:`records.config`. :: - - Create rules in the :file:`congestion.config` file 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 - - if Traffic Server tracks the origin servers per IP address or per - hostname + CONFIG proxy.config.http.congestion_control.enabled INT 1 -#. Run the command :option:`traffic_line -x` to apply the configuration - changes. +#. Create rules in :file:`congestion.config` to specify: -.. _transaction-buffering-control: + - Which origin servers Traffic Server tracks for congestion. -Using Transaction Buffering Control -=================================== + - The timeouts Traffic Server uses, depending on whether a server is + congested. -By default I/O operations are run at full speed, as fast as either Traffic Server, the network, or the cache can go. -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>`_. + - The page Traffic Server sends to the client when a server becomes + congested. -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. + - Whether Traffic Server tracks the origin servers by IP address or by + hostname. -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. +#. Run the command :option:`traffic_line -x` to apply the configuration changes. -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. +.. _transaction-buffering-control: -The buffer size calculations include all elements in the transaction, including any buffers associated with :ref:`transform plugins <transform-plugin>`. +Using Transaction Buffering Control +=================================== -Transaction buffering control can be enabled globally by using configuration variables or by :c:func:`TSHttpTxnConfigIntSet` in a plugin. +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 @@ -771,76 +801,169 @@ Set high water :ts:cv:`proxy.config.http.flow_control.high_water` :c:data:`TS 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. +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`. +If using :c:func:`TSHttpTxnConfigIntSet`, it must be called no later than +:c:data:`TS_HTTP_READ_RESPONSE_HDR_HOOK`. -.. _reducing-origin-server-requests-avoiding-the-thundering-herd: +.. _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. +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. The difference is that Squid allows this as soon as it goes to origin, whereas ATS can not do it until we get the complete response header. The reason for this is that we make no distinction between cache refresh, and cold cache, so we have no way to know if a response is going to be cacheable, and therefore allow read-while-writer functionality. -The configurations necessary to enable this in ATS are: +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 :ts:cv:`proxy.config.cache.enable_read_while_writer` ``INT 1`` -| CONFIG :ts:cv:`proxy.config.http.background_fill_active_timeout` ``INT 0`` -| CONFIG :ts:cv:`proxy.config.http.background_fill_completed_threshold` ``FLOAT 0.000000`` -| CONFIG :ts:cv:`proxy.config.cache.max_doc_size` ``INT 0`` + 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: -- enable_read_while_writer turns the feature on. It's off (0) by default -- The background fill feature should be allowed to kick in for every possible request. This is necessary, in case the writer ("first client session") goes away, someone needs to take over the session. Hence, you should set the background fill timeouts and threshold to zero; this assures they never times out and always is allowed to kick in. -- The 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. +- :ts:cv:`proxy.config.cache.enable_read_while_writer` being set to ``1`` turns + the feature on, as it is off (``0``) by default. -Once all this enabled, you have something that is very close, but not quite the same, as Squid's Collapsed Forwarding. +- 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. .. _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 :ts:cv:`proxy.config.http.cache.fuzz.time` ``INT 240`` -| CONFIG :ts:cv:`proxy.config.http.cache.fuzz.min_time` ``INT 0`` -| CONFIG :ts:cv:`proxy.config.http.cache.fuzz.probability` ``FLOAT 0.005`` -For every request for an object that occurs "fuzz.time" before (in the example above, 240 seconds) the object is set to become stale, there is a small -chance (fuzz.probability == 0.5%) that the request will trigger a revalidation request to the origin. For objects getting a few requests per second, this would likely not trigger, but then this feature is not necessary anyways since odds are only 1 or a small number of connections would hit origin upon objects going stale. The defaults are a good compromise, for objects getting roughly 4 requests / second or more, it's virtually guaranteed to trigger a revalidate event within the 240s. These configs are also overridable per remap rule or via a plugin, so can be adjusted per request if necessary. +Traffic Server can be set to attempt to revalidate an object before it becomes +stale in cache. :file:`records.config` contains the settings:: -Note that if the 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. + 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 -Finally, the fuzz.min_time is there to be able to handle requests with a TTL less than fuzz.time â it allows for different times to evaluate the probability of revalidation for small TTLs and big 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 remap.config conf_remap.so configs. +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. -These configurations are similar to Squid's refresh_stale_hit configuration option. +.. 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 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 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. +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. -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 proxies 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. -Similarly, this setting should 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 another request 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. -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):: -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 -| CONFIG :ts:cv:`proxy.config.http.cache.max_open_read_retries` ``INT -1`` -| CONFIG :ts:cv:`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. -The default means that the feature is disabled, and every connection is allowed to go to origin instantly. When enabled, you will try max_open_read_retries times, each with a open_read_retry_time timeout. http://git-wip-us.apache.org/repos/asf/trafficserver/blob/9fbd4201/doc/admin/index.en.rst ---------------------------------------------------------------------- diff --git a/doc/admin/index.en.rst b/doc/admin/index.en.rst index 3b1229b..b4b7490 100644 --- a/doc/admin/index.en.rst +++ b/doc/admin/index.en.rst @@ -5,28 +5,25 @@ 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. + 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. -This chapter discusses how: - -Contents: +Table of Contents: .. toctree:: :maxdepth: 2 @@ -50,12 +47,11 @@ Contents: 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 terabytes of data, on a daily basis, +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 @@ -80,9 +76,8 @@ To best suit your needs, Traffic Server can be deployed in several ways: - In a cache hierarchy The following sections provide a summary of these Traffic Server -deployment options. Please keep in mind that with every of these options -Traffic Server can be run as a *single instance*, or as a *multi-node -cluster*. +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 ----------------------------------- @@ -100,6 +95,10 @@ 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 --------------------------------- @@ -108,7 +107,8 @@ 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`. +acceleration. Reverse proxy is described in more detail in +:ref:`reverse-proxy-and-http-redirects`. Traffic Server in a Cache Hierarchy ----------------------------------- @@ -121,29 +121,31 @@ 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:`hierarchical-caching`. +Hierarchical caching is described in more detail in :ref:`admin-hierarchical-caching`. Deployment Limitations ---------------------- -There's a number of deployment options that Traffic Server does not support right out -of the box. Such funcionality may be implemented in a plugin, but in some cases -Traffic Server's internal APIs or architectural restrictions won't make it easy: +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. These main -components are described below. +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 +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 @@ -157,7 +159,7 @@ 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:`configuring-the-cache`. +information about the cache, see :ref:`admin-configuring-the-cache`. The RAM Cache ------------- @@ -165,8 +167,8 @@ 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`. +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 ----------------- @@ -177,11 +179,13 @@ 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) +- 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) + used with hosts running modern servers). + - Host reliability and availability information (so users will not wait - for servers that are not running) + for servers that are not running). The DNS Resolver ---------------- @@ -197,8 +201,7 @@ Traffic Server Processes ------------------------ Traffic Server contains three processes that work together to serve -requests and manage/control/monitor the health of the system. The three -processes are described below: +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, @@ -223,9 +226,9 @@ processes are described below: - 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` process by - issuing heartbeat requests to fetch synthetic web pages. In the event - of failure (if no response is received within a timeout interval or + 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. @@ -242,19 +245,22 @@ Administration Tools Traffic Server offers the following administration options: -- The Traffic Line 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 +- The Traffic Line (:program:`traffic_line`) 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. -- The Traffic Shell command-line interface is an additional - command-line tool that enables you to execute individual commands + +- The Traffic Shell (:program:`traffic_shell`) command-line interface is an + additional command-line tool that enables you to execute individual commands that monitor and configure the Traffic Server system. + - 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 or Traffic Shell are automatically made to the configuration files as well. -- Finally there is a clean C API which can be put to good use from a + +- 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. @@ -273,7 +279,7 @@ monitoring: 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 + 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 @@ -295,17 +301,21 @@ 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 @@ -314,6 +324,6 @@ Traffic Server security options are described in more detail in Tuning Traffic Server ===================== -Finally this last chapter on :ref:`performance-tuning` discusses the vast -number of options that allow to optimally tune Apache Traffic Server for -maximum performance. +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/9fbd4201/doc/admin/monitoring-traffic.en.rst ---------------------------------------------------------------------- diff --git a/doc/admin/monitoring-traffic.en.rst b/doc/admin/monitoring-traffic.en.rst index c77548b..30e04ad 100644 --- a/doc/admin/monitoring-traffic.en.rst +++ b/doc/admin/monitoring-traffic.en.rst @@ -1,4 +1,3 @@ - .. _monitoring-traffic: Monitoring Traffic @@ -6,20 +5,20 @@ 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 - + 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. Traffic Server provides several options for monitoring system performance and analyzing network traffic. @@ -35,9 +34,11 @@ 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`_. + - The Traffic Shell command-line tool provides yet another alternative method of viewing Traffic Server performance and network traffic information; refer to `Starting Traffic Shell <../getting-started#StartTrafficShell>`_. @@ -56,19 +57,21 @@ 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: -1. In the :file:`records.config` file -2. Set the :ts:cv:`proxy.config.alarm_email` variable to the email address alarms will be routed to. -3. Run the command :option:`traffic_line -x` to apply the configuration - changes. +#. 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 "ale...@example.com" + +#. Run the command :option:`traffic_line -x` to apply the configuration changes. Using a Script File for Alarms ------------------------------ -Alarm messages are built into Traffic Server - you cannot change them. +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; simply modify the -file to suit your needs. +``example_alarm_bin.sh`` in the ``bin`` directory which can serve as the +basis for your custom alarm scripts. Viewing Statistics from Traffic Line ==================================== @@ -82,7 +85,7 @@ 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::: +To view a statistic, enter the following command::: traffic_line -r variable @@ -100,4 +103,11 @@ prepend the Traffic Line command with ``./`` (for example: :option:`traffic_line -r` ``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/9fbd4201/doc/admin/performance-tuning.en.rst ---------------------------------------------------------------------- diff --git a/doc/admin/performance-tuning.en.rst b/doc/admin/performance-tuning.en.rst index 1d9efc0..5486e90 100644 --- a/doc/admin/performance-tuning.en.rst +++ b/doc/admin/performance-tuning.en.rst @@ -1,4 +1,3 @@ - .. _performance-tuning: Performance Tuning @@ -6,21 +5,20 @@ Performance Tuning .. 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 @@ -29,9 +27,9 @@ Before you start ================ There is no single option to that will guarantee maximum performance of -Apache Traffic Server in every use-case. There are however numerous options +Apache Traffic Server in every use case. There are however numerous options that help tune its performance under different loads and in its - often -vastly different - use-cases. +vastly different - use cases. Building Traffic Server =======================
