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 <[email protected]> Authored: Tue Feb 16 00:50:57 2016 +0000 Committer: Jon Sime <[email protected]> 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/
