TS-2329 Update documentation for header_rewrite plugin
Project: http://git-wip-us.apache.org/repos/asf/trafficserver/repo Commit: http://git-wip-us.apache.org/repos/asf/trafficserver/commit/4b6f7ae8 Tree: http://git-wip-us.apache.org/repos/asf/trafficserver/tree/4b6f7ae8 Diff: http://git-wip-us.apache.org/repos/asf/trafficserver/diff/4b6f7ae8 Branch: refs/heads/5.0.x Commit: 4b6f7ae87eac26eefcb795b9e1f1a45158c0cfcd Parents: b314eb3 Author: Leif Hedstrom <[email protected]> Authored: Thu Jan 30 16:28:18 2014 -0700 Committer: Leif Hedstrom <[email protected]> Committed: Thu Jan 30 16:28:18 2014 -0700 ---------------------------------------------------------------------- doc/reference/plugins/header_rewrite.en.rst | 13 +- doc/reference/plugins/index.en.rst | 1 + plugins/header_rewrite/README | 239 +---------------------- 3 files changed, 12 insertions(+), 241 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/trafficserver/blob/4b6f7ae8/doc/reference/plugins/header_rewrite.en.rst ---------------------------------------------------------------------- diff --git a/doc/reference/plugins/header_rewrite.en.rst b/doc/reference/plugins/header_rewrite.en.rst index 92c04c2..25fd9cf 100644 --- a/doc/reference/plugins/header_rewrite.en.rst +++ b/doc/reference/plugins/header_rewrite.en.rst @@ -49,16 +49,16 @@ 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 <value> [operator_flags] + set-timeout-out <value> [operator_flags] set-status-reason <value> [operator_flags] - set-config config <value> [operator_flags] - no-op [operator_flags] + set-config overridable-config <value> [operator_flags] counter counter-name [operator_flags] + no-op [operator_flags] -The following operator(s) currently only works when instantiating the -plugin as a remap plugin:: - - set-destination [qual] value Where qual is one of the support URL qualifiers:: @@ -124,6 +124,7 @@ 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) cond %{READ_REQUEST_HDR_HOOK} + cond %{READ_REQUEST_PRE_REMAP_HOOK} cond %{SEND_REQUEST_HDR_HOOK} cond %{SEND_RESPONSE_HDR_HOOK} http://git-wip-us.apache.org/repos/asf/trafficserver/blob/4b6f7ae8/doc/reference/plugins/index.en.rst ---------------------------------------------------------------------- diff --git a/doc/reference/plugins/index.en.rst b/doc/reference/plugins/index.en.rst index 33c0a2c..43a990f 100644 --- a/doc/reference/plugins/index.en.rst +++ b/doc/reference/plugins/index.en.rst @@ -44,6 +44,7 @@ Apache Traffic Server releases. conf_remap.en gzip.en header_filter.en + header_rewrite.en regex_remap.en stats_over_http.en http://git-wip-us.apache.org/repos/asf/trafficserver/blob/4b6f7ae8/plugins/header_rewrite/README ---------------------------------------------------------------------- diff --git a/plugins/header_rewrite/README b/plugins/header_rewrite/README index 3ea6c6c..40ea174 100644 --- a/plugins/header_rewrite/README +++ b/plugins/header_rewrite/README @@ -1,8 +1,8 @@ Apache Traffic Server Rewrite Header Plugin This is a plugin for ATS (Apache Traffic Server), that allows you to perform various header "rewrite" rules (operations) on a request or -response. Currently, only one operation is supported, since we had to get -this rolling asap. +response. It is loosely modeled after Apache HTTPD's mod_rewrite. + Using the plugin ---------------- @@ -22,237 +22,6 @@ 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. +For more information on how to use this plugin, please see -Operators ---------- -The following operators are available: - - rm-header header-name [operator_flags] - add-header header <value> [operator_flags] - set-status <status-code> [operator_flags] - set-status-reason <value> [operator_flags] - set-config config <value> [operator_flags] - no-op [operator_flags] - counter counter-name [operator_flags] - -The following operator(s) currently only works when instantiating the -plugin as a remap plugin: - - set-destination [qual] value - -Where qual is one of the support URL qualifiers - - HOST - PORT - PATH - QUERY - -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. Currently, only one flag is supported: - - [L] Last rule, do not continue - - -Variable expansion ------------------- -Currntly 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 %{PORT} operand [condition_flags] - cond %{HOST} operand [condition_flags] - cond %{TOHOST} operand [condition_flags] - cond %{FROMHOST} operand [condition_flags] - cond %{PATH} operand [condition_flags] - cond %{PARAMS} operand [condition_flags] - cond %{QUERY} operand [condition_flags] - - -The difference between HEADER and CLIENT-HEADER is that HEADER adapts to the -hook it's running in, whereas CLIENT-HEADER always applies to the client -request header. The %{TRUE} condition is also the default condition if no -other conditions are specified. - -These conditions have to be first in a ruleset, and you can only have one in -each rule. This implies that a new hook condition starts a new rule as well. - - cond %{READ_RESPONSE_HDR_HOOK} (this is the default hook) - cond %{READ_REQUEST_HDR_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. - - -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 absense 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] - - - -RELEASES --------- -Version 2.0.0 (6/8/12, bcall) --- Ported to ATS - -Version 1.7.3 (12/01/11,sambani) --- changed mdbm locks to mutex - -Version 1.7.2 (10/18/11,cdoshi) --- check for url redirect length - -Version 1.7.1 (10/18/11,cdoshi) --- use size_t instead of unsigned - -Version 1.7.0 (10/17/11,cdoshi) - - Support for %{PATH} - -Version 1.6.9 (10,17,11,cdoshi) - - Support for PATH condition - -Version 1.6.8 (10/17/11,cdoshi) - - Replace the INKHttpHdrStatusSet with INKHttptxnSetHttpRetStatus - -Version 1.6.7 (07/21/11, bcall) - - [bug 4699620] - Removed some extra printf()'s - -Version 1.6.6 (cdoshi) - - when Host adder is added setHostChange will be called - -Version 1.6.5 (cdoshi) - - fix QSA for set-destination - -Version 1.6.4 (cdoshi) - - support QSA for set-destination - -Version 1.6.3 (cdoshi) - - support the query,fix the remap stuff - -Version 1.6.2 (cdoshi) - - Support for regex matcher - -Version 1.6.1 (09/15/10, leif) - - [bug 3985913] - -Version 1.6.0 (07/14/10, leif) - - Added support for the timeout-out operator. - - Added support for the set-redirect operator. - - Added support for INK_HTTP_READ_REQUEST_PRE_REMAP_HOOK (this means we - now require YTS 1.18.1 or later). - -Version 1.5.0 (06/02/10, leif) - - Add support for running as a remap plugin. - - Add support for set-destination operator (this currently only works in - a remap plugin). - -Version 1.4.1 (02/09/10, leif) - - Cleanup of error messages. - - Changed name from MDBM to DBM. - -Version 1.4 (01/20/10, leif) - - Added support for CLIENT-HEADER condition. - - Cleanup in flags handling and features. - - Support MDBM as a condition. - -Version 1.3.1 (12/22/09, leif) - - Fixed package to support MDBM v2.x and v3.x. - -Version 1.3 (12/22/09, leif) - - Refactored to allow conditions to be used as values. - - Added condition for HEADER. - - Added condition for MDBM lookups. - - Fixed consistency problems on HOOK names. - -Version 1.2 (10/28/09, leif) - - Added support for SEND_RESPONSE_HDR_HOOK. - -Version 1.1 (10/08/09, leif) - - Added support for SEND_REQUEST_HDR_HOOK. - -Version 1.0 (9/24/09, leif) - - Added support for two hooks. - - Added "add-header". Remember to "rm-header" the header first if you - want to assure there's only one version. - - Added support for %{RANDOM:NN} condition - - Added support for %{ACCESS:file} condition - - Lots of more code cleanup. - -Version 0.2 (7/24/09, leif) - - Added support for some basic conditions. - - Added support for setting the return status code and reason. - -Version 0.1 (7/13/09, leif) - - Initial version. + http://docs.trafficserver.apache.org/en/latest/reference/plugins/header_rewrite.en.html
