test

Sun Java System Web Server 7.0 관리자 설명서

부록 B FastCGI 플러그인

개요

FastCGI는 외부 응용 프로그램과 Web Server 간의 표준 인터페이스로 사용되는 기존 CGI(Common Gateway Interface)를 향상시킨 것입니다. CGI와 마찬가지로 FastCGI 응용 프로그램은 별도의 격리된 프로세스에서 실행됩니다. FastCGI를 사용하는 경우의 장점은 다음과 같습니다.

FastCGI 플러그인을 사용하면 Web Server에서 안전하게, 확장 가능한 방식으로 흔히 사용되는 타사의 동적 컨텐트 생성 기술(Perl 및 Python 등)로 작업을 수행할 수 있습니다.

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는 서비스 함수입니다. 이 함수는 "응답기"로 사용되는 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는 서비스 함수입니다. 이 기능은 요청을 "필터" 유형의 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-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 매개 변수

SAF의 FastCGI 플러그인인 "auth-fastcgi", " responder-fastcgi" 및 "filter-fastcgi"는 따로 명시되지 않은 한 다음 매개 변수를 모두 허용합니다.

매개 변수 chroot, user, group 및 nice는 UNIX 플랫폼에서만 사용할 수 있습니다. Windows 플랫폼에서는 이런 매개 변수가 무시됩니다.

error-fastcgi SAF(Server Application Function)에는 다음과 같은 매개 변수를 사용할 수 있습니다.

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>
...

서로 다른 URL 패턴에 다른 개체를 정의하거나 SAF를 서로 다른 MIME 유형에 매핑하면 다양한 방법으로 FastCGI SAF를 호출할 수 있습니다.

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 < build info>

  2. obj.conf에서 요청 매핑이 정확하게 지정되었는지 확인합니다. obj.conf 파일에 대한 자세한 내용은 Sun Java System Web Server Administrator's Configuration Reference File을 참조하십시오.

  3. 오류 로그에 오류 메시지가 있는지 확인합니다.

  4. 스텁 바이너리와 FastCGI 응용 프로그램의 권한을 확인합니다. 충분한 권한이 지정되지 않은 경우에는 플러그인에서 스텁 또는 응용 프로그램 시작에 실패합니다.

  5. Fastcgistub.log 파일에서 스텁 부분의 오류가 있는지 확인합니다.

  6. 가능한 경우 FastCGI 응용 프로그램을 독립 실행형 모드로 실행하고 문제 없이 실행되는지 확인합니다.

라이브러리 종속성 오류가 발생한 경우에는 obj.conf에서 LD_LIBRARY_PATH를 LD_LIBRARY_PATH=<dependency library paths>인 app-env 매개 변수로 지정합니다.

문제: 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

시작 장애의 원인 중에는 종속성 라이브러리 로드 실패가 있을 수 있습니다. 이 문제는 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 응용 프로그램의 코드 구조는 다음과 같습니다. 

Initialization code

Start of response loop
		body of response loop
End of response loop

초기화 코드는 응용 프로그램을 초기화할 때 한 번만 실행됩니다. 초기화 코드는 보통 데이터베이스 열기 또는 테이블이나 비트맵의 값 계산과 같이 시간이 오래 걸리는 작업을 수행합니다. CGI 프로그램을 FastCGI 프로그램으로 변환할 때의 주된 작업은 초기화 코드를 각 요청에 대해 실행해야 할 코드와 분리하는 것입니다.

응답 루프는 계속 실행되며 클라이언트 요청이 도착하기를 기다립니다. 루프는 FastCGI 라이브러리에 있는 루틴인 FCGI_Accept에 대한 호출로 시작됩니다. FCGI_Accept 루틴은 클라이언트에서 FastCGI 응용 프로그램을 요청할 때까지 프로그램 실행을 차단합니다. 클라이언트 요청이 들어오면 FCGI_Accept 차단이 해제되고 응답 루프 본문이 한 번 실행된 후 다시 차단되어 다른 클라이언트 요청을 기다립니다. 루프는 시스템 관리자 또는 Web Server가 FastCGI 응용 프로그램을 종료한 경우에만 종료됩니다.

Perl 사용

CPAN에서 최신 FCGI를 다운로드하여 설치합니다. 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 엔진용으로 지원되는 구성이 되었습니다. FastCGI을 지원하는 PHP 4.3.x 이상의 엔진을 컴파일하려면 다음과 같이 작성 과정 중에 구성 스위치 --enable-fastcgi를 포함합니다.


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

컴파일이 끝나면 php 바이너리에 FastCGI를 사용할 수 있게 됩니다.

PHP 버전 5.1.2 이하(PHP 4.x 포함)를 사용하는 경우에는 FastCGI 플러그인을 바인드 경로와 함께 host:port 형식으로 구성해야 합니다. 예를 들면 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/";

		// Open a known directory, and proceed to read its contents
		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'} ) { 
        # This value can be further decoded to get the actual username and password and then
        # perform some kind of user validation. This program only checks for the presence of
        # of this environment param and is not really bothered about its value

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

   }

}
Example obj.conf settings for the above example:

위 예에 사용되는 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);
   
				/* clear out stdin */
         	while (EOF != getc(stdin)) {
             	stdinDataSize++;
         	}

				dataToBeRead = filterDataLen;
        	FCGI_StartFilterData();
        	tmp = page; /** just in case fread or fwrite moves our pointer **/


				//start responding
				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; 
					/** at this point your data is in page pointer, so do 
					whatever you want 
               with it before sending it back to the server.
					In this example, no data is manipulated. Only the count of number of 
               times the filter data is read and the total bytes read 
					at the end of every 
               loop is printed. **/	

					dataToBeRead -= numchars;
					loopCount++;
					printf("loop count = %d ... so far read %d bytes <br>", loopCount, 
					(filterDatalen - dataToBeRead));
				}
				printf("\r\n\r\n"); /** send a new line at the end of transfer **/

				fflush(stdout);

				page = tmp; /** restore page pointer **/
				memset(page,NULL,numchars);
		}

		free(page);
}

위 예에 사용되는 obj.conf 설정의 예.

Web Server를 실행하는 시스템과 같은 시스템에서 이 FastCGI 응용 프로그램을 사용할 수 있는 경우

<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 인스턴스의 docroot 디렉토리에 있는 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