You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by ml...@apache.org on 2016/03/22 22:41:15 UTC
trafficserver git commit: New documentation for escalation plugin
Repository: trafficserver
Updated Branches:
refs/heads/master 41441da8e -> 015b77176
New documentation for escalation plugin
- fix some typos
- fix some spacing issues for preformatted text inside paragraphs
Project: http://git-wip-us.apache.org/repos/asf/trafficserver/repo
Commit: http://git-wip-us.apache.org/repos/asf/trafficserver/commit/015b7717
Tree: http://git-wip-us.apache.org/repos/asf/trafficserver/tree/015b7717
Diff: http://git-wip-us.apache.org/repos/asf/trafficserver/diff/015b7717
Branch: refs/heads/master
Commit: 015b7717612f35de9d8adc0a8a2abe3efece8abd
Parents: 41441da
Author: Miles Libbey <ml...@apache.org>
Authored: Tue Mar 22 14:37:59 2016 -0700
Committer: Miles Libbey <ml...@apache.org>
Committed: Tue Mar 22 14:39:45 2016 -0700
----------------------------------------------------------------------
.../files/ssl_multicert.config.en.rst | 3 +-
doc/admin-guide/plugins/escalate.en.rst | 64 ++++++++++++++++++++
doc/admin-guide/plugins/index.en.rst | 6 +-
doc/admin-guide/plugins/regex_remap.en.rst | 2 +-
doc/static/override.css | 4 ++
5 files changed, 76 insertions(+), 3 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/015b7717/doc/admin-guide/files/ssl_multicert.config.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/files/ssl_multicert.config.en.rst b/doc/admin-guide/files/ssl_multicert.config.en.rst
index 0be58e6..25bab6e 100644
--- a/doc/admin-guide/files/ssl_multicert.config.en.rst
+++ b/doc/admin-guide/files/ssl_multicert.config.en.rst
@@ -105,7 +105,8 @@ ticket_key_name=FILENAME (optional)
:ts:cv:`proxy.config.ssl.server.cert.path` configuration variable.
This option has no effect if session tickets are disabled by the
``ssl_ticket_enabled`` option. The contents of the key file should
- be 48 random bytes.
+ be 48 random (ASCII) bytes. One way to generate this would be to run
+ ``head -c48 /dev/urandom | openssl enc -base64 | head -c48 > file.ticket``.
Session ticket support is enabled by default. If neither of the
``ssl_ticket_enabled`` and ``ticket_key_name`` options are
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/015b7717/doc/admin-guide/plugins/escalate.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin-guide/plugins/escalate.en.rst b/doc/admin-guide/plugins/escalate.en.rst
new file mode 100644
index 0000000..0bdbd94
--- /dev/null
+++ b/doc/admin-guide/plugins/escalate.en.rst
@@ -0,0 +1,64 @@
+.. _escalate-plugin:
+
+Escalate 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 Escalate plugin allows Traffic Server to try an alternate
+origin when the origin server in the remap rule is either unavailable
+or returns specific HTTP error codes. Some services call this failover
+or fail-action.
+
+Plugin Configuration
+--------------------
+
+The escalate plugin is a remap plugin (not global) and takes a parameter
+with two delimitated fields: ``comma-separated-error-codes:secondary-origin-server``. For instance,
+
+ ``@pparam=401,404,410,502:second-origin.example.com``
+
+would have Traffic Server send a cache miss to ``second-origin.example.com``
+when the origin server in the remap rule returns a 401,
+404, 410, or 502 error code.
+
+@pparam=--pristine
+ This option sends the "pristine" Host: header (eg, the Host: header
+ that the client sent) to the escalated request.
+
+Installation
+------------
+
+This plugin is only built if the configure option ::
+
+ --enable-experimental-plugins
+
+is given at build time.
+
+Example
+-------
+
+With this line in :file:`remap.config` ::
+
+ map cdn.example.com origin.example.com
+ @plugin=escalate.so @pparam=401,404,410,502:second-origin.example.com @pparam=--pristine
+
+Traffic Server would accept a request for ``cdn.example.com`` and, on a cache miss, proxy the
+request to ``origin.example.com``. If the response code from that server is a 401, 404, 410,
+or 502, then Traffic Server would proxy the request to ``second-origin.example.com``, using a
+Host: header of ``cdn.example.com``.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/015b7717/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 de4084f..981f80d 100644
--- a/doc/admin-guide/plugins/index.en.rst
+++ b/doc/admin-guide/plugins/index.en.rst
@@ -104,6 +104,7 @@ directory of the |TS| source tree. Experimental plugins can be compiled by passi
Cache Promote <cache_promote.en>
Combo Handler <combo_handler.en>
Epic <epic.en>
+ Escalate <escalate.en>
ESI <esi.en>
Generator <generator.en>
GeoIP ACL <geoip_acl.en>
@@ -145,7 +146,10 @@ directory of the |TS| source tree. Experimental plugins can be compiled by passi
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.
+ Emits Traffic Server metrics in a format that is consumed by the Epic Network Monitoring System.
+
+:doc:`Escalate <escalate.en>`
+ Escalate: when the origin returns specific status codes, retry the request at a secondary origin (failover/fail-action)
:doc:`ESI <esi.en>`
Implements the Edge Side Includes (ESI) specification.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/015b7717/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 0b2a9f9..6f2ce8b 100644
--- a/doc/admin-guide/plugins/regex_remap.en.rst
+++ b/doc/admin-guide/plugins/regex_remap.en.rst
@@ -125,7 +125,7 @@ remap.config. The following options are available ::
@connect_timeout=<nnn> - Connect timeouts (in ms)
@dns_timeout=<nnn> - Connect timeouts (in ms)
- @overridable-config=<value> - see :ref:`ts-overridable-config`
+ @overridable-config=<value> - see :ref:`Overridable Configurations <ts-overridable-config>`
@caseless - Make regular expressions case insensitive
@lowercase_substitutions - Turn on (enable) lower case substitutions
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/015b7717/doc/static/override.css
----------------------------------------------------------------------
diff --git a/doc/static/override.css b/doc/static/override.css
index 709e190..0a080c2 100644
--- a/doc/static/override.css
+++ b/doc/static/override.css
@@ -8,3 +8,7 @@
max-width: 100%;
overflow: visible;
}
+/* pre inside paragraphs gets weird spacing */
+span.pre {
+ line-height: initial;
+}
Re: trafficserver git commit: New documentation for escalation plugin
Posted by James Peach <jp...@apache.org>.
Hi Miles,
Next time, would you mind splitting this into separate commits? That makes it easier to see what was fixed in the commit history ...
> On Mar 22, 2016, at 2:41 PM, mlibbey@apache.org wrote:
>
> Repository: trafficserver
> Updated Branches:
> refs/heads/master 41441da8e -> 015b77176
>
>
> New documentation for escalation plugin
>
> - fix some typos
> - fix some spacing issues for preformatted text inside paragraphs
>
>
> Project: http://git-wip-us.apache.org/repos/asf/trafficserver/repo
> Commit: http://git-wip-us.apache.org/repos/asf/trafficserver/commit/015b7717
> Tree: http://git-wip-us.apache.org/repos/asf/trafficserver/tree/015b7717
> Diff: http://git-wip-us.apache.org/repos/asf/trafficserver/diff/015b7717
>
> Branch: refs/heads/master
> Commit: 015b7717612f35de9d8adc0a8a2abe3efece8abd
> Parents: 41441da
> Author: Miles Libbey <ml...@apache.org>
> Authored: Tue Mar 22 14:37:59 2016 -0700
> Committer: Miles Libbey <ml...@apache.org>
> Committed: Tue Mar 22 14:39:45 2016 -0700
>
> ----------------------------------------------------------------------
> .../files/ssl_multicert.config.en.rst | 3 +-
> doc/admin-guide/plugins/escalate.en.rst | 64 ++++++++++++++++++++
> doc/admin-guide/plugins/index.en.rst | 6 +-
> doc/admin-guide/plugins/regex_remap.en.rst | 2 +-
> doc/static/override.css | 4 ++
> 5 files changed, 76 insertions(+), 3 deletions(-)
> ----------------------------------------------------------------------
>
>
> http://git-wip-us.apache.org/repos/asf/trafficserver/blob/015b7717/doc/admin-guide/files/ssl_multicert.config.en.rst
> ----------------------------------------------------------------------
> diff --git a/doc/admin-guide/files/ssl_multicert.config.en.rst b/doc/admin-guide/files/ssl_multicert.config.en.rst
> index 0be58e6..25bab6e 100644
> --- a/doc/admin-guide/files/ssl_multicert.config.en.rst
> +++ b/doc/admin-guide/files/ssl_multicert.config.en.rst
> @@ -105,7 +105,8 @@ ticket_key_name=FILENAME (optional)
> :ts:cv:`proxy.config.ssl.server.cert.path` configuration variable.
> This option has no effect if session tickets are disabled by the
> ``ssl_ticket_enabled`` option. The contents of the key file should
> - be 48 random bytes.
> + be 48 random (ASCII) bytes. One way to generate this would be to run
> + ``head -c48 /dev/urandom | openssl enc -base64 | head -c48 > file.ticket``.
>
> Session ticket support is enabled by default. If neither of the
> ``ssl_ticket_enabled`` and ``ticket_key_name`` options are
>
> http://git-wip-us.apache.org/repos/asf/trafficserver/blob/015b7717/doc/admin-guide/plugins/escalate.en.rst
> ----------------------------------------------------------------------
> diff --git a/doc/admin-guide/plugins/escalate.en.rst b/doc/admin-guide/plugins/escalate.en.rst
> new file mode 100644
> index 0000000..0bdbd94
> --- /dev/null
> +++ b/doc/admin-guide/plugins/escalate.en.rst
> @@ -0,0 +1,64 @@
> +.. _escalate-plugin:
> +
> +Escalate 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 Escalate plugin allows Traffic Server to try an alternate
> +origin when the origin server in the remap rule is either unavailable
> +or returns specific HTTP error codes. Some services call this failover
> +or fail-action.
> +
> +Plugin Configuration
> +--------------------
> +
> +The escalate plugin is a remap plugin (not global) and takes a parameter
> +with two delimitated fields: ``comma-separated-error-codes:secondary-origin-server``. For instance,
> +
> + ``@pparam=401,404,410,502:second-origin.example.com``
> +
> +would have Traffic Server send a cache miss to ``second-origin.example.com``
> +when the origin server in the remap rule returns a 401,
> +404, 410, or 502 error code.
> +
> +@pparam=--pristine
> + This option sends the "pristine" Host: header (eg, the Host: header
> + that the client sent) to the escalated request.
> +
> +Installation
> +------------
> +
> +This plugin is only built if the configure option ::
> +
> + --enable-experimental-plugins
> +
> +is given at build time.
> +
> +Example
> +-------
> +
> +With this line in :file:`remap.config` ::
> +
> + map cdn.example.com origin.example.com
> + @plugin=escalate.so @pparam=401,404,410,502:second-origin.example.com @pparam=--pristine
> +
> +Traffic Server would accept a request for ``cdn.example.com`` and, on a cache miss, proxy the
> +request to ``origin.example.com``. If the response code from that server is a 401, 404, 410,
> +or 502, then Traffic Server would proxy the request to ``second-origin.example.com``, using a
> +Host: header of ``cdn.example.com``.
> \ No newline at end of file
>
> http://git-wip-us.apache.org/repos/asf/trafficserver/blob/015b7717/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 de4084f..981f80d 100644
> --- a/doc/admin-guide/plugins/index.en.rst
> +++ b/doc/admin-guide/plugins/index.en.rst
> @@ -104,6 +104,7 @@ directory of the |TS| source tree. Experimental plugins can be compiled by passi
> Cache Promote <cache_promote.en>
> Combo Handler <combo_handler.en>
> Epic <epic.en>
> + Escalate <escalate.en>
> ESI <esi.en>
> Generator <generator.en>
> GeoIP ACL <geoip_acl.en>
> @@ -145,7 +146,10 @@ directory of the |TS| source tree. Experimental plugins can be compiled by passi
> 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.
> + Emits Traffic Server metrics in a format that is consumed by the Epic Network Monitoring System.
> +
> +:doc:`Escalate <escalate.en>`
> + Escalate: when the origin returns specific status codes, retry the request at a secondary origin (failover/fail-action)
>
> :doc:`ESI <esi.en>`
> Implements the Edge Side Includes (ESI) specification.
>
> http://git-wip-us.apache.org/repos/asf/trafficserver/blob/015b7717/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 0b2a9f9..6f2ce8b 100644
> --- a/doc/admin-guide/plugins/regex_remap.en.rst
> +++ b/doc/admin-guide/plugins/regex_remap.en.rst
> @@ -125,7 +125,7 @@ remap.config. The following options are available ::
> @connect_timeout=<nnn> - Connect timeouts (in ms)
> @dns_timeout=<nnn> - Connect timeouts (in ms)
>
> - @overridable-config=<value> - see :ref:`ts-overridable-config`
> + @overridable-config=<value> - see :ref:`Overridable Configurations <ts-overridable-config>`
>
> @caseless - Make regular expressions case insensitive
> @lowercase_substitutions - Turn on (enable) lower case substitutions
>
> http://git-wip-us.apache.org/repos/asf/trafficserver/blob/015b7717/doc/static/override.css
> ----------------------------------------------------------------------
> diff --git a/doc/static/override.css b/doc/static/override.css
> index 709e190..0a080c2 100644
> --- a/doc/static/override.css
> +++ b/doc/static/override.css
> @@ -8,3 +8,7 @@
> max-width: 100%;
> overflow: visible;
> }
> +/* pre inside paragraphs gets weird spacing */
> +span.pre {
> + line-height: initial;
> +}
>