Tomcat Web 애플리케이션 보호

tomcat을 사용하여 WAR 파일을 자체 포함형 Tomcat base 형태로 변환합니다. 실행 시 인코더에 내장된 Tomcat 구성 요소가 사용되므로 사용자의 로컬에 설치된 Tomcat을 읽어들이지 않습니다.

1. GUI 기반 작업

애플리케이션 유형 페이지에서 Tomcat WAR를 선택합니다.
입력할 WAR 파일, 포함된 Java 버전 및 대상 플랫폼을 선택한 후, 간단 모드 또는 고급 모드를 선택합니다.
고급 모드를 사용할 경우 Tomcat 9/10.1을 선택하거나 자동 감지를 그대로 유지할 수 있으며, 필요에 따라 Context Path, JVM 파라미터 및 제외 규칙을 설정할 수 있습니다. 간단 모드의 경우 호환성 검사를 통해 적절한 Tomcat 버전을 제안합니다. 각 옵션의 의미는 Protector4J 고급 모드 설정를 참조하십시오.
출력 디렉토리를 선택하고 파라미터 요약을 확인한 후 Run protection를 클릭합니다.

2. CLI 사용 예시

지정된 Context Path:

p4j tomcat app.war dist --context /app

호환성 검사 및 자동 적용 권장 사항:

p4j tomcat app.war --compat-scan
p4j tomcat app.war dist --compat-apply --context /app

이 두 옵션은 동시에 사용할 수 없으며, 그 차이점은 다음과 같습니다:

옵션	동작	사용 시기
`--compat-scan`	입력된 WAR 파일만 스캔한 뒤 위험 요소와 설정 권장 사항을 출력한 후 종료됩니다. 인코딩이 이루어지지 않으며 `dist`도 생성되지 않으므로 출력 디렉터리가 필요하지 않습니다.	애플리케이션을 처음으로 보호하거나, Tomcat 관련 종속성을 업그레이드하거나, 보호 범위나 JSP 설정을 조정한 후, 혹은 호환성 문제를 해결할 때 먼저 이를 사용하여 보고서를 확인합니다.
`--compat-apply`	스캔 후 자동으로 보수적인 권장 사항을 통합한 뒤 인코딩을 계속하여 결과물을 생성하므로 반드시 출력 디렉토리를 지정해야 합니다.	스캔 결과를 읽고 자동 권장 사항을 수락한 경우, 이를 활용하여 패키징을 완료할 수 있습니다. 또한 규칙이 이미 검증된 반복적인 빌드나 CI 프로세스에도 사용할 수 있습니다.

tomcat, --compat-apply의 경우 스캔 결과에 따라 제외 클래스를 추가하고 Tomcat 버전, ZIP overlay, 아카이브 접미사와 같은 옵션을 조정할 수 있습니다. 마지막 세 가지 옵션의 경우 명령줄에서 명시적으로 지정된 값이 우선시되며, 권장되는 제외 클래스는 기본적으로 명시적으로 지정된 --exclude와 통합됩니다. 자동으로 제외 클래스를 추가하지 않으려면 --no-compat-excludes도 함께 입력할 수 있습니다. 스캐너는 단순히 정적 힌트 기반 분석만 수행하므로 코드 수정이 필요한 문제들은 --compat-apply에 의해 자동으로 수정되지 않으며, 생성된 결과물은 여전히 목표 플랫폼에서 재테스트가 필요합니다.

기타 CLI 명령, 모든 옵션, 환경 변수 및 자동화 예제는 CLI 매개변수 참고를 참조하십시오.

--tomcat-version는 기본적으로 auto입니다. 필요한 경우 9 또는 10.1를 명시적으로 지정할 수 있습니다.

p4j tomcat app.war dist --context /app --tomcat-version 10.1

3. 출력 구조

dist/
├── bin/
│   ├── catalina.sh
│   ├── startup.sh
│   ├── shutdown.sh
│   └── *.bat
├── conf/p4jx/
│   ├── contexts.list
│   ├── protected-classes.list
│   └── allowed-prefixes.list
├── protected/
│   └── app.p4jx
├── lib/
│   ├── p4jx-tomcat-runtime.jar
│   └── tomcat-runtime-deps.jar
├── vlxjre/
├── run.sh
└── run.bat

기본적으로 물리적 WAR 파일은 생성되지 않습니다. web.xml, 정적 리소스, 공개 클래스, 메타데이터 스텁, 보호 구현은 모두 protected/<context>.p4jx에 위치하며, P4JX WebResourceSet를 통해 Tomcat에 제공됩니다.

4. 시작 및 중지

프론트엔드 실행:

./run.sh

Tomcat 스타일 백엔드 시작:

./bin/startup.sh
./bin/shutdown.sh

Windows의 경우 해당하는 .bat 파일을 사용합니다. 로그는 출력 디렉터리에 있는 logs/에 기록됩니다.

Windows 목표물을 패키징할 때 추가로 네이티브 시작 프로그램을 생성할 수 있으며, 이를 통해 내장된 Tomcat을 프론트엔드 방식으로 시작할 수 있습니다. 자세한 내용은 Windows EXE 시작 프로그램 생성를 참조하십시오.

JVM 시작 매개변수

패키징 시 GUI의 JVM startup options에서 각 줄에 하나의 매개변수를 입력하거나 CLI를 사용할 수 있습니다:

p4j tomcat app.war dist \
  --context /app \
  --jvm-option -Xms1g \
  --jvm-option -Xmx2g

배포 후 직접 수정:

macOS/Linux의 경우 bin/catalina.sh를 편집하고, run_java() 내의 JVM_OPTS=(...) 뒤에 JVM_OPTS+=("-Xms1g" "-Xmx2g")를 추가하면 프론트엔드 및 startup.sh를 통한 백엔드 시작 모두에 적용됩니다.
Windows 전면 모드: bin\catalina.bat를 편집하여 기존의 set "JVM_OPTS=..." 뒤에 set "JVM_OPTS=%JVM_OPTS% -Xms1g -Xmx2g"를 추가합니다.
Windows 백그라운드 모드: bin\startup.bat에서 catalina.bat를 호출하기 전에 set "APP_JAVA_OPTS=-Xms1g -Xmx2g"를 추가합니다. 전면 및 백그라운드 모드에서 동일한 영구적인 파라미터를 공유해야 하는 경우, GUI/CLI를 통해 다시 생성하는 것이 권장됩니다.

임시 실행 시에도 명령어 앞에 APP_JAVA_OPTS를 설정할 수 있습니다. 완전한 CMD, PowerShell 및 스크립트 예제는 JVM 시작 파라미터 설정를 참조하십시오.

5. Tomcat 버전 선택

WAR API 네임스페이스	Tomcat	Java 요구 사항
`javax.servlet.*`	Tomcat 9	Java 8/11/17/21/25
`jakarta.servlet.*`	Tomcat 10.1	Java 11/17/21/25

자동 감지는 우선 애플리케이션 클래스와 배포 설명자를 통해 API 네임스페이스를 식별하며, 의존하는 JAR 이름은 단지 보조 증거로만 사용됩니다. javax와 jakarta가 혼용되는 것이 감지되면, 해당 도구는 자동 추측을 거부합니다.

6. JSP

WAR에 JSP가 포함된 경우, 기본적으로 인코딩 단계에서 자동으로 servlet 클래스 및 URL 매핑으로 사전 컴파일됩니다. 이는 런타임 시 동적 JSP 컴파일이 Tomcat 작업 디렉터리에서 새로운 클래스를 정의하여 런타임 클래스 정의의 경계를 보호하는 원칙에 위배되기 때문입니다.

명시적으로 제어할 수 있음:

--precompile-jsp
--no-precompile-jsp

운영 환경에서는 기본값인 자동 사전 컴파일 상태를 그대로 유지하는 것이 권장됩니다. 이 기능을 비활성화하면 JSP가 포함된 애플리케이션이 페이지에 접근할 때 오류가 발생할 수 있습니다.

7. 보호 범위 및 제외 규칙

기본적으로 WEB-INF/classes에 속하는 애플리케이션 클래스가 보호되며, WEB-INF/lib는 기본적으로 보호되지 않습니다. 웹에 노출되는 클래스는 제외할 수 있습니다:

p4j tomcat app.war dist \
  --context /app \
  --exclude 'com.example.web.**,com.example.dto.**'

특히 servlet/filter/listener, DTO, 설정 클래스, 엔티티 클래스, JNI 브리지 클래스, 그리고 컨테이너에 의해 강화되어야 하는 클래스들을 반드시 제외해야 합니다. 호환성 검사를 통해 보수적인 권장 사항이 제공됩니다.

8. 동일한 Tomcat 패키지 내에 애플리케이션 추가

p4j tomcat second.war dist \
  --append-app \
  --context /second

제약 사항:

context path는 기존 애플리케이션과 중복되어서는 안 됩니다;
기존 애플리케이션과 새로운 애플리케이션은 동일한 Tomcat 메인 버전, Java 버전 및 대상 플랫폼을 사용해야 합니다;
--append-app가 전달되지 않으면, 해당 도구는 기존 Tomcat 패키지에 데이터를 쓰는 것을 거부합니다;
GUI에서 “Append application to an existing Tomcat folder”를 선택한 후 직접 기존 디렉터리를 지정합니다.

9. Java 8 사용 시 주의사항

Java 8 대상 환경에서는 ZIP overlay 기능이 자동으로 활성화되어, Tomcat WebResourceSet을 통해 보호된 아카이브 파일을 열 수 있습니다.