7.4 Configuring the Embedded Tomcat Servlet Container
Prev 7. Configuring the SpringSource dm Server Next

7.4 Configuring the Embedded Tomcat Servlet Container

SpringSource dm Server embeds an OSGi-enhanced version of the Tomcat Servlet Container in order to provide support for deploying Java EE WARs and Web Bundles. You configure the embedded Servlet container using the standard Apache Tomcat configuration. The main difference is that the configuration file is called tomcat-server.xml rather than server.xml. As with the other dm Server configuration files, the tomcat-server.xml file is located in the $SERVER_HOME/config directory.

The following listing displays the default configuration distributed with the dm Server; for clarity, the listing does not include the standard Apache License. 

<?xml version='1.0' encoding='utf-8'?>

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

  <Listener className="org.apache.catalina.core.AprLifecycleListener" SSLEngine="on" />
  <Listener className="org.apache.catalina.core.JasperListener" />
  <Listener className="org.apache.catalina.mbeans.ServerLifecycleListener" />
  <Listener className="org.apache.catalina.mbeans.GlobalResourcesLifecycleListener" />

  <Listener className="com.springsource.server.web.tomcat.ServerLifecycleLoggingListener"/>

  <GlobalNamingResources>
    <Resource name="UserDatabase" auth="Container"
              type="org.apache.catalina.UserDatabase"
              description="User database that can be updated and saved"
              factory="org.apache.catalina.users.MemoryUserDatabaseFactory"
              pathname="config/tomcat-users.xml" />
  </GlobalNamingResources>

  <Service name="Catalina">

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

    <Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"
               maxThreads="150" scheme="https" secure="true"
               clientAuth="false" sslProtocol="TLS"
               keystoreFile="config/management/keystore"
               keystorePass="changeit"/>


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

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

      <Realm className="org.apache.catalina.realm.UserDatabaseRealm"
             resourceName="UserDatabase"/>

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

         <Valve className="org.apache.catalina.valves.AccessLogValve" 
               directory="serviceability/logs/access"
               prefix="localhost_access_log." suffix=".txt" pattern="common" 
               resolveHosts="false"/>
      </Host>
    </Engine>
  </Service>
</Server>

Description of the Default Apache Tomcat Configuration

The following bullets describe the main elements and attributes in the default tomcat-server.xml file; for details about updating this file to further configure the embedded Apache Tomcat server, see the Apache Tomcat Configuration Reference.

[Tip]Relative paths

If the configured path to a directory or file does not represent an absolute path, dm Server typically interprets it as a path relative to the SERVER_HOME directory.

  • The root element of the tomcat-server.xml file is <Server>. The attributes of this element represent the characteristics of the entire embedded Tomcat servlet container. The shutdown attribute specifies the command string that the shutdown port number receives via a TCP/IP connection in order to shut down the servlet container. The port attribute specifies the TCP/IP port number that listens for a shutdown message.

  • The <Listener> XML elements specify the list of lifecycle listeners that monitor and manage the embedded Tomcat servlet container. Each listener class is a Java Management Extensions (JMX) MBean that listens to a specific component of the servlet container and has been programmed to do something at certain lifecycle events of the component, such as before starting up, after stopping, and so on.

    The first four <Listener> elements configure standard Tomcat lifecycle listeners. The listener implemented by the com.springsource.server.web.tomcat.ServerLifecycleLoggingListener class is specific to SpringSource dm Server and manages server lifecycle logging.

  • The <GlobalNamingResources> XML element groups together the global JNDI resources that Web applications deployed to the servlet container can use. The <Resource> element defines the database used to load the users and roles from the SERVER_HOME/config/tomcat-users.xml file into an in-memory data structure. This resource will be later referenced by the <Engine> XML element so that Web applications deployed to the servlet container can query the database for the list of users and the roles they are mapped to, as well as update the file.

  • The <Service> XML element groups together one or more connectors and a single engine. Connectors define a transport mechanism, such as HTTP, that clients use to to send and receive messages to and from the associated service. There are many transports that a client can use, which is why a <Service> element can have many <Connector> elements. The engine then defines how these requests and responses that the connector receives and sends are in turn handled by the servlet container; you can defined only a single <Engine> element for any given <Service> element.

    The sample tomcat-server.xml file above includes three <Connector> elements: one for the HTTP transport, one for the HTTPS transport, and one for the AJP transport. The file also includes a single <Engine> element, as required.

  • The first connector listens for HTTP requests at the 8080 TCP/IP port. The connector, after accepting a connection from a client, waits for a maximum of 20000 milliseconds for a request URI; if it does not receive one from the client by then, the connector times out. If this connector receives a request from the client that requires the SSL transport, the servlet container automatically redirects the request to port 8443.

  • The second connector is for HTTPS requests. The TCP/IP port that users specify as the secure connection port is 8443. Be sure that you set the value of the redirectPort attribute of your non-SSL connectors to this value to ensure that users that require a secure connection are redirected to the secure port, even if they initially start at the non-secure port. The SSLEnabled attribute specifies that SSL is enabled for this connector. The secure attribute ensures that a call to request.isSecure() from the connecting client always returns true. The scheme attribute ensures that a call to request.getScheme() from the connecting client always returns https when clients use this connector.

    The maxThreads attribute specifies that the servlet container creates a maximum of 150 request processing threads, which determines the maximum number of simultaneous requests that can be handled. The clientAuth attribute specifies that the servlet container does not require a certificate chain unless the client requests a resource protected by a security constraint that uses CLIENT-CERT authentication.

    The keystoreFile attribute specifies the name of the file that contains the servlet container's private key and public certificate used in the SSL handshake, encryption, and decryption. You use an alias and password to access this information. In the example, this file is SERVER_HOME/config/management/keystore. The keystorePass attributes specify the password used to access the keystore.

  • The third AJP Connector element represents a Connector component that communicates with a web connector via the AJP protocol.

  • The engine has a logical name of Catalina; this is the name used in all log and error messages so you can easily identify problems. The value of the defaultHost attribute refers to the name of a <Host> child element of <Engine>; this host processes requests directed to host names on this servlet container.

  • The <Realm> child element of <Engine> represents a database of users, passwords, and mapped roles used for authentication in this service. By default, the realm simply references the UserDatabase resource, defined by the <Resource> child element of <GlobalNamingResources>.

  • The <Host> child element represents a virtual host, which is an association of a network name for a server (such as www.mycompany.com) with the particular server on which Catalina is running. The servlet container unpacks Web applications into a directory hierarchy if they are deployed as WAR files. The xmlValidation attribute specifies that the servlet container does not validate XML files when parsing them, or in other words, it accepts invalid XML. The xmlNamespaceAware attribute specifies that the servlet container does not take namespaces into account when reading XML files.

  • Finally, the org.apache.catalina.valves.AccessLogValve valve creates log files in the same format as those created by standard web servers. The servlet container creates the log files in the SERVER_HOME/serviceability/logs/access directory. The log files are prefixed with the string localhost_access_log., have a suffix of .txt, use a standard format for identifying what should be logged, and do not include DNS lookups of the IP address of the remote host.

Connector Configuration

The SpringSource dm Server supports JSON-based configuration of any connector supported by Apache Tomcat. See the default configuration above for syntax examples, and for further details on the configuration properties supported for various <Connector> implementations, consult the official Tomcat HTTP Connector documentation.

[Tip]Configuring SSL for Tomcat

The SpringSource dm Server distribution includes a preconfigured SERVER_HOME/config/management/keystore file that contains a single self-signed SSL Certificate. The password for this keystore file is changeit. This keystore file is intended for testing purposes only. For detailed instructions on how to configure Tomcat's SSL support, consult the official Tomcat SSL Configuration HOW-TO.

Load Balancing Configuration

SpringSource dm Server supports JSON-based configuration of the load balancing supported by Tomcat.

Cluster Configuration

SpringSource dm Server supports JSON-based configuration of the clustering supported by Apache Tomcat. By default, clustering of the embedded servlet container is disabled, and the default configuration does not include any clustering information. See Tomcat Clustering/Session Replication HOW-TO for detailed information about enabling and configuring clustering.

Tomcat Configuration Files

In addition to the aforementioned configuration options, various parts of the embedded Tomcat Servlet container can be configured via the following files located in the Servlet container's configuration directory. The syntax and usage of each file comply with that of a standard Tomcat installation.

  • context.xml: XML based configuration file which will be loaded for each web application Context deployed to dm Server.

  • tomcat-users.xml: XML based configuration file used to manage users, passwords, and roles for an in-memory security realm. This file is used by the dm Server to configure a MemoryRealm for the embedded Tomcat Servlet container.

  • web.xml: The default web.xml deployment descriptor used for all web applications deployed on the dm Server. As each web application is deployed, this file is processed, followed by the /WEB-INF/web.xml deployment descriptor packaged with the web application itself, if present.

Prev Up Next
7.3 Configuring Serviceability Home 7.5 Configuring the Provisioning Repository