doc/admin-guide/plugins/cacheurl.en.rst - trafficserver - Git at Google

 .. 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

 .. _admin-plugins-cacheurl:

 Cache URL Plugin
 ****************

 .. note::

    This plugin is deprecated as of v6.2.0 and will be removed as of v7.0.0.
    It is replaced by a new :ref:`admin-plugins-cachekey` and you should change your configurations to use the new plugin instead.
    Please find some examples below.

 This plugin allows you to change the :term:`cache key` that is used for caching
 a request by using any portion of the URL via regular expressions.

 Purpose
 =======

 By default |TS| generates keys for cache objects from the full request URL.
 Future requests will only be able to use the existing cache object if they
 result in the same cache key. It can be the case, however, that the same
 content is accessible through more than one request URL. Without any special
 configuration, that same content will result in multiple cache objects based on
 the differing URLs.

 In this scenario, it can be very beneficial to allow |TS| to reuse a cache
 object for multiple URLs. This plugin enables that behavior, by allowing the
 administrator to define custom patterns for generating cache keys for some, or
 all, of their site's URLs. Uninteresting or irrelevant portions of request URLs
 may be removed, or altered, before the cache key is created using the full
 power of regular expressions.

 Installation
 ============

 This plugin is considered stable and is included with |TS| by default. There
 are no special steps necessary for its installation.

 .. configfile:: cacheurl.config

 Configuration
 =============

 #. Enable the plugin by modifying :file:`plugin.config` to include the plugin::

     cacheurl.so

 #. Create a ``cacheurl.config`` file in the plugin directory with the url regex
    patterns you wish to match, using the following format::

       <pattern> <replacement>

    The ``<pattern>`` is a regular expression (PCRE) applied against the
    incoming request URL. The ``<replacement>`` may contain ``$1``, ``$2``, and
    so on, which will be replaced with the appropriate matching group from
    ``<pattern>``.

 #. Reload your |TS| configuration with :option:`traffic_ctl config reload`.

 Logging
 =======

 A new log file will be generated by this plugin, containing entries for each
 incident of an incoming URL's cache key being altered, located in the |TS|
 log directory and named ``cacheurl.log``.

 Examples
 ========

 While many possibilities exist, limited really only by your site's URL scheme
 and the capabililties of PCRE regular expressions, the following are examples
 of a few situations |TS| administrators may encounter.

 Multiple Domains, One Cache Object
 ----------------------------------

 If you have multiple subdomains which serve the same file content, there may be
 no reason to duplicate their storage (leading to higher churn and faster
 potential eviction of still-fresh objects) in your |TS| cache. By default,
 however, the differing subdomains will lead to differing cache keys. To work
 around this, a pattern like the following can be used to create a single cache
 key which will be valid for all subdomains::

     http://s[123].example.com/(.*)  http://s.example.com.TSINTERNAL/$1

 Now, the domains ``s1.example.com``, ``s2.example.com``, and ``s3.example.com``
 will effectively share cache objects. Adding a unique suffix (``TSINTERNAL`` in
 this example) to the cache key guarantees that it won't clash with a real URL
 should s.example.com exist.

 Converting to :ref:`admin-plugins-cachekey`
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

 You could do the same with :ref:`admin-plugins-cachekey` by adding the following to the mapping rules::

     @plugin=cachekey.so @pparam=--capture-prefix=/s[123].example.com:.*/s.example.com.TSINTERNAL/


 Ignoring Some Query Parameters
 ------------------------------

 If your site attaches, for example, session information to URLs, even on pages
 which do not include session-specific content and may be safely cached, you can
 add a pattern which strips this unnecessary information from the URL before
 generating a cache key, while still retaining important query parameters::

     http://www.example.com/video\?.*?\&?(id=[0-9a-f]*).*?\&(format=[a-z]*)  http://video-srv.example.com.ATSINTERNAL/$1&$2

 Converting to :ref:`admin-plugins-cachekey`
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

 You could do the same with :ref:`admin-plugins-cachekey` by adding the following to the mapping rules::

     @plugin=cachekey.so @pparam=--include-params=id,format


 Ignore Query String on Specific Pages
 -------------------------------------

 To completely ignore a query string for a specific page, it's quite easy to
 simply match and drop everything from the ``?`` query string opener to the end
 of the URL::

     http://www.example.com/some/page(?:\?|$)  http://www.example.com/some/page

 Converting to :ref:`admin-plugins-cachekey`
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

 You could do the same with :ref:`admin-plugins-cachekey` by adding the following to the mapping rules::

     @plugin=cachekey.so @pparam=--remove-all-params
	.. 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

	.. _admin-plugins-cacheurl:

	Cache URL Plugin
	****************

	.. note::

	This plugin is deprecated as of v6.2.0 and will be removed as of v7.0.0.
	It is replaced by a new :ref:`admin-plugins-cachekey` and you should change your configurations to use the new plugin instead.
	Please find some examples below.

	This plugin allows you to change the :term:`cache key` that is used for caching
	a request by using any portion of the URL via regular expressions.

	Purpose
	=======

	By default \|TS\| generates keys for cache objects from the full request URL.
	Future requests will only be able to use the existing cache object if they
	result in the same cache key. It can be the case, however, that the same
	content is accessible through more than one request URL. Without any special
	configuration, that same content will result in multiple cache objects based on
	the differing URLs.

	In this scenario, it can be very beneficial to allow \|TS\| to reuse a cache
	object for multiple URLs. This plugin enables that behavior, by allowing the
	administrator to define custom patterns for generating cache keys for some, or
	all, of their site's URLs. Uninteresting or irrelevant portions of request URLs
	may be removed, or altered, before the cache key is created using the full
	power of regular expressions.

	Installation
	============

	This plugin is considered stable and is included with \|TS\| by default. There
	are no special steps necessary for its installation.

	.. configfile:: cacheurl.config

	Configuration
	=============

	#. Enable the plugin by modifying :file:`plugin.config` to include the plugin::

	cacheurl.so

	#. Create a ``cacheurl.config`` file in the plugin directory with the url regex
	patterns you wish to match, using the following format::

	<pattern> <replacement>

	The ``<pattern>`` is a regular expression (PCRE) applied against the
	incoming request URL. The ``<replacement>`` may contain ``$1``, ``$2``, and
	so on, which will be replaced with the appropriate matching group from
	``<pattern>``.

	#. Reload your \|TS\| configuration with :option:`traffic_ctl config reload`.

	Logging
	=======

	A new log file will be generated by this plugin, containing entries for each
	incident of an incoming URL's cache key being altered, located in the \|TS\|
	log directory and named ``cacheurl.log``.

	Examples
	========

	While many possibilities exist, limited really only by your site's URL scheme
	and the capabililties of PCRE regular expressions, the following are examples
	of a few situations \|TS\| administrators may encounter.

	Multiple Domains, One Cache Object
	----------------------------------

	If you have multiple subdomains which serve the same file content, there may be
	no reason to duplicate their storage (leading to higher churn and faster
	potential eviction of still-fresh objects) in your \|TS\| cache. By default,
	however, the differing subdomains will lead to differing cache keys. To work
	around this, a pattern like the following can be used to create a single cache
	key which will be valid for all subdomains::

	http://s[123].example.com/(.*) http://s.example.com.TSINTERNAL/$1

	Now, the domains ``s1.example.com``, ``s2.example.com``, and ``s3.example.com``
	will effectively share cache objects. Adding a unique suffix (``TSINTERNAL`` in
	this example) to the cache key guarantees that it won't clash with a real URL
	should s.example.com exist.

	Converting to :ref:`admin-plugins-cachekey`
	^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

	You could do the same with :ref:`admin-plugins-cachekey` by adding the following to the mapping rules::

	@plugin=cachekey.so @pparam=--capture-prefix=/s[123].example.com:.*/s.example.com.TSINTERNAL/


	Ignoring Some Query Parameters
	------------------------------

	If your site attaches, for example, session information to URLs, even on pages
	which do not include session-specific content and may be safely cached, you can
	add a pattern which strips this unnecessary information from the URL before
	generating a cache key, while still retaining important query parameters::

	http://www.example.com/video\?.?\&?(id=[0-9a-f]).?\&(format=[a-z]) http://video-srv.example.com.ATSINTERNAL/$1&$2

	Converting to :ref:`admin-plugins-cachekey`
	^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

	You could do the same with :ref:`admin-plugins-cachekey` by adding the following to the mapping rules::

	@plugin=cachekey.so @pparam=--include-params=id,format


	Ignore Query String on Specific Pages
	-------------------------------------

	To completely ignore a query string for a specific page, it's quite easy to
	simply match and drop everything from the ``?`` query string opener to the end
	of the URL::

	http://www.example.com/some/page(?:\?\|$) http://www.example.com/some/page

	Converting to :ref:`admin-plugins-cachekey`
	^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

	You could do the same with :ref:`admin-plugins-cachekey` by adding the following to the mapping rules::

	@plugin=cachekey.so @pparam=--remove-all-params