mod_ext_filter

摘要

mod_ext_filter为过滤器提供了一个简单而熟悉的编程 model。使用此模块，从 stdin 读取并写入 stdout(i.e.，Unix-style 过滤器命令)的程序可以是 Apache 的过滤器。这种过滤机制比使用专门为 Apache API 编写并在 Apache 服务器 process 内部运行的过滤器慢得多，但它确实具有以下优点：

• 编程 model 要简单得多
• 可以使用任何 programming/scripting 语言，前提是它允许程序从标准输入读取并写入标准输出
• 现有程序可以不加修改地用作 Apache 过滤器

即使 performance 特性不适合 production 使用，mod_ext_filter也可以用作过滤器的原型环境。

例子

从其他类型的响应生成 HTML

# mod_ext_filter directive to define a filter
# to HTML-ize text/c files using the external
# program /usr/bin/enscript, with the type of
# the result set to text/html
ExtFilterDefine c-to-html mode=output 
    intype=text/c outtype=text/html 
    cmd="/usr/bin/enscript --color -w html -Ec -o -"

<Directory "/export/home/trawick/apacheinst/htdocs/c">
    # core directive to cause the new filter to
    # be run on output
    SetOutputFilter c-to-html
    
    # mod_mime directive to set the type of .c
    # files to text/c
    AddType text/c .c
</Directory>

实现内容编码过滤器

注意：此 gzip example 仅用于说明目的。请参阅mod_deflate以获得实用的 implementation。

# mod_ext_filter directive to define the external filter
ExtFilterDefine gzip mode=output cmd=/bin/gzip

<Location "/gzipped">
    
    # core directive to cause the gzip filter to be
    # run on output
    SetOutputFilter gzip
    
    # mod_headers directive to add
    # "Content-Encoding: gzip" header field
    Header set Content-Encoding gzip
</Location>

放慢服务器的速度

# mod_ext_filter directive to define a filter
# which runs everything through cat; cat doesn't
# modify anything; it just introduces extra pathlength
# and consumes more resources
ExtFilterDefine slowdown mode=output cmd=/bin/cat 
    preservescontentlength

<Location "/">
    # core directive to cause the slowdown filter to
    # be run several times on output
    #
    SetOutputFilter slowdown;slowdown;slowdown
</Location>

使用 sed 替换响应中的文本

# mod_ext_filter directive to define a filter which
# replaces text in the response
#
ExtFilterDefine fixtext mode=output intype=text/html 
    cmd="/bin/sed s/verdana/arial/g"

<Location "/">
    # core directive to cause the fixtext filter to
    # be run on output
    SetOutputFilter fixtext
</Location>

您可以使用mod_substitute执行相同的操作而无需调用外部 process。

跟踪另一个过滤器

# Trace the data read and written by mod_deflate
# for a particular client (IP 192.168.1.31)
# experiencing compression problems.
# This filter will trace what goes into mod_deflate.
ExtFilterDefine tracebefore 
    cmd="/bin/tracefilter.pl /tmp/tracebefore" 
    EnableEnv=trace_this_client

# This filter will trace what goes after mod_deflate.
# Note that without the ftype parameter, the default
# filter type of AP_FTYPE_RESOURCE would cause the
# filter to be placed *before* mod_deflate in the filter
# chain.  Giving it a numeric value slightly higher than
# AP_FTYPE_CONTENT_SET will ensure that it is placed
# after mod_deflate.
ExtFilterDefine traceafter 
    cmd="/bin/tracefilter.pl /tmp/traceafter" 
    EnableEnv=trace_this_client ftype=21

<Directory "/usr/local/docs">
    SetEnvIf Remote_Addr 192.168.1.31 trace_this_client
    SetOutputFilter tracebefore;deflate;traceafter
</Directory>

以下是跟踪数据的过滤器：

#!/usr/local/bin/perl -w
use strict;

open(SAVE, ">$ARGV[0]")
    or die "can't open $ARGV[0]: $?";

while (<STDIN>) {
    print SAVE $_;
    print $_;
}

close(SAVE);

ExtFilterDefine 指令

ExtFilterDefine指令定义外部过滤器的特征，包括 run 程序及其 arguments。

filtername 指定要定义的过滤器的 name。然后可以在SetOutputFilter指令中使用此 name。它必须在所有已注册的过滤器中是唯一的在当前 time，register-filter API 未报告任何错误，因此不会向用户报告重复名称的问题。

后续参数可以出现在任何 order 中，并将外部命令定义为 run 和某些其他特征。唯一必需的参数是cmd=。这些参数是：

• cmd=cmdline
  cmd =关键字允许您指定 run 的外部命令。如果在程序 name 之后有 arguments，则命令 line 应该用引号括起来(e.g.，cmd =“/bin/mypgm arg1 arg2”.)正常 shell 引用是没有必要的，因为程序直接 run，绕过 shell。程序 arguments 是 blank-delimited。反斜杠可用于转义空白，这应该是程序参数的一部分。作为参数一部分的任何反斜杠必须使用反斜杠进行转义。除了标准的 CGI 环境变量，DOCUMENT_URI，DOCUMENT_PATH_INFO 和 QUERYSTRING_UNESCAPED 将也为该计划设定。
• mode=mode
  对处理响应的过滤器使用 mode=output(默认值)。将 mode=input 用于处理请求的过滤器。 _A在 Apache 2.1 及更高版本中可用。
• intype=imt
  此参数指定应筛选的文档的 Internet 媒体类型(i.e.，MIME 类型)。默认情况下，将过滤所有文档。如果指定了 intype =，则将禁用其他类型文档的过滤器。
• outtype=imt
  此参数指定筛选文档的 Internet 媒体类型(i.e.，MIME 类型)。当过滤器更改 Internet 媒体类型作为过滤操作的一部分时，它很有用。默认情况下，Internet 媒体类型保持不变。
• PreservesContentLength
  PreservesContentLength 关键字指定过滤器保留内容长度。这不是默认设置，因为大多数过滤器会更改内容长度。在 event 中，过滤器不会修改长度，应指定此关键字。
• ftype=filtertype
  此参数指定过滤器应注册为的过滤器类型的数字 value。在大多数情况下，默认的 value，AP_FTYPE_RESOURCE 就足够了。如果过滤器需要在过滤器链中的不同点上操作而不是资源过滤器，则此参数将是必需的。请参阅 util_filter.h 中的 AP_FTYPE_foo 定义以获取适当的值。
• disableenv=env
  此参数指定环境变量的 name，如果设置，将禁用过滤器。
• enableenv=env
  此参数指定必须设置的环境变量的 name，否则将禁用过滤器。

ExtFilterOptions 指令

ExtFilterOptions指令为mod_ext_filter指定了特殊处理选项。选项可以是其中之一

• LogStderr | NoLogStderr
  LogStderr 关键字指定外部过滤器程序写入标准错误的消息将保存在 Apache error log 中。 NoLogStderr 禁用此 feature。
• Onfail=[abort|remove]
  确定如果无法启动外部过滤器程序，如何继续。使用 abort(默认 value)，请求将被中止。删除后，过滤器将被删除，请求将在没有过滤器的情况下继续。

ExtFilterOptions LogStderr

写入过滤器标准错误的消息将存储在 Apache error log 中。