Getting Started with vFabric tc Server

The tc Server runtime component, known as tc Runtime, offers substantial usability enhancements over the open-source Apache Tomcat server:

Hyperic is a comprehensive enterprise application management tool for managing and monitoring tc Runtime instances, Spring-powered applications, and a variety of non-SpringSource platforms and application servers such as Apache Tomcat. The server instances and applications can be running on multiple computers. Hyperic provides a single console with powerful dashboards through which you can easily check the health of your applications. With Hyperic, you can:

In addition to the preceding tc Runtime-specific Hyperic tasks, you perform the standard tasks:

tc Server includes a full set of diagnostic features that makes it easy for you to troubleshoot problems with a tc Runtime instance or the applications that you deploy to tc Runtime instances. These diagnostic features include:

For some diagnostics features, the tc Server HQ plug-in includes one or more preconfigured alerts that make it easy for you to monitor the tc Runtime instance, as well as manage the various thresholds at which an alert is triggered. For additional information about these diagnostic features, and information about managing the associated Hyperic alerts, see tc Server Administration Guide, under Managing tc Runtime-Related Hyperic Alerts.

You can use the command-line interface (CLI) tcsadmin to:

tc Runtime and Apache Tomcat share key standard features of application servers.

Because tc Runtime is based on Apache Tomcat, it provides a powerful yet lightweight platform that is compatible with existing Tomcat-based applications and with Web applications that run on other Java EE application servers such as IBM WebSphere Application Server or Oracle WebLogic Server. Applications can be seamlessly moved from Apache Tomcat to tc Runtime to gain the benefits that tc Runtime provides beyond the base Apache Tomcat.

tc Server offers scripts and templates to simplify performing a number of advanced configurations.

tc Runtime includes advanced, distributed management and monitoring capabilities through a centralized management console called Hyperic user interface.

The tables in this section list the capabilities that tc Runtime provides over and above the base Apache Tomcat and also notes the features that Hyperic provides for existing Apache Tomcat environments.

tc Runtime provides a wide range of capabilities that enable developers, administrators, and operators to centrally diagnose, measure, and monitor the distributed application infrastructure.

tc Runtime provides a centralized, secure dashboard that enables administrators and operators to organize, operate, and control their distributed applications and infrastructure.

tc Server provides scripting support for administrators and operators who prefer to create and run scripts to handle distributed configuration and deployment steps.

The Developer Edition of tc Server is geared towards the application developer. It contains the tc Runtime, along with utilities that make it easy to create and start tc Runtime instances and a set of templates that make it easy to quickly create specific preconfigured tc Runtime instances, such as cluster-node ready and SSL-enabled.

This edition also includes Spring Insight Developer, an application that provides real-time visibility into the behavior and performance of user applications. The tc Server Developer Edition contains a template called insight that includes the Spring Insight application. You use this template to create new tc Runtime instances enabled with Spring Insight. See Using Spring Insight Developer for help setting up and using Spring Insight. (tc Server Developer Edition does not include access to Hyperic Server and Agent.)

The Developer Edition is distributed as either a ZIP or compressed TAR file with the following names:

The Standard Edition of tc Server is geared towards the administrator. Similar to the Developer Edition, the Standard Edition contains the tc Runtime, scripts to easily create and start tc Runtime instances, and templates to quickly create specific types of tc Runtime instances (such as cluster-node ready or SSL-enabled.) This edition does not include Spring Insight Developer.

With the Standard Edition, you have access to the vFabric Hyperic management system, which (as of version 4.5) includes the tc Server HQ plugin in the general distribution. Install vFabric Hyperic if you want to use Hyperic to configure and manage the tc Runtime. If you do not want to use Hyperic to manage tc Runtime instances and want to use the tc Runtime on its own, install only the tc Runtime.

The Standard Edition is distributed as either a ZIP or compressed TAR file with the following names:

To download an evaluation of Hyperic, go to the VMware Downloads Center.

The Spring Edition of tc Server includes the Standard Edition and Hyperic management components, plus production optimizations for Spring-based applications in the form of instrumented JARs for the following Spring technologies: Spring Framework, Spring Security, Spring Web Flow, and Spring Web Services.

The tc Server 2.5.2 maintenance upgrades tc Runtime 6.0 and tc Runtime 7.0 and provides minor bug fixes.

The Hyperic tc Server plug-in version 2.5.2 is included in the Hyperic 4.5.2.1 maintenance release. The tc Server plug-in is now Java 1.5 compatible, as required by Hyperic.

tc Runtime Version Upgrades

tc Server 2.5.2 includes the following upgraded tc Runtime versions:

tc Runtime 7.0 Version Update

The tc Runtime 7.0 version is based on tomcat-7.0.16.A-RELEASE as its core.

New Option for Hyperic tc Server Command-Line create-group Command

The Hyperic tc Server command-line interface create-group command has a new --version option to specify the tc Runtime version. The option accepts values of 6.0 and 7.0. Only servers of the specified tc Runtime version can be added to a group.

The 2.5.0 release of tc Server includes support for tc Runtimes based on Tomcat 6.0 and Tomcat 7.0. You can choose the version of tc Runtime when you create an instance. tc Runtime 7.0 offers several new features, including support for the Servlet 3.0, JSP 2.2, and JSP-EL2.2 specifications, as well as security improvements.

Following are additional features and changes that are new to this tc Server release:

SpringSource tc Runtime supports:

SpringSource tc Runtime runs on version 1.6 of the Java Runtime Environment (JRE).

The following table lists the supported configurations for running the tc Runtime. Other configurations may be supported on request; contact your sales representative for details.

Because you typically install and run the Hyperic Agent on the same computer as the tc Runtime, you should also consult HQ Agent Requirements.

SpringSource recommends that you follow the guidance of your operating system or JVM vendor when deciding which patch levels should be applied to your computer. In general, the latest patch update levels are recommended.

The following tables list specifically tested patch update levels for the latest 2.5.X version of tc Runtime. This table is updated as new configurations are tested.

The following table lists the product issues that were fixed in the 2.5.2 maintenance release.

The following table lists the product issues that were fixed in the 2.5.1 maintenance release.

No editions of tc Server bundle a JDK or JRE. Before you install tc Server, download and install a JDK or JRE on each computer on which you will install the tc Runtime component of tc Server. If you are installing the HQ components, the JDK or JRE requirement depends on whether you install the platform-specific or platform-neutral version; only the latter requires a JDK or JRE because the former bundles one. See Supported Configurations for platform-specific details of the JDK or JRE versions that are supported and have been tested.

For most platforms you can download and install the Sun JDK or JRE, although for IBM computers you might want to install the IBM-specific JDK or JRE. The following links point to download Web sites:

After you install the JDK or JRE, set your JAVA_HOME environment variable to point to your installation and update your PATH environment variable to point to the JAVA_HOME/bin directory.

Windows only. If you are installing the management components of tc Server (HQ Server and Agent), then you must also set the HQ_JAVA_HOME system environment variable to point to the location of your JDK or JRE. Set HQ_JAVA_HOME as a system environment variable; if you set it as a user environment variable, the HQ Agent aborts on startup.

This section applies only if you are using the Standard or Spring editions of tc Server and you want to also install the HQ Server and Agents management components using the platform-neutral version of the HQ distribution.

The HQ Server uses a database to store its metadata. The platform-neutral version of HQ Server does not, however, bundle a database. This means that if you do not have a database server already installed on either the computer on which you are going to install HQ Server or on an accessible remote computer, then you must download and install one. The platform-specific versions of the HQ distribution bundle a non-production database for you to get started, although it is not recommended that you use this database for production purposes.

Use Oracle 10g/11g, PostgreSQL, or MySQL 5.x with HQ Server. During the installation of HQ Server, you will provide the database URL for JDBC connection and the database username and password.

To set up one of these databases for use with HQ Server, see Set Up Hyperic Database.

This section contains notes about installing tc Server on Unix systems.

prompt$ tar --help

See Using Spring Insight for overview and usage information about Spring Insight as well as information about creating plug-ins that extend Spring Insight.

For general tc Server post-installation tasks discussed in this section, such as creating tc Runtime instances and starting them, see Next Steps.

See Next Steps for links to post-installation procedures.

This section describes how to install one or more instances of tc Runtime and HQ Agent together (also referred to as a managed node), as well as a single HQ Server; assuming the HQ components are version 4.5 or later, both HQ components automatically include the tc Server HQ plug-in.

Read How tc Server and HQ Work Together to understand the various installation scenarios for managed nodes and the HQ Server. Then decide which tc Server components (tc Runtime, HQ Agent, and HQ Server) you are going to install on your computer(s). The typical scenarios are:

The procedure below breaks the steps into those you do on the managed node computer(s) and those you do on the HQ Server computer. If you are installing everything on the same computer, then simply execute all steps on the same computer.

	Note
	If you will be installing tc Runtime instances on multiple computers you must install HQ Agent on each computer.

If you have an existing HQ installation, see Upgrade and Migration Guide for details about upgrading HQ with the tc Server HQ plug-in.

See Next Steps for links to post-installation procedures.

See Overview of tc Server Directories, Variables, and Configuration Files for conceptual information about tc Server directories and configuration files. See Post-Installation Tasks for the list of typical post-installation procedures, such as creating tc Runtime instances, starting the various components of tc Server and getting started with the HQ user interface.

Then try out the tutorials: Tutorial: Using HQ to Configure and Manage tc Runtime Instances and Tutorial: Very Simple Web Application Development.

The following tc Server variables are used:

The following variables are "exposed" by tc Runtime, which means that you can set them or use them in your environment (or in the bin/setenv.sh file of your tc Runtime instance) to achieve the specified results:

After you create a new tc Runtime instance, its CATALINA_BASE directory contains the following sub-directories:

You configure a particular tc Runtime instance by changing its configuration files (either by editing the XML file manually or through the HQ user interface); later chapters of this documentation describe how to do this. All the configuration files for a tc Runtime instance are located in its CATALINA_BASE/conf directory. The most important configuration files are as follows:

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.

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:

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.

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]

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

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

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

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

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:

1. Install the new tc Server release in a directory alongside the existing tc Server installation.

2. 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

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 

prompt$ ./tcruntime-instance.sh help

prompt$ ./tcruntime-instance.sh help create

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

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:

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 

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.

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

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).

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

By default, the tcruntime-instance.sh script creates all tc Runtime instances under the INSTALL_DIR/vfabric-tc-server-edition directory, where INSTALL_DIR refers to the directory in which you installed tc Server, such as /home/tcserver, and edition refers to the edition or package of tc Server you are using (developer or standard). Each tc Runtime instance lives in its own directory; this directory translates into the server's CATALINA_BASE variable. This is the default behavior of the command script; you might have specified a different location of your tc Runtime instance.

In the following procedure, it is assumed that you installed a tc Server Standard Edition.

To start and stop a tc Runtime instance:

See tcruntime-ctl Command Reference for the full list of commands of the tcruntime-ctl script.

For Unix platforms, the tc Runtime installation includes a command script file called INSTALL_DIR/vfabric-tc-server-edition/boot.rc.template, which is a template that you can use to customize your Unix boot process so that tc Runtime instances start automatically when your computer starts. It is assumed that you already know how to customize the Unix boot process for your particular platform, so this section does not provide details about where you should put this particular boot file (although typically you rename the file something like boot.rc and put it in the /etc/rc.d directory.) Rather, this section describes the updates you should make to the boot template file to reflect your tc Runtime instance environment. Consult your Unix administration documentation for further details about customizing the boot process.

A one-to-one relationship exists between a boot.rc file and a tc Runtime instance. For example, to start multiple tc Runtime instances automatically on the same Unix computer, you create separate boot.rc files for each tc Runtime instance, modify each of them to reflect the environment of the corresponding tc Runtime instance, and then put each of these files in the appropriate boot directory.

Edit only the top part of the boot.rc.template file that sets the following environment variables:

The following example specifies the tc Runtime home directory as /home/tcserver/vfabric-tc-server-standard, the instance directory as the tc Runtime home directory, the instance name as myserver, the JDK location as /home/java/jdk1.6.0_11, and the tomcat user as the starter of tc Runtime process:

TOMCAT_USER=tomcat
TC_SERVER_HOME=/home/tcserver/vfabric-tc-server-standard
INSTANCE_BASE=$TC_SERVER_HOME
INSTANCE_NAME=myserver
JAVA_HOME=/home/java/jdk1.6.0_11

Do not modify any part of the boot.rc.template file after the text DO NOT EDIT BEYOND THIS LINE.

By default, the tcruntime-instance.bat script creates all tc Runtime instances under the INSTALL_DIR\vfabric-tc-server-edition directory, where INSTALL_DIR refers to the directory in which you installed tc Server, such as c:\home\tcserver and edition is developer or standard. Each particular tc Runtime instance lives in its own directory; this directory translates into the server's CATALINA_BASE variable. This is the default behavior of the command script; you might have specified a different location of your tc Runtime instance. If so, adjust the following procedure accordingly.

In the following procedure, it is assumed that you installed a tc Server Standard Edition.

To start and stop tc Runtime instances as Windows Services:

To uninstall the tc Runtime service, execute the following command:

prompt> tcruntime-ctl.bat uninstall

Although SpringSource recommends that you always install the tc Runtime instance as a Windows service and stop and start it using the Services console, you can also stop and start the tc Runtime instance manually. See tcruntime-ctl Command Reference for the full list of commands of the tcruntime-ctl script.

On Windows, tc Runtime uses a Java Service Wrapper from Tanuki Software to install the tc Runtime instance as a Windows service. The Wrapper correctly handles user logouts under Windows, service dependencies, and the ability to run services which interact with the desktop.

The wrapper is configured using the CATALINA_BASE\conf\wrapper.conf file, where CATALINA_BASE is the top-level directory of the tc Runtime instance, such as c:\home\tcserver\vfabric-tc-server-standard\myserver. In most circumstances, you do not need to update this file because the default one created when you created the tc Runtime instance handles most use cases. However, you might sometimes want to further customize the Windows service to fit particular circumstances of your environment; in which case you can edit the wrapper.conf file.

For details about the configuration properties, see Configuration Property Overview.

You use the tcruntime-ctl.sh (Unix) and tcruntime-ctl.bat (Windows) command scripts to manage tc Runtime instances. The syntax of the script is as follows:

tcruntime-ctl.sh|bat command [option]

Typically, you run the command from the bin directory of the tc Runtime instance itself. However, you can also run it from the INSTALL_DIR/vfabric-tc-server-edition directory if you specify the name of the instance, where INSTALL_DIR refers to the directory in which you installed tc Server and edition refers the edition of tc Server (developer or standard.)

For example, to start a tc Runtime instance called myserver from the bin directory of the instance itself on Unix:

prompt$ cd /home/tcserver/vfabric-tc-server-standard/myserver/bin
prompt$ ./tcruntime-ctl.sh start

You can accomplish the same thing by running the command from the vfabric-tc-server-standard (or vfabric-tc-server-developer) directory by specifying the name of the instance:

prompt$ cd /home/tcserver/vfabric-tc-server-standard
prompt$ ./tcruntime-ctl.sh myserver start

It is assumed in the remainder of this section that you are running the command script from the bin directory of the tc Runtime instance.

The following table describes the tcruntime-ctl script commands and supported platforms.

The following table describes the options you can use with the tcruntime-ctl script. All the options are optional; you can use them with any of the tcruntime-ctl commands.

The following example shows how to stop the tc Runtime instance called myserver after waiting for up to 60 seconds:

prompt$ cd /home/tcserver/vfabric-tc-server-standard/myserver/bin
prompt$ ./tcruntime-ctl.sh stop 60

In the following example, use of the -n option indicates that the tc Runtime instance called myotherinstance has an instance directory of /home/tcserver/instances/myotherinstance. The example shows how to use the tcruntime-ctl script located in the main tc Server installation directory.

prompt$ cd /home/tcserver/vfabric-tc-server-standard
prompt$ ./tcruntime-ctl.sh myotherinstance stop 60 -n /home/tcserver/instances

The tcruntime-ctl.bat install command has an optional run-as-user parameter by which you specify the user account that you want the tc Runtime service to run as when you start the service from the Windows Service console. Windows requires that the specified user account must have their Logon as Service right set for this feature to work properly. To set this right:

The Local Security Policy tool does not appear to be available on Home versions of Windows 2000 and XP. It is thus not possible to run the tc Runtime service as a specific account under those versions of Windows.

To start and stop the HQ Server:

See the HQ_SERVER_INSTALL_DIR/logs/server.log for details about the starting or stopping of the HQ Server.

To start and stop the HQ Agent:

See the HQ_AGENT_INSTALL_DIR/log/agent.log for details about the starting or stopping of the HQ Agent.

To start and stop the HQ Server:

See the HQ_SERVER_INSTALL_DIR\logs\server.log for details about the starting or stopping of the HQ Server.

To start and stop the HQ Agent:

See the HQ_AGENT_INSTALL_DIR\log\agent.log for details about the starting or stopping of the HQ Agent.

The tc Server Developer Edition includes Tomcat Manager, an Apache Web application that you can use to deploy your own Web applications and manage their lifecyle, such as starting, stopping, and undeploying them.

The default tc Server Developer Edition configuration does not automatically authorize any user to access Tomcat Manager. The following procedure describes how to authorize a user to access the application, and then how to invoke the Web application in your browser.

The Applications table lists the currently deployed applications. Click the links in the Path column to actually invoke each application. The Commands column includes buttons for starting, stopping, reloading, and undeploying the applications.

From the Deploy section, you can deploy Web applications (either exploded or in a WAR format) from either the host where running the tc Runtime instance or from the local computer running your browser. When deploying from the host, you must specify the context path that users use to invoke the application.

For detailed information about Tomcat Manager, see the Manager App How-To on the Apache Tomcat Web site.

When you create an instance using tc Runtime 7, you can deploy multiple versions of the same web application. This makes it possible to upgrade applications without interruption. Users who have a session in process continue to use the existing version of the application, but new sessions use the latest version of the application.

To deploy a new version of an existing application using static deployment, append a version number to the context name, separated by two hash signs: contextName##version. For example, if you have already statically deployed a WAR file named myapp.war and you want to upgrade to version 2.0, you can deploy the new WAR file myapp##02.0.war.

If you use the Hyperic HQ user interface to deploy a new version, do not rename the WAR file. The tc Server HQ plug-in automatically appends the version number for you.

Users continue to use the same URL to access the application; they do not include the version number. New sessions use the highest version deployed. Existing sessions continue to use the version that is already managing their session. If tc Runtime cannot locate the session in the SessionManager of an earlier version, the newest version is used.

The version number is processed as a string, not as a number. This means that you can use letters in the version number, for example myapp##02b. It also means that you must be careful to ensure that your version numbers compare correctly. If the current version is myapp##9.0, deploying myapp##10.0 will not work as expected because the string "9.0" sorts higher than "10.0".

When all sessions using an earlier version of an application have ended, the older version can be undeployed.

To uninstall the HQ Server component of tc Server:

To uninstall the HQ Agent component of tc Server:

The following procedure describes how to uninstall the tc Runtime and all its associated instances.

If you are using an older version of Hyperic HQ Server, Hyperic 4.5 HQ Server includes new features and support for new releases of supported resources. To take advantage of these improvements in Hyperic 4.5, upgrade HQ Server on the computer where it is installed. The Hyperic 4.5 setup has an upgrade mode that updates an existing HQ Server installation. For complete instructions, see the vFabric Hyperic Documentation website.

After you have upgraded HQ Server to Hyperic 4.5, you can use the HQ user interface to upgrade HQ Agents on computers with tc Runtime instances. Follow the instructions to upgrade Hyperic components on the Hyperic Documentation website.

Install tc Server 2.5 in a new installation directory and create any new tc Runtime instances you want. Follow the instructions at Installing tc Server to perform the installation. To avoid overwriting files, be sure to install tc Server 2.5 in a different directory than your current installation. For example, if you have installed tc Server 2.1 in the directory /home/tcserver/springsource-tc-server-2.1, you can install vFabric tc Server 2.5 in the directory /home/tcserver/vfabric-tc-server-2.5.

Use the tcruntime-instance.sh|bat upgrade command to upgrade your tc Server 2.0 or 2.1 runtime instances to tc Server 2.5. The upgrade command, new in tc Server 2.5, migrates configuration information and applications from an existing instance to a new 2.5 instance.

By default, the upgrade command creates a new instance that uses the same version of tc Runtime as the current instance. If you want to keep the same tc Runtime version, you must ensure that the corresponding tc Runtime release exists in your tc Server 2.5 installation directory. Otherwise, the upgrade command will display an error message and quit. If necessary, copy the tc Runtime release directory from the previous tc Server installation directory into the tc Server 2.5 installation directory.

The script creates the upgraded instances in your tc Server 2.5 installation directory. For example, to upgrade the tc Server 2.1 instance at /home/tcserver/springsource-tc-server-2.1/myInstance, enter the following command in your tc Server 2.5 directory:

prompt$ ./tcruntime-instance.sh ../springsource-tc-server-2.1/myInstance upgrade

This command creates an upgraded instance with the same name as the original (myInstance) using the same version of tc Runtime.

To change the name of the upgraded instance, include the -i instanceDir option on the command.

To specify a different tc Runtime version, include the -v version option. When upgrading an unpinned instance, you must specify this option. The following example specifies a new instance name and pins the instance to tc Runtime release 7.0.6.A.RELEASE.

prompt$ ./tcruntime-instance.sh ../springsource-tc-server-2.1/myInstance upgrade 
   -i myNewInstance -v 7.0.6.A.RELEASE

See tcruntime-instance.sh Reference for more information about using this command.

Upgrading a 2.5.X tc Server installation to a later version consists of the following subtasks:

Depending on how you have configured your tc Server installation, you might perform different subtasks on different computers. For example, on the computer on which you have installed the HQ Agent and runtime component (called a managed node), you perform only the Agent and Runtime upgrade. On the computer on which you installed the HQ Server (and nothing else), you perform only the HQ Server upgrade. If you installed all components on the same computer, then simply execute all subtasks on the same computer.

Most of the examples in this section use Unix syntax; if you are upgrading on Windows, change the forward slashes to back-slashes and replace the *.sh suffix with *.bat when running a command script. Other changes between the two platforms are called out.

The examples in this procedure assume you are upgrading a 2.5.0 tc Runtime to version 2.5.1 (unless otherwise noted.) The procedure describes only how to upgrade the tc Runtime and associated instances; for information about upgrading the Hyperic components, see Upgrade Hyperic Components.

To upgrade your 2.5.X tc Runtime to a later 2.5.X version, follow these steps:

When you complete this procedure, you will have successfully upgraded your existing 2.5.X tc Runtime to a later version of 2.5.

In the preceding code:

For complete documentation about the Java Servlet technology, including API reference documentation, specifications, and tutorials, see Java Servlet Technology.

The hello.jsp page is a static HTML page embedded with a JSP command. A JSP command is an XML-like snippet that encapsulates logic that dynamically generates content within the static HTML. JSP commands can include directives, declarations, expressions, actions, and blocks of Java code, all enclosed within angle-brackets, like XML elements. At compile-time, the JSP is converted into a servlet, which is what tc Runtime instance actually executes at runtime.

The hello.jsp includes the following simple JSP directive:

<%= new String("Hello!") %>

This JSP directive simply prints out a message to the client (browser): Hello!

For complete documentation about JSPs, including specifications, FAQs, and tutorials, see JavaServer Pages Technology.

In the preceding web.xml deployment descriptor file, the <servlet> XML element declares the HelloServlet, the examples.Hello Java class implements the servlet, and the <servlet-mapping> XML element specifies the /hello URL pattern that invokes the servlet in a browser. This URL pattern is used in the index.html file.

The Ant build.xml file defines targets for compiling and packaging the HelloWorld Web application. In preparation, the build process first creates an output directory and creates the required directory hierarchy below it for a standard Web application. This includes the WEB-INF directory that will contain the web.xml file. The build process also sets the build's CLASSPATH value to include the required JAR files in the tc Server distribution.

The compile target uses the Java compiler to compile the Java servlet file into a class and copies it to the output directory. The package target creates a JAR file of the output directory.