This section describes the simplest way to use the tcruntime-instance command script to create a new tc Runtime instance. For an explanation of the type of instance that the example creates, see the description following the procedure.

When the preceding sample command completes, the new tc Runtime instance is located in the /var/opt/vmware/vfabric-tc-server-standard/myserver directory This directory is also the value of the CATALINA_BASE variable for this tc Runtime instance.

By default, the tc Runtime instance uses either the Java binaries pointed to by your JAVA_HOME environment variable or the java binary that it found in the PATH environment variable when it started. You can hard-code Java bianries that the tc Runtime instance uses by using the --java-home option.

The ports of the tc Runtime instance are the default values:

The preceding tcruntime-instance sample did not specify the --version option, so the instance is pinned to the highest tc Runtime version located in the installation directory, for example 7.0.8.A.RELEASE. You can use the modify-version verb to change the version to which the instance is pinned. See Pinning tc Runtime Instances to a Specific Version for more information.

When you use the tcruntime-instance.sh|bat command script to create an instance, you can specify additional optional parameters, as described in tcruntime-instance.sh Reference. For example, you can use the --property option to specify the Unix runtime user for the tc Runtime instance.

The tcruntime-instance command script has five possible command verbs, used to create, modify, or upgrade a tc Runtime instance, list the existing instances, or display help for the command script. Each command has its own set of options, as described in the tables in this section. Depending on the command, you must specify the name of a tc Runtime instance. The general syntax for each of the commands follows; click on the link to see the options for that particular command:

tcruntime-instance create [options] instance-name
tcruntime-instance modify-version [options] instance-name
tcruntime-instance upgrade [options] instance-name
tcruntime-instance list [options]
tcruntime-instance help [command-name]

prompt$ ./tcruntime-instance.sh create -i /var/opt/vmware/vfabric-tc-server-standard --interactive myserver

prompt$ ./tcruntime-instance.sh create -i /var/opt/vmware/vfabric-tc-server-standard  \
	--version 6.0.32.A.RELEASE --java-home /var/opt/java/jdk1.6.0_20 myserver

prompt$ ./tcruntime-instance.sh create --property bio.http.port=9090 \
	-i /var/opt/vmware/vfabric-tc-server-standard myserver

prompt$ ./tcruntime-instance.sh modify-version --version 6.0.32.A.RELEASE \
	-i /var/opt/vmware/vfabric-tc-server-instances myotherserver

prompt$ cd /opt/vmware/vfabric-tc-server-standard-new
prompt$ ./tcruntime-instance.sh upgrade -v 7.0.6.A.RELEASE ../vfabric-tc-server-standard/myInstance 

prompt$ ./tcruntime-instance.sh list -i /var/opt/vmware/vfabric-tc-server-standard
Listing instances in '/var/opt/vmware/vfabric-tc-server-standard'
  myInstance Info:
    Instance name:         myInstance
    Runtime version:       7.0.26.A.RELEASE
    tc Runtime Base:       /var/opt/vmware/vfabric-tc-server-standard/myInstance
    Status:                NOT RUNNING

prompt$ ./tcruntime-instance.sh help

prompt$ ./tcruntime-instance.sh help create

prompt$ ./tcruntime-instance.sh create -h
prompt$ ./tcruntime-instance.sh create --help

Use the quickstart/createInstance.sh|bat interactive script to quickly create a simple SSL-enabled tc Runtime instance. The script prompts you for all the information it needs.

Note: The createInstance script is meant for users who want to quickly create a simple tc Runtime instance for evaluation purposes. You should use the tcruntime-instance script to create instances for production use.

The createInstance.sh|bat script uses the following two tc Server templates when it creates the instance:

If you want to create an instance using different templates, use the tcruntime-instance.sh|bat script, as described in Creating tc Runtime Instances with the tcruntime-instance Command Script.

Prerequisites

Procedure

You can use the --version parameter of tcruntime-instance.sh|bat to specify the version of tc Runtime to which the new instance is pinned. Specifically:

To determine the list of available versions, search for INSTALL_DIR/tomcat-XXX directories, where XXX follows a pattern such as 6.0.32.A.RELEASE.

For example, if you create a new instance using the following command:

prompt$ ./tcruntime-instance.sh create --version 6.0.32.A.RELEASE \
       -i /var/opt/vmware/vfabric-tc-server-standard myserver

the myserver instance will always use version 6.0.32.A.RELEASE of the tc Runtime, even if a more recent version is installed. If, however, you do not specify the --version parameter, for example:

prompt$ ./tcruntime-instance.sh create -i /var/opt/vmware/vfabric-tc-server-standard myserver

the myserver instance is automatically pinned to the highest version available. Not having to explicitly specify a version when you create the instance is useful if you know that you simply want to use the highest available.

To determine the tc Runtime version to which existing instance is pinned, check the file INSTANCE-DIR/conf/tomcat.version which lists the version, such as 6.0.35.A.RELEASE.

When the instance starts, if it cannot find the tc Runtime version specified in its tomcat.version file, the instance outputs a warning and instead uses the highest version of tc Runtime in the same major runtime release (i.e. tc Runtime 6 or 7). For example, if the tomcat.version file specifies 6.0.32.A.RELEASE, but the instance finds only the 6.0.32.B.RELEASE, 6.0.35.A.RELEASE, and 7.0.27.A.RELEASE versions, then the instance uses the 6.0.35.A.RELEASE tc Runtime version. Note that it does not use the 7.0.27.A.RELEASE version because this is a different major release.

To change the version of a pinned instance, use the modify-version command together with --version to specify the new version. For example:

prompt$ ./tcruntime-instance.sh modify-version --version 6.0.26.A.RELEASE \
      -i /var/opt/vmware/vfabric-tc-server-standard myserver

The name of a tc Runtime instance is the name of its CATALINA_BASE directory, minus the leading directory paths. As a reminder, CATALINA_BASE is the base directory of the instance; this directory contains the instance-specific startup scripts in the bin sub-directory, the configuration files in the conf sub-directory, and so on. For example, if you create a tc Runtime instance in the /var/opt/vmware/vfabric-tc-server-standard/myserver directory, then its name is myserver.

The Hyperic user interface also uses this naming convention when first identifying a tc Runtime instance. In particular, the Hyperic user interface displays an instance with the name platform-resource tc Runtime catalina-base-dir, where platform-resource refers to the computer on which the tc Runtime instance is running and catalina-base-dir refers to the CATALINA_BASE directory of the tc Runtime instance without the leading directory pathnames. The Hyperic user interface uses the full pathname of CATALINA_BASE as the default description of the instance.

This means, however, that if you create two instances whose full pathnames differ, but their main installation directory names are the same, the instances will show up in the Hyperic user interface with the same names. This makes it difficult to differentiate multiple tc Runtime instances from each other, although you can always look at the description for the full pathname.

For this reason, it is best practice to use unique names for the main installation directory for each tc Runtime instance on the same computer.

Templates make it easier to automatically configure certain tc Runtime features at the time you create a tc Runtime instance. These features include SSL, clustering, and so on.

You use the --template option to specify a template to the tcruntime-instance script when you create a new tc Runtime instance. You can specify the --template option multiple times if you want to apply multiple templates, such as clustering and SSL.

When you create a tc Runtime instance using tcruntime-instance, the script performs the following high-level steps:

A template is simply a directory under the INSTALL-DIR/templates directory that contains additional or customized tc Runtime instance files. For example, the directory might contain a conf/server-fragment.xml file, which the tcruntime-instance script uses to update the base server.xml file with the relevant feature. The directory might also contain additional JAR files.

An example of creating an instance using the nio-ssl template is as follows:

prompt$ ./tcruntime-instance.sh create --template nio-ssl \
      -i /var/opt/vmware/vfabric-tc-server-standard myserver

In the example, the instance is created in the /var/opt/vmware/vfabric-tc-server-standard directory.

To use this feature, the specified template must already exist. You can use one of the out-of-the-box templates.

The files that make up a template reside in a single directory; the name of the template directory is the name of the template. The template files are organized in the standard Tomcat subdirectory hierarchy. For example, configuration files live in the conf subdirectory and JAR files live in the lib subdirectory. The configuration files in the conf template directory are actually just fragments of XML, called server-fragment.xml or context-fragment.xml, that contain just the additions, deletions, or changes that the script applies to the base instance. When the tcruntime-instance script applies the template after it has created a new base tc Runtime instance, it merges the XML fragment files with the corresponding base conf/server.xml or conf/context.xml file, and copies over any other files, such as JAR files. Depending on the contents of the template directory, the new tc Runtime instance might be quite different from the standard one. For example, the template might modify the standard server.xml file with additional server configuration, or copy one or more applications to the webapps directory so that they are automatically deployed on startup.

The argument to the --template option must be the tc Runtime template directory. The tcruntime-instance script looks for the template directory in the INSTALL_DIR/vfabric-tc-server-edition-version/templates directory, where edition-versin refers to the edition of tc Server you are using (developer or standard) and the version of tc Server.

You can specify the --template option multiple times; the tcruntime-instance script applies each template in the order given. First the script copies over any non-configuration files to the appropriate instance directory, and then the script merges the configuration file fragments with the instance configuration files. You will receive a warning if the creation of the instance copies over files with the same name and directory location from two or more different templates.

The following example shows how to create a new tc Runtime instance called myserver using the nio out-of-the-box template which adds a NIO Connector to the server.xml file:

prompt$ ./tcruntime-instance.sh create --template nio -i /var/opt/vmware/vfabric-tc-server-standard myserver

In the preceding example, because it does not specify the --version or --java-home options, the instance is uses the latest installed version of tc Runtime, and the instance uses the value of JAVA_HOME in the environment.

The following example shows how to create an instance that uses two templates:

prompt$ ./tcruntime-instance.sh create --template insight --template jmx-ssl \
      -i /var/opt/vmware/vfabric-tc-server-standard myserver

Note that the insight template is available only in the Developer Edition of tc Server.

tc Runtime provides several out-of-the-box templates. Most are server configuration related; for example, one template sets up a basic cluster node configuration and another sets up SSL. Some templates are provided only in certain editions of tc Server, such as the insight template in the Developer Edition.

You can download a tc Server template for setting up HTTP session replication with vFabric GemFire, the in-memory distributed data management platform, from the VMware vFabric GemFire section of the VMware Download Center. To use the template, see "Setting Up GemFire HTTP Session Management for tc Server" under "Tools and Modules" in the vFabric GemFire User's Guide.

The following example shows how to use the nio out-of-the-box template to create a tc Runtime instance that is automatically configured with the NIO Connector in its server.xml file:

prompt$ ./tcruntime-instance.sh create --template nio -i /var/opt/vmware/vfabric-tc-server-standard myserver-nio

Because the nio template is in the templates directory, you simply specify its name at the --template option.

The following table lists the templates that are provided by tc Runtime out-of-the-box and how each template differs from the generic tc Runtime instance (created without a specific template.) All templates are located in the INSTALL_DIR/vfabric-tc-server-edition/templates, where edition refers to the edition of tc Server you installed (developer or standard).

If you specify one of the SSL templates (bio-ssl, nio-ssl, apr-ssl, or jmx-ssl) when you create a tc Runtime instance, the tcruntime-instance script automatically configures SSL or OpenSSL for the instance; generates a new keystore; and provides default values for various properties if you do not specify them interactively.

For example, assume that you used the following command to create an instance:

prompt$ ./tcruntime-instance.sh create myserver-secure -t bio-ssl -i /var/opt/vmware/vfabric-tc-server-standard

The myserver-secure instance has the following default SSL properties and configuration:

This default configuration is adequate for testing. Typically, when you move to a production environment, you want to generate keystores with real information about your organization and customize the passwords. In this case, use the --interactive option of tcruntime-instance.sh|bat so that the script prompts you for the information about your particular environment.

The --interactive option still generates a self-signed certificate. If you require an authentic, verified certificate, purchase one from a well-known Certificate Authority such as VeriSign, and use the keytool JDK tool to import the certificate into your keystore. See the Creating a Simple Keystore File For Both SSL and OpenSSL section in the vFabric tc Server Administration Guide in this Documentation Center for more information.

You can create two flavors of tc Runtime instances, depending on the layout of their files: