granicus.if.org Git - apache/blob - docs/manual/mod/mod_filter.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
   3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
   4 <!-- $LastChangedRevision$ -->
   5
   6 <!--
   7  Copyright 2004-2005 The Apache Software Foundation or its licensors, as
   8  applicable.
   9
  10  Licensed under the Apache License, Version 2.0 (the "License");
  11  you may not use this file except in compliance with the License.
  12  You may obtain a copy of the License at
  13
  14      http://www.apache.org/licenses/LICENSE-2.0
  15
  16  Unless required by applicable law or agreed to in writing, software
  17  distributed under the License is distributed on an "AS IS" BASIS,
  18  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  19  See the License for the specific language governing permissions and
  20  limitations under the License.
  21 -->
  22
  23 <modulesynopsis metafile="mod_filter.xml.meta">
  24
  25 <name>mod_filter</name>
  26 <description>Context-sensitive smart filter configuration module</description>
  27 <status>Base</status>
  28 <sourcefile>mod_filter.c</sourcefile>
  29 <identifier>filter_module</identifier>
  30 <compatibility>Version 2.1 and later</compatibility>
  31
  32 <summary>
  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).</p>
  37
  38     <p><module>mod_filter</module> works by introducing indirection into
  39     the filter 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 <module>mod_filter</module>; no change to existing filter modules is
  43     required (although it may be possible to simplify them).</p>
  44 </summary>
  45
  46 <section id="smart"><title>Smart Filtering</title>
  47     <p>In the traditional filtering model, filters are inserted unconditionally
  48     using <directive module="mod_mime">AddOutputFilter</directive> and family.
  49     Each filter then needs to determine whether to run, and there is little
  50     flexibility available for server admins to allow the chain to be
  51     configured dynamically.</p>
  52
  53     <p><module>mod_filter</module> by contrast gives server administrators a
  54     great deal of flexibility in configuring the filter chain.  In fact,
  55     filters can be inserted based on any Request Header, Response Header
  56     or Environment Variable.  This generalises the limited flexibility offered
  57     by <directive module="core">AddOutputFilterByType</directive>, and fixes
  58     it to work correctly with dynamic content, regardless of the
  59     content generator.  The ability to dispatch based on Environment
  60     Variables offers the full flexibility of configuration with
  61     <module>mod_rewrite</module> to anyone who needs it.</p>
  62 </section>
  63
  64 <section id="terms"><title>Filter Declarations, Providers and Chains</title>
  65     <p class="figure">
  66     <img src="../images/mod_filter_old.gif" width="160" height="310"
  67     alt="[This image displays the traditional filter model]"/><br />
  68     <dfn>Figure 1:</dfn> The traditional filter model</p>
  69
  70     <p>In the traditional model, output filters are a simple chain
  71     from the content generator (handler) to the client.  This works well
  72     provided the filter chain can be correctly configured, but presents
  73     problems when the filters need to be configured dynamically based on
  74     the outcome of the handler.</p>
  75
  76     <p class="figure">
  77     <img src="../images/mod_filter_new.gif" width="423" height="331"
  78     alt="[This image shows the mod_filter model]"/><br />
  79     <dfn>Figure 2:</dfn> The <module>mod_filter</module> model</p>
  80
  81     <p><module>mod_filter</module> works by introducing indirection into
  82     the filter chain.  Instead of inserting filters in the chain, we insert
  83     a filter harness which in turn dispatches conditionally
  84     to a filter provider.  Any content filter may be used as a provider
  85     to <module>mod_filter</module>; no change to existing filter modules
  86     is required (although it may be possible to simplify them).  There can be
  87     multiple providers for one filter, but no more than one provider will
  88     run for any single request.</p>
  89
  90     <p>A filter chain comprises any number of instances of the filter
  91     harness, each of which may have any number of providers.  A special
  92     case is that of a single provider with unconditional dispatch: this
  93     is equivalent to inserting the provider filter directly into the chain.</p>
  94 </section>
  95
  96 <section id="config"><title>Configuring the Chain</title>
  97     <p>There are three stages to configuring a filter chain with
  98     <module>mod_filter</module>. For details of the directives, see below.</p>
  99
 100     <dl>
 101     <dt>Declare Filters</dt>
 102     <dd>The <directive module="mod_filter">FilterDeclare</directive> directive
 103     declares a filter, assigning it a name and filter type.  Required
 104     only if the filter is not the default type AP_FTYPE_RESOURCE.</dd>
 105
 106     <dt>Register Providers</dt>
 107     <dd>The <directive module="mod_filter">FilterProvider</directive>
 108     directive registers a provider with a filter. The filter may have
 109     been declared with <directive module="mod_filter"
 110     >FilterDeclare</directive>; if not, FilterProvider will implicitly
 111     declare it with the default type AP_FTYPE_RESOURCE. The provider
 112     must have been
 113     registered with <code>ap_register_output_filter</code> by some module.
 114     The remaining arguments to <directive module="mod_filter"
 115     >FilterProvider</directive> are a dispatch criterion and a match string.
 116     The former may be an HTTP request or response header, an environment
 117     variable, or the Handler used by this request.  The latter is matched
 118     to it for each request, to determine whether this provider will be
 119     used to implement the filter for this request.</dd>
 120
 121     <dt>Configure the Chain</dt>
 122     <dd>The above directives build components of a smart filter chain,
 123     but do not configure it to run.  The <directive module="mod_filter"
 124     >FilterChain</directive> directive builds a filter chain from smart
 125     filters declared, offering the flexibility to insert filters at the
 126     beginning or end of the chain, remove a filter, or clear the chain.</dd>
 127 </dl>
 128 </section>
 129
 130 <section id="examples"><title>Examples</title>
 131     <dl>
 132     <dt>Server side Includes (SSI)</dt>
 133     <dd>A simple case of using <module>mod_filter</module> in place of
 134     <directive module="core">AddOutputFilterByType</directive>
 135     <example>
 136       FilterDeclare SSI<br/>
 137       FilterProvider SSI INCLUDES resp=Content-Type $text/html<br/>
 138       FilterChain SSI
 139     </example>
 140     </dd>
 141
 142     <dt>Server side Includes (SSI)</dt>
 143     <dd>The same as the above but dispatching on handler (classic
 144     SSI behaviour; .shtml files get processed).
 145     <example>
 146       FilterProvider SSI INCLUDES Handler server-parsed<br/>
 147       FilterChain SSI
 148     </example>
 149     </dd>
 150
 151     <dt>Emulating mod_gzip with mod_deflate</dt>
 152     <dd>Insert INFLATE filter only if "gzip" is NOT in the
 153     Accept-Encoding header.  This filter runs with ftype CONTENT_SET.
 154     <example>
 155       FilterDeclare gzip CONTENT_SET<br/>
 156       FilterProvider gzip inflate req=Accept-Encoding !$gzip<br/>
 157       FilterChain gzip
 158     </example>
 159     </dd>
 160
 161     <dt>Image Downsampling</dt>
 162     <dd>Suppose we want to downsample all web images, and have filters
 163     for GIF, JPEG and PNG.
 164     <example>
 165       FilterProvider unpack jpeg_unpack Content-Type $image/jpeg<br/>
 166       FilterProvider unpack gif_unpack Content-Type $image/gif<br/>
 167       FilterProvider unpack png_unpack Content-Type $image/png<br/>
 168       <br />
 169       FilterProvider downsample downsample_filter Content-Type $image<br/>
 170       FilterProtocol downsample "change=yes"<br/>
 171       <br />
 172       FilterProvider repack jpeg_pack Content-Type $image/jpeg<br/>
 173       FilterProvider repack gif_pack Content-Type $image/gif<br/>
 174       FilterProvider repack png_pack Content-Type $image/png<br/>
 175       &lt;Location /image-filter&gt;<br/>
 176       <indent>
 177         FilterChain unpack downsample repack<br/>
 178       </indent>
 179       &lt;/Location&gt;
 180     </example>
 181     </dd>
 182     </dl>
 183 </section>
 184
 185 <section id="protocol"><title>Protocol Handling</title>
 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
 192     <ul>
 193     <li>Many filters will change the content, invalidating existing content
 194     tags, checksums, hashes, and lengths.</li>
 195
 196     <li>Filters that require an entire, unbroken response in input need to
 197     ensure they don't get byteranges from a backend.</li>
 198
 199     <li>Filters that transform output in a filter need to ensure they don't
 200     violate a <code>Cache-Control: no-transform</code> header from the
 201     backend.</li>
 202
 203     <li>Filters may make responses uncacheable.</li>
 204     </ul>
 205
 206     <p><module>mod_filter</module> aims to offer generic handling of these
 207     details of filter implementation, reducing the complexity required of
 208     content filter modules. This is work-in-progress; the
 209     <directive module="mod_filter">FilterProtocol</directive> implements
 210     some of this functionality for back-compatibility with Apache 2.0
 211     modules.  For httpd 2.1 and later, the
 212     <code>ap_register_output_filter_protocol</code> and
 213     <code>ap_filter_protocol</code> API enables filter modules to
 214     declare their own behaviour.</p>
 215
 216     <p>At the same time, <module>mod_filter</module> should not interfere
 217     with a filter that wants to handle all aspects of the protocol.  By
 218     default (i.e. in the absence of any <directive module="mod_filter"
 219     >FilterProtocol</directive> directives), <module>mod_filter</module>
 220     will leave the headers untouched.</p>
 221
 222     <p>At the time of writing, this feature is largely untested,
 223     as modules in common use are designed to work with 2.0.
 224     Modules using it should test it carefully.</p>
 225 </section>
 226
 227 <directivesynopsis>
 228 <name>FilterDeclare</name>
 229 <description>Declare a smart filter</description>
 230 <syntax>FilterDeclare <var>filter-name</var> <var>[type]</var></syntax>
 231 <contextlist><context>server config</context><context>virtual host</context>
 232 <context>directory</context><context>.htaccess</context></contextlist>
 233 <override>Options</override>
 234
 235 <usage>
 236     <p>This directive declares an output filter together with a
 237     header or environment variable that will determine runtime
 238     configuration.  The first argument is a <var>filter-name</var>
 239     for use in <directive module="mod_filter">FilterProvider</directive>,
 240     <directive module="mod_filter">FilterChain</directive> and
 241     <directive module="mod_filter">FilterProtocol</directive> directives.</p>
 242
 243     <p>The final (optional) argument
 244     is the type of filter, and takes values of <code>ap_filter_type</code>
 245     - namely <code>RESOURCE</code> (the default), <code>CONTENT_SET</code>,
 246     <code>PROTOCOL</code>, <code>TRANSCODE</code>, <code>CONNECTION</code>
 247     or <code>NETWORK</code>.</p>
 248 </usage>
 249 </directivesynopsis>
 250
 251 <directivesynopsis>
 252 <name>FilterProvider</name>
 253 <description>Register a content filter</description>
 254 <syntax>FilterProvider <var>filter-name</var> <var>provider-name</var>
 255  [req|resp|env]=<var>dispatch</var> <var>match</var></syntax>
 256 <contextlist><context>server config</context><context>virtual host</context>
 257 <context>directory</context><context>.htaccess</context></contextlist>
 258 <override>Options</override>
 259
 260 <usage>
 261     <p>This directive registers a <em>provider</em> for the smart filter.
 262     The provider will be called if and only if the <var>match</var> declared
 263     here matches the value of the header or environment variable declared
 264     as <var>dispatch</var>.</p>
 265
 266     <p>
 267     <var>provider-name</var> must have been registered by loading
 268     a module that registers the name with
 269     <code>ap_register_output_filter</code>.
 270 <!-- Placeholder; this is totally broken as of now
 271      , or declared with
 272     <directive module="mod_filter">FilterDeclare</directive>
 273     (or implicitly with another
 274     <directive module="mod_filter">FilterProvider</directive>).
 275 -->
 276     </p>
 277
 278     <p>The <var>dispatch</var> argument is a string with optional
 279     <code>req=</code>, <code>resp=</code> or <code>env=</code> prefix
 280     causing it to dispatch on (respectively) the request header, response
 281     header, or environment variable named.  In the absence of a
 282     prefix, it defaults to a response header.  A special case is the
 283     word <code>handler</code>, which causes <module>mod_filter</module>
 284     to dispatch on the content handler.</p>
 285
 286     <p>The <var>match</var> argument specifies a match that will be applied to
 287     the filter's <var>dispatch</var> criterion.  The <var>match</var> may be
 288     a string match (exact match or substring), a <glossary ref="regex"
 289     >regex</glossary>, an integer (greater, lessthan or equals), or
 290     unconditional.  The first characters of the <var>match</var> argument
 291     determines this:</p>
 292
 293     <p><strong>First</strong>, if the first character is an exclamation mark
 294     (<code>!</code>), this reverses the rule, so the provider will be used
 295     if and only if the match <em>fails</em>.</p>
 296
 297     <p><strong>Second</strong>, it interprets the first character excluding
 298     any leading <code>!</code> as follows:</p>
 299
 300     <table style="zebra" border="yes">
 301     <tr><th>Character</th><th>Description</th></tr>
 302     <tr><td><em>(none)</em></td><td>exact match</td></tr>
 303     <tr><td><code>$</code></td><td>substring match</td></tr>
 304     <tr><td><code>/</code></td><td>regex match (delimited by a second <code>/</code>)</td></tr>
 305     <tr><td><code>=</code></td><td>integer equality</td></tr>
 306     <tr><td><code>&lt;</code></td><td>integer less-than</td></tr>
 307     <tr><td><code>&lt;=</code></td><td>integer less-than or equal</td></tr>
 308     <tr><td><code>&gt;</code></td><td>integer greater-than</td></tr>
 309     <tr><td><code>&gt;=</code></td><td>integer greater-than or equal</td></tr>
 310     <tr><td><code>*</code></td><td>Unconditional match</td></tr>
 311     </table>
 312 </usage>
 313 </directivesynopsis>
 314
 315 <directivesynopsis>
 316 <name>FilterChain</name>
 317 <description>Configure the filter chain</description>
 318 <syntax>FilterChain [+=-@!]<var>filter-name</var> <var>...</var></syntax>
 319 <contextlist><context>server config</context><context>virtual host</context>
 320 <context>directory</context><context>.htaccess</context></contextlist>
 321 <override>Options</override>
 322
 323 <usage>
 324     <p>This configures an actual filter chain, from declared filters.
 325     <directive>FilterChain</directive> takes any number of arguments,
 326     each optionally preceded with a single-character control that
 327     determines what to do:</p>
 328
 329     <dl>
 330     <dt><code>+<var>filter-name</var></code></dt>
 331     <dd>Add <var>filter-name</var> to the end of the filter chain</dd>
 332
 333     <dt><code>@<var>filter-name</var></code></dt>
 334     <dd>Insert <var>filter-name</var> at the start of the filter chain</dd>
 335
 336     <dt><code>-<var>filter-name</var></code></dt>
 337     <dd>Remove <var>filter-name</var> from the filter chain</dd>
 338
 339     <dt><code>=<var>filter-name</var></code></dt>
 340     <dd>Empty the filter chain and insert <var>filter-name</var></dd>
 341
 342     <dt><code>!</code></dt>
 343     <dd>Empty the filter chain</dd>
 344
 345     <dt><code><var>filter-name</var></code></dt>
 346     <dd>Equivalent to <code>+<var>filter-name</var></code></dd>
 347     </dl>
 348 </usage>
 349 </directivesynopsis>
 350
 351 <directivesynopsis>
 352 <name>FilterProtocol</name>
 353 <description>Deal with correct HTTP protocol handling</description>
 354 <syntax>FilterProtocol <var>filter-name</var> [<var>provider-name</var>]
 355     <var>proto-flags</var></syntax>
 356 <contextlist><context>server config</context><context>virtual host</context>
 357 <context>directory</context><context>.htaccess</context></contextlist>
 358 <override>Options</override>
 359
 360 <usage>
 361     <p>This directs <module>mod_filter</module> to deal with ensuring the
 362     filter doesn't run when it shouldn't, and that the HTTP response
 363     headers are correctly set taking into account the effects of the
 364     filter.</p>
 365
 366     <p>There are two forms of this directive.  With three arguments, it
 367     applies specifically to a <var>filter-name</var> and a
 368     <var>provider-name</var> for that filter.
 369     With two arguments it applies to a <var>filter-name</var> whenever the
 370     filter runs <em>any</em> provider.</p>
 371
 372     <p><var>proto-flags</var> is one or more of</p>
 373
 374     <dl>
 375     <dt><code>change=yes</code></dt>
 376     <dd>The filter changes the content, including possibly the content
 377     length</dd>
 378
 379     <dt><code>change=1:1</code></dt>
 380     <dd>The filter changes the content, but will not change the content
 381     length</dd>
 382
 383     <dt><code>byteranges=no</code></dt>
 384     <dd>The filter cannot work on byteranges and requires complete input</dd>
 385
 386     <dt><code>proxy=no</code></dt>
 387     <dd>The filter should not run in a proxy context</dd>
 388
 389     <dt><code>proxy=transform</code></dt>
 390     <dd>The filter transforms the response in a manner incompatible with
 391     the HTTP <code>Cache-Control: no-transform</code> header.</dd>
 392
 393     <dt><code>cache=no</code></dt>
 394     <dd>The filter renders the output uncacheable (eg by introducing randomised
 395     content changes)</dd>
 396     </dl>
 397 </usage>
 398 </directivesynopsis>
 399
 400 <directivesynopsis>
 401 <name>FilterTrace</name>
 402 <description>Get debug/diagnostic information from
 403     <module>mod_filter</module></description>
 404 <syntax>FilterTrace <var>filter-name</var> <var>level</var></syntax>
 405 <contextlist><context>server config</context><context>virtual host</context>
 406 <context>directory</context></contextlist>
 407
 408 <usage>
 409     <p>This directive generates debug information from
 410     <module>mod_filter</module>.
 411     It is designed to help test and debug providers (filter modules), although
 412     it may also help with <module>mod_filter</module> itself.</p>
 413
 414     <p>The debug output depends on the <var>level</var> set:</p>
 415     <dl>
 416     <dt><code>0</code> (default)</dt>
 417     <dd>No debug information is generated.</dd>
 418
 419     <dt><code>1</code></dt>
 420     <dd><module>mod_filter</module> will record buckets and brigades
 421     passing through the filter to the error log, before the provider has
 422     processed them. This is similar to the information generated by
 423     <a href="http://apache.webthing.com/mod_diagnostics/">mod_diagnostics</a>.
 424     </dd>
 425
 426     <dt><code>2</code> (not yet implemented)</dt>
 427     <dd>Will dump the full data passing through to a tempfile before the
 428     provider. <strong>For single-user debug only</strong>; this will not
 429     support concurrent hits.</dd>
 430     </dl>
 431 </usage>
 432 </directivesynopsis>
 433
 434 </modulesynopsis>
 435