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

   1 <?xml version="1.0" encoding="UTF-8" ?>
   2 <!DOCTYPE manualpage SYSTEM "./style/manualpage.dtd">
   3 <?xml-stylesheet type="text/xsl" href="./style/manual.en.xsl"?>
   4 <!-- $LastChangedRevision$ -->
   5
   6 <!--
   7  Licensed to the Apache Software Foundation (ASF) under one or more
   8  contributor license agreements.  See the NOTICE file distributed with
   9  this work for additional information regarding copyright ownership.
  10  The ASF licenses this file to You under the Apache License, Version 2.0
  11  (the "License"); you may not use this file except in compliance with
  12  the License.  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 <manualpage metafile="filter.xml.meta">
  24
  25   <title>Filters</title>
  26
  27   <summary>
  28     <p>This document describes the use of filters in Apache.</p>
  29   </summary>
  30
  31   <section id="intro">
  32     <title>Filtering in Apache 2</title>
  33     <related>
  34       <modulelist>
  35         <module>mod_filter</module>
  36         <module>mod_deflate</module>
  37         <module>mod_ext_filter</module>
  38         <module>mod_include</module>
  39         <module>mod_charset_lite</module>
  40         <module>mod_reflector</module>
  41         <module>mod_buffer</module>
  42         <module>mod_data</module>
  43         <module>mod_ratelimit</module>
  44         <module>mod_reqtimeout</module>
  45         <module>mod_request</module>
  46         <module>mod_sed</module>
  47         <module>mod_substitute</module>
  48         <module>mod_xml2enc</module>
  49         <module>mod_proxy_html</module>
  50         <module>mod_policy</module>
  51       </modulelist>
  52       <directivelist>
  53         <directive module="mod_filter">FilterChain</directive>
  54         <directive module="mod_filter">FilterDeclare</directive>
  55         <directive module="mod_filter">FilterProtocol</directive>
  56         <directive module="mod_filter">FilterProvider</directive>
  57         <directive module="mod_mime">AddInputFilter</directive>
  58         <directive module="mod_mime">AddOutputFilter</directive>
  59         <directive module="mod_mime">RemoveInputFilter</directive>
  60         <directive module="mod_mime">RemoveOutputFilter</directive>
  61         <directive module="mod_reflector">ReflectorHeader</directive>
  62         <directive module="mod_ext_filter">ExtFilterDefine</directive>
  63         <directive module="mod_ext_filter">ExtFilterOptions</directive>
  64         <directive module="core">SetInputFilter</directive>
  65         <directive module="core">SetOutputFilter</directive>
  66       </directivelist>
  67     </related>
  68
  69 <p>The Filter Chain is available in Apache 2.0 and higher,
  70 and enables applications to process incoming and outgoing data
  71 in a highly flexible and configurable manner, regardless of
  72 where the data comes from.  We can pre-process incoming data,
  73 and post-process outgoing data, at will.  This is basically
  74 independent of the traditional request processing phases.</p>
  75 <p class="figure">
  76 <img src="images/filter_arch.png" width="569" height="392" alt=
  77 "Filters can be chained, in a Data Axis orthogonal to request processing"
  78 />
  79 </p>
  80 <p>Some examples of filtering in the standard Apache distribution are:</p>
  81 <ul>
  82 <li><module>mod_include</module>, implements server-side includes.</li>
  83 <li><module>mod_ssl</module>, implements SSL encryption (https).</li>
  84 <li><module>mod_deflate</module>, implements compression/decompression on the fly.</li>
  85 <li><module>mod_charset_lite</module>, transcodes between different character sets.</li>
  86 <li><module>mod_ext_filter</module>, runs an external program as a filter.</li>
  87 </ul>
  88 <p>Apache also uses a number of filters internally to perform
  89 functions like chunking and byte-range handling.</p>
  90
  91 <p>A wider range of applications are implemented by third-party filter
  92 modules available from <a
  93 href="http://modules.apache.org/">modules.apache.org</a> and
  94 elsewhere.  A few of these are:</p>
  95
  96 <ul>
  97 <li>HTML and XML processing and rewriting</li>
  98 <li>XSLT transforms and XIncludes</li>
  99 <li>XML Namespace support</li>
 100 <li>File Upload handling and decoding of HTML Forms</li>
 101 <li>Image processing</li>
 102 <li>Protection of vulnerable applications such as PHP scripts</li>
 103 <li>Text search-and-replace editing</li>
 104 </ul>
 105 </section>
 106
 107 <section id="smart">
 108 <title>Smart Filtering</title>
 109 <p class="figure">
 110 <img src="images/mod_filter_new.png" width="423" height="331"
 111 alt="Smart filtering applies different filter providers according to the state of request processing"/>
 112 </p>
 113 <p><module>mod_filter</module>, included in Apache 2.1 and later,
 114 enables the filter chain to be configured dynamically at run time.
 115 So for example you can set up a proxy to rewrite
 116 HTML with an HTML filter and JPEG images with a completely
 117 separate filter, despite the proxy having no prior information
 118 about what the origin server will send.  This works by using a
 119 filter harness, that dispatches to different providers according
 120 to the actual contents at runtime.  Any filter may be either
 121 inserted directly in the chain and run unconditionally, or
 122 used as a provider and inserted dynamically.  For example,</p>
 123 <ul>
 124 <li>an HTML processing filter will only run if the content is
 125 text/html or application/xhtml+xml</li>
 126 <li>A compression filter will only run if the input is a
 127 compressible type and not already compressed</li>
 128 <li>A charset conversion filter will be inserted if a text
 129 document is not already in the desired charset</li>
 130 </ul>
 131 </section>
 132
 133 <section id="service">
 134
 135 <title>Exposing Filters as an HTTP Service</title>
 136 <p>Filters can be used to process content originating from the client in
 137 addition to processing content originating on the server using the
 138 <module>mod_reflector</module> module.</p>
 139
 140 <p><module>mod_reflector</module> accepts POST requests from clients, and reflects
 141 the content request body received within the POST request back in the response,
 142 passing through the output filter stack on the way back to the client.</p>
 143
 144 <p>This technique can be used as an alternative to a web service running within
 145 an application server stack, where an output filter provides the transformation
 146 required on the request body. For example, the <module>mod_deflate</module>
 147 module might be used to provide a general compression service, or an image
 148 transformation filter might be turned into an image transformation service.</p>
 149
 150 </section>
 151
 152 <section id="using">
 153 <title>Using Filters</title>
 154 <p>There are two ways to use filtering: Simple and Dynamic.
 155 In general, you should use one or the other; mixing them can
 156 have unexpected consequences (although simple Input filtering
 157 can be mixed freely with either simple or dynamic Output filtering).</p>
 158 <p>The Simple Way is the only way to configure input filters, and is
 159 sufficient for output filters where you need a static filter chain.
 160 Relevant directives are
 161     <directive module="core">SetInputFilter</directive>,
 162     <directive module="core">SetOutputFilter</directive>,
 163     <directive module="mod_mime">AddInputFilter</directive>,
 164     <directive module="mod_mime">AddOutputFilter</directive>,
 165     <directive module="mod_mime">RemoveInputFilter</directive>, and
 166     <directive module="mod_mime">RemoveOutputFilter</directive>.</p>
 167
 168 <p>The Dynamic Way enables both static and flexible, dynamic configuration
 169 of output filters, as discussed in the <module>mod_filter</module> page.
 170 Relevant directives are
 171     <directive module="mod_filter">FilterChain</directive>,
 172     <directive module="mod_filter">FilterDeclare</directive>, and
 173     <directive module="mod_filter">FilterProvider</directive>.</p>
 174
 175 <p>One further directive <directive
 176 module="mod_filter">AddOutputFilterByType</directive> is still supported,
 177 but deprecated.  Use dynamic configuration instead.</p>
 178
 179   </section>
 180 </manualpage>