Protection for Tomcat Web applications

tomcat converts a WAR file into a self-contained Tomcat base. It uses the Tomcat components built into the encoder at runtime, without accessing the user’s local Tomcat installation.

1. GUI operations

1. Select Tomcat WAR on the application type page.

   

2. Choose to input the WAR file, select The included Java version and the target platform, then pick between simple mode or advanced mode.

   

3. In advanced mode, select Tomcat 9/10.1 or keep automatic detection, and set the Context Path, JVM parameters, and exclusion rules as needed; simple mode suggests a Tomcat version through a compatibility scan. For the meaning of each option, see Protector4J Advanced Mode Settings.

   

4. Select the output directory, review the parameter summary, then click Run protection.

   

2. CLI examples

Specify Context Path:

p4j tomcat app.war dist --context /app

Compatibility scan and automatic application recommendations:

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

These two options cannot be used simultaneously. The difference between them is:

For tomcat and --compat-apply, exclusion classes can be added based on the scan results, and options such as the Tomcat version, ZIP overlay, and archive suffix can be adjusted. For the latter three options, the values explicitly specified in the command line take precedence; the suggested exclusion classes are merged with the explicitly specified ones by default for --exclude. If you do not want exclusion classes to be added automatically, --no-compat-excludes can be provided as well. The scanner only performs static heuristic analysis, and issues that require code modifications will not be automatically fixed by --compat-apply; regression testing on the target platform is still necessary after generation.

For other CLI commands, all options, environment variables, and automation examples, see CLI Parameters Reference.

--tomcat-version defaults to auto. If necessary, 9 or 10.1 can be explicitly specified.

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

3. Output structure

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

A physical WAR is not generated by default. web.xml, static resources, public classes, metadata stubs, and protection implementations are all located in protected/<context>.p4jx, where they are presented to Tomcat via P4JX WebResourceSet.

4. Starting and stopping

Front-end operation:

./run.sh

Tomcat-style back-end startup:

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

For Windows, use the corresponding .bat file. Logs are written to logs/ in the output directory.

JVM startup parameters

When packaging, you can enter one parameter per line in JVM startup options in the GUI, or use the CLI:

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

Modify directly after deployment:

• macOS/Linux: Edit bin/catalina.sh, add JVM_OPTS+=("-Xms1g" "-Xmx2g") after JVM_OPTS=(...) in run_java(); this will take effect for both front-end and startup.sh back-end startups.
• Windows front-end: Edit bin\catalina.bat, and add set "JVM_OPTS=%JVM_OPTS% -Xms1g -Xmx2g" after the original set "JVM_OPTS=...".
• Windows background: Add set "APP_JAVA_OPTS=-Xms1g -Xmx2g" before calling catalina.bat in bin\startup.bat. If a single set of persistent parameters is needed for both background and foreground operations, it is recommended to regenerate them via GUI/CLI.

APP_JAVA_OPTS can also be set before the command for temporary startup. Complete CMD, PowerShell, and script examples are available at JVM startup parameters configuration.

5. Tomcat version selection

Automatic detection prioritizes identifying the API namespace from application classes and deployment descriptors, with JAR names serving only as supplementary evidence. If javax and jakarta are detected together, the tool will refuse to make automatic guesses.

6. JSP

When a WAR contains JSP files, it is automatically precompiled into servlet classes and URL mappings during the encoding phase by default. This is because dynamic JSP compilation at runtime defines new classes from the Tomcat working directory, which does not align with the protection scope of runtime class definitions.

It can be explicitly controlled:

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

It is recommended to keep the default automatic precompilation in the production environment. Disabling it may cause applications containing JSP to fail when accessing pages.

7. Protection scope and exclusion rules

By default, application classes under WEB-INF/classes are protected, while WEB-INF/lib is excluded from protection by default. Web-facing classes can be excluded:

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

Prioritize excluding servlet/filter/listener, DTO, configuration, entity, JNI bridge classes, and classes that require container enhancement. A compatibility scan will provide conservative recommendations.

8. Adding an application to the same Tomcat package

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

Constraints:

• The context path must not duplicate an existing application;
• Both the old and new applications must use the same Tomcat major version, Java version, and target platform;
• When --append-app is not provided, the tool refuses to write to existing Tomcat packages;
• Check “Append application to an existing Tomcat folder” in the GUI and directly select an existing directory.

9. Notes for Java 8

The Java 8 target automatically enables ZIP overlay, allowing Tomcat WebResourceSet to open protected archives.