README.google_code_home_page.wiki
1= nginx_substitutions_filter =
2
3_Note: this module is not distributed with the Nginx source. Installation instructions can be found [#Installation below]._
4
5== Description ==
6
7`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 [http://httpd.apache.org/docs/trunk/mod/mod_substitute.html mod_substitute].
8
9== Example ==
10
11{{{
12location / {
13
14 subs_filter_types text/html text/css text/xml;
15 subs_filter st(\d*).example.com $1.example.com ir;
16 subs_filter a.example.com s.example.com;
17 subs_filter http://$host https://$host;
18
19}
20}}}
21== Directives ==
22
23 * [#subs_filter_types subs_filter_types]
24 * [#subs_filter subs_filter]
25
26=== subs_filter_types ===
27
28`syntax:` _subs_filter_types mime-type `[`mime-types`]` _
29
30`default:` _subs_filter_types text/html_
31
32`context:` _http, server, location_
33
34_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_.
35
36This 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:
37
38proxy_set_header Accept-Encoding "";
39
40=== subs_filter ===
41
42`syntax:` _subs_filter source_str destination_str `[`gior`]` _
43
44`default:` _none_
45
46`context:` _http, server, location_
47
48_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:
49 * _g_ (default): Replace all the match strings.
50 * _i_: Perform a case-insensitive match.
51 * _o_: Just replace the first one.
52 * _r_: The pattern is treated as a regular expression, default is fixed string.
53
54=== subs_filter_bypass ===
55
56`syntax:` _subs_filter_bypass $variable1 ..._
57
58`default:` _none_
59
60`context:` _http, server, location_
61
62You 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.
63
64== Installation ==
65
66To install, get the source with subversion:
67
68{{{
69git clone git://github.com/yaoweibin/ngx_http_substitutions_filter_module.git
70}}}
71and then compile nginx with the following option:
72
73{{{
74./configure --add-module=/path/to/ngx_http_substitutions_filter_module
75}}}
76== Known issue ==
77 * Can't substitute the response header.
78
79== CHANGES ==
80
81Changes with nginx_substitutions_filter 0.6.4 2014-02-15
82
83 * Now non-200 response will work
84 * added the subs_filter_bypass directive
85
86Changes with nginx_substitutions_filter 0.6.2 2012-08-26
87
88 * fixed a bug of buffer overlap
89 * fixed a bug with last zero buffer
90
91Changes with nginx_substitutions_filter 0.6.0 2012-06-30
92
93 * refactor this module
94
95Changes with nginx_substitutions_filter 0.5.2 2010-08-11
96
97 * do many optimizing for this module
98 * fix a bug of buffer overlap
99 * fix a segment fault bug when output chain return NGX_AGAIN.
100 * fix a bug about last buffer with no linefeed. This may cause segment fault. Thanks for Josef Fröhle
101
102Changes with nginx_substitutions_filter 0.5 2010-04-15
103
104 * refactor the source structure, create branches of dev
105 * fix a bug of small chunk of buffers causing lose content
106 * fix the bug of last_buf and the nginx's compatibility above 0.8.25
107 * fix a bug with unwanted capture config error in fix string substitution
108 * add feature of regex captures
109
110Changes with nginx_substitutions_filter 0.4 2009-12-23
111
112 * fix many bugs
113
114Changes with nginx_substitutions_filter 0.3 2009-02-04
115
116 * Initial public release
117
118== Reporting a bug ==
119
120Questions/patches may be directed to Weibin Yao, yaoweibin@gmail.com.
121
122== Copyright & License ==
123
124This module is licensed under the BSD license.
125
126Copyright (C) 2014 by Weibin Yao <yaoweibin@gmail.com>.
127
128All rights reserved.
129
130Redistribution and use in source and binary forms, with or without
131modification, are permitted provided that the following conditions are
132met:
133
134 * Redistributions of source code must retain the above copyright
135 notice, this list of conditions and the following disclaimer.
136
137 * Redistributions in binary form must reproduce the above copyright
138 notice, this list of conditions and the following disclaimer in the
139 documentation and/or other materials provided with the distribution.
140
141THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
142IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
143TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
144PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
145HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
146SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
147TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
148PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
149LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
150NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
151SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
152
153
README.wiki
1= nginx_substitutions_filter =
2
3''Note: this module is not distributed with the Nginx source. Installation instructions can be found [[#Installation|below]].''
4
5== Description ==
6
7'''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 [http://httpd.apache.org/docs/trunk/mod/mod_substitute.html mod_substitute].
8
9== Example ==
10
11<geshi lang="nginx">
12location / {
13
14 subs_filter_types text/html text/css text/xml;
15 subs_filter st(\d*).example.com $1.example.com ir;
16 subs_filter a.example.com s.example.com;
17 subs_filter http://$host https://$host;
18
19}
20</geshi>
21
22== Directives ==
23
24* [[#subs_filter_types|subs_filter_types]]
25* [[#subs_filter|subs_filter]]
26
27=== subs_filter_types ===
28
29'''syntax:''' ''subs_filter_types mime-type [mime-types] ''
30
31'''default:''' ''subs_filter_types text/html''
32
33'''context:''' ''http, server, location''
34
35''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''.
36
37This 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:
38
39proxy_set_header Accept-Encoding "";
40
41=== subs_filter ===
42
43'''syntax:''' ''subs_filter source_str destination_str [gior] ''
44
45'''default:''' ''none''
46
47'''context:''' ''http, server, location''
48
49''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:
50* ''g''(default): Replace all the match strings.
51* ''i'': Perform a case-insensitive match.
52* ''o'': Just replace the first one.
53* ''r'': The pattern is treated as a regular expression, default is fixed string.
54
55=== subs_filter_bypass ===
56
57'''syntax:''' ''subs_filter_bypass $variable1 ...''
58
59'''default:''' ''none''
60
61'''context:''' ''http, server, location''
62
63You 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.
64
65== Installation ==
66
67To install, get the source with subversion:
68
69<code>
70git clone git://github.com/yaoweibin/ngx_http_substitutions_filter_module.git
71</code>
72
73and then compile nginx with the following option:
74
75<code>
76./configure --add-module=/path/to/ngx_http_substitutions_filter_module
77</code>
78
79== Known issue ==
80* Can't substitute the response header.
81
82== CHANGES ==
83
84Changes with nginx_substitutions_filter 0.6.4 2014-02-15
85
86* Now non-200 response will work
87* added the subs_filter_bypass directive
88
89Changes with nginx_substitutions_filter 0.6.2 2012-08-26
90
91* fixed a bug of buffer overlap
92* fixed a bug with last zero buffer
93
94Changes with nginx_substitutions_filter 0.6.0 2012-06-30
95
96* refactor this module
97
98Changes with nginx_substitutions_filter 0.5.2 2010-08-11
99
100* do many optimizing for this module
101* fix a bug of buffer overlap
102* fix a segment fault bug when output chain return NGX_AGAIN.
103* fix a bug about last buffer with no linefeed. This may cause segment fault. Thanks for Josef Fröhle
104
105Changes with nginx_substitutions_filter 0.5 2010-04-15
106
107* refactor the source structure, create branches of dev
108* fix a bug of small chunk of buffers causing lose content
109* fix the bug of last_buf and the nginx's compatibility above 0.8.25
110* fix a bug with unwanted capture config error in fix string substitution
111* add feature of regex captures
112
113Changes with nginx_substitutions_filter 0.4 2009-12-23
114
115* fix many bugs
116
117Changes with nginx_substitutions_filter 0.3 2009-02-04
118
119* Initial public release
120
121== Reporting a bug ==
122
123Questions/patches may be directed to Weibin Yao, yaoweibin@gmail.com.
124
125== Copyright & License ==
126
127This module is licensed under the BSD license.
128
129Copyright (C) 2014 by Weibin Yao <yaoweibin@gmail.com>.
130
131All rights reserved.
132
133Redistribution and use in source and binary forms, with or without
134modification, are permitted provided that the following conditions are
135met:
136
137* Redistributions of source code must retain the above copyright
138 notice, this list of conditions and the following disclaimer.
139
140* Redistributions in binary form must reproduce the above copyright
141 notice, this list of conditions and the following disclaimer in the
142 documentation and/or other materials provided with the distribution.
143
144THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
145IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
146TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
147PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
148HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
149SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
150TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
151PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
152LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
153NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
154SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
155
156