Tomcat FAQ

Table of Contents

A General Information

A.1 What does ITIS Web Services Tomcat environment consist of?
A.2 How do I access the DEV system?
A.3 What are the names/addresses of the Tomcat systems?

B Developer Groups and Tomcat Instances

B.1 What is a developer group? What is a Tomcat “instance”?
B.2 Where should I point CATALINA_HOME?
B.3 Where should I point CATALINA_BASE?
B.4 Why don’t I see a “common” or “server” sub-directory?
B.5 What ports does my Tomcat instance use on the network?

C The Tomcat Environment

C.1 What version of Linux is this?
C.2 What version of Tomcat is this?
C.3 What version of the Java JDK or JRE is this?
C.4 What is the Java Security Manager?
C.5 How does the Java Security Manager work?
C.6 How do I figure out what permissions my code needs? It seems to run okay in DEV.
C.7 This seems like a lot of work. Why don’t you just turn the Java Security Manager off? Don’t you trust us?

D The Development Environment

D.1 What development tools are available?
D.2 I want to use tool “X”. Will you install it?
D.3 What Java packages are available?
D.4 I want to use Java package “X”. Will you install it?
D.5 How do I restart Tomcat?
D.6 How do I deploy my application?
D.7 How do I migrate my application to QA? PROD?

E SSL, Logging, Databases, etc.

E.1 Is SSL available? How do I make sure that my application uses it?
E.2 What logging packages are available?
E.3 How should I configure and use logging in my application?
E.4 How can I review my logs in QA or Production?
E.5 What database options are available?
E.6 How do I request a database connection?
E.7 How do I reference this JNDI?
E.8 I need/want to write a file to disk. Why won’t you let me?

A General Information

A.1 What does ITIS Web Services Tomcat environment consist of?

Our Tomcat environment consists of three tiers of machines: development (DEV), quality assurance (QA), and production (PROD). Only the DEV tier is directly available to developers. In this tier is where you write, build, test, fix, rebuild, retest (and so on) your code. When it is working, the next step on the way to production is to push it to our QA tier. The QA tier is where you should test your application thoroughly. This tier is as close to the PROD tier as is possible, so if your application works well here, it should work well in PROD as well.

A.2 How do I access the DEV system?

Accounts on our Tomcat DEV system can be requested by filling out an account request form  and mailing that to ITIS Web Services, 6th Floor, Yong Hall. We’ll review the form, note what developer group you belong to, and have the account created by ITIS’s Unix administrators. Once you have your account, you can use SSH from any Purdue University system to login to the DEV system.

A.3 What are the names/addresses of the Tomcat systems?

Name Address
DEV tomcatdev.itap.purdue.edu 128.210.23.82
QA tomcatqa.itap.purdue.edu 128.210.7.130
PROD tomcat.itap.purdue.edu 128.210.7.128

B Developer Groups and Tomcat Instances

B.1 What is a developer group? What is a Tomcat “instance”?

Tomcat has the ability to run multiple “instances” from a single installation. Each instance is running in its own Java Virtual Machine (JVM), is independently configured, and can be started and stopped without affecting other instances. Web Services has chosen to use these instances to separate various Tomcat developers into groups to minimize the impact that each group will have on the others. For example, the ELT developer group can start and stop, configure logging options, and request other customized configuration from Web Services without impacting the CoT developer group. Developer groups are how we match developers with Tomcat instances. These are Unix groups and are used to control file permissions, access to sudo commands, etc. Current Tomcat instances and developer groups are:

Tomcat
Instance
Unix Group Developer Group
1.cot n/a College of Technology Solr
2.elt tc-elt ITaP Enterprise Learning Technologies
3.cem n/a CEM Cyclone
4.frsty tc-frsty Forestry
5.recon tc-recon Reconnet
6.onep tc-onep OnePurdue SAP Basis Team

B.2 Where should I point CATALINA_HOME?

CATALINA_HOME is the Tomcat environment variable that defines where the files are that Tomcat shares across all instances. Of the standard Tomcat directories, lib (for common code) is relative to CATALINA_HOME. On Web Services Tomcat systems, CATALINA_HOME should be /usr/share/tomcat6.

B.3 Where should I point CATALINA_BASE?

To allow multiple instances of Tomcat to have different configurations, logging, applications, etc, Tomcat uses the environment variable CATALINA_BASE to indicate the directory where the instance-specific files are stored. The standard Tomcat directories conf, lib (shared), logs, temp, webapps, and work are relative to CATALINA_BASE. All files in these directories are private to your group’s instance of Tomcat. On Web Services Tomcat systems, CATALINA_BASE should be /opt/tomcat6-instance/<INSTANCE_NAME>, where INSTANCE_NAME is the Tomcat instance from the table above. For example, the ELT developers would use CATALINA_BASE set to /opt/tomcat6-instance/2.elt.

B.4 Why don’t I see a “common” or “server” sub-directory?

The common and server sub-directories were from versions of Tomcat up to 5.5 and were where Tomcat looked for files shared across all instances. These directories were found in CATALINA_HOME. In Tomcat 6 and following, they were combined into a single lib directory (also found in CATALINA_HOME). See the questions above.

B.5 What ports does my Tomcat instance use on the network?

Each Tomcat instance uses its own ports on the network. For each of the Tomcat instances listed in the table above, these ports are:

Tomcat
Instance
HTTP HTTPS
1.cot 8081 8444
2.elt 8082 8445
3.cem 8083 8446
4.frsty 8084 8447
5.recon 8085 8448
6.onep 8086 8449

You should only need to know these ports for testing your applications as we will map all of the applications into a single namespace using our F5 load balancers for QA and Production.

C The Tomcat Environment

C.1 What version of Linux is this?

We are running RedHat Enterprise Linux v6.

C.2 What version of Tomcat is this?

We are running Apache Tomcat version 6.

C.3 What version of the Java JDK or JRE is this?

We are running Sun Microsystems/Oracle JDK 1.6.0.

C.4 What is the Java Security Manager?

Java is known as a secure language for development because the JVM carefully controls what an application can do to the local host system. But as normally configured, the JVM makes no effort to control what an application can do to the JVM or to other applications running there. For example, nothing prevents an application from calling “system.exit(1)” and shutting down the entire JVM. The Java Security Manager is a standard part of Java that allows us to define policies about what operations code is allowed to perform on a fairly fine granularity. Because of the shared nature of our Tomcat environment, we have chosen to enable the Java Security Manager and will work with developers to enable appropriate privileges for their code.

C.5 How does the Java Security Manager work?

The Java Security Manager is configured with a set of policies that define permissions for different code bases. Code bases are individual class or JAR files. Permissions have been defined as part of the Java standard for such activities as reading or writing system properties, manipulating files, and for certain critical functions (such as system.exit()). Before performing one of these actions, a check is made to see if the current code base has the required permission to perform the operation. If it does, the operation continues normally. If not, the Java Security Manager throws a security exception, which typically will halt the application.

C.6 How do I figure out what permissions my code needs? It seems to run okay in DEV.

Because the Java Security Manager is unforgiving about policy violations, it makes developing code a chore. You have to deal with determining if the reason your application failed was a security violation or due to a problem with your code. Then, if the problem is a security violation, you have to wait for the policy to be updated to allow the operation. This kind of “start-stop” development would be counter productive and frustrating for developers. So we have developed a “profiling” security manager that runs on our DEV machine. It follows two basic rules:

  1. If the real security manager would allow the operation, then allow the operation.
  2. If the real security manager would forbid the operation, then log the permissions needed and allow the operation.

This allows developers to work on their code without worrying about the security policies initially. Then, once you have the code working, you’ll need to “profile” it by clearing a cache that the security manager maintains (to prevent too many repeated messages), and fully exercise your code, exploring all code paths you possibly can. Once completed, the resulting log can be used by Web Services to update the security policy on DEV, QA, and PROD to allow the needed operations. While it should be possible to migrate your code to QA from there and not have any security policy issues, it would be wise to profile it again to ensure that no additional permissions were missed.

Once the code goes to QA, the real security manager is in charge and any security exceptions will result in your application being halted. Code that runs cleanly (no security exceptions) under QA will run cleanly on PROD as well because the security policies will be identical. While profiling a new application may involve a fair amount of effort, profiling of updates to applications will be made easier by the fact that most of the permissions needed will already have been allowed and only new permissions will need to be identified.

C.7 This seems like a lot of work. Why don’t you just turn the Java Security Manager off? Don’t you trust us?

Web Services has chosen to enable the Java Security Manager for several reasons, but not trusting our developers is not one of them. We assume that our developers are professionals and would not perform malicious activities that threaten the security of Purdue’s systems. However, without the Java Security Manager, errant calls in other applications could easily threaten the stability of your application’s code. Our intent is to maintain a stable environment where errors in one application have a minimal chance of impacting the stability of other applications. Web Services will work with developers to identify the permissions their code needs to function correctly and will adjust the security policy to support this.

D The Development Environment

D.1 What development tools are available?

Our DEV system has the standard complement of Unix tools. In addition, revision control systems such as subversion and CVS, a selection of Java-oriented tools such as ant are installed on these machines. Web Services may provide limited support for configuring these tools.

D.2 I want to use tool “X”. Will you install it?

Please open a  ticket by sending email to itap-webadmin@purdue.edu. In your ticket, please describe the tool as completely as possible, along with justification for installing it. Such justification might include how widely the tool will be used, why an existing tool is inadequate, etc. A reference to a website where it can be obtained is quite helpful. Web Services will investigate whether we can support the tool.

D.3 What Java packages are available?

Many of the standard Java packages are available. Check in /usr/share/java to see what is currently installed.

D.4 I want to use Java package “X”. Will you install it?

Our experience has been that it is best if Tomcat applications are as self-contained as possible. So other than database drivers (which we provide for all ITIS-supported database platforms), it is best if your application contains all the necessary jar files for any packages you want to use. If this is not possible for some reason, please open a ticket by sending email to itap-webadmin@purdue.edu with as much information about the package as you can and we will work with you.

D.5 How do I restart Tomcat?

Each developer group should have the privileges to start/stop their own Tomcat instance in DEV. Use the commands:

Start Tomcat
sudo /sbin/service tomcat6-<INSTANCE> start
Stop Tomcat
sudo /sbin/service tomcat6-<INSTANCE> stop
Restart (stop then start) Tomcat
sudo /sbin/service tomcat6-<INSTANCE> restart
Get Tomcat’s status
sudo /sbin/service tomcat6-<INSTANCE> status
Get Tomcat, the JVM, and Linux versions
sudo /sbin/service tomcat6-<INSTANCE> version

If /sbin is part of your path (normally not), you can just use “sudo service ….” Replace “<INSTANCE>” with the name from the table shown before.

D.6 How do I deploy my application?

Most applications can be deployed in DEV by simply placing the WAR file in $CATALINA_BASE/webapps. Within a short time (15-30 seconds), Tomcat will notice the WAR file, will unpack it, and will deploy the application. If the application has already been deployed and a newer WAR file is dropped in, Tomcat will remove the old deployed application and unpacked files, and will redeploy the new version. Tomcat should not need to be restarted.

The exception to this is when your application does not have a context fragment defined in its META-INF directory. This context fragment is a small file name context.xml and is specific to Tomcat installations. By putting this file into your WAR file, you prevent Tomcat from creating a default entry for your application in its server.xml file. It is these default entries that get written when Web Services uses the administrator apps that can prevent your application from correctly auto-deploying without a restart. A minimal context.xml file contains:

<?xml version="1.0" encoding="UTF-8"?>

<Context>
</Context>

D.7 How do I migrate my application to QA? PROD?

You may use the Deploy Tool.

E SSL, Logging, Databases, etc.

E.1 Is SSL available? How do I make sure that my application uses it?

SSL is available on all three Tomcat tiers. To ensure that your application uses SSL, add a security constraint to your application’s web.xml file after your servlet-mappings but before closing your web-app as follows:

<security-constraint>
        <web-resource-collection>
                <web-resource-name>Protected Content</web-resource-name>
                <url-pattern>/*</url-pattern>
        </web-resource-collection>

        <user-data-constraint>
                <transport-guarantee> CONFIDENTIAL </transport-guarantee>
        </user-data-constraint>
</security-constraint>

Adjust or add url-pattern elements as needed to define where in your application SSL must be applied.

E.2 What logging packages are available?

We have installed Apache’s modification to the Java Utility Logging Interface (JULI) as well as the Log4J logging package.

E.3 How should I configure and use logging in my application?

First, do not use “system.out()”. This sends the output to Tomcat’s stdout file descriptor which then gets intermingled with other output from Tomcat. This will not only make it harder for you to find your logging output, but it will also cause the file that captures this output to grow unnecessarily. Besides, by using a logging package, you can embed verbose logging into your application to help you during development and debugging, and then select the level of output you actually want for production without changing your code.

You should configure your logging to be placed in a file in CATALINA_BASE/logs/applogs. The Java Security Manager has been configured to allow this. If you attempt to put them elsewhere, it will likely result in security exceptions.

JULI Logging

If you are using JULI logging, you will need to place a logging.properties file in either your application’s WEB-INF directory or in $CATALINA_BASE/lib. We recommend placing a default logging configuration file in the lib directory so that all applications have a basic logging facility available, then placing an application-specific configuration in the application’s WEB-INF to override these defaults where desired. Here is an example logging.properties file:

handlers = org.apache.juli.FileHandler

############################################################
# Handler specific properties.
# Describes specific configuration info for Handlers.
############################################################

org.apache.juli.FileHandler.level = FINE
org.apache.juli.FileHandler.directory = ${catalina.base}/logs/applogs
org.apache.juli.FileHandler.prefix = logDemo1.

############################################################
# Facility specific properties.
# Provides extra control for each logger.
############################################################

#org.apache.catalina.core.ContainerBase.[Catalina].[localhost].[/myApp].level = INFO

Please do not include a handler for the console (org.apache.juli.ConsoleHandler) as this will cause logging information to once again go to Tomcat’s stdout file descriptor. The logging will be created in a file called “logDemo1.2008-04-15.log” (with the current date, of course) in the log/applogs directory. The level of logging that actually makes it to the log can be set to one of:

  • SEVERE
  • WARNING
  • INFO
  • CONFIG
  • FINE
  • FINER
  • FINEST

You can also use the facility specific properties (the last commented line) to make changes to the logging for specific applications in a shared configuration environment. See http://java.sun.com/j2se/1.4.2/docs/api/java/util/logging/package-summary.html for details on JULI logging.

Log4J Logging

If you are using Log4J logging, you will need to place a log4j.properties file in either your application’s WEB-INF directory or in $CATALINA_BASE/lib. We recommend placing a default logging configuration file in the shared directory so that all applications have a basic logging facility available, then placing an application-specific configuration in the application’s WEB-INF to override these defaults where desired. Here is an example log4j.properties file:

log4j.rootLogger=ERROR, R

# ***** R is set to be a RollingFileAppender.
log4j.appender.R=org.apache.log4j.RollingFileAppender
log4j.appender.R.File=${catalina.base}/logs/applogs/logDemo2.log

# ***** Max file size is set to 100KB
log4j.appender.R.MaxFileSize=100KB

# ***** Keep one backup file
log4j.appender.R.MaxBackupIndex=1

# ***** R uses PatternLayout.
log4j.appender.R.layout=org.apache.log4j.PatternLayout
log4j.appender.R.layout.ConversionPattern=%d [%c] %p - %m%n

This will create a file called “logDemo2.log” in the log/applogs directory that will be automatically rolled to a new log file when it reaches 100K with one backup copy. Lines in the file will look like:

2008-04-08 12:21:41,298 [MyClass] FATAL – This is my fatal message.

See http://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/PatternLayout.html for details about the various pattern values you can use to format your log to your liking.

Change the word “ERROR” on the first line to one of:

  • FATAL
  • ERROR
  • WARN
  • INFO
  • DEBUG
  • TRACE
  • ALL

to control how much logging actually gets to your log file.

E.4 How can I review my logs in QA or Production?

Because developers do not have access to login to the QA and production machines, we have created a web site you can use to access your logs in these environments. Go to Linux Server Logs and follow the links to get to the log(s) you need to review. Be aware that some logs may be quite large so may take a while to transfer to your browser.

E.5 What database options are available?

We have installed JDBC drivers for mySQL, Oracle, and Microsoft SQL Server.

E.6 How do I request a database connection?

Web Services will create a JNDI reference in your Tomcat instance for your application. To do this, we need to know the type of database (mySQL, Oracle, SQL Servers, etc.), the name of the database, the server hosting the database, the database username, the database password, and what JNDI reference you want the database to have. Send this information (minus the password!) to itap-webadmin@purdue.edu to create a ticket. We will contact you to obtain the appropriate password via secure means.

For example, to access an Oracle database named “mydatabase” hosted by ITIS’s DBA group, you would request:

Dbase Type: Oracle 
Dbase Name: mydatabase 
Dbase Host: ITIS Oracle 
Dbase User: db_user 
Dbase Password: DO NOT PROVIDE THIS IN EMAIL!!! 
JNDI name: jdbc/myjndi

Or, if the same database were served by ITIS’s DBA group as a SQL Server database, you would request:

Dbase Type: SQL Server 
Dbase Name: mydatabase 
Dbase Host: itidbaprod02 
Dbase User: db_user 
Dbase Password: DO NOT PROVIDE THIS IN EMAIL!!!
JNDI name: jdbc/myjndi

DO NOT send the database username and password in email or in a ticket! Instead, send the message or create the ticket, and when we receive it, we’ll call you for the password (the username is safe). Also, if you do not know the database hostname and ITIS hosts the database, just tell us that and we’ll work with the DBAs to identify the host.

E.7 How do I reference this JNDI?

Add one or more ResourceLink entries to your META-INF/context.xml file such as:

<?xml version="1.0" encoding="UTF-8"?>

<Context> 
  <ResourceLink
    name="jdbc/ics/infdbd"
    global=jdbc/ics/infdbd"
    type="javax.sql.DataSource" />
</Context>



The name field specifies what the resource is known to your application by (what’s in your web.xml file), and the global field specifies what the resource is known by to the server (what’s in server.xml). Finally, the type field specifies what Java type the resource is.

E.8 I need/want to write a file to disk. Why won’t you let me?

As the load on the Tomcat systems increases or the need for ultra-high availability is demonstrated, we will be moving toward a clustered environment where multiple machines will be servicing requests to your applications. In such an environment, writing to a local file does not have well-defined semantics. On one access it might be there, and on the next, it is gone because the request went to another node in the cluster. Using a database is a much safer approach.