<?xml version="1.0"?>
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
-<!-- $Revision: 1.8 $ -->
+<!-- $LastChangedRevision$ -->
<!--
- Copyright 2004 The Apache Software Foundation
-
- Licensed under the Apache License, Version 2.0 (the "License");
- you may not use this file except in compliance with the License.
- You may obtain a copy of the License at
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
<name>mod_filter</name>
<description>Context-sensitive smart filter configuration module</description>
-<status>Experimental</status>
+<status>Base</status>
<sourcefile>mod_filter.c</sourcefile>
<identifier>filter_module</identifier>
-<compatibility>Version 2.1 and higher</compatibility>
<summary>
<p>This module enables smart, context-sensitive configuration of
<p><module>mod_filter</module> by contrast gives server administrators a
great deal of flexibility in configuring the filter chain. In fact,
- filters can be inserted based on any Request Header, Response Header
- or Environment Variable. This generalises the limited flexibility offered
- by <directive module="core">AddOutputFilterByType</directive>, and fixes
- it to work correctly with dynamic content, regardless of the
- content generator. The ability to dispatch based on Environment
- Variables offers the full flexibility of configuration with
- <module>mod_rewrite</module> to anyone who needs it.</p>
+ filters can be inserted based on complex boolean
+ <a href="../expr.html">expressions</a> This generalises the limited
+ flexibility offered by <directive>AddOutputFilterByType</directive>.</p>
</section>
<section id="terms"><title>Filter Declarations, Providers and Chains</title>
<dl>
<dt>Declare Filters</dt>
<dd>The <directive module="mod_filter">FilterDeclare</directive> directive
- declares a filter, assigning it a name and a dispatch criterion.</dd>
-
+ declares a new smart filter, assigning it a name and optional filter
+ type.</dd>
<dt>Register Providers</dt>
<dd>The <directive module="mod_filter">FilterProvider</directive>
- directive registers a provider with a filter. The filter must have
- been registered with <directive module="mod_filter"
- >FilterDeclare</directive>. The provider must have been
+ directive registers a provider with a filter. The filter may have
+ been declared with <directive module="mod_filter"
+ >FilterDeclare</directive>; if not, FilterProvider will implicitly
+ declare it. The provider must have been
registered with <code>ap_register_output_filter</code> by some module.
The final argument to <directive module="mod_filter"
- >FilterProvider</directive> is a match string, that will be checked
- against the filter's dispatch criterion to determine whether to run
- this provider.</dd>
+ >FilterProvider</directive> is an expression: the provider will be
+ selected to run for a request if and only if the expression evaluates
+ to true. The expression may evaluate HTTP request or response
+ headers, environment variables, or the Handler used by this request.
+ Unlike earlier versions, mod_filter now supports complex expressions
+ involving multiple criteria with AND / OR logic (&& / ||)
+ and brackets. The details of the expression syntax are described in
+ the <a href="../expr.html">ap_expr documentation</a>.</dd>
<dt>Configure the Chain</dt>
<dd>The above directives build components of a smart filter chain,
beginning or end of the chain, remove a filter, or clear the chain.</dd>
</dl>
</section>
+<section id="errordocs"><title>Filtering and Response Status</title>
+ <p>mod_filter normally only runs filters on responses with
+ HTTP status 200 (OK). If you want to filter documents with
+ other response statuses, you can set the <var>filter-errordocs</var>
+ environment variable, and it will work on all responses
+ regardless of status. To refine this further, you can use
+ expression conditions with <directive>FilterProvider</directive>.</p>
+</section>
+<section id="upgrade"><title>Upgrading from Apache HTTP Server 2.2 Configuration</title>
+ <p>The <directive module="mod_filter">FilterProvider</directive>
+ directive has changed from httpd 2.2: the <var>match</var> and
+ <var>dispatch</var> arguments are replaced with a single but
+ more versatile <var>expression</var>. In general, you can convert
+ a match/dispatch pair to the two sides of an expression, using
+ something like:</p>
+ <example>"dispatch = 'match'"</example>
+ <p>The Request headers, Response headers and Environment variables
+ are now interpreted from syntax <var>%{req:foo}</var>,
+ <var>%{resp:foo}</var> and <var>%{env:foo}</var> respectively.
+ The variables <var>%{HANDLER}</var> and <var>%{CONTENT_TYPE}</var>
+ are also supported.</p>
+ <p>Note that the match no longer support substring matches. They can be
+ replaced by regular expression matches.</p>
+</section>
<section id="examples"><title>Examples</title>
<dl>
<dt>Server side Includes (SSI)</dt>
- <dd>A simple case of using <module>mod_filter</module> in place of
- <directive module="core">AddOutputFilterByType</directive>
- <example>
- FilterDeclare SSI Content-Type<br/>
- FilterProvider SSI INCLUDES $text/html<br/>
- FilterChain SSI
- </example>
+ <dd>A simple case replacing <directive>AddOutputFilterByType</directive>.
+ This example creates a new smart filter named "SSI" that conditionally leverates
+ the "INCLUDES" filter from <module>mod_include</module> as a provider.
+ <highlight language="config">
+FilterDeclare SSI
+FilterProvider SSI INCLUDES "%{CONTENT_TYPE} =~ m|^text/html|"
+FilterChain SSI
+ </highlight>
</dd>
<dt>Server side Includes (SSI)</dt>
<dd>The same as the above but dispatching on handler (classic
SSI behaviour; .shtml files get processed).
- <example>
- FilterDeclare SSI Handler<br/>
- FilterProvider SSI INCLUDES server-parsed<br/>
- FilterChain SSI
- </example>
+ <highlight language="config">
+FilterProvider SSI INCLUDES "%{HANDLER} = 'server-parsed'"
+FilterChain SSI
+ </highlight>
</dd>
<dt>Emulating mod_gzip with mod_deflate</dt>
- <dd>Insert INFLATE filter only if "gzip" is NOT in the
- Accept-Encoding header.
- <example>
- FilterDeclare gzip req=Accept-Encoding<br/>
- FilterProvider gzip inflate !$gzip<br/>
- FilterChain gzip
- </example>
+ <dd>This example demonstrates the dynamic properties granted to traditional
+ filters when a smart filter is constructed around them. A new smart filter
+ named "gzip" is created that dynamically inserts <module>mod_deflate</module>'s
+ INFLATE filter only if "gzip" is NOT in the Accept-Encoding header.
+ The gzip smart filter runs with type CONTENT_SET.
+ <highlight language="config">
+FilterDeclare gzip CONTENT_SET
+FilterProvider gzip INFLATE "%{req:Accept-Encoding} !~ /gzip/"
+FilterChain gzip
+ </highlight>
</dd>
<dt>Image Downsampling</dt>
- <dd>Suppose we want to downsample all web images, and have filters
- for GIF, JPEG and PNG.
- <example>
- FilterDeclare unpack Content-Type<br/>
- FilterProvider unpack jpeg_unpack $image/jpeg<br/>
- FilterProvider unpack gif_unpack $image/gif<br/>
- FilterProvider unpack png_unpack $image/png<br/>
- <br />
- FilterDeclare downsample Content-Type<br/>
- FilterProvider downsample downsample_filter $image<br/>
- FilterProtocol downsample "change=yes"<br/>
- <br />
- FilterDeclare repack Content-Type<br/>
- FilterProvider repack jpeg_pack $image/jpeg<br/>
- FilterProvider repack gif_pack $image/gif<br/>
- FilterProvider repack png_pack $image/png<br/>
- <Location /image-filter><br/>
- <indent>
- FilterChain unpack downsample repack<br/>
- </indent>
- </Location>
- </example>
+ <dd>This example demonstrates further abstractions that the smart filtering.
+ Suppose we want to downsample all web images, and have different
+ filter providers for manipulating GIF, JPEG and PNG
+ The configuration defines smart filters "unpack" and "repack" via
+ the harness that invokes the right underlying filter providers based on
+ the content type at runtime.
+ <highlight language="config">
+FilterProvider unpack jpeg_unpack "%{CONTENT_TYPE} = 'image/jpeg'"
+FilterProvider unpack gif_unpack "%{CONTENT_TYPE} = 'image/gif'"
+FilterProvider unpack png_unpack "%{CONTENT_TYPE} = 'image/png'"
+
+FilterProvider downsample downsample_filter "%{CONTENT_TYPE} = m|^image/(jpeg|gif|png)|"
+FilterProtocol downsample "change=yes"
+
+FilterProvider repack jpeg_pack "%{CONTENT_TYPE} = 'image/jpeg'"
+FilterProvider repack gif_pack "%{CONTENT_TYPE} = 'image/gif'"
+FilterProvider repack png_pack "%{CONTENT_TYPE} = 'image/png'"
+<Location "/image-filter">
+ FilterChain unpack downsample repack
+</Location>
+ </highlight>
</dd>
</dl>
</section>
details of filter implementation, reducing the complexity required of
content filter modules. This is work-in-progress; the
<directive module="mod_filter">FilterProtocol</directive> implements
- some of this functionality, but there are no API calls yet.</p>
+ some of this functionality for back-compatibility with Apache 2.0
+ modules. For httpd 2.1 and later, the
+ <code>ap_register_output_filter_protocol</code> and
+ <code>ap_filter_protocol</code> API enables filter modules to
+ declare their own behaviour.</p>
<p>At the same time, <module>mod_filter</module> should not interfere
with a filter that wants to handle all aspects of the protocol. By
default (i.e. in the absence of any <directive module="mod_filter"
>FilterProtocol</directive> directives), <module>mod_filter</module>
will leave the headers untouched.</p>
+
+ <p>At the time of writing, this feature is largely untested,
+ as modules in common use are designed to work with 2.0.
+ Modules using it should test it carefully.</p>
</section>
+<directivesynopsis>
+<name>AddOutputFilterByType</name>
+<description>assigns an output filter to a particular media-type</description>
+<syntax>AddOutputFilterByType <var>filter</var>[;<var>filter</var>...]
+<var>media-type</var> [<var>media-type</var>] ...</syntax>
+<contextlist><context>server config</context>
+<context>virtual host</context><context>directory</context>
+<context>.htaccess</context></contextlist>
+<override>FileInfo</override>
+<compatibility>Had severe limitations before
+being moved to <module>mod_filter</module> in version 2.3.7</compatibility>
+
+<usage>
+ <p>This directive activates a particular output <a
+ href="../filter.html">filter</a> for a request depending on the
+ response <glossary>media-type</glossary>.</p>
+
+ <p>The following example uses the <code>DEFLATE</code> filter, which
+ is provided by <module>mod_deflate</module>. It will compress all
+ output (either static or dynamic) which is labeled as
+ <code>text/html</code> or <code>text/plain</code> before it is sent
+ to the client.</p>
+
+ <highlight language="config">
+ AddOutputFilterByType DEFLATE text/html text/plain
+ </highlight>
+
+ <p>If you want the content to be processed by more than one filter, their
+ names have to be separated by semicolons. It's also possible to use one
+ <directive>AddOutputFilterByType</directive> directive for each of
+ these filters.</p>
+
+ <p>The configuration below causes all script output labeled as
+ <code>text/html</code> to be processed at first by the
+ <code>INCLUDES</code> filter and then by the <code>DEFLATE</code>
+ filter.</p>
+
+ <highlight language="config">
+<Location "/cgi-bin/">
+ Options Includes
+ AddOutputFilterByType INCLUDES;DEFLATE text/html
+</Location>
+ </highlight>
+
+</usage>
+
+<seealso><directive module="mod_mime">AddOutputFilter</directive></seealso>
+<seealso><directive module="core">SetOutputFilter</directive></seealso>
+<seealso><a href="../filter.html">filters</a></seealso>
+</directivesynopsis>
+
<directivesynopsis>
<name>FilterDeclare</name>
<description>Declare a smart filter</description>
-<syntax>FilterDeclare <var>filter-name</var> [req|resp|env]=<var>dispatch</var>
- <var>[type]</var></syntax>
+<syntax>FilterDeclare <var>smart-filter-name</var> <var>[type]</var></syntax>
<contextlist><context>server config</context><context>virtual host</context>
<context>directory</context><context>.htaccess</context></contextlist>
<override>Options</override>
<usage>
<p>This directive declares an output filter together with a
header or environment variable that will determine runtime
- configuration. The first argument is a <var>filter-name</var>
+ configuration. The first argument is a <var>smart-filter-name</var>
for use in <directive module="mod_filter">FilterProvider</directive>,
<directive module="mod_filter">FilterChain</directive> and
<directive module="mod_filter">FilterProtocol</directive> directives.</p>
- <p>The second is a string with optional <code>req=</code>,
- <code>resp=</code> or <code>env=</code> prefix causing it
- to dispatch on (respectively) the request header, response
- header, or environment variable named. In the absence of a
- prefix, it defaults to a response header. A special case is the
- word <code>handler</code>, which causes <module>mod_filter</module>
- to dispatch on the content handler.</p>
-
<p>The final (optional) argument
is the type of filter, and takes values of <code>ap_filter_type</code>
- namely <code>RESOURCE</code> (the default), <code>CONTENT_SET</code>,
<directivesynopsis>
<name>FilterProvider</name>
<description>Register a content filter</description>
-<syntax>FilterProvider <var>filter-name</var> <var>provider-name</var>
- <var>match</var></syntax>
+<syntax>FilterProvider <var>smart-filter-name</var> <var>provider-name</var>
+ <var>expression</var></syntax>
<contextlist><context>server config</context><context>virtual host</context>
<context>directory</context><context>.htaccess</context></contextlist>
<override>Options</override>
<usage>
<p>This directive registers a <em>provider</em> for the smart filter.
- The provider will be called if and only if the <var>match</var> declared
- here matches the value of the header or environment variable declared
- as <var>dispatch</var> in the <directive module="mod_filter"
- >FilterDeclare</directive> directive that declared
- <var>filter-name</var>.</p>
-
- <p><var>filter-name</var> must have been declared with
- <directive module="mod_filter">FilterDeclare</directive>.
+ The provider will be called if and only if the <var>expression</var>
+ declared evaluates to true when the harness is first called.</p>
+
+ <p>
<var>provider-name</var> must have been registered by loading
a module that registers the name with
- <code>ap_register_output_filter</code>.</p>
-
- <p>The <var>match</var> argument specifies a match that will be applied to
- the filter's <var>dispatch</var> criterion. The <var>match</var> may be
- a string match (exact match or substring), a regexp, an integer (greater,
- lessthan or equals), or unconditional. The first characters of the
- <var>match</var> argument determines this:</p>
-
- <p><strong>First</strong>, if the first character is an exclamation mark
- (<code>!</code>), this reverses the rule, so the provider will be used
- if and only if the match <em>fails</em>.</p>
-
- <p><strong>Second</strong>, it interprets the first character excluding
- any leading <code>!</code> as follows:</p>
-
- <table style="zebra" border="yes">
- <tr><th>Character</th><th>Description</th></tr>
- <tr><td><em>(none)</em></td><td>exact match</td></tr>
- <tr><td><code>$</code></td><td>substring match</td></tr>
- <tr><td><code>/</code></td><td>regexp match</td></tr>
- <tr><td><code>=</code></td><td>integer equality</td></tr>
- <tr><td><code><</code></td><td>integer less-than</td></tr>
- <tr><td><code><=</code></td><td>integer less-than or equal</td></tr>
- <tr><td><code>></code></td><td>integer greater-than</td></tr>
- <tr><td><code>>=</code></td><td>integer greater-than or equal</td></tr>
- <tr><td><code>*</code></td><td>Unconditional match</td></tr>
- </table>
+ <code>ap_register_output_filter</code>.
+ </p>
+
+ <p><var>expression</var> is an
+ <a href="../expr.html">ap_expr</a>.</p>
+
</usage>
+<seealso><a href="../expr.html">Expressions in Apache HTTP Server</a>,
+for a complete reference and examples.</seealso>
+<seealso><module>mod_include</module></seealso>
</directivesynopsis>
<directivesynopsis>
<name>FilterChain</name>
<description>Configure the filter chain</description>
-<syntax>FilterChain [+=-@!]<var>filter-name</var> <var>...</var></syntax>
+<syntax>FilterChain [+=-@!]<var>smart-filter-name</var> <var>...</var></syntax>
<contextlist><context>server config</context><context>virtual host</context>
<context>directory</context><context>.htaccess</context></contextlist>
<override>Options</override>
determines what to do:</p>
<dl>
- <dt><code>+<var>filter-name</var></code></dt>
+ <dt><code>+<var>smart-filter-name</var></code></dt>
<dd>Add <var>filter-name</var> to the end of the filter chain</dd>
- <dt><code>@<var>filter-name</var></code></dt>
- <dd>Insert <var>filter-name</var> at the start of the filter chain</dd>
+ <dt><code>@<var>smart-filter-name</var></code></dt>
+ <dd>Insert <var>smart-filter-name</var> at the start of the filter chain</dd>
- <dt><code>-<var>filter-name</var></code></dt>
- <dd>Remove <var>filter-name</var> from the filter chain</dd>
+ <dt><code>-<var>smart-filter-name</var></code></dt>
+ <dd>Remove <var>smart-filter-name</var> from the filter chain</dd>
- <dt><code>=<var>filter-name</var></code></dt>
- <dd>Empty the filter chain and insert <var>filter-name</var></dd>
+ <dt><code>=<var>smart-filter-name</var></code></dt>
+ <dd>Empty the filter chain and insert <var>smart-filter-name</var></dd>
<dt><code>!</code></dt>
<dd>Empty the filter chain</dd>
- <dt><code><var>filter-name</var></code></dt>
- <dd>Equivalent to <code>+<var>filter-name</var></code></dd>
+ <dt><code><var>smart-filter-name</var></code></dt>
+ <dd>Equivalent to <code>+<var>smart-filter-name</var></code></dd>
</dl>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>FilterProtocol</name>
<description>Deal with correct HTTP protocol handling</description>
-<syntax>FilterProtocol <var>filter-name</var> [<var>provider-name</var>]
+<syntax>FilterProtocol <var>smart-filter-name</var> [<var>provider-name</var>]
<var>proto-flags</var></syntax>
<contextlist><context>server config</context><context>virtual host</context>
<context>directory</context><context>.htaccess</context></contextlist>
filter.</p>
<p>There are two forms of this directive. With three arguments, it
- applies specifically to a <var>filter-name</var> and a
+ applies specifically to a <var>smart-filter-name</var> and a
<var>provider-name</var> for that filter.
- With two arguments it applies to a <var>filter-name</var> whenever the
+ With two arguments it applies to a <var>smart-filter-name</var> whenever the
filter runs <em>any</em> provider.</p>
+ <p>Flags specified with this directive are merged with the flags
+ that underlying providers may have registerd with
+ <module>mod_filter</module>. For example, a filter may internally specify
+ the equivalent of <code>change=yes</code>, but a particular
+ configuration of the module can override with <code>change=no</code>.
+ </p>
+
<p><var>proto-flags</var> is one or more of</p>
<dl>
- <dt><code>change=yes</code></dt>
- <dd>The filter changes the content, including possibly the content
- length</dd>
+ <dt><code>change=yes|no</code></dt>
+ <dd>Specifies whether the filter changes the content, including possibly
+ the content length. The "no" argument is supported in 2.4.7 and later.</dd>
<dt><code>change=1:1</code></dt>
<dd>The filter changes the content, but will not change the content
<name>FilterTrace</name>
<description>Get debug/diagnostic information from
<module>mod_filter</module></description>
-<syntax>FilterTrace <var>filter-name</var> <var>level</var></syntax>
+<syntax>FilterTrace <var>smart-filter-name</var> <var>level</var></syntax>
<contextlist><context>server config</context><context>virtual host</context>
<context>directory</context></contextlist>
</directivesynopsis>
</modulesynopsis>
-
projects / apache / blobdiff