Mastering Tomcat’s server.xml: A Complete Guide to Core Component Configuration

1. A server.xml configuration example

server.xml is located in $TOMCAT_HOME/conf. Below is a sample server.xml file that will be used to illustrate the meaning and function of each element.

2. server.xml element classification and overall structure

1. Overall structure

The overall structure of server.xml is shown below, highlighting only Tomcat’s core components.

In addition to the core components, Tomcat contains other components that will be introduced later.

2. Element classification

Elements in server.xml can be divided into four categories:

Top‑level elements: <Server> and <Service>

Connector: <Connector>

Containers: <Engine>, <Host>, <Context>

Embedded components: other elements that can be nested inside the containers

The following sections describe the core components and their relationships in detail.

3. Core components

1. Server

The <Server> element is the top‑most element representing the entire Tomcat container. A Server can contain one or more Service elements.

In the example, the outermost <Server> has a shutdown attribute that defines the command to stop the server and a port attribute (set to -1 to disable the shutdown port).

The Server’s main task is to provide an interface for clients to access the collection of Services and to manage the lifecycle of all contained Services.

2. Service

A Service wraps a set of Connectors and a single Engine, exposing them as a unified service. A Service may contain multiple Connectors but only one Engine.

In the example, the Server contains a Service named "Catalina". Tomcat can host multiple Services, each listening on different ports.

3. Connector

The Connector receives client requests, creates Request and Response objects, and passes them to the Engine for processing.

Two Connectors are shown in the example:

Connector 1 listens on port 8080 using the HTTP protocol. The protocol, port, redirectPort, and connectionTimeout attributes control its behavior.

Connector 2 listens on port 8009 using the AJP protocol, which is used to integrate Tomcat with other HTTP servers such as Apache.

4. Engine

The Engine is the request‑processing component inside a Service. It receives requests from one or more Connectors, processes them, and returns the response to the Connector.

In the example, the Engine configuration includes name (used for logging) and defaultHost, which must match the name of one Host component.

5. Host

Engine and Host

A Host is a child container of an Engine and represents a virtual host. An Engine can contain one or more Host elements; one Host must have a name that matches the Engine’s defaultHost.

Host purpose

The Host runs multiple web applications (each represented by a Context) and is responsible for installing, deploying, starting, and stopping them.

Host configuration

Key attributes include: name: the virtual host name (usually registered in DNS). unpackWARs: whether to unpack WAR files. autoDeploy and appBase: control automatic deployment of web applications.

6. Context

Context purpose

The <Context> element represents a web application running on a specific virtual host. Each Context belongs to a Host.

Automatic deployment

When autoDeploy and deployOnStartup are true, Tomcat automatically scans the Host’s xmlBase and appBase directories for XML configuration files, WAR files, and exploded application directories.

Scanning order:

XML configuration files in xmlBase WAR files in appBase Exploded application directories in

appBase

Context attributes

docBase

: path to the WAR file or application directory. path: the context path used in URLs. When auto‑deployment is used, path is derived from the file name. reloadable: if true, Tomcat monitors WEB-INF/classes and WEB-INF/lib for changes and reloads the application (useful for development, not recommended for production).

Example of an auto‑deployed app1.xml configuration:

4. Relationships among core components

Overall relationship

Server → Service → (Connector(s) + Engine) → Host → Context.

How a request is routed

Protocol and port select the Service and its Engine.

Host name (or IP) selects the Host; if none matches, the Engine’s defaultHost is used.

The request URI’s path selects the Context (web application) based on the path attribute.

Configuring multiple Services

To run multiple services on different ports, copy the <Service> element, adjust the Connector ports, change the name attributes of Service and Engine, and optionally modify the Host’s appBase.

5. Additional components

1. Listener

Listeners execute specific actions on lifecycle events such as server start or stop. In the example, six listeners are defined in the Server element, each specifying a className that implements org.apache.catalina.LifecycleListener.

2. GlobalNamingResources and Realm

The Realm provides authentication and role mapping. The example uses a UserDatabase resource defined in GlobalNamingResources, which reads $TOMCAT_HOME/conf/tomcat-users.xml.

3. Valve

A Valve is a request‑processing pipeline component. The example includes an AccessLogValve inside the Host to record access logs.

Key AccessLogValve attributes: className: specifies the valve type. directory: log directory (default $TOMCAT_HOME/logs). prefix and suffix: log file naming. pattern: log format (e.g., %h %l %u %t "%r" %s %b).

Analyzing access logs helps identify request distribution, response status codes, and processing times, which is valuable for performance tuning and troubleshooting.