test

Sun Java System Web Server 7.0 管理ガイド

付録 B FastCGI プラグイン

概要

FastCGI は、外部アプリケーションと Web サーバー間の標準インタフェースである既存の CGI (Common Gateway Interface) を拡張したものです。FastCGI アプリケーションは CGI と同じく、隔離された個別のプロセス内で実行されます。FastCGI を使用する利点を次にいくつか示します。

FastCGI プラグインを使えば、Perl や Python など、広く普及しているサードパーティーの動的コンテンツ生成テクノロジと Web Server との安全な連携動作を、高いスケーラビリティーを維持するかたちで実現できます。

FastCGI の詳細については、http://www.fastcgi.com/devkit/doc/fcgi-spec.html の仕様書を参照してください。

プラグイン関数 (SAF)

FastCGI プラグインが提供するサーバーアプリケーション関数 (SAF) は、次のとおりです。

FastCGI SAF の各種パラメータと「error-reason」文字列については、次の各節で説明します。

auth-fastcgi

auth-fastcgi は PatchCheck 関数です。この関数は、「オーソライザ」FastCGI アプリケーションに要求を転送するために使用されます。承認が成功すると、リターンコード 200 が送信されます。それ以外の場合は、「オーソライザ」FastCGI アプリケーションからの応答がユーザーエージェントに送り返されます。

FastCGI のロールの詳細については、http://www.fastcgi.com/devkit/doc/fcgi-spec.html#S6 を参照してください。

auth-fastcgi SAF が受け付けるパラメータについては、「FastCGI SAF パラメータ」を参照してください。

次の obj.conf コード例は、auth-fastcgi の使用方法を示したものです。

PathCheck fn="auth-fastcgi" app-path="/usr/bin/perl" app-args="/fastcgi/apps/auth/SimpleAuth.pl" bind-path="localhost:3432".

responder-fastcgi

responder-fastcgi は Service 関数です。この関数は、「レスポンダ」として機能する FastCGI アプリケーションに要求を転送するために使用されます。レスポンダアプリケーションからの応答は、ユーザーエージェントに送り返されます。FastCGI のロールの詳細については、http://www.fastcgi.com/devkit/doc/fcgi-spec.html#S6 を参照してください。

responder-fastcgi SAF が受け付けるパラメータの一覧については、「FastCGI SAF パラメータ」 を参照してください。

次の obj.conf コード例は、responder-fastcgi の使用方法を示したものです。

Service fn="responder-fastcgi" app-path="/fastcgi-enabled-php-installation/bin/php" bind-path="localhost:3433" app-env="PHP_FCGI_CHILDREN=8" app-env="PHP_FCGI_MAX_REQUEST=500".

filter-fastcgi

filter-fastcgi は Service 関数です。この関数は、「フィルタ」タイプの FastCGI アプリケーションに要求を転送するために使用されます。「フィルタ」アプリケーションは、HTTP 要求に関連付けられた情報と、サーバー上に格納されたファイルからのデータを受け取ります。次に、「フィルタ」アプリケーションは、「フィルタリング」されたバージョンのデータストリームを応答として生成します。これがユーザーエージェントに送り返されます。FastCGI のロールの詳細については、http://www.fastcgi.com/devkit/doc/fcgi-spec.html#S6 を参照してください。

filter-fastcgi SAF が受け付けるパラメータの一覧については、「FastCGI SAF パラメータ」 を参照してください。

次の obj.conf コード例は、filter-fastcgi の使用方法を示したものです。

Service fn="filter-fastcgi" app-path="/fastcgi/apps/filter/SimpleFilter" bind-path="localhost:3434" app-env="LD_LIBRARY_PATH=/fastcgi/fcgi-2.4/libfcgi/.libs" min-procs=2

error-fastcgi

error-fastcgi は Error 関数です。error-fastcgi SAF は、FastCGI プラグインに固有のエラーを処理します。一方、この関数は HTTP エラーを処理しません。エラー時に特定のページを表示するか特定の URL に要求をリダイレクトするように、FastCGI プラグインを構成することができます。

error-fastcgi SAF が受け付けるパラメータの一覧については、「FastCGI SAF パラメータ」を参照してください。

次の obj.conf コード断片は、error-fastcgi の使用方法を示したものです。

Error fn="error-fastcgi" error-reason="Invalid Parameters" error-url="http://www.foo.com/errorPage.html"

error-fastcgi パラメータの詳細については、「FastCGI SAF パラメータ」を参照してください。

FastCGI SAF パラメータ

FastCGI プラグインの SAF「auth-fastcgi」、「responder-fastcgi」、および「filter-fastcgi」はすべて、特に明記されていないかぎり、次のパラメータを受け付けます。

パラメータ chroot、user、group、および nice は、UNIX プラットフォームにしか適用できません。Windows プラットフォームでは、それらのパラメータは無視されます。

error-fastcgi サーバーアプリケーション関数 (SAF) は次のパラメータを受け付けます。

error-fastcgi SAF のエラー理由文字列

この節では、有効なすべての「error-reason」文字列とその説明の一覧を示します。

Web Server での FastCGI プラグインの構成

FastCGI プラグインは Web Server 7.0 にバンドルされています。このプラグインのインストール場所は次のとおりです。

32 ビットの FastCGI プラグインバイナリは、<install_dir>/plugins/fastcgi ディレクトリにインストールされます。

64 ビットの Solaris SPARC FastCGI プラグインバイナリは、<install_dir>/lib/plugins/fastcgi/64 ディレクトリにインストールされます。

インストールされる FastCGI バイナリは次のとおりです。

libfastcgi.so (Solaris/Linux 用)

fastcgi.dll (Windows 用)

Fastcgistub.exe (Windows 用)

libfastcgi.sl (HP-UX 用)

Fastcgistub (実行可能ファイル)

FastCGI プラグインを構成するには、<instance-dir>/config ディレクトリに格納されている Web Server 構成ファイルを使用します。FastCGI プラグインを構成するには、次の手順を実行します。

magnus.conf の変更

「load-modules」Init 関数を使って FastCGI プラグインの共有ライブラリを読み込みます。

Init fn=flex-init access="access" format.access="%Ses->client.ip%
- %Req->vars.auth-user% [%SYSDATE%] \"%Req->reqpb.clf-request%\"
%Req->srvhdrs.clf-status% %Req->srvhdrs.content-length%"

Init fn="load-modules" shlib="libJava EEplugin.so" shlib_flags="(global|now)"

Init fn="load-modules" shlib="libfastcgi.so" shlib_flags="(global|now)"

MIME タイプの変更 (省略可能)

mime.types ファイルを編集して MIME マッピングを指定します。MIME タイプのマッピングの変更は、省略可能な手順です。

次に例を示します。

#--Sun Microsystems Inc. MIME Information

# Do not delete the above line. It is used to identify the file type.

#

# Copyright 2006 Sun Microsystems, Inc. All rights reserved.

# Use is subject to license terms.

#


type=application/octet-stream exts=bin

type=application/astound exts=asd,asn

...

...

type=magnus-internal/fastcgi exts=php

...

...

obj.conf の変更

obj.conf ファイルを編集し、これまでの節で説明したプラグイン SAF を使って FastCGI に固有の要求を構成します。

変更後の obj.conf ファイルの例を、次に示します。

#

# Copyright 2006 Sun Microsystems, Inc. All rights reserved.

# Use is subject to license terms.

#


# You can edit this file, but comments and formatting changes

# might be lost when you use the administration GUI or CLI.



<object name = "default">

		AuthTrans fn="match-browser" browser="*MSIE*" 
						ssl-unclean-shutdown="true"
		NameTrans fn="ntrans-Java EE" name="Java EE"
		NameTrans fn="pfx2dir" from="/mc-icons" 
						dir="/ws7/lib/icons" name="es-internal"
		NameTrans fn="assign-name" from="/fcgi/*" name="fcgi.config"

</object>

<Object name="fcgi.config">

		AuthTrans fn="auth-fastcgi" app-path="/fastcgi/apps/c/simpleAuth" 
				bind-path="localhost:2111"
		Service fn="responder-fastcgi" 
						app-path="/fastcgi_enabled_php_installation_dir/bin/php" 
				app-env="name1=abc"

</object>
...

FastCGI の SAF は、URL パターンごとに異なるオブジェクトを定義したり、SAF を異なる MIME タイプにマップしたりするなど、さまざまな方法で呼び出せます。

obj.conf の構成や構文の詳細については、『Administration Configuration File Reference Guide』を参照してください。

FastCGI プラグインのトラブルシューティング

Fastcgistub は、FastCGI アプリケーションプロセスのライフサイクルを管理するプロセスマネージャーです。Fastcgistub は、Web Server の一時ディレクトリの下の Fastcgistub.log ファイルに、自身のメッセージを記録します。エラーが発生した場合、このファイルをチェックすると問題のデバッグが容易になる可能性があります。

問題: FastCGI の要求が処理されない

可能性のある原因とその解決法は、次のとおりです。

  1. FastCGI プラグインが読み込まれているかチェックします。Web Server の起動時に次のメッセージが表示されれば、このプラグインは正常に読み込まれています。そうでない場合は、magnus.conf でプラグインライブラリへのパスをチェックします。 FCGI1000: Sun Java System Web Server 7.0 FastCGI NSAPI Plugin <ビルド情報>

  2. obj.conf で要求のマッピングが正しく指定されているかチェックします。obj.conf ファイルの詳細については、『Sun Java System Web Server Administrator's Configuration Reference File』を参照してください。

  3. エラーログにエラーメッセージが含まれていないかチェックします。

  4. スタブバイナリと FastCGI アプリケーションのアクセス権をチェックします。十分なアクセス権が与えられていない場合、プラグインはスタブまたはアプリケーションの起動に失敗します。

  5. Fastcgistub.log ファイルにスタブ側のエラーが含まれていないかチェックします。

  6. 可能であれば、FastCGI アプリケーションをスタンドアロンモードで実行し、アプリケーションが問題なく実行されるかチェックします。

ライブラリの依存関係に関するエラーがスローされた場合には、LD_LIBRARY_PATH=<依存関係のあるライブラリのパス> を値に持つ app-env パラメータとして、obj.conf 内で LD_LIBRARY_PATH を指定します。

問題: FastCGI アプリケーションが起動されない。

可能性のある原因とその解決法は、次のとおりです。

Fastcgistub.log ファイルに次のログメッセージが含まれていないかチェックします。

 

..
<pid> process startup failure, trying to restart
...
Even after trying <n> time(s), <application path> process failed to start...no more retries

起動が失敗する原因の 1 つとして、依存関係のあるライブラリの読み込みに失敗していることが考えられます。obj.conf ファイル内で構成されている FastCGI アプリケーションへの app-env パラメータの値として、適切なライブラリパスを指定すれば、この問題を解決できます。次に例を示します。


Service fn="responder_fastcgi" app-path="/fastcgi/c/tux-app" bind-path="localhost:2112" 
app-env="LD_LIBRARY_PATH=/tuxedo/lib"

FastCGI アプリケーションの開発

FastCGI アプリケーションの開発は、Perl、PHP、C、および Java を使って行えます。次の各節では、広く普及しているいくつかのプログラミング言語を使ってアプリケーションを開発する手順について、簡単に説明します。

ProcedureFastCGI アプリケーションの実行

  1. Web Server を停止します。

  2. Web Server を再起動します。

  3. 「fcgi」をアプリケーションルートに持つアプリケーションにアクセスします。

    例: http://localhost/fcgi/ListDir.php

FastCGI アプリケーションの構造

典型的な FastCGI アプリケーションのコードは、次の構造を持ちます。

初期化コード

応答ループの開始
		応答ループの本体
応答ループの終了

初期化コードが実行されるのは、アプリケーションの初期化時に 1 回だけです。初期化コードは通常、データベースのオープンや、テーブルまたはビットマップの値の計算など、時間のかかる処理を実行します。CGI プログラムを FastCGI プログラムに変換する場合の主なタスクは、初期化コードと、要求ごとに実行する必要のあるコードとを分離することです。

応答ループは継続的に実行され、クライアント要求が到着するのを待ちます。このループはまず、FastCGI ライブラリのルーチン FCGI_Accept を呼び出します。FCGI_Accept ルーチンは、クライアントが FastCGI アプリケーションを要求するまで、プログラムの実行をブロックします。クライアント要求が到着すると、FCGI_Accept はブロックを解除し、応答ループの本体を 1 回実行したあと再度ブロックし、別のクライアント要求の到着を待ちます。このループが終了するのは、システム管理者または Web Server が FastCGI アプリケーションを終了した場合だけです。

Perl の使用

最新の FCGI モジュールを CPAN からダウンロードしてインストールします。ActivePerl については、http://aspn.activestate.com/ASPN/Downloads/ActivePerl/PPM/Zips からモジュールをダウンロードできます。

Perl を使って FastCGI アプリケーションを記述する方法の詳細については、http://www.fastcgi.com/devkit/fastcgi-prog-guide/ch3perl.htm#3659 を参照してください

PHP の使用

PHP 4.3.0 以降、FastCGI が PHP エンジンのサポートされた構成の 1 つになりました。PHP 4.3.x 以上のエンジンを FastCGI サポートを有効にしてコンパイルするには、次のように、構成スイッチ --enable-fastcgi をビルド処理の一部として含めます。


./configure <other-options> --enable-fastcgi
gmake

コンパイルが完了すると、php バイナリが FastCGI 対応になります。

PHP バージョン 5.1.2 以前 (PHP 4.x を含む) を使用する場合は、host:port 形式の bind-path を使って FastCGI プラグインを構成するようにしてください。たとえば、bind-path = “localhost:3333”のようにします。

PHP バージョン 5.1.3 以降の場合、bind-path は省略可能になります。指定する場合は、「host:port」形式を使用しないようにしてください。文字列で表します。たとえば、bind-path = “myphpbindpath”のようにします。

C/Java の使用

FastCGI 開発キットは、FastCGI C/Java アプリケーションを開発するための API を提供します。このキットは http://www.fastcgi.com/devkit/doc/fcgi-devel-kit.htm からダウンロードできます。

ダウンロードした FastCGI 開発キットをビルドするには、次の手順を実行します。

  1. tar ファイルを展開します。このアクションにより、fcgi-devel-kit という名前の新しいディレクトリが作成されます

  2. fcgi-devel-kit ディレクトリ内で次の一連のコマンドを実行します。

    1. ./configure

    2. make

C を使って FastCGI アプリケーションを記述する方法の詳細については、http://www.fastcgi.com/devkit/doc/fcgi-devel-kit.htm#S3 を参照してください

Java を使って FastCGI アプリケーションを記述する方法の詳細については、http://www.fastcgi.com/devkit/doc/fcgi-java.htm を参照してください

サンプル FastCGI アプリケーション

この節には、PHP、Perl、および C を使って記述されたサンプル FastCGI アプリケーションが含まれています。

PHP で記述されたレスポンダアプリケーション (ListDir.php)

<?php
 		$dir = "/tmp/";

		// ある既知のディレクトリを開き、続いてその内容を読み取ります
		if (is_dir($dir)) {
			if ($dh = opendir($dir)) {
 				while (($file = readdir($dh)) !== false) {
 					echo "filename: $file : filetype: " . filetype($dir . $file) . "\n";
 				}
				closedir($dh);
			}

		}
?>

この例に対する obj.conf の一部を次に示します。

<Object name="default">
		NameTrans fn="assign-name" from="/fcgi/*" name="responder.fcgi"
</Object>
<Object name="responder.fcgi">
		Service fn="responder-fastcgi" app-path="/foo/fastcgi-enabled-php-installation/bin/php" 
			bind-path="localhost:3431"  min-procs=3
</Object>

Perl で記述されたオーソライザアプリケーション (SimpleAuth.pl)

#!/usr/bin/perl

use FCGI;

while (FCGI::accept >= 0) {
		if( $ENV{'HTTP_AUTHORIZATION'} ) { 
        # この値をさらに復号化すれば、実際のユーザー名とパスワードが得られるので、
        # 何らかのユーザー検証を実行できます。このプログラムでは、この環境パラメータ
        # の存在チェックしか行っておらず、その値を実際に処理しているわけではありません

        print( "Status: 200\r\n" );
        print( "\r\n" );

    } else {
       
        print( "Status: 401\r\n" );
        print( "WWW-Authenticate: basic realm=\"foo\"\r\n" );
        print( "\r\n" );  

   }

}

この例に対する obj.conf の一部を次に示します。

<Object name="responder.fcgi">
		AuthTrans fn="auth-fastcgi" app-path="/fastcgi/apps/auth/SimpleAuth.pl" 
		bind-path="localhost:3432"
		Service fn="responder-fastcgi" app-path="/foo/fastcgi-enabled-php-installation/bin/php" 
		bind-path="localhost:3433" app-env="PHP_FCGI_CHILDREN=8" min-procs=1
</Object>

http://localhost/fcgi/php/ListDir.php への要求が初めて発生すると、ブラウザによって認証ダイアログボックスが表示されます。ユーザー名とパスワードの入力が完了すると、「/tmp」ディレクトリの内容が一覧表示されます。

C で記述されたフィルタアプリケーション (SimpleFilter.c)

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <fcgi_stdio.h>

		void main(void) {
			size_t PageSize = 1024 * 3;
    		char *page;
    		FCGX_Stream *in, *out, *err;
    		FCGX_ParamArray envp;

		 	int count=0;
    		page = (char *)malloc(PageSize);

		 	if (page == NULL) {

				printf("Content-type: text/x-server-parsed-html\r\n");
				printf("<title>malloc failure</title>");
				printf("<h1>Cannot allocate memory to run filter. exiting</h1>");
				printf("\r\n\r\n");
				exit(2);
			}

			while(FCGI_Accept() >= 0) {

         	char *tmp;
         	char *execcgi;      
         	char *dataLenStr = NULL;
         	int numchars = 0;
         	int stdinDataSize = 0;
         	int filterDataLen = 0;
         	int dataToBeRead = 0;
         	int x = 0;
         	int loopCount = 0;   
				

			  	count++;
         	dataLenStr = getenv("FCGI_DATA_LENGTH");
        
         	if(dataLenStr)
             	filterDataLen = atoi(dataLenStr);
   
				/* stdin のクリア */
         	while (EOF != getc(stdin)) {
             	stdinDataSize++;
         	}

				dataToBeRead = filterDataLen;
        	FCGI_StartFilterData();
        	tmp = page; /** fread や fwrite が我々のポインタを動かす場合にそなえて **/


				// 応答を開始します
				printf("Content-type: text/plain\r\n");
				printf("\r\n"); /** send a new line at the beginning **/
				printf("<title>SIMPLE FILTER</title>");
				printf(<h1>This page was Filtered by SimpleFilter FastCGI filter</h1>");
				printf("file size=%d<br>", filterDatalen);
				printf("stdin size=%d<br>, stdinDataSize);


				while(dataToBeRead > 0 ) {
           		x = 0;
           		page = tmp;
            
           		if(dataToBeRead > PageSize)
             		 x = PageSize;
           		else
              		 x = dataToBeRead;
					numchars = fread((void *)(page), 1, x, stdin);
				
					if( numchars == 0 )
						continue; 
					/** この時点で、データは page ポインタに格納されています。したがって、そのデータをサーバーに送り返す前に、そのデータに対して必要な操作をすべて行ってください。この例では、データ操作は一切行っていません。各ループの末尾でフィルタデータの読み取り回数と読み取り済み合計バイト数を出力しているだけです。**/	

					dataToBeRead -= numchars;
					loopCount++;
					printf("loop count = %d ... so far read %d bytes <br>", loopCount, 
					(filterDatalen - dataToBeRead));
				}
				printf("\r\n\r\n"); /** 転送終了時に改行を送信します **/

				fflush(stdout);

				page = tmp; /** ページポインタを復元します **/
				memset(page,NULL,numchars);
		}

		free(page);
}

この例に対する obj.conf の設定例を次に示します。

この FastCGI アプリケーションが、Web Server が稼働しているのと同じマシン上で利用可能になっている場合は、次のようにします。

<Object name=<"filter.fcgi">
						Service fn="filter-fastcgi" app-path="/fastcgi/apps/filter/SimpleFilter.exe" 
             bind-path="localhost:3434" app-env="LD_LIBRARY_PATH=/fastcgi/fcgi-2.4/libfcgi/.libs"
</Object>

このアプリケーションがリモートマシン上で実行されている場合には、obj.conf ファイル内に次のコード行を含める必要があります。

<Object name="filter.fcgi">
			Service fn="filter-fastcgi" bind-path="<remote-host>:<remote-port>"
</Object>

Web Server インスタンスのドキュメントルートディレクトリの下にある fcgi ディレクトリに格納されたサイズ「26868」バイトの「FilterThisFile」が、フィルタリング対象のファイルである場合、「http://localhost/fcgi/filter/FilterThisFile」への要求によって次の出力が生成されます。

This page was Filtered by SimpleFilter FastCGI filter

file size = 26868

stdin size = 0

loop count = 1... so far read 3072 bytes

loop count = 2... so far read 6144 bytes

loop count = 3... so far read 9216 bytes

loop count = 4... so far read 12288 bytes

loop count = 5... so far read 15360 bytes

loop count = 6... so far read 18432 bytes

loop count = 7... so far read 21504 bytes

loop count = 8... so far read 24576 bytes

loop count = 9... so far read 26868 bytes