From: Nick Kew Date: Sun, 13 Nov 2005 12:15:48 +0000 (+0000) Subject: Update filter documentation page. X-Git-Tag: 2.3.0~2782 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=c4d662ec071cb3a377772f116b3562867b0d6957;p=thirdparty%2Fapache%2Fhttpd.git Update filter documentation page. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@332971 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/filter.html.en b/docs/manual/filter.html.en index afb56efbe0e..b7459163ae9 100644 --- a/docs/manual/filter.html.en +++ b/docs/manual/filter.html.en @@ -1,20 +1,20 @@ - Filters - Apache HTTP Server - - - - -
+ + + + +

Modules | Directives | FAQ | Glossary | Sitemap

Apache HTTP Server Version 2.3

-
-
<-
+
+
<-
Apache > HTTP Server > Documentation > Version 2.3

Filters

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

This document describes the use of filters in Apache.

-
top
+ +
top
-

Filters

+

Filtering in Apache 2

-
Related ModulesRelated Directives
+
Related ModulesRelated Directives
-

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
    • +
+
top
+
+

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
    • +
+
top
+
+

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 e5de3c0bfb1..2d58be5120b 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 @@ -

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 +

+

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 +

+ +

+

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.

diff --git a/docs/manual/images/filter_arch.png b/docs/manual/images/filter_arch.png new file mode 100644 index 00000000000..de021af5b57 Binary files /dev/null and b/docs/manual/images/filter_arch.png differ diff --git a/docs/manual/images/mod_filter_new.png b/docs/manual/images/mod_filter_new.png new file mode 100644 index 00000000000..ad2cc735992 Binary files /dev/null and b/docs/manual/images/mod_filter_new.png differ