The following sample server.xml file shows a basic out-of-the-box configuration for tc Server included in tc Server. 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 that must be unique across multiple server instances computer, such as HTTP and JMX port numbers. These variables take the form ${var}. For example, the variable for the HTTP port that tc Server 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 some 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
In the preceding sample server.xml:
The root element of the server.xml file is <Server>. The attributes of this element represent the characteristics of the entire tc Server 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 tc Server. The port attribute specifies the TCP/IP port number that listens for a shutdown message for this tc Server instance; note that in this server.xml file uses the variable ${shutdown.port}. The catalina.properties file substitutes a value of -1, which indicates that it is the same as the listen port.
The <Listener> XML elements specify the list of lifecycle listeners that monitor and manage the tc Server instance. Each listener class is a Java Management Extensions (JMX) MBean that listens to a specific component of the tc Server 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 tc Server lifecycle listeners.
The listener implemented by the com.springsource.tcserver.serviceability.rmi.JmxSocketListener class is also specific to tc Server. This listener enables JMX management of tc Server; in particular, this is the JMX configuration that the AMS management console uses to manage tc Server instances. The port attribute specifies the port of the JMX server that management products, such as AMS, connect to. The variable ${jmx.port} is set to 6969 in the default catalina.properties file.
By default, SSL is disabled; if you enable it by updating the useSSL attribute, you must then configure AMS with the trustStore and trustStorePassword. To set these values, add the following to the agent.javaOpts entry in each AMS 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}
The <GlobalNamingResources> XML element groups together 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 will be later referenced by the <Engine> XML element so that Web applications deployed to tc Server 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, one or more executors, 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 executors define thread pools that can be shared between components, such as connectors. Finally, the engine then defines how these requests and responses that the connector receives and sends are in turn handled by the tc Server; you can defined 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.
The tomcatThreadPool thread pool, 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.
The single configured connector listens for HTTP requests at the 8080 TCP/IP port (as set by the ${http.port} variable in catalina.properties). It uses the thread pool defined by the tomcatThreadPool executor and ignores all other thread attributes. 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 tc Server instance automatically redirects the request to port 8443. If tc Server 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.
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 server.
The <Realm> child element of <Engine> represents a database of users, passwords, and mapped roles used for authentication in this service. In the sample above, the realm simply references the UserDatabase resource, defined by the <Resource> child element of <GlobalNamingResources>.
Finally, 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 Server automatically deploys Web applications that are copied to the CATALINA_BASE/webapps directory while tc Server is running and automatically deploys them when the server starts. SpringSource tc Server unpacks them into a directory hierarchy if they are deployed as WAR files. SpringSource tc Server parses any context.xml file contained in the META-INF directory of deployed applications. The xmlValidation attribute specifies that tc Server does not validate XML files when parsing them, or in other words, it accepts invalid XML. The xmlNamespaceAware attribute specifies that tc Server 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 Server configuration. There are, however, many more elements and attributes you can configure in this file. For complete documentation about the tc Server server.xml file and all the possible XML elements you can include, see Apache Tomcat Configuration Reference.