Tomcat installation and servlet development notes

These notes are intended to collect a number of key ideas and pointers for getting applications running in a Tomcat environment.

Contents:

Contents

  1. Tomcat installation and test
  2. Configuration
  3. Tomcat shutdown
  4. Enabling servlet logging
  5. Apache HTTPD Tomcat connector installation
    1. Configuring Tomcat to use the JK connector
  6. Notes for servlet developers
    1. Compatibility
    2. Tomcat and Jython
  7. Links

1. Tomcat installation and test

#Installation

(These notes for installation on Windows XP.)

There are more detailed notes for installing Tomcat here: http://www.coreservlets.com/Apache-Tomcat-Tutorial/.

2. Configuration

#Configuration

See the comcat configuration reference pages at http://tomcat.apache.org/tomcat-5.5-doc/config/index.html.

There is also a good pagae about servlet configuration in general at http://java.sun.com/developer/Books/javaserverpages/servlets_javaserver/servlets_javaserver05.pdf.

3. Tomcat shutdown

Sometimes tomcat fails to respond to the shutdwon command. This appears to happen mainly when prior to initialisation (which may take a prohibitively long time or never be completed if tomcat is not given enough memory) or when tomcat is running but memory in the system is too low for a new JVM to be started. The solution is the command "killall -9 java" when run as the tomcat user seems to work reliably. This will send all processes with the name "java" signal 9, killing them with prejudice. Do not use this command if you have other running java programs you do not wish to kill.

4. Enabling servlet logging

#EnablingServletLogging

In Tomcat 5.5, servlet diagnostics do not automatically appear in the Tomcat logs. To obtain diagnostic information reported by servlet code through the Apache logging system, it may be necessary to configure additional log handlers as described in http://tomcat.apache.org/tomcat-5.5-doc/logging.html.

In summary:

The format of log output messages is controlled by the ...layout.ConversionPattern property value. See http://logging.apache.org/log4j/docs/api/org/apache/log4j/PatternLayout.html for details.

The first line of the log4j.properties file above configures the root logger to send DEBUG level information to a new appender called 'R'. The following statements configure this appender. The final statement adjusts the level of information generated by classes in package org.apache.catalina

To suppress voluminous output from XML parsing, add the following line to the log4j configuration: 

log4j.logger.org.apache.commons.digester=SEVERE, R

5. Apache HTTPD Tomcat connector installation

#JKConnector

The connector known as mod_jk appears to be the favoured way to use Apache HTTPD to field HTTP requests that are handled by Tomcat. mod_jk2 was a later project, but has been relegated to "maintenance mode" due to lack of developer interest and configuration complexity.

The following notes refer to installation on Scientific Linux.

  1. Download source from http://www.apache.org/dist/tomcat/tomcat-connectors/jk/source/jk-1.2.15/jakarta-tomcat-connectors-1.2.15-src.tar.gz

  2. Unpack the tar file into a working directory. We have used /opt/jakarta-tomcat-connectors/.

  3. Change to the root of the unpacked directory tree and run configure (look out for helpful files {{jk/BUILD.txt}}} and jk/native/BUILDING): 

    • cd /opt/jakarta-tomcat-connectors/jakarta-tomcat-connectors-1.2.15-src/jk/native 
./configure --with-apxs=/usr/sbin/apxs
      Our initial attempot failed with: 'configure:5145: error: C++ preprocessor "/lib/cpp" fails sanity check'. The diagnostics aren't illuminating, but we think it's because C++ has not been installed. So try: 
      yum install libstdc++ gcc-c++ compat-libstdc++
      Now, the ./configure commands runs OK.
  4. Run make: 
    • make 
su -c 'make install'

      This can take a few minutes. When complete, the file mod_jk.so will be created in /usr/lib/httpd/modules/ (also linked as /etc/httpd/modules/.

  5. Create config files for the JK connector. We have placed these files in directory /etc/httpd/conf.d/, as they both relate to the httpd end of the connector. File /etc/httpd/conf.d/jk_mod.conf: 

    • <IfModule !mod_jk.c> 
   LoadModule jk_module modules/mod_jk.so
</IfModule>

JkWorkersFile "/etc/httpd/conf.d/workers.properties"
JkLogFile "/var/log/httpd/mod_jk.log"

# JkLogLevel emerg
JkLogLevel debug

JkMount /shibboleth-idp/* ajp13w
JkMount /jsp-examples/* ajp13w

      File /etc/httpd/conf.d/workers.properties: 

      # workers.properties.minimal - 
#
# This file provides minimal jk configuration properties needed to
# connect to Tomcat.
#
# The workers that jk should create and work with
#

worker.list=wlb,jkstatus,ajp13w

#
# Defining a worker named ajp13w and of type ajp13
# Note that the name and the type do not have to match.
#
worker.ajp13w.type=ajp13
worker.ajp13w.host=localhost
worker.ajp13w.port=8009

#
# Defining a load balancer
# 

worker.wlb.type=lb
worker.wlb.balance_workers=ajp13w

#
# Define status worker
#

worker.jkstatus.type=status

      With these files in place, when we retsrat httpd and browse to /jsp-examples/ on the web server, we see an internal server failure error, but the log files indicate that the connector is indeed looking for an ajp13 connection: 'Could not find a worker for worker name=ajp13'. Notes:

      • the connector name (ajp13w in the above examples) must be mentioned in the worker.list value in file workers.properties

      • the file jk.conf must use the work name (not worker type) in the JkMount commands that redirect requests via JK to Tomcat.

5.1. Configuring Tomcat to use the JK connector

Edit file /opt/apache-tomcat/apache-tomcat-5.5.16/conf/server.xml, so that the element <Service name="Catalina"> contains this connector configuration, with the address="127.0.0.1" to prevent off-host access to the Tomcat instance via the AJP connector protocol: 

<!-- Define an AJP 1.3 Connector on port 8009 --> 
<Connector port="8009"
           enableLookups="false" redirectPort="8443" protocol="AJP/1.3"
           address="127.0.0.1"
           tomcatAuthentication="false"
           />

The Shibboleth installation instructions refer to an <Ajp13Connector> element in server.xml, but this appears to be incorrect; a <Connector> element is used. They also mention setting request.tomcatAuthentication="false", but this appears to be specific to the JK2 connector (which we are not using), and ahould in any case be applied in a JK2 properties file.

The tomcatAuthentication="false" attribute supported by the AJP protocol connector tells Tomcat to not use its internal (primitive) authentication mechanism, but instead to use remote authentication provided by the front-end web server. This is also explained in http://tomcat.apache.org/tomcat-5.5-doc/config/ajp.html.

I also found this commentary (http://lists.samba.org/archive/jcifs/2003-July/002393.html) if you are using the AJP14 connector, you would edit server.xml: 

<Connector className="org.apache.ajp.tomcat4.Ajp13Connector" 
    tomcatAuthentication="false" port="8009" minProcessors="5"
    maxProcessors="75" acceptCount="10" debug="0"/>

The important part is the "tomcatAuthentication" attribute, which tells tomcat to use the authentication provided by the web server (otherwise, the request object won't be populated with the remote user from IIS). If you are using the Coyote JK2 connector, the equivalent setting would be added to the jk2.properties file: 

request.tomcatAuthentication="false"

6. Notes for servlet developers

6.1. Compatibility

6.2. Tomcat and Jython

(TBA)

7. Links

-- GrahamKlyne 2005-11-04 14:46:10

TomcatNotes (last edited 2006-07-12 15:14:09 by StuartYeates)

Creative Commons License
The content of this wiki is licensed under the Creative Commons Attribution-ShareAlike 2.0 England & Wales Licence.
OSS Watch is funded by the Joint Information Systems Committee (JISC) and is situated within the Research Technologies Service (RTS) of the University of Oxford.