cPanel Tomcat JSP and Servlets Guide

cPanel Tomcat JSP and Servlets Guide

Sections
01. Installation
02. Structure
03. Versions
04. Logs
05. Processes
06. Tomcat manager
07. War files
08. Testing
09. Troubleshooting
10. Customizations
11. Miscellaneous issues
12. Disable

01. Installation of Tomcat and adding JSP support for a domain

a. Installation

To install Tomcat, select the Tomcat option in WHM’s EasyApache (Apache Update) or using “/scripts/easyapache” (without the quotes) in command line. The Tomcat selection is found in Step 5’s Apache Options area.

b. Adding servlet support

After Tomcat has been installed, use WHM > Account Functions > Install Servlets to add JSP and servlets to an account’s main domain. You can also do this using the following in shell:

Code:

/usr/local/cpanel/scripts/addservlets2 --domain=domain.com

Please replace domain.com with the domain name.

c. Subdomain servlet support

You would need to use command line for adding subdomain support for servlets as they do not automatically include that support and WHM does not have any option to add servlets to subdomains.

d. Addon domain servlet support

Addon domains will not work when added using command line if added by the addon domain name. The /usr/local/apache/conf/httpd.conf ServerName sub.domain.com line is what is used and it must match the Host name="sub.domain.com" line in /usr/local/jakarta/conf/server.xml file exactly, so addon domain support is added by installing servlets onto the subdomain associated with the addon domain:

Code:

/usr/local/cpanel/scripts/addservlets2 --domain=sub.domain.com

e. Removing servlets

To remove JSP and servlets, only command line is available via this command:

Code:

/usr/local/cpanel/scripts/remservlets --domain=domain.com

02. Structure of the JSP and servlets installation

Tomcat places files into /usr/local/jakarta/tomcat which is symlinked from /usr/local/jakarta/apache-tomcat-# where # is the Tomcat version that was installed by EasyApache.

Here are the various files and folders:
/usr/local/jakarta/tomcat/conf/server.xml - Tomcat configuration file
/usr/local/jakarta/tomcat/bin - folder with Tomcat binaries such as startup.sh and shutdown.sh scripts
/usr/local/jakarta/tomcat/logs - folder with Tomcat log files
/usr/local/jakarta/tomcat/work/Catalina - folder for domains with servlet support that houses extracted .war files and other JSP content

03. Versions of Tomcat and Java

To see the Tomcat and JVM versions and paths, you can run the following in command line:

Code:

/usr/local/jakarta/tomcat/bin/version.sh

It outputs information such as the following:

Code:

root@host [/usr/local/jakarta/tomcat/bin]# ./version.sh 
Using CATALINA_BASE:   /usr/local/jakarta/tomcat
Using CATALINA_HOME:   /usr/local/jakarta/tomcat
Using CATALINA_TMPDIR: /usr/local/jakarta/tomcat/temp
Using JRE_HOME:        /usr/local/jdk
Using CLASSPATH:       /usr/local/jakarta/tomcat/bin/bootstrap.jar
Server version: Apache Tomcat/5.5.35
Server built:   Jan 6 2012 11:20:07
Server number:  5.5.35.0
OS Name:        Linux
OS Version:     2.6.18-274.7.1.el5.028stab095.1
Architecture:   amd64
JVM Version:    1.6.0_29-b11
JVM Vendor:     Sun Microsystems Inc.

If you only want to get the Java version, you can run:

Code:

java -version 

It will show something like the following:

Code:

root@host [/usr/local/jakarta/tomcat/bin]# java -version
java version "1.6.0_29"
Java(TM) SE Runtime Environment (build 1.6.0_29-b11)
Java HotSpot(TM) 64-Bit Server VM (build 20.4-b02, mixed mode)

04. Logs

a. Tomcat logs

The Tomcat log files are at /usr/local/jakarta/tomcat/logs location. They are the following:

Code:

catalina.err - The Tomcat error log
catalina.out - The Tomcat process log

b. mod_jk logs and runtime file

The mod_jk error and warning log file is at /usr/local/apache/logs/mod_jk.log location.

Of note, the jk-runtime-status.pid# and jk-runtime-status.pid#.lock files are also located in /usr/local/apache/logs directory.

05. Processes and Restarting Tomcat Properly

When Tomcat is installed onto a machine, the following type of processes will show:

If Tomcat is restarted manually without using our restart script at “/usr/local/cpanel/scripts/restartsrv_tomcat”, this type of process will show up instead:

This is done by issuing the following command:

Code:

/usr/local/jakarta/tomcat/bin/startup.sh

If you restart Tomcat using our service, we will not kill this process. The process needs to be killed manually (with “kill PID#” where PID# is the process number) before restarting our own Tomcat instance. If it isn’t, then Tomcat won’t function.

Of note, you can also restart Tomcat by calling “/usr/sbin/starttomcat” script, which is what our script calls.

06. Tomcat manager

a. Tomcat manager location

The Tomcat manager is at http://server.domain.com:8080/manager/html location (where server.domain.com is the machine’s hostname). Any domain on the server can also call this location via the same path.

b. Available options

Applications are listed in the manager with the ability to start, stop, reload and undeploy them there. War files can also be uploaded and deployed in the manager.

A Server Status section exists in Tomcat manager at http://server.domain.com:8080/manager/status

c. Authenticating

The username and password for accessing Tomcat manager is stored in /usr/local/jakarta/tomcat/conf/tomcat-users.xml file such as the following:

Code:

<tomcat-users>
  <user name="tomcat" password="tomcat" roles="tomcat" />
  <user name="role1"  password="tomcat" roles="role1"  />
  <user name="both"   password="tomcat" roles="tomcat,role1" />
  <user name="root" password="dK08U9PbCcU1" roles="admin,manager" />
</tomcat-users>

The manager is specifically the root user.

d. Giving another user access

Another user can be given access by adding an additional user line such as this example where the endar user is being added:

Code:

<tomcat-users>
  <user name="tomcat" password="tomcat" roles="tomcat" />
  <user name="role1"  password="tomcat" roles="role1"  />
  <user name="both"   password="tomcat" roles="tomcat,role1" />
  <user name="root" password="dK08U9PbCcU1" roles="admin,manager" />
  <user name="endar" password="h@ppyt1m3" roles="admin,manager" />
</tomcat-users>

Tomcat would need to be restarted after making this change:

Code:

/scripts/restartsrv_tomcat

07. War files

a. Description

War files are archives containing the full JSP and servlet application. They are automatically extracted by Tomcat into /usr/local/jakarta/tomcat/work/Catalina/domain.com location (where domain.com is the domain name for the site) by the name of the .war file. For example, if you have hello.war file, then the extracted folder application will be /usr/local/jakarta/tomcat/work/Catalina/domain.com/hello

b. Tomcat versus Apache

When war files extract, they extract only in the Tomcat folder and not the user’s /home/username/public_html folder. Because they aren’t extracted there, Apache does not recognize the folder and the application will then only load at http://domain.com:8080/hello (using our prior example) and not at http://domain.com/hello

There has been some confusion that these are not automatically set to extract using our default entry in /usr/local/jakarta/tomcat/conf/server.xml but this is not the case. Our default setup does have these extract into /usr/local/jakarta/tomcat/work/Catalina/domain.com path.

Conversely, they will not show up on Apache under port 80 by default. Revising the server.xml also does not work for these to auto extract nor is that even necessary to do. The way to add servlet support and to get all extracted war files showing up under Apache is by adding these two lines to /home/username/public_html/.htaccess file:

Code:

SetHandler jakarta-servlet
SetEnv JK_WORKER_NAME ajp13

I did this on my domain after adding sample.war to /home/endar/public_html (which then only extracted into /usr/local/jakarta/tomcat/work/Catalina/endar.org/sample folder), and after adding the lines I can access both Sample "Hello, World" Application and Sample "Hello, World" Application urls. That’s all it takes to get war files showing up under Apache.

The above lines also work for any servlet mapping where pages aren’t showing up in a browser with 404 errors for those pages even though the pages work when using the 8080 url.

c. war file testing

If war files appear not to be working, you can obtain a test war file at http://tomcat.apache.org/tomcat-5.5-doc/appdev/sample/sample.war and wget it to the account for deployment:

Code:

cd /home/username/public_html
wget http://tomcat.apache.org/tomcat-5.5-doc/appdev/sample/sample.war
chown username:username sample.war

At that point, try to load the http://domain.com:8080/sample url in a browser. If it works, then war files are working regularly.

08. Testing

To test if a domain has JSP working, there is a default test page that should be installed when servlet support is originally added to the domain or subdomain. The test page should look like the following on the backend for the file contents:

Code:

<html><head><title>Test JSP page</title></head><body bgcolor=white>

<table border="0"><tr><td><h1>Sample Application JSP Page</h1>
This is the output of a JSP page that is part of the Hello, World application.
It displays several useful values from the requestwe are currently processing.</td></tr>
</table>

<table border="0" border="100%"><tr>
<th align="right">Request Method:</th>
<td align="left"><%= request.getMethod() %></td></tr><tr>
<th align="right">Servlet Path:</th>
<td align="left"><%= request.getServletPath() %></td></tr></table></body></html>

The frontend would look like the following in a browser at http://domain.com/jsptest.jsp path:

Sample Application JSP Page
This is the output of a JSP page that is part of the Hello, World
application. It displays several useful values from the requestwe are
currently processing.
Request Method: GET
Servlet Path: /jsptest.jsp

If it does not look like this, then a different test page is being used. As such, copy the sample jsptest.jsp page at /usr/local/jakarta/apache-tomcat-5.5.35/samples/jsptest.jsp to the user’s account and check if it works:

Code:

cp /usr/local/jakarta/apache-tomcat-5.5.35/samples/jsptest.jsp /home/username/public_html
chown username:username /home/username/public_html/jsptest.jsp
/scripts/restartsrv_tomcat

Please replace username with the cPanel username above.

While Tomcat doesn’t really need to be restarted in this instance, doing so ensures that the account reloads. If the test page works and other pages still aren’t working, it is would be a coding issue.

09. Troubleshooting

a. Reinstalling Tomcat - last resort

In almost all instances, reinstalling Tomcat using EasyApache will not fix the issue with a page, pages, site or sites not working. Sometimes, a customized setup has been configured for Tomcat and reinstalling Tomcat will break all sites. Sometimes, the Tomcat version is older and, similar to Rails, newer Tomcat versions might not support the older coding, which will cause all sites to fail. As such, it is highly recommended to avoid reinstalling Tomcat unless absolutely necessary.

The only time reinstalling Tomcat has been beneficial was when the user ran out of disk space in /usr and had moved /usr/local to another directory. In that instance, the symlinks for java and tomcat services were pointing to files that no longer existed. Because of that, reinstalling Tomcat was required.

b. Coding configuration changes in WEB-INF on the account

The primary reason one account may not work for JSP is that coding has been placed into /home/username/public_html/WEB-INF that we did not provide and that coding, library or class is causing all pages to fail for JSP and servlets. This is easy to test.

First, here is what we provide on a default installation:

Code:

root@host [/home/endar/public_html/WEB-INF]# ls -lah
total 20K
drwxr-xr-x 4 endar endar  4.0K Jun 21 01:39 ./
drwxr-x--- 6 endar nobody 4.0K Jun 21 01:39 ../
drwxr-xr-x 2 endar endar  4.0K Jun 21 01:39 classes/
-rw-r--r-- 1 endar endar    14 Jun 21 01:39 .htaccess
drwxr-xr-x 2 endar endar  4.0K Jun 21 01:39 lib/

root@host [/home/endar/public_html/WEB-INF]# cat .htaccess 
deny from all

root@host [/home/endar/public_html/WEB-INF/lib]# ls -lah
total 8.0K
drwxr-xr-x 2 endar endar 4.0K Jun 21 01:39 ./
drwxr-xr-x 4 endar endar 4.0K Jun 21 01:39 ../

root@host [/home/endar/public_html/WEB-INF/classes]# ls -lah
total 12K
drwxr-xr-x 2 endar endar 4.0K Jun 21 01:39 ./
drwxr-xr-x 4 endar endar 4.0K Jun 21 01:39 ../
-rw-r--r-- 1 endar endar 2.2K Jun 21 01:39 ServletsTestPage.class

If there are any other files than these or content in the .htaccess besides what we provide, then any of those changes could be breaking JSP. Simply move the entire /home/username/public_html/WEB-INF directory to a backup and recreate it with only the contents we provide.

After making this change, restart Tomcat using “/usr/local/cpanel/scripts/restartsrv_tomcat” and check the jsptest.jsp page on the site in a browser again.

If the page works, then it is a coding issue.

c. Other reasons for JSP not working

In this guide, I previously discussed a few other reasons JSP and servlets might not be working:

- An addon domain rather than the subdomain was added for servlet support, and the Apache VirtualHost ServerName must match the domain being added to server.xml
- A non-cPanel Tomcat process is running due to issuing /usr/local/jakarta/tomcat/bin/startup.sh and that process needs to be killed, then /scripts/restartsrv_tomcat issued
- Servlet mapping hasn’t been added for war and other files and an .htaccess entry needs to be added for urls to work in Apache rather than showing a 404 Not Found error page

10. Customizations

a. server.xml configuration changes for Host entry

If you wish to customize the entries for Hosts (domains) in /usr/local/jakarta/tomcat/conf/server.xml file, then a TemplateToolkit file would be created at /var/cpanel/templates/tomcat/server.xml.host_entry.default (/var/cpanel/templates/tomcat folder needs to be created first and then the file). If this is not done, then any revisions will be wiped that are made directly to server.xml the next time servlets are added to another domain. The template file must be used in place of manually editing the server.xml file.

Here is one example of the contents that file could have:

Code:

<Host name="[% name %]" appBase="[% appbase %]" 
   unpackWARs="true" autoDeploy="true" xmlValidation="false" 
   xmlNamespaceAware="false" reloadable="true">
[%- FOREACH alias IN alias_list %]
<Alias>[% alias %]</Alias>
[% END -%]
<Context path="" reloadable="true" docBase="[% appbase %]" debug="0" 
   privileged="true" autoDeploy="true" liveDeploy="true"/>
<Context path="/manager" debug="0" privileged="true"
docBase="/usr/local/jakarta/tomcat/server/webapps/manager">
</Context>
</Host>

This will create an entry that looks like the following for new servlets that are added in /usr/local/jakarta/tomcat/conf/server.xml file:

Code:

<Host name="domain.com" appBase="/home/username/public_html" 
   unpackWARs="true" autoDeploy="true" xmlValidation="false" 
   xmlNamespaceAware="false" reloadable="true">
<Alias>www.domain.com</Alias>
<Context path="" reloadable="true" docBase="/home/username/public_html" debug="0" 
   privileged="true" autoDeploy="true" liveDeploy="true"/>
<Context path="/manager" debug="0" privileged="true"
   docBase="/usr/local/jakarta/tomcat/server/webapps/manager">
</Context>
</Host>

The old entry prior to adding this template would have been this instead:

Code:

       <Host name="domain.com" appBase="/home/username/public_html">
          <Alias>www.domain.com</Alias> 
          <Context path="" reloadable="true" docBase="/home/username/public_html" debug="1"/>
          <Context path="/manager" debug="0" privileged="true"
              docBase="/usr/local/jakarta/tomcat/server/webapps/manager">
          </Context>
       </Host>

After creating the file and to add it for all pre-existing users, you would issue this command:

Code:

/usr/local/cpanel/scripts/gentomcatlist

This should restart Tomcat as well.

b. Java startup values

If you wish to change startup values for Heap size and others (you can see the settings that are configurable if you issue “java -X” without the quotes), then a file named /var/cpanel/tomcat.options could be created.

Here’s an example of entries that could be placed into the file:

Code:

-Xmx200M
-Xms100M

This would change the maximum Java heap size (Xmx) and the initial Java heap size (Xms) on startup.

After this has been done, Tomcat would need to be restarted:

Code:

/scripts/restartsrv_tomcat

11. A few other reasons Tomcat might not be working

a. Disk space full and /usr moved

Tomcat will cease working when /usr/java is symlinked to /usr/local/jdk and /usr/local/jdk doesn't exist due to 100% disk space usage or /usr has been moved for that reason.

Here are the actual paths and file permissions for these files on a working machine:

Code:

root@host [/usr/local/jakarta/tomcat/conf]# ls -lah /usr/local/jdk
lrwxrwxrwx 1 root root 22 Jun 21 00:19 /usr/local/jdk -> /usr/local/jdk1.6.0_29/

root@host [/usr/local/jakarta/tomcat/conf]# ls -lah /usr/local/jre
lrwxrwxrwx 1 root root 18 Jun 21 00:20 /usr/local/jre -> /usr/local/jdk/jre/

root@host [/usr]# ls -lah java*
lrwxrwxrwx 1 root root 14 Jun 21 00:34 java -> /usr/local/jdk/

root@host [/usr/share]# ls -ld java
drwxr-xr-x 3 root root 4096 May  4 20:54 java/

root@host [/usr/share]# ls -ld /usr/local/jdk1.6.0_29/
drwxr-xr-x 10 root root 4096 Jun 21 00:19 /usr/local/jdk1.6.0_29//

root@host [/usr/share]# ls -ld /usr/local/jdk/jre
drwxr-xr-x 7 root root 4096 Jun 21 00:19 /usr/local/jdk/jre/

b. public_html file permissions

On public_html, this needs to be 755 for Tomcat to access JSP and servlet files. A reboot can cause pages to cease working when public_html is set to 750. You'll see an error like the following in the /usr/local/jakarta/tomcat/logs/catalina.err error log file:

12. Disabling Tomcat

We have a touch file that disables the ability to start up tomcat:

Code:

/etc/tomcatdisable

If you add that file and then kill the Tomcat processes, “/scripts/restartsrv_tomcat” will no longer start up Tomcat. Check /usr/local/cpanel/scripts/restartsrv_tomcat to see the code for that.

Please note that this doesn't remove Tomcat. Currently, no script exists to remove it. When you uncheck it in EasyApache after it has been compiled onto the machine, the “Install Servlets” option still appears in WHM.