----- Original Message -----
> [TS-2329] Add a restructured text version of the header rewrite's README
>
>
> Project: http://git-wip-us.apache.org/repos/asf/trafficserver/repo
> Commit: http://git-wip-us.apache.org/repos/asf/trafficserver/commit/0f45c068
> Tree: http://git-wip-us.apache.org/repos/asf/trafficserver/tree/0f45c068
> Diff: http://git-wip-us.apache.org/repos/asf/trafficserver/diff/0f45c068
>
> Branch: refs/heads/master
> Commit: 0f45c0684164c74ffe73e430e080ec62193dc001
> Parents: b5494fd
> Author: Miles Libbey <mlib...@apache.org>
> Authored: Fri Dec 13 13:31:41 2013 -0800
> Committer: Miles Libbey <mlib...@apache.org>
> Committed: Fri Dec 13 13:31:41 2013 -0800
>
> ----------------------------------------------------------------------
> doc/reference/plugins/header_rewrite.en.rst | 174 +++++++++++++++++++++++
> 1 file changed, 174 insertions(+)
> ----------------------------------------------------------------------
>
>
> http://git-wip-us.apache.org/repos/asf/trafficserver/blob/0f45c068/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
> new file mode 100644
> index 0000000..2069d26
> --- /dev/null
> +++ b/doc/reference/plugins/header_rewrite.en.rst
> @@ -0,0 +1,174 @@
> +.. _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. Currently, only one operation is supported.
> +
> +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.
> +
> +Operators
> +---------
> +
> +The following operators are available::
> +
> + rm-header header-name [flags]
> + add-header header <value> [flags]
> + set-status <status-code> [flags]
> + set-status-reason <value> [flags]
> + set-config config <value> [flags]
> + no-op [flags]
> + counter counter-name [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
> +--------------
> +::
> +
> + [L] Last rule, do not continue
> +
> +Variable expansion
> +------------------
> +Currently 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 [flags]
> + cond %{RANDOM:nn} operand [flags]
> + cond %{ACCESS:file} [flags]
> + cond %{TRUE} [flags]
> + cond %{FALSE} [flags]
> + cond %{HEADER:header-name} operand [flags]
> + cond %{COOKIE:cookie-name} operand [flags]
> + cond %{CLIENT-HEADER:header-name} operand [flags]
> + cond %{PROTOCOL} operand [flags]
> + cond %{PORT} operand [flags]
> + cond %{HOST} operand [flags]
> + cond %{TOHOST} operand [false]
> + cond %{FROMHOST} operand [false]
> + cond %{PATH} operand [false]
> + cond %{PARAMS} operand [false]
> + cond %{QUERY} operand [false]
> +
> +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
we should link to remap.config and the HOOK here.
> +configuration, but being the default it is also optional.
> +
> +---------------
> +Condition flags
> +---------------
> +::
> +
> + [NC] Not case sensitive condition (when applicable)
> + [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]
> +
>
>
--
Igor Galić
Tel: +43 (0) 664 886 22 883
Mail: i.ga...@brainsware.org
URL: http://brainsware.org/
GPG: 8716 7A9F 989B ABD5 100F 4008 F266 55D6 2998 1641
