7.2 Configuring the Embedded Tomcat Servlet Container

The 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 Modules. The embedded Servlet container can be configured via the servletContainer.config file located in the SERVER_HOME/config directory. The following listing displays the default configuration distributed with the dm Server.

{
   "servletContainer": {
      "version": 1.0,
      /* configDir should be either an absolute path or relative to the SERVER_HOME directory */
      "configDir": "config/servlet",
      "hostName": "localhost",
      "jvmRoute": "jvm1",
      "listeners": [
         {
            /*
             * APR library loader.
             * Documentation at http://tomcat.apache.org/tomcat-6.0-doc/apr.html
             */
            "enabled": true,
            "className": "org.apache.catalina.core.AprLifecycleListener",
            "SSLEngine": "on"
         },
         {
            /*
             * Initialize Jasper prior to loading webapps.
             * Documentation at http://tomcat.apache.org/tomcat-6.0-doc/jasper-howto.html
             */
            "enabled": true,
            "className": "org.apache.catalina.core.JasperListener"
         }
      ],
      "connectors": [
         {
            /* 
             * HTTP Connector.
             * Documentation at http://tomcat.apache.org/tomcat-6.0-doc/config/http.html
             */
            "enabled": true,
            "port": 8080,
            "protocol": "HTTP/1.1",
            "connectionTimeout": 20000,
            "maxThreads": 150,
            "emptySessionPath": false,
            "redirectPort": 8443
         },
         {
            /* 
             * HTTPS Connector.
             * Documentation at http://tomcat.apache.org/tomcat-6.0-doc/config/http.html
             * and http://tomcat.apache.org/tomcat-6.0-doc/ssl-howto.html
             */
            "enabled": true,
            "port": 8443,
            "protocol": "HTTP/1.1",
            "scheme": "https",
            "connectionTimeout": 20000,
            "maxThreads": 150,
            "emptySessionPath": false,
            "clientAuth": false,
            /* keystoreFile should be a path relative to the configured value for servletContainer:configDir */
            "keystoreFile": "../control/keystore",
            "keystorePass": "changeit",
            "secure": true,
            "SSLEnabled": true,
            "sslProtocol": "TLS"
         },
         {
            /*
             * AJP Connector.
             * Documentation at http://tomcat.apache.org/tomcat-6.0-doc/config/ajp.html
             */
            "enabled": true,
            "port": 8009,
            "protocol": "AJP/1.3",
            "connectionTimeout": 20000,
            "redirectPort": 8443
         }
      ],
      "logs": {
         "perApplicationLogging": true,
         /* accessLogDir should be either an absolute path or relative to the SERVER_HOME directory */
         "accessLogDir": "serviceability/logs/access",
         "accessLogFormat": "long"
      },
      "threadPool": {
         "minSize": 25,
         "maxSize": 200,
         "keepAlivePeriod": 60000
      }
      /*
       * The next section of this file is configuration for Tomcat clustering.  By default this is disabled.
       */
      /*,
      "cluster": {
         "className": "org.apache.catalina.ha.tcp.SimpleTcpCluster",
         "channelSendOptions": 8,
         "heartbeatBackgroundEnabled": false,
         "manager": {
            "className": "org.apache.catalina.ha.session.DeltaManager",
            "expireSessionsOnShutdown": false,
            "notifyListenersOnReplication": true
         },
         "channel": {
            "className": "org.apache.catalina.tribes.group.GroupChannel",
            "membership": {
               "className": "org.apache.catalina.tribes.membership.McastService",
               "address": "228.0.0.4",
               "port": 45564,
               "frequency": 500,
               "dropTime": 3000
            },
            "receiver": {
               "className": "org.apache.catalina.tribes.transport.nio.NioReceiver",
               "address": "auto",
               "port": 4000,
               "autoBind": 100,
               "selectorTimeout": 5000,
               "maxThreads": 6
            },
            "sender": {
               "className": "org.apache.catalina.tribes.transport.ReplicationTransmitter",
               "transport": {
                  "className": "org.apache.catalina.tribes.transport.nio.PooledParallelSender"
               }
            },
            "interceptors": [
               {
                  "className": "org.apache.catalina.tribes.group.interceptors.TcpFailureDetector"
               },
               {
                  "className": "org.apache.catalina.tribes.group.interceptors.MessageDispatch15Interceptor"
               }
            ]
         },
         "valves": [
            {
               "className": "org.apache.catalina.ha.tcp.ReplicationValve",
               "filter": ""
            },
            {
               "className": "org.apache.catalina.ha.session.JvmRouteBinderValve"
            }
         ],
         "deployer": {
            "className": "org.apache.catalina.ha.deploy.FarmWarDeployer",
            "tempDir": "/tmp/war-temp/",
            "deployDir": "/tmp/war-deploy/",
            "watchDir": "/tmp/war-listen/",
            "watchEnabled": false
         },
         "clusterListeners": [
            {
               "className": "org.apache.catalina.ha.session.JvmRouteSessionIDBinderListener"
            },
            {
               "className": "org.apache.catalina.ha.session.ClusterSessionListener"
            }
         ]
      }*/
   }
}
[Tip]Disabling configuration elements

Listener and Connector configuration elements can be disabled by setting the enabled flag to false. This allows you to disable but still retain the configuration for such elements without the need to delete the configuration.

7.2.1 Servlet Container Configuration

The following table lists all top-level options for configuring the embedded Servlet container.

[Tip]Relative paths

If the configured path to a directory or file does not represent an absolute path, it will typically be interpreted as a path relative to the SERVER_HOME directory.

Table 7.1. Servlet Container Configuration Values

EntryDescriptionSupported ValuesDefault Value
version

The configuration schema version.

1.0N/A
configDir

The path to the Servlet container's config directory. This directory serves as the central location for implementation-specific configuration files. The config directory also serves as the base directory for any relative-path-based configuration resources for the Servlet container.

If the configured value does not represent an absolute path, it will be interpreted as a directory relative to the SERVER_HOME directory.

config/servletN/A
hostName

The host name to use for the Servlet container's default host.

Any valid hostname for the system on which the dm Server is running.localhost
jvmRoute A unique identifier for the Servlet container instance, used to configure a JVM route for load balancing. A unique text value, typically purely alpha-numeric.jvm1
listeners A list of LifecycleListener configuration elements. Consult the official Tomcat documentation for further information on available listeners. N/AN/A
connectors A list of Connector configuration elements. See the connector configuration section for details. N/AN/A
logs - perApplicationLogging

Boolean flag for enabling access logging on a per-application basis.

true or falsetrue
logs - accessLogDir

The path to the access log directory where HTTP requests to the Servlet container will be logged.

If the configured value does not represent an absolute path, it will be interpreted as a directory relative to the SERVER_HOME directory.

(see description)serviceability/logs/access
logs - accessLogFormat

The style to use for formatting the access log.

short or longlong
threadPool - minSize

The minimum number of threads to be kept in the Servlet Container's threadpool.

Any positive int25
threadPool - maxSize

The maximum number of threads to be kept in the Servlet Container's threadpool.

Any positive int200
threadPool - keepAlivePeriod

The period of time, in milliseconds, that an idle thread will be kept alive in the Servlet Container's threadpool.

Any positive int60000

7.2.2 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 keystore file which contains a single self-signed SSL Certificate. The password for this keystore file is changeit. Please note that the provided 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.

7.2.3 Load Balancing Configuration

The SpringSource dm Server supports JSON-based configuration of the load balancing supported by tomcat. See the default configuration for syntax examples.

7.2.4 Cluster Configuration

The SpringSource dm Server supports JSON-based configuration of the clustering supported by Apache Tomcat. See the default configuration (which is disabled) for syntax examples, and for further details on the configuration properties support for Cluster implementations, consult the official Tomcat Clustering/Session Replication HOW-TO documentation.

7.2.5 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 (see configDir above). 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 on the 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.