You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by jp...@apache.org on 2015/11/03 07:10:12 UTC
[36/51] trafficserver git commit: Documentation reorganization
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/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
new file mode 100644
index 0000000..7826884
--- /dev/null
+++ b/doc/admin-guide/plugins/background_fetch.en.rst
@@ -0,0 +1,91 @@
+.. _background-fetch-plugin:
+
+Background Fetch 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.
+
+
+This is a plugin for Apache Traffic Server that allows you to proactively
+fetch content from Origin in a way that it will fill the object into
+cache. This is particularly useful when all (or most) of your client requests
+are of the byte-Range type. The underlying problem being that Traffic Server
+is not able to cache request / responses with byte ranges.
+
+Using the plugin
+----------------
+
+This plugin functions as either a global or per remap plugin, and it takes
+an optional argument for specifying a config file with inclusion or
+exclusion criteria. The config file can be specified both via an absolute
+path or via a relative path to the install dir
+
+To activate the plugin in global mode, in :file:`plugin.config`, simply add::
+
+ background_fetch.so --config <config-file>
+
+To activate the plugin in per remap mode, in :file:`remap.config`, simply append the
+below to the specific remap line::
+
+ @plugin=background_fetch.so @pparam=<config-file>
+
+Functionality
+-------------
+
+Examining the responses from origin, we decide to trigger a background fetch
+of the original (Client) request under these conditions:
+
+- The request is a ``GET`` request (we only support these right now)
+- The response is a ``206`` response
+- The original client request, and the Origin server response, is clearly
+ indicating that the response is cacheable. This uses the new API
+ c:func:`TSHttpTxnIsCacheable()`, which also implies honoring current
+ Traffic Server configurations.
+
+
+Once deemed a good candidate to performance a background fetch, we'll replay
+the original client request through the Traffic Server proxy again, except
+this time eliminating the ``Range`` header. This is transparent to the
+original client request, which continues as normal.
+
+Only one background fetch per URL is ever performed, making sure we do not
+accidentally put pressure on the origin servers.
+
+The plugin now supports a config file that can specify exclusion or inclusion of
+background fetch based on any arbitrary header or client-ip::
+
+ background_fetch.so --config <config-file>
+
+The contents of the config-file could be as below::
+
+ include User-Agent ABCDEF
+ exclude User-Agent *
+ exclude Content-Type text
+ exclude X-Foo-Bar text
+ exclude Content-Length <1000
+
+The plugin also now supports per remap activation. To activate the plugin for
+a given remap, add the below on the remap line::
+
+ @plugin=background_fetch.so @pparam=<config-file>
+
+Future additions
+----------------
+
+- Limiting the background fetches to content of certain sizes
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/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
new file mode 100644
index 0000000..b156028
--- /dev/null
+++ b/doc/admin-guide/plugins/balancer.en.rst
@@ -0,0 +1,83 @@
+.. _balancer-plugin:
+
+Balancer 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.
+
+
+The ``balancer`` balances requests across multiple origin servers.
+To use this plugin, configure it in a :file:`remap.config` rule, specifying
+a balancing policy and a set of origin servers. For example::
+
+ map http://foo.com http://foo.com \
+ @plugin=balancer.so @pparam=--policy=hash,url @pparam=one.bar.com @pparam=two.bar.com
+
+The ``replacement`` URL in the mapping rule is not used. The argument
+to the ``--policy`` option is a comma-separated list of keywords.
+The first keyword is the name of a balancing policy. The subsequent
+keywords are used to refine the requested policy.
+
+The remaining plugin arguments are balancer targets. Typically,
+these will be the host names of origin servers that requests should
+be balanced across. The target name may contain a colon-separated
+port number.
+
+Hash Balancing Policy
+---------------------
+
+The ``hash`` balancing policy performs a consistent hash across the
+set of origins. This minimizes the number of hash entries that must
+be moved when the set of origin servers changes. An optional list
+of hash fields follows the ``hash`` keyword. Each specified hash
+field is hashed to select an outbound origin server.
+
+The following fields can be supplied to the hash:
+
+key
+ The request cache key. Note that the cache key will only be
+ set if you have already chained a plugin that sets a custom
+ cache key.
+
+url
+ The request URL. This is the default hash field that is used if
+ no other fields are specified.
+
+srcaddr
+ The source IP address of the request.
+
+dstaddr
+ The destination IP address of the request.
+
+Round Robin Balancing Policy
+----------------------------
+
+The ``roundrobin`` balancing policy simply allocates requests to
+origin servers in order. Over time, the number of requests received
+by each origin should be approximately the same.
+
+Health Checking
+---------------
+
+The ``balancer`` plugin does not check the health of the origin
+servers, however the plugin is fully reloadable so health checking
+is usualy simple to implement. Most production environments already
+have mechanisms to check service health. It is recommended that you
+write a simple script to monitor this information and rewrite
+:file:`remap.config` when appropriate. Running :option:`traffic_ctl config reload`
+will reload the ``balancer`` plugin with the new set of origin servers.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/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
new file mode 100644
index 0000000..7ae04bd
--- /dev/null
+++ b/doc/admin-guide/plugins/buffer_upload.en.rst
@@ -0,0 +1,82 @@
+.. _buffer-upload-plugin:
+
+Buffer Upload 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.
+
+The Buffer Upload plugin offers the following features
+
+Installation
+============
+
+Configuration can be explicitly specified as a parameter in ``plugin.config`` ::
+
+ buffer_upload.so /FOOBAR/upload.conf
+
+Memory buffering (buffer the entire POST data in IOBuffer before connecting to OS)
+==================================================================================
+
+Memory buffer size is configured with "mem_buffer_size" in config file. Default and minimum value is 32K. You can
+increase it in the config file. If the size of a request is larger than the "mem_buffer_size" value specifiied in the
+config file, then the upload proxy feature will be disabled for this particular request
+
+Disk buffering (buffer the entire POST data on disk before connecting to OS)
+============================================================================
+
+1. Disk async IO is used. AIO api call only involves certain amount of threads. The number of threads is configurable in
+plugin's config file (default is 4)
+
+2. Directories and files are generated on disk . Base directory is /FOOBAR/var/buffer_upload_tmp/ (configurable in
+config file). Number of subdirectories is 64 (configurable in config file). Filename are randomly generated. Files will
+be removed when the entire data have been sent out to OS . At startup time, dangling files are removed (left on disk due
+to transaction interruption or traffic server crash)
+
+3. Default chunk size when reading from disk is 16K, configurable in config file
+
+Trigger POST buffering on certain URLs
+======================================
+
+1. Certain URLs will be provided in a plain text file (one URL each line)
+2. Specify filename in config file by "url_list_file"
+3. max length of each URL is 4096 (configurable in config file)
+4. use exact match, don't support regex for now
+
+Other Features
+==============
+
+1. Default buffering mode is disk aio buffering mode. To turn off disk buffering, add a "use_disk_buffer 0" line in
+config file
+
+2. All request headers inlcuding cookies plus the entire POST data will be buffered (either in memory or on disk)
+
+Configuration File
+==================
+
+sample config file ::
+
+ use_disk_buffer 1
+ convert_url 1
+ chunk_size 1024
+ url_list_file /tmp/url_list.conf
+ max_url_length 10000
+ base_dir /tmp/test1
+ subdir_num 100
+ thread_num 10
+ mem_buffer_size 40000
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/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
new file mode 100644
index 0000000..1ad35bf
--- /dev/null
+++ b/doc/admin-guide/plugins/cacheurl.en.rst
@@ -0,0 +1,78 @@
+.. _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
+
+ 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.
+
+
+
+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.
+
+Installation
+============
+
+This plugin is only built if the configure option ::
+
+ --enable-experimental-plugins
+
+is given at build time.
+
+Configuration
+=============
+
+Create a ``cacheurl.config`` file in the plugin directory with the url
+regex patterns to match.
+
+``url_pattern cache_key_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.
+
+Add the plugin to your :file:`plugin.config` file::
+
+ cacheurl.so
+
+Start traffic server. Any rewritten URLs will be written to
+``cacheurl.log`` in the log directory by default.
+
+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``
+
+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.
+
+ ``http://www.example.com/video\?.*?\&?(id=[0-9a-f]*).*?\&(format=[a-z]*) http://video-srv.example.com.ATSINTERNAL/$1&$2``
+
+3. Completely ignore a query string for a specific page
+
+ ``http://www.example.com/some/page.html(?:\?|$) http://www.example.com/some/page.html``
+
+More docs
+=============
+
+There are some docs on cacheurl in Chinese, please find them in the following:
+
+.. http://people.apache.org/~zym/trafficserver/cacheurl.html`` <http://people.apache.org/~zym/trafficserver/cacheurl.html>`_
+
+https://blog.zymlinux.net/index.php/archives/195
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/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
new file mode 100644
index 0000000..f851be6
--- /dev/null
+++ b/doc/admin-guide/plugins/combo_handler.en.rst
@@ -0,0 +1,85 @@
+.. _combo-handler-plugin:
+
+Combohandler 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.
+
+
+This plugin provides an intelligent way to combine multiple URLs into a single
+URL, and have Apache Traffic Server combine the components into one
+response. This is useful for example to create URLs that combine multiple CSS
+or Javascript files into one.
+
+Installation
+============
+
+This plugin is only built if the configure option ::
+
+ --enable-experimental-plugins
+
+is given at build time. Note that this plugin is built and installed in
+combination with the ESI module, since they share common code.
+
+Configuration
+=============
+
+The arguments in the :file:`plugin.config` line in order represent
+
+1. The path that should triggers combo handler (defaults to
+ "admin/v1/combo")
+
+2. The name of the key used for signature verification (disabled by
+ default)
+
+A "-" can be supplied as a value for any of these arguments to request
+default value be applied.
+
+Also, just like the original combohandler, this plugin generates URLs of
+the form ``http://localhost/<dir>/<file-path>``. ``<dir>`` here defaults
+to ``l`` unless specified by the file path in the query parameter using
+a colon. For example::
+
+ http://combo.com/admin/v1/combo?filepath1&dir1:filepath2&filepath3
+
+Will result in these three pages being fetched::
+
+ http://localhost/l/filepath1
+ http://localhost/dir1/filepath2
+ http://localhost/l/filepath3
+
+Remap rules have to be specified to map the above URLs to desired
+content servers.
+
+The plugin also supports a prefix parameter. Common parts of successive
+file paths can be extracted and specified separately using a 'p' query
+parameter. Successive file path parameters are appended to this prefix
+to create complete file paths. The prefix will remain active until
+changed or cleared (set to an empty string). For example, the query ::
+
+ "/file1&p=/path1/&file2&file3&p=&/file4&p=/dir:path2/&file5&file6"
+
+results in these file paths being "reconstructed"::
+
+ /file1
+ /path1/file2
+ /path1/file3
+ /file4
+ /dir:path2/file5
+ /dir:path2/file6
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/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
new file mode 100644
index 0000000..bcd974a
--- /dev/null
+++ b/doc/admin-guide/plugins/conf_remap.en.rst
@@ -0,0 +1,51 @@
+.. 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.
+
+.. _conf-remap-plugin:
+
+conf_remap Plugin
+=================
+
+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.
+
+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.
+
+When using a separate configuration file, the standard
+:file:`records.config` syntax is used, for example::
+
+ map http://cdn.example.com/ http://some-server.example.com \
+ @plugin=conf_remap.so @pparam=/etc/trafficserver/cdn.conf
+
+where `cdn.conf` contains::
+
+ 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::
+
+ map http://cdn.example.com/ http://some-server.example.com \
+ @plugin=conf_remap.so @pparam=proxy.config.url_remap.pristine_host_hdr=1
+
+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/ce162a6d/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
new file mode 100644
index 0000000..dcc74b3
--- /dev/null
+++ b/doc/admin-guide/plugins/epic.en.rst
@@ -0,0 +1,46 @@
+.. _epic-plugin:
+
+Epic 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.
+
+The `Epic` plugin emits Traffic Server metrics in a format that is
+consumed by the `Epic Network Monitoring System
+<https://code.google.com/p/epicnms/>`_. It is a global plugin that
+is installed by adding it to the :file:`plugin.config` file.
+
+Plugin Options
+--------------
+
+--directory=DIR
+ Specify the directory the plugin will write sample files to. The
+ default is ``/usr/local/epic/cache/eapi``.
+
+--period=SECS
+ Specify the sample period in seconds. The default is to write samples every
+ 30 seconds.
+
+Caveats
+-------
+
+The Traffic Server metrics system does not store the semantics of
+metrics, so it is not possible to programmatically determine whether
+a metrics can be rate converted. The plugin contains a static list
+of metrics that should not be rate converted (gauges in Epic
+terminilogy).
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/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
new file mode 100644
index 0000000..757cab7
--- /dev/null
+++ b/doc/admin-guide/plugins/esi.en.rst
@@ -0,0 +1,151 @@
+.. _esi-plugin:
+
+ESI 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.
+
+
+This plugin implements the ESI specification.
+
+Specification
+=============
+
+Supportted ESI tags:
+
+::
+
+ esi:include
+ esi:remove
+ esi:comment
+ esi:vars
+ esi:choose
+ esi:when
+ esi:otherwise
+ esi:try
+ esi:attempt
+ esi:except
+ <!--esi ... -->
+
+extended ESI tags: *esi:special-include*
+
+Supported variables:
+
+::
+
+ $(HTTP_HOST)
+ $(HTTP_REFERER)
+ $(HTTP_ACCEPT_LANGUAGE{name})
+ $(HTTP_COOKIE{name}) or $(HTTP_COOKIE{name;subkey})
+ $(QUERY_STRING{name})
+
+Note: the name is the key name such as "username", "id" etc. For cookie support sub-name or sub-key, the format is:
+name;subkey, such as "l;u", "l;t" etc. e.g. such cookie string: l=u=test&t=1350952328, the value of
+$(HTTP_COOKIE{"l;u"}) is test and the value of $(HTTP_COOKIE{"l;t"}) is 1350952328
+
+Compile and Installation
+========================
+
+This plugin is only built if the configure option ::
+
+ --enable-experimental-plugins
+
+is given at build time. Note that this plugin is built and installed in combination with the combo handler module, since
+they share common code.
+
+Enabling ESI
+============
+
+1. First we need to set up /usr/local/etc/trafficserver/plugin.config and make sure the following line is present.
+
+::
+
+ esi.so
+
+2. There are four options you can add to the above.
+
+- "--private-response" will add private cache control and expires header to the processed ESI document.
+- "--packed-node-support" will enable the support for using packed node, which will improve the performance of parsing
+ cached ESI document.
+- "--disable-gzip-output" will disable gzipped output, which will NOT gzip the output anyway.
+- "--first-byte-flush" will enable the first byte flush feature, which will flush content to users as soon as the entire
+ ESI document is received and parsed without all ESI includes fetched (the flushing will stop at the ESI include markup
+ till that include is fetched).
+
+3. We need a mapping for origin server response that contains the ESI markup. Assume that the ATS server is abc.com. And your origin server is xyz.com and the response containing ESI markup is http://xyz.com/esi.php. We will need
+ the following line in /usr/local/etc/trafficserver/remap.config
+
+::
+
+ map http://abc.com/esi.php http://xyz.com/esi.php
+
+4. Your response should contain ESI markup and a response header of 'X-Esi: 1'. e.g. using PHP,
+
+::
+
+ <?php header('X-Esi: 1'); ?>
+ <html>
+ <body>
+ Hello, <esi:include src="http://abc.com/date.php"/>
+ </body>
+ </html>
+
+5. You will need a mapping for the src of the ESI include in remap.config if it is not already present.
+
+::
+
+ map http://abc.com/date.php http://xyz.com/date.php
+
+Or if both your ESI response and the ESI include comes from the same origin server, you can have the following line in
+remap.config instead to replace separate map rules for date.php and esi.php
+
+::
+
+ map http://abc.com/ http://xyz.com/
+
+6. Here is a sample PHP for date.php
+
+::
+
+ <?php
+ header ("Cache-control: no-cache");
+ echo date('l jS \of F Y h:i:s A');
+ ?>
+
+Useful Note
+===========
+
+1. You can provide proper cache control header and the ESI response and ESI include response can be cached separately.
+ It is extremely useful for rendering page with multiple modules. The page layout can be a ESI response with multiple
+ ESI include include, each for different module. The page layour ESI response can be cached and each individual ESI
+ include can also be cached with different duration.
+
+2. You might want to compile the code without using ESI_PACKED_NODE_SUPPORT because it may not work in some corner cases
+
+Differences from Spec - http://www.w3.org/TR/esi-lang
+=====================================================
+
+1. <esi:include> does not support "alt" and "onerror" attributes
+
+2. <esi:inline> is not supported
+
+3. You cannot have <esi:try> inside another <esi:try>
+
+4. HTTP_USER_AGENT variable is not supported
+
+5. HTTP_COOKIE supports fetching for sub-key
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/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
new file mode 100644
index 0000000..28fadb3
--- /dev/null
+++ b/doc/admin-guide/plugins/generator.en.rst
@@ -0,0 +1,69 @@
+.. _generator-plugin:
+
+Generator 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.
+
+The `Generator` allows testing of synthetic workloads by generating
+HTTP responses of various sizes. The size and cacheability of the
+response is specified by the first two coomponents of the requested
+URL path. This plugin only supports the ``GET`` and ``HEAD`` HTTP
+methods.
+
++---------------+----------------------------------------------------------------+
+|Path component | Description |
++===============+================================================================+
+|1 | ``cache`` or ``nocache``. If ``cache`` is specifed, the |
+| | `Generator` plugin will respond with ``Cache-Control`` headers |
+| | marking the response as cacheable for 24 hours. |
+|2 | Integral number of bytes to return in the response. |
++---------------+----------------------------------------------------------------+
+
+Path components after the first 2 are ignored. This means that the
+trailing path components can be manipulated to create unique URLs
+following any covenient convention.
+
+The `Generator` plugin publishes the following metrics:
+
+ generator.response_bytes:
+ The total number of bytes emitted
+ generator.response_count:
+ The number of HTTP responses generated by the plugin
+
+Examples:
+---------
+
+The most common way to use the `Generator` plugin is to configure
+it as a remap plugin in :file:`remap.config`::
+
+ map http://workload.example.com/ http://127.0.0.1/ \
+ @plugin=generator.so
+
+Notice that although the remap target is never contacted because
+the `Generator` plugin intercepts the request and acts as the origin
+server, it must be syntactically valid and resolvable in DNS.
+
+A 10 byte, cacheable object can then be generated::
+
+ $ curl -o /dev/null -x 127.0.0.1:8080 http://workload.example.com/cache/10/caf1fc92332b3a3c8cb8b3826b6a1658
+
+The `Generator` plugin can return responses as large as you like::
+
+ $ curl -o /dev/null -x 127.0.0.1:8080 http://workload.example.com/cache/$((10 * 1024 * 1024))/$RANDOM
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/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
new file mode 100644
index 0000000..15b46ad
--- /dev/null
+++ b/doc/admin-guide/plugins/geoip_acl.en.rst
@@ -0,0 +1,96 @@
+.. _geoip-acl-plugin:
+
+GeoIP ACLs 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.
+
+This is a simple ATS plugin for denying (or allowing) requests based on
+the source IP geo-location. Currently only the Maxmind APIs are
+supported, but we'd be happy to other other (open) APIs if you let us
+know. This plugin comes with the standard distribution of Apache Traffic
+Server, and should be installed as part of the normal build process.
+
+
+Configuration
+=============
+
+Once installed, there are three primary use cases, which we will discuss
+in details. Note that in all configurations, the first plugin parameter
+must specify what the matches should be applied to. Currently, only one
+rule set is supported, for Country ISO codes. This is specified with a
+parameter of ::
+
+ @pparam=country
+
+Future additions to this plugin could include other regions, such as
+city, state, continent etc.
+
+The three typical use cases are as follows:
+
+1. Per remap configurations, applicable to the entire remap rule. This
+ is useful when you can partition your content so that entire prefix
+ paths should be filtered. For example, lets assume that
+ http://example.com/music is restricted to US customers only, and
+ everything else is world wide accessible. In remap.config, you would
+ have something like ::
+
+ map http://example.com/music http://music.example.com \
+ @plugin=geoip_acl.so @pparam=country @pparam=allow @pparam=US
+ map http://example.com http://other.example.com
+
+2. If you can not partition the data with a path prefix, you can specify
+ a separate regex mapping filter. The remap.config file might then
+ look like ::
+
+ map http://example.com http://music.example.com \
+ @plugin=geoip_acl.so @pparam=country \
+ @pparam=regex::/etc/music.regex
+
+where music.regex is a format with PCRE (perl compatible) regular
+expressions, and unique rules for match. E.g.::
+
+ .*\.mp3 allow US
+ .*\.ogg deny US
+
+Note that the default in the case of no matches on the regular
+expressions is to "allow" the request. This can be overriden, see next
+use case.
+
+3. You can also combine 1) and 2), and provide defaults in the
+ remap.config configuration, which then applies for the cases where no
+ regular expressions matches at all. This would be useful to override
+ the default which is to allow all requests that don't match. For
+ example ::
+
+ map http://example.com http://music.example.com \
+ @plugin=geoip_acl.so @pparam=country @pparam=allow @pparam= US
+ @pparam=regex::/etc/music.regex
+
+This tells the plugin that in the situation where there is no matching
+regular expression, only allow requests originating from the US.
+
+Finally, there's one additional parameter option that can be used ::
+
+ @pparam=html::/some/path.html
+
+This will override the default reponse body for the denied responses
+with a custom piece of HTML. This can be useful to explain to your users
+why they are getting denied access to a particular piece of content.
+This configuration can be used with any of the use cases described
+above.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/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
new file mode 100644
index 0000000..bf93688
--- /dev/null
+++ b/doc/admin-guide/plugins/gzip.en.rst
@@ -0,0 +1,97 @@
+.. _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
+
+ 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.
+
+
+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.
+
+Installation
+============
+
+Add the following line to :file:`plugin.config`::
+
+ gzip.so
+
+In this case, the plugin will use the default behaviour:
+
+- 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)
+
+Configuration
+=============
+
+Alternatively, a configuration can also be specified::
+
+ 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)
+
+Options
+=======
+
+Flags and options are:
+
+``enabled``: (``true`` or ``false``) Enable or disable compression for a
+host.
+
+``remove-accept-encoding``: (``true`` or ``false``) Sets whether the
+plugin should hide the accept encoding from origin servers:
+
+- To ease the load on the origins.
+- For when the proxy parses responses, and the resulting
+ compression/decompression is wasteful.
+
+``cache``: (``true`` or ``false``) When set, the plugin stores the
+uncompressed and compressed response as alternates.
+
+``compressible-content-type``: Wildcard pattern for matching
+compressible content types.
+
+``disallow``: Wildcard pattern for disabling compression on urls.
+
+``flush``: (``true`` or ``false``) Enable or disable flushing of gzipped content.
+
+Options can be set globally or on a per-site basis, as such::
+
+ # Set some global options first
+ cache true
+ enabled true
+ remove-accept-encoding false
+ compressible-content-type text/*
+ flush false
+
+ # Now set a configuration for www.example.com
+ [www.example.com]
+ cache false
+ remove-accept-encoding true
+ disallow /notthis/*.js
+ flush true
+
+See example.gzip.config for example configurations.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/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
new file mode 100644
index 0000000..27cc269
--- /dev/null
+++ b/doc/admin-guide/plugins/header_rewrite.en.rst
@@ -0,0 +1,245 @@
+.. _header-rewrite-plugin:
+
+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.
+
+
+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.
+
+Using the plugin
+----------------
+
+This plugin can be used as both a global plugin, enabled in 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::
+
+ 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),
+
+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``.
+
+Operators
+---------
+
+The following operators are available::
+
+ 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]
+ counter counter-name [operator_flags]
+ no-op [operator_flags]
+
+
+Where qual is one of the support URL qualifiers::
+
+ HOST
+ PORT
+ PATH
+ QUERY
+ SCHEME
+ URL
+
+For example (as a remap rule)::
+
+ cond %{HEADER:X-Mobile} = "foo"
+ set-destination HOST foo.mobile.bar.com [L]
+
+Operator flags
+--------------
+
+The operator flags are optional, and must not contain whitespaces inside
+the brackets. Two flags are available:
+
+ [L] Last rule, do not continue
+ [QSA] Append 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
+
+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 %{PROTOCOL} operand [condition_flags]
+ cond %{PATH} operand [condition_flags]
+ cond %{QUERY} operand [condition_flags]
+ cond %{INTERNAL-TRANSACTION} [condition_flags]
+ cond %{CLIENT-IP} [condition_flags]
+ cond %{INCOMING-PORT} [condition_flags]
+ cond %{METHOD} [condition_flags]
+ cond %{CLIENT-URL:option-name} [condition_flags]
+ cond %{URL:option-name} [condition_flags]
+ cond %{FROM-URL:option-name} [condition_flags]
+ cond %{TO-URL:option-name} [condition_flags]
+ cond %{TXN-COUNT} [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
+
+---------------
+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::
+
+ [NC] Not case sensitive condition (when applicable) [NOT IMPLEMENTED!]
+ [AND] AND with next condition (default)
+ [OR] OR with next condition
+ [NOT] Invert this condition
+
+Operands to conditions
+----------------------
+::
+
+ /string/ # regular expression
+ <string # lexically lower
+ >string # lexically greater
+ =string # lexically equal
+
+The absence of a "matcher" means value exists.
+
+Values
+------
+Setting e.g. a header with a value can take the following formats:
+
+- 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
+
+Examples
+--------
+::
+
+ 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]
+
+
+.. note:: Notes about header conditionals
+
+ 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:
+
+ Conditions::
+
+ # rule 1
+ cond %{HEADER:foo} /bar/
+
+ # rule 2
+ cond %{HEADER:foo} =bar
+
+ Examples::
+
+ # matches 1 and 2
+ foo: bar
+
+ # matches 1
+ foo: bar
+ foo: baz
+
+ # matches 1
+ foo: baz
+ foo: bar
+
+ # matches 1
+ foo: bar,baz
+
+ # matches 1
+ foo: baz,bar
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/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
new file mode 100644
index 0000000..6248a9c
--- /dev/null
+++ b/doc/admin-guide/plugins/hipes.en.rst
@@ -0,0 +1,126 @@
+.. _hipes-plugin:
+
+HIPES 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.
+
+
+This is a remap plugin used in the HIPES system.
+
+Configuration
+=============
+
+``urlp:<name>``
+ Default: ``url``
+ Name of the query parameter for the service URL
+
+``path:<path>``
+ Default: ``/``
+ Path to use for the service URL
+
+``ssl``
+ Default: ``no``
+ Use SSL when connecting to the service
+
+``service``
+ Service server, ``host[:port]``
+
+``server``
+ Default: ``hipes.yimg.com``
+ Name of HIPES server, ``host[:port]``
+
+``active_timeout``
+ The active connection timeout in ms
+
+``no_activity_timeout``
+ The no activity timeout in ms
+
+``connect_timeout``
+ The connect timeout in ms
+
+``dns_timeout``
+ The DNS timeout
+
+The timeout options override the server defaults (from
+```records.config``), and
+only apply to the connection to the specific "service" host.
+
+Notes on HIPES
+==============
+
+HTTP Pipes (aka HIPES and pronounced "Hippies") allows data services to be pipelined together, as illustrated by the
+example below.
+
+Example
+=======
+1. ATS is run on port 80 and apache HTTP web server is run on port 8080 on localhost (127.0.0.1)
+
+2. The HIPES plugin is used in ``remap.config`` ::
+
+ map http://127.0.0.1/svc_case http://nosuchhost @plugin=hipes.so @pparam=service:127.0.0.1:8080 @pparam=path:svc_case.php @pparam=server:127.0.0.1
+ map http://127.0.0.1/svc_reverse http://nosuchhost @plugin=hipes.so @pparam=service:127.0.0.1:8080 @pparam=path:svc_reverse.php @pparam=server:127.0.0.1
+ map http://127.0.0.1/test.txt http://127.0.0.1:8080/test.txt
+
+3. The plugin remaps the incoming URL such as ::
+
+ http://127.0.0.1/svc_reverse/svc_case;case=u/test.txt
+
+to the following ::
+
+ http://127.0.0.1:8080/svc_reverse?url=http%3A%2F%2F127.0.0.1%2Fsvc_case%3Bcase%3Du%2Ftest.txt
+
+4. The service ``svc_reverse.php`` fetches the ``url`` from the ATS again and the plugin remaps the URL ::
+
+ http://127.0.0.1/svc_case;case=u/test.txt
+
+to this URL ::
+
+ http://127.0.0.1:8080/svc_case.php?case=u&url=http%3A%2F%2F127.0.0.1%2Ftest.txt
+
+5. In this example, the service ``svc_case.php`` fetches and transforms the response of ``http://127.0.0.1/test.txt``
+(which ATS proxies the request to a local file) to upper case. And subsequently the service ``svc_reverse.php`` receives
+the response and reverse the order before the response is sent back to the client by ATS.
+
+Notes on reducing traffic
+=========================
+
+There can be significant overhead using HIPES because the data can traverse through ATS many times. Caching can be
+important to reduce traffic to services/through ATS and can be achieved via a proper ``Cache-Control`` header returned
+by the services. Another way to reduce traffic through ATS is to have ATS to return 302 redirects to url for the
+requests made by service, instead of proxying the requests to that url. However, the service must then be able to follow
+the redirect. The down side is that we cannot use ATS to cache intermediate results. Below is an example of using
+redirect.
+
+Modification to above example to reduce traffic using redirect
+==============================================================
+
+1. The service ``svc_reverse.php`` is modified to add a header of ``X-HIPES-Redirect: 2`` to the request made against
+``url``.
+
+2. HIPES plugin will instruct ATS to return a redirect response to this url ::
+
+ http://127.0.0.1:8080/svc_case.php?case=u&url=http%3A%2F%2F127.0.0.1%2Ftest.txt
+
+for the following request ::
+
+ http://127.0.0.1/svc_case;case=u/test.txt
+
+3. The service ``svc_reverse.php`` is also modified to follow the redirect. Thus the response of the service of
+``svc_case.php`` will not pass through ATS and will pass to ``svc_reverse.php`` service instead.
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/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
new file mode 100644
index 0000000..0952c5d
--- /dev/null
+++ b/doc/admin-guide/plugins/index.en.rst
@@ -0,0 +1,89 @@
+.. 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:
+
+Plugins
+*******
+
+.. toctree::
+ :maxdepth: 2
+
+Overview
+========
+
+One of the key features of |ATS| is its modularity. Features that aren't needed
+in the core simply aren't there. This helps to provide an additional guarantee
+that our core can remain fast by concentrating on the things that we always
+provide: caching and proxying.
+
+All other functionality can be moved into plugins and by offering a consistent
+C API, everyone can implement their own functionality, without having to touch
+the core.
+
+Stable plugins
+==============
+
+Plugins that are considered stable are installed by default in |TS| releases.
+
+.. toctree::
+ :maxdepth: 1
+
+ CacheURL Plugin: allows you to change the key that is used for caching a request by using any portion of the url via regex <cacheurl.en>
+ conf_remap Plugin: allows you to override configuration directives dependent on actual remapping rules <conf_remap.en>
+ gzip / deflate Plugin: gzips or deflates responses <gzip.en>
+ Header Rewrite Plugin: allows you to modify various headers based on defined rules (operations) on a request or response <header_rewrite.en>
+ Regex Remap Plugin: allows you to configure mapping rules based on regular expressions <regex_remap.en>
+ Stats over HTTP Plugin: implements an HTTP interface to all Traffic Server statistics <stats_over_http.en>
+ TCPInfo Plugin: logs TCP metrics at various points in the HTTP processing pipeline <tcpinfo.en>
+
+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
+`--enable-experimental-plugins` option to `configure`::
+
+ $ autoconf -i
+ $ ./configure --enable-experimental-plugins
+ $ make
+
+.. toctree::
+ :maxdepth: 1
+
+ AuthProxy Plugin: delegates the authorization decision of a request to an external HTTP service <authproxy.en>
+ Background Fetch Plugin: allows you to proactively fetch content from Origin in a way that it will fill the object into cache <background_fetch.en>
+ Balancer Plugin: balances requests across multiple origin servers <balancer.en>
+ Buffer Upload Plugin: buffers POST data before connecting to the Origin server <buffer_upload.en>
+ Cache Promotion Plugin: provides additional control over when an object should be allowed into the cache <cache_promote.en>
+ Combohandler Plugin: 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>
+ Epic Plugin: emits Traffic Server metrics in a format that is consumed tby the Epic Network Monitoring System <epic.en>
+ ESI Plugin: implements the ESI specification <esi.en>
+ Generator Plugin: generate arbitrary response data <generator.en>
+ GeoIP ACLs Plugin: denying (or allowing) requests based on the source IP geo-location <geoip_acl.en>
+ hipes.en
+ Metalink Plugin: implements the Metalink download description format in order to try not to download the same file twice. <metalink.en>
+ MySQL Remap Plugin: allows dynamic “remaps” from a database <mysql_remap.en>
+ AWS S3 Authentication plugin: provides support for the Amazon S3 authentication features <s3_auth.en>
+ SSL Headers: Populate request headers with SSL session information <sslheaders.en>
+ stale_while_revalidate.en
+ ts-lua Plugin: allows plugins to be written in Lua instead of C code <ts_lua.en>
+ XDebug Plugin: allows HTTP clients to debug the operation of the Traffic Server cache using the X-Debug header <xdebug.en>
+ MP4 Plugin: mp4 streaming media <mp4.en>
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/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
new file mode 100644
index 0000000..b7de205
--- /dev/null
+++ b/doc/admin-guide/plugins/metalink.en.rst
@@ -0,0 +1,123 @@
+.. 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.
+
+.. _metalink-plugin:
+
+
+Metalink Plugin
+===============
+
+The `Metalink` plugin implements the Metalink_ download description
+format in order to try not to download the same file twice. This
+improves cache efficiency and speeds up users' downloads.
+
+It takes standard headers and knowledge about objects in the cache and
+potentially rewrites those headers so that a client will use a URL
+that's already cached instead of one that isn't. The headers are
+specified in RFC 6249 (Metalink/HTTP: Mirrors and Hashes) and RFC 3230
+(Instance Digests in HTTP) and are sent by various download
+redirectors or content distribution networks.
+
+A lot of download sites distribute the same files from many different
+mirrors and users don't know which mirrors are already cached. These
+sites often present users with a simple download button, but the
+button doesn't predictably access the same mirror, or a mirror that's
+already cached. To users it seems like the download works sometimes
+(takes seconds) and not others (takes hours), which is frustrating.
+
+An extreme example of this happens when users share a limited,
+possibly unreliable internet connection, as is common in parts of
+Africa for example.
+
+
+How it Works
+------------
+
+When the plugin sees a response with a :mailheader:`Location: ...`
+header and a :mailheader:`Digest: SHA-256=...` header, it checks if
+the URL in the :mailheader:`Location` header is already cached. If it
+isn't, then it tries to find a URL that is cached to use instead. It
+looks in the cache for some object that matches the digest in the
+:mailheader:`Digest` header and if it succeeds, then it rewites the
+:mailheader:`Location` header with that object's URL.
+
+This way a client should get sent to a URL that's already cached and
+won't download the file again.
+
+
+Installation
+------------
+
+The `Metalink` plugin is a :term:`global plugin`. Enable it by adding
+``metalink.so`` to your :file:`plugin.config` file. There are no
+options.
+
+
+Implementation Status
+---------------------
+
+The plugin implements the :c:data:`TS_HTTP_SEND_RESPONSE_HDR_HOOK`
+hook to check and potentially rewrite the :mailheader:`Location` and
+:mailheader:`Digest` headers after responses are cached. It doesn't
+do it before they're cached because the contents of the cache can
+change after responses are cached. It uses :c:func:`TSCacheRead` to
+check if the URL in the :mailheader:`Location` header is already
+cached. In future, the plugin should also check if the URL is fresh
+or not.
+
+The plugin implements the :c:data:`TS_HTTP_READ_RESPONSE_HDR_HOOK`
+hook and :doc:`a null transformation <../../sdk/http-transformation-plugin/sample-null-transformation-plugin.en>`
+to compute the SHA-256 digest for
+content as it's added to the cache. It uses SHA256_Init(),
+SHA256_Update(), and SHA256_Final() from OpenSSL to compute the
+digest, then it uses :c:func:`TSCacheWrite` to associate the digest
+with the request URL. This adds a new cache object where the key is
+the digest and the object is the request URL.
+
+To check if the cache already contains content that matches a digest,
+the plugin must call :c:func:`TSCacheRead` with the digest as the key,
+read the URL stored in the resultant object, and then call
+:c:func:`TSCacheRead` again with this URL as the key. This is
+probably inefficient and should be improved.
+
+An early version of the plugin scanned :mailheader:`Link: <...>;
+rel=duplicate` headers. If the URL in the :mailheader:`Location: ...`
+header wasn't already cached, it scanned :mailheader:`Link: <...>;
+rel=duplicate` headers for a URL that was. The :mailheader:`Digest:
+SHA-256=...` header is superior because it will find content that
+already exists in the cache in every case that a :mailheader:`Link:
+<...>; rel=duplicate` header would, plus in cases where the URL is not
+listed among the :mailheader:`Link: <...>; rel=duplicate` headers,
+maybe because the content was downloaded from a URL not participating
+in the content distribution network, or maybe because there are too
+many mirrors to list in :mailheader:`Link: <...>; rel=duplicate`
+headers.
+
+The :mailheader:`Digest: SHA-256=...` header is also more efficient
+than :mailheader:`Link: <...>; rel=duplicate` headers because it
+involves a constant number of cache lookups. RFC 6249 requires a
+:mailheader:`Digest: SHA-256=...` header or :mailheader:`Link: <...>;
+rel=duplicate` headers MUST be ignored:
+
+ If Instance Digests are not provided by the Metalink servers, the
+ :mailheader:`Link` header fields pertaining to this specification
+ MUST be ignored.
+
+ Metalinks contain whole file hashes as described in Section 6, and
+ MUST include SHA-256, as specified in [FIPS-180-3].
+
+
+.. _Metalink: http://en.wikipedia.org/wiki/Metalink
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/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
new file mode 100644
index 0000000..2bb3b00
--- /dev/null
+++ b/doc/admin-guide/plugins/mysql_remap.en.rst
@@ -0,0 +1,85 @@
+.. _mysql-remap-plugin:
+
+MySQL 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
+
+ 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.
+
+
+This is a basic plugin for doing dynamic "remaps" from a database. It
+essentially rewrites the incoming request's Host header / origin server
+connection to one retrieved from a database.
+
+The generic proxying setup is the following::
+
+ UA ----> Traffic Server ----> Origin Server
+
+Without the plugin a request like::
+
+ GET /path/to/something HTTP/1.1
+ Host: original.host.com
+
+Ends up requesting ``http://original.host.com/path/to/something``
+
+With this plugin enabled, you can easily change that to anywhere you
+desire. Imagine the many possibilities....
+
+We have benchmarked the plugin with ab at about 9200 requests/sec (1.7k
+object) on a commodity hardware with a local setup of both, MySQL and
+Traffic Server local. Real performance is likely to be substantially
+higher, up to the MySQL's max queries / second.
+
+Installation
+============
+
+This plugin is only built if the configure option ::
+
+ --enable-experimental-plugins
+
+is given at build time.
+
+Configuration
+=============
+
+Import the default schema to a database you create::
+
+ mysql -u root -p -e "CREATE DATABASE mysql_remap;" # create a new database
+ mysql -u root -p mysql_remap < schema/import.sql # import the provided schema
+
+insert some interesting values in mysql_remap.hostname &
+mysql_remap.map
+
+Traffic Server plugin configuration is done inside a global
+configuration file: ``/etc/trafficserver/plugin.config``::
+
+ mysql_remap.so /etc/trafficserver/mysql_remap.ini
+
+The INI file should contain the following values::
+
+ [mysql_remap]
+ mysql_host = localhost #default
+ mysql_port = 3306 #default
+ mysql_username = remap_user
+ mysql_password =
+ mysql_database = mysql_remap #default
+
+To debug errors, start trafficserver manually using::
+
+ traffic_server -T "mysql_remap"
+
+And resolve any errors or warnings displayed.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/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
new file mode 100644
index 0000000..5a11047
--- /dev/null
+++ b/doc/admin-guide/plugins/regex_remap.en.rst
@@ -0,0 +1,142 @@
+.. _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
+
+ 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.
+
+
+This allows you to configure mapping rules based on regular expressions.
+This is similar to what you can accomplish using mod_rewrite in Apache
+httpd, but obviously not as flexible or sophisticated (yet).
+
+To use this plugin, configure a remap.config rule like ::
+
+ map http://a.com http://b.com @plugin=regex_remap.so @pparam=maps.reg
+
+The file name parameter is always required. Unless an absolute path
+is specified, the file name is assumed to be a path relative to the
+Traffic Server configuration directory.
+
+The regular expressions listed in the configuration file are evaluated
+sequentially. When a regular expression is positively matched against
+a request URL, evaluation is stopped and the rewrite rule is applied.
+If none of the regular expressions are a match, the default destination
+URL is applied (``http://b.com`` in the example above).
+
+An optional argument (``@pparam``) with the string "``profile``\ " will
+enable profiling of this regex remap rule, e.g. ::
+
+ ... @pparam=maps.reg @pparam=profile
+
+Profiling is very low overhead, and the information is dumped to
+``traffic.out``, located in the log directory. This information is
+useful to optimize the order of your regular expression, such that the
+most common matches appears early in the file. In order to force a
+profile dump, you can do ::
+
+ $ sudo touch remap.config
+ $ sudo traffic_ctl config reload
+
+By default, only the path and query string of the URL are provided for
+the regular expressions to match. The following optional parameters can
+be used to modify the plugin instance behavior ::
+
+ @pparam=[no-]method [default: off]
+ @pparam=[no-]query-string [default: on]
+ @pparam=[no-]matrix-parameters [default: off]
+
+If you wish to match on the HTTP method used (e.g. "``GET``\ "),
+you must use the option ``@pparam=method``. e.g. ::
+
+ ... @pparam=maps.reg @pparam=method
+
+With this enabled, the string that you will need to match will look
+like ::
+
+ GET/path?query=bar
+
+The methods are always all upper-case, and always followed by one single
+space. There is no space between the method and the rest of the URL (or
+URI path).
+
+By default, the query string is part of the string that is matched
+again, to turn this off use the option 'no-query-string', e.g. ::
+
+ ... @pparam=maps.reg @pparam=no-query-string
+
+Finally, you can also include the matrix parameters in the string, using
+the option 'matrix-parameters', e.g. ::
+
+ ... @pparam=maps.reg @pparam=matrix-parameters
+
+A typical regex would look like ::
+
+ ^/(ogre.*)/more http://www.ogre.com/$h/$0/$1
+
+The regular expression must not contain any white spaces!
+
+When the regular expression is matched, only the URL path + query string
+is matched (without any of the optional configuration options). The path
+will always start with a "/". Various substitution strings are allowed
+on the right hand side during evaluation ::
+
+ $0 - The entire matched string
+ $1-9 - Regular expression groups ($1 first group etc.)
+ $h - The original host header from the request
+ $f - The host as used in the "from" portion of the remap rule
+ $t - The host as used in the "to" portion of the remap rule
+ $p - The original port number
+ $s - The scheme (e.g. http) of the request
+ $P - The entire path of the request
+ $q - The query part of the request
+ $r - The path parameters of the request (not implemented yet)
+ $c - The cookie string from the request
+ $i - The client IP for this request
+
+.. note::
+
+ The ``$0`` substitution expands to the characters that were
+ matched by the regular expression, not to the entire string that
+ the regular expression was matched against.
+
+You can also provide options, similar to how you configure your
+remap.config. The following options are available ::
+
+ @status=<nnn> - Force the response code to <nnn>
+ @active_timeout=<nnn> - Active timeout (in ms)
+ @no_activity_timeout=<nnn> - No activity timeout (in ms)
+ @connect_timeout=<nnn> - Connect timeouts (in ms)
+ @dns_timeout=<nnn> - Connect timeouts (in ms)
+
+ @overridable-config=<value> - see :ref:`ts-overridable-config`
+
+ @caseless - Make regular expressions case insensitive
+ @lowercase_substitutions - Turn on (enable) lower case substitutions
+
+
+This can be useful to force a particular response for some URLs, e.g. ::
+
+ ^/(ogre.*)/bad http://www.examle.com/ @status=404
+
+Or, to force a 302 redirect ::
+
+ ^/oldurl/(.*)$ http://news.example.com/new/$1 @status=302
+
+Setting the status to 301 or 302 will force the new URL to be used
+as a redirect (Location:).
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/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
new file mode 100644
index 0000000..38861d5
--- /dev/null
+++ b/doc/admin-guide/plugins/s3_auth.en.rst
@@ -0,0 +1,84 @@
+.. _s3-auth-plugin:
+
+AWS S3 Authentication 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.
+
+
+This is a plugin for Apache Traffic Server that provides support for the
+``Amazon S3`` authentication features. This is useful if you for example want
+to use ``S3`` as your origin server, yet want to avoid direct user access to
+the content.
+
+Using the plugin
+----------------
+
+There are three configuration options for this plugin::
+
+ --access_key <key>
+ --secret_key <key>
+ --virtual_host
+ --config <config file>
+
+
+Using the first two in a remap rule would be e.g.::
+
+ ... @plugin=s3_auth @pparam=--access_key @pparam=my-key \
+ @pparam=--secret_key @pparam=my-secret \
+ @pparam=--virtual_host
+
+
+Alternatively, you can store the access key and secret in an external
+configuration file, and point the remap rule(s) to it:
+
+ ... @plugin=s3_auth @pparam=--config @pparam=s3.config
+
+
+Where s3.config would look like::
+
+ # AWS S3 authentication
+ access_key=my-key
+ secret_key=my-secret
+ virtual_host=yes
+
+
+For more details on the S3 auth, see::
+
+ http://docs.aws.amazon.com/AmazonS3/latest/dev/RESTAuthentication.html
+
+
+ToDo
+----
+
+This is a pretty barebone start for the S3 services, it is missing a number of features:
+
+- It does not do UTF8 encoding (as required)
+
+- It only implements the v2 authentication mechanism. For details on v4, see
+
+ http://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating-requests.html
+
+- It does not deal with canonicalization of AMZ headers.
+
+- It does not handle POST requests (but do we need to ?)
+
+- It does not incorporate query parameters.
+
+
+Contributions to any of these would be appreciated.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/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
new file mode 100644
index 0000000..bab09c2
--- /dev/null
+++ b/doc/admin-guide/plugins/sslheaders.en.rst
@@ -0,0 +1,91 @@
+.. _sslheaders-plugin:
+
+SSLHeaders 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.
+
+The ``sslheaders`` plugins injects SSL session information into
+HTTP request headers. It can operate as a global plugin or as a
+remap plugin.
+
+Plugin Options
+--------------
+
+The following options may be specified when loading the plugin in
+:file:`plugin.config` or :file:`remap.config`:
+
+--attach=WHICH This option specifies which HTTP request the SSL headers are
+ attached to.
+
+ ``client`` causes the headers to be injected into
+ the client request. This is primarily useful if another plugin
+ should inspect then. ``server`` is the default and injects the
+ headers into the origin server request. ``both`` injects the
+ headers into both the client request and the origin server
+ request.
+
+A list of `KEY=VALUE` pairs follows any options. The `KEY` names the HTTP
+header to inject, and `VALUE` names the SSL session field.
+
+====================== ===============================================
+SSL session field Description
+====================== ===============================================
+client.certificate The client certificate in PEM format
+client.subject The client certificate subject DN
+client.issuer The client certificate issuer DN
+client.serial The client certificate serial number in hexadecimal format
+client.signature The client certificate signature in hexadecimal format
+client.notbefore The client certificate validity start time
+client.notafter The client certificate validity end time
+server.certificate The server certificate in PEM format
+server.subject The server certificate subject DN
+server.issuer The server certificate issuer DN
+server.serial The server certificate serial number in hexadecimal format
+server.signature The server certificate signature in hexadecimal format
+server.notbefore The server certificate validity start time
+server.notafter The server certificate validity end time
+====================== ===============================================
+
+The `client.certificate` and `server.certificate` fields emit
+the corresponding certificate in PEM format, with newline characters
+replaced by spaces.
+
+If the ``sslheaders`` plugin activtes on non-SSL connections, it
+will delete all the configured HTTP header names so that malicious
+clients cannot inject misleading information. If any of the SSL
+fields expand to an empty string, those headers are also deleted.
+
+Examples:
+---------
+
+In this example, the origin server is interested in the subject of
+the server certificate that was used to accept a client connetion.
+We can apply the ``sslheaders`` plugin to a generic remap rule to
+provide this information. The :file:`remap.config` configuration
+would be::
+
+ regex_map https://*.example.com/ http://origin.example.com/ \
+ @plugin=sslheaders.so @pparam=SSL-Server=server.subject
+
+In this example, we have set :ts:cv:`proxy.config.ssl.client.certification_level`
+to request SSL client certificates. We can then configure ``sslheaders``
+to populate the client certificate subject globally by adding it
+to :file:`plugin.config`::
+
+ sslheaders.so SSL-Client-ID=client.subject SSL-Client-NotBefore=client.notbefore SSL-Client-NotAfter-client.notafter
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/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
new file mode 100644
index 0000000..108cf38
--- /dev/null
+++ b/doc/admin-guide/plugins/stale_while_revalidate.en.rst
@@ -0,0 +1,23 @@
+.. _stale-while-revalidate-plugin:
+
+Stale While Revalidate Plugin (undocumented)
+********************************************
+
+.. 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.
+
+refresh content asynchronously while serving stale data
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/admin-guide/plugins/stats_over_http.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/plugins/stats_over_http.en.rst b/doc/admin-guide/plugins/stats_over_http.en.rst
new file mode 100644
index 0000000..14cd35b
--- /dev/null
+++ b/doc/admin-guide/plugins/stats_over_http.en.rst
@@ -0,0 +1,69 @@
+.. 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-stats-over-http:
+
+Stats Over HTTP Plugin
+**********************
+
+This plugin implements an HTTP interface to all Traffic Server statistics. The
+metrics returned are in a JSON format, for easy processing. This plugin is now
+part of the standard ATS build process, and should be available after install.
+
+Enabling Stats Over HTTP
+========================
+
+To enable this plugin, add to the :file:`plugin.conf` file::
+
+ stats_over_http.so
+
+After starting Traffic Server, the JSON metrics are now available on the
+default URL::
+
+ http://host:port/_stats
+
+where host and port is the hostname/IP and port number of the server.
+
+Plugin Options
+==============
+
+.. option:: --integer-counters
+
+This option causes the plugin to emit floating point and integral
+metric values as JSON numbers, rather then JSON strings. This can
+cause interoperability problems since integer metrics have a 64-bit
+unsigned range.
+
+.. option:: --wrap-counters
+
+This option wraps 64-bit unsigned values to the 64-bit signed range.
+This aids interoperability with Java, since prior to the Java SE 8
+release, Java did not have a 64-bit unsigned type.
+
+You can optionally modify the path to use, and this is highly
+recommended in a public facing server. For example::
+
+ stats_over_http.so 81c075bc0cca1435ea899ba4ad72766b
+
+and the URL would then be e.g.::
+
+ https://host:port/81c075bc0cca1435ea899ba4ad72766b
+
+This is weak security at best, since the secret could possibly leak if you are
+careless and send it over clear text.