Filters

@@ -27,46 +27,99 @@

This document describes the use of filters in Apache.

Filtering in Apache 2
Smart Filtering
Using Filters

Filtering in Apache 2

Related Modules	Related Directives
`mod_deflate` `mod_ext_filter` `mod_include`	`AddInputFilter` `AddOutputFilter` `RemoveInputFilter` `RemoveOutputFilter` `ExtFilterDefine` `ExtFilterOptions` `SetInputFilter` `SetOutputFilter`

- +

Related Modules	Related Directives
`mod_filter` `mod_deflate` `mod_ext_filter` `mod_include` `mod_charset_lite`	`FilterChain` `FilterDeclare` `FilterProtocol` `FilterProvider` `AddInputFilter` `AddOutputFilter` `RemoveInputFilter` `RemoveOutputFilter` `ExtFilterDefine` `ExtFilterOptions` `SetInputFilter` `SetOutputFilter`

A filter 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 input filters while data sent - by the server to the client is processed by output - filters. Multiple filters can be applied to the data, and - the order of the filters can be explicitly specified.

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.

+ Filters can be chained, in a Data Axis orthogonal to request processing +

Some examples of filtering in the standard Apache distribution are:

mod_includes, implements server-side includes.
mod_ssl, implements SSL encryption (https).
mod_deflate, implements compression/decompression on the fly.
mod_charset_lite, transcodes between different character sets.
mod_ext_filter, runs an external program as a filter.

Apache also uses a number of filters internally, to perform +functions like chunking and byte-range handling.

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 +

A wider range of applications are implemented by third-party +filter modules. A few of these are:

HTML and XML processing and rewriting
XSLT transforms and XIncludes
XML Namespace support
File Upload handling and decoding of HTML Forms
Image processing
Protection of vulnerable applications such as PHP scripts
Text search-and-replace editing

Smart Filtering

+ +

+ Smart filtering applies different filter providers according to the state of request processing +

mod_filter, 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,

an HTML processing filter will only run if the content is +text/html or application/xhtml+xml
A compression filter will only run if the input is a +compressable type and not already compressed
A charset conversion filter will be inserted if a text +document is not already in the desired charset

Using Filters

+ +

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!

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 SetInputFilter, SetOutputFilter, AddInputFilter, AddOutputFilter, RemoveInputFilter, and - RemoveOutputFilter - directives.

- -

The following user-selectable filters are currently provided - with the Apache HTTP Server distribution.

- -

INCLUDES: Server-Side Includes processing by mod_include
DEFLATE: Compress output before sending it to the client using - mod_deflate -

+ RemoveOutputFilter.

In addition, the module mod_ext_filter allows - for external programs to be defined as filters.

The Dynamic Way enables both static and flexible, dynamic configuration +of output filters, as discussed in the mod_filter page. +Relevant directives are + FilterChain, + FilterDeclare, + FilterProvider.

One further directive AddOutputFilterByType is still supported, +but may be problematic and is now deprecated. Use dynamic configuration +instead.

Available Languages: en | @@ -77,4 +130,4 @@

- \ No newline at end of file + 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 @@

This document describes the use of filters in Apache.

- Filters +

+ Filtering in Apache 2 + mod_filter mod_deflate mod_ext_filter mod_include + mod_charset_lite + FilterChain + FilterDeclare + FilterProtocol + FilterProvider AddInputFilter AddOutputFilter RemoveInputFilter @@ -48,39 +54,90 @@ -

+ +"Filters +

Some examples of filtering in the standard Apache distribution are:

mod_includes, implements server-side includes.
mod_ssl, implements SSL encryption (https).
mod_deflate, implements compression/decompression on the fly.
mod_charset_lite, transcodes between different character sets.
mod_ext_filter, runs an external program as a filter.

Apache also uses a number of filters internally, to perform +functions like chunking and byte-range handling.

A wider range of applications are implemented by third-party +filter modules. A few of these are:

HTML and XML processing and rewriting
XSLT transforms and XIncludes
XML Namespace support
File Upload handling and decoding of HTML Forms
Image processing
Protection of vulnerable applications such as PHP scripts
Text search-and-replace editing

+Smart Filtering +

+ +

mod_filter, 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,

an HTML processing filter will only run if the content is +text/html or application/xhtml+xml
A compression filter will only run if the input is a +compressable type and not already compressed
A charset conversion filter will be inserted if a text +document is not already in the desired charset

+ +

+Using Filters +

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 SetInputFilter, SetOutputFilter, AddInputFilter, AddOutputFilter, RemoveInputFilter, and - RemoveOutputFilter - directives.

- -

The following user-selectable filters are currently provided - with the Apache HTTP Server distribution.

- -

INCLUDES: Server-Side Includes processing by mod_include
DEFLATE: Compress output before sending it to the client using - mod_deflate -

+ RemoveOutputFilter.

In addition, the module mod_ext_filter allows - for external programs to be defined as filters.

The Dynamic Way enables both static and flexible, dynamic configuration +of output filters, as discussed in the mod_filter page. +Relevant directives are + FilterChain, + FilterDeclare, + FilterProvider.

One further directive AddOutputFilterByType is still supported, +but may be problematic and is now deprecated. Use dynamic configuration +instead.

diff --git a/docs/manual/images/filter_arch.png b/docs/manual/images/filter_arch.png new file mode 100644 index 0000000000000000000000000000000000000000..de021af5b57c9337a281f203163ad88ca4e13465 GIT binary patch literal 2553 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 P00000NkvXXu0mjfpOd^t literal 0 HcmV?d00001 diff --git a/docs/manual/images/mod_filter_new.png b/docs/manual/images/mod_filter_new.png new file mode 100644 index 0000000000000000000000000000000000000000..ad2cc7359925461bc72ae70eb0d34967f5ac5188 GIT binary patch literal 1130 zcmV-w1eN=VP)Oq!It;++>QuwrbljE`VU zAAoB^TENC)Vk{3}qDfx_Qxjif+b7uGaY5AKYd>IjnR9IEG1-6mF@^bc*p}UyIkZA# z$&w{YmgJNM!tmS*QsvZ}1l2IHO5l|>P^wwoDYY?5f>H&ia)KIbrhuZ3Nve)la-!-O zWep5(*s8*ZHfFFaS<(V)R8973xJCse#XrDa@ei<9`~&P2n^=GRMDKt!6)XXbyHlxQ zp@6+g4N=(x^|4|g)nr2=mKEHF+Pb_pn|q~49gMOs9^N+#4fyP&bz2%M_fYoKo}`CV zxv{GC40nE8%|B6-79A7yMvWy6f42qx2br!KN{J(kGCXMQm6S4u+RAUK-D1lbS zsPY`IR39lxs!UK#S+hS4kjg8_a^V$V$0|r!cu7&EpW)-`jISy8#$?4mB>_!bM&Ia?dLLgRKH`tlU%R zADGxjcm(k67xodFU4Xs->?8cBltdrbdw?_K&(QT-h}ppg|63wvA}>xwv#e~=yzEit zWt*}}F+7Ue6oggEWI>8nn?69O>Dm|k+w|0AC><5vr{rB-72a{|ia>#`$`ABauuqu{ zrK5s<%6urTQUurJxWt8)}u75SfqNCwOEf@t;EtZ>Q<{*iwaT2idL3%t60(6*NQ4u zOpS=pk2d&NJ% zUhxlbSI3L>UoF&Di#sfu{>9S>hh~2`=D!4_m(AJd-PB%-@n)Z`HUj1S&MrbdiD|7) z@Gk+DJ_^00g?M!