1<?xml version="1.0" encoding="ISO-8859-1"?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> 3<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!-- 4 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 5 This file is generated from xml source: DO NOT EDIT 6 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 7 --> 8<title>mod_filter - Apache HTTP Server</title> 9<link href="/style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" /> 10<link href="/style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" /> 11<link href="/style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link rel="stylesheet" type="text/css" href="/style/css/prettify.css" /> 12<script src="/style/scripts/prettify.min.js" type="text/javascript"> 13</script> 14 15<link href="/images/favicon.ico" rel="shortcut icon" /></head> 16<body> 17<div id="page-header"> 18<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p> 19<p class="apache">Apache HTTP Server Version 2.4</p> 20<img alt="" src="/images/feather.gif" /></div> 21<div class="up"><a href="./"><img title="<-" alt="<-" src="/images/left.gif" /></a></div> 22<div id="path"> 23<a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="../">Version 2.4</a> > <a href="./">Modules</a></div> 24<div id="page-content"> 25<div id="preamble"><h1>Apache Module mod_filter</h1> 26<div class="toplang"> 27<p><span>Available Languages: </span><a href="/en/mod/mod_filter.html" title="English"> en </a> | 28<a href="/fr/mod/mod_filter.html" hreflang="fr" rel="alternate" title="Fran�ais"> fr </a></p> 29</div> 30<table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Context-sensitive smart filter configuration module</td></tr> 31<tr><th><a href="module-dict.html#Status">Status:</a></th><td>Base</td></tr> 32<tr><th><a href="module-dict.html#ModuleIdentifier">Module�Identifier:</a></th><td>filter_module</td></tr> 33<tr><th><a href="module-dict.html#SourceFile">Source�File:</a></th><td>mod_filter.c</td></tr> 34<tr><th><a href="module-dict.html#Compatibility">Compatibility:</a></th><td>Version 2.1 and later</td></tr></table> 35<h3>Summary</h3> 36 37 <p>This module enables smart, context-sensitive configuration of 38 output content filters. For example, apache can be configured to 39 process different content-types through different filters, even 40 when the content-type is not known in advance (e.g. in a proxy).</p> 41 42 <p><code class="module"><a href="/mod/mod_filter.html">mod_filter</a></code> works by introducing indirection into 43 the filter chain. Instead of inserting filters in the chain, we insert 44 a filter harness which in turn dispatches conditionally 45 to a filter provider. Any content filter may be used as a provider 46 to <code class="module"><a href="/mod/mod_filter.html">mod_filter</a></code>; no change to existing filter modules is 47 required (although it may be possible to simplify them).</p> 48</div> 49<div id="quickview"><h3 class="directives">Directives</h3> 50<ul id="toc"> 51<li><img alt="" src="/images/down.gif" /> <a href="#addoutputfilterbytype">AddOutputFilterByType</a></li> 52<li><img alt="" src="/images/down.gif" /> <a href="#filterchain">FilterChain</a></li> 53<li><img alt="" src="/images/down.gif" /> <a href="#filterdeclare">FilterDeclare</a></li> 54<li><img alt="" src="/images/down.gif" /> <a href="#filterprotocol">FilterProtocol</a></li> 55<li><img alt="" src="/images/down.gif" /> <a href="#filterprovider">FilterProvider</a></li> 56<li><img alt="" src="/images/down.gif" /> <a href="#filtertrace">FilterTrace</a></li> 57</ul> 58<h3>Topics</h3> 59<ul id="topics"> 60<li><img alt="" src="/images/down.gif" /> <a href="#smart">Smart Filtering</a></li> 61<li><img alt="" src="/images/down.gif" /> <a href="#terms">Filter Declarations, Providers and Chains</a></li> 62<li><img alt="" src="/images/down.gif" /> <a href="#config">Configuring the Chain</a></li> 63<li><img alt="" src="/images/down.gif" /> <a href="#errordocs">Filtering and Response Status</a></li> 64<li><img alt="" src="/images/down.gif" /> <a href="#upgrade">Upgrading from Apache HTTP Server 2.2 Configuration</a></li> 65<li><img alt="" src="/images/down.gif" /> <a href="#examples">Examples</a></li> 66<li><img alt="" src="/images/down.gif" /> <a href="#protocol">Protocol Handling</a></li> 67</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div> 68<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 69<div class="section"> 70<h2><a name="smart" id="smart">Smart Filtering</a></h2> 71 <p>In the traditional filtering model, filters are inserted unconditionally 72 using <code class="directive"><a href="/mod/mod_mime.html#addoutputfilter">AddOutputFilter</a></code> and family. 73 Each filter then needs to determine whether to run, and there is little 74 flexibility available for server admins to allow the chain to be 75 configured dynamically.</p> 76 77 <p><code class="module"><a href="/mod/mod_filter.html">mod_filter</a></code> by contrast gives server administrators a 78 great deal of flexibility in configuring the filter chain. In fact, 79 filters can be inserted based on complex boolean 80 <a href="/expr.html">expressions</a> This generalises the limited 81 flexibility offered by <code class="directive">AddOutputFilterByType</code>.</p> 82</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 83<div class="section"> 84<h2><a name="terms" id="terms">Filter Declarations, Providers and Chains</a></h2> 85 <p class="figure"> 86 <img src="/images/mod_filter_old.gif" width="160" height="310" alt="[This image displays the traditional filter model]" /><br /> 87 <dfn>Figure 1:</dfn> The traditional filter model</p> 88 89 <p>In the traditional model, output filters are a simple chain 90 from the content generator (handler) to the client. This works well 91 provided the filter chain can be correctly configured, but presents 92 problems when the filters need to be configured dynamically based on 93 the outcome of the handler.</p> 94 95 <p class="figure"> 96 <img src="/images/mod_filter_new.gif" width="423" height="331" alt="[This image shows the mod_filter model]" /><br /> 97 <dfn>Figure 2:</dfn> The <code class="module"><a href="/mod/mod_filter.html">mod_filter</a></code> model</p> 98 99 <p><code class="module"><a href="/mod/mod_filter.html">mod_filter</a></code> works by introducing indirection into 100 the filter chain. Instead of inserting filters in the chain, we insert 101 a filter harness which in turn dispatches conditionally 102 to a filter provider. Any content filter may be used as a provider 103 to <code class="module"><a href="/mod/mod_filter.html">mod_filter</a></code>; no change to existing filter modules 104 is required (although it may be possible to simplify them). There can be 105 multiple providers for one filter, but no more than one provider will 106 run for any single request.</p> 107 108 <p>A filter chain comprises any number of instances of the filter 109 harness, each of which may have any number of providers. A special 110 case is that of a single provider with unconditional dispatch: this 111 is equivalent to inserting the provider filter directly into the chain.</p> 112</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 113<div class="section"> 114<h2><a name="config" id="config">Configuring the Chain</a></h2> 115 <p>There are three stages to configuring a filter chain with 116 <code class="module"><a href="/mod/mod_filter.html">mod_filter</a></code>. For details of the directives, see below.</p> 117 118 <dl> 119 <dt>Declare Filters</dt> 120 <dd>The <code class="directive"><a href="#filterdeclare">FilterDeclare</a></code> directive 121 declares a filter, assigning it a name and filter type. Required 122 only if the filter is not the default type AP_FTYPE_RESOURCE.</dd> 123 124 <dt>Register Providers</dt> 125 <dd>The <code class="directive"><a href="#filterprovider">FilterProvider</a></code> 126 directive registers a provider with a filter. The filter may have 127 been declared with <code class="directive"><a href="#filterdeclare">FilterDeclare</a></code>; if not, FilterProvider will implicitly 128 declare it with the default type AP_FTYPE_RESOURCE. The provider 129 must have been 130 registered with <code>ap_register_output_filter</code> by some module. 131 The final argument to <code class="directive"><a href="#filterprovider">FilterProvider</a></code> is an expression: the provider will be 132 selected to run for a request if and only if the expression evaluates 133 to true. The expression may evaluate HTTP request or response 134 headers, environment variables, or the Handler used by this request. 135 Unlike earlier versions, mod_filter now supports complex expressions 136 involving multiple criteria with AND / OR logic (&& / ||) 137 and brackets. The details of the expression syntax are described in 138 the <a href="/expr.html">ap_expr documentation</a>.</dd> 139 140 <dt>Configure the Chain</dt> 141 <dd>The above directives build components of a smart filter chain, 142 but do not configure it to run. The <code class="directive"><a href="#filterchain">FilterChain</a></code> directive builds a filter chain from smart 143 filters declared, offering the flexibility to insert filters at the 144 beginning or end of the chain, remove a filter, or clear the chain.</dd> 145</dl> 146</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 147<div class="section"> 148<h2><a name="errordocs" id="errordocs">Filtering and Response Status</a></h2> 149 <p>mod_filter normally only runs filters on responses with 150 HTTP status 200 (OK). If you want to filter documents with 151 other response statuses, you can set the <var>filter-errordocs</var> 152 environment variable, and it will work on all responses 153 regardless of status. To refine this further, you can use 154 expression conditions with <code class="directive">FilterProvider</code>.</p> 155</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 156<div class="section"> 157<h2><a name="upgrade" id="upgrade">Upgrading from Apache HTTP Server 2.2 Configuration</a></h2> 158 <p>The <code class="directive"><a href="#filterprovider">FilterProvider</a></code> 159 directive has changed from httpd 2.2: the <var>match</var> and 160 <var>dispatch</var> arguments are replaced with a single but 161 more versatile <var>expression</var>. In general, you can convert 162 a match/dispatch pair to the two sides of an expression, using 163 something like:</p> 164 <div class="example"><p><code>"dispatch = 'match'"</code></p></div> 165 <p>The Request headers, Response headers and Environment variables 166 are now interpreted from syntax <var>%{req:foo}</var>, 167 <var>%{resp:foo}</var> and <var>%{env:foo}</var> respectively. 168 The variables <var>%{HANDLER}</var> and <var>%{CONTENT_TYPE}</var> 169 are also supported.</p> 170 <p>Note that the match no longer support substring matches. They can be 171 replaced by regular expression matches.</p> 172</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 173<div class="section"> 174<h2><a name="examples" id="examples">Examples</a></h2> 175 <dl> 176 <dt>Server side Includes (SSI)</dt> 177 <dd>A simple case of replacing <code class="directive">AddOutputFilterByType</code> 178 <pre class="prettyprint lang-config">FilterDeclare SSI 179FilterProvider SSI INCLUDES "%{CONTENT_TYPE} =~ m|^text/html|" 180FilterChain SSI</pre> 181 182 </dd> 183 184 <dt>Server side Includes (SSI)</dt> 185 <dd>The same as the above but dispatching on handler (classic 186 SSI behaviour; .shtml files get processed). 187 <pre class="prettyprint lang-config">FilterProvider SSI INCLUDES "%{HANDLER} = 'server-parsed'" 188FilterChain SSI</pre> 189 190 </dd> 191 192 <dt>Emulating mod_gzip with mod_deflate</dt> 193 <dd>Insert INFLATE filter only if "gzip" is NOT in the 194 Accept-Encoding header. This filter runs with ftype CONTENT_SET. 195 <pre class="prettyprint lang-config">FilterDeclare gzip CONTENT_SET 196FilterProvider gzip inflate "%{req:Accept-Encoding} !~ /gzip/" 197FilterChain gzip</pre> 198 199 </dd> 200 201 <dt>Image Downsampling</dt> 202 <dd>Suppose we want to downsample all web images, and have filters 203 for GIF, JPEG and PNG. 204 <pre class="prettyprint lang-config">FilterProvider unpack jpeg_unpack "%{CONTENT_TYPE} = 'image/jpeg'" 205FilterProvider unpack gif_unpack "%{CONTENT_TYPE} = 'image/gif'" 206FilterProvider unpack png_unpack "%{CONTENT_TYPE} = 'image/png'" 207 208FilterProvider downsample downsample_filter "%{CONTENT_TYPE} = m|^image/(jpeg|gif|png)|" 209FilterProtocol downsample "change=yes" 210 211FilterProvider repack jpeg_pack "%{CONTENT_TYPE} = 'image/jpeg'" 212FilterProvider repack gif_pack "%{CONTENT_TYPE} = 'image/gif'" 213FilterProvider repack png_pack "%{CONTENT_TYPE} = 'image/png'" 214<Location /image-filter> 215 FilterChain unpack downsample repack 216</Location></pre> 217 218 </dd> 219 </dl> 220</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 221<div class="section"> 222<h2><a name="protocol" id="protocol">Protocol Handling</a></h2> 223 <p>Historically, each filter is responsible for ensuring that whatever 224 changes it makes are correctly represented in the HTTP response headers, 225 and that it does not run when it would make an illegal change. This 226 imposes a burden on filter authors to re-implement some common 227 functionality in every filter:</p> 228 229 <ul> 230 <li>Many filters will change the content, invalidating existing content 231 tags, checksums, hashes, and lengths.</li> 232 233 <li>Filters that require an entire, unbroken response in input need to 234 ensure they don't get byteranges from a backend.</li> 235 236 <li>Filters that transform output in a filter need to ensure they don't 237 violate a <code>Cache-Control: no-transform</code> header from the 238 backend.</li> 239 240 <li>Filters may make responses uncacheable.</li> 241 </ul> 242 243 <p><code class="module"><a href="/mod/mod_filter.html">mod_filter</a></code> aims to offer generic handling of these 244 details of filter implementation, reducing the complexity required of 245 content filter modules. This is work-in-progress; the 246 <code class="directive"><a href="#filterprotocol">FilterProtocol</a></code> implements 247 some of this functionality for back-compatibility with Apache 2.0 248 modules. For httpd 2.1 and later, the 249 <code>ap_register_output_filter_protocol</code> and 250 <code>ap_filter_protocol</code> API enables filter modules to 251 declare their own behaviour.</p> 252 253 <p>At the same time, <code class="module"><a href="/mod/mod_filter.html">mod_filter</a></code> should not interfere 254 with a filter that wants to handle all aspects of the protocol. By 255 default (i.e. in the absence of any <code class="directive"><a href="#filterprotocol">FilterProtocol</a></code> directives), <code class="module"><a href="/mod/mod_filter.html">mod_filter</a></code> 256 will leave the headers untouched.</p> 257 258 <p>At the time of writing, this feature is largely untested, 259 as modules in common use are designed to work with 2.0. 260 Modules using it should test it carefully.</p> 261</div> 262<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 263<div class="directive-section"><h2><a name="AddOutputFilterByType" id="AddOutputFilterByType">AddOutputFilterByType</a> <a name="addoutputfilterbytype" id="addoutputfilterbytype">Directive</a></h2> 264<table class="directive"> 265<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>assigns an output filter to a particular media-type</td></tr> 266<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>AddOutputFilterByType <var>filter</var>[;<var>filter</var>...] 267<var>media-type</var> [<var>media-type</var>] ...</code></td></tr> 268<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> 269<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr> 270<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr> 271<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_filter</td></tr> 272<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Had severe limitations before 273being moved to <code class="module"><a href="/mod/mod_filter.html">mod_filter</a></code> in version 2.3.7</td></tr> 274</table> 275 <p>This directive activates a particular output <a href="/filter.html">filter</a> for a request depending on the 276 response <a class="glossarylink" href="/glossary.html#media-type" title="see glossary">media-type</a>.</p> 277 278 <p>The following example uses the <code>DEFLATE</code> filter, which 279 is provided by <code class="module"><a href="/mod/mod_deflate.html">mod_deflate</a></code>. It will compress all 280 output (either static or dynamic) which is labeled as 281 <code>text/html</code> or <code>text/plain</code> before it is sent 282 to the client.</p> 283 284 <pre class="prettyprint lang-config">AddOutputFilterByType DEFLATE text/html text/plain</pre> 285 286 287 <p>If you want the content to be processed by more than one filter, their 288 names have to be separated by semicolons. It's also possible to use one 289 <code class="directive">AddOutputFilterByType</code> directive for each of 290 these filters.</p> 291 292 <p>The configuration below causes all script output labeled as 293 <code>text/html</code> to be processed at first by the 294 <code>INCLUDES</code> filter and then by the <code>DEFLATE</code> 295 filter.</p> 296 297 <pre class="prettyprint lang-config"><Location /cgi-bin/> 298 Options Includes 299 AddOutputFilterByType INCLUDES;DEFLATE text/html 300</Location></pre> 301 302 303 304<h3>See also</h3> 305<ul> 306<li><code class="directive"><a href="/mod/mod_mime.html#addoutputfilter">AddOutputFilter</a></code></li> 307<li><code class="directive"><a href="/mod/core.html#setoutputfilter">SetOutputFilter</a></code></li> 308<li><a href="/filter.html">filters</a></li> 309</ul> 310</div> 311<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 312<div class="directive-section"><h2><a name="FilterChain" id="FilterChain">FilterChain</a> <a name="filterchain" id="filterchain">Directive</a></h2> 313<table class="directive"> 314<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configure the filter chain</td></tr> 315<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>FilterChain [+=-@!]<var>filter-name</var> <var>...</var></code></td></tr> 316<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> 317<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>Options</td></tr> 318<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr> 319<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_filter</td></tr> 320</table> 321 <p>This configures an actual filter chain, from declared filters. 322 <code class="directive">FilterChain</code> takes any number of arguments, 323 each optionally preceded with a single-character control that 324 determines what to do:</p> 325 326 <dl> 327 <dt><code>+<var>filter-name</var></code></dt> 328 <dd>Add <var>filter-name</var> to the end of the filter chain</dd> 329 330 <dt><code>@<var>filter-name</var></code></dt> 331 <dd>Insert <var>filter-name</var> at the start of the filter chain</dd> 332 333 <dt><code>-<var>filter-name</var></code></dt> 334 <dd>Remove <var>filter-name</var> from the filter chain</dd> 335 336 <dt><code>=<var>filter-name</var></code></dt> 337 <dd>Empty the filter chain and insert <var>filter-name</var></dd> 338 339 <dt><code>!</code></dt> 340 <dd>Empty the filter chain</dd> 341 342 <dt><code><var>filter-name</var></code></dt> 343 <dd>Equivalent to <code>+<var>filter-name</var></code></dd> 344 </dl> 345 346</div> 347<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 348<div class="directive-section"><h2><a name="FilterDeclare" id="FilterDeclare">FilterDeclare</a> <a name="filterdeclare" id="filterdeclare">Directive</a></h2> 349<table class="directive"> 350<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Declare a smart filter</td></tr> 351<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>FilterDeclare <var>filter-name</var> <var>[type]</var></code></td></tr> 352<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> 353<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>Options</td></tr> 354<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr> 355<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_filter</td></tr> 356</table> 357 <p>This directive declares an output filter together with a 358 header or environment variable that will determine runtime 359 configuration. The first argument is a <var>filter-name</var> 360 for use in <code class="directive"><a href="#filterprovider">FilterProvider</a></code>, 361 <code class="directive"><a href="#filterchain">FilterChain</a></code> and 362 <code class="directive"><a href="#filterprotocol">FilterProtocol</a></code> directives.</p> 363 364 <p>The final (optional) argument 365 is the type of filter, and takes values of <code>ap_filter_type</code> 366 - namely <code>RESOURCE</code> (the default), <code>CONTENT_SET</code>, 367 <code>PROTOCOL</code>, <code>TRANSCODE</code>, <code>CONNECTION</code> 368 or <code>NETWORK</code>.</p> 369 370</div> 371<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 372<div class="directive-section"><h2><a name="FilterProtocol" id="FilterProtocol">FilterProtocol</a> <a name="filterprotocol" id="filterprotocol">Directive</a></h2> 373<table class="directive"> 374<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Deal with correct HTTP protocol handling</td></tr> 375<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>FilterProtocol <var>filter-name</var> [<var>provider-name</var>] 376 <var>proto-flags</var></code></td></tr> 377<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> 378<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>Options</td></tr> 379<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr> 380<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_filter</td></tr> 381</table> 382 <p>This directs <code class="module"><a href="/mod/mod_filter.html">mod_filter</a></code> to deal with ensuring the 383 filter doesn't run when it shouldn't, and that the HTTP response 384 headers are correctly set taking into account the effects of the 385 filter.</p> 386 387 <p>There are two forms of this directive. With three arguments, it 388 applies specifically to a <var>filter-name</var> and a 389 <var>provider-name</var> for that filter. 390 With two arguments it applies to a <var>filter-name</var> whenever the 391 filter runs <em>any</em> provider.</p> 392 393 <p>Flags specified with this directive are merged with the flags 394 that underlying providers may have registerd with 395 <code class="module"><a href="/mod/mod_filter.html">mod_filter</a></code>. For example, a filter may internally specify 396 the equivalent of <code>change=yes</code>, but a particular 397 configuration of the module can override with <code>change=no</code>. 398 </p> 399 400 <p><var>proto-flags</var> is one or more of</p> 401 402 <dl> 403 <dt><code>change=yes|no</code></dt> 404 <dd>Specifies whether the filter changes the content, including possibly 405 the content length. The "no" argument is supported in 2.4.7 and later.</dd> 406 407 <dt><code>change=1:1</code></dt> 408 <dd>The filter changes the content, but will not change the content 409 length</dd> 410 411 <dt><code>byteranges=no</code></dt> 412 <dd>The filter cannot work on byteranges and requires complete input</dd> 413 414 <dt><code>proxy=no</code></dt> 415 <dd>The filter should not run in a proxy context</dd> 416 417 <dt><code>proxy=transform</code></dt> 418 <dd>The filter transforms the response in a manner incompatible with 419 the HTTP <code>Cache-Control: no-transform</code> header.</dd> 420 421 <dt><code>cache=no</code></dt> 422 <dd>The filter renders the output uncacheable (eg by introducing randomised 423 content changes)</dd> 424 </dl> 425 426</div> 427<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 428<div class="directive-section"><h2><a name="FilterProvider" id="FilterProvider">FilterProvider</a> <a name="filterprovider" id="filterprovider">Directive</a></h2> 429<table class="directive"> 430<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Register a content filter</td></tr> 431<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>FilterProvider <var>filter-name</var> <var>provider-name</var> 432 <var>expression</var></code></td></tr> 433<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> 434<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>Options</td></tr> 435<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr> 436<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_filter</td></tr> 437</table> 438 <p>This directive registers a <em>provider</em> for the smart filter. 439 The provider will be called if and only if the <var>expression</var> 440 declared evaluates to true when the harness is first called.</p> 441 442 <p> 443 <var>provider-name</var> must have been registered by loading 444 a module that registers the name with 445 <code>ap_register_output_filter</code>. 446 </p> 447 448 <p><var>expression</var> is an 449 <a href="/expr.html">ap_expr</a>.</p> 450 451 452<h3>See also</h3> 453<ul> 454<li><a href="/expr.html">Expressions in Apache HTTP Server</a>, 455for a complete reference and examples.</li> 456<li><code class="module"><a href="/mod/mod_include.html">mod_include</a></code></li> 457</ul> 458</div> 459<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 460<div class="directive-section"><h2><a name="FilterTrace" id="FilterTrace">FilterTrace</a> <a name="filtertrace" id="filtertrace">Directive</a></h2> 461<table class="directive"> 462<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Get debug/diagnostic information from 463 <code class="module"><a href="/mod/mod_filter.html">mod_filter</a></code></td></tr> 464<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>FilterTrace <var>filter-name</var> <var>level</var></code></td></tr> 465<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr> 466<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr> 467<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_filter</td></tr> 468</table> 469 <p>This directive generates debug information from 470 <code class="module"><a href="/mod/mod_filter.html">mod_filter</a></code>. 471 It is designed to help test and debug providers (filter modules), although 472 it may also help with <code class="module"><a href="/mod/mod_filter.html">mod_filter</a></code> itself.</p> 473 474 <p>The debug output depends on the <var>level</var> set:</p> 475 <dl> 476 <dt><code>0</code> (default)</dt> 477 <dd>No debug information is generated.</dd> 478 479 <dt><code>1</code></dt> 480 <dd><code class="module"><a href="/mod/mod_filter.html">mod_filter</a></code> will record buckets and brigades 481 passing through the filter to the error log, before the provider has 482 processed them. This is similar to the information generated by 483 <a href="http://apache.webthing.com/mod_diagnostics/">mod_diagnostics</a>. 484 </dd> 485 486 <dt><code>2</code> (not yet implemented)</dt> 487 <dd>Will dump the full data passing through to a tempfile before the 488 provider. <strong>For single-user debug only</strong>; this will not 489 support concurrent hits.</dd> 490 </dl> 491 492</div> 493</div> 494<div class="bottomlang"> 495<p><span>Available Languages: </span><a href="/en/mod/mod_filter.html" title="English"> en </a> | 496<a href="/fr/mod/mod_filter.html" hreflang="fr" rel="alternate" title="Fran�ais"> fr </a></p> 497</div><div class="top"><a href="#page-header"><img src="/images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>Notice:</strong><br />This is not a Q&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our <a href="http://httpd.apache.org/lists.html">mailing lists</a>.</div> 498<script type="text/javascript"><!--//--><![CDATA[//><!-- 499var comments_shortname = 'httpd'; 500var comments_identifier = 'http://httpd.apache.org/docs/2.4/mod/mod_filter.html'; 501(function(w, d) { 502 if (w.location.hostname.toLowerCase() == "httpd.apache.org") { 503 d.write('<div id="comments_thread"><\/div>'); 504 var s = d.createElement('script'); 505 s.type = 'text/javascript'; 506 s.async = true; 507 s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier; 508 (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s); 509 } 510 else { 511 d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>'); 512 } 513})(window, document); 514//--><!]]></script></div><div id="footer"> 515<p class="apache">Copyright 2014 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p> 516<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!-- 517if (typeof(prettyPrint) !== 'undefined') { 518 prettyPrint(); 519} 520//--><!]]></script> 521</body></html>
