Creating and Managing tc Server 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 Tomcat Manager.

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 tcserver create/tcserver create-from-file command line or through interactive prompts.

A template is a directory containing files that the tcserver create/tcserver create-from-file 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

Modifying Properties Files

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, nio, and nio-ssl templates.

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

* Sets Xmx to 512M
* Sets Xss to 256K
* 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 generated password
* 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: 4.0.0.RELEASE
Build Date: 20180306170814

* 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: nio-ssl
Version: 4.0.0.RELEASE
Build Date: 20180306170814

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

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 1. setenv.properties Keys

Key	Description
`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 line.
`java.opt.#`	A JVM option to be added to the JVM command line.
`jdk.java.options.$`	Introduced in 4.0.22 and 4.1.10 this translates to the `JDK_JAVA_OPTIONS` environment variable.

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

You can specify your own environment variables bin/setenv.properties. Note that you when you define such variables, you must append the variable name with a numeric suffix, for example:

myapp.options.1=-Dproperty1=value1
myapp.options.2=-Dproperty2=value2

The custom properties convert as MYAPP.OPTIONS="value1 value2" in the CATALINA_BASE/bin/setenv.sh (Unix) or CATALINA_BASE/bin/setenv.bat (Windows) file.

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 2. Automatic Boilerplate Decoration
Entry	Entry 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`
`myapp.options.1=value1 myapp.options.2=value2`	`MYAPP_OPTIONS="-Dproperty1=value1-Dproperty2=value2"`

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="Catalina"][@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="203.0.113.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>

Specifying the Location of a New Element in an XML Configuration File

When you use a template XML fragment file to add a new element to an XML configuration file, the new element is added to the bottom of the parent element by default. Sometimes, however, you might need to specify an exact location for the new element in the XML file. For example, there are some <Listener> elements that must appear as the first child elements of the root <Server> element at the top of the conf/server.xml file; if they are added to the bottom of the file, the tc Runtime instance will not start.

You specify the exact location of the new element by also including the sibling element that should appear after the new element in the XML fragment file. At instance-creation time when the template is being applied, if the sibling element is found, the new element will be added before it. If, however, the sibling element is not found, the new element will be added at the bottom of its parent element (the default behavior).

For example, assume the original server.xml file, before the template is applied, looks like the following (some elements removed for clarity):

<?xml version="1.0"?>
<Server port="${base.shutdown.port}"
        shutdown="SHUTDOWN">
    <Listener className="org.apache.catalina.core.JasperListener"/>
    <Listener className="org.apache.catalina.core.JreMemoryLeakPreventionListener"/>
    <Listener className="org.apache.catalina.mbeans.GlobalResourcesLifecycleListener"/>
    ...
</Server>

If you want your template to add a new <Listener> element right before the one with classname org.apache.catalina.core.JreMemoryLeakPreventionListener, create the XML fragment file similar to the following:

<?xml version='1.0' encoding='utf-8'?>
<Server>
        <add:Listener className="com.springsource.tcserver.properties.SystemProperties"
                file.1="${catalina.base}/local/environment.properties"
                file.2="${catalina.base}/local/credentials.properties"
                immutable="false"
                trigger="now"/>
        <Listener className="org.apache.catalina.core.JreMemoryLeakPreventionListener"/>
</Server>

After the template is applied to a new tc Runtime instance, the server.xml file will look like the following:

<?xml version="1.0"?>
<Server port="${base.shutdown.port}"
        shutdown="SHUTDOWN">
    <Listener className="org.apache.catalina.core.JasperListener"/>
    <Listener className="com.springsource.tcserver.properties.SystemProperties"
                file.1="${catalina.base}/local/environment.properties"
                file.2="${catalina.base}/local/credentials.properties"
                immutable="false"
                trigger="now"/>
    <Listener className="org.apache.catalina.core.JreMemoryLeakPreventionListener"/>
    <Listener className="org.apache.catalina.mbeans.GlobalResourcesLifecycleListener"/>
    ...
</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.

############################################################
#
# 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

Modifying Properties Files

The following table describes the prefixes that you can add to your custom template to modify the properties files in an instance.

Table 3. Properties File Modification Prefixes
Prefix	Description	Example	Supported in Version
add	Adds the property to the properties file.	add.my-property=my-value1,my-value2 Adds my-property=my-value1,myvalue2 to the properties file.	2.5+
append	Appends the specified value to the end of the current value of that property. The prefix adds the property if it does not already exist.	append.my-property=appended-value Appends the specified value to the existing my-property property value: my-property=my-previous-value,appended-value	2.9.5+
append-delimiter	Changes the default delimiter (a comma) to the specified delimiter character.	append-delimiter.my-property=; Changes the delimiter to a semicolon for the my-property=previous-value;appended-value property value	2.9.5+
delete	Removes the property from the properties file.	delete.my-property= Removes the my-property property from the properties file.	2.9.5+
update	Replaces the current property value with the specified value.	update.my-property=my-new-value Replaces the current my-property property value with the specified value.	2.9.5+

Other Files

Any other file in the template that is not specifically excluded (see Platform Specificity) is copied directly to the instance. Properties files and XML 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.

Property Substitution

Property substitution allows you to customize tc Runtime instances by providing instance-specific values at creation time. The tcserver script scans for property place holders in files. It substitutes a value that is derived from a default or another defined property, or supplied interactively by the user when the script is run with the --interactive option. Property substitution occurs in the bin/setenv.properties file, the logging properties fragment, all properties files, and XML complete and fragment files.

The syntax for a place holder is as follows:

${property-name[:default-value]}

Implicit Properties

Templates are provided as a set of implicit properties, determined at instance creation time. They are generally specific to the platform where the instance is created and the JAVA_HOME the instance will use at runtime. The list of implicit properties and their possible values are shown in the following table.

Table 4. Implicit Properties
Property	Possible Values
`os.family`	`unix` `windows`
`vm.arch`	`x64` `x86`
`vm.name`	`hotspot` `j9`
`catalina.base`	`$CATALINA_BASE` `%CATALINA_BASE%`
`catalina.home`	`$CATALINA_HOME` `%CATALINA_HOME%`

Configuration Prompts

When a user runs the instance creation script in interactive mode, the script prompts for any property not specified as part of the command. The standard prompt is Please enter a value for '%s'. Default '%s': when a default is provided and Please enter a value for '%s': when no default is provided. These prompts are generic and not good at helping the user select a useful value. You can provide more helpful custom prompt text. To do this, a template must contain a resource bundle called configuration-prompts.properties in the root of the template. This bundle contains the text to display when prompting for a value. In addition, the prompt can include the default value for the property by embedding the ${default} place holder in the text. For example:

pivotal.tools.location=Enter the path to the Pivotal tools installation. The default path is '${default}'\:

The template user accepts the default by pressing Enter without entering a value.

Configuration prompts can be localized for particular languages and countries. To do this, append language and country codes to the file name. For example, a resource bundle containing localized prompts for Spanish speakers would be called configuration-prompts_es.properties.

Platform Specificity

When a tc Runtime instance is created, some files are not created or copied to the instance because they are not required by the target platform. For example, there is no benefit to copying Windows .bat files to a Linux host. In addition, some files are used by the template, or to document the template, and are not copied into the instance.

Files Excluded on Unix

When a template is rendered on a Unix platform, Windows platform-specific files are not rendered in the instance. This includes files matched by the following patterns:

**/*.bat
**/*.dll
**/*.exe
**/amd64-winnt/**
**/x86-winnt/**
**/win32/**
**/winx86_64/**

Files Excluded on Windows

When a template is rendered on a Windows platform, Unix platform-specific files are not rendered in the instance. This includes files matched by the following patterns:

**/*.sh
**/*.so
**/amd64-linux/**
**/x86-linux/**

Template Files Excluded

Files matching the following patterns are not copied directly into a tc Runtime instance:

README.txt
bin/setenv.properties
conf/*-fragment.properties
conf/*-fragment.xml
configuration-prompts(_([A-Za-z])+)?.properties

Splitting a Template for Tomcat Versions

The base template is an example of a template that provides different options depending on whether the target instance uses tc Runtime 9 or tc Runtime 10.1. This is a generalized feature that you can use if you have different configuration options or file contributions for tc Runtime 9 or tc Runtime 10.1.

The base template has three parts:

Template Name	Description	Available Since
`base`	The files in this directory are processed for all tc Runtime instances.	2.0
`base-tomcat-9`	The files in this directory are processed only if the target instance uses a Tomcat 9 runtime.	5.0
`base-tomcat-101`	The files in this directory are processed only if the target instance uses a Tomcat 10.1 runtime.	5.0

You can create a custom template with different options for tc Runtime 7, tc Runtime 8, and tc Runtime 8.5 by using the same directory naming convention.

Managing Templates

Install a Template Using `get-template` Command

The get-template command enables a tc Server admin to download and install a template from a remote location using either the http or https protocol, a local zip file, or directory path.

Usage

Execute get-template with the command:

tcserver get-template <name> [OPTIONS]

Table 5. get-template options

Option	Description	Available Since
`-h`,`--help`	Prints usage information for `get-template`.	3.1.0
`--overwrite`	Overwrite the template directory if it already exists. If neither --no-overwrite or --overwrite are specified then it will prompt to overwrite.	3.2.0
`-p`, `--password <password>`	Password to use with an authenticated URL. If this option is omitted and username is specified then you will be prompted to enter password.	3.1.0
`-u`, `--username <username>`	Username to use with an authenticated URL.	3.1.0

Examples

To download and install a template from a web server:

tcserver get-template http://templates.example.com/ default_template.zip --url

To use a file available on the local filesystem:

tcserver get-template /var/templates/default_template.zip --file

To use a directory on the local filesystem:

tcserver get-template /var/templates/default_template --source-directory

Instructions

Note: If a previous version of the template already exists, you should backup that template's directories prior to installing the new template.

Download the tc Server template of your choice.
Unzip the package into the <tc Server Installation>/templates directory.
Verify you see the template's name listed in the templates directory.
You can also verify the version of the template by looking in the template's README.txt file.

Step By Step Example

The following example steps show how to create a custom template which adds a property called myproperty to an tc Runtime Instance's conf/catalina.properties file. These steps can be shortened, however, the individual steps are shown to help illustrate the directory layout.

In your local template directory create a directory called myproperty
```
mkdir myproperty
```
From inside that directory create a directory called conf
```
cd myproperty
mkdir conf
```
Create a file called catalina-fragment.properties and insert myproperty=${myproperty:true} into the file.
```
echo 'myproperty=${myproperty:true}' > catalina-fragment.properties
```
Go back to parent directory and create a file called configuration-prompts.properties and insert a descriptive prompts
```
cd ..
echo 'Please provide a value for myproperty' > configuration-prompts.properties
```

This is all that is needed to create a very basic template. This template can be applied to an tc Runtime Instance or used during creation of the instance.

tcserver create myinstance -t myproperty

The instance will contain a property/value pair of myproperty = true inside the conf/catalina.Properties

The value of myproperty may be changed when the instance is used. Note: That the reason for the double usage of myproperty is because the first usage refers to the name of the template and the second usage refers to the specific property. If the template was named mytemplate and the property was named autoreload then the property would be referred to as mytemplate.autoreload in the next steps.

tcserver create myinstance -t myproperty -p myproperty.myproperty=false

The instance will contain a property/value pair of myproperty = false inside the conf/catalina.Properties

Similarly the property may be specified in a properties file and used with the -f option.

echo 'myproperty.myproperty=false' > myinstance.properties
tcserver create myinstance -t myproperty -f myinstance.properties

The instance will contain a property/value pair of myproperty = false inside the conf/catalina.Properties

Parts of a Template

README.txt

Environment

Automatic Boilerplate Decoration

Memory and Stack Size JAVA_OPTS Filtering

JVM Type Specific Properties

OS Family Specific Properties

VM Architecture Specific Properties

Combining Values in Qualified Properties

XML Configuration Fragments

Specifying the Location of a New Element in an XML Configuration File

Logging Properties Fragment

Modifying Properties Files

Other Files

Property Substitution

Implicit Properties

Configuration Prompts

Platform Specificity

Files Excluded on Unix

Files Excluded on Windows

Template Files Excluded

Splitting a Template for Tomcat Versions

Managing Templates

Install a Template Using get-template Command

Usage

Examples

Instructions

Step By Step Example

Install a Template Using `get-template` Command