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