An In-Depth Look at Tomcat's server.xml Files

DZone 's Guide to

An In-Depth Look at Tomcat's server.xml Files

Well, that title is rather self explanatory. So read on to get an up close and personal look at Apache Tomcat 8 and how to use it to create web apps.

· Web Dev Zone ·
Free Resource


Today I am going to explain every single block in server.xml file of Tomcat 8.

Many of you are using Tomcat as a server for web deployment, some of you may change the server.xml file according to your requirements like the port, the given certificate for SSL, etc. So, here is the brief idea about the meaning of each specified block in that given file, and how you can configure them according to your requirements.

The first block is the "Server" -- This element represents the entire catalina servlet container. Therefore, this is the starting block for our server.xml file. In this block, we have to define the valid container, listener, engine, etc.

Please note that Server is not itself a "Container," so we cannot define subcomponents at this level. Its attribute represents the characteristics of the servlet container as a whole.

Supported attributes in the Server are (in Java, we call similar parameters supported in method): className, address, port, and shutdown.

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

The second block is "Listener" -- This element defines a component that performs actions when specific events occur.

The only supported attribute in Listener is className.

  • className - Again, we can provide a Java class name of the implementation to the user. This class must be implemented by the org.apache.catalina.LifecycleListener interface.

<Listener className="org.apache.catalina.startup.VersionLoggerListener" />

The third block is "Service" -- This element represents the combination of one or more Connector components that share a single Engine Component for processing incoming requests.

Again note that Service is not itself a "Container," so we can not define subcomponents at this level. One or more Service elements may be nested inside a Server element. Its attributes are className and name.

  • className - Again, we can provide a Java class name of the implementation to the user. This class must be implemented by the org.apache.catalina.Service interface.

  • name - The display name of the Service, which will be included in log messages. Here, note that the name of each Service that is associated with a particular Server must be unique. The default value for this attribute is "Catalina."

<Service name="Catalina">

The fourth block is "Connector" -- This represents an endpoint by which requests are received and responses are returned.

We can define two types of Connectors inside the Service block.

  1. The HTTP connector: The HTTP connector element represents a Connector component that supports the HTTP/1.1 protocol. It enables Catalina to function as a stand-alone web server. A particular instance of this component listens for connectors on a specific TCP port number on the server. One or more such Connectors can be configured inside the Service block, each forwarding to the associated Engine to perform request processing and create the response. Each incoming request requires a thread for the duration of that request. If more simultaneous requests are received than can be handled by the currently available request processing threads, additional threads will be created up to the configured maximum. If still more simultaneous requests are received, they are stacked up inside the server socket created by the Connector, up to the configured maximum. Any further simultaneous requests will receive "connection refused" errors until resources are available to process them. I am not going to list and explain each supported attribute for this connector, hence I will only write few important attributes which may help us to setup server.xml in a better way. Refer here for more details.

    • Let's discuss a few of these attributes: 

      1. maxThreads - This is used to define the maximum number of request processing threads to be created by this Connector. The default value for this attribute is 200, i.e. 200 simultaneous requests can be handled by this Connector.

      2. acceptCount - This is used to define the maximum queue length for incoming connection requests when all possible request processing threads are in use. The default value for this attribute is 100. Any request received when the queue is full will be refused.

      3. port - The TCP port number on which this Connector will create a server socket and await incoming connections (OS will allow only one server application to listen to a particular port number on a particular IP address). The default value in case of non-SSL is 8080 and, in case of SSL, it's 8443.

      4. protocol - This will be used to set the protocol to handle incoming traffic. The default value is HTTP/1.1, which uses an auto-switching mechanism to select either a Java NIO-based connector or an APR/native-based connector.

      5. connectionTimeout - This will be used to set the number of milliseconds for the Connector to wait, after accepting a connection, for the request URI lines to be presented. Use a value of -1 to indicate no timeout. The default value for this attribute is 60000 (60 seconds), but when we install Tomcat, Tomcat sets this to 20000 (20 seconds).

      6. URIEncoding - This specifies the character encoding used to decode the URI bytes, after %xx decoding the URL; if nothing is specified, UTF-8 will be used.

      7. redirectPort - If the Connector is supporting non-SSL requests, and a request is received which requires an SSL transport, Catalina will automatically redirect the request to the port number specified here.

      8. SSLEnabled - It is used to enable SSL traffic on a Connector. The default value is false.

      9. scheme - Set this attribute to the name of the protocol you wish to have returned by calls. The default value is "HTTP."

      10. secure - Set this attribute to true if you wish to have calls to be secure on this Connector. The default value is false.

  2. The AJP Connector
    The AJP Connector element represents a Connector component that communicates with a web connector via the AJP Protocol. This connector supports load balancing when used in conjunction with the jvmRoute attribute in Engine.

  • Here's a code snippet for an HTTP connector:

<Connector port="8080" protocol="HTTP/1.1"
redirectPort="8443" />

<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
               maxThreads="150" SSLEnabled="true" scheme="https" secure="true"
               clientAuth="false" sslProtocol="TLS" />

  • Here's a code snippet for an AJP connector:

<Connector port="8009" protocol="AJP/1.3" redirectPort="8443" />

The fifth block I'd like to talk about is "Engine" -- This represents the entire request processing machinery associated with a particular Catalina service. It receives and process all requests from one or more Connectors, and returns the completed response to the Connector for its ultimate transmission back to the client.

Supported attributes of the Engine are: namedefaultHostbackgroundAndProcessorDelayclassNamejvmRoute, etc.

  • defaultHost - The default host's name, which identifies the host that will process requests redirected to the host names on this server.

  • name - This is used to define the logical name of the engine, which is used in logs and error messages. When using multiple Service elements on the same server, each Engine MUST be assigned a unique name.

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

The sixth block I'd like to discuss is "Host" -- This element represents a virtual host, which is an association of a network name of a server, i.e. www.sample.com, with the particular server on which Tomcat is running.

Let's discuss the supported attributes for this block.

  • appBase - The application base directory for this virtual host. Basically, it contains the pathname of a directory which contains the web applications to be deployed on this virtual host.

  • name - Generally, we set the name of the host as registered in our domain name service server. Tomcat will convert this name to lower case internally.

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

That's it. So, I hope I cleared up any confusion you've had on the blocks of the server.xml file of Tomcat, which is generally located in conf folder.

Happy coding!

apache tomcat, tomcat 8, web dev, xml file

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}