~ubuntu-branches/ubuntu/feisty/apache2/feisty

<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.2</p>

<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.2</a> > <a href="./">Modules</a></div>

<div id="preamble"><h1>Apache Module mod_filter</h1>

<p><span>Available Languages: </span><a href="../en/mod/mod_filter.html" title="English"> en </a></p>

</div>

<table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Context-sensitive smart filter configuration module</td></tr>

<tr><th><a href="module-dict.html#Status">Status:</a></th><td>Base</td></tr>

<tr><th><a href="module-dict.html#ModuleIdentifier">Module�Identifier:</a></th><td>filter_module</td></tr>

<tr><th><a href="module-dict.html#SourceFile">Source�File:</a></th><td>mod_filter.c</td></tr>

<tr><th><a href="module-dict.html#Compatibility">Compatibility:</a></th><td>Version 2.1 and later</td></tr></table>

<h3>Summary</h3>

<p>This module enables smart, context-sensitive configuration of

output content filters. For example, apache can be configured to

process different content-types through different filters, even

when the content-type is not known in advance (e.g. in a proxy).</p>

<p><code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code> works by introducing indirection into

the filter chain. Instead of inserting filters in the chain, we insert

a filter harness which in turn dispatches conditionally

to a filter provider. Any content filter may be used as a provider

to <code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code>; no change to existing filter modules is

required (although it may be possible to simplify them).</p>

</div>

<div id="quickview"><h3 class="directives">Directives</h3>

<li><img alt="" src="../images/down.gif" /> <a href="#filterchain">FilterChain</a></li>

<li><img alt="" src="../images/down.gif" /> <a href="#filterdeclare">FilterDeclare</a></li>

<li><img alt="" src="../images/down.gif" /> <a href="#filterprotocol">FilterProtocol</a></li>

<li><img alt="" src="../images/down.gif" /> <a href="#filterprovider">FilterProvider</a></li>

<li><img alt="" src="../images/down.gif" /> <a href="#filtertrace">FilterTrace</a></li>

</ul>

<h3>Topics</h3>

<li><img alt="" src="../images/down.gif" /> <a href="#smart">Smart Filtering</a></li>

<li><img alt="" src="../images/down.gif" /> <a href="#terms">Filter Declarations, Providers and Chains</a></li>

<li><img alt="" src="../images/down.gif" /> <a href="#config">Configuring the Chain</a></li>

<li><img alt="" src="../images/down.gif" /> <a href="#examples">Examples</a></li>

<li><img alt="" src="../images/down.gif" /> <a href="#protocol">Protocol Handling</a></li>

</ul></div>

<h2><a name="smart" id="smart">Smart Filtering</a></h2>

<p>In the traditional filtering model, filters are inserted unconditionally

using <code class="directive"><a href="../mod/mod_mime.html#addoutputfilter">AddOutputFilter</a></code> and family.

Each filter then needs to determine whether to run, and there is little

flexibility available for server admins to allow the chain to be

configured dynamically.</p>

<p><code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code> 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 <code class="directive"><a href="../mod/core.html#addoutputfilterbytype">AddOutputFilterByType</a></code>, 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

<code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> to anyone who needs it.</p>

</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>

<h2><a name="terms" id="terms">Filter Declarations, Providers and Chains</a></h2>

<dfn>Figure 1:</dfn> The traditional filter model</p>

<p>In the traditional model, output filters are a simple chain

from the content generator (handler) to the client. This works well

provided the filter chain can be correctly configured, but presents

problems when the filters need to be configured dynamically based on

the outcome of the handler.</p>

<dfn>Figure 2:</dfn> The <code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code> model</p>

<p><code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code> works by introducing indirection into

the filter chain. Instead of inserting filters in the chain, we insert

a filter harness which in turn dispatches conditionally

to a filter provider. Any content filter may be used as a provider

100

to <code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code>; no change to existing filter modules

101

is required (although it may be possible to simplify them). There can be

102

multiple providers for one filter, but no more than one provider will

103

run for any single request.</p>

104

105

<p>A filter chain comprises any number of instances of the filter

106

harness, each of which may have any number of providers. A special

107

case is that of a single provider with unconditional dispatch: this

108

is equivalent to inserting the provider filter directly into the chain.</p>

109

</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>

110

111

<h2><a name="config" id="config">Configuring the Chain</a></h2>

112

<p>There are three stages to configuring a filter chain with

113

<code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code>. For details of the directives, see below.</p>

114

115

<dl>

116

<dt>Declare Filters</dt>

117

<dd>The <code class="directive"><a href="#filterdeclare">FilterDeclare</a></code> directive

118

declares a filter, assigning it a name and filter type. Required

119

only if the filter is not the default type AP_FTYPE_RESOURCE.</dd>

120

121

<dt>Register Providers</dt>

122

<dd>The <code class="directive"><a href="#filterprovider">FilterProvider</a></code>

123

directive registers a provider with a filter. The filter may have

124

been declared with <code class="directive"><a href="#filterdeclare">FilterDeclare</a></code>; if not, FilterProvider will implicitly

125

declare it with the default type AP_FTYPE_RESOURCE. The provider

126

must have been

127

registered with <code>ap_register_output_filter</code> by some module.

128

The remaining arguments to <code class="directive"><a href="#filterprovider">FilterProvider</a></code> are a dispatch criterion and a match string.

129

The former may be an HTTP request or response header, an environment

130

variable, or the Handler used by this request. The latter is matched

131

to it for each request, to determine whether this provider will be

132

used to implement the filter for this request.</dd>

133

134

<dt>Configure the Chain</dt>

135

<dd>The above directives build components of a smart filter chain,

136

but do not configure it to run. The <code class="directive"><a href="#filterchain">FilterChain</a></code> directive builds a filter chain from smart

137

filters declared, offering the flexibility to insert filters at the

138

beginning or end of the chain, remove a filter, or clear the chain.</dd>

139

</dl>

140

</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>

141

142

<h2><a name="examples" id="examples">Examples</a></h2>

143

<dl>

144

<dt>Server side Includes (SSI)</dt>

145

<dd>A simple case of using <code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code> in place of

146

<code class="directive"><a href="../mod/core.html#addoutputfilterbytype">AddOutputFilterByType</a></code>

147

148

FilterDeclare SSI<br />

149

FilterProvider SSI INCLUDES resp=Content-Type $text/html<br />

150

FilterChain SSI

151

</code></p></div>

152

</dd>

153

154

<dt>Server side Includes (SSI)</dt>

155

<dd>The same as the above but dispatching on handler (classic

156

SSI behaviour; .shtml files get processed).

157

158

FilterProvider SSI INCLUDES Handler server-parsed<br />

159

FilterChain SSI

160

</code></p></div>

161

</dd>

162

163

<dt>Emulating mod_gzip with mod_deflate</dt>

164

<dd>Insert INFLATE filter only if "gzip" is NOT in the

165

Accept-Encoding header. This filter runs with ftype CONTENT_SET.

166

167

FilterDeclare gzip CONTENT_SET<br />

168

FilterProvider gzip inflate req=Accept-Encoding !$gzip<br />

169

FilterChain gzip

170

</code></p></div>

171

</dd>

172

173

<dt>Image Downsampling</dt>

174

<dd>Suppose we want to downsample all web images, and have filters

175

for GIF, JPEG and PNG.

176

177

FilterProvider unpack jpeg_unpack Content-Type $image/jpeg<br />

178

FilterProvider unpack gif_unpack Content-Type $image/gif<br />

179

FilterProvider unpack png_unpack Content-Type $image/png<br />

180

<br />

181

FilterProvider downsample downsample_filter Content-Type $image<br />

182

FilterProtocol downsample "change=yes"<br />

183

<br />

184

FilterProvider repack jpeg_pack Content-Type $image/jpeg<br />

185

FilterProvider repack gif_pack Content-Type $image/gif<br />

186

FilterProvider repack png_pack Content-Type $image/png<br />

187

188

189

FilterChain unpack downsample repack<br />

190

</span>

191

</Location>

192

</code></p></div>

193

</dd>

194

</dl>

195

</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>

196

197

<h2><a name="protocol" id="protocol">Protocol Handling</a></h2>

198

<p>Historically, each filter is responsible for ensuring that whatever

199

changes it makes are correctly represented in the HTTP response headers,

200

and that it does not run when it would make an illegal change. This

201

imposes a burden on filter authors to re-implement some common

202

functionality in every filter:</p>

203

204

<ul>

205

<li>Many filters will change the content, invalidating existing content

206

tags, checksums, hashes, and lengths.</li>

207

208

<li>Filters that require an entire, unbroken response in input need to

209

ensure they don't get byteranges from a backend.</li>

210

211

<li>Filters that transform output in a filter need to ensure they don't

212

violate a <code>Cache-Control: no-transform</code> header from the

213

backend.</li>

214

215

<li>Filters may make responses uncacheable.</li>

216

</ul>

217

218

<p><code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code> aims to offer generic handling of these

219

details of filter implementation, reducing the complexity required of

220

content filter modules. This is work-in-progress; the

221

<code class="directive"><a href="#filterprotocol">FilterProtocol</a></code> implements

222

some of this functionality for back-compatibility with Apache 2.0

223

modules. For httpd 2.1 and later, the

224

<code>ap_register_output_filter_protocol</code> and

225

<code>ap_filter_protocol</code> API enables filter modules to

226

declare their own behaviour.</p>

227

228

<p>At the same time, <code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code> should not interfere

229

with a filter that wants to handle all aspects of the protocol. By

230

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>

231

will leave the headers untouched.</p>

232

233

<p>At the time of writing, this feature is largely untested,

234

as modules in common use are designed to work with 2.0.

235

Modules using it should test it carefully.</p>

236

</div>

237

238

<div class="directive-section"><h2><a name="FilterChain" id="FilterChain">FilterChain</a> <a name="filterchain" id="filterchain">Directive</a></h2>

239

240

<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configure the filter chain</td></tr>

241

<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>FilterChain [+=-@!]<var>filter-name</var> <var>...</var></code></td></tr>

242

<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>

243

<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>Options</td></tr>

244

<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>

245

<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_filter</td></tr>

246

</table>

247

<p>This configures an actual filter chain, from declared filters.

248

<code class="directive">FilterChain</code> takes any number of arguments,

249

each optionally preceded with a single-character control that

250

determines what to do:</p>

251

252

<dl>

253

<dt><code>+<var>filter-name</var></code></dt>

254

<dd>Add <var>filter-name</var> to the end of the filter chain</dd>

255

256

<dt><code>@<var>filter-name</var></code></dt>

257

<dd>Insert <var>filter-name</var> at the start of the filter chain</dd>

258

259

<dt><code>-<var>filter-name</var></code></dt>

260

<dd>Remove <var>filter-name</var> from the filter chain</dd>

261

262

<dt><code>=<var>filter-name</var></code></dt>

263

<dd>Empty the filter chain and insert <var>filter-name</var></dd>

264

265

266

<dd>Empty the filter chain</dd>

267

268

<dt><code><var>filter-name</var></code></dt>

269

<dd>Equivalent to <code>+<var>filter-name</var></code></dd>

270

</dl>

271

272

</div>

273

274

<div class="directive-section"><h2><a name="FilterDeclare" id="FilterDeclare">FilterDeclare</a> <a name="filterdeclare" id="filterdeclare">Directive</a></h2>

275

276

<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Declare a smart filter</td></tr>

277

<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>FilterDeclare <var>filter-name</var> <var>[type]</var></code></td></tr>

278

<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>

279

<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>Options</td></tr>

280

<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>

281

<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_filter</td></tr>

282

</table>

283

<p>This directive declares an output filter together with a

284

header or environment variable that will determine runtime

285

configuration. The first argument is a <var>filter-name</var>

286

for use in <code class="directive"><a href="#filterprovider">FilterProvider</a></code>,

287

<code class="directive"><a href="#filterchain">FilterChain</a></code> and

288

<code class="directive"><a href="#filterprotocol">FilterProtocol</a></code> directives.</p>

289

290

<p>The final (optional) argument

291

is the type of filter, and takes values of <code>ap_filter_type</code>

292

- namely <code>RESOURCE</code> (the default), <code>CONTENT_SET</code>,

293

<code>PROTOCOL</code>, <code>TRANSCODE</code>, <code>CONNECTION</code>

294

or <code>NETWORK</code>.</p>

295

296

</div>

297

298

<div class="directive-section"><h2><a name="FilterProtocol" id="FilterProtocol">FilterProtocol</a> <a name="filterprotocol" id="filterprotocol">Directive</a></h2>

299

300

<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Deal with correct HTTP protocol handling</td></tr>

301

<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>FilterProtocol <var>filter-name</var> [<var>provider-name</var>]

302

<var>proto-flags</var></code></td></tr>

303

<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>

304

<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>Options</td></tr>

305

<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>

306

<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_filter</td></tr>

307

</table>

308

<p>This directs <code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code> to deal with ensuring the

309

filter doesn't run when it shouldn't, and that the HTTP response

310

headers are correctly set taking into account the effects of the

311

filter.</p>

312

313

<p>There are two forms of this directive. With three arguments, it

314

applies specifically to a <var>filter-name</var> and a

315

<var>provider-name</var> for that filter.

316

With two arguments it applies to a <var>filter-name</var> whenever the

317

filter runs <em>any</em> provider.</p>

318

319

<p><var>proto-flags</var> is one or more of</p>

320

321

<dl>

322

<dt><code>change=yes</code></dt>

323

<dd>The filter changes the content, including possibly the content

324

length</dd>

325

326

<dt><code>change=1:1</code></dt>

327

<dd>The filter changes the content, but will not change the content

328

length</dd>

329

330

<dt><code>byteranges=no</code></dt>

331

<dd>The filter cannot work on byteranges and requires complete input</dd>

332

333

<dt><code>proxy=no</code></dt>

334

<dd>The filter should not run in a proxy context</dd>

335

336

<dt><code>proxy=transform</code></dt>

337

<dd>The filter transforms the response in a manner incompatible with

338

the HTTP <code>Cache-Control: no-transform</code> header.</dd>

339

340

<dt><code>cache=no</code></dt>

341

<dd>The filter renders the output uncacheable (eg by introducing randomised

342

content changes)</dd>

343

</dl>

344

345

</div>

346

347

<div class="directive-section"><h2><a name="FilterProvider" id="FilterProvider">FilterProvider</a> <a name="filterprovider" id="filterprovider">Directive</a></h2>

348

349

<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Register a content filter</td></tr>

350

<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>FilterProvider <var>filter-name</var> <var>provider-name</var>

351

[req|resp|env]=<var>dispatch</var> <var>match</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 registers a <em>provider</em> for the smart filter.

358

The provider will be called if and only if the <var>match</var> declared

359

here matches the value of the header or environment variable declared

360

as <var>dispatch</var>.</p>

361

362

<p>

363

<var>provider-name</var> must have been registered by loading

364

a module that registers the name with

365

<code>ap_register_output_filter</code>.

366

367

</p>

368

369

<p>The <var>dispatch</var> argument is a string with optional

370

<code>req=</code>, <code>resp=</code> or <code>env=</code> prefix

371

causing it to dispatch on (respectively) the request header, response

372

header, or environment variable named. In the absence of a

373

prefix, it defaults to a response header. A special case is the

374

word <code>handler</code>, which causes <code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code>

375

to dispatch on the content handler.</p>

376

377

<p>The <var>match</var> argument specifies a match that will be applied to

378

the filter's <var>dispatch</var> criterion. The <var>match</var> may be

379

a string match (exact match or substring), a <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regex</a>, an integer (greater, lessthan or equals), or

380

unconditional. The first characters of the <var>match</var> argument

381

determines this:</p>

382

383

<p><strong>First</strong>, if the first character is an exclamation mark

384

(<code>!</code>), this reverses the rule, so the provider will be used

385

if and only if the match <em>fails</em>.</p>

386

387

<p><strong>Second</strong>, it interprets the first character excluding

388

any leading <code>!</code> as follows:</p>

389

390

<table class="bordered"><tr class="header"><th>Character</th><th>Description</th></tr>

391

<tr><td><em>(none)</em></td><td>exact match</td></tr>

392

<tr class="odd"><td><code>$</code></td><td>substring match</td></tr>

393

<tr><td><code>/</code></td><td>regex match (delimited by a second <code>/</code>)</td></tr>

394

<tr class="odd"><td><code>=</code></td><td>integer equality</td></tr>

395

<tr><td><code><</code></td><td>integer less-than</td></tr>

396

<tr class="odd"><td><code><=</code></td><td>integer less-than or equal</td></tr>

397

<tr><td><code>></code></td><td>integer greater-than</td></tr>

398

<tr class="odd"><td><code>>=</code></td><td>integer greater-than or equal</td></tr>

399

<tr><td><code>*</code></td><td>Unconditional match</td></tr>

400

</table>

401

402

</div>

403

404

<div class="directive-section"><h2><a name="FilterTrace" id="FilterTrace">FilterTrace</a> <a name="filtertrace" id="filtertrace">Directive</a></h2>

405

406

<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Get debug/diagnostic information from

407

<code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code></td></tr>

408

<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>FilterTrace <var>filter-name</var> <var>level</var></code></td></tr>

409

<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>

410

<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr>

411

<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_filter</td></tr>

412

</table>

413

<p>This directive generates debug information from

414

<code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code>.

415

It is designed to help test and debug providers (filter modules), although

416

it may also help with <code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code> itself.</p>

417

418

<p>The debug output depends on the <var>level</var> set:</p>

419

<dl>

420

<dt><code>0</code> (default)</dt>

421

<dd>No debug information is generated.</dd>

422

423

424

<dd><code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code> will record buckets and brigades

425

passing through the filter to the error log, before the provider has

426

processed them. This is similar to the information generated by

427

<a href="http://apache.webthing.com/mod_diagnostics/">mod_diagnostics</a>.

428

</dd>

429

430

<dt><code>2</code> (not yet implemented)</dt>

431

<dd>Will dump the full data passing through to a tempfile before the

432

provider. <strong>For single-user debug only</strong>; this will not

433

support concurrent hits.</dd>

434

</dl>

435

436

</div>

437

</div>

438

439

<p><span>Available Languages: </span><a href="../en/mod/mod_filter.html" title="English"> en </a></p>

440

</div><div id="footer">

441

442

443

</body></html>

b'\\ No newline at end of file'

Older »