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.min.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.4</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.4</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="/fr/mod/mod_ext_filter.html" hreflang="fr" rel="alternate" title="Fran�ais"> fr </a> | 29<a href="/ja/mod/mod_ext_filter.html" hreflang="ja" rel="alternate" title="Japanese"> ja </a> | 30<a href="/ko/mod/mod_ext_filter.html" hreflang="ko" rel="alternate" title="Korean"> ko </a></p> 31</div> 32<table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Pass the response body through an external program before 33delivery to the client</td></tr> 34<tr><th><a href="module-dict.html#Status">Status:</a></th><td>Extension</td></tr> 35<tr><th><a href="module-dict.html#ModuleIdentifier">Module�Identifier:</a></th><td>ext_filter_module</td></tr> 36<tr><th><a href="module-dict.html#SourceFile">Source�File:</a></th><td>mod_ext_filter.c</td></tr></table> 37<h3>Summary</h3> 38 39 <p><code class="module"><a href="/mod/mod_ext_filter.html">mod_ext_filter</a></code> presents a simple and familiar 40 programming model for <a href="/filter.html">filters</a>. With 41 this module, a program which reads from stdin and writes to stdout 42 (i.e., a Unix-style filter command) can be a filter for 43 Apache. This filtering mechanism is much slower than using a 44 filter which is specially written for the Apache API and runs 45 inside of the Apache server process, but it does have the 46 following benefits:</p> 47 48 <ul> 49 <li>the programming model is much simpler</li> 50 51 <li>any programming/scripting language can be used, provided 52 that it allows the program to read from standard input and 53 write to standard output</li> 54 55 <li>existing programs can be used unmodified as Apache 56 filters</li> 57 </ul> 58 59 <p>Even when the performance characteristics are not suitable 60 for production use, <code class="module"><a href="/mod/mod_ext_filter.html">mod_ext_filter</a></code> can be used as 61 a prototype environment for filters.</p> 62 63</div> 64<div id="quickview"><h3 class="directives">Directives</h3> 65<ul id="toc"> 66<li><img alt="" src="/images/down.gif" /> <a href="#extfilterdefine">ExtFilterDefine</a></li> 67<li><img alt="" src="/images/down.gif" /> <a href="#extfilteroptions">ExtFilterOptions</a></li> 68</ul> 69<h3>Topics</h3> 70<ul id="topics"> 71<li><img alt="" src="/images/down.gif" /> <a href="#examples">Examples</a></li> 72</ul><h3>See also</h3> 73<ul class="seealso"> 74<li><a href="/filter.html">Filters</a></li> 75</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div> 76<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 77<div class="section"> 78<h2><a name="examples" id="examples">Examples</a></h2> 79 80 <h3>Generating HTML from some other type of response</h3> 81 <pre class="prettyprint lang-config"># mod_ext_filter directive to define a filter 82# to HTML-ize text/c files using the external 83# program /usr/bin/enscript, with the type of 84# the result set to text/html 85ExtFilterDefine c-to-html mode=output \ 86 intype=text/c outtype=text/html \ 87 cmd="/usr/bin/enscript --color -W html -Ec -o - -" 88 89<Directory "/export/home/trawick/apacheinst/htdocs/c"> 90 # core directive to cause the new filter to 91 # be run on output 92 SetOutputFilter c-to-html 93 94 # mod_mime directive to set the type of .c 95 # files to text/c 96 AddType text/c .c 97</Directory></pre> 98 99 100 101 <h3>Implementing a content encoding filter</h3> 102 <p>Note: this gzip example is just for the purposes of illustration. 103 Please refer to <code class="module"><a href="/mod/mod_deflate.html">mod_deflate</a></code> for a practical 104 implementation.</p> 105 106 <pre class="prettyprint lang-config"># mod_ext_filter directive to define the external filter 107ExtFilterDefine gzip mode=output cmd=/bin/gzip 108 109<Location /gzipped> 110 111 # core directive to cause the gzip filter to be 112 # run on output 113 SetOutputFilter gzip 114 115 # mod_headers directive to add 116 # "Content-Encoding: gzip" header field 117 Header set Content-Encoding gzip 118</Location></pre> 119 120 121 122 <h3>Slowing down the server</h3> 123 <pre class="prettyprint lang-config"># mod_ext_filter directive to define a filter 124# which runs everything through cat; cat doesn't 125# modify anything; it just introduces extra pathlength 126# and consumes more resources 127ExtFilterDefine slowdown mode=output cmd=/bin/cat \ 128 preservescontentlength 129 130<Location /> 131 # core directive to cause the slowdown filter to 132 # be run several times on output 133 # 134 SetOutputFilter slowdown;slowdown;slowdown 135</Location></pre> 136 137 138 139 <h3>Using sed to replace text in the response</h3> 140 <pre class="prettyprint lang-config"># mod_ext_filter directive to define a filter which 141# replaces text in the response 142# 143ExtFilterDefine fixtext mode=output intype=text/html \ 144 cmd="/bin/sed s/verdana/arial/g" 145 146<Location /> 147 # core directive to cause the fixtext filter to 148 # be run on output 149 SetOutputFilter fixtext 150</Location></pre> 151 152 153 154 <h3>Tracing another filter</h3> 155 <pre class="prettyprint lang-config"># Trace the data read and written by mod_deflate 156# for a particular client (IP 192.168.1.31) 157# experiencing compression problems. 158# This filter will trace what goes into mod_deflate. 159ExtFilterDefine tracebefore \ 160 cmd="/bin/tracefilter.pl /tmp/tracebefore" \ 161 EnableEnv=trace_this_client 162 163# This filter will trace what goes after mod_deflate. 164# Note that without the ftype parameter, the default 165# filter type of AP_FTYPE_RESOURCE would cause the 166# filter to be placed *before* mod_deflate in the filter 167# chain. Giving it a numeric value slightly higher than 168# AP_FTYPE_CONTENT_SET will ensure that it is placed 169# after mod_deflate. 170ExtFilterDefine traceafter \ 171 cmd="/bin/tracefilter.pl /tmp/traceafter" \ 172 EnableEnv=trace_this_client ftype=21 173 174<Directory /usr/local/docs> 175 SetEnvIf Remote_Addr 192.168.1.31 trace_this_client 176 SetOutputFilter tracebefore;deflate;traceafter 177</Directory></pre> 178 179 180 <div class="example"><h3>Here is the filter which traces the data:</h3><pre class="prettyprint lang-perl">#!/usr/local/bin/perl -w 181use strict; 182 183open(SAVE, ">$ARGV[0]") 184 or die "can't open $ARGV[0]: $?"; 185 186while (<STDIN>) { 187 print SAVE $_; 188 print $_; 189} 190 191close(SAVE);</pre> 192</div> 193 194</div> 195<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 196<div class="directive-section"><h2><a name="ExtFilterDefine" id="ExtFilterDefine">ExtFilterDefine</a> <a name="extfilterdefine" id="extfilterdefine">Directive</a></h2> 197<table class="directive"> 198<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Define an external filter</td></tr> 199<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ExtFilterDefine <var>filtername</var> <var>parameters</var></code></td></tr> 200<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr> 201<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 202<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ext_filter</td></tr> 203</table> 204 <p>The <code class="directive">ExtFilterDefine</code> directive defines the 205 characteristics of an external filter, including the program to 206 run and its arguments.</p> 207 208 <p><var>filtername</var> specifies the name of the filter being 209 defined. This name can then be used in <code class="directive"><a href="/mod/core.html#setoutputfilter">SetOutputFilter</a></code> 210 directives. It must be unique among all registered filters. 211 <em>At the present time, no error is reported by the 212 register-filter API, so a problem with duplicate names isn't 213 reported to the user.</em></p> 214 215 <p>Subsequent parameters can appear in any order and define the 216 external command to run and certain other characteristics. The 217 only required parameter is <code>cmd=</code>. These parameters 218 are:</p> 219 220 <dl> 221 <dt><code>cmd=<var>cmdline</var></code></dt> 222 223 <dd>The <code>cmd=</code> keyword allows you to specify the 224 external command to run. If there are arguments after the 225 program name, the command line should be surrounded in 226 quotation marks (<em>e.g.</em>, <code>cmd="<var>/bin/mypgm</var> 227 <var>arg1</var> <var>arg2</var>"</code>.) Normal shell quoting is 228 not necessary since the program is run directly, bypassing the shell. 229 Program arguments are blank-delimited. A backslash can be used to 230 escape blanks which should be part of a program argument. Any 231 backslashes which are part of the argument must be escaped with 232 backslash themselves. In addition to the standard CGI environment 233 variables, DOCUMENT_URI, DOCUMENT_PATH_INFO, and 234 QUERY_STRING_UNESCAPED will also be set for the program.</dd> 235 236 <dt><code>mode=<var>mode</var></code></dt> 237 238 <dd>Use <code>mode=output</code> (the default) for filters which 239 process the response. Use <code>mode=input</code> for filters 240 which process the request. <code>mode=input</code> is available 241 in Apache 2.1 and later.</dd> 242 243 <dt><code>intype=<var>imt</var></code></dt> 244 245 <dd>This parameter specifies the internet media type (<em>i.e.</em>, 246 MIME type) of documents which should be filtered. By default, 247 all documents are filtered. If <code>intype=</code> is 248 specified, the filter will be disabled for documents of other 249 types.</dd> 250 251 <dt><code>outtype=<var>imt</var></code></dt> 252 253 <dd>This parameter specifies the internet media type (<em>i.e.</em>, 254 MIME type) of filtered documents. It is useful when the 255 filter changes the internet media type as part of the 256 filtering operation. By default, the internet media type is 257 unchanged.</dd> 258 259 <dt><code>PreservesContentLength</code></dt> 260 261 <dd>The <code>PreservesContentLength</code> keyword specifies 262 that the filter preserves the content length. This is not the 263 default, as most filters change the content length. In the 264 event that the filter doesn't modify the length, this keyword 265 should be specified.</dd> 266 267 <dt><code>ftype=<var>filtertype</var></code></dt> 268 269 <dd>This parameter specifies the numeric value for filter type 270 that the filter should be registered as. The default value, 271 AP_FTYPE_RESOURCE, is sufficient in most cases. If the filter 272 needs to operate at a different point in the filter chain than 273 resource filters, then this parameter will be necessary. See 274 the AP_FTYPE_foo definitions in util_filter.h for appropriate 275 values.</dd> 276 277 <dt><code>disableenv=<var>env</var></code></dt> 278 279 <dd>This parameter specifies the name of an environment variable 280 which, if set, will disable the filter.</dd> 281 282 <dt><code>enableenv=<var>env</var></code></dt> 283 284 <dd>This parameter specifies the name of an environment variable 285 which must be set, or the filter will be disabled.</dd> 286 </dl> 287 288</div> 289<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 290<div class="directive-section"><h2><a name="ExtFilterOptions" id="ExtFilterOptions">ExtFilterOptions</a> <a name="extfilteroptions" id="extfilteroptions">Directive</a></h2> 291<table class="directive"> 292<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> 293<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ExtFilterOptions <var>option</var> [<var>option</var>] ...</code></td></tr> 294<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ExtFilterOptions NoLogStderr</code></td></tr> 295<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory</td></tr> 296<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 297<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_ext_filter</td></tr> 298</table> 299 <p>The <code class="directive">ExtFilterOptions</code> directive specifies 300 special processing options for <code class="module"><a href="/mod/mod_ext_filter.html">mod_ext_filter</a></code>. 301 <var>Option</var> can be one of</p> 302 303 <dl> 304 <dt><code>LogStderr | NoLogStderr</code></dt> 305 306 <dd>The <code>LogStderr</code> keyword specifies that 307 messages written to standard error by the external filter 308 program will be saved in the Apache error log. 309 <code>NoLogStderr</code> disables this feature.</dd> 310 311 <dt><code>Onfail=[abort|remove]</code></dt> 312 <dd>Determines how to proceed if the external filter program 313 cannot be started. With <code>abort</code> (the default value) 314 the request will be aborted. With <code>remove</code>, the 315 filter is removed and the request continues without it.</dd> 316 </dl> 317 318 <pre class="prettyprint lang-config">ExtFilterOptions LogStderr</pre> 319 320 321 <p>Messages written to the filter's standard error will be stored 322 in the Apache error log.</p> 323 324</div> 325</div> 326<div class="bottomlang"> 327<p><span>Available Languages: </span><a href="/en/mod/mod_ext_filter.html" title="English"> en </a> | 328<a href="/fr/mod/mod_ext_filter.html" hreflang="fr" rel="alternate" title="Fran�ais"> fr </a> | 329<a href="/ja/mod/mod_ext_filter.html" hreflang="ja" rel="alternate" title="Japanese"> ja </a> | 330<a href="/ko/mod/mod_ext_filter.html" hreflang="ko" rel="alternate" title="Korean"> ko </a></p> 331</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> 332<script type="text/javascript"><!--//--><![CDATA[//><!-- 333var comments_shortname = 'httpd'; 334var comments_identifier = 'http://httpd.apache.org/docs/2.4/mod/mod_ext_filter.html'; 335(function(w, d) { 336 if (w.location.hostname.toLowerCase() == "httpd.apache.org") { 337 d.write('<div id="comments_thread"><\/div>'); 338 var s = d.createElement('script'); 339 s.type = 'text/javascript'; 340 s.async = true; 341 s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier; 342 (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s); 343 } 344 else { 345 d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>'); 346 } 347})(window, document); 348//--><!]]></script></div><div id="footer"> 349<p class="apache">Copyright 2014 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> 350<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[//><!-- 351if (typeof(prettyPrint) !== 'undefined') { 352 prettyPrint(); 353} 354//--><!]]></script> 355</body></html>
