Creating tc Runtime Templates

A template provides configuration information and files to support a feature or application on a tc Runtime instance. The built-in templates that ship with tc Server make it simple to configure tc Runtime features such as SSL or JMX or to add a management application to an instance at creation time, such as Spring Insight.

You can create your own templates by creating a subdirectory in the templates directory of your tc Server installation directory and populating it with files according to the instructions in this section. You could, for example, construct a template that allows creating a tc Runtime instance with a web application or set of web applications ready to deploy, with a custom configuration specified at the tcruntime-instance create command line or through interactive prompts.

A template is a directory containing files that the tcruntime-instance create command processes when it creates a new tc Runtime instance. Some files are copied directly to the new tc Runtime instance. Other files are applied to configuration files in the tc Runtime instance; that is, they are used to alter the content of standard configuration files, such as conf/server.xml.

Files you place in the template directory that are not interpreted specially by the instance creation scripts are copied into the new instance. For example, if your web application requires JAR libraries, you can create a lib subdirectory and place the JAR files there. If you have a WAR file to deploy, put it in a webapps subdirectory and it will be copied to the webapps subdirectory of the new tc Runtime instance.

The target platform (Windows or Unix) and the JVM (Sun HotSpot or IBM J9) are recognized at instance creation time and variables are handled accordingly, files omitted from the copy when appropriate. Your Linux tc Runtime instances will not have unneeded .bat or .dll files. Path names and environment variables are automatically handled with the correct syntax for the target platform.

Parts of a Template

A template directory contains at minimum a README.txt file. The other contents depend on the purpose of the template. The following sections describe the kinds of files that a template can have.

README.txt

Environment

XML Configuration Fragments

Logging Properties Fragment

Other Files

README.txt

A template must have a README.txt file in its root directory. This file is a synopsis of the configuration and content that the template provides to an instance. The file should not have the name of the template, but a version and build date are considered best practices. When in doubt, look at the examples provided by the templates packaged in tc Runtime.

When an instance is created, the content of the README.txt files in each template are combined into a single README.txt file that is placed in the root of the created instance. The combined README.txt file documents the templates' contributions to the newly created instance.

Following is the README.txt file that is the result of creating an instance using the base, bio, bio-ssl, and elastic-memory templates.

Operating System Family: unix
Virtual Machine Architecture: x64
Virtual Machine Name: hotspot
========================================================================================================================
Template: base
Version: 2.6.0.RELEASE
Build Date: 20110729092530

* Sets Xmx to 512M
* Sets Xss to 192K
* Adds a control script to the instance
* Adds the Windows service wrapper libraries
* Adds a default jmxremote configuration with a read/write user called 'admin' with a password of 'springsource'
* Adds a default JULI logging configuration
* Adds a default server configuration containing:
	* A JRE memory leak prevention listener
	* A tc Runtime Deployer listener
	* A JMX socket listener
	* A LockOutRealm to prevent attempts to guess user passwords via a brute-force attack
	* An in-memory user database
	* A threadpool that has up to 300 threads
	* A host that uses 'webapps' as its app base
	* An AccessLogValve
* Adds a default Tomcat user configuration that is empty
* Adds an init.d script configured to start the instance as a specific user
* Adds a root web application
========================================================================================================================
Template: base-tomcat-7
Version: 2.6.0.RELEASE
Build Date: 20110729092530

* Adds Tomcat 7-specific ThreadLocalLeakPreventionListener
* Adds Tomcat 7-specific catalina.properties
* Adds Tomcat 7-specific default catalina.policy to be used when starting with the -security option
* Adds Tomcat 7-specific JspServlet configuration
* Adds Tomcat 7-specific web-app declaration
========================================================================================================================
Template: bio
Version: 2.6.0.RELEASE
Build Date: 20110729092530

* Adds a Blocking IO (BIO) connector for HTTP
========================================================================================================================
Template: bio-ssl
Version: 2.6.0.RELEASE
Build Date: 20110729092530

* Adds a Blocking IO (BIO) connector for HTTPS
* Adds sample certificate and key files that can be used to test the SSL configuration

NOTE: The sample certificate and key files are not suitable for production systems.
========================================================================================================================
Template: elastic-memory
Version: 1.0.0.RELEASE
Build Date: 20110729095358

* Adds Elastic Memory for Java version 82906b25cc97bb5d799578d0114921a35c26e41b to launch configuration
* Sets Xmx to 1024M
* Sets up EM4J logging in conf/logging.properties

Environment

A template may contribute a bin/setenv.properties file containing platform-agnostic environmental configuration. This file is turned into bin/setenv.sh on Unix machines and bin/setenv.bat and conf/wrapper.conf files on Windows machines. The file may contain properties with any of the following well-known keys.

Table 32. setenv.properties Keys

KeyDescription
java.homeThe directory where the JVM is installed.
java.agent.#The path to the Eleastic Memory for Java native library. It is added to the JVM command line with the -agentpath option.
agent.path.#The path to the Elastic Memory for Java JAR file. I tis added to the JVM command line with the -javaagent option.
class.path.#Adds a JAR to the Java class path.
java.library.path.#The path to a native library. It is added to the java.library.path in the JVM command command line.
java.opt.#A JVM option to be added to the JVM command line.

Except for java.home, each of these keys can be declared multiple times by incrementing its digit suffix. An example declaring two entries for java.library.path follows.

java.library.path.1=${catalina.base}/bin/amd64-linux
java.library.path.2=${vmware.tools.location:/usr/lib/vmware-tools}/lib/libvmGuestLib.so

Automatic Boilerplate Decoration

Entries for the setenv.properties keys do not need to have boilerplate text attached. When the template is processed, the values are processed to create command line options with the correct platform- and JVM-specific syntax. The following table describes what will be prepended to each entry.

Table 33. Automatic Boilerplate Decoration

EntryEntry After Decoration
java.agent.1=value-1
java.agent.2=value-2
-javaagent:value-1 -javaagent:value-2
agent.path.1=value-1
agent.path.2=value-2
-agentpath:value-1 -agentpath:value-2
class.path.1=value-1
class.path.2=value-2
value-1:value-2
java.library.path.1=value-1 
java.library.path.2=value-2
-Djava.library.path=value-1:value-2

Memory and Stack Size JAVA_OPTS Filtering

There are a few common properties that are regularly set to control memory and stack size of the VM. In cases where duplicate values for these are found due to the combination of templates, the largest value of each will be chosen. The list of these properties follows.

  • -Xmx

  • -Xms

  • -Xss

  • -XX:MaxPermSize

JVM Type Specific Properties

To ensure that a property is only used for a specific JVM type, the well-known keys can be qualified with values of the vm.name property. The value must be located between the base key and the incrementing digit, delimited by '.' characters. For example:

java.opt.hotspot.1=+XX:MaxPermSize=1024M
java.opt.j9.2=-Xaggressive

OS Family Specific Properties

To ensure that a property is only used for a specific operating system family, the well-known keys can be qualified with values of the os.family property. The value must be located between the base key and the incrementing digit, delimited by '.' characters. An example using the os.family property follows.

java.library.path.unix.1=${vmware.tools.location:/usr/lib/vmware-tools}/lib/libvmGuestLib.so
java.library.path.windows.2=${vmware.tools.location:C:\Program Files\VMware\VMware Tools}

VM Architecture Specific Properties

To ensure that a property is only used for a specific VM architecture, the well-known keys can be qualified with values of the vm.arch property. The value must be located between the base key and the incrementing digit, delimited by '.' characters. An example using the vm.arch property follows.

java.library.path.unix.x64.1=${catalina.base}/bin/amd64-linux
java.library.path.unix.x86.2=${catalina.base}/bin/x86-linux

Combining Values in Qualified Properties

The well-known keys can be qualified with values of any combination of the implicit properties. These values must be located between the base key and the incrementing digit, delimited by '.' characters, but can be in any order. An example using the os.family, vm.arch, and vm.name properties follows.

java.library.path.unix.x64.hotspot.1=${catalina.base}/bin/amd64-linux

XML Configuration Fragments

A template may contribute any of the following XML configuration files.

  • conf/server-fragment.xml

  • conf/web-fragment.xml

  • conf/context-fragment.xml

  • conf/tomcat-users-fragment.xml

These files contribute to the standard Tomcat configuration file of the same name, less the "-fragment" portion of the name. Inside the file is an XML fragment that describes what is to be added, removed, or updated in the respective configuration file. The XML fragment describes its contributions using the add: and remove: keywords on elements and attributes and the update: keyword, which can only be used on attributes. In addition, other XML elements are defined to describe a single XML element that the contributions should act upon. The XML elements that exist can be thought of as a direct example of an XPath expression. For example the XPath expression //Server/Service[@name="Catalina"] would be represented as follows.

<?xml version='1.0' encoding='utf-8'?>
<Server>
  <Service name="Catalina">
  </Service>
</Server>

A more complex example of the XPath expression //Server/Service[@name="Catalina"]/Engine[@name="Catalaina"][@defaultHost="localhost"] is represented as follows.

<?xml version='1.0' encoding='utf-8'?>
<Server>
  <Service name="Catalina">
    <Engine name="Catalina" defaultHost="localhost">
    </Engine>
  </Service>
</Server>

Once an element has been specified using an XML fragment, contributions can then be specified. They could be updates and additions of attributes, as illustrated in the following example.

<?xml version='1.0' encoding='utf-8'?>
<Server>
  <Listener className="com.springsource.tcserver.serviceability.rmi.JmxSocketListener"
      update:useSSL="true"
      add:useJdkClientFactory="true"
      passwordFile="${catalina.base}/conf/jmxremote.password"
      accessFile="${catalina.base}/conf/jmxremote.access"
      add:keystoreFile="${catalina.base}/conf/tcserver.keystore"
      add:keystorePass="changeme"
      add:truststoreFile="${catalina.base}/conf/tcserver.keystore"
      add:truststorePass="changeme"
      update:authenticate="false"/>
</Server>

When adding an element, once the element has been marked as add:, it is unnecessary to also mark the attributes of the new element. An example of adding an element without marking its attributes follows.

<?xml version='1.0' encoding='utf-8'?>
<Server>
  <Service name="Catalina">
    <add:Connector executor="tomcatThreadPool"
        port="${http.port:8080}"
        protocol="org.apache.coyote.http11.Http11Protocol"
        connectionTimeout="20000"
        redirectPort="${https.port:8443}"
        acceptCount="100"
        maxKeepAliveRequests="15"/>
  </Service>
</Server>

It is unnecessary to mark any sub-elements with add: when the parent element is marked. An example adding an element with sub-elements without marking its sub-elements follows.

<?xml version='1.0' encoding='utf-8'?>
<Server>
  <Service name="Catalina">
    <Engine name="Catalina" defaultHost="localhost" add:jvmRoute="${node.name:tc-runtime-1}">
      <add:Cluster className="org.apache.catalina.ha.tcp.SimpleTcpCluster" channelSendOptions="8">
        <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"/>
          </Sender>
          <Interceptor className="org.apache.catalina.tribes.group.interceptors.TcpFailureDetector"/>
          <Interceptor className="org.apache.catalina.tribes.group.interceptors.MessageDispatch15Interceptor"/>
        </Channel>
        <Valve className="org.apache.catalina.ha.tcp.ReplicationValve" filter=""/>
        <Valve className="org.apache.catalina.ha.session.JvmRouteBinderValve"/>
        <ClusterListener className="org.apache.catalina.ha.session.JvmRouteSessionIDBinderListener"/>
        <ClusterListener className="org.apache.catalina.ha.session.ClusterSessionListener"/>
      </add:Cluster>
    </Engine>
  </Service>
</Server>

Logging Properties Fragment

A template may contribute a conf/logging-fragment.properties file. This file contributes to the standard Tomcat conf/logging.properties file. The properties fragment describes its contributions by prefixing property keys with the add. keyword, as shown in the following example.

############################################################
# For Elastic Memory for Java (EM4J) logging.
#
# Values for com.vmware.jem.level are:
# WARNING, INFO, CONFIG, FINE, FINER, FINEST
#
############################################################
add.com.vmware.jem.level=${loggingLevel:INFO}
add.com.vmware.jem.handlers=java.util.logging.ConsoleHandler
add.java.util.logging.ConsoleHandler.formatter=com.vmware.jem.BalloonLogFormatter

Other Files

Any other file in the template that is not specifically excluded (see Platform Specificity) is copied directly to the instance. Properties files have their content substituted when copied. If a file clashes with a file contributed by another template, a warning is displayed to the user and the later file will replace the earlier file. Ordering of template application is dependent on user input and may vary.