2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
4 <!-- $LastChangedRevision$ -->
7 Licensed to the Apache Software Foundation (ASF) under one or more
8 contributor license agreements. See the NOTICE file distributed with
9 this work for additional information regarding copyright ownership.
10 The ASF licenses this file to You under the Apache License, Version 2.0
11 (the "License"); you may not use this file except in compliance with
12 the License. You may obtain a copy of the License at
14 http://www.apache.org/licenses/LICENSE-2.0
16 Unless required by applicable law or agreed to in writing, software
17 distributed under the License is distributed on an "AS IS" BASIS,
18 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19 See the License for the specific language governing permissions and
20 limitations under the License.
23 <modulesynopsis metafile="mod_ext_filter.xml.meta">
25 <name>mod_ext_filter</name>
26 <description>Pass the response body through an external program before
27 delivery to the client</description>
28 <status>Extension</status>
29 <sourcefile>mod_ext_filter.c</sourcefile>
30 <identifier>ext_filter_module</identifier>
33 <p><module>mod_ext_filter</module> presents a simple and familiar
34 programming model for <a href="../filter.html">filters</a>. With
35 this module, a program which reads from stdin and writes to stdout
36 (i.e., a Unix-style filter command) can be a filter for
37 Apache. This filtering mechanism is much slower than using a
38 filter which is specially written for the Apache API and runs
39 inside of the Apache server process, but it does have the
40 following benefits:</p>
43 <li>the programming model is much simpler</li>
45 <li>any programming/scripting language can be used, provided
46 that it allows the program to read from standard input and
47 write to standard output</li>
49 <li>existing programs can be used unmodified as Apache
53 <p>Even when the performance characteristics are not suitable
54 for production use, <module>mod_ext_filter</module> can be used as
55 a prototype environment for filters.</p>
58 <seealso><a href="../filter.html">Filters</a></seealso>
60 <section id="examples"><title>Examples</title>
62 <section><title>Generating HTML from some other type of response</title>
63 <highlight language="config">
64 # mod_ext_filter directive to define a filter
65 # to HTML-ize text/c files using the external
66 # program /usr/bin/enscript, with the type of
67 # the result set to text/html
68 ExtFilterDefine c-to-html mode=output \
69 intype=text/c outtype=text/html \
70 cmd="/usr/bin/enscript --color -W html -Ec -o - -"
72 <Directory "/export/home/trawick/apacheinst/htdocs/c">
73 # core directive to cause the new filter to
75 SetOutputFilter c-to-html
77 # mod_mime directive to set the type of .c
84 <section><title>Implementing a content encoding filter</title>
85 <p>Note: this gzip example is just for the purposes of illustration.
86 Please refer to <module>mod_deflate</module> for a practical
89 <highlight language="config">
90 # mod_ext_filter directive to define the external filter
91 ExtFilterDefine gzip mode=output cmd=/bin/gzip
93 <Location /gzipped>
95 # core directive to cause the gzip filter to be
99 # mod_header directive to add
100 # "Content-Encoding: gzip" header field
101 Header set Content-Encoding gzip
106 <section><title>Slowing down the server</title>
107 <highlight language="config">
108 # mod_ext_filter directive to define a filter
109 # which runs everything through cat; cat doesn't
110 # modify anything; it just introduces extra pathlength
111 # and consumes more resources
112 ExtFilterDefine slowdown mode=output cmd=/bin/cat \
113 preservescontentlength
116 # core directive to cause the slowdown filter to
117 # be run several times on output
119 SetOutputFilter slowdown;slowdown;slowdown
124 <section><title>Using sed to replace text in the response</title>
125 <highlight language="config">
126 # mod_ext_filter directive to define a filter which
127 # replaces text in the response
129 ExtFilterDefine fixtext mode=output intype=text/html \
130 cmd="/bin/sed s/verdana/arial/g"
133 # core directive to cause the fixtext filter to
135 SetOutputFilter fixtext
140 <section><title>Tracing another filter</title>
141 <highlight language="config">
142 # Trace the data read and written by mod_deflate
143 # for a particular client (IP 192.168.1.31)
144 # experiencing compression problems.
145 # This filter will trace what goes into mod_deflate.
146 ExtFilterDefine tracebefore \
147 cmd="/bin/tracefilter.pl /tmp/tracebefore" \
148 EnableEnv=trace_this_client
150 # This filter will trace what goes after mod_deflate.
151 # Note that without the ftype parameter, the default
152 # filter type of AP_FTYPE_RESOURCE would cause the
153 # filter to be placed *before* mod_deflate in the filter
154 # chain. Giving it a numeric value slightly higher than
155 # AP_FTYPE_CONTENT_SET will ensure that it is placed
157 ExtFilterDefine traceafter \
158 cmd="/bin/tracefilter.pl /tmp/traceafter" \
159 EnableEnv=trace_this_client ftype=21
161 <Directory /usr/local/docs>
162 SetEnvIf Remote_Addr 192.168.1.31 trace_this_client
163 SetOutputFilter tracebefore;deflate;traceafter
167 <example><title>Here is the filter which traces the data:</title>
168 <highlight language="perl">
169 #!/usr/local/bin/perl -w
172 open(SAVE, ">$ARGV[0]")
173 or die "can't open $ARGV[0]: $?";
175 while (<STDIN>) {
184 </section> <!-- /Examples -->
187 <name>ExtFilterDefine</name>
188 <description>Define an external filter</description>
189 <syntax>ExtFilterDefine <var>filtername</var> <var>parameters</var></syntax>
190 <contextlist><context>server config</context></contextlist>
193 <p>The <directive>ExtFilterDefine</directive> directive defines the
194 characteristics of an external filter, including the program to
195 run and its arguments.</p>
197 <p><var>filtername</var> specifies the name of the filter being
198 defined. This name can then be used in <directive module="core"
199 >SetOutputFilter</directive>
200 directives. It must be unique among all registered filters.
201 <em>At the present time, no error is reported by the
202 register-filter API, so a problem with duplicate names isn't
203 reported to the user.</em></p>
205 <p>Subsequent parameters can appear in any order and define the
206 external command to run and certain other characteristics. The
207 only required parameter is <code>cmd=</code>. These parameters
211 <dt><code>cmd=<var>cmdline</var></code></dt>
213 <dd>The <code>cmd=</code> keyword allows you to specify the
214 external command to run. If there are arguments after the
215 program name, the command line should be surrounded in
216 quotation marks (<em>e.g.</em>, <code>cmd="<var>/bin/mypgm</var>
217 <var>arg1</var> <var>arg2</var>"</code>.) Normal shell quoting is
218 not necessary since the program is run directly, bypassing the shell.
219 Program arguments are blank-delimited. A backslash can be used to
220 escape blanks which should be part of a program argument. Any
221 backslashes which are part of the argument must be escaped with
222 backslash themselves. In addition to the standard CGI environment
223 variables, DOCUMENT_URI, DOCUMENT_PATH_INFO, and
224 QUERY_STRING_UNESCAPED will also be set for the program.</dd>
226 <dt><code>mode=<var>mode</var></code></dt>
228 <dd>Use <code>mode=output</code> (the default) for filters which
229 process the response. Use <code>mode=input</code> for filters
230 which process the request. <code>mode=input</code> is available
231 in Apache 2.1 and later.</dd>
233 <dt><code>intype=<var>imt</var></code></dt>
235 <dd>This parameter specifies the internet media type (<em>i.e.</em>,
236 MIME type) of documents which should be filtered. By default,
237 all documents are filtered. If <code>intype=</code> is
238 specified, the filter will be disabled for documents of other
241 <dt><code>outtype=<var>imt</var></code></dt>
243 <dd>This parameter specifies the internet media type (<em>i.e.</em>,
244 MIME type) of filtered documents. It is useful when the
245 filter changes the internet media type as part of the
246 filtering operation. By default, the internet media type is
249 <dt><code>PreservesContentLength</code></dt>
251 <dd>The <code>PreservesContentLength</code> keyword specifies
252 that the filter preserves the content length. This is not the
253 default, as most filters change the content length. In the
254 event that the filter doesn't modify the length, this keyword
255 should be specified.</dd>
257 <dt><code>ftype=<var>filtertype</var></code></dt>
259 <dd>This parameter specifies the numeric value for filter type
260 that the filter should be registered as. The default value,
261 AP_FTYPE_RESOURCE, is sufficient in most cases. If the filter
262 needs to operate at a different point in the filter chain than
263 resource filters, then this parameter will be necessary. See
264 the AP_FTYPE_foo definitions in util_filter.h for appropriate
267 <dt><code>disableenv=<var>env</var></code></dt>
269 <dd>This parameter specifies the name of an environment variable
270 which, if set, will disable the filter.</dd>
272 <dt><code>enableenv=<var>env</var></code></dt>
274 <dd>This parameter specifies the name of an environment variable
275 which must be set, or the filter will be disabled.</dd>
281 <name>ExtFilterOptions</name>
282 <description>Configure <module>mod_ext_filter</module> options</description>
283 <syntax>ExtFilterOptions <var>option</var> [<var>option</var>] ...</syntax>
284 <default>ExtFilterOptions NoLogStderr</default>
285 <contextlist><context>directory</context></contextlist>
288 <p>The <directive>ExtFilterOptions</directive> directive specifies
289 special processing options for <module>mod_ext_filter</module>.
290 <var>Option</var> can be one of</p>
293 <dt><code>LogStderr | NoLogStderr</code></dt>
295 <dd>The <code>LogStderr</code> keyword specifies that
296 messages written to standard error by the external filter
297 program will be saved in the Apache error log.
298 <code>NoLogStderr</code> disables this feature.</dd>
300 <dt><code>Onfail=[abort|remove]</code></dt>
301 <dd>Determines how to proceed if the external filter program
302 cannot be started. With <code>abort</code> (the default value)
303 the request will be aborted. With <code>remove</code>, the
304 filter is removed and the request continues without it.</dd>
307 <highlight language="config">
308 ExtFilterOptions LogStderr
311 <p>Messages written to the filter's standard error will be stored
312 in the Apache error log.</p>