1<?xml version="1.0" encoding="ISO-8859-1"?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> 3<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!-- 4 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 5 This file is generated from xml source: DO NOT EDIT 6 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 7 --> 8<title>mod_ext_filter - Apache HTTP Server</title> 9<link href="/style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" /> 10<link href="/style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" /> 11<link href="/style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link rel="stylesheet" type="text/css" href="/style/css/prettify.css" /> 12<script src="/style/scripts/prettify.js" type="text/javascript"> 13</script> 14 15<link href="/images/favicon.ico" rel="shortcut icon" /></head> 16<body> 17<div id="page-header"> 18<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p> 19<p class="apache">Apache HTTP Server Version 2.2</p> 20<img alt="" src="/images/feather.gif" /></div> 21<div class="up"><a href="./"><img title="<-" alt="<-" src="/images/left.gif" /></a></div> 22<div id="path"> 23<a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="../">Version 2.2</a> > <a href="./">Modules</a></div> 24<div id="page-content"> 25<div id="preamble"><h1>Apache Module mod_ext_filter</h1> 26<div class="toplang"> 27<p><span>Available Languages: </span><a href="/en/mod/mod_ext_filter.html" title="English"> en </a> | 28<a href="/ja/mod/mod_ext_filter.html" hreflang="ja" rel="alternate" title="Japanese"> ja </a> | 29<a href="/ko/mod/mod_ext_filter.html" hreflang="ko" rel="alternate" title="Korean"> ko </a></p> 30</div> 31<table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Pass the response body through an external program before 32delivery to the client</td></tr> 33<tr><th><a href="module-dict.html#Status">Status:</a></th><td>Extension</td></tr> 34<tr><th><a href="module-dict.html#ModuleIdentifier">Module�Identifier:</a></th><td>ext_filter_module</td></tr> 35<tr><th><a href="module-dict.html#SourceFile">Source�File:</a></th><td>mod_ext_filter.c</td></tr></table> 36<h3>Summary</h3> 37 38 <p><code class="module"><a href="/mod/mod_ext_filter.html">mod_ext_filter</a></code> presents a simple and familiar 39 programming model for <a href="/filter.html">filters</a>. With 40 this module, a program which reads from stdin and writes to stdout 41 (i.e., a Unix-style filter command) can be a filter for 42 Apache. This filtering mechanism is much slower than using a 43 filter which is specially written for the Apache API and runs 44 inside of the Apache server process, but it does have the 45 following benefits:</p> 46 47 <ul> 48 <li>the programming model is much simpler</li> 49 50 <li>any programming/scripting language can be used, provided 51 that it allows the program to read from standard input and 52 write to standard output</li> 53 54 <li>existing programs can be used unmodified as Apache 55 filters</li> 56 </ul> 57 58 <p>Even when the performance characteristics are not suitable 59 for production use, <code class="module"><a href="/mod/mod_ext_filter.html">mod_ext_filter</a></code> can be used as 60 a prototype environment for filters.</p> 61 62</div> 63<div id="quickview"><h3 class="directives">Directives</h3> 64<ul id="toc"> 65<li><img alt="" src="/images/down.gif" /> <a href="#extfilterdefine">ExtFilterDefine</a></li> 66<li><img alt="" src="/images/down.gif" /> <a href="#extfilteroptions">ExtFilterOptions</a></li> 67</ul> 68<h3>Topics</h3> 69<ul id="topics"> 70<li><img alt="" src="/images/down.gif" /> <a href="#examples">Examples</a></li> 71</ul><h3>See also</h3> 72<ul class="seealso"> 73<li><a href="/filter.html">Filters</a></li> 74</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div> 75<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 76<div class="section"> 77<h2><a name="examples" id="examples">Examples</a></h2> 78 79 <h3>Generating HTML from some other type of response</h3> 80 <div class="example"><p><code> 81 # mod_ext_filter directive to define a filter<br /> 82 # to HTML-ize text/c files using the external<br /> 83 # program /usr/bin/enscript, with the type of<br /> 84 # the result set to text/html<br /> 85 ExtFilterDefine c-to-html mode=output \<br /> 86 <span class="indent"> 87 intype=text/c outtype=text/html \<br /> 88 cmd="/usr/bin/enscript --color -W html -Ec -o - -"<br /> 89 </span> 90 <br /> 91 <Directory "/export/home/trawick/apacheinst/htdocs/c"><br /> 92 <span class="indent"> 93 # core directive to cause the new filter to<br /> 94 # be run on output<br /> 95 SetOutputFilter c-to-html<br /> 96 <br /> 97 # mod_mime directive to set the type of .c<br /> 98 # files to text/c<br /> 99 AddType text/c .c<br /> 100 <br /> 101 # mod_ext_filter directive to set the debug<br /> 102 # level just high enough to see a log message<br /> 103 # per request showing the configuration in force<br /> 104 ExtFilterOptions DebugLevel=1<br /> 105 </span> 106 </Directory> 107 </code></p></div> 108 109 110 <h3>Implementing a content encoding filter</h3> 111 <p>Note: this gzip example is just for the purposes of illustration. 112 Please refer to <code class="module"><a href="/mod/mod_deflate.html">mod_deflate</a></code> for a practical 113 implementation.</p> 114 115 <div class="example"><p><code> 116 # mod_ext_filter directive to define the external filter<br /> 117 ExtFilterDefine gzip mode=output cmd=/bin/gzip<br /> 118 <br /> 119 <Location /gzipped><br /> 120 <span class="indent"> 121 # core directive to cause the gzip filter to be<br /> 122 # run on output<br /> 123 SetOutputFilter gzip<br /> 124 <br /> 125 # mod_header directive to add<br /> 126 # "Content-Encoding: gzip" header field<br /> 127 Header set Content-Encoding gzip<br /> 128 </span> 129 </Location> 130 </code></p></div> 131 132 133 <h3>Slowing down the server</h3> 134 <div class="example"><p><code> 135 # mod_ext_filter directive to define a filter<br /> 136 # which runs everything through cat; cat doesn't<br /> 137 # modify anything; it just introduces extra pathlength<br /> 138 # and consumes more resources<br /> 139 ExtFilterDefine slowdown mode=output cmd=/bin/cat \<br /> 140 <span class="indent"> 141 preservescontentlength<br /> 142 </span> 143 <br /> 144 <Location /><br /> 145 <span class="indent"> 146 # core directive to cause the slowdown filter to<br /> 147 # be run several times on output<br /> 148 #<br /> 149 SetOutputFilter slowdown;slowdown;slowdown<br /> 150 </span> 151 </Location> 152 </code></p></div> 153 154 155 <h3>Using sed to replace text in the response</h3> 156 <div class="example"><p><code> 157 # mod_ext_filter directive to define a filter which<br /> 158 # replaces text in the response<br /> 159 #<br /> 160 ExtFilterDefine fixtext mode=output intype=text/html \<br /> 161 <span class="indent"> 162 cmd="/bin/sed s/verdana/arial/g"<br /> 163 </span> 164 <br /> 165 <Location /><br /> 166 <span class="indent"> 167 # core directive to cause the fixtext filter to<br /> 168 # be run on output<br /> 169 SetOutputFilter fixtext<br /> 170 </span> 171 </Location> 172 </code></p></div> 173 174 175 <h3>Tracing another filter</h3> 176 <div class="example"><p><code> 177 # Trace the data read and written by mod_deflate<br /> 178 # for a particular client (IP 192.168.1.31)<br /> 179 # experiencing compression problems.<br /> 180 # This filter will trace what goes into mod_deflate.<br /> 181 ExtFilterDefine tracebefore \<br /> 182 <span class="indent"> 183 cmd="/bin/tracefilter.pl /tmp/tracebefore" \<br /> 184 EnableEnv=trace_this_client<br /> 185 </span> 186 <br /> 187 # This filter will trace what goes after mod_deflate.<br /> 188 # Note that without the ftype parameter, the default<br /> 189 # filter type of AP_FTYPE_RESOURCE would cause the<br /> 190 # filter to be placed *before* mod_deflate in the filter<br /> 191 # chain. Giving it a numeric value slightly higher than<br /> 192 # AP_FTYPE_CONTENT_SET will ensure that it is placed<br /> 193 # after mod_deflate.<br /> 194 ExtFilterDefine traceafter \<br /> 195 <span class="indent"> 196 cmd="/bin/tracefilter.pl /tmp/traceafter" \<br /> 197 EnableEnv=trace_this_client ftype=21<br /> 198 </span> 199 <br /> 200 <Directory /usr/local/docs><br /> 201 <span class="indent"> 202 SetEnvIf Remote_Addr 192.168.1.31 trace_this_client<br /> 203 SetOutputFilter tracebefore;deflate;traceafter<br /> 204 </span> 205 </Directory> 206 </code></p></div> 207 208 <div class="example"><h3>Here is the filter which traces the data:</h3><p><code> 209 #!/usr/local/bin/perl -w<br /> 210 use strict;<br /> 211 <br /> 212 open(SAVE, ">$ARGV[0]")<br /> 213 <span class="indent"> 214 or die "can't open $ARGV[0]: $?";<br /> 215 </span> 216 <br /> 217 while (<STDIN>) {<br /> 218 <span class="indent"> 219 print SAVE $_;<br /> 220 print $_;<br /> 221 </span> 222 }<br /> 223 <br /> 224 close(SAVE); 225 </code></p></div> 226 227</div> 228<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 229<div class="directive-section"><h2><a name="ExtFilterDefine" id="ExtFilterDefine">ExtFilterDefine</a> <a name="extfilterdefine" id="extfilterdefine">Directive</a></h2> 230<table class="directive"> 231<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Define an external filter</td></tr> 232<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ExtFilterDefine <var>filtername</var> <var>parameters</var></code></td></tr> 233<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr> 234<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 235<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ext_filter</td></tr> 236</table> 237 <p>The <code class="directive">ExtFilterDefine</code> directive defines the 238 characteristics of an external filter, including the program to 239 run and its arguments.</p> 240 241 <p><var>filtername</var> specifies the name of the filter being 242 defined. This name can then be used in <code class="directive"><a href="/mod/core.html#setoutputfilter">SetOutputFilter</a></code> 243 directives. It must be unique among all registered filters. 244 <em>At the present time, no error is reported by the 245 register-filter API, so a problem with duplicate names isn't 246 reported to the user.</em></p> 247 248 <p>Subsequent parameters can appear in any order and define the 249 external command to run and certain other characteristics. The 250 only required parameter is <code>cmd=</code>. These parameters 251 are:</p> 252 253 <dl> 254 <dt><code>cmd=<var>cmdline</var></code></dt> 255 256 <dd>The <code>cmd=</code> keyword allows you to specify the 257 external command to run. If there are arguments after the 258 program name, the command line should be surrounded in 259 quotation marks (<em>e.g.</em>, <code>cmd="<var>/bin/mypgm</var> 260 <var>arg1</var> <var>arg2</var>"</code>.) Normal shell quoting is 261 not necessary since the program is run directly, bypassing the shell. 262 Program arguments are blank-delimited. A backslash can be used to 263 escape blanks which should be part of a program argument. Any 264 backslashes which are part of the argument must be escaped with 265 backslash themselves. In addition to the standard CGI environment 266 variables, DOCUMENT_URI, DOCUMENT_PATH_INFO, and 267 QUERY_STRING_UNESCAPED will also be set for the program.</dd> 268 269 <dt><code>mode=<var>mode</var></code></dt> 270 271 <dd>Use <code>mode=output</code> (the default) for filters which 272 process the response. Use <code>mode=input</code> for filters 273 which process the request. <code>mode=input</code> is available 274 in Apache 2.1 and later.</dd> 275 276 <dt><code>intype=<var>imt</var></code></dt> 277 278 <dd>This parameter specifies the internet media type (<em>i.e.</em>, 279 MIME type) of documents which should be filtered. By default, 280 all documents are filtered. If <code>intype=</code> is 281 specified, the filter will be disabled for documents of other 282 types.</dd> 283 284 <dt><code>outtype=<var>imt</var></code></dt> 285 286 <dd>This parameter specifies the internet media type (<em>i.e.</em>, 287 MIME type) of filtered documents. It is useful when the 288 filter changes the internet media type as part of the 289 filtering operation. By default, the internet media type is 290 unchanged.</dd> 291 292 <dt><code>PreservesContentLength</code></dt> 293 294 <dd>The <code>PreservesContentLength</code> keyword specifies 295 that the filter preserves the content length. This is not the 296 default, as most filters change the content length. In the 297 event that the filter doesn't modify the length, this keyword 298 should be specified.</dd> 299 300 <dt><code>ftype=<var>filtertype</var></code></dt> 301 302 <dd>This parameter specifies the numeric value for filter type 303 that the filter should be registered as. The default value, 304 AP_FTYPE_RESOURCE, is sufficient in most cases. If the filter 305 needs to operate at a different point in the filter chain than 306 resource filters, then this parameter will be necessary. See 307 the AP_FTYPE_foo definitions in util_filter.h for appropriate 308 values.</dd> 309 310 <dt><code>disableenv=<var>env</var></code></dt> 311 312 <dd>This parameter specifies the name of an environment variable 313 which, if set, will disable the filter.</dd> 314 315 <dt><code>enableenv=<var>env</var></code></dt> 316 317 <dd>This parameter specifies the name of an environment variable 318 which must be set, or the filter will be disabled.</dd> 319 </dl> 320 321</div> 322<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 323<div class="directive-section"><h2><a name="ExtFilterOptions" id="ExtFilterOptions">ExtFilterOptions</a> <a name="extfilteroptions" id="extfilteroptions">Directive</a></h2> 324<table class="directive"> 325<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configure <code class="module"><a href="/mod/mod_ext_filter.html">mod_ext_filter</a></code> options</td></tr> 326<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ExtFilterOptions <var>option</var> [<var>option</var>] ...</code></td></tr> 327<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ExtFilterOptions DebugLevel=0 NoLogStderr</code></td></tr> 328<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory</td></tr> 329<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 330<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ext_filter</td></tr> 331</table> 332 <p>The <code class="directive">ExtFilterOptions</code> directive specifies 333 special processing options for <code class="module"><a href="/mod/mod_ext_filter.html">mod_ext_filter</a></code>. 334 <var>Option</var> can be one of</p> 335 336 <dl> 337 <dt><code>DebugLevel=<var>n</var></code></dt> 338 339 <dd> 340 The <code>DebugLevel</code> keyword allows you to specify 341 the level of debug messages generated by 342 <code class="module"><a href="/mod/mod_ext_filter.html">mod_ext_filter</a></code>. By default, no debug messages 343 are generated. This is equivalent to 344 <code>DebugLevel=0</code>. With higher numbers, more debug 345 messages are generated, and server performance will be 346 degraded. The actual meanings of the numeric values are 347 described with the definitions of the DBGLVL_ constants 348 near the beginning of <code>mod_ext_filter.c</code>. 349 350 <p>Note: The core directive <code class="directive"><a href="/mod/core.html#loglevel">LogLevel</a></code> should be used to cause debug messages to 351 be stored in the Apache error log.</p> 352 </dd> 353 354 <dt><code>LogStderr | NoLogStderr</code></dt> 355 356 <dd>The <code>LogStderr</code> keyword specifies that 357 messages written to standard error by the external filter 358 program will be saved in the Apache error log. 359 <code>NoLogStderr</code> disables this feature.</dd> 360 361 <dt><code>Onfail=[abort|remove]</code> (new in httpd version 2.2.12).</dt> 362 <dd>Determines how to proceed if the external filter program 363 cannot be started. With <code>abort</code> (the default value) 364 the request will be aborted. With <code>remove</code>, the 365 filter is removed and the request continues without it.</dd> 366 </dl> 367 368 <div class="example"><h3>Example</h3><p><code> 369 ExtFilterOptions LogStderr DebugLevel=0 370 </code></p></div> 371 372 <p>Messages written to the filter's standard error will be stored 373 in the Apache error log. No debug messages will be generated by 374 <code class="module"><a href="/mod/mod_ext_filter.html">mod_ext_filter</a></code>. </p> 375 376</div> 377</div> 378<div class="bottomlang"> 379<p><span>Available Languages: </span><a href="/en/mod/mod_ext_filter.html" title="English"> en </a> | 380<a href="/ja/mod/mod_ext_filter.html" hreflang="ja" rel="alternate" title="Japanese"> ja </a> | 381<a href="/ko/mod/mod_ext_filter.html" hreflang="ko" rel="alternate" title="Korean"> ko </a></p> 382</div><div class="top"><a href="#page-header"><img src="/images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>Notice:</strong><br />This is not a Q&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our <a href="http://httpd.apache.org/lists.html">mailing lists</a>.</div> 383<script type="text/javascript"><!--//--><![CDATA[//><!-- 384var comments_shortname = 'httpd'; 385var comments_identifier = 'http://httpd.apache.org/docs/2.2/mod/mod_ext_filter.html'; 386(function(w, d) { 387 if (w.location.hostname.toLowerCase() == "httpd.apache.org") { 388 d.write('<div id="comments_thread"><\/div>'); 389 var s = d.createElement('script'); 390 s.type = 'text/javascript'; 391 s.async = true; 392 s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier; 393 (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s); 394 } 395 else { 396 d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>'); 397 } 398})(window, document); 399//--><!]]></script></div><div id="footer"> 400<p class="apache">Copyright 2013 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p> 401<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!-- 402if (typeof(prettyPrint) !== 'undefined') { 403 prettyPrint(); 404} 405//--><!]]></script> 406</body></html>
