7. Post-Installation Tasks

7. Post-Installation Tasks
Prev		Next

Creating tc Runtime Instances: Typical Steps

This section describes the simplest way 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.

Open a terminal window (Unix) or Command Prompt (Windows).
Change to the INSTALL_DIR/vfabric-tc-server-edition-release directory, where INSTALL_DIR refers to the main tc Server installation directory, such as /home/tcserver, edition refers to the edition of tc Server you are using (developer or standard.), and release is the release specifier For example:
```
prompt$ cd /home/tcserver/vfabric-tc-server-standard-2.5.0-RELEASE
```
Run the tcruntime-instance.sh (Unix) or tcruntime-instance.bat (Windows) script, passing it the create serverName option. Replace serverName with the name of your new tc Runtime instance. See Best Practice: Naming tc Runtime Instances for tips on naming an instance.
For example, on Unix:
```
prompt$ ./tcruntime-instance.sh create myserver 
```
On Windows:
```
prompt> tcruntime-instance.bat create myserver 
```

When the preceding sample command completes, the new tc Runtime instance is located by default in the INSTALL_DIR/vfabric-tc-server-edition/myserver directory (such as /home/tcserver/vfabric-tc-server-standard/myserver); you can specify a different instance directory with the --instance-directory directory option. This directory is also the value of the CATALINA_BASE variable for this tc Runtime instance. For example:

prompt> tcruntime-instance.bat create myserver --instance-directory /home/tcserver/instances

In the preceding example, the myserver instance directory will be /home/tcserver/instances/myserver.

By default, the tc Runtime instance uses the JAVA_HOME environment variable for the Java binaries, or the instance uses the java binary that it found in the PATH environment variable when it started. You can specify a specific JAVA_HOME using the --java-home option.

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

HTTP listen port: 8080
JMX port: 6969
AJP port: 8009
Shutdown port: -1

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 unpin the instance. 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 a configuration property.

tcruntime-instance.sh Reference

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 instance-name [options]
tcruntime-instance modify-version instance-name [options]
tcruntime-instance upgrade instance-name [options]
tcruntime-instance list [options]
tcruntime-instance help [command-name]

The create Command

Use the create command to create a new tc Runtime instance.

The command requires that you specify a name for the new tc Runtime instance directly after the create text.

When you create a new instance, and you do not specify the --template option to apply one or more specific templates, the tcruntime-instance script creates a basic tc Runtime instance that uses the default template (called bio); this template adds the Blocking IO (BIO) HTTP Connector to the server.xml of the instance. You can use the --template option to apply one or more templates so that the instance is automatically configured for a particular feature, such as the NIO connector, clustering, or SSL.

Examples of creating new tc Runtime instances are shown after the options reference table.

The following table lists options for the create command of tcruntime-instance.sh|bat. When specifying the most common options, you can use either the short form (such as -i) or the long form (such as --instance-directory); less common options support only the long form.

Table 7.1. Options of the create Command

Option (Long Form)	Option (Short Form, if available)	Description
`--force`	`N/A`	Forces the script to create a new tc Runtime instance, even if one already exists. By default the script does not force the creation. If you specify this parameter and a tc Runtime instance with the name already exists, the script replaces only the existing `bin` and `conf` directories; the script does not replace the other directories, such as `lib` or `temp`. It is assumed in this case that you do not want to touch the user-specific files, such as Web applications. To update the tc Runtime version used by an instance, use the `modify-version` command, not the `--force` option.
`--help`	`-h`	Outputs usage information about the `create` command usage.
`--interactive`	N/A	Tells the script to interactively ask for configuration properties. For example, use this parameter if you want to change the default port numbers, as listed in Creating tc Runtime Instances: Typical Steps. Warning: Be sure that all tc Runtime instances on the same computer have unique port numbers.
`--instance-directory instanceDir`	`-i instanceDir`	Replace `instanceDir` with the full or relative pathname of the directory in which you want the new tc Runtime instance to be created. If you specify a relative directory pathname, the directory is relative to the directory from which you are running the `tcruntime-instance.sh\|bat` script. The default value of this option is the current working directory.
`--java-home` `--java-home path_to_jre`	N/A	If specified without a `path_to_jre` value, hard-codes the `JAVA_HOME` variable in various files of the instance, using the global `JAVA_HOME` environment variable value. You can also use this option to specify a different location of the JDK or JRE. In this case, replace `path_to_jre` with the full pathname of the JRE or JDK. If you do not specify this option at all, then the instance uses the `JAVA_HOME` global environment variable, and does not hard-code the value anywhere.
`--layout layout`	N/A	Specifies the type of layout you want your new tc Runtime instance to use: `separate` or `combined`. The default value is `separate`. In the separate layout, `CATALINA_HOME` and `CATALINA_BASE` point to different directories; in the combined layout they point to the same directory, which means that the tc Runtime binaries are bundled within your instance. The combined is the standard Apache Tomcat layout. Warning: SpringSource recommends that you always use the separate layout, which is why it is the default value if you do not specify this option. For addiditonal information, see Differences Between the Separate and Combined Layouts.
`--properties-file file`	`-f file`	Specifies the name of a properties file that contains configuration properties that you want to apply to the new tc Runtime instance. When you create the properties file, it should contain one property per line, in the form `template-name.property-name=value`. The name of the property depends on the template. For example, the default template (called `bio`) has two configuration properties: `http.port` and `https.port`. Other templates might specify their own configuration properties. If you want to pass your own values of these properties to the `tcruntime-instance` script at the command line, rather than the instance taking the default values, create a file such as the following: `bio.http.port=9090` `bio.https.port=9191` Then point to this configuration property file using this option: `--properties-file my-property-file`
`--property template.property=value`	`-p template.property=value`	Specifies a single configuration that you want to apply to the new tc Runtime instance. When you create a tc Runtime instance, the `tcruntime-instance` script always applies a template, even if it is the default one (called `bio`). Templates usually have configuration properties. For example, the `bio` template has two configuration properties: `http.port` and `https.port`. Other templates might specify their own configuration properties. If you want to pass your own values of these properties to the `tcruntime-instance` script at the command line, rather than the instance taking the default values, use this option to specify the property in the form `template-name.property-name=value`. For example, to specify that the HTTP port for a new tc Runtime instance that uses the default template is 9090, specify the property as follows: `--property bio.http.port=9090`
`--template template_name`	`-t template_name`	Applies a template to a newly-created tc Runtime instance. You can specify this option multiple times to apply multiple templates to the instance. In this context, a tc Runtime template refers to a set of customized tc Runtime files that the `tcruntime-instance` script copies to or merges with the instance it just created. The template files are organized in the standard Tomcat hierarchy; for example, configuration files are in the `conf` directory and binary files are in the `bin` directory. Changes to the `conf/server.xml` or `conf/context.xml` files of the instance are contained in template files called `conf/server-fragment.xml` or `conf/context-fragment.xml`, respectively. These fragment XML files contain just the additions, deletions, or changes that will be applied to the base tc Runtime instance. When the `tcruntime-instance` script applies the template after it has created a new base instance, it merges `server-fragment.xml` or `context-fragment.xml` files with their base originals, or it might replace other instance files, depending on the contents of the template. For example, the template might copy one or more applications to the `webapps` directory so that they are automatically deployed on startup. If you use this option to specify one or more templates that do not add a `<Connector>` element to the `server.xml` configuration file, the `tcruntime-instance` script automatically adds a Blocking IO (BIO) HTTP Connector to the instance. If your templates include a `<Connector>` element, then the script does not add a BIO Connector. Replace the `template_name` argument with the name of an existing subdirectory of the `INSTALL_DIR/vfabric-tc-server-edition/templates` directory, where `edition` refers to the Edition of tc Server you are using (`developer` or `standard`.) An example of an existing template is `apr-ssl` or `cluster-node`. For additional details and examples about using this feature, see Creating a tc Runtime Instance with a Template.

The following example shows how be be interactively prompted for configuration properties (such as port numbers) and that you want the new tc Runtime instance to be located in the /home/tcserver/instances directory:

prompt$ ./tcruntime-instance.sh create myserver --instance-directory /home/tcserver/instances
    --interactive

The following example shows how to pin a new instance to version 6.0.32.A-RELEASE of tc Runtime and to specify a hard-coded value for JAVA_HOME:

prompt$ ./tcruntime-instance.sh create myserver --version 6.0.32.A-RELEASE
    --java-home /home/java/jdk1.6.0_20

The following example shows how to pass the value 9090 to the http.port configuration property of the default template (called bio), rather than use the default value of 8080:

prompt$ ./tcruntime-instance.sh create myserver --property bio.http.port=9090

The modify-version Command

Use the modify-version command to modify the version of tc Runtime used by an existing instance that is pinned to a particular version of tc Runtime.

Use the --version option to specify the new version of the instance. If you do not specify --version, the resulting instance is unpinned, which means it uses the latest available version of tc Runtime. See Pinning tc Runtime Instances to a Version.

Note: It is assumed that you have already installed the tc Runtime version to which you want to modify the existing instance.

Examples of modifying existing tc Runtime instances are shown after the options reference table.

The following table list options for the modify-version command of tcruntime-instance.sh|bat. When specifying the options, you can use either the short form (such as -i) or the long form (such as --instance-directory).

Table 7.2. Options of the modify-version Command

Option (Long Form) Option (Short Form) Description

Option (Long Form)	Option (Short Form)	Description
`--version version`	`-v version`	Pins the instance to the specified version of tc Runtime, such as `6.0.32.A-RELEASE`. Valid values depend on the versions of tc Runtime that you have installed. The `tcruntime-instance.sh` script determines the list of available versions by searching for `INSTALL_DIR/tomcat-XXX` directories, where `XXX` follows a pattern such as `6.0.32.A-RELEASE`. You can check for these directories to determine the versions to which you can pin a tc Runtime instance. If you do not specify this option, the instance is not pinned to a tc Runtime version, which means that when you use the `tcruntime-ctl.sh\|bat` script to start the instance, the script searches for the highest version and applies it to the instance. For example, if `6.0.24.A-RELEASE`, `6.0.24.B-RELEASE` and `6.0.32.A-RELEASE` are all present, and you don't specify this option, then the start script automatically chooses `6.0.32.A-RELEASE` as the version of the instance. See Pinning a tc Runtime Instance to a Specific Version for more information.
`--instance-directory instanceDir`	`-i instanceDir`	Replace `instanceDir` with the full or relative pathname of the directory that contains the tc Runtime instance you want to modify. If you specify a relative directory pathname, the directory is relative to the directory from which you are running the `tcruntime-instance.sh\|bat` script. The default value of this option is the current working directory.
`--help`	`-h`	Outputs usage information about the `modify-version` command usage.

--version
                version

-v
                version

Pins the instance to the specified version of tc Runtime, such as 6.0.32.A-RELEASE.

Valid values depend on the versions of tc Runtime that you have installed. The tcruntime-instance.sh script determines the list of available versions by searching for INSTALL_DIR/tomcat-XXX directories, where XXX follows a pattern such as 6.0.32.A-RELEASE. You can check for these directories to determine the versions to which you can pin a tc Runtime instance.

If you do not specify this option, the instance is not pinned to a tc Runtime version, which means that when you use the tcruntime-ctl.sh|bat script to start the instance, the script searches for the highest version and applies it to the instance. For example, if 6.0.24.A-RELEASE, 6.0.24.B-RELEASE and 6.0.32.A-RELEASE are all present, and you don't specify this option, then the start script automatically chooses 6.0.32.A-RELEASE as the version of the instance. See Pinning a tc Runtime Instance to a Specific Version for more information.

--instance-directory
                instanceDir

-i
                instanceDir

Replace instanceDir with the full or relative pathname of the directory that contains the tc Runtime instance you want to modify. If you specify a relative directory pathname, the directory is relative to the directory from which you are running the tcruntime-instance.sh|bat script.

The default value of this option is the current working directory.

--help -h Outputs usage information about the modify-version command usage.

The following example shows how to modify an existing tc Runtime instance called myotherserver to use version 6.0.32.A-RELEASE of tc Runtime; the resulting instance will be pinned to this version:

prompt$ ./tcruntime-instance.sh modify-version myotherserver --version 6.0.32.A-RELEASE

The following example shows how to unpin the myotherserver instance so it always uses the latest available version of tc Runtime when it starts:

prompt$ ./tcruntime-instance.sh modify-version myotherserver

The upgrade Command

Use the upgrade command to upgrade an instance to a new version of tc Server. The upgrade command copies the existing instance to a new instance directory and updates the files and descriptors in the instance.

The difference between the upgrade command and the modify-version command is that the upgrade command upgrades the tc Server scripts and other tc Server files to a newer version, and the modify-version command changes the tc Runtime version to a tc Runtime based on a different Apache Tomcat release.

	Note
	The `upgrade` command can upgrade an instance using tc Runtime 6 to a newer version of tc Runtime 6, but not to tc Runtime 7. To move from tc Runtime 6 to tc Runtime 7, create a new instance using tc Runtime 7 and redeploy your Web applications.

The usual procedure for using the upgrade command is to:

Install the new tc Server release in a directory alongside the existing tc Server installation.
Execute the upgrade command from the new tc Server installation directory, specifying the instance to be upgraded in the old tc Server installation directory.

This results in a new tc Runtime instance in the new tc Server installation directory. When all instances have been upgraded, restarted, and verified, the old tc Server instance directory can be removed.

Before you use the upgrade command:

If the instance to be upgraded is running, stop it. For example, execute the following command in the tc Server Installation directory:
```
prompt$ tcruntime-ctl.bat myInstance stop
```
If the instance to be upgraded is installed as a Windows service, uninstall it. For example:
```
prompt$ tcruntime-ctl.bat myInstance uninstall
```

After running the upgrade command, install the new instance as a Windows service (if on Windows) and then start the new instance.

If you have linked the CATALINA_HOME/bin/init.d.sh script to /etc/init.d on a UNIX system, unlink the script before upgrading and then re-link the script in the new instance directory after the upgrade is complete.

Table 7.3. Options of the upgrade Command

Option (Long Form)	Option (Short Form)	Description
`--instance-directory instanceDir`	`-i instanceDir`	Replace `instanceDir` with the full or relative pathname of the directory where the upgraded instance is to be created. If you specify a relative pathname, the directory is relative to the directory where you run the `tcruntime-instance.sh\|bat` script. The default value of this option is the current working directory.
`--version version`	`-v version`	Specifies the tc Runtime version to use for the upgraded instance. This option is required when upgrading an unpinned instance or to prevent the instance from being upgraded to the most recent release. If omitted, the most recent available version of the existing major release is used; if the instance is currently using tc Runtime 6, it is upgraded to use the highest tc Runtime 6 version in the tc Server installation directory. Valid values for `version` depend on the versions of tc Runtime that you have installed. The `tcruntime-instance.sh` script determines the list of available versions by searching for `INSTALL_DIR/tomcat-XXX` directories, where `XXX` follows a pattern such as `6.0.32.A-RELEASE`. You can check for these directories to determine which versions to which you can pin a tc Runtime instance.
`--help`	`-h`	Displays usage information for the `upgrade` command.

The following example upgrades the instance at /home/tcserver/vfabric-tc-server-standard/myInstance to a new instance at /home/tcserver/vfabric-tc-server-standard-new/myInstance. The upgraded instance will use tc Runtime release 7.0.6.A.RELEASE. The command is executed in the /home/tcserver/vfabric-tc-server-standard-new directory:

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

The list Command

Use the list command to list the known tc Runtime instances. For each instance, the command outputs the information additional information, such as the parent directory of the instance, the directories that contain its command scripts and binaries, the version of the instance (both base tc Runtime version and tc Server version), and whether the instance is currently running.

The following table lists options for the list command of tcruntime-instance.sh|bat. When specifying the options, you can use either the short form (such as -i) or the long form (such as --instance-directory)

Table 7.4. Options of the list Command

Option (Long Form)	Option (Short Form)	Description
`--instance-directory instanceDir`	`-i instanceDir`	Replace `instanceDir` with the full or relative pathname of the directory that contains the tc Runtime instances for which you want a listing. If you specify a relative directory pathname, the directory is relative to the directory from which you are running the `tcruntime-instance.sh\|bat` script. The default value of this option is the current working directory.
`--help`	`-h`	Outputs usage information about the `list` command usage.

The following example shows how to list known instances in the tc Server installation directory. There is one instance, myInstance, in this example.

prompt$ ./tcruntime-instance.sh list 
Listing instances in '/home/tcserver/vfabric-tc-server-standard-2.5.0.RELEASE' 
  myInstance Status: 
    INFO Derived instance name: myInstance 
    INFO Executing /home/tcserver/vfabric-tc-server-standard-2.5.0.RELEASE/./tcruntime-ctl.sh 
    INFO Instance name: myInstance 
    INFO Script directory: /home/tcserver/vfabric-tc-server-standard-2.5.0.RELEASE 
    INFO tc Runtime location:/home/tcserver/vfabric-tc-server-standard-2.5.0.RELEASE 
    INFO Instance base: /home/tcserver/vfabric-tc-server-standard-2.5.0.RELEASE 
    INFO Binary dir: /home/tcserver/vfabric-tc-server-standard-2.5.0.CI-279/tomcat-7.0.14.A.CI-72 
    INFO Runtime version: 7.0.14.A.CI-72 
    INFO Script version: 2.5.0.RELEASE 
    STATUS Instance is RUNNING as PID=6039

Getting Help for tcruntime-instance

To view a summary of all available commands of the tcruntime-instance script, use the help command:

prompt$ ./tcruntime-instance.sh help

To view the usage information about a particular command, specify the name of the command after the help command:

prompt$ ./tcruntime-instance.sh help create

The output includes brief information about the available options. You can also use the --help option of the commands to view the same information:

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

Pinning tc Runtime Instances to a Specific Version

Depending on whether you explicitly specify the --version parameter of the tcruntime-instance.sh|bat script when you create an instance, the resulting tc Runtime instance is either pinned or unpinned to a particular version of tc Runtime. Specifically:

If you explicitly specify the --version parameter, the tc Runtime instance is pinned to that version. This means that when you use the tcruntime-ctl.sh|bat script to start the instance, the instance always uses this tc Runtime version, even if you have installed a more recent version of the tc Runtime.
If you do not specify the --version parameter, the tc Runtime instance is unpinned. This means that when you use the tcruntime-ctl.sh|bat script to start the instance, the script searches for the most recent version of tc Runtime and applies it to the instance.

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 myserver --version 6.0.32.A-RELEASE

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 myserver

the myserver instance always uses the latest version of tc Runtime that is currently installed. Thus if you later install a new version of tc Runtime (which means that there will be a new tomcat-7.0.X.X-X directory alongside the existing ones), and start the unpinned myserver instance using the tcruntime-ctl.sh|bat script, the instance automatically uses the latest tc Runtime version without your having to explicitly do anything.

To determine whether an existing tc Runtime instance is pinned, check for the file INSTANCE-DIR/conf/tomcat.version; if the file exists, then the instance is pinned to the version specified in the file.

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 myserver --version 6.0.26.A-RELEASE

Finally, if you want to convert a currently pinned instance to one that is unpinned, use the modify-version command without --version. For example:

prompt$ ./tcruntime-instance.sh modify-version myserver

Best Practice: Naming tc Runtime Instances

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 /home/tcserver/vfabric-tc-server-standard/myServer directory, then its name is myServer.

The HQ user interface also uses this naming convention when first identifying a tc Runtime instance. In particular, the HQ 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 HQ 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 HQ 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.

Creating a tc Runtime Instance with a Template

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:

Creates the instance directory and applies the base template to it. This template provides configuration common to all tc Runtime instances, such as ensuring that the instance can be monitored with HQ.
If you specified one or more templates with the --template option, the script applies each template in order. The templates might update the instance's server.xml or context.xml file as well as copy over other files, such as JAR files.
Applies any needed configuration properties. The script gets the value of these properties either interactively from you, from the --property or --properties-file options you might have specified at the command-line, or from the default property values if no value is provided.
If there are no <Connector> elements in the server.xml file after the templates have been applied, the tcruntime-instance script adds a Blocking IO (BIO) HTTP Connector to the instance.

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 myserver --template nio-ssl

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/templates directory, where edition refers to the edition of tc Server you are using (developer or standard.)

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 myserver --template nio

In the preceding example, because it does not specify the --version or --java-home options, the instance is unpinned, and thus 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 myserver --template insight --template jmx-ssl

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

Templates Provided by tc Runtime

SpringSource tc Runtime provides a number of 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 using VMware vFabric GemFire, the in-memory distributed data management platform, from the VMware vFabric GemFire section of the VMware Download Center. See Setting Up GemFire HTTP Session Management for tc Server at the GemFire community website for instructions for using the template.

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 myserver-nio --template 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).

Table 7.5. Out-of-the-Box Templates Provided by tc Runtime

Template Name	Comparison with Default tc Runtime Instance
base	This template is the base from which all new tc Runtime instances are created. It provides the configuration that is common to all tc Runtime instances, such as ensuring that the instance can be monitored with HQ. When this template is applied, either the `base-tomcat-6` or `base-tomcat-7` is applied as well, depending on the tc Runtime version to be used by the instance.
base-tomcat-6	Part of the `base` template, this directory contains files specific to tc Runtime 6.
base-tomcat-7	Part of the `base` template, this directory contains files specific to tc Runtime 7.
ajp	This template adds an Apache JServe Protocol (AJP) connector, which enables Apache web server to communicate with the tc Runtime instance. For details about the connector, see The AJP Connector in the Apache Tomcat Configuration Reference.
apr	This template: Adds a `APRLifecycleListener` to detect the APR-based native library required to use the APR/native connector. Adds the APR HTTPS connector. NOTE: You must install the APR/native library in order to use the APR connector. For more information, see Apache Portable Runtime (APR) based Native library for Tomcat on the Apache Tomcat Web site.
apr-ssl	This template: Adds an `APRLifecycleListener` to detect the APR-based native library required to use the APR/native connector. Adds an APR HTTPS connector. Adds a sample certificate and key files for testing the SSL configuration. Warning: These sample certificates and key files are provided only to aid testing and debugging; they are not for production use. You must replace them with your own generated certificates and keys before moving to a production system. NOTE: You must install the APR/native library in order to use the APR connector. For more information, see Apache Portable Runtime (APR) based Native library for Tomcat and SSL Configuration HOW-TO on the Apache Tomcat Web site.
bio	This template adds a Blocking IO (BIO) HTTP Connector to the new instance's `server.xml` file.
bio-ssl	This template: Adds a Blocking IO (BIO) HTTPS connector. Adds a sample JKS keystore for testing the SSL configuration. Warning: The sample keystore is provided only to aid testing and debugging; it is not for production use. You must replace it with your own generated keystore before moving to a production system. For more information, see The HTTP Connector and SSL Configuration HOW-TO on the Apache Tomcat Web site.
cluster-node	This template: Adds the default Cluster configuration at the Engine level. By default, multicast discovery is used to identify other nodes in the cluster. If multicast is not enabled on the subnet or if multiple tc Runtime clusters may be present on the same subnet, reconfigure this cluster node to use static membership. Adds the `jvmRoute` attribute to the Engine element to uniquely identify the node. This is parameterized using `${tcserver.node}`, which is defined in the `CATALINA_BASE/conf/catalina.properties` file. tc Server provides a default value for the `jvmRoute` attribute. You can specify a value other than the default when you create the tc Runtime instance by specifying the `cluster-node.node.name` property using the `--property` option as follows: `--property cluster-node.node.name=my-node`. Because this template does not specifically add a Connector to the instance's `server.xml` file, the `tcruntime-instance` script will automatically add a Blocking IO (BIO) HTTP Connector. For more information, see Clustering/Session Replication HOW-TO on the Apache Tomcat Web site.
diagnostics	This template: Adds a sample JDBC resource configuration that integrates with the request diagnostics to report slow queries. Adds a ThreadDiagnosticsValve at the Engine level to report on slow running requests. Because this template does not specifically add a Connector to the instance's `server.xml` file, the `tcruntime-instance` script will automatically add a Blocking IO (BIO) HTTP Connector.
insight	Developer Edition Only. This template adds the Spring Insight Web application to your instance. Spring Insight gives you real-time visibility into the behavior and performance of your user applications. See Using Spring Insight. Because this template does not specifically add a Connector to the instance's `server.xml` file, the `tcruntime-instance` script will automatically add a Blocking IO (BIO) HTTP Connector.
jmx-ssl	This template: Updates the `JmxSocketListener` to use SSL for all JMX communication Adds a sample JKS keystore that you can use to test the JMX over SSL configuration. Warning: The sample keystore is provided only to aid testing and debugging; it is not for production use. You must replace it with your own generated keystore before moving to a production system. Because this template does not specifically add a Connector to the instance's `server.xml` file, the `tcruntime-instance` script will automatically add a Blocking IO (BIO) HTTP Connector. For more information, see SSL Configuration HOW-TO on the Apache Tomcat Web site.
nio	This template adds a Non-Blocking IO (NIO) connector for HTTP. For more information, see The HTTP Connector on the Apache Tomcat Web site.
nio-ssl	This template: Adds an NIO HTTPS connector. Adds a sample JKS keystore that you can use to test the SSL configuration. Warning: The sample keystore is provided only to aid testing and debugging; it is not for production use. You must replace it with your own generated keystore before moving to a production system. For more information, see The HTTP Connector and SSL Configuration HOW-TO on the Apache Tomcat Web site.

Differences Between the Separate and Combined Layouts

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

Separate layout: In this layout, the instance's CATALINA_HOME and CATALINA_BASE point to two different directories. Typically, CATALINA_HOME points to a tomcat-6.0.X.X-RELEASE directory, which in turn contains the set of tc Runtime binaries that are shared by other instances that use the separate layout.
SpringSource highly recommends you use this layout, which is the default.
Combined layout: This layout closely resembles the standard Apache Tomcat layout where the instance's CATALINA_HOME and CATALINA_BASE point to the same directory. This means that each instance that uses the combined layout has its own copy of the tc Runtime binaries. For this reason, it is very difficult to upgrade to a new version of tc Runtime.
SpringSource does not recommend you use this layout, because it is so difficult to upgrade instances. The main reason for using it is if you are familiar with the Apache Tomcat layout and want to continue to use it in your environment.

Prev		Next
6.3 Overview of tc Server Directories, Variables, and Configuration Files	Home	7.2 Starting and Stopping tc Runtime Instances