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
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<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/webappscontext.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.
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.