Apache 模块 mod_filter

Summary

该模块可对输出内容过滤器进行智能的，上下文相关的配置。例如，即使预先不知道 Content Type(例如，在代理中)，apache 也可以配置为通过不同的过滤器处理不同的 Content Type。

mod_filter通过将间接引入过滤器链来工作。而不是在链中插入过滤器，我们插入过滤器线束，然后依次有条件地将其分发给过滤器提供程序。任何内容过滤器都可以用作mod_filter的提供者；无需更改现有的过滤器模块(尽管可以简化它们)。

Smart Filtering

在传统过滤模型中，过滤器是使用AddOutputFilter和 family 无条件插入的。然后，每个过滤器都需要确定是否运行，并且服务器 Management 员几乎没有灵 Active 来允许动态配置链。

与此相反，mod_filter为服务器 Management 员提供了配置过滤器链的极大灵 Active。实际上，可以基于复杂的布尔值expressions插入过滤器。这概括了AddOutputFilterByType提供的有限的灵 Active。

过滤器声明，提供者和链

图 1：传统的过滤器模型

在传统模型中，输出过滤器是一条从内容生成器(处理程序)到 Client 端的简单链。只要可以正确配置过滤器链，此方法就可以很好地工作，但是当需要根据处理程序的结果动态配置过滤器时，就会出现问题。

图 2：mod_filter模型

mod_filter通过将间接引入过滤器链来工作。而不是在链中插入过滤器，我们插入过滤器线束，然后依次有条件地将其分发给过滤器提供程序。任何内容过滤器都可以用作mod_filter的提供者；无需更改现有的过滤器模块(尽管可以简化它们)。一个过滤器可以有多个提供程序，但对于单个请求，最多只能运行一个提供程序。

过滤器链包括过滤器线束的任意数量的实例，每个实例可以具有任意数量的提供者。一个特殊情况是具有无条件分派的单个提供程序：相当于将提供程序过滤器直接插入到链中。

配置链

使用mod_filter配置过滤器链分为三个阶段。有关指令的详细信息，请参见下文。

• Declare Filters

  • FilterDeclare指令声明一个过滤器，并为其指定名称和过滤器类型。仅当过滤器不是默认类型 AP_FTYPE_RESOURCE 时才需要。

• Register Providers

  • FilterProvider指令使用过滤器注册提供程序。过滤器可能已使用FilterDeclare声明；如果不是，FilterProvider 将使用默认类型 AP_FTYPE_RESOURCE 隐式声明它。提供者必须已通过某个模块在ap_register_output_filter中注册。 FilterProvider的最后一个参数是一个表达式：当且仅当表达式的计算结果为 true 时，才会选择提供程序来运行请求。该表达式可以求值 HTTP 请求或响应 Headers，环境变量或此请求使用的处理程序。与早期版本不同，mod_filter 现在支持复杂的表达式，该表达式涉及多个条件，并带有 AND/OR 逻辑(&&/||)和方括号。 ap_expr documentation中描述了表达式语法的详细信息。

• 配置链

  • 上面的指令构建了智能过滤器链的组件，但没有将其配置为运行。 FilterChain指令从声明的智能过滤器构建过滤器链，从而可以灵活地在过滤器链的开头或结尾插入过滤器，删除过滤器或清除过滤器链。

筛选和响应状态

mod_filter 通常仅对 HTTP 状态为 200(OK)的响应运行筛选器。如果要过滤具有其他响应状态的文档，则可以设置 filter-errordocs 环境变量，并且该变量将对所有响应起作用，而与状态无关。要进一步优化，可以将表达式条件与FilterProvider一起使用。

从 Apache HTTP Server 2.2 配置升级

FilterProvider伪指令已从 httpd 2.2 更改：匹配和调度参数被单个但更通用的表达式替换。通常，您可以使用以下方法将匹配/发送对转换为表达式的两侧：

"dispatch = 'match'"

现在，分别从语法％\ {}，％\ {}和％\ {}解释 Request 头，Response 头和 Environment 变量。还支持变量％\ {}和％\ {}。

请注意，该匹配不再支持子字符串匹配。可以将它们替换为正则表达式匹配项。

Examples

• 服务器端包含(SSI)

  • 替换AddOutputFilterByType的简单案例

FilterDeclare SSI
FilterProvider SSI INCLUDES "%{CONTENT_TYPE} =~ m|^text/html|"
FilterChain SSI

• 服务器端包含(SSI)

与上述相同，但在处理程序上调度(经典 SSI 行为； .shtml 文件得到处理)。

FilterProvider SSI INCLUDES "%{HANDLER} = 'server-parsed'"
FilterChain SSI

• 用 mod_deflate 模拟 mod_gzip

仅当 Accept-Encoding Headers 中没有“ gzip”时，才插入 INFLATE 过滤器。该过滤器以 ftype CONTENT_SET 运行。

FilterDeclare gzip CONTENT_SET
FilterProvider gzip inflate "%{req:Accept-Encoding} !~ /gzip/"
FilterChain gzip

• Image Downsampling

假设我们要对所有 Web 图像进行降采样，并具有针对 GIF，JPEG 和 PNG 的过滤器。

FilterProvider unpack jpeg_unpack "%{CONTENT_TYPE} = 'image/jpeg'"
FilterProvider unpack gif_unpack  "%{CONTENT_TYPE} = 'image/gif'"
FilterProvider unpack png_unpack  "%{CONTENT_TYPE} = 'image/png'"

FilterProvider downsample downsample_filter "%{CONTENT_TYPE} = m|^image/(jpeg|gif|png)|"
FilterProtocol downsample "change=yes"

FilterProvider repack jpeg_pack "%{CONTENT_TYPE} = 'image/jpeg'"
FilterProvider repack gif_pack  "%{CONTENT_TYPE} = 'image/gif'"
FilterProvider repack png_pack  "%{CONTENT_TYPE} = 'image/png'"
<Location "/image-filter">
    FilterChain unpack downsample repack
</Location>

Protocol Handling

从历史上看，每个过滤器负责确保其所做的任何更改均正确地表示在 HTTP 响应 Headers 中，并且在进行非法更改时不运行。这给过滤器作者带来了负担，他们需要在每个过滤器中重新实现一些常用功能：

• 许多过滤器会更改内容，使现有的内容标签，校验和，哈希和长度无效。

• 在 Importing 中需要完整无间断响应的过滤器需要确保它们不会从后端获取字节范围。

• 在过滤器中转换输出的过滤器需要确保它们不违反后端的Cache-Control: no-transformHeaders。

• 筛选器可能会使响应不可缓存。

mod_filter旨在为过滤器实现的这些细节提供通用处理，从而降低内容过滤器模块所需的复杂性。这是正在进行的工作； FilterProtocol实现了部分此功能，以实现与 Apache 2.0 模块的向后兼容性。对于 httpd 2.1 及更高版本，ap_register_output_filter_protocol和ap_filter_protocol API 使过滤器模块可以声明自己的行为。

同时，mod_filter不应干扰要处理协议所有方面的过滤器。默认情况下(即在没有任何FilterProtocol指令的情况下)，mod_filter将保持标题不变。

在撰写本文时，此功能尚未经过测试，因为常用的模块旨在与 2.0 一起使用。使用它的模块应该仔细测试。

AddOutputFilterByType Directive

该指令根据响应media-type激活请求的特定输出filter。

以下示例使用mod_deflate提供的DEFLATE过滤器。它将压缩所有标记为text/html或text/plain的输出(静态或动态)，然后再将其发送到 Client 端。

AddOutputFilterByType DEFLATE text/html text/plain

如果希望内容由多个过滤器处理，则它们的名称必须用分号分隔。对于每个这些过滤器，也可以使用一个AddOutputFilterByType指令。

以下配置使所有标记为text/html的脚本输出首先由INCLUDES过滤器处理，然后由DEFLATE过滤器处理。

<Location "/cgi-bin/">
    Options Includes
    AddOutputFilterByType INCLUDES;DEFLATE text/html
</Location>

See also

• AddOutputFilter

• SetOutputFilter

• filters

FilterChain Directive

这将从声明的过滤器配置实际的过滤器链。 FilterChain接受任意数量的参数，每个参数可选地以一个单字符控件开头，该控件确定要执行的操作：

• +filter-name

  • 将过滤器名称添加到过滤器链的末尾

• @filter-name

  • 在过滤器链的开头插入过滤器名称

• -filter-name

  • 从过滤器链中删除过滤器名称

• =filter-name

  • 清空过滤器链并插入过滤器名称

• !

  • 清空过滤链

• filter-name

  • 相当于+filter-name

FilterDeclare Directive

该指令声明输出过滤器以及将确定运行时配置的 Headers 或环境变量。第一个参数是用于FilterProvider，FilterChain和FilterProtocol指令的过滤器名称。

最后一个(可选)参数是过滤器的类型，并采用ap_filter_type的值-即RESOURCE(默认值)，CONTENT_SET，PROTOCOL，TRANSCODE，CONNECTION或NETWORK。

FilterProtocol Directive

这指示mod_filter处理确保过滤器在不应该运行的情况下不运行，并考虑到过滤器的影响正确设置了 HTTP 响应 Headers。

该指令有两种形式。它带有三个参数，专门适用于该过滤器的过滤器名称和提供者名称。每当过滤器运行* any *提供程序时，它都有两个参数适用于过滤器名称。

用此伪指令指定的标志与基础提供程序可能已在mod_filter注册的标志合并。例如，过滤器可以在内部指定change=yes的等效项，但是模块的特定配置可以用change=no覆盖。

原型标志是以下一项或多项

• change=yes|no

  • 指定过滤器是否更改内容，包括可能的内容长度。 2.4.7 和更高版本支持“ no”参数。

• change=1:1

  • 过滤器更改内容，但不会更改内容长度

• byteranges=no

  • 过滤器无法在字节范围上工作，需要完整的 Importing

• proxy=no

  • 筛选器不应在代理上下文中运行

• proxy=transform

  • 过滤器以与 HTTP Cache-Control: no-transformHeaders 不兼容的方式转换响应。

• cache=no

  • 过滤器使输出不可缓存(例如，通过引入随机的内容更改)

FilterProvider Directive

该指令为智能过滤器注册了一个“提供者”。当且仅当第一次调用线束时声明的表达式的值为 true 时，才将调用提供程序。

provider-name 必须已通过加载将名称注册到ap_register_output_filter的模块来注册。

表达式是ap_expr。

See also

• Apache HTTP Server 中的表达式，以获取完整的参考和示例。

• mod_include

FilterTrace Directive

该指令从mod_filter生成调试信息。尽管它也可能对mod_filter本身有所帮助，但它旨在帮助测试和调试提供程序(过滤器模块)。

调试输出取决于设置的级别：

• 0(默认)

  • 没有调试信息生成。

• 1

  • mod_filter将在提供者处理它们之前记录通过过滤器到达错误日志的存储桶和旅。这类似于mod_diagnostics生成的信息。

• 2(尚未实施)

  • 将转储提供者之前传递到临时文件的完整数据。 仅适用于单用户调试 ；这将不支持并发命中。