X-Git-Url: https://granicus.if.org/sourcecode?a=blobdiff_plain;f=docs%2Fmanual%2Fmod%2Fmod_filter.xml;h=5f43b42c10b197c12e762737247e1c1bfd83287a;hb=4a408697dcb8efd6a02f1b619418295fc1d7ba59;hp=2ccef8f590460432c9228f370417e7b0e18b9a6f;hpb=ad6c7a547a94358e412fbdf9628b09fdce72f51c;p=apache

diff --git a/docs/manual/mod/mod_filter.xml b/docs/manual/mod/mod_filter.xml
index 2ccef8f590..5f43b42c10 100644
--- a/docs/manual/mod/mod_filter.xml
+++ b/docs/manual/mod/mod_filter.xml
@@ -1,14 +1,15 @@
 <?xml version="1.0"?>
 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
-<!-- $Revision: 1.7 $ -->
+<!-- $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
 
@@ -23,10 +24,9 @@
 
 <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
@@ -51,13 +51,9 @@
 
     <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>
@@ -99,18 +95,24 @@
     <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 (&amp;&amp; / ||)
+    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,
@@ -120,62 +122,88 @@
     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/>
-      &lt;Location /image-filter&gt;<br/>
-      <indent>
-        FilterChain unpack downsample repack<br/>
-      </indent>
-      &lt;/Location&gt;
-    </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'"
+&lt;Location "/image-filter"&gt;
+    FilterChain unpack downsample repack
+&lt;/Location&gt;
+    </highlight>
     </dd>
     </dl>
 </section>
@@ -205,20 +233,78 @@
     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">
+&lt;Location "/cgi-bin/"&gt;
+    Options Includes
+    AddOutputFilterByType INCLUDES;DEFLATE text/html
+&lt;/Location&gt;
+    </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>
@@ -226,19 +312,11 @@
 <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>,
@@ -250,56 +328,36 @@
 <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>&lt;</code></td><td>integer less-than</td></tr>
-    <tr><td><code>&gt;</code></td><td>integer greater-than</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>
@@ -311,23 +369,23 @@
     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>
@@ -335,7 +393,7 @@
 <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>
@@ -348,17 +406,24 @@
     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
@@ -385,7 +450,7 @@
 <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>
 
@@ -416,4 +481,3 @@
 </directivesynopsis>
 
 </modulesynopsis>
-