Chapter 4 Implementing the Tomcat Java Servlet and JavaServer Pages Container

Tomcat Overview

Tomcat is a Java Servlet and JavaServer Pages (JSP) container provided through the Apache Software Foundation Jakarta project. The Tomcat container is most commonly used with commercial grade Web servers such as Apache. It can also be used as a standalone Web server.

Tomcat is provided with the Secure Web Server as an optional subset (IAETOMCATxxx, where xxx is the version number of the Secure Web Server release). When this subset is installed:

The Tomcat subset creates a Cluster Application Availability (CAA) resource when it is used in a TruCluster environment. Tomcat is configured as a single instance resource so that it can take advantage of sessions and other capabilities of a Java Servlet environment. The public instances of the (multi-instance) Secure Web Server are configured to communicate with the Tomcat instance and will handle the failover of the Tomcat resource.

For more information on developing and installing servlets and JSPs, see Section : Locating Additional Information. After installing or updating an application, the Tomcat container and the public Web server may need to be restarted. For information on starting Tomcat, see Section : Starting Tomcat.

Using Tomcat as a Standalone Public Web Server

Tomcat may be installed as a standalone public Web server. When you install Tomcat in this manner, the server is configured to respond to HTTP requests on a specified port. Tomcat was previously used exclusively as a backend to an Apache-based Web server. It has now evolved into a full-featured Web server.

A Web server is normally run as a non-privileged user to reduce potential security risks. The Secure Web Server has provisions for switching to the user httpd after it has opened its ports. To perform the same actions with Tomcat, you must run a program called jsvc whenever the Web server port configured is less than 1024. The jsvc program is part of the Tomcat source distribution. This installation will automatically use the jsvc program, if needed, when Tomcat is started with the /sbin/init.d/tomcat script or by using the Manage the Tomcat Java Servlet and JSP Engine link from the Web Server Administration menu (see Section : Starting and Stopping Tomcat from the Administration Utility).

Locating Tomcat Directories

After installation, Tomcat resides in the /usr/internet/httpd/tomcat directory. Applications (Java Servlets and JSPs) are installed under the /usr/internet/httpd/tomcat/webapps directory.

Tomcat-specific configuration information is installed in the /usr/internet/httpd/tomcat/conf directory.

Selecting a Java Environment

In some cases, multiple Java Development Environment kits (JDK) might be installed on a system. You can customize the Java environment used to power the Tomcat container by specifying which Java Development Environment kit (JDK) to use and by adding optional parameters to the java command. Customizing the Java environment is also useful when special tuning of the Java Runtime is desired.

Tomcat first uses values specified in the /usr/internet/httpd/tomcat/bin/setenv.sh initialization file. If no values are specified in this file, Tomcat uses the Java system default . When you first install the Tomcat subset, it creates the /usr/internet/httpd/tomcat/bin/setenv.sh initialization file (if it does not already exist) so that Tomcat will use the newest version of the JDK that is present at installation.

If you want to use a different version of the JDK, change the JAVA_HOME and JAVA_CMD variables defined in the initialization file. The JAVA_HOME and JAVA_CMD variables should always reference the same JDK; if they do not, Tomcat will fail to operate properly. The JAVA_CMD variable should be quoted to allow for the addition of arguments.

The following example shows a /usr/internet/httpd/tomcat/bin/setenv.sh initialization file with additional java command arguments:

JAVA_HOME=/usr/opt/java/131
JAVA_CMD="$JAVA_HOME/bin/java -classic"
export JAVA_HOME JAVACMD

Starting Tomcat

Section : Starting and Stopping Tomcat from the Administration Utility describes how to start, stop, and restart Tomcat as a standalone server from the Web Server Administration utility.

Starting or restarting Tomcat is different if you are running your Secure Web Server in a TruCluster environment. Section : Restarting Tomcat in a Non-TruCluster Environment describes how to restart Tomcat using the tomcat startup script when it is not in a TruCluster environment. Section : Restarting Tomcat in a TruCluster Environment describes how to restart Tomcat using the caa_start and cluster_restart scripts when running Tomcat in a TruCluster environment.

Section : Tomcat Log Files gives the location of the Tomcat log files.

The Secure Web Server startup script is designed to detect the presence of Tomcat and start the Web server with additional command-line directives that enable the communication with Tomcat and cause the dynamic configuration files generated by Tomcat to be used.

The Tomcat engine creates a number of configuration files each time it is started. These configuration files contain directives that determine the information the Secure Web Server will serve and the requests that should be directed to the Tomcat engine.

	Note: To take full advantage of the changes in Web contexts, the Secure Web Server configuration must be changed to map the new contexts and then the web server must be restarted whenever you change the Tomcat configuration.

Starting and Stopping Tomcat from the Administration Utility

You can start, stop, and restart the standalone Tomcat server from the Web Server Administration utility.

To start the Tomcat server:

1. On the Web Server Administration menu, choose Manage the Tomcat Java Servlet and JSP Engine. The Manage the Tomcat Java Servlet and JSP Engine form is displayed.

2. On the Manage the Tomcat Java Servlet and JSP Engine form, click on Start/Stop the Manage the Tomcat Java Servlet and JSP Engine (Figure 4-1). Tomcat starts the server and displays a message that the server is running.

   Figure 4-1 Manage the Tomcat Java Servlet and JSP Engine Form

To stop and restart the Tomcat server:

1. On the Manage the Tomcat Java Servlet and JSP Engine form, click on Start/Stop the Manage the Tomcat Java Servlet and JSP Engine (Figure 4-1). The Start/Stop the Manage the Tomcat Java Servlet and JSP Engine form is displayed (Figure 4-2).

   Figure 4-2 Start/Stop the Tomcat Java Servlet and JSP Engine Form

2. Click on stop to stop the server. Tomcat displays a message that the server is stopped.

3. To restart the server, click on restart. Tomcat displays a message that the server is again running.

Restarting Tomcat in a Non-TruCluster Environment

To start Tomcat and the Secure Web Server that is not part of a TruCluster environment:

1. If Tomcat is running, use the stop command to stop the server:

   # /sbin/init.d/tomcat stop

   And this command to restart the server:

   # /sbin/init.d/tomcat restart

2. Start the Tomcat server using the start command:

   # /sbin/init.d/tomcat start

3. Restart the public instance of the Secure Web Server using the restart command:

   # /sbin/init.d/httpd_public restart

Restarting Tomcat in a TruCluster Environment

To restart Tomcat and the Secure Web Server in a TruCluster environment:

1. If Tomcat is running, use the caa_stop command to stop the server:

   # caa_stop tomcat

   And this command to restart the server:

   # /sbin/init.d/tomcat restart

2. Start the Tomcat Server using the caa_start command:

   # caa_start tomcat

3. Restart (on all cluster members) the public instance of the Secure Web Server using the cluster-restart command:

   # /sbin/init.d/httpd_public cluster-restart

Tomcat Log Files

Tomcat records log files in the /usr/internet/httpd/logs directory. Table 4-1 lists the log files Tomcat creates and provides a description of each file.

Table 4-1 Tomcat Log Files

Log File	Description
tomcat_startup.log	Tomcat startup log
catalina.out	Tomcat general log
access_log	Access requests log, shared with the Secure Web Server
error_log	Failed access requests log, shared with the Secure Web Server
tomcat.pid	The process ID of the Tomcat process.

 

Accessing the Tomcat Administration and Manager Applications

Tomcat provides Web-based applications for administering the Tomcat deployment and for managing the lifecycle of Web applications running within the Tomcat container. To access the Tomcat Web-based administration features:

By default, access to these management applications is limited to browsers running on the local host and requires that users successfully authenticate before being granted access. The local host restriction is established by access control valves in the /usr/internet/httpd/tomcat/conf/server.xml file.

To modify this restriction:

	Note: The default restriction requires that a browser on the local host must access the management applications using URLs that begin with http://localhost/. If you attempt to access the applications with URLs that begin with http://actual_hostname_of_local_host/, it will be rejected. User authentication is provided by a custom realm that allows a user who successfully authenticates as the Secure Web Server administration user to be mapped to the Tomcat user roles admin and manager. These roles are required to access the administration and Web application management utilities. If this initial authentication attempt fails, the realm then attempts to authenticate via Tomcat's default user authentication database, defined by the /usr/internet/httpd/tomcat/conf/tomcat-users.xmlfile. To change the behavior of this custom realm, modify the /usr/internet/httpd/tomcat/conf/server.xml file as necessary and then restart Tomcat.

Accessing the Tomcat Examples

The Tomcat subset includes Web applications for the Tomcat documentation and example Java Servlets and JavaServer Pages. The Web applications are installed in the /usr/internet/httpd/tomcat/samples directory . The Web applications are deployed by default and are accessed by specifying the name of your host domain, as follows:

http://yourhost.domain/tomcat/

To prevent the Web applications from being deployed, perform the following task:

Edit the /usr/internet/httpd/tomcat/conf/server.xml file and comment out or remove the following entries:

<Context path="/tomcat"
 docBase="/usr/internet/httpd/tomcat/samples/ROOT.war"
 reloadable="false" debug="0" />

<Context path="/tomcat/examples"
 docBase="/usr/internet/httpd/tomcat/samples/examples.war"
 reloadable="false" debug="0" />

<Context path="/tomcat/docs"
docBase="/usr/internet/httpd/tomcat/samples/tomcat-docs.war"
reloadable="false" debug="0" />

<Context path="/tomcat/webdav"
docBase="/usr/internet/httpd/tomcat/samples/webdav.war"
reloadable="false" debug="0" />

Locating Additional Information

Additional information about Tomcat can be found in the following locations: