nginx_substitutions_filter

Note: this module is not distributed with the Nginx source. Installation instructions can be found below. >

Description

nginx_substitutions_filter is a filter module which can do both regular expression and fixed string substitutions on response bodies. This module is quite different from the Nginx's native Substitution Module. It scans the output chains buffer and matches string line by line, just like Apache's mod_substitute (http://httpd.apache.org/docs/trunk/mod/mod_substitute.html).

Example

location / {

    subs_filter_types text/html text/css text/xml;
    subs_filter st(\d*).example.com $1.example.com ir;
    subs_filter a.example.com s.example.com;
    subs_filter http://$host https://$host;

}

Directives

subs_filter_types

syntax: subs_filter_types mime-type [mime-types]

default: subs_filter_types text/html

context: http, server, location

subs_filter_types is used to specify which content types should be checked for subs_filter, in addition to *text/html*. The default is only text/html.

This module just works with plain text. If the response is compressed, it can't uncompress the response and will ignore this response. This module can be compatible with gzip filter module. But it will not work with proxy compressed response. You can disable the compressed response like this:

proxy_set_header Accept-Encoding ``'';

subs_filter

syntax: subs_filter source_str destination_str [gior]

default: none

context: http, server, location

subs_filter allows replacing source string(regular expression or fixed) in the nginx response with destination string. The variables in matching text is only avaiable under fixed string mode, which means the matching text could not contain variables if it is a regular expression. Substitution text may contain variables. More than one substitution rules per location is supported. The meaning of the third flags are:

subs_filter_bypass

syntax: subs_filter_bypass $variable1 ...

default: none

context: http, server, location

You can sepcify several variables with this directive. If at least one of the variable is not empty and is not equal to '0', this substitution filter will be disabled.

Installation

To install, get the source with subversion:

git clone git://github.com/yaoweibin/ngx_http_substitutions_filter_module.git

and then compile nginx with the following option:

./configure --add-module=/path/to/ngx_http_substitutions_filter_module

Known issue

CHANGES

Changes with nginx_substitutions_filter 0.6.4 2014-02-15

Changes with nginx_substitutions_filter 0.6.2 2012-08-26

Changes with nginx_substitutions_filter 0.6.0 2012-06-30

Changes with nginx_substitutions_filter 0.5.2 2010-08-11

Changes with nginx_substitutions_filter 0.5 2010-04-15

Changes with nginx_substitutions_filter 0.4 2009-12-23

Changes with nginx_substitutions_filter 0.3 2009-02-04

Reporting a bug

Questions/patches may be directed to Weibin Yao, yaoweibin@gmail.com.

Copyright & License

This module is licensed under the BSD license.

Copyright (C) 2014 by Weibin Yao <yaoweibin@gmail.com>.

All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

    notice, this list of conditions and the following disclaimer.
    notice, this list of conditions and the following disclaimer in the
    documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.