mod_ext_filter - Apache HTTP サーバ バージョン 2.4

Apache Server 2.4

<-

Apache モジュール mod_ext_filter

この日本語訳はすでに古くなっている 可能性があります。 最近更新された内容を見るには英語版をご覧下さい。
説明:レスポンスのボディをクライアントに送る前に外部プログラムで処理する
ステータス:Extension
モジュール識別子:ext_filter_module
ソースファイル:mod_ext_filter.c

概要

mod_ext_filter では フィルタ の慣れ親しんだ単純なプログラミングモデルが提供されます。このモジュールを 使えば、標準入力から読み込んで、標準出力に書き出すプログラム (すなわち Unix 形式のフィルタコマンド) を Apache のフィルタにすることが できます。このフィルタの機構は、Apache API 向けに書かれた Apache サーバプロセス内で実行される専用のフィルタよりもずっと遅いですが、 以下のような利点もあります。

  • ずっとシンプルなプログラミングモデル
  • プログラムが標準入力から読んで標準出力に書くものである限り、 どんなプログラム言語やスクリプト言語でも使うことができる
  • 既存のプログラムを変更することなく Apache のフィルタとして 使うことができる

性能の問題により実運用に適さないとしても、フィルタのプロトタイプ用の 環境としては mod_ext_filter は使えます。

top

他のタイプのレスポンスから 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

# mod_ext_filter directive to set the debug
# level just high enough to see a log message
# per request showing the configuration in force
ExtFilterOptions DebugLevel=1
</Directory>

コンテントエンコーディングのフィルタを実装する

注: この gzip の例はデモ用です。実用的な実装は mod_deflate を参照してください。

# 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_header 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>

別のフィルタのトレース

# 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);

top

ExtFilterDefine ディレクティブ

説明:外部フィルタを定義
構文:ExtFilterDefine filtername parameters
コンテキスト:サーバ設定ファイル
ステータス:Extension
モジュール:mod_ext_filter

ExtFilterDefine は、実行するプログラムや 引数など、外部フィルタの特性を定義します。

filtername は定義するフィルタの名前を指定します。 この名前は後で SetOutputFilter ディレクティブで指定できます。名前は登録されるすべてのフィルタで 一意でなくてはなりません。現時点では、フィルタの登録 API からは エラーは報告されません。ですから、重複する名前を使ってしまったときでも ユーザにはそのことは報告されません。

続くパラメータの順番は関係無く、それらは実行する外部コマンドと、 他の特性を定義します。cmd= だけが必須のパラメータです。 指定可能なパラメータは:

cmd=cmdline
cmd= キーワードは実行する外部コマンドを指定します。 プログラム名の後に引数がある場合は、コマンド行は引用符で囲む 必要があります (例えばcmd="/bin/mypgm arg1 arg2" のように)。プログラムは シェル経由でなく、直接実行されますので、通常のシェル用の エスケープは必要ありません。プログラムの引数は空白で区切られます。 プログラムの引数の一部となる必要のある空白はバックスペースでエスケープ できます。引数の一部になるバックスラッシュはバックスラッシュで エスケープする必要があります。標準の CGI 環境変数に加えて、 環境変数 DOCUMENT_URI, DOCUMENT_PATH_INFO, and QUERY_STRING_UNESCAPED がプログラムのために設定されます。
mode=mode
応答を処理するフィルタには mode=output (デフォルト) を使います。リクエストを処理するフィルタには mode=input を使います。mode=input は Apache 2.1 以降で利用可能です。
intype=imt
このパラメータはフィルタされるべきドキュメントの インターネットメディアタイプ (すなわち、MIME タイプ) を 指定します。デフォルトではすべてのドキュメントがフィルタされます。 intype= が指定されていれば、フィルタは指定されていない ドキュメントには適用されなくなります。
outtype=imt
このパラメータはフィルタされたドキュメントの インターネットメディアタイプ (すなわち、MIME タイプ) を 指定します。フィルタ動作にともなってインターネットメディアタイプが 変わる場合に有用です。デフォルトではインターネットメディアタイプは 変更されません。
PreservesContentLength
PreservesContentLength キーワードはフィルタが content length (訳注: コンテントの長さ) を変更しないということを指定します。ほとんどのフィルタは content length を変更するため、これはデフォルトではありません。 フィルタが長さを変えないときは、このキーワードを指定すると よいでしょう。
ftype=filtertype
このパラメータはフィルタが登録されるべきフィルタタイプの 数値を指定します。ほとんどの場合は、デフォルトの AP_FTYPE_RESOURCE で 十分です。フィルタがフィルタチェーンの別の場所で動作する必要がある 場合は、このパラメータを指定する必要があります。指定可能な値は util_filter.h の AP_FTYPE_foo 定義を参照してください。
disableenv=env
設定されていた場合にフィルタを無効にするための環境変数を 指定します。
enableenv=env
このパラメータはフィルタが有効になるために設定されていなければ ならない環境変数を指定します。
top

ExtFilterOptions ディレクティブ

説明:mod_ext_filter のオプションを設定
構文:ExtFilterOptions option [option] ...
デフォルト:ExtFilterOptions DebugLevel=0 NoLogStderr
コンテキスト:ディレクトリ
ステータス:Extension
モジュール:mod_ext_filter

ExtFilterOptions ディレクティブは mod_ext_filter の特別な処理用のオプションを 指定します。Option には以下のどれかを指定します。

DebugLevel=n
DebugLevelmod_ext_filter の生成するデバッグメッセージのレベルを設定できます。 デフォルトでは、デバッグメッセージは生成されません。 これは DebugLevel=0 と設定するのと同じです。 数字が大きくなればなるほど、より多くのデバッグメッセージが 生成され、サーバの性能は落ちます。数値の実際の意味は mod_ext_filter.c の先頭近くの DBGLVL_ 定数の 定義で説明されています。

注: デバッグメッセージを Apache のエラーログに 保存するようにするためには、core のディレクティブ LogLevel を使う必要があります。

LogStderr | NoLogStderr
LogStderr キーワードは外部フィルタプログラムにより 標準エラー (訳注: stderr) に書かれたメッセージを Apache のエラーログに保存するようにします。NoLogStderr は 逆に保存しないようにします。

ExtFilterOptions LogStderr DebugLevel=0

この例では、フィルタの標準出力に書かれたメッセージは Apache のエラーログに保存されます。mod_ext_filter からは デバッグメッセージは生成されません。