plugins/header_rewrite/README

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.

Note that currently only static string "values" are supported. We'll add
advanced features to allow for expansions in a future release.


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]
  no-op		    			[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


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 %{CLIENT-HEADER:header-name} operand	[flags]
  cond %{METHOD} 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}


Condition flags
---------------
  [NC]  Not ase 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 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 %{METHOD} =GET [OR]
cond %{METHOD} =POST
set-header X-Y-Fiefum %{HEADER:X-Y-Foobar}
rm-header X-Y-Foobar
rm-header Set-Cookie

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.