Tomcat Server.xml Explained

Tomcat containers are objects that can contribute to the request-response communication between clients (e.g.  browsers) and the targeted servlets. There are several types of Tomcat containers, each of which is configured within the tomcat server.xml based upon its type.

The Server Container

 

It is used as a top-level element for a single Tomcat instance; it is a simple singleton element that represents the entire Tomcat JVM. It may contain one or more Service containers. The server container is defined by the org.apache.catalina.Server interface.
Below are the possible attributes that can be set for the <Server> element.

Attribute         Description
---------------------------------------------
className         Names the fully qualified Java name of the class that implements the org.apache.catalina.Server interface. If no class name is specified, the default implementation is used, which is the org.apache.catalina.core.StandardServer.

address            This attribute specifies the TCP/IP address on which this server listens for the shutdown command. The default value is localhost, which means that the server can be shut down from the same machine where it is installed (i.e., remote shutdown is disabled).

port            Names the TCP/IP port number on which the server listens for a shutdown command. If you’re running Tomcat as daemon (i.e.,as Windows service), you can disable shutdown port by setting this value to -1. This attribute is required.

shutdown        Defines the command string that must be received by the server on the configured address and port to shut down Tomcat. This attribute is required.

The default server.xml distributed with Tomcat uses following code snippet to configure the server container:

<Server port="8005" shutdown="SHUTDOWN">
…
</Server>

The <Server> element must be the root XML element in server.xml file, and cannot be configured as the child of any element. However, it can be configured as the parent of other XML elements. The allowed nested child XML elements for <Server> component are – <Service> element, which we discuss in the next section, and – <GlobalNamingResources> element, used for configuration of global JNDI resources.

The Service Container

The service container is configured using the <Service> XML element in the server.xml. The service container holds a collection of one or more connectors, and a single engine container. The service container is configured as a nested XML element within the <Server> element. Multiple service containers can be configured within the same server container. The service container element is defined by the org.apache.catalina.Service Java interface.

The Configurable Attributes of the <Service> XML Element

Attribute         Description

className         Names the fully qualified Java name of the class that implements the org.apache.catalina. Service interface. If no class name is specified, the implementation will be used, which is the org.apache.catalina.core.StandardService.

name             Defines the display name of the defined service. The service name must be unique within the enclosing server container. This value is used in all Tomcat log messages. This attribute is required.

The only <Service> definition that can be found in the default server.xml file is the Catalina service:

<Service name="Catalina">
…
</Service>

The <Service> XML element is configured as a child of the <Server> element. As we mentioned before, multiple connectors and a single engine container can be configured for each service container. Allowed nested XML elements within <Service> element are:

— the <Connector> element.
— the <Engine> element.

 

The Engine Container

 

Engine container represents the heart of the request-processing mechanism in Tomcat. It is responsible for processing all incoming requests from configured connectors, and returns the processed response back to the connector for dispatching to the calling client. Engine container is configured in the server.xml file using the <Engine> XML element. Each defined service container can have one and only one engine container, and this single engine receives all requests received by all of the defined connectors. The <Engine> element must be nested after the <Connector> elements, inside its owning <Service> element.
The <Engine> element is defined by the org.apache.catalina.Engine interface. See below desc for the possible <Engine> element attributes.

Attribute         Description

className         Names the fully qualified Java name of the class that implements the org.apache.catalina.Engine interface. If no class name is specified, the implementation is used, which is the org.apache.catalina.core .StandardEngine.

defaultHost        Names the host name to which all requests are defaulted if not otherwise named. The name specified must reference a host defined by a child <Host> element. This attribute is required.

Name            Defines the logical name of this engine. The name defined is used in log messages, and must be unique within the server component that this engine belongs to. This attribute is required.

backgroundProcessorDelay Defines the delay time in seconds before the child containers’ background processes will be invoked, in case they are executing in the same thread. This background processing thread is responsible for live web application deployment tasks. The default value is 10.

jvmRoute        String identifier appended to every session in load balancing scenarios. It’s used to enable the front-end load balancer to send requests with the same session identifier to same Tomcat instances. If configured, the value of jvmRoute must be unique among all servers in a cluster.

The following code snippet contains the <Engine> element defined in the default server.xml file:

<Engine name="Catalina" defaultHost="localhost">

The <Engine> element is configured as a child of the <Service> element, and as a parent to the following elements:

- <Host>: Used to configure host container, which is discussed in the next section.
- <Realm>: Used to configure Tomcat’s security realm.
- <Valve>: Used to configure Tomcat’s valve.
- <Listener>: Used to configure Tomcat’s listener, which is used to react on events occurring internally in the Tomcat engine.

The Host Container

 

The host container links the server machine where the Tomcat is running to the network name (for example, www.techpaste.com or 174.27.12.241). The host container is configured using the <Host> XML element within the <Engine> element. Each <Host> can be a parent to one or more web applications, represented by a context container.

You must define at least one <Host> for each <Engine> element, and the name of one defined host must match the defaultHost attribute of the parent engine container. The default <Host> element is usually named localhost.

The Attributes of the <Host> Element

Attribute        Description
className         Names the fully qualified Java name of the class that implements the org.apache.catalina.Host interface. If no class name is specified, the implementation is used, which is the org.apache.catalina.core.StandardHost. This attribute is required.

Name            Defines the hostname of this virtual host. This attribute is required and must be unique among the virtual hosts running in this servlet container. This attribute is required.

appBase            Defines the directory for this virtual host. This directory is the pathname of the web applications to be executed in this virtual host. This value can be either an absolute path or a path that is relative to the CATALINA_HOME directory. If this value is not specified, the relative value webapps is used.

xmlBase            The directory location of the XML deployment descriptors that are deployed to this host. If not specified, the path [engine_name]/[host_name] is specified.

createDirs        Specifies whether the directories specified in appBase and xmlBase attributes should be created on Tomcat startup. The default value is true.

autoDeploy        Specifies whether Tomcat should check for new or updated web applications to be deployed to this host. The default is true.

backgroundProcessorDelay The delay time in seconds between the background process method invocation on this container and any child containers. This background process is responsible for webapp deployment tasks. The default value is -1, which means that this host will rely on the delay setting of its parent engine.

deployIgnore        The regular expression pattern that specifies directories to skip when performing auto deployment, for example *.svn* will skip deployment of the SVN files in case your web applications are deployed directory from an SV version control system.

deployOnStartup        Specifies if the web applications found in appBase and xmlBase directories should be deployed on server startup. The default value is true.

If you’re using the Tomcat’s default StandardHost implementation, you can use the additional attributes listed below

Attribute         Description

unpackWARs         Determines if WAR files should be unpacked or run directly from the WAR file. If not specified, the default value is true.

workDir             Specifies the work directory for all web applications deployed to this host. If not specified, the default value is CATALINA_HOME/work.

copyXML             If set to true, the context configuration file specified within the web application (/META-INF/context.xml) should be copied to the xmlBase directory. The default value is false.

deployXML         Specifies whether the context configuration supplied with web application (/META-INF/context.xml) should be parsed during web application deployment. Default value is true.

errorReportValveClass     Configures the valve responsible for rendering the Tomcat error pages. By default, the host will use org.apache.catalina.valves.ErrorReportValve.

The default server.xml configuration has one host configured for the Catalina engine:

<Host name="localhost" appBase="webapps" unpackWARs="true" autoDeploy="true">

This host definition defines a Tomcat virtual host named localhost that can be accessed by opening the following URL (with default Tomcat port 8080):

http://localhost:8080/

The <Host> element is configured as a child of the <Engine> element, and can have the following nested XML elements:

-- <Context>: Context container, described in the next section.
-- <Realm>: Used to configure Tomcat’s security realm
-- <Valve>: Used to configure Tomcat’s valve.
-- <Listener>: Used to configure Tomcat’s listener, which is used to react on events occurring internally in the Tomcat engine.

The Context Container

 

The context container represents a single web application deployed to Tomcat. It is configured using the <Context> XML element, and is the most commonly used container in the server.xml file. Any number of contexts can be defined within a <Host>, but each <Context> definition must have a unique context path, which is defined using the path attribute. There are over 50 different attributes that you can configure for the <Context> element.

The Main Attributes of the <Context> XML Element:

Attribute         Description

className         Names the fully qualified Java name of the class that implements the org.apache.catalina.Context interface. If no class name is specified, the implementation is used, which is the org.apache.catalina.core.StandardContext.

cookies             Determines if you want cookies to be used for a session identifier. The default value is true.

crossContext         If set to true, allows the ServletContext.getContext() method to successfully return the ServletContext for other web applications running in the same host. The default value is false, which prevents the access of cross context access.

docBase             Defines the directory for the web application associated with this <Context>. This is the pathname of a directory that contains the resources for the web application. This attribute is required.

path             Defines the context path for this web application. This value must be unique for each <Context> defined in a given <Host>.

reloadable          If set to true, causes Tomcat to check for class changes in the /WEB-INF/classes/ and /WEB-INF/lib directories. If these classes have changed, the application owning these classes is automatically reloaded. This feature should be used only during development. Setting this attribute to true causes severe performance degradation and therefore should be set to false in a production environment.

wrapperClass         Defines the Java name of the org.apache.catalina.Wrapper implementation class that is used to wrap servlets managed by this context. If not specified, the standard value org.apache.catalina.core.StandardWrapper is used.

sessionCookieName     Overrides any session cookie name specified by individual web applications. If not specified, and no web application specific value is defined, JSESSIONID name will be used. You can configure other session cookie attributes using the sessionCookiePath and sessionCookieDomain attributes.

override         Should be set to true, if you wish to override the configuration settings inherited from parent <Host> or <Engine> elements. The default value is true.

swallowOutput         If set to true, all System.out and System.err output will be redirected to the web application logging engine, instead if being written to catalina.out file. The default value is false.

The Additional Attributes for Configuration of StandardContext Implementation

unpackWar         Determines if the WAR file for this web application should be unpacked or the web application should be executed directly from the WAR file. If not specified, the default value is true.

workDir             Defines the pathname to a work directory that this Context uses for temporary read and write access. The directory is made visible as a servlet context attribute of type java.io.File, with the standard key of java.servlet.context.tempdir. If this value is not specified, Tomcat uses the host’s work directory CATALINA_HOME/work by default.

useNaming         Should be set to true (the default) if you wish to have Catalina enable JNDI.

cachingAllowed         If set to true, Tomcat will cache the static resources it serves (images, css and javascript file, for example).

antiJARLocking         Specifies whether Tomcat class loader should take extra care when reading resources from jar file, to avoid jar locking. Specifying this attribute to true will slow deployment of web applications to Tomcat. Default value is false. You can configure locking of any other resource file using antiResourcesLocking attribute.

The <Context> element that defines the /examples application is included in the following code snippet:

<Context path="/examples" docBase="examples" reloadable="true">

The context definition defines a Web application under context path /examples that has all of its resources stored in the directory examples, relative to the appBase directory of the parent host (by default CATALINA_HOME/webapps/examples). This context also states that this application is reloaded when its files are updated.

The <Context> element is configured as a child of the <Host> element, and as a parent to the following elements:

-- <Loader>: Used for configuration of web application class loader.
-- <Realm>: Used to configure Tomcat’s security realm.
-- <Valve>: Used to configure Tomcat’s valve.
-- <Listener>: Used to configure Tomcat’s listener, which is used to react on events occurring internally in the Tomcat engine.
-- <Manager>: Used to configure session manager for the web application deployed in context container.
-- <Parameter>: Used to set parameters for ServletContext initialization.
-- <Environment>: Used to configure values that will be available in the web application as environment entries.
-- <Resources>: Used to configure JNDI resources for the web application deployed in this context.
-- <WatchedResource>: Used to configure resources that will be monitored by auto deployer, and which will trigger web application redeployment if changed or updated.

Connectors

The connector components are responsible for accepting incoming requests in Tomcat, passing the request to the engine container defined for the given connector, accepting the resulting response from the engine container and passing the response to the calling client. The connector elements are configured in Tomcat’s server.xml file using the <Connector> XML element. The <Connector> XML element is defined as a nested element within the <Service> element, at the same level as the engine container it communicates to.

The <Connector> element is defined by the org.apache.catalina.Connector interface. There are two main connector types available in Tomcat, based on the protocol they support:

— HTTP connector component, that supports HTTP protocol, which enables Catalina engine to run as a web server and servlet container, handling HTTP request from users via the browser.

— AJP connector component that supports the communication using AJP protocol, used for integrating Tomcat with Apache Web server.

 

For more details please refer to below links:

HTTP connector component

AJP connector component

Connectors Doc

In case of any ©Copyright or missing credits issue please check CopyRights page for faster resolutions.