IIS HowTo

Apache Software Foundation | Jakarta Project | Apache Tomcat

이것는 IIS와 톰캣을 함께 작동하도록 설정하는 방법을 설명하는 문서입니다.

보통의 IIS는 서블릿과 자바 서버 페이지 (JSP)를 실행할 수 없습니다, IIS에 JK ISAPI redirector 플러그인을 사용/설정하여, IIS가 서블릿과 JSP 요청을 톰캣에 보내도록 할 것입니다 (그리고 이 방법은, 클라이언트에도 요청을 보냅니다).

웹서버와 톰캣 엔진간의 작동하도록 하는 설정법을 배우기위하여 Workers HowTo 문서도 읽기를 권장합니다.

가정의 협의 문서

${tomcat_home} 는 톰캣의 루트 디렉토리입니다. 톰캣이 설치되면 다음의 하위디렉토리가 생깁니다.

${tomcat_home}\conf - 여러가지의 설정 파일을 넣는 장소
${tomcat_home}\webapps - 예제 애플리케이션이 있습니다
${tomcat_home}\bin - 웹 서버의 플러그인을 넣는 장소

이 문서에서 모든 예시문은 ${tomcat_home} 를 c:\jakarta-tomcat 로 표기합니다. worker는 IIS 서버로부터 일거리를 받는 톰캣의 처리를 정의합니다.

지원되는 설정

IIS-Tomcat redirector 는 다음 환경에서 개발되고 테스트되었습니다:

WinNT4.0-i386 SP4/SP5/SP6a (다른 서비스팩에서도 작동할 것입니다), Win2K 와 WinXP 와 Win98
IIS4.0 와 PWS4.0
Tomcat 3.2.x, Tomcat 3.3.x, Tomcat 4.0.x, Tomcat 4.1.x 와 Tomcat 5

redirector 는 ajp12 와 ajp13 을 사용하여 요청을 톰캣 컨테이너에 보냅니다. 또한 추가적으로 톰캣의 내부 처리과정를 사용하고 싶다면, in process howto 의 in-process mode 에 관하여 알아보세요.

누가 ajp 프로토콜을 지원하나요?

ajp12 프로토콜은 톰캣 3.2.x 와 3.3.x 만 이용가능합니다.

톰캣 3.3.x 는 ajp12 와 사용하는 것을 비추천하고, 대신 톰캣 Tomcat 4.0.x, 4.1.x 와 5 에 의해 알려진 ajp 프로토콜 ajp13 을 사용하시기 바랍니다.

물론 톰캣 3.2.x 와 3.3.x 또한 ajp13 프로토콜을 지원합니다.

jetty 같은 다른 서블릿 엔진도 ajp13 프로토콜을 지원합니다.

어떻게 작동하나요?

IIS-Tomcat redirector 는, IIS 가 redirector 플러그인을 읽어드리고 각각의 들어오는 요청을 필터 기능에 호출하도록하는, IIS 플러그인 (필터 + 확장기능)입니다.
필터는 uriworkermap.properties 안의 URI-경로 목록에 대하여 요청 URL을 테스트하고, 현재 요청이 URI-경로 목록에 속하는 하나와 일치한다면, 필터는 요청을 확장기능에 보냅니다.
확장기능은 요청 파라미터(parameter)을 모으고, ajp13 같은 정의된 프로토콜을 사용하고 있는 적합한 worker 에 그것을 보냅니다.
확장기능은 worker 의 응답을 모아, 그것을 브라우저에게 보냅니다.

설치하기

ISAPI redirector 서버 플러그인의 미리 빌드된 버전인, isapi_redirect.

l 은 jakarta-tomcat-connectors 제품의 win32/i386 디렉토리에 있습니다. 브라우저로 넷스케이프를 사용한다면, 되도록이면 zip 버전의 파일을 내려받기 하시기 바랍니다. 넷스케이프는 DLL 파일을 내려받기하는데 문제가 발생할 수 있습니다. 또한, jakarta-tomcat-connectors 제품의 소스로부터 자체적으로 카피하여 빌드할 수도 있습니다. 톰캣 redirector 는 3가지가 필요합니다.

isapi_redirect.dll - IIS 서버 플러그인, 미리 빌드된 DLL 이나 자체적으로 빌드한 것이 필요합니다 (빌드 부분을 보세요).
workers.properties - worker(톰캣 처리과정) 에 사용되는 host 나 port 를 표현한 파일입니다. conf 디렉토리에 workers.properties 샘플이 있습니다.
uriworkermap.properties - workers에 URL-경로 패턴을 표기하는 파일입니다. 마찬가지로 conf 디렉토리에 uriworkermap.properties 샘플이 있습니다.

설치하기는 아래 내용을 가지고 있습니다..

기본/예제 컨텍스트(context)으로 ISAPI redirector 를 설정하고, IIS로 서블릿을 보낼 수 있는지 체크합니다.
설정에 더 많은 컨텍스트을 추가합니다.

ISAPI Redirector 를 설정하기

이 문서는 isapi_redirect.dll 이 c:\jakarta-tomcat\bin\win32\i386\isapi_redirect.dll 에 있다고 가정하고, c:\jakarta-tomcat\conf 에 프로퍼티 파일들을 작성하였습니다.

레지스트리에서, "HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Jakarta Isapi Redirector\1.0" 라 명명된 새로운 레지스트리 키를 생성합니다.
extension_uri 이름의 문자열 값을 추가하고, 값 데이터에 /jakarta/isapi_redirect.dll 를 넣습니다.
log_file 이름의 문자열 값을 추가하고, 값 데이터에 로그 파일이 생성될 곳을 넣습니다 (예를 들면, c:\jakarta-tomcat\logs\isapi.log ).
log_level 이름의 문자열 값을 추가하고, 값 데이터에 로그 등급을 넣습니다 (debug, info, error 또는 emerg 가 될 수 있습니다).
worker_file 이름의 문자열 값을 추가하고, 값 데이터에 workers.properties 파일의 전체 경로를 넣습니다 (예를 들면, c:\jakarta-tomcat\conf\workers.properties )
worker_mount_file 이름의 문자열 값을 추가하고, 값 데이터에 uriworkermap.properties 파일의 전체 경로를 넣습니다 (예를 들면, c:\jakarta-tomcat\conf\uriworkermap.properties )
인터넷서비스관리자 콘솔을 사용하여, IIS/PWS 웹 사이트에 새로운 가상 디렉토리를 추가합니다. 가상 디렉토리의 이름은 꼭 jakarta 로 하고, 컨텐트가 있는 경로는 isapi_redirect.dll 이 있는 디렉토리로 하세요 (예를 들면, c:\jakarta-tomcat\bin\win32\i386). 이 새로운 가상 디렉토리에 실행 액세스 권한을 부여하시기 바랍니다.
인터넷서비스관리자 콘솔을 사용하여, IIS/PWS 웹 사이트에 isapi_redirect.dll 같은 필터를 추가합니다. 필터 이름은 그것의 임무를 반영하는 것(전 jakarta 라고 지었습니다)으로 하시고, 실행파일은 반드시 c:\jakarta-tomcat\bin\win32\i386\isapi_redirect.dll 로 하셔야 합니다. PWS에서는, regedit를 사용하여 HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\W3SVC\Parameters 아래의 "Filter DLLs" 키를 추가/수정할 필요가 있습니다. 이 키는 "," 로 구분지어진 dll들의 목록입니다 ( 전체 경로 ) - isapi_reeidrect.dll 의 전체 경로를 넣어야 합니다.
IIS 서비스재시작하고 (IIS 서비스에서 중지 + 시작), jakarta 필터가 녹색의 상향 화살표로 변했는지 확인하시기 바랍니다. Win98이라면 cd WINDOWS\SYSTEM\inetsrv 하고 PWS /stop 을 쳐야 합니다. ( DLL 과 로그 파일은 잠겨졌습니다 - 중지 버튼을 클릭한다해도, PWS는 메모리에 여전히 DLL들를 유지하고 있을 겁니다. ). 다시 start 라고 pws를 치시기 바랍니다.

이게 다입니다. 지금 톰캣을 시작하고, IIS에 /examples 콘텍스트를 물어보세요. 예제와 약간의 JSP 예제들을 실행하기 위해 http://localhost/examples/jsp/index.html 를 시도하세요.

성공적으로 작동하지 않는다면, 문제에 대해 정확하게 도와주는 아래의 문제해결 부분을 참조하시기 바랍니다.

추가적인 컨텍스트 추가하기

예제 컨텍스트는 설치된 것을 확인하는데 유용합니다. 하지만 자신의 컨텍스트를 추가할 필요가 있습니다. 추가되는 새로운 컨텍스트는 두개의 체제가 필요합니다:

컨텍스트를 톰캣에 추가합니다 (이것에 관하여 언급하지 않겠습니다).
컨텍스트를 ISAPI redirector에 추가합니다.

ISAPI redirector에 컨텍스트를 추가하는 것은 간단합니다, uriworkermap.properties를 수정하고 다음에 보이는 것처럼 줄을 추가하는 것이 전부입니다.

 /context/*=worker_name

Woker들과 그것들의 이름은 workers.properties에 정의되어 있습니다. 디폴트의 workers.properties 는 "defworker" 라는 이름의 worker 하나로 미리 설정되어 있고 그것을 사용할 수 있습니다. 예를 들어, "shop" 이라는 이름의 컨텍스트를 추가하고 싶다면, uriworkermap.properties에 다음과 같은 줄을 추가하면 됩니다:

 /shop/*=defworker

톰캣 3.2까지의 uriworkermap.properties-auto는 톰캣이 매번 시작할 때마다 자동적으로 적용되는 기능이었습니다. 이 파일은 톰캣이 돌아가는 동안에도 각각의 컨텍스트들의 설정이 적용됩니다.

각각의 컨텍스트는 톰캣이 취급하는 서블릿과 JSP 요청의 설정사항을 가지고 있습니다만, IIS가 서비스하는 기본의 정적인 내용은 없어집니다.

각각의 컨텍스트는, 또한 톰캣이 컨텍스트에 모든 요청을 처리하도록 설정을 기록합니다. 이 파일은 이름바꾸기를 할 수 있고(그래서 다음번 톰캣이 시작될 때 덮어쓰기되지 않도록), 이 설정을 기록하지 못하도록 하거나, 다른 방법으로는 사용자에 맞게 만들수도 있습니다.

또한 이 파일을 worker_mount_file 설정처럼 사용할 수 있습니다.

고급적인 컨텍스트 설정

가끔, 톰캣에 의해 서비스되는 내용의 파일이라고 해도, 정적인 페이지 (html, gif, jpeg etc.)는 IIS가 서비스하는게 더 좋습니다.

예를 들어, 톰캣으로 서비스하는 것이 필요없고 IIS로 충분한, examples 컨텍스트의 html 과 gif 파일들을 생각해 봅시다.

톰캣의 정적인 파일 부분을 IIS가 서비스하도록 만드는 컨텍스트는 아래사항을 요구합니다.

톰캣 컨텍스트를 파악하도록, IIS를 설정합니다.
IIS를 위해, 정적인 파일들을 떼어내도록 redirector를 설정합니다.

IIS가 톰캣 컨텍스트를 취급하는 새로운 IIS 가상 디렉토리의 추가를 요구하도록, 톰캣에 컨텍스트를 추가합니다. 예를 들면, c:\jakarta-tomcat\webapps\examples 디렉토리를 취급하는 IIS 가상 디렉토리 /example 을 추가합니다.

톰캣이 처리하길 원하는 정확한 URL-경로를 지정하려면, redirector를 좀 더 복잡하게 설정해야 합니다 (보통 JSP 파일이나 servlets). 이것은 uriworkermap.properties의 수정을 요구합니다.

For the examples context it requires to replace the following line
examples 컨텍스트는 다음 줄로 교체되는 것이 요구됩니다.

/examples/*=defworker

with the following two lines
다음 두 줄도 포함

/examples/*.jsp=defworker

 /examples/servlet/*=defworker

위에 보이는 두번째 설정은 좀 더 구체적입니다. 이것은, /examples/servlet/ 아래의 자료와 /examples/ 아래의 .jsp 로 끝나는 이름의 자료의 요청만을 redirector 로 연결하도록 지시합니다. 이것은, 각각의 컨텍스트에서uriworkermap.properties-auto 파일이 자동적으로 작성되는 것과 유사합니다.

좀 더 구체적으로 하려면 다음과 같은 줄을 제공하시기 바랍니다:

 /example/servletname=defworker

/example/servletname 와 같은 URL-경로의 요청을, defworker 란 이름의 worker로 연결하도록 redirector를 지시합니다.

WEB-INF 디렉토리 보호하기

각각의 서블릿 애플리케이션(컨텍스트)은 WEB-INF란 이름의 특별한 디렉토리를 가지고 있습니다, 이 디렉터리는 예민한 설정 데이터와, 자바 클래스들과, 웹 사용자로부터 꼭 숨겨져야하는 것들을 포함하고 있습니다. 인터넷서비스관리자 콘솔을 사용하면, 사용자의 접근으로부터 WEB-INF 디렉토리를 보호하는 것이 가능합니다, 이것은 하지만 관리자가 그것을 기억하는 것을 요구합니다.

이 방법 말고는, URL-경로에 WEB-INF를 포함한 요청을 거절하는 것에 의한, WEB-INF 디렉토리를 자동적으로 보호하는 redirector 플러그인이 필요합니다.

고급적인 Worker 설정

가끔, 다른 톰캣 처리과정에 다른 컨텍스트를 서비스하기를 원할 것입니다 (예를 들어, 다른 장비 사이에서 읽어드리기). 이러한 것을 얻기 위해, 여러 개의 worker를 정의하고, 자신의 worker로 각각의 컨텍스트를 할당하는 것이 필요할 것입니다.

worker의 정의는 workers.proerties에서 이루어집니다. 이 파일은 두가지 형태를 가지고 있습니다.

정의된 모든 worker 목록을 넣습니다.

 worker.list=worker1, worker2

이 worker에 적합한 host 와 port 를 정의하는 것을 넣습니다.

 worker.worker1.host=localhost

worker.worker1.port=8009
worker.worker1.type=ajp13

 worker.worker2.host=otherhost

worker.worker2.port=8009
worker.worker2.type=ajp13

위는 두 개의 worker를 정의하는 예제입니다, 지금 우리는 이 worker를, 자신의 worker로 두 개의 각각 다른 컨텍스트를 서비스하도록 사용할수 있습니다.

uriworkermap.properties 예제의 부분

/examples/*=worker1
/webpages/*=worker2

webpages 컨텍스트가 worker2 에 의해 서비스되는 동안, examples 컨텍스트는 worker1 에 의해 서비스되는 것을 보실 수 있습니다.

worker를 사용하고 설정하는 것에 관한 더 많은 정보는 Workers HowTO에 있습니다.

ISAPI redirector 빌드하기

redirector는 비주얼 C++ 버전.6.0을 사용하여 개발되었습니다, 따라서 개인적으로 빌드를 수행하기를 원한다면 이 환경이 미리 준비되어 있어야 합니다. 또한, IIS 개발자 SDK를 가지고 다음 과정을 거쳐야 합니다.

isapi 플러그인 소스 디렉토리로 디렉토리를 변경합니다.
MSDEV로 소스를 Make 합니다.

Change directory to the isapi plugins source directory

  c:\> cd 
              c:\home\apache\jk\isapi

Build the sources using MSDEV

  c:\> MSDEV 
              isapi.dsp /MAKE ALL

msdev 가 패스(path)에 없다면, msdev.exe 의 전체 경로를 넣으세요. 이것은, redirector 플러그인의 배포버전과 디버그 버전을 둘 다 빌드하는 것입니다. 둘 중 하나는 msdev안에서 isapi 작업공간(workspace) 파일을 열고, 빌드 메뉴를 사용하여 그것을 빌드할 것입니다.

문제해결

ISAPI redirector를 인스톨하고 첫번째 시도 했을 때 작동하기란 쉽지 않습니다.

문제가 발생했다면, 여기 문제를 바로잡는 다음의 단계가 있습니다.

이 단계은 모든 가능한 문제를 다루고 있지 않습니다, 하지만 전형적인 실수를 찾는 것을 도와줄 것입니다.

이 단계 중에 어떤 수정할 것을 발견했다면, 위에서 서술된 설치하기의 마지막 단계처럼 IIS 서비스를 재시작하시기 바랍니다.

에러 분석에서는, 웹 사이트 활동이 로그기록 남는지 확인하시기 바랍니다. PWS 4.0 은 퍼스널 웹 관리자의 고급 옵션의 "Save Web Site Activity Log" 가 체크되어 있는지 확인하시기 바랍니다.

주의: 이 단계는 worker_mount_file 설정을 uriworkermap.properties 파일의 수정되지 않은 복사본에 넣었다고 가정하였습니다.
worker_mount_file 을 수정된 uriworkermap.properties 나 uriworkermap.properties-auto 파일에 넣는다면, 결과가 불분명할 것입니다.
이것은 또한 톰캣에 바로 접근한다면, "/examples" 컨텍스트는 정확하게 작동한다고 가정하였습니다.

Win98

IIS 서비스와 톰캣를 시작합니다.

log_file 설정에서 지정된 ISAPI redirector 로그 파일이 존재하는지 점검합니다. 만약에 없다면, 다음을 확인하세요:

"HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\W3SVC\Parameters" 키의 "Filter DLLs" 설정사항을 점검하고, 경로가 정확한지 점검합니다.
"HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Jakarta Isapi Redirector\1.0" 키의 철자를 점검합니다. 중요하지 않은 것 같지만, 부정확한 철자는 레지스트리 설정에서 isapi_redirect.dll 를 찾는 것을 방해합니다.
log_file 설정을 형태(typos), 이름과 데이터면에서 점검합니다. 또한 벌써 존재하는 곳에 로그 파일이 나타나는지 디렉토리를 점검합니다.

브라우저에 http://localhost/examples/jsp/index.html URL을 실행시켜 주세요. 케이스는 톰캣에서 중요합니다. URL의 "localhost" 를 따르는 문자는 케이스를 더 좁게 합니다. 페이지가 나타나지 않으면, IIS 서비스를 멈춥니다 (IIS 로그 파일 보려면 필요함). 그후, SYSTEM/LogFiles/W3SVC1 의 IIS 로그 파일을 찾아서 마지막 줄을 확인해 보세요 :

마지막 줄이 다음을 포함한다면:

 GET 
              "/examples/jsp/index.html HTTP/1.1" 404

"/examples" 컨텍스트의 요청을 처리해야 하는 것을, ISAPI redirector는 분간할 수 없었습니다. 다음을 점검해보세요:

extension_rui 명을 형태(typos)면에서 점검합니다.
worker_file 설정을 형태, 이름과 데이터면에서 점검합니다.
worker_mount_file 설정의 형태, 이름과 데이터를 점검합니다.

마지막 줄이 이와 같은 것을 포함한다면:

 GET 
              "/jakarta/isapi_redirect.dll HTTP1.1"

요청을 처리하는 것을, ISAPI redirector는 분간할 수 있습니다. 그러나 요청을 톰캣이 서비스하도록 하는 것이 성공한 것은 아닙니다.

다음의 GET "/..." HTTP 에러 코드를 점검합니다:

Error 404

GET "/..." 404

URL 을 정확하게 넣었는지 확인합니다.
가상 디렉토리가 "jakarta"란 이름으로 생성되었는지 확인합니다. 이것은, "/jakarta"처럼 퍼스널 웹 관리자에서 보여져야 합니다 (quotes 없이).
extension_uri 데이터가 "/jakarta/"로 시작하는지 확인합니다 (quotes 없이).

Error 500

GET "/..." 500

extension_uri 설정의 "/jakarta/" 뒤에 "isapi_redirect.dll" 이 있는지 확인합니다.
workers.properties 파일을 점검하고, server.xml의 "Apache AJP12 support"에 지정된 port가 worker.ajp12.port와 똑같은지 port 설정을 확인합니다.

Error 200 or 403

GET "/..." 200
GET "/..." 403

jakarta 가상 디렉토리의 퍼스널 웹 관리자의 고급 옵션에서 실행 액세스권한이 있는지 확인합니다.

위의 설정이 올바르다면, 브라우저에 index.html 페이지가 나타날 것입니다. 또한 Execute 링크를 클릭하여 JSP 예제를 실행할 수 있을 것입니다.

WinNT/Win2K/WinXP

World Wide Web Publishing Service 와 톰캣을 시작합니다.

log_file 설정에서 지정된 ISAPI redirector 로그 파일이 존재하는지 점검합니다. 만약에 없다면, 다음을 확인하세요:

인터넷서비스관리자 콘솔에서 필터를 "실행"으로 설정하였는지 점검하고 경로가 올바른지 확인합니다.
"HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Jakarta Isapi Redirector\1.0" 키의 철자를 점검합니다. 중요하지 않은 것 같지만, 부정확한 철자는 레지스트리 설정에서 isapi_redirect.dll 를 찾는 것을 방해합니다.
log_file 설정을 형태(typos), 이름과 데이터면에서 점검합니다. 또한 벌써 존재하는 곳에 로그 파일이 나타나는지 디렉토리를 점검합니다.

추가된 jakarta 필터를 점검하고 그것의 상태가 녹색의 상향 화살표로 보이는지 확인합니다. 만약 그렇지 않다면, 다음 내용을 점검해보세요.

worker_file 설정을 형태, 이름과 데이터면에서 점검합니다.
worker_mount_file 설정의 형태, 이름과 데이터를 점검합니다.

브라우저에 http://localhost/examples/jsp/index.html URL을 실행시켜 주세요. 케이스는 톰캣에서 중요합니다. URL의 "localhost" 를 따르는 문자는 케이스를 더 좁게 합니다. 페이지가 나타나지 않으면, SYSTEM/LogFiles/W3SVC1 의 IIS 서버 로그 파일을 찾아서 마지막 줄을 확인해 보세요.

마지막 줄에: GET "/jakarta/isapi_redirect.dll HTTP1.1" 같은 것이 포함되어 있다면, 요청을 처리하는 것을, ISAPI redirector는 분간할 수 있습니다.