Getting Started with tc Server

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

Hyperic HQ 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 HQ provides a single console with powerful dashboards through which you can easily check the health of your applications. With Hyperic HQ, you can:

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

SpringSource 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 HQ alerts, see tc Server Administration Guide, under Managing tc Runtime-Related HQ Alerts.

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

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

Because SpringSource tc Runtime is based on Apache Tomcat 6, 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 or Oracle WebLogic. Applications can be seamlessly moved from Apache Tomcat to SpringSource tc Runtime to gain the benefits that SpringSource tc Runtime provides beyond the base Apache Tomcat.

SpringSource tc Runtime has a number of advanced configuration features that Apache Tomcat does not.

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

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

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

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

SpringSource tc Runtime 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, an application that provides real-time visibility into the behavior and performance of your user applications. The Developer Edition contains a precreated tc Runtime instance called spring-insight-instance that includes the Spring Insight application. You can use this instance as a template to create new tc Runtime instances that also have Spring Insight. (Developer Edition does not include Hyperic HQ 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, which is a developer tool. One of the two Standard Edition packages includes management components (the HQ Server and Agent , which are preconfigured with the tc Server plug-in to Hyperic HQ.)

These two packages are:

Install a managed node if you want to use Hyperic HQ to configure and manage the tc Runtime. If you do not want to use Hyperic HQ to manage tc Runtime instances and want to use the tc Runtime on its own, install only the runtime package.

If you will use Hyperic HQ to manage tc Runtime instances, also install the HQ Server and be sure it has been configured with the tc Server HQ plug-in. An HQ Server preconfigured with the tc Server plug-in is available to Standard Edition users as a separate, license-constrained download.

You can upgrade an existing HQ installation to manage tc Runtime instances by installing the tc Server HQ plug-in into your existing HQ Server and HQ Agents. Your existing HQ installation must be the same fully-qualified version (or a later version) as the version of HQ bundled with tc Server. See the Release Notes for the latest fully-qualified versions of tc Server and its bundled components.

The Standard Edition is distributed as either a ZIP or compressed TAR file with the following names, where node refers to the managed node and standard refers to the runtime version:

The HQ Server that is preconfigured with the tc Server HQ plug-in is distributed as a platform-neutral ZIP or compressed TAR file, with the following names:

	Note
	Platform-specific HQ Server distributions are also available for existing 6.0.X tc Server users who want to upgrade to 2.0.X. For new tc Server users, SpringSource recommends you install the platform-neutral package.

The tc Server HQ plug-in is also separately downloadable so you can upgrade an existing HQ installation. The HQ plug-in has both an agent- and server-side component. Each component is distributed as a ZIP file with the following names:

The Spring Edition of tc Server includes the Standard Edition (managed node) and HQ Server, 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.

SpringSource tc Runtime supports:

SpringSource tc Runtime runs on versions 1.5 and 1.6 of the Java Runtime Environment (JRE.)

The following table lists the supported configurations for running the tc Runtime.

Because you typically install and run the HQ 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.0.X version of tc Runtime.

You can use the HQ application management features that are specific to tc Server only with the runtime component of tc Server (also called tc Runtime); these features do not work with standard Apache Tomcat. The HQ application management features include deploy, undeploy, start, stop, and reload of Web applications.

SpringSource tc Server provides the license to use the following set of HQ plug-ins that are suitable to the needs of tc Server environments:

The 2.0.6 release of tc Server does not contain any new features. See Fixed Issues for the list of issues that were fixed in this maintenance release.

The 2.0.5.SR1 release of tc Server contains no new features or fixed issues since release 2.0.5. The only change is to update the version of Tomcat used by tc Runtime to version 6.0.32.A. This is a security release to pick up changes since version 6.0.29C of Tomcat. See the Apache Tomcat Changelog for a list of the changes to Tomcat.

The 2.0.5 release of tc Server does not contain any new features. See Fixed Issues for the list of issues that were fixed in this maintenance release.

The 2.0.4 release of tc Server does not contain any new features. See Fixed Issues for the list of issues that were fixed in this maintenance release.

The following features are new in tc Server 2.0.3. Other than the new version of tc Runtime and bundled HQ, these features are in addition to all previous 2.0.X features.

See Fixed Issues for the list of issues that were fixed in this maintenance release.

There are no new features in tc Server 2.0.2. The only change in this release is that the known issue TCS-153 has been fixed.

See Fixed Issues for the list of issues that were fixed in this maintenance release.

The following features are new in tc Server 2.0.1. Other than the new version of tc Runtime, these features are in addition to all previous 2.0.X features.

See Fixed Issues for the list of issues that were fixed in this maintenance release.

The following features are new in tc Server 2.0.0.

The following major changes have occurred in the functionality of version 2.0.X of tc Server:

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 any component of tc Server. If you are installing Standard Edition or Spring Edition, this includes installing the JDK or JRE on the HQ Server computer as well as the computer(s) that will host tc Runtime and HQ Agent. 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 install the HQ Server and Agents that have been preconfigured with the tc Server HQ plug-in.

If you are installing tc Server for the first time, SpringSource recommends that you install the platform-neutral version of HQ Server. Platform-specific versions of HQ Server exist, but they have been made available only for existing tc Server users who are upgrading from previous versions.

The HQ Server uses a database to store its metadata. The platform-neutral version of HQ Server that is already configured with the tc Server plug-in 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.

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

If you are installing tc Server on Unix and have downloaded the compressed TAR file format (*.tar.gz), be sure that the tar command on your computer is compatible with the one required by the tc Server. Open a terminal window and enter:

prompt$ tar --help

Search the help output for a -z option (which filters the output through gzip); if the tar command on your computer supports this option, then it is compatible with the one required by tc Server and you can begin the installation.

If, however, your tar command does not supports this option, then you must install GNUtar (gtar) from an external source. For example, the Web site Sunfreeware.com includes many free downloads for the Solaris platform, including GNUtar.

After you install GNUtar, update the PATH environment variable (either of the user installing tc Server or the system-wide environment variable) to include the location of the gtar command. The location depends on the directory in which you installed GNUtar.

If you have installed GNUtar, then substitute the command gtar for any references to tar in the following install procedure.

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, see Next Steps.

See Next Steps for links to post-installation procedures.

This section describes how to install a managed node (tc Runtime and HQ Agent) as well as an HQ Server; both HQ components are preconfigured with 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/springsource-tc-server-edition/myserver directory (such as /home/tcserver/springsource-tc-server-node/myserver); you can specify a different instance directory with the -n instanceDir option. This directory is also the value of the CATALINA_BASE variable for this tc Runtime instance.

By default, the tc Runtime instance uses the JDK or JRE pointed to by the JAVA_HOME or JRE_HOME environment variables, respectively, or the instance uses the java binary that it found in the PATH environment variable when it started. Because no JDK or JRE has been explicitly set, the tc Runtime instance is portable; see Creating Portable tc Runtime Instances for more information. You can specify a different location for the JDK or JRE with the -j or -r options.

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

Because the preceding sample use of tcruntime-instance.sh|bat did not specify the -v version option, the version of the tc Runtime instance is unpinned. This means that when you use the tcruntime-ctl.sh|bat script to start the instance, the script uses the highest version of the tc Runtime it can find in the installation directory, for example 6.0.25.A-RELEASE. 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, if tc Server is installed on a 64-bit Windows operating system and you are using a 64-bit JVM, then you can specify that the tc Runtime instance use a 64-bit service wrapper; by default, the Windows service wrapper is 32-bit. You can also use the -p parameter to specify different port numbers from the default ones, and the -n parameter to specify a directory in which the instance lives other than the default tc Runtime installation directory.

The following table lists options of the tcruntime-instance.sh|bat command script.

You specify options with a single dash and a letter (such as -s) or with two dashes and a word (such as --server).

For example, to request that you be prompted for port numbers and that the tc Runtime installation directory is /home/tcserver/springsource-tc-server-node, run the following:

prompt$ ./tcruntime-instance.sh -s myserver -j /home/java/jdk1.6.0_12 -d /home/tcserver/springsource-tc-server-node -i

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

prompt$ ./tcruntime-instance.sh -s myotherserver -m -v 6.0.25.A-RELEASE 

Depending on whether you explicitly specify the -v 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:

Use the -h parameter of tcruntime-instance.sh|bat to list the known tc Runtime versions.

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

prompt$ ./tcruntime-instance.sh -s myserver -v 6.0.25.A-RELEASE

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

prompt$ ./tcruntime-instance.sh -s 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-6.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 -m parameter together with -v to specify the new version. For example:

prompt$ ./tcruntime-instance.sh -s myserver -m -v 6.0.26.A-RELEASE

Finally, if you want to convert a currently pinned instance to one that is unpinned, use the -m parameter without -v. For example:

prompt$ ./tcruntime-instance.sh -s myserver -m 

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/springsource-tc-server-node/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 example, assume you have two instances in the following directories running on a computer identified as my-desktop in HQ:

Although they are completely different instances, they will both show up in the HQ user interface with the name my-desktop tc Runtime myServer.

For this reason, SpringSource recommends as a best practice that you use unique names for the main installation directory for each tc Runtime instance on the same computer. For example, the following two instances will show up in the HQ user interface with different names:

To use the tcruntime-instance script to create a new tc Runtime instance with a template, use the -t (or --template) option. A template is simply a directory that contains additional or customized tc Runtime instance files, such as server.xml or JAR files. For example:

prompt$ ./tcruntime-instance.sh -s myserver -t cluster-node

An existing instance of tc Runtime can itself be used as a template.

When you specify the -t option, the tcruntime-instance script first creates the tc Runtime instance as usual, which mostly entails copying over the standard Tomcat files from the tomcat-version directory to the new instance directory, where version refers to the version of tc Runtime, such as 6.0.25.A-RELEASE. After the script creates a standard tc Runtime instance, it copies over the files and subdirectories contained in the specified tc Runtime template.

To use this feature, a template must already exist. You can create your own template, as described in Creating tc Runtime Templates, use one of the out-of-the-box templates, or even use an existing tc Runtime instance.

The files that make up a template reside in a single directory and 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. If you create a template, you can create additional subdirectories. When the tcruntime-instance script applies the template after it has created a new tc Runtime instance, it copies over all the files, including those in subdirectories. 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 replace the standard server.xml file with a new customized file, or copy one or more applications to the webapps directory so that they are automatically deployed on startup.

The argument to the -t option must be a template directory, an existing tc Runtime instance (which itself can act as a template), or a file that lists multiple template directories. If the template argument is a single name, the tcruntime-instance script assumes the template directory is located in the INSTALL_DIR/springsource-tc-server-edition/templates directory, where edition refers to the Edition of tc Server you are using (either node, developer, or standard.) You can also use an absolute directory name to specify a template directory in another location or an existing tc Runtime instance.

If you specify a file as an argument, the file must contain a list of absolute template directories. This feature enables you to easily apply multiple templates when creating a new instance. The tcruntime-instance script applies each template in order, first to last. This means that if each template contains a file with the same name and location, then only the last file actually takes priority because the first ones are copied over with files from subsequent templates.

The following example shows how to create a new tc Runtime instance called myserver using the cluster-node out-of-the-box template:

prompt$ ./tcruntime-instance.sh -s myserver -t cluster-node

In the preceding example, because it does not specify the -v or -j 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 a new tc Runtime instance called myserver using a custom template called my-super-template that is located in the templates directory:

prompt$ ./tcruntime-instance.sh -s myserver -t my-super-template

The following example shows how to create an instance using a template located in the directory /home/templates/tcserver/mytemplate:

prompt$ ./tcruntime-instance.sh -s myserver -t /home/templates/tcserver/mytemplate

The Developer Edition of tc Server includes a pre-created instance called spring-insight-instance; the instance is located in the INSTALL_DIR/springsource-tc-server-developer directory. The instance includes the Spring Insight feature. The following example shows how you can create a new tc Runtime instance using this existing instance:

prompt$ ./tcruntime-instance.sh -s myserver -t /home/tcserver/springsource-tc-server-developer/spring-insight-instance

The following example shows how to create an instance that uses multiple templates by specifying a file (templates.txt) that lists the templates; each template is listed with an absolute pathname, as shown after the example:

prompt$ ./tcruntime-instance.sh -s myserver -t templates.txt

The templates.txt file in turn contains a list of absolute template names:

/home/templates/tcserver/mytemplate
/home/templates/tcserver/myothertemplate

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.

Additionally, the Developer Edition of tc Server also provides an out-of-the-box instance called spring-insight-instance in the INSTALL_DIR/springsource-tc-server-developer directory. This instance includes the Spring Insight feature, and is ready to use as soon as you install the Developer Edition of tc Server. You can also use the instance as a template if you want to create new instances that are automatically configured with Spring Insight.

The following example shows how to use the cluster-node out-of-the-box template to create a tc Runtime instance that is automatically configured as a cluster node:

prompt$ ./tcruntime-instance.sh -s myserver-clustered -t cluster-node

Because the cluster-node template is in the templates directory, you simply specify its name at the -t 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 template.) All templates are located in the INSTALL_DIR/springsource-tc-server-edition/templates, where edition refers to the edition of tc Server you installed (node, developer, or standard.)

You can create your own templates that include customizations that you can then use later to create new customized tc Runtime instances.

The following file listing shows an example of a template called my-super-template; use it as a guide when creating your own templates. (You can also look at the out-of-the-box templates in the templates directory.) Note that the following sample template customizes the standard conf/context.xml and conf/server.xml files, adds JAR files to the lib and webapps directory and creates a new subdirectory (webapps-lib, alongside webapps), among other things:

my-super-template/lib/myapp_core-1.0.0.jar
my-super-template/lib/spring-instrument-classloading-3.0.0.BUILD.jar
my-super-template/deployToTomcat.sh
my-super-template/webapps-lib/myapp-springweb-1.0.0.jar
my-super-template/webapps-lib/myapp-springcore-1.0.0.jar
my-super-template/webapps-lib/myapp-jdbc-1.0.0.jar
my-super-template/webapps/myapp.war
my-super-template/conf/context.xml
my-super-template/conf/server.xml
my-super-template/conf/myapp.yml
my-super-template/instrument-tomcat.xml

A portable tc Runtime instance is one whose instance directory you can copy to a new directory name, and the instance still starts and works correctly without your having to update the instance configuration files.

To guarantee the portability of a newly-created tc Runtime instance, specify only the one required option of tcruntime-instance.sh|bat: -s serverName. Use the INSTANCE-DIR/bin/tcruntime-ctl.sh|bat script to start and stop the instance.

For example, assume you created a tc Runtime instance called myserveCcr in the main tc Server installation directory:

prompt$ cd /home/tcserver/springsource-tc-server-node
prompt$ ./tcruntime-instance.sh -s myserver

Because this instance is completely portable, you can copy the resulting instance directory to another location, and then start and use this new instance as if you had created it with the tcruntime-instance script. For example, assume you want to copy the myserver instance to the /home/tcserver/instances directory and call it myserver-new:

prompt$ cd /home/tcserver/springsource-tc-server-node
prompt$ cp -r myserver ../instances/myserver-new
prompt$ cd ../instances/myserver-new/bin
prompt$ ./tcruntime-ctl.sh start

Important: Remember that when you copy an instance in this way, the ports that the two tc Runtime instances listen to will be the same. If you want to run both instances on the same computer, update the conf/catalina.properties file of one instance to differentiate the port name.

By default, the tcruntime-instance.sh script creates all tc Runtime instances under the INSTALL_DIR/springsource-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 (node, 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 Managed Node.

To start and stop a tc Runtime instance:

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

On Unix platforms, the tc Runtime installation includes a command script file called INSTALL_DIR/springsource-tc-server-edition/boot.rc.template, which is a template file 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 go into detail 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/springsource-tc-server-node, 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/springsource-tc-server-node
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\springsource-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 node, 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 Managed Node.

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\springsource-tc-server-node\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.

Important: When you start a tc Runtime instance on Windows using the tcruntime-ctl.bat command script, the script might override the following parameters of the wrapper.conf file with instance-specific values:

This means, for example, that although the wrapper.conf file might appear to set the ARCH parameter to win32, the tcruntime-ctl.bat script overrides this generic value with something else (such as winx86_64) if in fact you are running the tc Runtime instance on a 64-bit computer.

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/springsource-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, standard, or node.)

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

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

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

prompt$ cd /home/tcserver/springsource-tc-server-node
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 60 seconds:

prompt$ cd /home/tcserver/springsource-tc-server-node/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/springsource-tc-server-node
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.

This topic applies to the Developer Edition of tc Server only.

The Developer Edition of tc Server includes Tomcat Manager, which is a simple Web application that you can use to deploy your own Web applications and manage their lifecycle, such as starting, stopping, and undeploying them.

The default configuration of Developer Edition of tc Server 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 from which you are running the tc Runtime instance or from the local computer on which you are running your browser. When deploying from the host, you must specify the context path that users use to actually invoke the application.

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

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.

Upgrading a 2.0.X tc Server installation to a later 2.0.X version consists of the following subtasks, which are explained in more detail in the next section:

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 the second and third subtasks. On the computer on which you installed the HQ Server (and nothing else), you perform only the first subtask. 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 have previously installed all components on the same computer, then simply execute all steps 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.

For simplicity, the examples in this procedure assume that you are upgrading a 2.0.0 tc Server installation to version 2.0.4 (unless otherwise noted.) The 2.0.0 tc Server installation consists of a managed node (6.0.25.A tc Runtime and 4.2.0.7 HQ Agent) on one computer and a 4.2.0.7 HQ Server on another computer; this setup is similar to the one described by the Quick Start Instructions. The procedure shows how to upgrade the same setup to version 2.0.4 of tc Server (6.0.29.A tc Runtime and 4.2.0.8 HQ Agent and Server.)

If your setup is different, adjust the procedure accordingly. For example, if you have installed Standard Edition (tc Runtime package), and thus do not use HQ, then follow only the tc Runtime sections of this procedure.

It is also assumed in this procedure that the HQ Server uses an external database, such as Oracle, rather than the database packaged with HQ Server.

To upgrade your 2.0.X tc Server installation to a later 2.0.X version, follow these steps:

When you complete this procedure for all components on all computers, you will have successfully upgraded your full 2.0.X tc Server installation to a later version of 2.0.

After you complete HQ upgrade, you must always use the new versions of HQ Server and Agents rather than the old ones. For details about starting and stopping them, see Starting and Stopping the HQ Server and Agents.

When you first connect to the HQ user interface that is using the upgraded HQ Server, the new 4.2.X.X HQ Agent(s) and your existing tc Runtime instance(s) show up in the Auto-Discovery portlet. You must add them to the Inventory before you can proceed. This is true whether you upgraded your existing instances to the latest tc Runtime or not.

After you add the existing tc Runtime instances to the HQ inventory, you should be able to manage and control them as before, and any previous custom configuration of the tc Runtime instances should show up intact, as well as all deployed applications. Additionally, all history and management information about the instance, such as control history, historical metric data, and alert settings, will still be available.

Upgrading a 6.0.X tc Server installation consists of the following subtasks, which are explained in the next section:

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 AMS agent and runtime component (called a managed node), you perform the second and third subtasks. On the computer on which you installed the AMS server (and nothing else), you perform only the first subtask. The procedure below breaks the steps into those you do on the managed node computer(s) and those you do on the AMS Server computer. If you have previously installed all components on the same computer, then simply execute all steps 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.

To upgrade your 6.0.X tc Server installation to 2.0.X, follow these steps:

When you complete this procedure for all components on all computers, you will have successfully upgraded your full tc Server installation.

After you complete the AMS -> HQ upgrade, you must always use the new HQ Server and Agents rather than the old AMS ones. For details about starting and stopping them, see Starting and Stopping the HQ Server and Agents.

Similarly, after you upgrade your existing tc Runtime instances to the latest version (such as 6.0.25.A-RELEASE), you must always use the tcruntime-ct.sh|bat scripts to control the instances. You should also use the tcruntime-instance.sh|bat script to create new instances.

When you first connect to the HQ user interface that is using the upgraded AMS->HQ Server, the new 4.2.X.X HQ Agent(s) and your existing tc Runtime instance(s) show up in the Auto-Discovery portlet. You must add them to the Inventory before you can proceed. This is true whether you upgraded your existing instances to the latest tc Runtime or not.

Both existing (upgraded or not) and newly-created tc Runtime instances now show up in the HQ user interface 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. For example:

my-computer tc Runtime myserver

Note

After you add the existing tc Runtime instances to the HQ inventory, you should be able to manage and control them as before, and any previous custom configuration of the tc Runtime instances should show up intact, as well as all deployed applications. However, all history and management information about the instance, such as control history, historical metric data, and alert settings, will be lost. This is due to the change in name of the resource from tc Server to tc Runtime, and there is no way for you to access this historic data after the upgrade. Also, if you invoke the new HQ user interface in the same browser in which you have previously invoked the old AMS administration console, you might have to clear the browser's cache and then reload the Web page so that the new HQ graphical objects and colors render correctly and do not get mixed up with the old AMS ones.

The HQ user interface is very similar to the old AMS console. If, however, you'd like more hands-on information about the user interface, see:

The procedure consists of the following high-level tasks:

The procedure first explains (if you are upgrading a 4.2 HQ installation) how you must ensure that it is at the minimum patch level required by the tc Server HQ plug-in (4.2.0.7 and how to upgrade if not; this does not apply to version 4.3 or 4.4. And then it describes how to apply the tc Server HQ plug-in to both the HQ Server and all the HQ Agents. Depending on how you have configured your Hyperic HQ installation, you might perform the HQ Server tasks on one computer, and then perform the HQ Agent tasks on multiple separate computers. However, for simplicity, it is assumed in the following procedure that you have installed the HQ Server and Agent on the same computer, and so you perform all the tasks on same computer. Make the appropriate changes to the procedure to fit your particular environment.

In the procedure examples, it is assumed you are upgrading a 4.3 HQ installation.

To upgrade a Hyperic HQ installation to manage tc Runtime instances:

For instructions on installing the Standard Edition (runtime package) of tc Server, see Installing Standard Edition (Runtime Package). Then see Creating a New tc Runtime Instance for details about creating a tc Runtime instance that you can then manage with HQ.

After upgrading and starting the HQ Server and Agents, and then creating and starting a tc Runtime instance, the instance automatically shows up in the Auto-Discovery portlet of the HQ user interface. The tc Runtime instance shows up 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. For example:

my-desktop tc Runtime myserver

As soon as you add the tc Runtime instances to the inventory, you can start to manage them. See Tutorial: Using HQ to Configure and Manage tc Runtime Instances for additional information.

For clarity, the migration procedure uses the following sample data; adjust the examples to fit your own environment accordingly:

The examples use Unix syntax; if you are performing this migration on Windows, change the forward slashes to back-slashes and replace the *.sh suffix with *.bat when running a command script.

To migrate an existing ERS server instance to tc Server 2.0.x:

After upgrading and starting the HQ Server and Agents, and then creating and starting a tc Runtime instance, the instance automatically shows up in the Auto-Discovery portlet of the HQ user interface. The tc Runtime instance shows up 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. For example:

my-desktop tc Runtime myserver

As soon as you add the tc Runtime instances to the inventory, you can start to manage them. See Tutorial: Using HQ to Configure and Manage tc Runtime Instances for additional information.

For instructions on installing the Standard Edition (runtime package) of tc Server, see Installing Standard Edition (Runtime Package). Then see Creating a New tc Runtime Instance for details about creating a tc Runtime instance that you can then manage with HQ.

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