Apache HTTP サーバ バージョン 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
は使えます。
例
他のタイプのレスポンスから 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);
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
- このパラメータはフィルタが有効になるために設定されていなければ ならない環境変数を指定します。
ExtFilterOptions ディレクティブ
説明: | mod_ext_filter のオプションを設定 |
---|---|
構文: | ExtFilterOptions option [option] ... |
デフォルト: | ExtFilterOptions DebugLevel=0 NoLogStderr |
コンテキスト: | ディレクトリ |
ステータス: | Extension |
モジュール: | mod_ext_filter |
ExtFilterOptions
ディレクティブは
mod_ext_filter
の特別な処理用のオプションを
指定します。Option には以下のどれかを指定します。
DebugLevel=n
-
DebugLevel
でmod_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
からは
デバッグメッセージは生成されません。