4.2 Simple tc Runtime Configuration

The following sample server.xml file shows a basic out-of-the-box configuration for a default tc Runtime instance included in tc Runtime. This configuration file uses typical values for a standard set of XML elements. Sample server.xml files in later sections of this documentation build on this file.

This server.xml file uses variable substitution for configuration properties, such as HTTP and JMX port numbers, that must be unique across multiple server instances on one computer. These variables take the form ${var}. For example, the variable for the HTTP port that the tc Runtime instance listens to is ${http.port}. The specific values for these variables for a particular server instance are stored in the catalina.properties file, located in the same directory as the server.xml file. A snippet of the default catalina.properties file is shown after the sample server.xml file; the snippet shows specific values of variables such as the HTTP port.

See Description of the Basic server.xml File for information about the elements and attributes in this sample configuration file in case you need to change them to suit your own environment.

<?xml version='1.0' encoding='utf-8'?>
<Server port="${shutdown.port}" shutdown="SHUTDOWN">

  <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.tcserver.serviceability.rmi.JmxSocketListener"
            port="${jmx.port}"
            bind="127.0.0.1"
            useSSL="false"
            passwordFile="${catalina.base}/conf/jmxremote.password"
            accessFile="${catalina.base}/conf/jmxremote.access"
            authenticate="true"/>

  <Listener className="com.springsource.tcserver.serviceability.deploy.TcContainerDeployer" />

  <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="conf/tomcat-users.xml" />
  </GlobalNamingResources>


  <Service name="Catalina">

    <Executor name="tomcatThreadPool" namePrefix="tomcat-http--" maxThreads="300" minSpareThreads="50"/>

    <Connector
               executor="tomcatThreadPool"
               port="${http.port}"
               protocol="HTTP/1.1"
               connectionTimeout="20000"
               redirectPort="8443"
               acceptCount="100"
               maxKeepAliveRequests="15"/>

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

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

      <Host name="localhost"  appBase="webapps"
            unpackWARs="true" autoDeploy="true" deployOnStartup="true" deployXML="true"
            xmlValidation="false" xmlNamespaceAware="false">
      </Host>
    </Engine>
  </Service>
</Server> 

The following snippet of catalina.properties shows how to set values for the variables used in the preceding server.xml file.

   tcserver.node=tcServer
   shutdown.port=-1
   http.port=8080
   jmx.port=6969
   ajp.port=8009

Description of the Basic server.xml File

Note the following components of the preceding sample server.xml:

  • <Server>. Root element of the server.xml file. Its attributes represent the characteristics of the entire tc Runtime servlet container. The shutdown attribute specifies the command string that the shutdown port number receives through a TCP/IP connection in order to shut down the tc Runtime instance. The port attribute is the TCP/IP port number that listens for a shutdown message for this tc Runtime instance; note that in this server.xml file the variable is ${shutdown.port}. By default, the catalina.properties file substitutes a value of -1, which disables the shutdown via TCP connection. Thus the only way to stop the tc Runtime instance is to issue a kill command on the process ID (PID) of the tc Runtime instance. This is what the tcruntime-ctl.sh command does when you use it to stop a running tc Runtime instance.

  • <Listener>. List of lifecycle listeners that monitor and manage the tc Runtime instance. Each listener listens to a specific component of the tc Runtime instance 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 three <Listener> elements configure standard Tomcat lifecycle listeners.

    You can insert a com.springsource.tcserver.properties.SystemProperties listener before these standard listeners to set properties from external properties files. See Adding a System Properties Listener.

    The listener implemented by the com.springsource.tcserver.serviceability.rmi.JmxSocketListener class is specific to tc Server. This listener enables JMX management of tc Runtime; in particular, this is the JMX configuration that the HQ user interface uses to monitor tc Runtime instances. The port attribute specifies the port of the JMX server that monitoring products, such as Hyperic HQ, connect to. The variable ${jmx.port} is set to 6969 in the default catalina.properties file. The bind attribute specifies the host of the JMX server; by default, this attribute is set to the localhost (127.0.0.1.)

    Warning: The value of the bind attribute of JmxSocketListener overrides the value of the java.rmi.server.hostname Java system property. This directly affects how names are bound in the RMI registries; by default, the names will be bound to localhost (127.0.0.1.) This in turn means that RMI clients running on a different host from the one hosting the tc Runtime instance will be unable to access the RMI objects because, from their perspective, the host name is incorrect. This is because, the host should be the name or IP address of the tc Runtime computer rather than localhost. When the tc Runtime instance starts, if it finds that the value of the bind attribute is different from or incompatible with the java.rmi.server.hostname Java system property, the instance will log a warning but will startup anyway and override the system property as described. If this causes problems in your particular environment, then you should change the value of the bind attribute to specify the actual hostname on which the tc Runtime runs rather than the default 127.0.0.1 value.

    The monitoring application (such as Hyperic) that connects to the tc Runtime instance via JMX must specify a user and password to actually gain access. You configure these in the files pointed to by the accessFile and passwordFile attributes of the Listener. By default, the JMX user is admin with password springsource.

    By default, SSL is disabled; if you enable it by updating the useSSL attribute, you must then configure HQ with the trustStore and trustStorePassword. To set these values, add the following to the agent.javaOpts entry in each HQ Agent's agent.properties file:

    agent.javaOpts=-Xmx128m -Djava.net.preferIPv4Stack=true -Dsun.net.inetaddr.ttl=60 \ 
    -Djavax.net.ssl.trustStore=${full path to truststore} -Djavax.net.ssl.trustStorePassword=${password}
  • <GlobalNamingResources> . Groups the global JNDI resources for this server instance that Web applications deployed to the server can use. In the preceding example, the <Resource> element defines the database used to load the users and roles from the CATALINA_BASE/conf/tomcat-users.xml file into an in-memory data structure. This resource is later referenced by the <Engine> XML element so that Web applications deployed to tc Runtime instances can query the database for the list of users and the roles to which the users are mapped, as well as update the file.

  • <Service>. Groups one or more connectors, one or more executors, and a single engine. Connectors define a transport mechanism, such as HTTP, that clients use to send and receive messages to and from the associated service. A client can use many transports, which is why a <Service> element can have many <Connector> elements. The executors define thread pools that can be shared between components, such as connectors. The engine then defines how these requests and responses that the connector receives and sends are in turn handled by the tc Runtime instance; you can define only a single <Engine> element for any given <Service> element.

    The sample server.xml file above includes a single <Connector> for the HTTP transport, a single <Executor> that configures the thread pool used by the connector, and a single <Engine> as required.

  • tomcatThreadPool. As defined by the <Executor> XML element, allows a maximum of 300 active threads. The minimum number of threads that are always kept alive is 50.

  • <Connector>. Listens for HTTP requests at the 8080 TCP/IP port (as set by the ${http.port} variable in catalina.properties). The connector uses the thread pool defined by the tomcatThreadPool executor and ignores all other thread attributes. After accepting a connection from a client, the connector waits a maximum of 20000 milliseconds for a request URI, after which it times out. If this connector receives a request from the client that requires the SSL transport, the tc Runtime instance automatically redirects the request to port 8443. If the tc Runtime instance receives a connection request at a moment in time when all possible request processing threads are in use, the server puts the request on a queue; the acceptCount attribute specifies the maximum length of this queue (100) after which the server refuses all connection requests. Finally, the maximum number of HTTP requests that can be pipelined until the connection is closed by the server is 15, as specified by the maxKeepAliveRequests attribute.

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

    The <Realm> child element of <Engine> represents a database of users, passwords, and mapped roles used for authentication in this service. In the preceding sample, 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. tc Runtime automatically deploys Web applications that are copied to the CATALINA_BASE/webapps directory while the tc Runtime instance is running and automatically deploys them when the server starts. The tc Runtime instance unpacks the Web applications into a directory hierarchy if they are deployed as WAR files. SpringSource tc Runtime parses any context.xml file contained in the META-INF directory of deployed applications. The xmlValidation attribute specifies that the tc Runtime instance does not validate XML files when parsing them, or in other words, it accepts invalid XML. The xmlNamespaceAware attribute specifies that tc Runtime does not take namespaces into account when reading XML files.

The preceding sample server.xml file contains typical elements and attribute values for a simple out-of-the-box tc Runtime configuration. However, you can configure many more elements and attributes in this file. For complete elements documentation about the tc Runtime server.xml file, see Apache Tomcat Configuration Reference.

Adding a System Properties Listener

tc Server includes a useful feature that allows you to configure tc Server and Java system properties through external properties files. Properties that you set using this method can be use to as replacement values in server.xml. The external properties files are also useful for setting application properties, instead of modifying the setenv.sh script to set them on the java command line with the -D flag. The properties are available to applications through java.lang.System.getProperties().

The listener should be the first child of the Server element in the server.xml file, since XML is processed in the order it appears and properties must be set before they are referenced.

The following example specifies four properties files to be processed in sequence.

<Listener className="com.springsource.tcserver.properties.SystemProperties"
    file.1="${catalina.base}/conf/base.properties"
    file.3="${catalina.base}/conf/qa.properties"
    file.2="${catalina.base}/conf/dev.properties"
    file.4="${catalina.base}/conf/prod.properties"
    immutable="false"
    trigger="now"/>

There can be up to one hundred files, and they are processed in sequence by the numeric extension, not in the order they appear. In the example above, the dev.properties file is processed before the qa.properties file, even though they are not listed in that order.

The immutable attribute, false by default, determines if properties can be overridden. When false, the property value is set each time the key is encountered. If immutable is true, once a value is associated with a key it cannot be changed; later occurrences of the property are ignored. Whether immutable is set to true or false, a debug message is logged when an existing property is encountered.

If you specify a properties file that does not exist, a message is logged, but processing continues. This allows you to set up system.xml for different runtime environments by supplying only the appropriate properties files. In the example above, for example, if the prod.properties file is missing, the properties in the base.properties, dev.properties, and qa.properties files are processed, with any properties overridden in qa.properties taking precedence.

The presence of the trigger attribute causes the properties to be applied before parsing the remainder of the server.xml file. The value of the trigger attribute is ignored.