On Java Development

All things related to Java development, from the perspective of a caveman.

Configuring Tomcat

without comments

Introduction

This post talks about a few configuration parameters that are added to Tomcat’s JVM. Technically known as arguments, they give the ability to connect to test or production databases and direct Log4j’s log files to the proper directory. Also, when Tomcat is running on the iSeries machine, there is another configuration parameter (“java.awt.headless”) that must be added to the JVM argument list.

This post is divided into a few sections. The first section is about the configuration process for the required JVM arguments. The section that follows explains in detail what these arguments are for. The next section is for changes made to server.xml and to context.xml. The remaining sections go over some procedures to use during trouble shooting on the iSeries.

 

Configuring Tomcat’s Startup Process with JVM Parameters

This section contains information about how to configure Tomcat as a service and when installed to be started manually from the command line or by a host process.

 
 

Configuring Tomcat When Installed as a Service

When Tomcat has been installed as a service (using Apache’s apache-tomcat-7.0.57.exe), the install process creates entries under the Start menu;
ConfigureTomcatService00

Selecting the option shown presents a dialog box to configure JVM parmameters.
ConfigureTomcatService02

The parameters shown in the “Java Options” window seen in the Java tab of the dialog box shown above are required by the Java web applications to be deployed on this server. They are listed after the parameters that are already provided by Apache. After adding the parameters as shown, the configuration is complete and Tomcat is ready for applications.

 
 

Configuring Tomcat When Not Installed as a Service

This section describes how the parameters must be specified when Tomcat is not installed as a service. This means Tomcat will be started manually. The modifications described affect three files.

There are two ways of manually starting Tomcat on a Windows machine; one is to execute “catalina400.bat start” or “startup400.bat” from the command line. Both are listed below.

  • setenv.sh – Bash shell script that exports variable name/value pairs to the environment of the child process running in the current shell. The current shell in this case contains the Tomcat job after having been manually started.
  • startup.sh – Starts Tomcat normally, with output and error streams being written to the standard Catalina.out log file. Calls catalina400.sh
  • catalina400.sh – Bash shell script that actually starts Tomcat.

 
 

Create/Modify setenv.sh

Under Tomcat’s home directory there is a text-file called “RUNNING.txt“. In it, there are a few conflicting statements about the existence of setenv.sh. Regardless of what the narrative says, this file does not exist. So, it must be created. Do this by copying the source code below. Place the contents into setenv.sh and save it into the bin directory. When this file exists, catalina400.sh will use the name/value pairs within.

The code exports the named parameters with their associated values. This will make them available for use by the shell scripts that follow.

 
 

Create startup400.sh

When running in an iSeries environment it is best to use a copy of startup400.sh provided by another release but absent from more recent releases of Tomcat. The source is provided below. As seen on line 21, this shell script calls catalina400.sh Use this when Tomcat has been installed under an IFS directory on the iSeries. If Tomcat has been installed on a Windows machine, then ignore it. Regardless of the case, see catalina400.sh.

 
 

Create/Modify catalina400.sh

As with the previous shell script, when running in an iSeries environment it is best to use a copy of catalina400.sh provided by another release but absent from more recent releases of Tomcat. The source is provided below. This is a long script. Note the comments made on lines 23 and 24. It is the reason for creating setenv.sh in the first place.

Add the entries shown on lines 401 through 427. Be aware that lines 412 through 416 already exist. They were simply replaced by the source shown between 401 through 417. You can see the code that references the name/value pairs defined by setenv.sh which were then exported into the shell environment. The values are appended to the JVM parameters list. The effect is the same as adding the parameters shown in the “Java Options” window seen in the Java tab of the dialog box shown near the start of this post. Yes, this way is more complicated which makes installing Tomcat as a service more attractive.

 
 

The Parameters in Detail

The sections that follow further describe the parameters required by baseproject. Keep in mind that the parameter for the “headless” option is required only when Tomcat has been installed on an iSeries or any mainframe or dedicated server on your project that has no display device, keyboard, or mouse. For more information about this parameter see this link.

 

The “runtimeEnvironment” Parameter

The “runtimeEnvironment” parameter identifies the server as a development, test or production oriented server. At startup time, the application reads this value which will enable the application to establish the correct DB connections as reflected by those environmental values. It is also used to govern the overall behavior of the application. For example, if running on the localhost during development or on the test server during the User Acceptance Test (UAT) phase, certain features such as sending email must behave accordingly and not send email out to the corporate recipients as would be needed when the application is running in production.

This parameter takes the following form:

  • Developer’s machine: -DruntimeEnvironment="localhost"
  • Test server: -DruntimeEnvironment="TEST"
  • Production server: -DruntimeEnvironment="PROD"

 

The “logFilePath” Parameter

This parameter uses the value in $CATALINA_HOME to build the path to the base directory under which the application’s log files will be written. The applications use Log4J for this and the rest of the path is supplied by the values established within their respective log4j.xml configuration file.

To illustrate, take a look at the following log4j appender definition, and specifically, line 3.

 
This line is responsible for setting the directory for the application’s log file. When the application is running on the test or production server, it gets the base path by reading the server’s logFilePath parameter to which the rest of the entry is appended. However, while running on the developer’s machine, this parameter will not have been set on the local Tomcat instance. It doesn’t have to be. The deliberate absence of the parameter for localhost removes the need to configure the local server. This evokes the application’s startup logic to instead read the value from the application’s configuration file. Since this file is already the center of focus for the developer during the configuration process it relieves the developer from having to remember to configure their server for this value.

This parameter takes the following form:

  • All servers: -DlogFilePath=”’$CATALINA_HOME’”/logs”

 
This link presents the web-application’s startup servlet and shows how the settings for “runtimeEnvironment” and “logFilePath” are used.

 

The JVM Argument Required for the iSeries

This section presents JVM arguments required when Tomcat is installed on an iSeires.

 

The “java.awt.headless” Parameter

This parm tells the JVM within which Tomcat runs that the machine on which it is running has no display device, no mouse and no keyboard a.k.a. “headless”. When running on the iSeries without this parm, the following java stack trace will be emitted when Tomcat starts.

The JVM parameter needed to indicate a headless machine is below.

  • All servers: -Djava.awt.headless=true

 

Changes made to Tomcat’s server.xml and context.xml files

This section presents changes made to server.xml and context.xml

 

Enabling Applications to Read PDF Documents

Some applications need to read PDF documents. Tomcat’s server.xml has been modified to allow for this. The only requirement for the developer is to copy the PDF documents into the appropriate folder. For example, when a new application is created that needs to read PDF documents from a folder designated by that application, create the folder under Tomcat7028T/appcontent for Tomcat test server and Tomcat7028/appcontent for the production server.

The change that allows for this is due to the entry made to the Tomcat’s server.xml file. Shown below is the value entered (line 4) for the test server. A similar entry was made for the production server.

 

JNDI configuration made to context.xml

Baseproject requires a JNDI config entry for each Tomcat install. A config entry like the one shown goes into context.xml under Tomcat’s conf directory. The following entries have been made for the TEST server. A similar entry was also made for the PROD server.

After making these additions, be sure to add as400.jar to the lib directory. If you don’t, you’ll see entries in the log file like these:

 

Prevent Application Restarts When Changes to context.xml Have Been Made

Normally, after Tomcat has been started and when changes to context.xml have occurred, Tomcat will notice the change and restart all apps running on that server at that moment. That can be a real hoot for the user community.

To prevent that from happening, modify the host attribute in server.xml by changing the autoDeploy parm to ‘false’.

Now, when anything in context.xml is changed, say, a JNDI definition, Tomcat won’t restart the apps until the next morning when the server is restarted. Then the change made will become active.

 
 

Changes to Tomcat Web Application Manager

This section presents changes made to Tomcat7028\webapps\manager\WEB-INF\web.xml

Enabling upload of jar-files up to 102,400kb in size.

The configuration entry shown below was modified to allow uploading of jar-files up to 102,400 kb in size. The actual number applied is arrived at by jar-file kb limit * 1024 = threshold size e.g. 102400 * 1024 = 104857600

The server must be restarted for this change to be in effect.

 
 

Starting and Stopping Tomcat 7.n.n on the iSeries

The following table shows the commands used to start and stop Tomcat 7 servers that have been installed on the iSeries. The commands are executed by QSH (QShell). Related log files are also shown.
TomcatQShellStartStop

This iSeries command, STRTOMCAT, starts a Tomcat production level server. It should only be used when starting a production level server. When starting a test level server, the command STRTCTEST should be used.

To make this process easier on the iSeries user and for nightly processing, an iSeries command has been created to allow starting and stopping of Tomcat servers that have been installed in the iSeries. The commands are shown below.

This iSeries command, STRTOMCAT, starts a Tomcat production level server. It should only be used when starting a production level server. When starting a test level server, the command STRTCTEST should be used.
STRTOMCAT

This iSeries command, ENDTOMCAT, starts a Tomcat production level server. It should only be used when starting a production level server. When ending a test level server, the command ENDTCTEST should be used.
ENDTOMCAT

Regardless of which flavor of the start commands are used, be aware of the fact that it submits a CL Program (STRTOMCAT or STRTCTEST)to batch. The CLP then uses the STRQSH (Start SQHELL) to start a QSHELL session in which a JVM is started to run Tomcat. As a consequence, no completion message is issued as long as the Tomcat server is running. When using the appropriate command to end the Tomcat server, it will end the job and a completion message will then be issued followed by another completion message for the command which ended it.

Once a Tomcat server has been started, the job can be observed using WRKACTJOB. Note that the server is running under QINTER Subsystem.
TomcatQINTERJob

 

Changes made to Tomcat’s Home Page

This section shows how to change Tomcat’s index.jsp so that the page’s title announces the server’s role and port number. This serves to confirm that the developer/admin is on the server they believe they requested. This is helpful when the environment contains multiple servers.

 

Tomcat’s index.jsp

Shown below is a segment of the source code for Tomcat’s index.jsp page that is first presented to the admin after entering the server’s URL in the browser window. It has been modified to announce to the admin the server’s role and port number. The change made to index.jsp is shown on lines 17 through 19. The path to this file is (Tomcat Home)\webapps\ROOT.

The effect of the change is shown below. The information for the TEST server is presented in orange while the color for the PROD server is red.
ApacheTomcatTestServerBanner01

 
 

Problems?

The following entries describe various methods to use when troubleshooting problems in the iSeries.

 

Starting Tomcat from the command line on the iSeries

 

To View Tomcat’s Log File on the iSeries

To inspect Tomcat’s log on the iSeries, use the Work Link command to locate then display catalina.out.

After starting Tomcat, monitor this log file. You should notice the entries being added reflecting the start of each application. For example …

…indicates the application “FileFields” is being launched. Each application’s start up servlet, if it has one, will be logging to this logfile until Log4J has been initialized after which time the entries are written to the application’s logfile, usually located in a directory for the application. See ‘T:\Tomcat7028T\logs

When all application have been started, you should see entries similar to these:

Line 12 indicates the Tomcat server is ready for business.

 

Canceling Tomcat on the iSeries

In the event that the custom command ENDTCTEST does not work properly or taking too long, the server can be canceled in the traditional manner used for any iSeries job. First, locate the job using :

Then cancel.

 
 

Written by admin

January 7th, 2014 at 7:23 pm

Posted in iSeries,Tomcat

Tagged with ,

Leave a Reply

You must be logged in to post a comment.