plugins/regex_remap/README

This is a plugin for the Apache Traffic Server, that allows you to
configure mapping rules based on regular expressions. This is similar to
what you can accomplish using mod_rewrite in apache, but obviously not
as flexible or sophisticated (yet).

To use this plugin, configure a remap.config rule like

   map http://a.com http://b.com @plugin=regex_remap.so @pparam=maps.reg


An optional argument (@@pparam) with the string "profile" will enable
profiling of this regex remap rule, e.g.

  ... @pparam=maps.reg @pparam=profile


Profiling is very low overhead, and the information is dumped to
traffic.out, typically in /usr/local/var/logs/trafficserver/traffic.out.
In order to force a profile dump, you can do

    $ sudo touch /usr/local/etc/trafficserver/remap.config
    $ sudo traffic_line -x


By default, only the path and query string of the URL is
provided for the regular expressions to match. The following optional
parameters can be used to modify the plugin instance behavior:

    @pparam=[no-]method              [default: off]
    @pparam=[no-]query-string        [default: on]
    @pparam=[no-]matrix-parameters   [default: off]



If you wish to match on the HTTP method used (e.g. "GET"), you must
use the option @pparam=method. For example:

   ... @pparam=maps.reg @pparam=method


With this enabled, the string that you will need to match will look like

    GET/path?query=bar


The methods are always all upper-case, and always followed by one single
space. There is no space between the method and the rest of the URL (or
URI path).

By default, the query string is part of the string that is matched again,
to turn this off use the option 'no-query-string', e.g.

   ... @pparam=maps.reg @pparam=no-query-string


Finally, you can also include the matrix parameters in the string, using the
option 'matrix-parameters', e.g.

   ... @pparam=maps.reg @pparam=matrix-parameters


Note that the path to the plugin must be absolute, and by default it is

    /usr/local/libexec/trafficserver/regex_remap.so


The config file (maps.reg above) can be placed anywhere, but unless you
specify an absolute path (as above), it will default to the directory

  /usr/local/etc/regex_remap


A typical regex would look like

    ^/(ogre.*)/more     http://www.ogre.com/$h/$0/$1


The regular expression must not contain any white spaces!

When the regular expression is matched, only the URL path + query string is
matched (without any of the optional configuration options). The path
will always start with a "/". Various substitution strings are allowed
on the right hand side:

    $0     - The entire matched string
    $1-9   - Regular expression groups ($1 first group etc.)
    $h     - The original host header from the request
    $f     - The host as used in the "from" portion of the remap rule
    $t     - The host as used in the "to" portion of the remap rule
    $p     - The original port number
    $s     - The scheme (e.g. http) of the request
    $P     - The entire path of the request
    $l     - The entire path of the request in lowercase
    $q     - The query part of the request
    $r     - The path parameters of the request (not implemented yet)
    $c     - The cookie string from the request
    $i     - The client IP for this request


You can also provide options, similar to how you configure your
remap.config. The following options are available

    @status=<nnn>                   - Force the response code to <nnn>
    @active_timeout=<nnn>           - Active timeout (in ms)
    @no_activity_timeout=<nnn>      - No activity timeout (in ms)
    @connect_timeout=<nnn>          - Connect timeouts (in ms)
    @dns_timeout=<nnn>              - Connect timeouts (in ms)
    @lowercase_substitutions=<0|1>  - Turn on lowercasing all the substitutions


For example, this can be useful to force a particular response for some
URLs, e.g.

    ^/(ogre.*)/bad      http://www.examle.com/  @status=404


Or, to force a 302 redirect

    ^/oldurl/(.*)$      http://news.example.com/new/$1 @status=302


Note: Setting the status to 301 or 302 will force the new URL to be used
as a redirect (Location:).


RELEASES
--------

Version 2.0
  - Initial Open Source release.