Server.xml Configuration in Tomcat 3.3

General configuration

Tomcat 3.3 is implemented using a set of modules. Each module has a number of settable properties and implements one or more 'hooks', providing a piece of functionality.

The modules can be configured and assembled in several ways, but the default and most flexible mechanism uses XML files. Each module is described by an XML element, with attributes used to set module properties. The main configuration file is located in TOMCAT_HOME/conf/server.xml, used to configure the server. Additional TOMCAT_HOME/conf/server-name.xml files will be read after server.xml, allowing local configurations.

Variable substitution

In Tomcat 3.3.1, each attribute value may use the ant-style variable substitution by using "${variable}" in the attribute string, i.e. attribute="text${variable}text". (Note: A bug prevented this from working in Tomcat 3.3.)

The variable must specify a ContextManager property or System property, with ContextManager properties taking precedence. If a matching property isn't found, the attribute string is left as is. Note that the properties are not the same as attributes, and attributes are not accessible via variable substitution.

There are two predefined ContextManager properties, "tomcat.home" and "tomcat.install". These correspond to the ContextManager home and installDir attributes, respectively. There are three methdos for setting additional ContextManager properties.

1. Include a name="value" specification on the ContextManager element in server.xml, where name doesn't correspond to a ContextManager attribute. For example:
   

       <ContextManager ... my.prop="myvalue" ... >

2. Include a Property element within the scope of the ContextManager element in server.xml. For example:
   

       <ContextManager ... >
           <Property name="my.prop" value="myvalue" />
           ...
       </ContextManager>

   This form of setting properties is logged if the ContextManager's debug level is one or greater.
   
   
3. Include "-name value" as command line arguments, where name doesn't match any of the arguments supported by the "start" task. For example:
   

       bin/startup -my.prop myvalue

Note: The property values may themselves use "variable substitution", provided the specified property is already defined.

Common Parameters

All modules have the following common attributes:

Configuration Elements

Server.xml is an XML document. Most elements correspond to Tomcat modules, with Java setters being automatically associated with element attributes. The javadoc will contain most details, in this document we focus on the common and supported behaviors.

Parent Configuration Elements

The purpose of the server.xml is to define the configuration of an instance of the Tomcat 3.3 web server. The parent configuration elements in the server.xml file represent that instance.

Server

This is the main element in server.xml. It has a single child describing the tomcat configuration, ContextManager.

Examples

<Server>
   <ContextManager > 
      ... ( tomcat configuration )
   </ContextManager>
</Server>

ContextManager

Description

This is the main tag, used to set generic Tomcat options. The following are some of the childen it supports:

<module_name>

Adds a module to the configuration. Module names are defined in modules.xml, where each tag is associated with a class name that implements the module. Each element attribute corresponds to a setter method in the implementing class.

<Context>

Defines a web application. This is a legacy method of specifying a web application. It is included for backward compatibility with older Tomcats. As a rule, applications should be defined in separate config files, named apps-name.xml. This way you can configure your web applications without modifying your server.xml file.

<Property name="property_name" value="property_value">

Adds arbitrary name/values to ContextManager. The properties can be used for variable substitutions, instead of attributes.

<module name="module_name" javaClass="full.class.name">

Adds a module to the configuration. All modules included in the standard distribution are defined in modules.xml, but you can define additional tags and their associated class in server.xml. This behaves like taskdef in ant.

Attributes

Example(s)

<ContextManager install="/opt/tomcat" workDir="/var/tomcat" home="/var" />

Module Configuration Elements

It is the set of modules and their configuration that control the behavior of the Tomcat web server. By specifying which modules and their attributes, you have a lot of flexibility in controlling the features of your instance of Tomcat.

Note that "interceptor" is a name that used in the past, prior to the adoption of the name "module". It should be considered synonomous with "module". "Interceptor" will appear various in places, especially in module names and their classes.

The list of modules below is in alphabetical order. Functionally, they may be grouped as follows:

• Access, Authentication, and Authorization
  • AccessInterceptor
  • CredentialsInterceptor
  • JDBCRealm
  • SimpleRealm
• Configuration
  • ApacheConfig
  • AutoDeploy
  • AutoWebApp
  • ContextXmlReader
  • IISConfig
  • JservConfig
  • LoaderInterceptor11
  • LogSetter
  • MxInterceptor
  • NSConfig
  • PolicyLoader
  • TrustedLoader
  • WorkDirSetup
• Generators
  • ErrorHandler
  • InvokerInterceptor
  • Jdk12Interceptor
  • StaticInterceptor
• Servlet 2.2 Facade
  • WebXmlReader
  • JspInterceptor
  • Servlet22Interceptor
  • LoadOnStartupInterceptor
  • TagPoolManagerInterceptor
• Loggers
  • AccessLogInterceptor
  • LogEvents
• Mappers
  • DecodeInterceptor
  • ReloadInterceptor
  • SimpleMapper1
• Server
  • CoyoteConnector
  • Http10Connector
  • JniConnector
  • Ajp12Connector
  • Ajp13Connector
• Session
  • SimpleSessionStore
  • SessionIdGenerator
  • SessionExpirer
  • SessionId

AccessInterceptor

Type: Access, Authentication, and Authorization

Description

Determines if security constraints specified in the web.xml apply to a request and provides the handling for BASIC and FORM authentication if necessary.

Attributes

Example(s)

<AccessInterceptor />

AccessLogInterceptor

Type: Loggers

Description

Creates log files in the style of the Apache servers "AccessLog".

Attributes

        '%h %l %u %t "%r" %>s %b "%{Referer}" "%{User-Agent}"'
        '%h %l %u %t "%r" %>s %b'
      

              GET /index.html?frame=main HTTP/1.0
            

              [20/Apr/2001:19:45:23 0200]
            

Example(s)

<AccessLogInterceptor format="common" />

Ajp12Connector

Type: Server

Description

Handles incoming Ajp12 requests. Ajp12 is a protocol used by the mod_jk based web server connectors and the mod_jserv connector. Also, used for shutting down Tomcat.

Attributes

Example(s)

<Ajp12Connector port="8007" ajpidFile="conf/ajp12_2.id" />

Additional note:

If using Ajp12Connector to shutdown Tomcat, the minimum of 2 threads have to be configured, or the shutdown will not be successful. Default configuration (no maxThreads) configures more then 2 threads and should work fine.

You need two threads since one is always supposed to be listening, and the other does the actual shutting down. Since the shutdown thread tries to unblock the listening thread, it hangs if there isn't anyone listening.

Ajp13Connector

Type: Server

Description

Handles incoming Ajp13 requests. Ajp13 is a protocol used by the mod_jk based web server connectors.

In Tomcat 3.3.1, some attributes were added for supporting password protected shutdown using Ajp13. This feature is actived by setting the shutdownEnable to true, or setting a password using the secret or useSecret attributes. Also, if a password is set, authentication of Ajp13 connections can also be performed. This feature requires the authenticateRequests attribute be set true in addition to a password, and the mod_jk based connector support this feature. The connectors available with Tomcat 3.3.x do not support this feature. Connectors that do support this feature will be made available through the jakarta-tomcat-connectors project.

Attributes

Example(s)

<Ajp13Connector port="8009" tomcatAuthentication="false" />

ApacheConfig

Type: Configuration

Description

Generate configuration file for mod_jk to be included in Apache's httpd.conf.

For additional information on connecting Tomcat to Apache via mod_jk, see the Working with mod_jk document.

Important Note: The configuration files are not written as part of a normal startup of Tomcat. To generate the configuration files on demand, append:

    jkconf

or

    -jkconf

to the startup command. Tomcat will initialize sufficiently to write the configuration files and then exit. This may be done while Tomcat 3.3 is running. To generate the configuration files during normal startup, add:

    jkconf="true"

to the <ContextManager ... > element in the server.xml file.

Attributes

Example(s)

<ApacheConfig forwardAll="true" noRoot="false" />

AutoDeploy

Type: Configuration

Description

Automatically expands WAR files on startup.

Note: If the redeploy attribute is true and a ReloadInterceptor is present, then WAR files will re-deploy automatically while Tomcat 3.3 is running.

Attributes

Example(s)

<AutoDeploy source="webapps" target="webapps" />

AutoWebApp

Type: Configuration

Description

Automatically adds web application contexts from a directory.

Attributes

Note: The special directory name handling controlled by hostChar, hostDotChar, and pathSlashChar is always enabled. If you wish to include '_' characters in a web application directory name, disable the feature by redefining the pathSlashChar to an empty string.

Example(s)

  <AutoWebApp dir="webapps" host="DEFAULT" />
  <AutoWebApp dir="myhost" host="myhost.com" />
  <AutoWebApp dir="webapps" pathSlashChar="" />

ContextXmlReader

Type:Configuration

Description

Reads the XML files that define contexts to be served by Tomcat. You specify a single file to read. However, in addition to that file, all other files in the same directory will be read that match the pattern "base-*.xml", where base is the base name (i.e. name without extension) of the file you specified. Each file may configure one or more contexts. Where the context matches a context automatically created by the AutoWebApp module, the configuration file will override the default context settings.

For details on the syntax of the context configuration file, refer to the Adding and Customizing Contexts section of the Tomcat 3.3 Users Guide.

Note: In Tomcat 3.3.1, ant-style variable substitution is supported in the XML files. Details are included in the "Adding and Customizing Contexts" section mentioned above.

Attributes

Example(s)

  <ContextXmlReader config="conf/myapps.xml" />

CredentialsInterceptor

Type: Access, Authentication, and Authorization

Description

Extracts the user name and password from a request and makes the information available for another module to perform the authentication. It currently supports extracting user name and passwords from BASIC and FORM based authetication.

This module must appear prior to the "realm" module that performs the authentication.

Attributes

This module has no user settable attributes.

Example(s)

<CredentialsInterceptor />

DecodeInterceptor

Type: Mappers

Description

Handles the task of establishing the encoding of a request. It also handles optionally normalizing the request and optionally checking the request for unsafe escape sequences.

Attributes

Example(s)

<DecodeInterceptor useSessionEncoding="true" >

ErrorHandler

Type: Generator

Description

Handles response generation when a request encounters an error. Calls the appropriate error handler if specified, or generates the default error response if not specified.

Attributes

Example(s)

<ErrorHandler showDebugInfo="false" />

CoyoteConnector

Type: Server

Description

Handles incoming AJP13 and HTTP, or optionally HTTPS, requests. [Tomcat 3.3.2]

Attributes

Note: You may specify attributes that do not appear in the list above. These attribute settings will be saved in a list and made available to the secure socket factory when secure is set true. Supported attributes are:

PureTLS

JSSE

Example(s)

<CoyoteConnector port="8080" timeout="60" />

Http10Connector

Type: Server

Description

Handles incoming HTTP, or optionally HTTPS, requests.

Attributes

Note: In Tomcat 3.3.1 and later, you may specify attributes that do not appear in the list above. These attribute settings will be saved in a list and made available to the secure socket factory when secure is set true. Supported attributes are:

PureTLS

JSSE

Example(s)

<Http10Interceptor port="8080" timeout="60" />

IISConfig

Type: Configuration

Description

Generate configuration files for isapi_redirect.dll to be used for connecting IIS to Tomcat. In Tomcat 3.3, two files will be generated, iis_redirect.reg and uriworkermap.properties. Both files will be written to conf/auto relative to TOMCAT_HOME. The iis_redirect.reg contains the needed registry entries for the iis_redirect.dll. You may enter the settings into the registry by double-clicking on this file in Windows Explorer. The uriworkermap.properties file will be read by the isapi_redirect.dll to get the mappings that determine which requests should be passed to Tomcat.

In Tomcat 3.3.1, an additional file is written. The default is to write an isapi_redirect.properties file to the same directory as the iis_redirect.reg file. It contains the same configuration information as the iis_redirect.reg, and offers an alternative method of configuring the redirector instead of relying on the registry. See the document mentioned in the next paragraph for details on its use.

For additional information on connecting Tomcat to IIS, see the Tomcat IIS HowTo document.

Important Note: The configuration files are not written as part of a normal startup of Tomcat. To generate the configuration files on demand, append:

    jkconf

or

    -jkconf

to the startup command. Tomcat will initialize, write the configuration files, and then shutdown. This may be done while Tomcat 3.3 is running. To generate the configuration files during normal startup, add:

    jkconf="true"

to the <ContextManager ... > element in the server.xml file.

Attributes

Example(s)

<IISConfig forwardAll="true" noRoot="false" />

InvokerInterceptor

Type: Generator

Description

Provides support for the "/servlet/class name" legacy method of invoking servlets.

Attributes

This module has no user settable attributes.

Example(s)

<InvokerInterceptor />

JDBCRealm

Type: Access, Authentication, and Authorization

Description

Authenticates the user if required for a request. The authentication occurs using data from "user" and "user roles" tables accessed using a JDBC connection.

Attributes

Example(s)

<JDBCRealm driverName="sun.jdbc.odbc.JdbcOdbcDriver" 
              connectionURL="jdbc:odbc:TOMCAT" 
              userTable="users"
              userNameCol="user_name" 
              userCredCol="user_pass" 
              userRoleTable="user_roles" 
              roleNameCol="role_name" />

Jdk12Interceptor

Type: Generator

Description

Ensures that the proper context classloader is in effect during servlet execution.

Attributes

This module has no user settable attributes.

Example(s)

<Jdk12Interceptor />

JniConnector

Type: Server

Description

Handles requests processed by Tomcat running in-process. It has no effect if Tomcat was not started in-process by the Tomcat connector.

Attributes

Example(s)

<JniConnector nativeLibrary="bin/jni_connect.so" />

JservConfig

Type: Configuration

Description

Generate configuration file for mod_jserv to be included in Apache's httpd.conf.

For additional information on connecting Tomcat to Apache via mod_jserv, see the Tomcat Apache HowTo document.

Important Note: The most stable and robust connector for connecting Tomcat 3.3 to Apache is mod_jk. Its use is recommended over mod_jserv. Also, unlike the ApacheConfig, IISConfig, and NSConfig modules, JservConfig does not participate in the "jkcont" startup option. Instead, the configuration file is written each time Tomcat is started.

Attributes

Example(s)

<JservConfig forwardAll="true" noRoot="false" />

JspInterceptor

Type: Servlet 2.2 Facade

Description

Handles turning a JSP page into a loaded servlet for execution. Execution for the loaded servlet is handled the same as any other servlet. It uses Jasper for translating the JSP to a Java file, then performs compilation to a class file directly rather than using Jasper for the class compilation.

There is support for using Sun's javac Java compiler as well as IBM's Jikes Java compiler.

Attributes

Example(s)

<JspInterceptor keepGenerated="false" />
<JspInterceptor javaCompiler="jikes" />

LoaderInterceptor11

Type: Configuration

Description

This module constructs and sets the classloader for each context. It supports the Servlet 2.2 spec by including WEB-INF/classes and the Jars in WEB-INF/lib in the classloader. The available attributes allow control over the context classloader's parent. With the default attributes, "trusted" contexts get the Server Classloader as their parent and "untrusted" contexts get the Apps Classloader as their parent.

Attributes

Example(s)

<LoaderInterceptor11 jaxp="true" />
<LoaderInterceptor11 jaxp="true" use11Loader="true"/>

Additional Note

For Tomcat 3.3.1 and later, LoaderInterceptor11 also supports an additionalJars Context property that works the same as the module's additionalJars attribute for that context only. If additionalJars is specified as a Context property and as a LoaderInterceptor11 attribute, both lists are added. For information on setting Context properties, see Adding and Customizing Contexts in the Tomcat 3.3 User's Guide.

LoadOnStartupInterceptor

Type: Servlet 2.2 Facade

Description

Handles pre-loading of servlets specified as <load-on-startup> in a Context's web.xml file.

Attributes

This module has no user settable attributes.

Example(s)

<LoadOnStartupInterceptor />

LogEvents

Type: Configuration

Description

This module enables logging of when module methods are called. The log output goes to the ContextManager's log channel. Event logging is automatically enabled if the ContextManager's debug level is set greater than 5.

Attributes

Example(s)

<LogEvents enabled="true" />

LogSetter

Type: Configuration

Description

Configures a log channel.

Attributes

Example(s)

<LogSetter name="tc_log" verbosityLevel="DEBUG" />
<LogSetter name="servlet_log" timestamps="true"
    verbosityLevel="INFORMATION" path="logs/servlet-${yyyyMMdd}.log" />

MxInterceptor

Type: Configuration

Description

JMX MBeans support has been added to Tomcat 3.3.2, which allow you to manage Tomcat from any JMX console (JRMP) or via a simple browser by the build in HTTP Adaptor

To enable JMX, you should add the optional JmxSupport module to the $TOMCAT_HOME/modules directory.

To also activate the HTTP/JRMP Adaptor you should at least define the port

Attributes

Example(s)

<MxInterceptor type="HTTP" port="8999" host="mysystem" authentication="basic" user="admin" password="changeillico" />

NSConfig

Type: Configuration

Description

Generate configuration files for nsapi_redirect.dll to be used for connecting Netscape Web Server to Tomcat. An obj.conf will be written to conf/auto relative to TOMCAT_HOME. The contents of this obj.conf will need to be merged with the obj.conf file being used for the disired server.

For additional information on connecting Tomcat to Netscape, see the Tomcat Netscape HowTo document.

Important Note: The configuration files are not written as part of a normal startup of Tomcat. To generate the configuration files on demand, append:

    jkconf

or

    -jkconf

to the startup command. Tomcat will initialize, write the configuration files, and then shutdown. This may be done while Tomcat 3.3 is running. To generate the configuration files during normal startup, add:

    jkconf="true"

to the <ContextManager ... > element in the server.xml file.

Attributes

Example(s)

<NSConfig forwardAll="true" noRoot="false" objectName="tomcat" />

PolicyLoader

Type: Configuration

Description

Installs a security manager and/or a policy file if Tomcat is started with "sandbox" enabled. This module has no effect if you specify a "-Djava.security.policy=..." in the startup command for the Java VM. Setting the policy on the command line is the preferred method.

Attributes

Example(s)

<PolicyLoader securityManagerClass="java.lang.SecurityManager"
    policyFile="conf/tomcat.policy" />

ReloadInterceptor

Type: Mappers

Description

Handles reloading of servlets and contexts.

Attributes

Example(s)

<ReloadInterceptor fullReload="true" />

Servlet22Interceptor

Type: Servlet 2.2 Facade

Description

Handles some miscellaneous tasks that help implement behavior related to the Servlet 2.2 specification.

Attributes

This module has no user settable attributes.

Example(s)

<Servlet22Interceptor />

SessionExpirer

Type: Session

Description

Handles actual descruction of expired sessions.

Attributes

Example(s)

<SessionExpirer checkInterval="120" />

SessionId

Type: Session

Description

Handles associating sessions with requests and responses.

Attributes

Example(s)

<SessionId cookiesFirst="true" noCookies="false" />
<SessionId noCookies="true" />
<SessionId noCookies="true" checkSSLSessionId="true"/>

SessionIdGenerator

Type: Session

Description

Creates new session IDs when needed for a request. If the randomFile is not available, the class specified by randomClass will be used. In this case, initialization of class occurs on the first request requiring a session.

Note: The initialization for the java.security.SecureRandom class can take a relatively long time. For development purposes, you may speed this up by specifying java.util.Random as the randomClass setting. This should be done only for development since the random sequence generated by java.util.Random is predictable.

Attributes

Example(s)

<SessionIdGenerator randomClass="java.security.SecureRandom"
    randomFile="/dev/urandom" />

SimpleMapper1

Type: Mapper

Description

Handles the mapping of requests to the appropriate context.

Attributes

Example(s)

<SimpleMapper1 />

SimpleRealm

Type: Access, Authentication, and Authorization

Description

Authenticates the user if required for a request. It compares the user name and password information provided by the CredentialsInterceptor against data in memory obtained from an XML file.

Since passwords are stored in text form, you should not use this module when security is important. Replace this module with a more secure one, such as the JDBCRealm.

This module must follow the CredentialsInterceptor.

Attributes

Example(s)

<SimpleRealm filename="conf/users/users.xml" />

XML file format:

<tomcat-users>
  <user name="user name" password="password" roles="role[,role]" />
</tomcat-users>

SimpleSessionStore

Type: Session

Description

Creates, stores, and maintains session objects in a simple in-memory pool.

Note: This module must follow the SessionId module.

Attributes

Example(s)

<SimpleSessionStore maxActiveSessions="-1" />

StaticInterceptor

Type: Generator

Description

Generates the response for requests that map to static files or directories. The display of directory listings may be disabled.

In Tomcat 3.3.1, some additional attributes were added to allow control of locale and character encoding of directory listings.

Attributes

Example(s)

<StaticInterceptor listing="false" />
<StaticInterceptor listing="true"
        useAcceptLanguag="true" useCharset="locale"/>
<StaticInterceptor listing="true"
        useAcceptLanguag="true" useCharset="UTF-8"/>
<StaticInterceptor listing="true"
        useAcceptLanguag="false" useCharset="locale"/>

TagPoolManagerInterceptor

Type: Servlet 2.2 Facade

Description

Handles an enhancement to tag libary support by managing a pool tag objects. Tag objects will be created the first time a JSP page runs. After use the tag objects are placed in a pool. The next time the JSP page runs, the tag objects are retrieved from the pool rather than recreated.

If this module is not present, tag objects can't be retrieved from the pool and tag objects are created for each use.

Attributes

This module has no user settable attributes.

Example(s)

<TagPoolManagerInterceptor />

TrustedLoader

Type: Configuration

Description

Provides special handling for "trusted" contexts which have a interceptors.xml file in their WEB-INF directory. This file can specify modules to be added to the server as if they were specified in the server.xml file.

Attributes

This module has no user settable attributes.

Example(s)

<TrustedLoader />

WebXmlReader

Type: Servlet 2.2 Facade

Description

Reads the WEB-INF/web.xml file for each context.

Attributes

Example(s)

<WebXmlReader validate="false" />

WorkDirSetup

Type: Configuration

Description

Set the "work" directory for contexts which don't have the "work" directory specified explicitly.

Attributes

Example(s)

<WorkDirSetup cleanWorkDir="false" workDirBase="work" />