granicus.if.org Git - apache/blob - docs/manual/mod/mod_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_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.1</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-project/">Documentation</a> &gt; <a href="../">Version 2.1</a> &gt; <a href="./">Modules</a></div>
  21 <div id="page-content">
  22 <div id="preamble"><h1>Apache Module mod_filter</h1>
  23 <div class="toplang">
  24 <p><span>Available Languages: </span><a href="../en/mod/mod_filter.html" title="English">&nbsp;en&nbsp;</a></p>
  25 </div>
  26 <table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Context-sensitive smart filter configuration module</td></tr>
  27 <tr><th><a href="module-dict.html#Status">Status:</a></th><td>Extension</td></tr>
  28 <tr><th><a href="module-dict.html#ModuleIdentifier">Module Identifier:</a></th><td>filter_module</td></tr>
  29 <tr><th><a href="module-dict.html#SourceFile">Source File:</a></th><td>mod_filter.c</td></tr>
  30 <tr><th><a href="module-dict.html#Compatibility">Compatibility:</a></th><td>Apache 2.0 and higher</td></tr></table>
  31 <h3>Summary</h3>
  32
  33 <p>This module enables smart, context-sensitive configuration of
  34 output content filters.  For example, apache can be configured to
  35 process different content-types through different filters, even
  36 when the content-type is not known in advance (e.g. in a proxy).
  37 </p>
  38 <p>mod_filter works by introducing indirection into the filter
  39 chain.  Instead of inserting filters in the chain, we insert
  40 a filter harness which in turn dispatches conditionally
  41 to a filter provider.  Any content filter may be used as a provider
  42 to mod_filter; no change to existing filter modules is required
  43 (although it may be possible to simplify them).
  44 </p>
  45 </div>
  46 <div id="quickview"><h3 class="directives">Directives</h3>
  47 <ul id="toc">
  48 <li><img alt="" src="../images/down.gif" /> <a href="#filterchain">FilterChain</a></li>
  49 <li><img alt="" src="../images/down.gif" /> <a href="#filterdeclare">FilterDeclare</a></li>
  50 <li><img alt="" src="../images/down.gif" /> <a href="#filterprotocol">FilterProtocol</a></li>
  51 <li><img alt="" src="../images/down.gif" /> <a href="#filterprovider">FilterProvider</a></li>
  52 <li><img alt="" src="../images/down.gif" /> <a href="#filtertrace">FilterTrace</a></li>
  53 </ul>
  54 <h3>Topics</h3>
  55 <ul id="topics">
  56 <li><img alt="" src="../images/down.gif" /> <a href="#smart">Smart Filtering</a></li>
  57 <li><img alt="" src="../images/down.gif" /> <a href="#terms">Filter Declarations, Providers and Chains</a></li>
  58 <li><img alt="" src="../images/down.gif" /> <a href="#config">Configuring the Chain</a></li>
  59 <li><img alt="" src="../images/down.gif" /> <a href="#examples">Examples</a></li>
  60 <li><img alt="" src="../images/down.gif" /> <a href="#protocol">Protocol Handling</a></li>
  61 </ul></div>
  62 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  63 <div class="section">
  64 <h2><a name="smart" id="smart">Smart Filtering</a></h2>
  65 <p>In the traditional filtering model, filters are inserted unconditionally
  66 using <code class="directive"><a href="../mod/mod_mime.html#addoutputfilter">AddOutputFilter</a></code> and family.
  67 Each filter then needs to determine whether to run, and there is little
  68 flexibility available for server admins to allow the chain to be
  69 configured dynamically.</p>
  70 <p>mod_filter by contrast gives server administrators a great deal of
  71 flexibility in configuring the filter chain.  In fact, filters can be
  72 inserted based on any Request Header, Response Header or Environment
  73 Variable.  This generalises the limited flexibility offered by
  74 <code class="directive"><a href="../mod/core.html#addoutputfilterbytype">AddOutputFilterByType</a></code>, and fixes
  75 it to work correctly with dynamic content, regardless of the
  76 content generator.  The ability to dispatch based on Environment
  77 Variables offers the full flexibility of configuration with
  78 <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> to anyone who needs it.</p>
  79
  80 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  81 <div class="section">
  82 <h2><a name="terms" id="terms">Filter Declarations, Providers and Chains</a></h2>
  83 <img src="../images/mod_filter_old.gif" alt="" />
  84 <p>In the traditional model, output filters are a simple chain
  85 from the content generator (handler) to the client.  This works well
  86 provided the filter chain can be correctly configured, but presents
  87 problems when the filters need to be configured dynamically based on
  88 the outcome of the handler.</p>
  89 <img src="../images/mod_filter_new.gif" alt="" />
  90 <p>mod_filter works by introducing indirection into the filter
  91 chain.  Instead of inserting filters in the chain, we insert
  92 a filter harness which in turn dispatches conditionally
  93 to a filter provider.  Any content filter may be used as a provider
  94 to mod_filter; no change to existing filter modules is required
  95 (although it may be possible to simplify them).  There can be
  96 multiple providers for one filter, but no more than one provider will
  97 run for any single request.
  98 </p>
  99 <p>A filter chain comprises any number of instances of the filter
 100 harness, each of which may have any number of providers.  A special
 101 case is that of a single provider with unconditional dispatch: this
 102 is equivalent to inserting the provider filter directly into the chain.
 103 </p>
 104 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 105 <div class="section">
 106 <h2><a name="config" id="config">Configuring the Chain</a></h2>
 107 <p>There are three stages to configuring a filter chain with mod_filter.
 108 For details of the directives, see below.</p>
 109 <dl>
 110 <dt>Declare Filters</dt>
 111 <dd>The <code class="directive">FilterDeclare</code> directive declares a filter,
 112 assigning it a name and a dispatch criterion.</dd>
 113 <dt>Register Providers</dt>
 114 <dd>The <code class="directive">FilterProvider</code> directive registers a provider with a filter.
 115 The filter must have been registered with <code class="directive">FilterDeclare</code>.
 116 The provider must have been registered with
 117 <code>ap_register_output_filter</code> by some module.  The final argument
 118 to <code class="directive">FilterProvider</code> is a match string, that will be checked against
 119 the filter's dispatch criterion to determine whether to run this provider.</dd>
 120 <dt>Configure the Chain</dt>
 121 <dd>The above directives build components of a smart filter chain,
 122 but do not configure it to run.  The <code class="directive">FilterChain</code> directive
 123 builds a filter chain from smart filters declared, offering the
 124 flexibility to insert filters at the beginning or end of the chain,
 125 remove a filter, or clear the chain.</dd>
 126 </dl>
 127 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 128 <div class="section">
 129 <h2><a name="examples" id="examples">Examples</a></h2>
 130 <dl>
 131 <dt>Serverside Includes (SSI)</dt>
 132 <dd>
 133 <p>A simple case of using mod_filter in place of
 134 <code>AddOutputFilterByType</code></p>
 135 <div class="example"><p><code>
 136 FilterDeclare SSI Content-Type<br />
 137 FilterProvider SSI INCLUDES $text/html<br />
 138 FilterChain SSI<br />
 139 </code></p></div>
 140 </dd>
 141 <dt>Serverside Includes (SSI)</dt>
 142 <dd>
 143 <p>The same as the above but dispatching on handler (classic
 144 SSI behaviour; .shtml files get processed).</p>
 145 <div class="example"><p><code>
 146 FilterDeclare SSI Handler<br />
 147 FilterProvider SSI INCLUDES server-parsed<br />
 148 FilterChain SSI<br />
 149 </code></p></div>
 150 </dd>
 151 <dt>Emulating mod_gzip with mod_deflate</dt>
 152 <dd>
 153 <p>Insert INFLATE filter only if "gzip" is NOT in the
 154 Accept-Encoding header.</p>
 155 <div class="example"><p><code>
 156 FilterDeclare gzip req=Accept-Encoding<br />
 157 FilterProvider gzip inflate !$gzip<br />
 158 FilterChain gzip<br />
 159 </code></p></div>
 160 </dd>
 161 <dt>Image Downsampling</dt>
 162 <dd>
 163 <p>Suppose we want to downsample all web images, and have filters
 164 for GIF, JPEG and PNG.</p>
 165 <div class="example"><p><code>
 166 FilterDeclare unpack Content-Type<br />
 167 FilterProvider unpack jpeg_unpack $image/jpeg<br />
 168 FilterProvider unpack gif_unpack $image/gif<br />
 169 FilterProvider unpack png_unpack $image/png<br />
 170 FilterDeclare downsample Content-Type<br />
 171 FilterProvider downsample downsample_filter $image<br />
 172 FilterProtocol downsample "change=yes"<br />
 173 FilterDeclare repack Content-Type<br />
 174 FilterProvider repack jpeg_pack $image/jpeg<br />
 175 FilterProvider repack gif_pack $image/gif<br />
 176 FilterProvider repack png_pack $image/png<br />
 177 &lt;Location /image-filter&gt;<br />
 178 FilterChain unpack downsample repack<br />
 179 &lt;/Location&gt;
 180 </code></p></div>
 181 </dd>
 182 </dl>
 183 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 184 <div class="section">
 185 <h2><a name="protocol" id="protocol">Protocol Handling</a></h2>
 186 <p>Historically, each filter is responsible for ensuring that whatever
 187 changes it makes are correctly represented in the HTTP response headers,
 188 and that it does not run when it would make an illegal change.  This
 189 imposes a burden on filter authors to re-implement some common
 190 functionality in every filter:</p>
 191 <ul>
 192 <li>Many filters will change the content, invalidating existing content
 193 tags, checksums, hashes, and lengths.</li>
 194 <li>Filters that require an entire, unbroken response in input need to
 195 ensure they don't get byteranges from a backend.</li>
 196 <li>Filters that transform output in a filter need to ensure they don't
 197 violate a <code>Cache-Control: no-transform</code> header from the
 198 backend.</li>
 199 <li>Filters may make responses uncacheable.</li>
 200 </ul>
 201 <p>mod_filter aims to offer generic handling of these details of filter
 202 implementation, reducing the complexity required of content filter modules.
 203 This is work-in-progress; the <code class="directive">FilterProtocol</code>
 204 implements some of this functionality, but there are no API calls yet.</p>
 205 <p>At the same time, mod_filter should not interfere with a filter that
 206 wants to handle all aspects of the protocol.  By default (i.e. in the
 207 absence of any <code class="directive">FilterProtocol</code> directives), mod_filter
 208 will leave the headers untouched.</p>
 209 </div>
 210 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 211 <div class="directive-section"><h2><a name="FilterChain" id="FilterChain">FilterChain</a> <a name="filterchain" id="filterchain">Directive</a></h2>
 212 <table class="directive">
 213 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configure the filter chain</td></tr>
 214 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>FilterChain ([+=-@!]<var>filter-name</var>)+</code></td></tr>
 215 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 216 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 217 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_filter</td></tr>
 218 </table>
 219 <p>This configures an actual filter chain, from declared filters.
 220 <code class="directive">FilterChain</code> takes any number of arguments,
 221 each optionally preceded with a single-character control that
 222 determines what to do:</p>
 223 <dl>
 224 <dt>+filter-name</dt>
 225 <dd>Add filter-name to the end of the filter chain</dd>
 226 <dt>@filter-name</dt>
 227 <dd>Insert filter-name at the start of the filter chain</dd>
 228 <dt>-filter-name</dt>
 229 <dd>Remove filter-name from the filter chain</dd>
 230 <dt>=filter-name</dt>
 231 <dd>Empty the filter chain and insert filter-name</dd>
 232 <dt>!</dt>
 233 <dd>Empty the filter chain</dd>
 234 <dt>filter-name</dt>
 235 <dd>Equivalent to +filter-name</dd>
 236 </dl>
 237
 238 </div>
 239 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 240 <div class="directive-section"><h2><a name="FilterDeclare" id="FilterDeclare">FilterDeclare</a> <a name="filterdeclare" id="filterdeclare">Directive</a></h2>
 241 <table class="directive">
 242 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Declare a smart filter</td></tr>
 243 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>FilterDeclare <var>filter-name</var> [req|resp|env]=<var>dispatch</var>
 244 <var>[type]</var>
 245 </code></td></tr>
 246 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 247 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 248 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_filter</td></tr>
 249 </table>
 250 <p>This directive declares an output filter together with a
 251 header or environment variable that will determine runtime
 252 configuration.  The first argument is a <code>filter-name</code>
 253 for use in <code class="directive">FilterProvider</code>,
 254 <code class="directive">FilterChain</code> and
 255 <code class="directive">FilterProtocol</code> directives.</p>
 256 <p>The second is a string with optional <code>req=</code>,
 257 <code>resp=</code> or <code>env=</code> prefix causing it
 258 to dispatch on (respectively) the request header, response
 259 header, or environment variable named.  In the absence of a
 260 prefix, it defaults to a response header.  A special case is the
 261 word "handler", which causes mod_filter to dispatch on the handler.</p>
 262 <p>The final (optional) argument
 263 is the type of filter, and takes values of <var>ap_filter_type</var>
 264 - namely <var>RESOURCE</var> (the default), <var>CONTENT_SET</var>,
 265 <var>PROTOCOL</var>, <var>TRANSCODE</var>, <var>CONNECTION</var>
 266 or <var>NETWORK</var>.
 267 </p>
 268
 269
 270 </div>
 271 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 272 <div class="directive-section"><h2><a name="FilterProtocol" id="FilterProtocol">FilterProtocol</a> <a name="filterprotocol" id="filterprotocol">Directive</a></h2>
 273 <table class="directive">
 274 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Deal with correct HTTP protocol handling</td></tr>
 275 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>FilterProtocol filter-name [provider-name] "proto-flags"</code></td></tr>
 276 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 277 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 278 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_filter</td></tr>
 279 </table>
 280 <p>This directs mod_filter to deal with ensuring the filter doesn't run
 281 when it shouldn't, and that the HTTP response headers are correctly set
 282 taking into account the effects of the filter.</p>
 283 <p>There are two forms of this directive.  With three arguments, it
 284 applies specifically to a filter-name and a provider for that filter.
 285 With two arguments it applies to a filter-name whenever the filter runs
 286 <em>any</em> provider.</p>
 287 <p>proto-flags is one or more of</p>
 288 <dl>
 289 <dt>change=yes</dt>
 290 <dd>The filter changes the content, including possibly the content length</dd>
 291 <dt>change=1:1</dt>
 292 <dd>The filter changes the content, but will not change the content length</dd>
 293 <dt>byteranges=no</dt>
 294 <dd>The filter cannot work on byteranges and requires complete input</dd>
 295 <dt>proxy=no</dt>
 296 <dd>The filter should not run in a proxy context</dd>
 297 <dt>proxy=transform</dt>
 298 <dd>The filter transforms the response in a manner incompatible with
 299 the HTTP <code>Cache-Control: no-transform</code> header.</dd>
 300 <dt>cache=no</dt>
 301 <dd>The filter renders the output uncacheable (eg by introducing randomised
 302 content changes)</dd>
 303 </dl>
 304
 305 </div>
 306 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 307 <div class="directive-section"><h2><a name="FilterProvider" id="FilterProvider">FilterProvider</a> <a name="filterprovider" id="filterprovider">Directive</a></h2>
 308 <table class="directive">
 309 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Register a content filter</td></tr>
 310 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>FilterProvider <var>filter-name</var> <var>provider-name</var> <var>match</var></code></td></tr>
 311 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 312 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 313 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_filter</td></tr>
 314 </table>
 315 <p>This directive registers a <em>provider</em> for the smart filter.
 316 The provider will be called if and only if the <var>match</var> declared
 317 here matches the value of the header or environment variable declared
 318 as <var>dispatch</var> in the <code class="directive">FilterDeclare</code>
 319 directive that declared <var>filter-name</var>.</p>
 320 <p><var>filter-name</var> must have been declared with
 321 <code class="directive">FilterDeclare</code>.  <var>provider-name</var> must have
 322 been registered by loading a module that registers the name with
 323 <code>ap_register_output_filter</code>.</p>
 324 <p>The <var>match</var> argument specifies a match that will be applied to
 325 the filter's <var>dispatch</var> criterion.  The match may be a string
 326 match (exact match or substring), a regexp, an integer (greater, lessthan
 327 or equals), or unconditional.  The first characters of the <var>match</var>
 328 argument determines this:</p>
 329 <p><strong>First</strong>, if the first character is an exclamation mark
 330 <strong>!</strong>, this reverses the rule, so the provider will be used
 331 if and only if the match <em>fails</em>.</p>
 332 <p><strong>Second</strong>, it interprets the first character excluding
 333 any leading ! as follows:</p>
 334 <dl>
 335 <dt>default</dt>
 336 <dd>exact match</dd>
 337 <dt>$</dt>
 338 <dd>substring match</dd>
 339 <dt>/</dt>
 340 <dd>regexp match</dd>
 341 <dt>=</dt>
 342 <dd>integer equality</dd>
 343 <dt>&lt;</dt>
 344 <dd>integer less-than</dd>
 345 <dt>&gt;</dt>
 346 <dd>integer greater-than</dd>
 347 <dt>*</dt>
 348 <dd>Unconditional match</dd>
 349 </dl>
 350
 351 </div>
 352 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 353 <div class="directive-section"><h2><a name="FilterTrace" id="FilterTrace">FilterTrace</a> <a name="filtertrace" id="filtertrace">Directive</a></h2>
 354 <table class="directive">
 355 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Get debug/diagnostic information from mod_filter</td></tr>
 356 <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>FilterTrace filter-name level</code></td></tr>
 357 <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
 358 <tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
 359 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_filter</td></tr>
 360 </table>
 361 <p>This directive generates debug information from mod_filter.
 362 It is designed to help test and debug providers (filter modules), although
 363 it may also help with mod_filter itself.</p>
 364 <p>The debug output depends on the level set:</p>
 365 <dl>
 366 <dt>0 (default)</dt>
 367 <dd>No debug information is generated.</dd>
 368 <dt>1</dt>
 369 <dd>mod_filter will record buckets and brigades passing through the filter
 370 to the error log, before the provider has processed them.
 371 This is similar to the information generated by
 372 <a href="http://apache.webthing.com/mod_diagnostics/">mod_diagnostics</a>.
 373 </dd>
 374 <dt>2 (not yet implemented)</dt>
 375 <dd>Will dump the full data passing through to a tempfile before the provider.
 376 <strong>For single-user debug only</strong>; this will not
 377 support concurrent hits.</dd>
 378 </dl>
 379
 380 </div>
 381 </div>
 382 <div class="bottomlang">
 383 <p><span>Available Languages: </span><a href="../en/mod/mod_filter.html" title="English">&nbsp;en&nbsp;</a></p>
 384 </div><div id="footer">
 385 <p class="apache">Copyright 1999-2004 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>
 386 <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>
 387 </body></html>