Manager App HOW-TO

소개 Introduction

많은 제품 환경에서, 전체 컨테이너를 종료(shut down) 했다가 재시작(restart) 하지 않고도 새로운 웹 어플리케이션을 배치하거나 이미 설치된 것을 해체하는 기능이 있다면 매우 유용할 것입니다. 더우기, Tomcat 4 서버 환경설정 파일에 reloadable 로 설정되어 있지 않더라도 현재 실행중인 어플리케이션을 재시동하도록 요청할 수 있습니다.

이러한 기능을 지원하기 위해, Tomcat 4 는 다음 기능을 지원하는 웹 어플리케이션을 포함합니다 (기본적으로 /manager 컨텍스트 경로에 설치되어 있습니다.):

특정한 컨텍스트 경로에, 정해진 디렉토리 또는 WAR 파일 경로명으로부터 새로운 웹 어플리케이션 배치.

현재 배치된 웹 어플리케이션 목록과 각각의 웹 어플리케이션들의 살아있는 세션들 목록

운영중인 어플리케이션을 재적재(reload)함.

운영중인 어플리케이션 제거.

운영중인 어플리케이션 중지(사용할 수 없게함)하지만, 제거하지는 않음.

중지된 어플리케이션을 시작함 (다시 가용하게 함).

Manager 자신도 웹 어플리케이션이기 때문에, HTTP 요청과 응답을 사용해서 작동합니다. 그러나 "사용자 인터페이스"는 최소화했습니다. 왜냐하면 시스템 관리자만 접근하도록 의도되었기 때문입니다. 이러해서, 주소에 명령이 붙어서 전달됩니다. 결과 응답은 간단한 텍스트 형태로 되어있습니다. 파싱하고 처리하기 쉽기 때문이죠.

Tomcat 4 의 다음 버전들에서는 (적어도) 다음 형식의 관리기능이 추가될 것입니다:

웹 서비스로, Tomcat 관리가 원격 또는 자바가 아닌 관리환경으로 용이하게 통합될 것입니다.

좋은 사용자 인터페이스의 (웹 서비스 처리 계층의 상위에 지어지고) 웹 어플리케이션으로 웹 브라우저를 통해서 쉽게 Tomcat 관리를 할 수 있게 합니다.

관리자 어플리케이션 접근 설정하기 Configuring Manager Application Access

아래 설명에서 변수명 $CATALINA_HOME 은 Tomcat 4 가 설치된 디렉토리를 지칭하며 모든 상대경로들이 해석되는 기본 디렉토리입니다. 그러나, Tomcat 4 를 CATALINA_BASE 디렉토리를 설치해서 다중 인스턴스로 설정했다면, 이들 참고들을 위해 $CATALINA_HOME 대신에 $CATALINA_BASE 를 사용해야 합니다.

기본 설정에 인터넷으로 아무나 서버의 Manager 애플리케이션을 실행하도록 놔두는 것은 아주 위험한 일입니다. 그러므로, manager 권한을 갖고 있는 username 과 password 로 인증을 거쳐야 사용할 수 있도록 배포됩니다. 더우기, 이 역할을 지정하는 기본 users 파일($CATALINA_HOME/conf/tomcat-users.xml) 에는 username 이 없습니다. 그러므로, Manager 애플리케이션은 기본적으로 아주 사용할 수 없도록 되어있습니다.

Manager 웹 애플리케이션을 사용하려면, 새로운 username/password 를 만들어서 manager 역할(role)을 갖게 하거나, 이미 있는 username/password 에 manager 역할을 추가해줘야 합니다. 이것이 완벽하게 동작하기 위해서는 사용하고 있는 Realm 구현에 달려있습니다:
MemoryRealm - $CATALINA_HOME/conf/server.xml 에서 다른 파일을 지정하지 않았다면, Tomcat 4 는 기본적으로 $CATALINA_HOME/conf/tomcat-users.xml 를 불러옵니다. 이 파일은 아무 텍스트 편집기로 수정할 수 있습니다. 이 파일에는 각각의 사용자마다 <user> 가 있습니다. 아래처럼 보일 것입니다:
<user name="craigmcc" password="secret" roles="standard,manager" />
로그온 할 때 사용할 username 과 password, 그리고 관련된 role 을 설정합니다. 한명 이상의 기존의 사용자나 새로운 사용자를 만들어 쉼표(comma)로 구분된 roles 속성에 manager 역할을 추가할 수 있습니다.
JDBCRealm - 사용자와 역할 정보는 JDBC 를 통해서 접근되는 database에 저장되어있습니다. 환경에 맞는 표준 절차를 따라서, 기존의 사용자나 새로운 사용자를 만들어서 manager 역할을 추가해주십시오.

JNDIRealm - 사용자와 역할 정보는 LDAP 를 통해서 접근되는 디렉토리 서버에 저장되어있습니다. 환경에 맞는 표준 절차를 따라서, 기존의 사용자나 새로운 사용자를 만들어서 manager 역할을 추가해주십시오.
다음 섹션의 설명대로 Manager 를 실행해보려한다면 BASIC 인증을 통해서 로그온 해야됩니다. username 과 password 는 manager 역할을 갖고 있는 사용자 database의 유효한 사용자라는 것을 인증하기만하면 됩니다.

지원되는 Manager 명령어 Supported Manager Commands

Manager 애플리케이션이 처리를 어떻게 할 지 알려주는 명령어들은 다음과 같이 요청 URI로 지정합니다:
http://{host}:{port}/manager/{command}?{parameters}
여기서 {host} 와 {port} 는 Tomcat 이 사용하는 호스트명과 포트번호를 뜻하고, {command} 는 실행하려고 하는 Manager 명령어를 나타내고, {parameters} 는 명령어에 해당하는 질의 파라메터를 나타냅니다. 아래의 예시에서 호스트와 포트를 각자의 환경에 적절하게 바꿔보십시오.

대부분의 명령어는 하나 이상의 다음 질의 파라메터를 필요로 합니다:

path - 처리하려는 웹 애플리케이션의 컨텍스트 경로 (맨 앞에 / 를 포함). ROOT 웹 애플리케이션을 선택하려면 아무것도 지정하 지 않아야합니다. NOTE - Manager 애플리케이션 자체에는 아무런 관리 명령어도 실행할 수 없습니다.

war - 웹 애플리케이션 압축(WAR) 파일이나 웹 애플리케이션이 있는 디렉토리의 경로명의 URL. URL 은 다음 형식 중에서 아무 것이나 사용 하면 됩니다:

file:/absolute/path/to/a/directory - 웹 애플리케이션의 압축이 풀린 버전을 갖고 있는 디렉토리의 절대경로. 별다른 변경이 없다면 이 디렉토리는 컨텍스트 경로에 붙게 됩니다.

jar:file:/absolute/path/to/a/warfile.war!/ - 로컬 웹 애플리케이션 압축(WAR) 파일의 URL. 전체 JAR 파일의 참조를 위한 JarURLConnection 클래스에 유효한 어떤 문법을 사용해도 무방합니다.

jar:http://hostname:port/path/to/a/warfile.war!/ - 원격 JAR 파일로 부터 웹 애플리케이션을 배치할 수 있습니다. 전체 JAR 파일의 참조를 위한 JarURLConnection 클래스에 유효한 어떤 문법을 사용해도 무방합니다.

각각의 명령은 text/plain 형식의 응답을 반환합니다.(즉, HTML 태그가 없는 plain ASCII로 사람이나 프로그램이나 모두 읽기 손쉬운 형태). 첫줄은 명령어 실행이 성공인지 아닌지를 뜻하는 OK 이나 FAIL 중에 하나로 시작합니다. 실패했을 경우, 다음 줄 부터 무엇이 문제였는지 설명이 나옵니다. 어떤 명령어들은 아래와 같은 추가정보를 포함합니다.

국제화 Note - Manager 애플리케이션은 자원 번들에 있는 메시지 문자열을 찾습니다. 때문에 문자열을 각각의 플랫폼에 따라 번역을 해도 됩니다. 아래 예제는 영어버전의 메시지들입니다.
새 애플리케이션 배치하기 Deploy A New Application
http://localhost:8080/manager/install?path=/foo&war=file:/path/to/foo

http://localhost:8080/manager/install?path=/bar&war=jar:file:/path/to/bar.war!/
(다른 웹 애플리케이션이 사용하지 않는) 지정된 컨텍스트 경로에 새로운 웹 애플리케이션을 설치하고 시작합니다. war 파라메터는 디렉토리나 웹 애플리케이션 압축(WAR) 파일에대한 URL 을 지정합니다. (file: 를 포함합니다.) WAR 파일을 지칭하는 URL에서 사용할 문법은 java.net.JarURLConnection 클래스에 대한 Javadocs 문서에 설명되어 있습니다. 전체 WAR 파일을 지칭하는 URL을 사용하십시오.

설치와 시작이 성공적이었다면, 다음과 같은 응답을 받을 겁니다:
OK - Installed application at context path /foo
그렇지 않을 경우, 에러메시지를 갖고 있는 응답은 FAIL로 시작합니다. 문제의 발생할 수 있는 원인은 다음과 같습니다:

Application already exists at path /foo

현재 실행되고 있는 웹 애플리케이션들의 컨텍스트 경로는 유일해야 합니다. 그러므로, 같은 컨텍스트 경로를 가진 기존의 웹 애플리케이션을 먼저 해체하거나, 새로운 웹 애플리케이션의 컨텍스트 경로를 다른 이름으로 해야합니다.

Document base does not exist or is not a readable directory

war 파라메터로 지정한 URL과 이 서버에 있는 디렉토리에 "압축풀린" 버전의 웹 애플리케이션이 있는지 또는 웹 애플리케이션 압축(WAR) 파일의 절대경로 URL 이 맞는지 확인해야합니다. war 파라메터의 값을 올바로 수정해주십시오.

Encountered exception

새로운 웹 애플리케이션을 시작할 때 예외가 발생했습니다. 자세한 내용은 Tomcat 4 의 logs 를 확인해야합니다. 하지만, 적당한 해법은 /WEB-INF/web.xml 파일을 파싱하거나 애플리케이션 이벤트 리스너와 필터를 초기화할 때 클래스가 빠져있는 문제들을 포함합니다.

Invalid application URL was specified

URL의 지정한 디렉토리나 웹 애플리케이션이 유효하지 않습니다. 그런 경우 URL은 file:로 시작해야하고 WAR 파일에 대한 URL 은 ".war" 로 끝나야합니다.

Invalid context path was specified

ROOT 일 경우를 제외하고, 컨텍스트 경로는 슬래시 문자로 시작해야 합니다. -- ROOT 일 경우는 아무 문자열도 사용하지 않습니다.

No context path was specified
path 파라미터가 필요합니다.
현재 배치된 애플리케이션 목록 List Currently Deployed Applications
http://localhost:8080/manager/list
모든 배치된 웹 애플리케이션들의 컨텍스트 경로, 현재 상태(running 또는 stopped), 살아있는 세션 수들을 목록으로 보여줍니다. Tomcat 시동 후에 즉시 보여지는 전형적인 응답은 다음과 같습니다:
OK - Listed applications for virtual host localhost
/webdav:running:0
/examples:running:0
/manager:running:0
/:running:0
기존 애플리케이션 재적재하기 Reload An Existing Application
http://localhost:8080/manager/reload?path=/examples
기존 애플리케이션을 셧다운하거나 재시동하도록 신호를 보냅니다. 두 가지 경우에 유용한데, 첫째는 $CATALINA_HOME/conf/server.xml 에서 <Context> 항목에 reloadable="true" 속성으로 되있지 않은 애플리케이션의 재컴파일된 클래스들이 있을 경우와 두번째는 Tomcat 에 의해 자동으로 인식되지 않는(conf/web.xml 내용 변경과 같은) 다른 변경사항이 있을 경우입니다.

이 명령이 성공하면, 다음과 같은 응답을 받습니다:
OK - Reloaded application at context path /examples
그렇지 않을 경우, 에러메시지를 갖고 있는 응답은 FAIL로 시작합니다. 문제의 발생할 수 있는 원인은 다음과 같습니다:

Encountered exception

웹 애플리케이션을 재시작하려고 할 때 예외가 발생했습니다. 자세한 내용은 Tomcat 4 의 logs 를 확인해보세요.

Invalid context path was specified

ROOT 일 경우를 제외하고, 컨텍스트 경로는 슬래시 문자로 시작해야 합니다. -- ROOT 일 경우는 아무 문자열도 사용하지 않습니다.

No context exists for path /foo

지정한 컨텍스트 경로로 배치되어 있는 것이 없습니다.

No context path was specified
path 파라메터가 필요합니다.
세션 통계 Session Statistics
http://localhost:8080/manager/sessions?path=/examples
웹 애플리케이션의 기본 세션 종료시간과 현재 살아있는 세션 수(종료시간 10분 내의)를 표시합니다. 예를 들어, Tomcat 을 재시작한 후, /examples 웹 애플리케이션에 있는 JSP 예제 하나를 실행했다면 다음과 같이 나옵니다:
OK - Session information for application at context path /examples
Default maximum session inactive interval 30 minutes
30 - <40 minutes:1 sessions
기존 애플리케이션 시작하기 Start an Existing Application
http://localhost:8080/manager/start?path=/examples
중지된 애플리케이션을 재시작하도록 합니다. 예를 들어, 데이터베이스가 애플리케이션에 의해 임시로 사용할 수 없을 때 중지하고 시작하는 것은 유용합니다. 사용자가 계속 데이터베이스 예외를 보도록 방치하는 것 보다는 이 데이터베이스를 사용하는 웹 애플리케이션을 중지하는게 낫습니다.

이 명령이 성공하면, 다음과 같은 응답을 받습니다:
OK - Started application at context path /examples
그렇지 않을 경우, 에러메시지를 갖고 있는 응답은 FAIL로 시작합니다. 문제의 발생할 수 있는 원인은 다음과 같습니다:

Encountered exception

웹 애플리케이션을 시작하려고 할 때 예외가 발생했습니다. 자세한 내용은 Tomcat 4 의 logs 를 확인해보세요.

Invalid context path was specified

ROOT 일 경우를 제외하고, 컨텍스트 경로는 슬래시 문자로 시작해야 합니다. -- ROOT 일 경우는 아무 문자열도 사용하지 않습니다.

No context exists for path /foo

지정한 컨텍스트 경로로 배치되어 있는 것이 없습니다.

No context path was specified
path 파라메터가 필요합니다.
기존 애플리케이션 중지하기 Stop an Existing Application
http://localhost:8080/manager/stop?path=/examples
기존 애플리케이션을 사용할 수 없도록 합니다만 배치된 상태로 놔둡니다. 애플리케이션이 중지된 상태에서는 어떤 요청도 HTTP error 404 를 보게됩니다. 그리고, 애플리케이션 목록 명령에서는 "stopped" 로 표시됩니다.

이 명령이 성공하면, 다음과 같은 응답을 받습니다:
OK - Stopped application at context path /examples
그렇지 않을 경우, 에러메시지를 갖고 있는 응답은 FAIL로 시작합니다. 문제의 발생할 수 있는 원인은 다음과 같습니다:

Encountered exception

웹 애플리케이션을 중지하려고 할 때 예외가 발생했습니다. 자세한 내용은 Tomcat 4 의 logs 를 확인해보세요.

Invalid context path was specified

ROOT 일 경우를 제외하고, 컨텍스트 경로는 슬래시 문자로 시작해야 합니다. -- ROOT 일 경우는 아무 문자열도 사용하지 않습니다.

No context exists for path /foo

지정한 컨텍스트 경로로 배치되어 있는 것이 없습니다.

No context path was specified
path 파라메터가 필요합니다.
기존 애플리케이션 해체하기 Undeploy an Existing Application
http://localhost:8080/manager/remove?path=/examples
기존 애플리케이션을 탈없이 종료하고, Tomcat 에서 제거합니다(나중에 이 컨텍스트 경로를 다시 사용할 수 있게됩니다).

이 명령이 성공하면, 다음과 같은 응답을 받습니다:
OK - Removed application at context path /examples
그렇지 않을 경우, 에러메시지를 갖고 있는 응답은 FAIL로 시작합니다. 문제의 발생할 수 있는 원인은 다음과 같습니다:

Encountered exception

웹 애플리케이션을 중지하려고 할 때 예외가 발생했습니다. 자세한 내용은 Tomcat 4 의 logs 를 확인해보세요.

Invalid context path was specified

ROOT 일 경우를 제외하고, 컨텍스트 경로는 슬래시 문자로 시작해야 합니다. -- ROOT 일 경우는 아무 문자열도 사용하지 않습니다.

No context exists for path /foo

지정한 컨텍스트 경로로 배치되어 있는 것이 없습니다.

No context path was specified
path 파라메터가 필요합니다.
원본:http://jakarta.apache.org/tomcat/tomcat-4.0-doc/manager-howto.html