diff options
| -rw-r--r-- | docs/manual/filter.html.en | 131 | ||||
| -rw-r--r-- | docs/manual/filter.xml | 115 | ||||
| -rw-r--r-- | docs/manual/images/filter_arch.png | bin | 0 -> 2553 bytes | |||
| -rw-r--r-- | docs/manual/images/mod_filter_new.png | bin | 0 -> 1130 bytes |
4 files changed, 178 insertions, 68 deletions
diff --git a/docs/manual/filter.html.en b/docs/manual/filter.html.en index afb56efbe0..b7459163ae 100644 --- a/docs/manual/filter.html.en +++ b/docs/manual/filter.html.en @@ -1,20 +1,20 @@ <?xml version="1.0" encoding="ISO-8859-1"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> -<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!-- +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /><!-- XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX This file is generated from xml source: DO NOT EDIT XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX --> <title>Filters - Apache HTTP Server</title> -<link href="./style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" /> -<link href="./style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" /> -<link href="./style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /> -<link href="./images/favicon.ico" rel="shortcut icon" /></head> -<body id="manual-page" class="no-sidebar"><div id="page-header"> +<link title="Main stylesheet" type="text/css" media="all" rel="stylesheet" href="./style/css/manual.css" /> +<link title="No Sidebar - Default font size" type="text/css" media="all" rel="alternate stylesheet" href="./style/css/manual-loose-100pc.css" /> +<link type="text/css" media="print" rel="stylesheet" href="./style/css/manual-print.css" /> +<link rel="shortcut icon" href="./images/favicon.ico" /></head> +<body id="manual-page"><div id="page-header"> <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> <p class="apache">Apache HTTP Server Version 2.3</p> -<img alt="" src="./images/feather.gif" /></div> -<div class="up"><a href="./"><img title="<-" alt="<-" src="./images/left.gif" /></a></div> +<img src="./images/feather.gif" alt="" /></div> +<div class="up"><a href="./"><img src="./images/left.gif" alt="<-" title="<-" /></a></div> <div id="path"> <a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs-project/">Documentation</a> > <a href="./">Version 2.3</a></div><div id="page-content"><div id="preamble"><h1>Filters</h1> <div class="toplang"> @@ -27,46 +27,99 @@ <p>This document describes the use of filters in Apache.</p> </div> -<div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div> +<div id="quickview"><ul id="toc"><li><img src="./images/down.gif" alt="" /> <a href="#intro">Filtering in Apache 2</a></li> +<li><img src="./images/down.gif" alt="" /> <a href="#smart">Smart Filtering</a></li> +<li><img src="./images/down.gif" alt="" /> <a href="#using">Using Filters</a></li> +</ul></div> +<div class="top"><a href="#page-header"><img src="./images/up.gif" alt="top" /></a></div> <div class="section"> -<h2><a name="filters" id="filters">Filters</a></h2> +<h2><a id="intro" name="intro">Filtering in Apache 2</a></h2> - <table class="related"><tr><th>Related Modules</th><th>Related Directives</th></tr><tr><td><ul><li><code class="module"><a href="./mod/mod_deflate.html">mod_deflate</a></code></li><li><code class="module"><a href="./mod/mod_ext_filter.html">mod_ext_filter</a></code></li><li><code class="module"><a href="./mod/mod_include.html">mod_include</a></code></li></ul></td><td><ul><li><code class="directive"><a href="./mod/mod_mime.html#addinputfilter">AddInputFilter</a></code></li><li><code class="directive"><a href="./mod/mod_mime.html#addoutputfilter">AddOutputFilter</a></code></li><li><code class="directive"><a href="./mod/mod_mime.html#removeinputfilter">RemoveInputFilter</a></code></li><li><code class="directive"><a href="./mod/mod_mime.html#removeoutputfilter">RemoveOutputFilter</a></code></li><li><code class="directive"><a href="./mod/mod_ext_filter.html#extfilterdefine">ExtFilterDefine</a></code></li><li><code class="directive"><a href="./mod/mod_ext_filter.html#extfilteroptions">ExtFilterOptions</a></code></li><li><code class="directive"><a href="./mod/core.html#setinputfilter">SetInputFilter</a></code></li><li><code class="directive"><a href="./mod/core.html#setoutputfilter">SetOutputFilter</a></code></li></ul></td></tr></table> + <table class="related"><tr><th>Related Modules</th><th>Related Directives</th></tr><tr><td><ul><li><code class="module"><a href="./mod/mod_filter.html">mod_filter</a></code></li><li><code class="module"><a href="./mod/mod_deflate.html">mod_deflate</a></code></li><li><code class="module"><a href="./mod/mod_ext_filter.html">mod_ext_filter</a></code></li><li><code class="module"><a href="./mod/mod_include.html">mod_include</a></code></li><li><code class="module"><a href="./mod/mod_charset_lite.html">mod_charset_lite</a></code></li></ul></td><td><ul><li><code class="directive"><a href="./mod/mod_filter.html#filterchain">FilterChain</a></code></li><li><code class="directive"><a href="./mod/mod_filter.html#filterdeclare">FilterDeclare</a></code></li><li><code class="directive"><a href="./mod/mod_filter.html#filterprotocol">FilterProtocol</a></code></li><li><code class="directive"><a href="./mod/mod_filter.html#filterprovider">FilterProvider</a></code></li><li><code class="directive"><a href="./mod/mod_mime.html#addinputfilter">AddInputFilter</a></code></li><li><code class="directive"><a href="./mod/mod_mime.html#addoutputfilter">AddOutputFilter</a></code></li><li><code class="directive"><a href="./mod/mod_mime.html#removeinputfilter">RemoveInputFilter</a></code></li><li><code class="directive"><a href="./mod/mod_mime.html#removeoutputfilter">RemoveOutputFilter</a></code></li><li><code class="directive"><a href="./mod/mod_ext_filter.html#extfilterdefine">ExtFilterDefine</a></code></li><li><code class="directive"><a href="./mod/mod_ext_filter.html#extfilteroptions">ExtFilterOptions</a></code></li><li><code class="directive"><a href="./mod/core.html#setinputfilter">SetInputFilter</a></code></li><li><code class="directive"><a href="./mod/core.html#setoutputfilter">SetOutputFilter</a></code></li></ul></td></tr></table> - <p>A <em>filter</em> is a process that is applied to data that - is sent or received by the server. Data sent by clients to the - server is processed by <em>input filters</em> while data sent - by the server to the client is processed by <em>output - filters</em>. Multiple filters can be applied to the data, and - the order of the filters can be explicitly specified.</p> +<p>The Filter Chain is available in Apache 2.0 and higher, +and enables applications to process incoming and outgoing data +in a highly flexible and configurable manner, regardless of +where the data comes from. We can pre-process incoming data, +and post-process outgoing data, at will. This is basically +independent of the traditional request processing phases.</p> +<p class="figure"> +<img src="images/filter_arch.png" width="569" height="392" alt="Filters can be chained, in a Data Axis orthogonal to request processing" /> +</p> +<p>Some examples of filtering in the standard Apache distribution are:</p> +<ul> +<li>mod_includes, implements server-side includes.</li> +<li>mod_ssl, implements SSL encryption (https).</li> +<li>mod_deflate, implements compression/decompression on the fly.</li> +<li>mod_charset_lite, transcodes between different character sets.</li> +<li>mod_ext_filter, runs an external program as a filter.</li> +</ul> +<p>Apache also uses a number of filters internally, to perform +functions like chunking and byte-range handling.</p> - <p>Filters are used internally by Apache to perform functions such - as chunking and byte-range request handling. In addition, modules - can provide filters that are selectable using run-time - configuration directives. The set of filters that apply to data - can be manipulated with the +<p>A wider range of applications are implemented by third-party +filter modules. A few of these are:</p> +<ul> +<li>HTML and XML processing and rewriting</li> +<li>XSLT transforms and XIncludes</li> +<li>XML Namespace support</li> +<li>File Upload handling and decoding of HTML Forms</li> +<li>Image processing</li> +<li>Protection of vulnerable applications such as PHP scripts</li> +<li>Text search-and-replace editing</li> +</ul> +</div><div class="top"><a href="#page-header"><img src="./images/up.gif" alt="top" /></a></div> +<div class="section"> +<h2><a id="smart" name="smart">Smart Filtering</a></h2> + +<p class="figure"> +<img src="images/mod_filter_new.png" width="423" height="331" alt="Smart filtering applies different filter providers according to the state of request processing" /> +</p> +<p><code class="module"><a href="./mod/mod_filter.html">mod_filter</a></code>, included in Apache 2.1 and up, +enables the filter chain to be configured dynamically at run time. +So for example you can set up a proxy to rewrite +HTML with an HTML filter and JPEG images with a completely +separate filter, despite the proxy having no prior information +about what the origin server will send. This works by using a +filter harness, that dispatches to different providers according +to the actual contents at runtime. Any filter may be either +inserted directly in the chain and run unconditionally, or +used as a provider and inserted dynamically. For example,</p> +<ul> +<li>an HTML processing filter will only run if the content is +text/html or application/xhtml+xml</li> +<li>A compression filter will only run if the input is a +compressable type and not already compressed</li> +<li>A charset conversion filter will be inserted if a text +document is not already in the desired charset</li> +</ul> +</div><div class="top"><a href="#page-header"><img src="./images/up.gif" alt="top" /></a></div> +<div class="section"> +<h2><a id="using" name="using">Using Filters</a></h2> + +<p>There are two ways to use filtering: Simple and Dynamic. +In general, you should use one or the other: mixing them can +have unexpected consequences (although simple Input filtering +can be mixed freely with either simple or dynamic Output filtering!</p> +<p>The Simple Way is the only way to configure input filters, and is +suficient for output filters where you need a static filter chain. +Relevant directives are <code class="directive"><a href="./mod/core.html#setinputfilter">SetInputFilter</a></code>, <code class="directive"><a href="./mod/core.html#setoutputfilter">SetOutputFilter</a></code>, <code class="directive"><a href="./mod/mod_mime.html#addinputfilter">AddInputFilter</a></code>, <code class="directive"><a href="./mod/mod_mime.html#addoutputfilter">AddOutputFilter</a></code>, <code class="directive"><a href="./mod/mod_mime.html#removeinputfilter">RemoveInputFilter</a></code>, and - <code class="directive"><a href="./mod/mod_mime.html#removeoutputfilter">RemoveOutputFilter</a></code> - directives.</p> - - <p>The following user-selectable filters are currently provided - with the Apache HTTP Server distribution.</p> - - <dl> - <dt>INCLUDES</dt> - <dd>Server-Side Includes processing by <code class="module"><a href="./mod/mod_include.html">mod_include</a></code></dd> - <dt>DEFLATE</dt> - <dd>Compress output before sending it to the client using - <code class="module"><a href="./mod/mod_deflate.html">mod_deflate</a></code> - </dd> - </dl> + <code class="directive"><a href="./mod/mod_mime.html#removeoutputfilter">RemoveOutputFilter</a></code>.</p> - <p>In addition, the module <code class="module"><a href="./mod/mod_ext_filter.html">mod_ext_filter</a></code> allows - for external programs to be defined as filters.</p> +<p>The Dynamic Way enables both static and flexible, dynamic configuration +of output filters, as discussed in the <code class="module"><a href="./mod/mod_filter.html">mod_filter</a></code> page. +Relevant directives are + <code class="directive"><a href="./mod/mod_filter.html#filterchain">FilterChain</a></code>, + <code class="directive"><a href="./mod/mod_filter.html#filterdeclare">FilterDeclare</a></code>, + <code class="directive"><a href="./mod/mod_filter.html#filterprovider">FilterProvider</a></code>.</p> +<p>One further directive AddOutputFilterByType is still supported, +but may be problematic and is now deprecated. Use dynamic configuration +instead.</p> </div></div> <div class="bottomlang"> <p><span>Available Languages: </span><a href="./en/filter.html" title="English"> en </a> | @@ -77,4 +130,4 @@ </div><div id="footer"> <p class="apache">Copyright 1995-2005 The Apache Software Foundation or its licensors, as applicable.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p> <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> -</body></html>
\ No newline at end of file +</body></html> diff --git a/docs/manual/filter.xml b/docs/manual/filter.xml index e5de3c0bfb..2d58be5120 100644 --- a/docs/manual/filter.xml +++ b/docs/manual/filter.xml @@ -28,15 +28,21 @@ <p>This document describes the use of filters in Apache.</p> </summary> - <section id="filters"> - <title>Filters</title> + <section id="intro"> + <title>Filtering in Apache 2</title> <related> <modulelist> + <module>mod_filter</module> <module>mod_deflate</module> <module>mod_ext_filter</module> <module>mod_include</module> + <module>mod_charset_lite</module> </modulelist> <directivelist> + <directive module="mod_filter">FilterChain</directive> + <directive module="mod_filter">FilterDeclare</directive> + <directive module="mod_filter">FilterProtocol</directive> + <directive module="mod_filter">FilterProvider</directive> <directive module="mod_mime">AddInputFilter</directive> <directive module="mod_mime">AddOutputFilter</directive> <directive module="mod_mime">RemoveInputFilter</directive> @@ -48,39 +54,90 @@ </directivelist> </related> - <p>A <em>filter</em> is a process that is applied to data that - is sent or received by the server. Data sent by clients to the - server is processed by <em>input filters</em> while data sent - by the server to the client is processed by <em>output - filters</em>. Multiple filters can be applied to the data, and - the order of the filters can be explicitly specified.</p> +<p>The Filter Chain is available in Apache 2.0 and higher, +and enables applications to process incoming and outgoing data +in a highly flexible and configurable manner, regardless of +where the data comes from. We can pre-process incoming data, +and post-process outgoing data, at will. This is basically +independent of the traditional request processing phases.</p> +<p class="figure"> +<img src="images/filter_arch.png" width="569" height="392" alt= +"Filters can be chained, in a Data Axis orthogonal to request processing" +/> +</p> +<p>Some examples of filtering in the standard Apache distribution are:</p> +<ul> +<li>mod_includes, implements server-side includes.</li> +<li>mod_ssl, implements SSL encryption (https).</li> +<li>mod_deflate, implements compression/decompression on the fly.</li> +<li>mod_charset_lite, transcodes between different character sets.</li> +<li>mod_ext_filter, runs an external program as a filter.</li> +</ul> +<p>Apache also uses a number of filters internally, to perform +functions like chunking and byte-range handling.</p> - <p>Filters are used internally by Apache to perform functions such - as chunking and byte-range request handling. In addition, modules - can provide filters that are selectable using run-time - configuration directives. The set of filters that apply to data - can be manipulated with the +<p>A wider range of applications are implemented by third-party +filter modules. A few of these are:</p> +<ul> +<li>HTML and XML processing and rewriting</li> +<li>XSLT transforms and XIncludes</li> +<li>XML Namespace support</li> +<li>File Upload handling and decoding of HTML Forms</li> +<li>Image processing</li> +<li>Protection of vulnerable applications such as PHP scripts</li> +<li>Text search-and-replace editing</li> +</ul> +</section> +<section id="smart"> +<title>Smart Filtering</title> +<p class="figure"> +<img src="images/mod_filter_new.png" width="423" height="331" +alt="Smart filtering applies different filter providers according to the state of request processing"/> +</p> +<p><module>mod_filter</module>, included in Apache 2.1 and up, +enables the filter chain to be configured dynamically at run time. +So for example you can set up a proxy to rewrite +HTML with an HTML filter and JPEG images with a completely +separate filter, despite the proxy having no prior information +about what the origin server will send. This works by using a +filter harness, that dispatches to different providers according +to the actual contents at runtime. Any filter may be either +inserted directly in the chain and run unconditionally, or +used as a provider and inserted dynamically. For example,</p> +<ul> +<li>an HTML processing filter will only run if the content is +text/html or application/xhtml+xml</li> +<li>A compression filter will only run if the input is a +compressable type and not already compressed</li> +<li>A charset conversion filter will be inserted if a text +document is not already in the desired charset</li> +</ul> +</section> + +<section id="using"> +<title>Using Filters</title> +<p>There are two ways to use filtering: Simple and Dynamic. +In general, you should use one or the other: mixing them can +have unexpected consequences (although simple Input filtering +can be mixed freely with either simple or dynamic Output filtering!</p> +<p>The Simple Way is the only way to configure input filters, and is +suficient for output filters where you need a static filter chain. +Relevant directives are <directive module="core">SetInputFilter</directive>, <directive module="core">SetOutputFilter</directive>, <directive module="mod_mime">AddInputFilter</directive>, <directive module="mod_mime">AddOutputFilter</directive>, <directive module="mod_mime">RemoveInputFilter</directive>, and - <directive module="mod_mime">RemoveOutputFilter</directive> - directives.</p> - - <p>The following user-selectable filters are currently provided - with the Apache HTTP Server distribution.</p> - - <dl> - <dt>INCLUDES</dt> - <dd>Server-Side Includes processing by <module>mod_include</module></dd> - <dt>DEFLATE</dt> - <dd>Compress output before sending it to the client using - <module>mod_deflate</module> - </dd> - </dl> + <directive module="mod_mime">RemoveOutputFilter</directive>.</p> - <p>In addition, the module <module>mod_ext_filter</module> allows - for external programs to be defined as filters.</p> +<p>The Dynamic Way enables both static and flexible, dynamic configuration +of output filters, as discussed in the <module>mod_filter</module> page. +Relevant directives are + <directive module="mod_filter">FilterChain</directive>, + <directive module="mod_filter">FilterDeclare</directive>, + <directive module="mod_filter">FilterProvider</directive>.</p> +<p>One further directive AddOutputFilterByType is still supported, +but may be problematic and is now deprecated. Use dynamic configuration +instead.</p> </section> </manualpage> diff --git a/docs/manual/images/filter_arch.png b/docs/manual/images/filter_arch.png Binary files differnew file mode 100644 index 0000000000..de021af5b5 --- /dev/null +++ b/docs/manual/images/filter_arch.png diff --git a/docs/manual/images/mod_filter_new.png b/docs/manual/images/mod_filter_new.png Binary files differnew file mode 100644 index 0000000000..ad2cc73599 --- /dev/null +++ b/docs/manual/images/mod_filter_new.png |
