docs/manual/mod/mod_ext_filter.html.en

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