You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by js...@apache.org on 2016/02/16 01:52:12 UTC
[1/2] trafficserver git commit: Docs: remove plugin index wall-o-blue
and begin unifying plugin doc layouts
Repository: trafficserver
Updated Branches:
refs/heads/master 12033407f -> 65f4e69c6
Docs: remove plugin index wall-o-blue and begin unifying plugin doc layouts
Project: http://git-wip-us.apache.org/repos/asf/trafficserver/repo
Commit: http://git-wip-us.apache.org/repos/asf/trafficserver/commit/b30cc31d
Tree: http://git-wip-us.apache.org/repos/asf/trafficserver/tree/b30cc31d
Diff: http://git-wip-us.apache.org/repos/asf/trafficserver/diff/b30cc31d
Branch: refs/heads/master
Commit: b30cc31dccd7de00f4d15dd37e06e0174d84fcd2
Parents: 1203340
Author: Jon Sime <js...@apache.org>
Authored: Tue Feb 16 00:50:57 2016 +0000
Committer: Jon Sime <js...@apache.org>
Committed: Tue Feb 16 00:50:57 2016 +0000
----------------------------------------------------------------------
doc/admin-guide/files/records.config.en.rst | 6 +-
doc/admin-guide/files/storage.config.en.rst | 2 +-
doc/admin-guide/introduction.en.rst | 3 +-
doc/admin-guide/plugins/authproxy.en.rst | 2 +-
doc/admin-guide/plugins/background_fetch.en.rst | 2 +-
doc/admin-guide/plugins/balancer.en.rst | 2 +-
doc/admin-guide/plugins/buffer_upload.en.rst | 2 +-
doc/admin-guide/plugins/cache_promote.en.rst | 6 +-
doc/admin-guide/plugins/cachekey.en.rst | 7 +-
doc/admin-guide/plugins/cacheurl.en.rst | 133 ++++++++++-----
doc/admin-guide/plugins/combo_handler.en.rst | 6 +-
doc/admin-guide/plugins/conf_remap.en.rst | 139 +++++++++++----
doc/admin-guide/plugins/epic.en.rst | 2 +-
doc/admin-guide/plugins/esi.en.rst | 2 +-
doc/admin-guide/plugins/generator.en.rst | 2 +-
doc/admin-guide/plugins/geoip_acl.en.rst | 2 +-
doc/admin-guide/plugins/gzip.en.rst | 171 +++++++++++++------
doc/admin-guide/plugins/healthchecks.en.rst | 6 +-
doc/admin-guide/plugins/hipes.en.rst | 4 +-
doc/admin-guide/plugins/index.en.rst | 161 +++++++++++++----
doc/admin-guide/plugins/memcache.en.rst | 4 +-
doc/admin-guide/plugins/metalink.en.rst | 2 +-
doc/admin-guide/plugins/mp4.en.rst | 4 +-
doc/admin-guide/plugins/mysql_remap.en.rst | 2 +-
doc/admin-guide/plugins/regex_remap.en.rst | 37 ++--
doc/admin-guide/plugins/s3_auth.en.rst | 2 +-
doc/admin-guide/plugins/sslheaders.en.rst | 6 +-
.../plugins/stale_while_revalidate.en.rst | 6 +-
doc/admin-guide/plugins/tcpinfo.en.rst | 10 +-
doc/admin-guide/plugins/ts_lua.en.rst | 2 +-
doc/admin-guide/plugins/xdebug.en.rst | 2 +-
doc/appendices/command-line/traffic_via.en.rst | 2 +-
.../documentation/plugins.en.rst | 10 ++
doc/getting-started/index.en.rst | 10 +-
34 files changed, 522 insertions(+), 237 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/b30cc31d/doc/admin-guide/files/records.config.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/files/records.config.en.rst b/doc/admin-guide/files/records.config.en.rst
index b5fedb9..4dc3bc6 100644
--- a/doc/admin-guide/files/records.config.en.rst
+++ b/doc/admin-guide/files/records.config.en.rst
@@ -55,7 +55,7 @@ A variable marked as ``Reloadable`` can be updated via the command::
traffic_ctl config reload
A variable marked as ``Overridable`` can be changed on a per-remap basis using plugins
-(like the :ref:`conf-remap-plugin`).
+(like the :ref:`admin-plugins-conf-remap`).
``INT`` type configurations are expressed as any normal integer,
e.g. *32768*. They can also be expressed using more human readable values
@@ -1296,6 +1296,8 @@ Congestion Control
When enabled >= (``0``), Traffic Server will enforce a maximum number of simultaneous websocket connections.
+.. _admin-negative-response-caching:
+
Negative Response Caching
=========================
@@ -1804,6 +1806,8 @@ RAM Cache
Compression runs on task threads. To use more cores for RAM cache compression, increase :ts:cv:`proxy.config.task_threads`.
+.. _admin-heuristic-expiration:
+
Heuristic Expiration
====================
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/b30cc31d/doc/admin-guide/files/storage.config.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/files/storage.config.en.rst b/doc/admin-guide/files/storage.config.en.rst
index 1c958ba..6701830 100644
--- a/doc/admin-guide/files/storage.config.en.rst
+++ b/doc/admin-guide/files/storage.config.en.rst
@@ -81,7 +81,7 @@ supported. They include
Assignment Table
----------------
-Each storage element defined in :file:`storage.config` is divided in to :term:`stripes`. The
+Each storage element defined in :file:`storage.config` is divided in to :term:`stripes <cache stripe>`. The
assignment table maps from an object URL to a specific stripe. The table is initialized based on a
pseudo-random process which is seeded by hashing a string for each stripe. This string is composed
of a base string, an offset (the start of the stripe on the storage element), and the length of the
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/b30cc31d/doc/admin-guide/introduction.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/introduction.en.rst b/doc/admin-guide/introduction.en.rst
index 5a13503..84730c3 100644
--- a/doc/admin-guide/introduction.en.rst
+++ b/doc/admin-guide/introduction.en.rst
@@ -103,7 +103,8 @@ 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`.
+* Load Balancing - note that there is an experimental plugin for this,
+:ref:`admin-plugins-balancer`.
.. 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
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/b30cc31d/doc/admin-guide/plugins/authproxy.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/plugins/authproxy.en.rst b/doc/admin-guide/plugins/authproxy.en.rst
index d4a5e19..95f262b 100644
--- a/doc/admin-guide/plugins/authproxy.en.rst
+++ b/doc/admin-guide/plugins/authproxy.en.rst
@@ -1,4 +1,4 @@
-.. _authproxy-plugin:
+.. _admin-plugins-authproxy:
AuthProxy Plugin
****************
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/b30cc31d/doc/admin-guide/plugins/background_fetch.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/plugins/background_fetch.en.rst b/doc/admin-guide/plugins/background_fetch.en.rst
index 7826884..0ff4cdd 100644
--- a/doc/admin-guide/plugins/background_fetch.en.rst
+++ b/doc/admin-guide/plugins/background_fetch.en.rst
@@ -1,4 +1,4 @@
-.. _background-fetch-plugin:
+.. _admin-plugins-background-fetch:
Background Fetch Plugin
***********************
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/b30cc31d/doc/admin-guide/plugins/balancer.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/plugins/balancer.en.rst b/doc/admin-guide/plugins/balancer.en.rst
index b156028..a9cd211 100644
--- a/doc/admin-guide/plugins/balancer.en.rst
+++ b/doc/admin-guide/plugins/balancer.en.rst
@@ -1,4 +1,4 @@
-.. _balancer-plugin:
+.. _admin-plugins-balancer:
Balancer Plugin
***************
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/b30cc31d/doc/admin-guide/plugins/buffer_upload.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/plugins/buffer_upload.en.rst b/doc/admin-guide/plugins/buffer_upload.en.rst
index 7ae04bd..3513936 100644
--- a/doc/admin-guide/plugins/buffer_upload.en.rst
+++ b/doc/admin-guide/plugins/buffer_upload.en.rst
@@ -1,4 +1,4 @@
-.. _buffer-upload-plugin:
+.. _admin-plugins-buffer-upload:
Buffer Upload Plugin
********************
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/b30cc31d/doc/admin-guide/plugins/cache_promote.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/plugins/cache_promote.en.rst b/doc/admin-guide/plugins/cache_promote.en.rst
index 657acc1..c297b1c 100644
--- a/doc/admin-guide/plugins/cache_promote.en.rst
+++ b/doc/admin-guide/plugins/cache_promote.en.rst
@@ -15,10 +15,10 @@
specific language governing permissions and limitations
under the License.
-.. _cache-promote-plugin:
+.. _admin-plugins-cache-promote:
-cache_promote Plugin
-====================
+Cache Promote Plugin
+********************
The `cache_promote` plugin provides a means to control when an object should
be allowed to enter the cache. This is orthogonal from normal Cache-Control
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/b30cc31d/doc/admin-guide/plugins/cachekey.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/plugins/cachekey.en.rst b/doc/admin-guide/plugins/cachekey.en.rst
index 294348c..51310d7 100644
--- a/doc/admin-guide/plugins/cachekey.en.rst
+++ b/doc/admin-guide/plugins/cachekey.en.rst
@@ -1,4 +1,5 @@
-.. _cachekey-plugin:
+.. _admin-plugins-cachekey:
+
.. 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
@@ -17,8 +18,8 @@
under the License.
-Cache Key Manipulation (cachekey)
----------------------------------------
+Cache Key Manipulation Plugin
+*****************************
Description
===========
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/b30cc31d/doc/admin-guide/plugins/cacheurl.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/plugins/cacheurl.en.rst b/doc/admin-guide/plugins/cacheurl.en.rst
index 1ad35bf..1c176f5 100644
--- a/doc/admin-guide/plugins/cacheurl.en.rst
+++ b/doc/admin-guide/plugins/cacheurl.en.rst
@@ -1,78 +1,121 @@
-.. _cacheurl-plugin:
-
-CacheURL Plugin
-***************
-
.. 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.
+
+.. include:: ../../common.defs
+
+.. _admin-plugins-cacheurl:
+
+Cache URL Plugin
+****************
+
+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.
-This plugin allows you to change the key that is used for caching a
-request by using any portion of the url via regex. It is designed so that multiple requests that have different
-URLs but the same content (for example, site mirrors) need be cached
-only once.
+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 only built if the configure option ::
+This plugin is considered stable and is included with |TS| by default. There
+are no special steps necessary for its installation.
- --enable-experimental-plugins
-
-is given at build time.
+.. configfile:: cacheurl.config
Configuration
=============
-Create a ``cacheurl.config`` file in the plugin directory with the url
-regex patterns to match.
+#. Enable the plugin by modifying :file:`plugin.config` to include the plugin::
+
+ cacheurl.so
-``url_pattern cache_key_replacement``
+#. 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 url_pattern is a regular expression (pcre). The replacement can contain $1, $2 and so on, which will be replaced with the appropriate matching group from the pattern.
+ 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>``.
-Add the plugin to your :file:`plugin.config` file::
+#. Reload your |TS| configuration with :option:`traffic_ctl reload`.
- cacheurl.so
+Logging
+=======
-Start traffic server. Any rewritten URLs will be written to
-``cacheurl.log`` in the log directory by default.
+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
========
-1. To make files from s1.example.com, s2.example.com and s3.example.com all be cached with the same key. 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.
- ``http://s[123].example.com/(.*) http://s.example.com.TSINTERNAL/$1``
+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.
-2. Cache based on only some parts of a query string (e.g. ignore session information). This plucks out the id and format query string variables and only considers those when making the cache key.
+Multiple Domains, One Cache Object
+----------------------------------
- ``http://www.example.com/video\?.*?\&?(id=[0-9a-f]*).*?\&(format=[a-z]*) http://video-srv.example.com.ATSINTERNAL/$1&$2``
+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::
-3. Completely ignore a query string for a specific page
+ http://s[123].example.com/(.*) http://s.example.com.TSINTERNAL/$1
- ``http://www.example.com/some/page.html(?:\?|$) http://www.example.com/some/page.html``
+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.
-More docs
-=============
+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
+
+Ignore Query String on Specific Pages
+-------------------------------------
-There are some docs on cacheurl in Chinese, please find them in the following:
+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://people.apache.org/~zym/trafficserver/cacheurl.html`` <http://people.apache.org/~zym/trafficserver/cacheurl.html>`_
+ http://www.example.com/some/page(?:\?|$) http://www.example.com/some/page
-https://blog.zymlinux.net/index.php/archives/195
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/b30cc31d/doc/admin-guide/plugins/combo_handler.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/plugins/combo_handler.en.rst b/doc/admin-guide/plugins/combo_handler.en.rst
index f851be6..be07ea4 100644
--- a/doc/admin-guide/plugins/combo_handler.en.rst
+++ b/doc/admin-guide/plugins/combo_handler.en.rst
@@ -1,7 +1,7 @@
-.. _combo-handler-plugin:
+.. _admin-plugins-combo-handler:
-Combohandler Plugin
-*******************
+Combo Handler Plugin
+********************
.. Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/b30cc31d/doc/admin-guide/plugins/conf_remap.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/plugins/conf_remap.en.rst b/doc/admin-guide/plugins/conf_remap.en.rst
index bcd974a..1cd19da 100644
--- a/doc/admin-guide/plugins/conf_remap.en.rst
+++ b/doc/admin-guide/plugins/conf_remap.en.rst
@@ -1,51 +1,120 @@
.. 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.
-.. _conf-remap-plugin:
+ 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.
-conf_remap Plugin
-=================
+.. include:: ../../common.defs
-The `conf_remap` plugin allows you to override configuration
-directives dependent on actual remapping rules. The plugin is built
-and installed as part of the normal Apache Traffic Server installation
-process.
+.. _admin-plugins-conf-remap:
-The `conf_remap` plugin accepts configuration directives in the
-arguments list or in a separate configuration file. In both cases,
-only string and integer directives are supported.
+Configuration Remap Plugin
+**************************
-When using a separate configuration file, the standard
-:file:`records.config` syntax is used, for example::
+This plugin allows you to override configuration directives dependent on
+remapping rules.
- map http://cdn.example.com/ http://some-server.example.com \
- @plugin=conf_remap.so @pparam=/etc/trafficserver/cdn.conf
+Purpose
+=======
+
+|TS| provides a plethora of configuration options, but specifying the values of
+those options in :file:`records.config` is global. All requests, regardless of
+the cache object or its origin, will be evaluated within the same collection of
+settings. Sometimes you may want |TS| to behave differently for portions of
+your cache.
+
+Perhaps you have :ref:`admin-negative-response-caching` enabled, but you wish
+to greatly reduce the validity times for just one of your origin servers while
+allowing the rest of your origins to have their errors cached for long
+durations.
+
+Or maybe you make use of :ref:`admin-heuristic-expiration` but require
+different fuzz times for various objects because of the nature of their content
+and expected lifetimes.
+
+Any configuration directive which is overridable can be modified on a per-map
+basis with this plugin. This opens up a level of flexibility in your
+configurations for effectively managing and caching content with varied needs,
+without having to resort to multiple |TS| instances.
+
+Installation
+============
+
+This plugin is considered stable and is included with |TS| by default. There
+are no special steps necessary for its installation.
+
+Configuration
+=============
+
+Configuration of this plugin is performed alongside the actual remapping rules
+which trigger the desired configuration directive changes. There are two
+methods available for specifying the actual directives and their modified
+values.
+
+Inline Directives
+-----------------
-where `cdn.conf` contains::
+In cases where you have very few remapping rules which modify directives, and
+they are modifying only a small number of directives, you may find it easiest
+to simply specify those directive changes in-line with your remapping rules.
+This is done by specifying *key* = *value* pairs, where the key is the
+configuration directive name and the value is its desired setting for the
+remapping rule.
+
+For example, the enable :ts:cv:`proxy.config.url_remap.pristine_host_hdr` for a
+single `map` rule, you would add the following to your :file:`remap.config`::
+
+ map http://cdn.example.com/ http://origin.example.com/ \
+ @plugin=conf_remap.so @pparam=proxy.config.url_remap.pristine_host_hdr=1
+
+External Configuration
+----------------------
+
+There may be situations in which you have many directives you wish to modify, or
+where multiple remapping rules perform the same directive changes. External
+configurations can simplify management of these rules, and help to reduce the
+possibility of transcription errors, or keeping all the directive settings in
+sync across all the remapping rules over time.
+
+Instead of specifying the directives and their values in :file:`remap.config`
+as you do with the in-line method, you place all the affected directives in a
+separate text file. The location and name is entirely up to you, but we'll use
+`/etc/trafficserver/cdn_conf_remap.config` here. The contents of this file
+should mirror how configuration directives are written in :file:`records.config`::
CONFIG proxy.config.url_remap.pristine_host_hdr INT 1
-When using inline arguments, the `conf_remap` plugin accepts a
-``key=value`` syntax, where the ``KEY`` is the name of the configuration
-directive and ``VALUE`` is the desired value, for example::
+Your :file:`remap.config` will then contain remapping rules that point to this
+external file::
map http://cdn.example.com/ http://some-server.example.com \
- @plugin=conf_remap.so @pparam=proxy.config.url_remap.pristine_host_hdr=1
+ @plugin=conf_remap.so @pparam=/etc/trafficserver/cdn_conf_remap.config
+
+Your external configuration may contain as many directives as you wish.
+
+Caveats
+=======
+
+This plugin can only modify the values for those configuration directives which
+are *overridable*, meaning they are not fixed upon |TS| startup. While this
+generally shouldn't prove too onerous a restriction, you should consult the
+individual directives' documentation to confirm whether they may be overridden.
+
+Further Reading
+===============
+
+For more information about the implementation of overridable configuration
+directives, you may consult the developer's documentation for
+:ref:`ts-overridable-config`.
-Doing this, you will override your global default configuration on
-a per mapping rule. For more details on the APIs, functionality, and a
-complete list of all overridable configurations, see :ref:`ts-overridable-config`.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/b30cc31d/doc/admin-guide/plugins/epic.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/plugins/epic.en.rst b/doc/admin-guide/plugins/epic.en.rst
index dcc74b3..ee3fa1a 100644
--- a/doc/admin-guide/plugins/epic.en.rst
+++ b/doc/admin-guide/plugins/epic.en.rst
@@ -1,4 +1,4 @@
-.. _epic-plugin:
+.. _admin-plugins-epic:
Epic Plugin
***********
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/b30cc31d/doc/admin-guide/plugins/esi.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/plugins/esi.en.rst b/doc/admin-guide/plugins/esi.en.rst
index 5d1cdf5..8215b68 100644
--- a/doc/admin-guide/plugins/esi.en.rst
+++ b/doc/admin-guide/plugins/esi.en.rst
@@ -1,4 +1,4 @@
-.. _esi-plugin:
+.. _admin-plugins-esi:
ESI Plugin
**********
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/b30cc31d/doc/admin-guide/plugins/generator.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/plugins/generator.en.rst b/doc/admin-guide/plugins/generator.en.rst
index 28fadb3..523bb0c 100644
--- a/doc/admin-guide/plugins/generator.en.rst
+++ b/doc/admin-guide/plugins/generator.en.rst
@@ -1,4 +1,4 @@
-.. _generator-plugin:
+.. _admin-plugins-generator:
Generator Plugin
****************
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/b30cc31d/doc/admin-guide/plugins/geoip_acl.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/plugins/geoip_acl.en.rst b/doc/admin-guide/plugins/geoip_acl.en.rst
index 15b46ad..cd1f96e 100644
--- a/doc/admin-guide/plugins/geoip_acl.en.rst
+++ b/doc/admin-guide/plugins/geoip_acl.en.rst
@@ -1,4 +1,4 @@
-.. _geoip-acl-plugin:
+.. _admin-plugins-geoip-acl:
GeoIP ACLs Plugin
*****************
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/b30cc31d/doc/admin-guide/plugins/gzip.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/plugins/gzip.en.rst b/doc/admin-guide/plugins/gzip.en.rst
index bf93688..51a55f3 100644
--- a/doc/admin-guide/plugins/gzip.en.rst
+++ b/doc/admin-guide/plugins/gzip.en.rst
@@ -1,84 +1,143 @@
-.. _gzip-plugin:
-
-gzip / deflate Plugin
-*********************
-
.. 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.
+
+.. include:: ../../common.defs
+
+.. _admin-plugins-gzip:
+
+GZip Plugin
+***********
+
+This plugin adds compression and decompression options to both origin and cache
+responses.
-This plugin gzips or deflates responses, whichever is applicable. It can
-compress origin respones as well as cached responses. The plugin is built
-and installed as part of the normal Apache Traffic Server installation
-process.
+Purpose
+=======
+
+Not all clients can handle compressed content. Not all origin servers are
+configured to respond with compressed content when a client says it can accept
+it. And it's not always necessary to make two separate requests to an origin,
+and track two separate cache objects, for the same content - once for a
+compressed version and another time for an uncompressed version.
+
+This plugin tidies up these problems by transparently compressing or deflating
+origin responses, as necessary, so that both variants of a response are stored
+as :term:`alternates <alternate>` and the appropriate version is used for client responses,
+depending on the client's indication (via an ``Accept`` request header) of what
+it can support.
+
+Additionally, this plugin adds configurability for what types of origin
+responses will receive this treatment, which will be proxied and cached with
+default behavior, and which may be explicitly disallowed to cache both
+compressed and deflated versions (because, for example, the cost of compression
+is known ahead of time to outweigh the space and bandwidth savings and you wish
+to avoid |TS| even testing for the possibility).
Installation
============
-Add the following line to :file:`plugin.config`::
+This plugin is considered stable and is included with |TS| by default. There
+are no special steps necessary for its installation.
+
+Configuration
+=============
+
+This plugin is enabled globally for |TS| by adding the following to your
+:file:`plugin.config`::
gzip.so
-In this case, the plugin will use the default behaviour:
+With no further options, this will enable the following default behavior:
-- Enable caching
-- Compress text/\* for every origin
-- Don't hide accept encoding from origin servers (for an offloading
- reverse proxy)
-- No urls are disallowed from compression
-- Disable flush (flush gzipped content to client)
+- Enable caching of both compressed and uncompressed versions of origin
+ responses as :term:`alternates <alternate>`.
-Configuration
-=============
+- Compress objects with `text/*` content types for every origin.
+
+- Don't hide `Accept` encoding headers from origin servers (for an offloading
+ reverse proxy).
+
+- No URLs are disallowed from compression.
+
+- Disable flush (flush gzipped content to client).
-Alternatively, a configuration can also be specified::
+Alternatively, a configuration may be specified (shown here using the sample
+configuration provided with the plugin's source)::
gzip.so <path-to-plugin>/sample.gzip.config
-After modifying plugin.config, restart traffic server (sudo traffic_ctl
-server restart) the configuration is also re-read when a management
-update is given (sudo traffic_ctl config reload)
+The following sections detail the options you may specify in the plugin's
+configuration file. Options may be used globally, or may be specified on a
+per-site basis by preceding them with a `[<site>]` line, where `<site>` is the
+client-facing domain for which the options should apply.
-Options
-=======
+cache
+-----
+
+When set to ``true``, causes |TS| to cache both the compressed and uncompressed
+versions of the content as :term:`alternates <alternate>`. When set to
+``false``, |TS| will cache only the compressed or decompressed variant returned
+by the origin. Enabled by default.
+
+compressible-content-type
+-------------------------
-Flags and options are:
+Provides a wildcard to match against content types, determining which are to be
+considered compressible. This defaults to ``text/*``.
-``enabled``: (``true`` or ``false``) Enable or disable compression for a
-host.
+disallow
+--------
-``remove-accept-encoding``: (``true`` or ``false``) Sets whether the
-plugin should hide the accept encoding from origin servers:
+Provides a wildcard pattern which will be applied to request URLs. Any which
+match the pattern will be considered uncompressable, and only deflated versions
+of the objects will be cached and returned to clients. This may be useful for
+objects which already have their own compression built-in, to avoid the expense
+of multiple rounds of compression for trivial gains.
-- To ease the load on the origins.
-- For when the proxy parses responses, and the resulting
- compression/decompression is wasteful.
+enabled
+-------
-``cache``: (``true`` or ``false``) When set, the plugin stores the
-uncompressed and compressed response as alternates.
+When set to ``true`` permits objects to be compressed, and when ``false``
+effectively disables the plugin in the current context.
-``compressible-content-type``: Wildcard pattern for matching
-compressible content types.
+flush
+-----
-``disallow``: Wildcard pattern for disabling compression on urls.
+Enables (``true``) or disables (``false``) flushing of compressed objects to
+clients.
-``flush``: (``true`` or ``false``) Enable or disable flushing of gzipped content.
+remove-accept-encoding
+----------------------
-Options can be set globally or on a per-site basis, as such::
+When set to ``true`` this option causes the plugin to strip the request's
+``Accept`` encoding header when contacting the origin server. Setting this option to ``false``
+will leave the header intact if the client provided it.
+
+- To ease the load on the origins.
+
+- For when the proxy parses responses, and the resulting compression and
+ decompression is wasteful.
+
+Examples
+========
+
+To establish global defaults for all site requests passing through |TS|, while
+overriding just a handful for requests to content at ``www.example.com``, you
+might create a configuration with the following options::
# Set some global options first
cache true
@@ -94,4 +153,8 @@ Options can be set globally or on a per-site basis, as such::
disallow /notthis/*.js
flush true
-See example.gzip.config for example configurations.
+Assuming the above options are in a file at ``/etc/trafficserver/gzip.config``
+the plugin would be enabled for |TS| in :file:`plugin.config` as::
+
+ gzip.so /etc/trafficserver/gzip.config
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/b30cc31d/doc/admin-guide/plugins/healthchecks.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/plugins/healthchecks.en.rst b/doc/admin-guide/plugins/healthchecks.en.rst
index a89b630..7c5182a 100644
--- a/doc/admin-guide/plugins/healthchecks.en.rst
+++ b/doc/admin-guide/plugins/healthchecks.en.rst
@@ -17,10 +17,10 @@
.. include:: ../../common.defs
-.. _healthcheck-plugin:
+.. _admin-plugins-healthchecks:
-Health Check Plugin
-*******************
+Health Checks Plugin
+********************
This is a simple plugin, to provide basic (but configurable) health checks.
This is a server intercept plugin, and it takes one single configuration
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/b30cc31d/doc/admin-guide/plugins/hipes.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/plugins/hipes.en.rst b/doc/admin-guide/plugins/hipes.en.rst
index 6248a9c..cc2651d 100644
--- a/doc/admin-guide/plugins/hipes.en.rst
+++ b/doc/admin-guide/plugins/hipes.en.rst
@@ -1,6 +1,6 @@
-.. _hipes-plugin:
+.. _admin-plugins-hipes:
-HIPES plugin
+HIPES Plugin
************
.. Licensed to the Apache Software Foundation (ASF) under one
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/b30cc31d/doc/admin-guide/plugins/index.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/plugins/index.en.rst b/doc/admin-guide/plugins/index.en.rst
index 2df8e45..5745a4d 100644
--- a/doc/admin-guide/plugins/index.en.rst
+++ b/doc/admin-guide/plugins/index.en.rst
@@ -43,23 +43,49 @@ Stable plugins
Plugins that are considered stable are installed by default in |TS| releases.
.. toctree::
- :maxdepth: 1
+ :hidden:
- CacheURL: allows you to change the key that is used for caching a request by using any portion of the url via regex <cacheurl.en>
- Configuration Remap: allows you to override configuration directives dependent on actual remapping rules <conf_remap.en>
- GZip: gzips or deflates responses <gzip.en>
- Header Rewrite: allows you to modify various headers based on defined rules (operations) on a request or response <header_rewrite.en>
- Health Checks: allows you to define health check links <healthchecks.en>
- Regex Remap: allows you to configure mapping rules based on regular expressions <regex_remap.en>
- Stats over HTTP: implements an HTTP interface to all Traffic Server statistics <stats_over_http.en>
- TCPInfo: logs TCP metrics at various points in the HTTP processing pipeline <tcpinfo.en>
+ Cache URL <cacheurl.en>
+ Configuration Remap <conf_remap.en>
+ GZip <gzip.en>
+ Header Rewrite <header_rewrite.en>
+ Health Checks <healthchecks.en>
+ Regex Remap <regex_remap.en>
+ Stats over HTTP <stats_over_http.en>
+ TCPInfo <tcpinfo.en>
+
+:doc:`Cache URL <cacheurl.en>`
+ Modify the :term:`cache key` used for requests by applying a regular
+ expression to the URL.
+
+:doc:`Configuration Remap <conf_remap.en>`
+ Override configuration directives on a per-rule basis.
+
+:doc:`GZip <gzip.en>`
+ Compress or deflate cache responses.
+
+:doc:`Header Rewrite <header_rewrite.en>`
+ Modify requests and responses based on incoming and outgoing headers and
+ other transaction attributes.
+
+:doc:`Health Checks <healthchecks.en>`
+ Define service health check links.
+
+:doc:`Regex Remap <regex_remap.en>`
+ Configure remapping rules using regular expressions.
+
+:doc:`Stats over HTTP <stats_over_http.en>`
+ Provide an HTTP interface to all |TS| statistics.
+
+:doc:`TCPInfo <tcpinfo.en>`
+ Log TCP metrics at various points of the HTTP processing pipeline.
Experimental plugins
====================
Plugins that are considered experimental are located in the
`plugins/experimental <https://git-wip-us.apache.org/repos/asf?p=trafficserver.git;a=tree;f=plugins/experimental;hb=HEAD>`_
-directory of the Apache Traffic Server source tree. Experimental plugins can be compiled by passing the
+directory of the |TS| source tree. Experimental plugins can be compiled by passing the
`--enable-experimental-plugins` option to `configure`::
$ autoconf -i
@@ -67,27 +93,94 @@ directory of the Apache Traffic Server source tree. Experimental plugins can be
$ make
.. toctree::
- :maxdepth: 1
-
- AWS S3 Authentication: provides support for the Amazon S3 authentication features <s3_auth.en>
- AuthProxy: delegates the authorization decision of a request to an external HTTP service <authproxy.en>
- Background Fetch: allows you to proactively fetch content from Origin in a way that it will fill the object into cache <background_fetch.en>
- Balancer: balances requests across multiple origin servers <balancer.en>
- Buffer Upload: buffers POST data before connecting to the Origin server <buffer_upload.en>
- Cache Promotion: provides additional control over when an object should be allowed into the cache <cache_promote.en>
- Cachekey: allows some common cache key manipulations based on various HTTP request elements <cachekey.en>
- Combo Handler: provides an intelligent way to combine multiple URLs into a single URL, and have Apache Traffic Server combine the components into one response <combo_handler.en>
- ESI: implements the ESI specification <esi.en>
- Epic: emits Traffic Server metrics in a format that is consumed tby the Epic Network Monitoring System <epic.en>
- Generator: generate arbitrary response data <generator.en>
- GeoIP ACLs: denying (or allowing) requests based on the source IP geo-location <geoip_acl.en>
- MP4: mp4 streaming media <mp4.en>
- Memcache: implements the memcache protocol for cache contents <memcache.en>
- Metalink: implements the Metalink download description format in order to try not to download the same file twice. <metalink.en>
- MySQL Remap: allows dynamic “remaps” from a database <mysql_remap.en>
- SSL Headers: Populate request headers with SSL session information <sslheaders.en>
- XDebug: allows HTTP clients to debug the operation of the Traffic Server cache using the X-Debug header <xdebug.en>
- hipes.en
- stale_while_revalidate.en
- ts-lua: allows plugins to be written in Lua instead of C code <ts_lua.en>
- Signed URLs: adds support for verifying URL signatures for incoming requests to either deny or redirect access <url_sig.en>
+ :hidden:
+
+ AuthProxy <authproxy.en>
+ AWS S3 Authentication <s3_auth.en>
+ Background Fetch <background_fetch.en>
+ Balancer <balancer.en>
+ Buffer Upload <buffer_upload.en>
+ Cache Key Manipulation <cachekey.en>
+ Cache Promote <cache_promote.en>
+ Combo Handler <combo_handler.en>
+ Epic <epic.en>
+ ESI <esi.en>
+ Generator <generator.en>
+ GeoIP ACL <geoip_acl.en>
+ HIPES <hipes.en>
+ Memcache <memcache.en>
+ Metalink <metalink.en>
+ MP4 <mp4.en>
+ MySQL Remap <mysql_remap.en>
+ Signed URLs <url_sig.en>
+ SSL Headers <sslheaders.en>
+ Stale While Revalidate <stale_while_revalidate.en>
+ TS Lua <ts_lua.en>
+ X-Debug <xdebug.en>
+
+:doc:`AuthProxy <authproxy.en>`
+ Delegates the authorization decision of a request to an external HTTP service.
+
+:doc:`AWS S3 Authentication <s3_auth.en>`
+ Support for Amazon S3 authentication features.
+
+:doc:`Background Fetch <background_fetch.en>`
+ Proactively fetch content from Origin in a way that it will fill the object into cache.
+
+:doc:`Balancer <balancer.en>`
+ Balances requests across multiple origin servers.
+
+:doc:`Buffer Upload <buffer_upload.en>`
+ Buffers POST data before connecting to the Origin server.
+
+:doc:`Cache Key Manipulation <cachekey.en>`
+ Allows some common cache key manipulations based on various HTTP request elements.
+
+:doc:`Cache Promote <cache_promote.en>`
+ Provides additional control over when an object should be allowed into the cache.
+
+:doc:`Combo Handler <combo_handler.en>`
+ Provides an intelligent way to combine multiple URLs into a single URL, and have Apache Traffic Server combine the components into one response.
+
+:doc:`Epic <epic.en>`
+ Emits Traffic Server metrics in a format that is consumed tby the Epic Network Monitoring System.
+
+:doc:`ESI <esi.en>`
+ Implements the Edge Side Includes (ESI) specification.
+
+:doc:`Generator <generator.en>`
+ Generate arbitrary response data.
+
+:doc:`GeoIP ACL <geoip_acl.en>`
+ Deny or allow requests based on the source IP geo-location.
+
+:doc:`HIPES <hipes.en>`
+ Adds support for HTTP Pipes.
+
+:doc:`Memcache <memcache.en>`
+ Implements the memcache protocol for cache contents.
+
+:doc:`Metalink <metalink.en>`
+ Implements the Metalink download description format in order to try not to download the same file twice.
+
+:doc:`MP4 <mp4.en>`
+ MP4 streaming media.
+
+:doc:`MySQL Remap <mysql_remap.en>`
+ Allows dynamic remaps from a MySQL database.
+
+:doc:`Signed URLs <url_sig.en>`
+ Adds support for verifying URL signatures for incoming requests to either deny or redirect access.
+
+:doc:`SSL Headers <sslheaders.en>`
+ Populate request headers with SSL session information.
+
+:doc:`Stale While Revalidate <stale_while_revalidate.en>`
+ Refresh content asynchronously while serving stale data.
+
+:doc:`TS Lua <ts_lua.en>`
+ Allows plugins to be written in Lua instead of C code.
+
+:doc:`X-Debug <xdebug.en>`
+ Allows HTTP clients to debug the operation of the Traffic Server cache using the X-Debug header.
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/b30cc31d/doc/admin-guide/plugins/memcache.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/plugins/memcache.en.rst b/doc/admin-guide/plugins/memcache.en.rst
index 271b09b..a32e9cc 100644
--- a/doc/admin-guide/plugins/memcache.en.rst
+++ b/doc/admin-guide/plugins/memcache.en.rst
@@ -1,6 +1,6 @@
-.. _memcache-plugin:
+.. _admin-plugins-memcache:
-memcache Plugin
+Memcache Plugin
***************
.. Licensed to the Apache Software Foundation (ASF) under one
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/b30cc31d/doc/admin-guide/plugins/metalink.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/plugins/metalink.en.rst b/doc/admin-guide/plugins/metalink.en.rst
index 7b63701..e6a028a 100644
--- a/doc/admin-guide/plugins/metalink.en.rst
+++ b/doc/admin-guide/plugins/metalink.en.rst
@@ -14,7 +14,7 @@
implied. See the License for the specific language governing
permissions and limitations under the License.
-.. _metalink-plugin:
+.. _admin-plugins-metalink:
Metalink Plugin
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/b30cc31d/doc/admin-guide/plugins/mp4.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/plugins/mp4.en.rst b/doc/admin-guide/plugins/mp4.en.rst
index deddc29..d5346a2 100644
--- a/doc/admin-guide/plugins/mp4.en.rst
+++ b/doc/admin-guide/plugins/mp4.en.rst
@@ -1,7 +1,7 @@
-.. _mp4-plugin:
+.. _admin-plugins-mp4:
MP4 Plugin
-****************
+**********
.. Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/b30cc31d/doc/admin-guide/plugins/mysql_remap.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/plugins/mysql_remap.en.rst b/doc/admin-guide/plugins/mysql_remap.en.rst
index 2bb3b00..04cafda 100644
--- a/doc/admin-guide/plugins/mysql_remap.en.rst
+++ b/doc/admin-guide/plugins/mysql_remap.en.rst
@@ -1,4 +1,4 @@
-.. _mysql-remap-plugin:
+.. _admin-plugins-mysql-remap:
MySQL Remap Plugin
******************
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/b30cc31d/doc/admin-guide/plugins/regex_remap.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/plugins/regex_remap.en.rst b/doc/admin-guide/plugins/regex_remap.en.rst
index 5a11047..0b2a9f9 100644
--- a/doc/admin-guide/plugins/regex_remap.en.rst
+++ b/doc/admin-guide/plugins/regex_remap.en.rst
@@ -1,25 +1,26 @@
-.. _regex-remap-plugin:
-
-Regex Remap Plugin
-******************
-
.. 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.
+
+.. include:: ../../common.defs
+
+.. _admin-plugins-regex-remap:
+
+Regex Remap Plugin
+******************
This allows you to configure mapping rules based on regular expressions.
This is similar to what you can accomplish using mod_rewrite in Apache
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/b30cc31d/doc/admin-guide/plugins/s3_auth.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/plugins/s3_auth.en.rst b/doc/admin-guide/plugins/s3_auth.en.rst
index 38861d5..d6f5709 100644
--- a/doc/admin-guide/plugins/s3_auth.en.rst
+++ b/doc/admin-guide/plugins/s3_auth.en.rst
@@ -1,4 +1,4 @@
-.. _s3-auth-plugin:
+.. _admin-plugins-s3-auth:
AWS S3 Authentication plugin
****************************
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/b30cc31d/doc/admin-guide/plugins/sslheaders.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/plugins/sslheaders.en.rst b/doc/admin-guide/plugins/sslheaders.en.rst
index bab09c2..8fc0881 100644
--- a/doc/admin-guide/plugins/sslheaders.en.rst
+++ b/doc/admin-guide/plugins/sslheaders.en.rst
@@ -1,7 +1,7 @@
-.. _sslheaders-plugin:
+.. _admin-plugins-ssl-headers:
-SSLHeaders Plugin
-*****************
+SSL Headers Plugin
+******************
.. Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/b30cc31d/doc/admin-guide/plugins/stale_while_revalidate.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/plugins/stale_while_revalidate.en.rst b/doc/admin-guide/plugins/stale_while_revalidate.en.rst
index 108cf38..0a14f23 100644
--- a/doc/admin-guide/plugins/stale_while_revalidate.en.rst
+++ b/doc/admin-guide/plugins/stale_while_revalidate.en.rst
@@ -1,7 +1,7 @@
-.. _stale-while-revalidate-plugin:
+.. _admin-plugins-tale-while-revalidate:
-Stale While Revalidate Plugin (undocumented)
-********************************************
+Stale While Revalidate Plugin
+*****************************
.. Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/b30cc31d/doc/admin-guide/plugins/tcpinfo.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/plugins/tcpinfo.en.rst b/doc/admin-guide/plugins/tcpinfo.en.rst
index 19db046..260ac84 100644
--- a/doc/admin-guide/plugins/tcpinfo.en.rst
+++ b/doc/admin-guide/plugins/tcpinfo.en.rst
@@ -1,8 +1,3 @@
-.. _tcpinfo-plugin:
-
-TCPInfo Plugin
-**************
-
.. 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
@@ -20,6 +15,11 @@ TCPInfo Plugin
specific language governing permissions and limitations
under the License.
+.. _admin-plugins-tcpinfo:
+
+TCPInfo Plugin
+**************
+
This global plugin logs TCP metrics at various points in the HTTP
processing pipeline. The TCP information is retrieved by the
:manpage:`getsockopt(2)` function using the ``TCP_INFO`` option.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/b30cc31d/doc/admin-guide/plugins/ts_lua.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/plugins/ts_lua.en.rst b/doc/admin-guide/plugins/ts_lua.en.rst
index c6915c0..ee8e206 100644
--- a/doc/admin-guide/plugins/ts_lua.en.rst
+++ b/doc/admin-guide/plugins/ts_lua.en.rst
@@ -19,7 +19,7 @@
.. _admin-plugins-ts-lua:
-ts-lua Plugin
+TS Lua Plugin
*************
This module embeds Lua, via the standard Lua 5.1 interpreter, into |ATS|. With
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/b30cc31d/doc/admin-guide/plugins/xdebug.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/plugins/xdebug.en.rst b/doc/admin-guide/plugins/xdebug.en.rst
index 1b39159..688b290 100644
--- a/doc/admin-guide/plugins/xdebug.en.rst
+++ b/doc/admin-guide/plugins/xdebug.en.rst
@@ -17,7 +17,7 @@
.. include:: ../../common.defs
-.. _xdebug-plugin:
+.. _admin-plugins-xdebug:
XDebug Plugin
*************
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/b30cc31d/doc/appendices/command-line/traffic_via.en.rst
----------------------------------------------------------------------
diff --git a/doc/appendices/command-line/traffic_via.en.rst b/doc/appendices/command-line/traffic_via.en.rst
index 275d46e..5b966d3 100644
--- a/doc/appendices/command-line/traffic_via.en.rst
+++ b/doc/appendices/command-line/traffic_via.en.rst
@@ -72,7 +72,7 @@ Decode the Via header from command-line arguments::
Parent proxy connection status :no parent proxy or unknown
Origin server connection status :connection open failed
-Decode the Via header from a curl request, using the :ref:`X-Debug <xdebug-plugin>` plugin::
+Decode the Via header from a curl request, using the :ref:`X-Debug <admin-plugins-xdebug>` plugin::
$ curl -H "X-Debug: Via" -I http://test.example.com | traffic_via -
Via header is uScMsSf pSeN:t cCMi p sS, Length is 24
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/b30cc31d/doc/developer-guide/documentation/plugins.en.rst
----------------------------------------------------------------------
diff --git a/doc/developer-guide/documentation/plugins.en.rst b/doc/developer-guide/documentation/plugins.en.rst
index ea1532d..7abbd2d 100644
--- a/doc/developer-guide/documentation/plugins.en.rst
+++ b/doc/developer-guide/documentation/plugins.en.rst
@@ -140,3 +140,13 @@ that will be covered in the sections that follow. This, it is hoped, will get
the usual case out of the way quickly for most |TS| administrators while
limiting the paralysis of choice they may face otherwise.
+Documentation Template
+======================
+
+For the convenience of plugin developers, this manual includes a
+:ref:`plugin documentation template <developer-doc-plugin-template>` which you
+may use as a base. The template includes placeholders, with markup, for common
+features of the documentation which may be relevant for your plugin. Developers
+are very strongly encouraged to use this template whenever possible, as a means
+of producing and maintaining a consistent format for plugin documentation.
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/b30cc31d/doc/getting-started/index.en.rst
----------------------------------------------------------------------
diff --git a/doc/getting-started/index.en.rst b/doc/getting-started/index.en.rst
index 66a5cb4..5dab8f9 100644
--- a/doc/getting-started/index.en.rst
+++ b/doc/getting-started/index.en.rst
@@ -277,11 +277,11 @@ Configure Origin Location
~~~~~~~~~~~~~~~~~~~~~~~~~
The previous settings enable reverse proxying (and prevent flagrant abuse of
-it), but now |TS| needs to know what to proxy. This is achieved by writing remap
-rules, which make use of the core :ref:`conf-remap-plugin`. For our Getting
-Started guide's |AW| example scenario, we have very simple needs and want little
-more than to proxy all requests to our single origin server. This is
-accomplished with the following rule added to the :file:`remap.config`
+it), but now |TS| needs to know what to proxy. This is achieved by writing
+remap rules, which make use of the core :ref:`admin-plugins-conf-remap`. For
+our Getting Started guide's |AW| example scenario, we have very simple needs
+and want little more than to proxy all requests to our single origin server.
+This is accomplished with the following rule added to the :file:`remap.config`
configuration::
regex_map http://(.*)/ http://localhost:80/
[2/2] trafficserver git commit: Docs: updated header_rewrite plugin
documentation
Posted by js...@apache.org.
Docs: updated header_rewrite plugin documentation
Project: http://git-wip-us.apache.org/repos/asf/trafficserver/repo
Commit: http://git-wip-us.apache.org/repos/asf/trafficserver/commit/65f4e69c
Tree: http://git-wip-us.apache.org/repos/asf/trafficserver/tree/65f4e69c
Diff: http://git-wip-us.apache.org/repos/asf/trafficserver/diff/65f4e69c
Branch: refs/heads/master
Commit: 65f4e69c64916e8fd2a161ea4d9b8ec65db0d33f
Parents: b30cc31
Author: Jon Sime <js...@apache.org>
Authored: Tue Feb 16 00:51:29 2016 +0000
Committer: Jon Sime <js...@apache.org>
Committed: Tue Feb 16 00:51:29 2016 +0000
----------------------------------------------------------------------
doc/admin-guide/plugins/header_rewrite.en.rst | 1053 ++++++++++++++++----
1 file changed, 866 insertions(+), 187 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/65f4e69c/doc/admin-guide/plugins/header_rewrite.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/plugins/header_rewrite.en.rst b/doc/admin-guide/plugins/header_rewrite.en.rst
index 427b442..4e2f18e 100644
--- a/doc/admin-guide/plugins/header_rewrite.en.rst
+++ b/doc/admin-guide/plugins/header_rewrite.en.rst
@@ -1,246 +1,925 @@
-.. _header-rewrite-plugin:
+.. 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-header-rewrite:
Header Rewrite Plugin
*********************
-.. 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
+This plugin allows you to modify arbitrary headers based on defined rules, for
+both requests and responses.
- http://www.apache.org/licenses/LICENSE-2.0
+Purpose
+=======
- 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.
+Remapping an incoming client request to an origin server is at the heart of
+what we use |TS| for, but often we need to do more to requests than just change
+their destination according to simple rewriting rules against the URL.
+We may need to direct requests to different origins based on a client cookie.
-This is a plugin for Apache Traffic Server that allows you to
-modify various headers based on defined rules (operations) on a request or
-response.
+Our origins might return error response codes which are a little too customized
+and we want to condense the possible values to just the official codes.
-Using the plugin
-----------------
+We might want to strip a set of internal-use or debugging related HTTP headers
+from responses before sending them to clients, unless the original request had
+its own special header indicating that they should be retained.
+
+Or perhaps we want to redirect certain requests differently when they come from
+a known group of IP addresses (say, our developers' office network) and we have
+a file on our proxy caching servers called ``/var/developertesting``. (Stranger
+QA methods exist.)
+
+Maybe we want to deny access to a resource with an HTTP 403 if the client
+connected to |TS| over a particular port, used ``HEAD`` instead of ``GET``,
+doesn't list Spanish (Paraguay dialect) in their ``Accept-Language`` header,
+and either the origin server replied with 304 or we randomly generate an
+integer between 0 and 500 and get back anything greater than 290.
+
+These more complicated transformations of requests and responses (even that
+last one) are made possible by this plugin.
+
+Installation
+============
+
+This plugin is considered stable and is included with |TS| by default. There
+are no special steps necessary for its installation.
+
+Configuration
+=============
-This plugin can be used as both a global plugin, enabled in plugin.config::
+Header rewrite configurations, the actual conditions and operations that make
+up the activity performed by the plugin, are specified in external files and
+not in-line with the various mapping (and remapping) rules you may have
+configured for your proxy. The location of this file is arbitrary, as long as
+the |TS| processes have permissions to read it, though you may find it useful
+to keep it in the same location as your other proxy configuration files.
+
+The paths given to the configuration file(s) may be absolute (leading with a
+``/`` character), or they may be relative to the |TS| configuration directory.
+
+There are two methods for enabling this plugin, based on whether you wish it to
+operate globally on every request that passes through your proxy, or only on
+some subset of the requests by enabling it only for specific mapping rules.
+
+Enabling Globally
+-----------------
+
+This plugin may be enabled globally, so that the conditions and header
+rewriting rules are evaluated for every request made to your |TS| instance.
+This is done by adding the following line to your :file:`plugin.config`::
header_rewrite.so config_file_1.conf config_file_2.conf ...
-These are global rules, which would apply to all requests. Another option is
-to use per remap rules in remap.config::
+You may specify multiple configuration files. Their rules will be evaluated in
+the order the files are listed.
+
+Enabling Per-Mapping
+--------------------
+
+Alternatively, the plugin can be enabled for specific mapping rules, by
+modifying the relevant entries in your :file:`remap.config`::
map http://a http://b @plugin=header_rewrite.so @pparam=rules1.conf ...
-In the second example, hooks which are not to be executed during the remap
-phase (the default) causes a transaction hook to be instantiated and used
-at a later time. This allows you to setup e.g. a rule that gets executed
-during the origin response header parsing, using READ_RESPONSE_HDR_HOOK.
-Note that the remap mode of the plugin can only execute rules on hooks that
-occur at remap phase or later (e.g. SEND_REQUEST_HDR_HOOK, READ_RESPONSE_HDR_HOOK etc),
+As with the global method above, multiple configuration files may be listed,
+each with its own ``@pparam=<file>`` and their contents will be evaluated in
+the order the files were specified.
+
+Rewriting Rules
+===============
+
+Header rewriting rules consist of zero or more `Conditions`_ followed by one or
+more `Operators`_. Conditions are used to limit the requests which will be
+affected by the operator(s). Additionally, both conditions and operators may
+have flags which modify their behavior.
+
+A complete rule, consisting of two conditions and a single operator might look
+like the following::
+
+ cond %{STATUS} >399 [AND]
+ cond %{STATUS} <500
+ set-status 404
+
+Which converts any 4xx HTTP status code from the origin server to a 404. A
+response from the origin with a status of 200 would be unaffected by this rule.
+
+Conditions
+----------
+
+Conditions are used as qualifiers, causing the associated operators to only be
+evaluated if the condition(s) are met. Conditions all take the following form::
+
+ cond %{<condition name>[:<argument>]} <operand> [<flags>]
+
+Every condition begins with the literal string ``cond`` to indicate that this
+line is a condition, not an operator. This is followed by the condition name,
+inside curly braces and preceded by a percent sign (e.g. ``%{TRUE}`` for the
+condition named ``TRUE``). Some condition names take an argument. Header
+conditions, for example, take the name of the header in question, and cookie
+conditions take the name of the cookie. For these, the condition name is
+followed by a colon and the argument value (e.g. ``%{HEADER:User-Agent}`` for a
+header condition against the ``User-Agent`` header).
+
+The operand of a condition provides a value, pattern, or range against which to
+match. The format is described in `Condition Operands`_ below.
+
+Finally, a condition may optionally have various flags associated with it.
+These are described in `Condition Flags`_ below.
+
+The following sections list all of the condition types currently supported. For
+increased clarity in their usage, the optional ``[<flags>]`` portion of the
+condition is omitted from all of the examples.
+
+ACCESS
+~~~~~~
+::
+
+ cond %{ACCESS:<path>}
+
+Returns true if |TS| was able to successfully update the access time on the
+file at ``<path>``. This condition will return false if the file does not exist
+or |TS| cannot access it for any other reason.
+
+CLIENT-HEADER
+~~~~~~~~~~~~~
+::
+
+ cond %{CLIENT-HEADER:<name>} <operand>
+
+Value of the header ``<name>`` from the original client request (regardless of
+the hook context in which the rule is being evaluated). Note that some headers
+may appear in an HTTP message more than once. In these cases, the value of the
+header operated on by this condition will be a comma separated string of the
+values from every occurrence of the header. More details are provided in
+`Repeated Headers`_ below.
+
+CLIENT-IP
+~~~~~~~~~
+::
+
+ cond %{CLIENT-IP} <operand>
+
+Remote IP address, as a string, of the client connection for the current
+transaction.
+
+CLIENT-URL
+~~~~~~~~~~
+::
+
+ cond %{CLIENT-URL:<part>} <operand>
+
+The URL of the original request. Regardless of the hook context in which the
+rule is evaluated, this condition will always operate on the original, unmapped
+URL supplied by the client. The ``<part>`` may be specified according to the
+options documented in `URL Parts`_.
+
+COOKIE
+~~~~~~
+::
+
+ cond %{COOKIE:<name>} <operand>
+
+Value of of the cookie ``<name>``. This does not expose or match against a
+cookie's expiration, the domain(s) on which it is valid, whether it is protocol
+restricted, or any of the other metadata; simply the current value of the
+cookie as presented by the client.
+
+FROM-URL
+~~~~~~~~
+::
+
+ cond %{FROM-URL:<part>} <operand>
+
+In a remapping context, this condition matches against the source URL from
+which the remapping was generated. This condition is valid only within
+configurations provided through :file:`remap.config` as described in `Enabling
+Per-Mapping`_ above.
+
+The ``<part>`` allows the operand to match against just a component of the URL,
+as documented in `URL Parts`_ below.
+
+HEADER
+~~~~~~
+::
+
+ cond %{HEADER:<name>} <operand>
+
+Value of the header ``<name>`` from either the original client request or the
+origin server's response, depending upon the hook context in which the rule is
+being evaluated. Consult `Requests vs. Responses`_ for more information on how
+to distinguish the two, as well as enforce that a rule is always evaluated in
+the desired context.
-Configuration filenames without an absolute path are searched for in the
-default configuration directory. This is typically where your main
-configuration files are, e.g. ``/usr/local/etc/trafficserver``.
+Note that some headers may appear in an HTTP message more than once. In these
+cases, the value of the header operated on by this condition will be a comma
+separated string of the values from every occurrence of the header. Refer to
+`Repeated Headers`_ for more information.
+
+If you wish to use a client request header, regardless of hook context, you may
+consider using the `CLIENT-HEADER`_ condition instead.
+
+INCOMING-PORT
+~~~~~~~~~~~~~
+::
+
+ cond %{INCOMING-PORT} <operand>
+
+TCP port, as a decimal integer, on which the incoming client connection was
+made.
+
+INTERNAL-TRANSACTION
+~~~~~~~~~~~~~~~~~~~~
+::
+
+ cond %{INTERNAL-TRANSACTION}
+
+Returns true if the current transaction was internally-generated by |TS| (using
+:c:func:`TSHttpTxnIsInternal`). These transactions are not initiated by
+external client requests, but are triggered (often by plugins) entirely within
+the |TS| process.
+
+METHOD
+~~~~~~~
+::
+
+ cond %{METHOD} <operand>
+
+The HTTP method (e.g. ``GET``, ``HEAD``, ``POST``, and so on) used by the
+client for this transaction.
+
+PATH
+~~~~
+::
+
+ cond %{PATH} <operand>
+
+The path component of the transaction. This includes the leading ``/`` that
+immediately follows the hostname and terminates prior to the ``?`` signifying
+the beginning of query parameters (or the end of the URL, whichever occurs
+first).
+
+Refer to `Requests vs. Responses`_ for more information on determining the
+context in which the transaction's URL is evaluated.
+
+QUERY
+~~~~~
+::
+
+ cond %{QUERY} <operand>
+
+The query parameters, if any, of the transaction. Refer to `Requests vs.
+Responses`_ for more information on determining the context in which the
+transaction's URL is evaluated.
+
+RANDOM
+~~~~~~
+::
+
+ cond %{RANDOM:<n>} <operand>
+
+Generates a random integer between ``0`` and ``<n>``, inclusive.
+
+STATUS
+~~~~~~
+::
+
+ cond %{STATUS} <operand>
+
+Numeric HTTP status code of the response.
+
+TO-URL
+~~~~~~
+::
+
+ cond %{TO-URL:<part>} <operand>
+
+In a remapping context, this condition matches against the target URL to which
+the remapping is directed. This condition is valid only within configurations
+provided through :file:`remap.config` as described in `Enabling Per-Mapping`_
+above.
+
+The ``<part>`` allows the operand to match against just a component of the URL,
+as documented in `URL Parts`_ below.
+
+TRUE / FALSE
+~~~~~~~~~~~~
+::
+
+ cond %{TRUE}
+ cond %{FALSE}
+
+These conditions always return a true value and a false value, respectively.
+The true condition is implicit in any rules which specify no conditions (only
+operators).
+
+TXN-COUNT
+~~~~~~~~~
+::
+
+ cond %{TXN-COUNT} <operand>
+
+Returns the current HTTP client session, which permits detection of requests
+which are sharing a client session. Shared client sessions occur when multiple
+simultaneous requests are received for the same cache object. Instead of
+contacting the origin server separately for each of those client requests, one
+origin connection is used to fulfill all of the requests assigned to the shared
+client session.
+
+URL
+~~~
+::
+
+ cond %{URL:option} <operand>
+
+The complete URL of the current transaction. This will automatically choose the
+most relevant URL depending upon the hook context in which the condition is
+being evaluated.
+
+Refer to `Requests vs. Responses`_ for more information on determining the
+context in which the transaction's URL is evaluated.
+
+Condition Operands
+------------------
+
+Operands provide the means to restrict the values, provided by a condition,
+which will lead to that condition evaluating as true. There are currently four
+types supported:
+
+=========== ===================================================================
+Operand Description
+=========== ===================================================================
+/regex/ Matches the condition's provided value against the regular
+ expression.
+<string Matches if the value from the condition is lexically less than
+ *string*.
+>string Matches if the value from the condition is lexically greater than
+ *string*.
+=string Matches if the value from the condition is lexically equal to
+ *string*.
+=========== ===================================================================
+
+The absence of an operand for conditions which accept them simply requires that
+a value exists (e.g. the content of the header is not an empty string) for the
+condition to be considered true.
+
+Condition Flags
+---------------
+
+The condition flags are optional, and you can combine more than one into
+a comma-separated list of flags. Note that whitespaces are not allowed inside
+the brackets:
+
+====== ========================================================================
+Flag Description
+====== ========================================================================
+AND Indicates that both the current condition and the next must be true.
+ This is the default behavior for all conditions when no flags are
+ provided.
+NC Indicates that the condition operand should be matched case-insensitive.
+ **Not implemented.**
+NOT Inverts the condition.
+OR Indicates that either the current condition or the next one must be
+ true, as contrasted with the default behavior from ``[AND]``.
+====== ========================================================================
Operators
---------
-The following operators are available::
+Operators are the part of your header rewriting rules which actually modify the
+header content of your requests and responses. They are always the final part
+of a rule, following any of the conditions which whittled down the requests and
+responses to which they will be applied.
- rm-header header-name [operator_flags]
- add-header header <value> [operator_flags]
- set-header header <value> [operator_flags]
- set-status <status-code> [operator_flags]
- set-destination [qual] <value> [operator_flags]
- set-redirect <status-code> <destination> [operator_flags]
- set-timeout-out <value> [operator_flags]
- set-status-reason <value> [operator_flags]
- set-config overridable-config <value> [operator_flags]
- set-conn-dscp <value> [operator_flags]
- skip-remap <value> [operator_flags]
- set-debug [operator_flags]
- counter counter-name [operator_flags]
- no-op [operator_flags]
+Multiple operators may be specified for a single rule, and they will be
+executed in the order listed. The end of the rule is marked either by the end
+of the configuration file or the next appearance of a condition (whichever
+occurs first).
+The following operators are available:
-Where qual is one of the support URL qualifiers::
+add-header
+~~~~~~~~~~
+::
- HOST
- PORT
- PATH
- QUERY
- SCHEME
- URL
+ add-header <name> <value>
-For example (as a remap rule)::
+Adds a new ``<name>`` header line with the contents ``<value>``. Note that this
+operator can produce duplicate headers if one of ``<name>`` already exists, or
+your configuration supplies multiple instances of this operator in different
+rules which are all invoked. This is not an issue for headers which may safely
+be specified multiple times, such as ``Set-Cookie``, but for headers which may
+only be specified once you may prefer to use `set-header`_ instead.
- cond %{HEADER:X-Mobile} = "foo"
- set-destination HOST foo.mobile.bar.com [L]
+The header's ``<value>`` may be specified as a literal string, or it may take
+advantage of `Variable Expansion`_ to calculate a dynamic value for the header.
+In contrast, `set-header`_ does not support variable expansion for the header
+value. If you wish to use variable expansion and avoid duplicate headers, you
+may consider using an `rm-header`_ operator followed by `add-header`_.
+
+counter
+~~~~~~~
+::
+
+ counter <name>
-Operator flags
+Increments an integer counter called ``<name>`` every time the rule is invoked.
+The counter is initialized at ``0`` if it does not already exist. The name you
+give your counter is arbitrary, though it is strongly advisable to avoid
+conflicts with existing |TS| statistics.
+
+This counter can be viewed at any time through the standard statistics APIs,
+including the :ref:`Stats Over HTTP plugin <admin-plugins-stats-over-http>`.
+
+Counters can only increment by 1 each time this operator is invoked. There is
+no facility to increment by other amounts, nor is it possible to initialize the
+counter with any value other than ``0``. Additionally, the counter will reset
+whenever |TS| is restarted.
+
+no-op
+~~~~~
+::
+
+ no-op
+
+This operator does nothing, takes no arguments, and has no side effects.
+
+rm-header
+~~~~~~~~~
+::
+
+ rm-header <name>
+
+Removes the header ``<name>``.
+
+set-config
+~~~~~~~~~~
+::
+
+ set-config <name> <value>
+
+Allows you to override the value of a |TS| configuration variable for the
+current connection. The variables specified by ``<name>`` must be overridable.
+For details on available |TS| configuration variables, consult the
+documentation for :file:`records.config`. You can read more about overridable
+configuration variables in the developer's documentation for
+:ref:`ts-overridable-config`.
+
+set-conn-dscp
+~~~~~~~~~~~~~
+::
+
+ set-conn-dscp <value>
+
+When invoked, sets the client side `DSCP
+<https://en.wikipedia.org/wiki/Differentiated_services>`_ value for the current
+transaction. The ``<value>`` should be specified as a decimal integer.
+
+set-debug
+~~~~~~~~~
+::
+
+ set-debug
+
+When invoked, this operator enables the internal transaction debugging flag
+(via :c:func:`TSHttpTxnDebugSet`), which causes debug messages to be printed to
+the appropriate logs even when the debug tag has not been enabled. For
+additional information on |TS| debugging statements, refer to
+:ref:`developer-debug-tags` in the developer's documentation.
+
+set-destination
+~~~~~~~~~~~~~~~
+::
+
+ set-destination <part> <value>
+
+Modifies individual components of the remapped destination's address. When
+changing the remapped destination, ``<part>`` should be used to indicate the
+component that is being modified (see `URL Parts`_), and ``<value>`` will be
+used as its replacement. You must supply a non-zero length value, otherwise
+this operator will be an effective no-op (though a warning will be emitted to
+the logs if debugging is enabled).
+
+set-header
+~~~~~~~~~~
+::
+
+ set-header <name> <value>
+
+Replaces the value of header ``<name>`` with ``<value>``, creating the header
+if necessary.
+
+Note that, unlike `add-header`_, this operator does not currently support
+variable expansion. Values may only be specified according to `Header Values`_.
+
+set-redirect
+~~~~~~~~~~~~
+::
+
+ set-redirect <code> <destination>
+
+When invoked, sends a redirect response to the client, with HTTP status
+``<code>``, and a new location of ``<destination>``. If the ``QSA`` flag is
+enabled, the original query string will be preserved and added to the new
+location automatically. This operator supports `Variable Expansion`_ for
+``<destination>``.
+
+set-status
+~~~~~~~~~~
+::
+
+ set-status <code>
+
+Modifies the :ref:`HTTP status code <appendix-http-status-codes>` used for the
+response. ``<code>`` must be a valid status code. This operator will also
+update the reason in the HTTP response, based on the code you have chosen. If
+you wish to override that with your own text, you will need to invoke the
+`set-status-reason`_ operator after this one.
+
+set-status-reason
+~~~~~~~~~~~~~~~~~
+::
+
+ set-status-reason <reason>
+
+Modifies the HTTP response to use ``<reason>`` as the HTTP status reason,
+instead of the standard string (which depends on the :ref:`HTTP status code
+<appendix-http-status-codes>` used).
+
+set-timeout-out
+~~~~~~~~~~~~~~~
+::
+
+ set-timeout-out <type> <value>
+
+Modifies the timeout values for the current transaction to ``<value>``
+(specified in milliseconds). The ``<type>`` must be one of the following:
+``active``, ``inactive``, ``connect``, or ``dns``.
+
+skip-remap
+~~~~~~~~~~
+::
+
+ skip-remap <value>
+
+When invoked, and when ``<value>`` is any of ``1``, ``true``, or ``TRUE``, this
+operator causes |TS| to abort further request remapping. Any other value and
+the operator will effectively be a no-op.
+
+Operator Flags
--------------
-The operator flags are optional, and must not contain whitespaces inside
-the brackets. Two flags are available:
+Operator flags are optional, are separated by commas when using more than one
+for a single operator, and must not contain whitespace inside the brackets. For
+example, an operator with the ``L`` flag would be written in this manner::
+
+ set-destination HOST foo.bar.com [L]
- [L] Last rule, do not continue
- [QSA] Append query string
+The flags currently supported are:
-Variable expansion
+====== ========================================================================
+Flag Description
+====== ========================================================================
+L Last rule, do not continue.
+QSA Append the results of the rule to the query string.
+====== ========================================================================
+
+Variable Expansion
------------------
-Only limited variable expansion is supported in add-header. Supported
-substitutions include::
- %<proto> Protocol
- %<port> Port
- %<chi> Client IP
- %<cqhl> Client request length
- %<cqhm> Client HTTP method
- %<cquup> Client unmapped URI
+Only limited variable expansion is supported in `add-header`_. Supported
+substitutions are currently:
-Conditions
-----------
-The conditions are used as qualifiers: The operators specified will
-only be evaluated if the condition(s) are met::
-
- cond %{STATUS} operand [condition_flags]
- cond %{RANDOM:nn} operand [condition_flags]
- cond %{ACCESS:file} [condition_flags]
- cond %{TRUE} [condition_flags]
- cond %{FALSE} [condition_flags]
- cond %{HEADER:header-name} operand [condition_flags]
- cond %{COOKIE:cookie-name} operand [condition_flags]
- cond %{CLIENT-HEADER:header-name} operand [condition_flags]
- cond %{PATH} operand [condition_flags]
- cond %{QUERY} operand [condition_flags]
- cond %{INTERNAL-TRANSACTION} [condition_flags]
- cond %{CLIENT-IP} operand [condition_flags]
- cond %{INCOMING-PORT} operand [condition_flags]
- cond %{METHOD} operand [condition_flags]
- cond %{CLIENT-URL:option-name} operand [condition_flags]
- cond %{URL:option-name} operand [condition_flags]
- cond %{FROM-URL:option-name} operand [condition_flags]
- cond %{TO-URL:option-name} operand [condition_flags]
- cond %{TXN-COUNT} operand [condition_flags]
-
-The difference between HEADER and CLIENT-HEADER is that HEADER adapts to the
-hook it's running in, whereas CLIENT-HEADER always applies to the client
-request header. The %{TRUE} condition is also the default condition if no
-other conditions are specified.
-
-These conditions have to be first in a ruleset, and you can only have one in
-each rule. This implies that a new hook condition starts a new rule as well.::
-
- cond %{READ_RESPONSE_HDR_HOOK} (this is the default hook for global rules)
- cond %{READ_REQUEST_HDR_HOOK}
- cond %{READ_REQUEST_PRE_REMAP_HOOK}
- cond %{SEND_REQUEST_HDR_HOOK}
- cond %{SEND_RESPONSE_HDR_HOOK}
-
-For remap.config plugin instanations, the default hook is named
-REMAP_PSEUDO_HOOK. This can be useful if you are mixing other hooks in a
-configuration, but being the default it is also optional. This hook is
-executed directly as part of the remapping phase.
-
-Note that for configurations that are global, i.e. setup via
-``plugin.config``, the default hook is READ_RESPONSE_HDR_HOOK.
-
-CLIENT-URL, URL, URL-FROM, and URL-TO
--------------------------------------
-URL adapts to the hook it's running in and CLIENT-URL will always give you
-the client URL. FROM-URL and TO-URL are from the remap rule that matched and
-can only be used if the plugin is a being run as a remap plugin. An option
-is required to match that section of the URL.
-
-Supported Option Names:
- HOST
-
-Example:
- cond %{URL:HOST} =www.example.com
+============ ==================================================================
+Variable Description
+============ ==================================================================
+%<proto> Protocol
+%<port> Port
+%<chi> Client IP
+%<cqhl> Client request length
+%<cqhm> Client HTTP method
+%<cquup> Client unmapped URI
+============ ==================================================================
----------------
-Condition flags
+Header Values
+-------------
+
+Setting a header with a value can take the following formats:
+
+- Any `condition <Conditions>`_ which extracts a value from the request.
+
+- ``$N``, where 0 <= N <= 9, from matching groups in a regular expression.
+
+- A string (which can contain the numbered matches from a regular expression as
+ described above).
+
+- Null.
+
+Supplying no value for a header for certain operators can lead to an effective
+no-op. In particular, `add-header`_ and `set-header`_ will simply short-circuit
+if no value has been supplied for the named header.
+
+URL Parts
+---------
+
+Some of the conditions and operators which use a request or response URL as
+their target allow for matching against specific components of the URL. For
+example, the `CLIENT-URL`_ condition can be used to test just against the query
+parameters by writing it as::
+
+ cond %{CLIENT-URL:QUERY} <operand>
+
+The URL part names which may be used for these conditions and actions are:
+
+======== ======================================================================
+Part Description
+======== ======================================================================
+HOST Full hostname.
+PATH URL substring beginning with the first ``/`` after the hostname up to,
+ but not including, the query string.
+PORT Port number.
+QUERY URL substring from the ``?``, signifying the beginning of the query
+ parameters, until the end of the URL. Empty string if there were no
+ quuery parameters.
+SCHEME URL scheme in use (e.g. ``http`` and ``https``).
+URL The complete URL.
+======== ======================================================================
+
+As another example, a remap rule might use the `set-destination`_ operator to
+change just the hostname via::
+
+ cond %{HEADER:X-Mobile} = "foo"
+ set-destination HOST foo.mobile.bar.com [L]
+
+Requests vs. Responses
+======================
+
+Both HTTP requests and responses have headers, a good number of them with the
+same names. When writing a rule against, for example, the ``Connection`` or
+``Via`` headers which are both valid in a request and a response, how can you
+tell which is which, and how do you indicate to |TS| that the condition is
+specifically and exclusively for a request header or just for a response
+header? And how do you ensure that a header rewrite occurs against a request
+before it is proxied?
+
+Hook Conditions
---------------
-The condition flags are optional, and you can combine more than one into
-a comma-separated list of flags. Note that whitespaces are not allowed inside
-the brackets::
+In addition to the conditions already described above, there are a set of
+special hook conditions. Only one of these conditions may be specified per
+ruleset, and they must be the first condition listed. Which hook condition is
+used determines the context in which the ruleset is evaluated, and whether the
+other conditions will default to operating on the client request headers or the
+origin response (or cache response) headers.
- [NC] Not case sensitive condition (when applicable) [NOT IMPLEMENTED!]
- [AND] AND with next condition (default)
- [OR] OR with next condition
- [NOT] Invert this condition
+Hook conditions are written just like the other conditions, except that none of
+them take any operands::
-Operands to conditions
-----------------------
-::
+ cond %{<name>}
+
+Because hook conditions must be the first condition in a ruleset, the use of
+one forces the beginning of a new ruleset.
+
+READ_RESPONSE_HDR_HOOK
+~~~~~~~~~~~~~~~~~~~~~~
+
+Rulesets evaluated within this context will process only once the origin server
+response (or cached response) has been read, but prior to |TS| sending that
+response to the client.
+
+This is the default hook condition for all globally-configured rulesets.
+
+READ_REQUEST_HDR_HOOK
+~~~~~~~~~~~~~~~~~~~~~
+
+Evaluates as soon as the client request has been read, but prior to any further
+processing (including contacting origin servers or fetching objects from cache).
+Conditions and operators which adapt to matching or manipulating request or
+response entities (e.g. headers) depending on their context will all operate on
+the request variants when using this hook, as there is no response data yet.
+
+READ_REQUEST_PRE_REMAP_HOOK
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
- /string/ # regular expression
- <string # lexically lower
- >string # lexically greater
- =string # lexically equal
+For ruleset configurations provided via :file:`remap.config`, this forces their
+evaluation as soon as the request has been read, but prior to the remapping.
+For all context-adapting conditions and operators, matching will occur against
+the request, as there is no response data available yet.
+
+REMAP_PSEUDO_HOOK
+~~~~~~~~~~~~~~~~~
+
+This is the default hook condition for all rulesets configured via remapping
+rules in :file:`remap.config`. Functionally equivalent to
+`READ_RESPONSE_HDR_HOOK`_ in that rulesets will evaluate after responses from
+origin servers have been received (or the object has been retrieved from
+cache), but prior to sending the client response.
+
+What sets this hook context apart is that in configuration files shared by both
+the global :file:`plugin.config` and individual remapping entries in
+:file:`remap.config`, this hook condition will force the subsequent ruleset(s)
+to be valid only for remapped transactions.
+
+SEND_REQUEST_HDR_HOOK
+~~~~~~~~~~~~~~~~~~~~~
+
+Forces evaluation of the ruleset just prior to contacting origin servers (or
+fetching the object from cache), but after any remapping may have occurred.
+
+SEND_RESPONSE_HDR_HOOK
+~~~~~~~~~~~~~~~~~~~~~~
+
+Evaluates rulesets just prior to sending the client response, but after any
+cache updates may have been performed. This hook context provides a means to
+modify aspects of the response sent to a client, while still caching the
+original versions of those attributes delivered by the origin server.
+
+Affected Conditions
+-------------------
+
+The following conditions are affected by the hook context in which they are
+evaluated and will adjust using request or response entities automatically:
+
+- `HEADER`_
+
+- `METHOD`_
+
+- `PATH`_
+
+- `QUERY`_
+
+- `URL`_
+
+Affected Operators
+------------------
-The absence of a "matcher" means value exists.
+The following operators are affected by the hook context in which they are
+evaluated and will adjust modifying request or response entities automatically:
-Values
-------
-Setting e.g. a header with a value can take the following formats:
+- `add-header`_
-- Any of the cond definitions, that extracts a value from the request
-- $N 0 <= N <= 9, as grouped in a regular expression
-- string (which can contain the above)
-- null
+- `rm-header`_
+
+- `set-header`_
+
+Caveats
+=======
+
+Repeated Headers
+----------------
+
+Some headers may appear more than once in a request or a response. When this
+occurs, all values will be collapsed into a single comma-delimited string
+before the conditions see them. This avoids the problem of determining which
+header instance out of several a condition's rule will be applied to, but it
+may introduce unexpected behavior in your operands.
+
+For example, let us assume an origin response includes a header named ``X-Foo``
+which specifies a keyword of some sort. This header may appear zero or more
+times and we wish to construct a `HEADER`_ condition that can handle this.
+
+Condition A
+~~~~~~~~~~~
+
+This condition will match using a direct equality operand::
+
+ cond %{HEADER:X-Foo} =bar
+
+Condition B
+~~~~~~~~~~~
+
+This condition will match using an unanchored regular expression::
+
+ cond %{HEADER:X-Foo} /bar/
+
+Sample Headers
+~~~~~~~~~~~~~~
+
+Both conditions A and B will match this response::
+
+ HTTP/1.1 200 OK
+ Date: Mon, 08 Feb 2016 18:11:30 GMT
+ Content-Length: 1234
+ Content-Type: text/html
+ X-Foo: bar
+
+Only condition B will match this response::
+
+ HTTP/1.1 200 OK
+ Date: Mon, 08 Feb 2016 18:11:30 GMT
+ Content-Length: 1234
+ Content-Type: text/html
+ X-Foo: bar
+ X-Foo: baz
+
+That is because the `HEADER`_ condition will see the value of ``X-Foo`` as
+``bar,baz``. Condition B will still match this because the regular expression,
+being unanchored, finds the substring ``bar``. But condition A fails, as it is
+expecting the value to be the exact string ``bar``, nothing more and nothing
+less.
Examples
---------
-::
+========
+
+Remove Origin Authentication Headers
+------------------------------------
+
+The following ruleset removes any authentication headers from the origin
+response before caching it or returning it to the client. This is accomplished
+by setting the hook context and then removing the cookie and basic
+authentication headers.::
+
+ cond %{READ_RESPONSE_HDR_HOOK}
+ rm-header Set-Cookie
+ rm-header WWW-Authenticate
+
+Count Teapots
+-------------
+
+Maintains a counter statistic, which is incremented every time an origin server
+has decided to be funny by returning HTTP 418::
+
+ cond %{STATUS} =418
+ counter plugin.header_rewrite.teapots
+
+Normalize Statuses
+------------------
+
+For client-facing purposes only (because we set the hook context to just prior
+to delivering the response back to the client, but after all processing and
+possible cache updates have occurred), replaces all 4xx HTTP status codes from
+the origin server with ``404``::
+
+ cond %{SEND_RESPONSE_HDR_HOOK}
+ cond %{STATUS} >399
+ cond %{STATUS} <500
+ set-status 404
+
+Remove Cache Control to Origins
+-------------------------------
+
+Removes cache control related headers from requests before sending them to an
+origin server::
+
+ cond %{SEND_REQUEST_HDR_HOOK}
+ rm-header Cache-Control
+ rm-header Pragma
- cond %{HEADER:X-Y-Foobar}
- cond %{COOKIE:X-DC} =DC1
- add-header X-Y-Fiefum %{HEADER:X-Y-Foobar}
- add-header X-Forwarded-For %<chi>
- rm-header X-Y-Foobar
- rm-header Set-Cookie
- counter plugin.header_rewrite.x-y-foobar-dc1
- cond %{HEADER:X-Y-Foobar} "Some string" [AND,NC]
+Enable Debugging Per-Request
+----------------------------
+Turns on |TS| debugging statements for a transaction, but only when a special
+header is present in the client request::
-.. note:: Notes about header conditionals
+ cond %{READ_REQUEST_HDR_HOOK}
+ cond %{CLIENT-HEADER:X-Debug} =supersekret
+ set-debug
- In HTTP multiple headers can be consolidated into a single comma separated string.
- To avoid complex markup within header-rewrite all header conditionals are
- evaluated against all values of the header normalized into a single comma separated string.
- Some examples:
+Remove Internal Headers
+-----------------------
- Conditions::
+Removes special internal/development headers from origin responses, unless the
+client request included a special debug header::
- # rule 1
- cond %{HEADER:foo} /bar/
+ cond %{CLIENT-HEADER:X-Debug} =keep [NOT]
+ rm-header X-Debug-Foo
+ rm-header X-Debug-Bar
- # rule 2
- cond %{HEADER:foo} =bar
+Return Original Method in Response Header
+-----------------------------------------
- Examples::
+This rule copies the original HTTP method that was used by the client into a
+custom response header::
- # matches 1 and 2
- foo: bar
+ cond %{SEND_RESPONSE_HDR_HOOK}
+ set-header X-Original-Method %{METHOD}
- # matches 1
- foo: bar
- foo: baz
+Useless Example From Purpose
+----------------------------
- # matches 1
- foo: baz
- foo: bar
+Even that useless example from `Purpose`_ in the beginning of this document is
+possible to accomplish::
- # matches 1
- foo: bar,baz
+ cond %{INCOMING-PORT} =8090
+ cond %{METHOD} =HEAD
+ cond %{CLIENT-HEADER:Accept-Language} /es-py/ [NOT]
+ cond %{STATUS} =304 [OR]
+ cond %{RANDOM:500} >290
+ set-status 403
- # matches 1
- foo: baz,bar