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