Getting Started with tc Server

Juliet Shackell

tc Server

2.0

Copyright © 2010 VMware Inc. All rights reserved.


Table of Contents

1. Copyright Notice
2. Quick Start Instructions
3. Overview of tc Server
3.1. Features of tc Server
3.2. Comparing tc Runtime and Apache Tomcat
3.3. tc Server Editions
3.4. Supported Configurations
3.5. How tc Server and HQ Work Together
3.6. Restrictions and Licensing
3.7. Links to Additional Documentation
4. Release Notes
4.1. New Versioning Process
4.2. What's New and Changed in This Release?
4.3. Known Issues
4.4. Fixed Issues
5. What Are the Main Steps Required to Get Going?
5.1. Before You Begin
5.2. Installing tc Server and Creating a New tc Runtime Instance
5.3. Starting the Components and Doing Initial Configuration
5.4. Exploring the Features of tc Server
6. Installing tc Server
6.1. Before You Begin: System Requirements
6.2. Installing tc Server: Main Steps
6.3. Overview of tc Server Directories, Variables, and Configuration Files
7. Post-Installation Tasks
7.1. Creating a New tc Runtime Instance
7.2. Starting and Stopping tc Runtime Instances
7.3. Windows: Installing the HQ Server and Agents as Windows Services
7.4. Starting and Stopping the HQ Server and Agents
7.5. Getting Started with the HQ User Interface
7.6. Deploying Applications to tc Runtime Instances
7.7. Uninstalling tc Server: Typical Steps
8. Upgrade and Migration Guide
8.1. Before You Begin: Installation Prerequisites and New Versioning Process
8.2. Upgrading a 2.0.X tc Server Installation to the Latest Version
8.3. Upgrading a 6.0.X tc Server Installation to the Latest Version
8.4. Upgrading an Existing 4.2, 4.3 or 4.4 Hyperic HQ Installation to Manage tc Runtime Instances
8.5. Upgrading Only the tc Runtime Version
8.6. Upgrading Only the Server-Side tc Server HQ Plug-in
8.7. Migrating an ERS Server Instance to tc Server 2.0.x
9. Tutorial: Using HQ to Configure and Manage tc Runtime Instances
9.1. Before You Begin
9.2. Restart a tc Runtime Instance
9.3. Reconfigure a tc Runtime Instance
9.4. Deploy a Web Application to a tc Server Runtime Instance
9.5. Add tc Runtime Instances to the Favorite Resources Portlet
9.6. Create an HQ Group of Multiple tc Runtime Instances
9.7. Monitoring tc Runtime Instances
9.8. Manage the Preconfigured Deadlock Detected Alert
10. Tutorial: Very Simple Helloworld Web Application
10.1. Before You Begin
10.2. Creating and Deploying the Helloworld Web Application
10.3. Java Source of the Hello.java Servlet
10.4. JSP Source for the hello.jsp JSP
10.5. Sample web.xml File
10.6. Sample Default index.html File
10.7. Ant Build File to Compile and Package the Example
11. Troubleshooting
11.1. HQ: Resources Not Showing up in the HQ User Interface
11.2. HQ: Errors When Trying to Add an Auto-Discovered Resource
11.3. HQ 4.3: Non-hqadmin User With Custom Role Unable to Restart tc Runtime Instance
11.4. HQ Agent: Errors When Starting on Solaris
11.5. tc Runtime: Hot Redeploy/Stop/Undeploy on Windows Fails
11.6. tc Runtime: Error When Running a Web Application on tc Runtime and Using SpringSource Tool Suite
11.7. tc Runtime: JVM Performing a Full GC
A. Using the ASF Layout
A.1. Differences Between the SpringSource and ASF Layouts of tc Server
A.2. Creating a New tc Runtime Instance Using the ASF Layout
A.3. Starting and Stopping tc Runtime Instances in the ASF Layout

1. Copyright Notice

Copyright © 2010 VMware Inc. All rights reserved.

VMware Web Site Legal Notice

2. Quick Start Instructions

This section provides quick start instructions for installing a tc Server Standard Edition managed node and an HQ server (configured with the tc Server HQ plug-in) on the same computer, creating a tc Runtime instance, and starting all components. For simplicity, the instructions install all components (tc Runtime, HQ Agent, and HQ Server) into the same directory.

[Note]Note

tc Runtime is the runtime component of tc Server.

If you want to install the Developer or Spring Editions of tc Server; install different components on different computers; or simply want more detailed installation instructions, see Installing tc Server. It is assumed that you are installing tc Server from scratch; if you are upgrading an existing tc Server installation, see the upgrade documentation.

To install all tc Server components:

  1. Download and install a JDK or JRE on your local computer. See Required Software: JDK or JRE.

  2. Download and install a database server on your local or remote computer. See Possibly Required Software: Database Server.

    Obtain the URL and username/password for the database connection, because the HQ Server installation program will ask for it.

  3. Open a terminal (Unix) or command prompt (Windows) and create a new directory that will contain tc Runtime, the HQ Agent, and the HQ Server, such as /home/tcserver. For example, on Unix:

    prompt$ mkdir /home/tcserver
  4. From the SpringSource Download Center, download the springsource-tc-server-node-2.0.X.RELEASE.zip file and unzip the contents into the directory you created in the preceding step.

    This action is all that is required to install tc Runtime and the HQ Agent ; there is no installer program.

    For example, if you created a directory called /home/tcserver in the preceding step, after you unzip the ZIP file you will have a directory called /home/tcserver/springsource-tc-server-node. This directory in turn includes the HQ Agent (in the hyperic-hq-agent-4.2.X.X-EE sub-directory) and all the tc Runtime files and directories.

  5. From the SpringSource Download Center, download the hyperic-hq-installer-noJRE-tc-server-2.0.X.RELEASE.zip file and unzip it into a temporary directory.

  6. From your terminal window or command prompt, change to this temporary directory and execute the setup.sh (Unix) or setup.bat (Windows) script:

    prompt$ cd /temp/hyperic-hq-installer-noJRE-tc-server-2.0.X.RELEASE
    
    prompt$ ./setup.sh

    After accepting the terms of agreement, enter 1 to install only the HQ Server (you installed the HQ Agent in a preceding step.) The script asks a few more questions, such as information about your database and the directory in which you will install HQ Server (/home/tcserver in our example.)

    When the setup.sh script completes, HQ Server is installed in the directory /home/tcserver/server-4.2.X.X-EE.

To create a tc Runtime instance and start all components:

  1. From your terminal window or command prompt, change to the tc Server node directory and execute the tcruntime-instance command to create a tc Runtime instance:

    prompt$ cd /home/tcserver/springsource-tc-server-node
    prompt$ ./tcruntime-instance.sh -s myserver
  2. Execute the tcruntime-ctl command to start the new tc Runtime instance:

    prompt$ ./tcruntime-ctl.sh myserver start

    To ensure that the tc Runtime instance actually started, invoke its welcome page in a browser. Use the URL http://host:8080, where host is the computer on which the tc Runtime instance is running (localhost if local):

    http://localhost:8080
  3. Start the HQ Server:

    prompt$ cd /home/tcserver/server-4.2.X.X-EE/bin
    prompt$ ./hq-server.sh start 
  4. Start the HQ Agent:

    prompt$ cd /home/tcserver/springsource-tc-server-node/hyperic-hq-agent-4.2.X.X-EE/bin
    prompt$ ./hq-agent.sh start

    The first time you start the HQ Agent, it prompts for information about the HQ Server to which it will connect. If this is a non-production installation, you can usually take the default values. When the script prompts you for the HQ server IP address, enter 127.0.0.1 or localhost. The default HQ login/password is hqadmin/hqadmin.

  5. Invoke the HQ server console using the URL http://host:7080 in your browser, where host is the computer on which the HQ server is running (localhost if local):

    http://localhost:7080

    Username and password, by default, are both hqadmin.

    The tc Runtime instance should show up automatically in the auto-discovery portlet. Click the Help link on the HQ server console for online help.

3. Overview of tc Server

3.1 Features of tc Server

SpringSource tc Server is a Web application server based on open-source Apache Tomcat. It preserves the best of Tomcat and adds many mission-critical operational capabilities that are unavailable in the open-source product:

For a detailed comparison between SpringSource tc Server and Apache Tomcat, see Comparing tc Runtime and Apache Tomcat.

tc Server Enhancements to Apache Tomcat

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

  • Improved out-of-the-box configuration. In most cases, you can use tc Server immediately after you install it, with no additional configuration.

  • Easy creation of a tc Runtime instance with the tcruntime-instance command script. You can leverage additional (optional) configuration features by specifying prepackaged templates when you create a tc Runtime instance, such as automatically configuring clustering or SSL.

  • Easy and intuitive to start a tc Runtime instance on both UNIX and Windows platforms.

  • Default configuration of high-concurrency JDBC connection pool in new tc Runtime instances.

  • Tunable local standard configuration files using the catalina.properties file.

Easy Configuration and Monitoring with Hyperic HQ

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:

  • Manage the lifecycle of tc Runtime instances by starting, stopping, and restarting a local or remote instance.

  • Similarly manage the lifecycle of a group of tc Runtime instances that are distributed over a network of computers.

  • Configure a single instance of tc Runtime. Configuration options include the various port numbers to which the tc Runtime instance listens, JVM options such as heap size and enabling debugging, default server values for JSPs and static content, JDBC datasources, various tc Runtime connectors, and so on.

  • Deploy a Web application from an accessible file system, either local or remote. You can deploy to a single tc Runtime instance or to a predefined group of servers.

  • Manage the lifecycle of applications deployed to a single tc Runtime instance or group of servers. Application lifecycle operations include start, stop, redeploy, undeploy, and reload.

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

  • Inventory the resources on your network.

  • Monitor resources.

  • Receive alerts on problems with resources. The tc Server HQ plug-in includes a variety of preconfigured alerts.

  • Control resources.

Enhanced Diagnostics

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:

  • Thread diagnostics. When you deploy and start a Web application on a tc Runtime instance, and then clients begin connecting and using the application, you might find that the clients occasionally run into problems such as slow or failed requests. By default, tc Runtime logs errors in the log files; however, it is often difficult to pinpoint the exact source of the error and how to fix it. With thread diagnostics enabled, tc Runtime provides additional troubleshooting information.

  • Deadlock detection. The tc Server HQ plug-in automatically detects whether a thread deadlock occurs in a tc Runtime instance or an application deployed to the instance.

  • Time in Garbage Collection.The tc Server HQ plug-in has a new metric that represents the percentage of process up time (0 -100) that a tc Runtime instance has spent in garbage collection.

  • Tomcat JDBC DataSource monitoring. A new tc Server HQ plug-in service represents the high-concurrency Tomcat JDBC datasources you have configured for your tc Runtime instance. This service monitors the health of the datasource, such as whether its connection to the database has failed or was abandoned, and whether the JDBC queries that clients execute are taking too long.

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.

tc Server Command-Line Interface and Command Scripts

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

  • List servers, groups, and deployed applications.

  • Deploy applications

  • Configure tc Runtime instances and groups

  • Control tc Runtime instances and groups

3.2 Comparing tc Runtime and Apache Tomcat

The runtime component of SpringSource tc Server (tc Runtime) is an enterprise version of Apache Tomcat. tc Runtime is a drop-in replacement for Apache Tomcat 6, ensuring a seamless upgrade path for existing custom-built and commercial software applications already certified for Tomcat. Maintaining this level of compatibility enables customers to add the functionality they need to run and manage their applications more effectively with the least amount of effort.

SpringSource tc Runtime also adds many business-critical features to standard Apache Tomcat. The following sections compare the two:

Standard Application Server Features

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

Table 3.1. Standard Application Server Feature Comparison

Application Server FeaturesSpringSource tc RuntimeApache Tomcat
Servlet 2.5 supportYesYes
Java Server Pages (JSP) 2.1 supportYesYes
HTTP session clusteringYesYes
Advanced I/O featuresYesYes
Pre-built advanced non-blocking I/O componentsYesYes
Basic Windows service wrapperYesYes

Enterprise Application Server Features

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.

Table 3.2. Enterprise Application Server Feature Comparison

Enterprise Application Server FeaturesSpringSource tc RuntimeApache Tomcat
Multiple runtime instances from a single binary installationYesNo
New high-concurrency JDBC connection pool`YesNo
Preconfigured for JMX managementYesNo
Includes latest security vulnerability and bug fixesYesRebuild Tomcat yourself to apply incremental fixes.
Binary patch updatesYesBinary patches are not provided by Tomcat community.
Unix boot scriptsYesNo
Enhanced Windows service wrapperYesNo

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

Table 3.3. Advanced Configuration Feature Comparison

Advanced Configuration FeaturesSpringSource tc RuntimeApache Tomcat
Templated production-ready configuration out-of-the-box.YesNo
Create Tomcat single server configuration.YesNo
Modify general server configuration including JVM startup parameters.YesNo
Modify context container configuration.YesNo
Modify server defaults for JSPs and static content.YesNo
Add, modify, and delete JDBC datasources.YesNo
Modify HTTP and AJP connector settings.YesNo
Create and view general services.YesNo
Modify general engine configuration.YesNo
Pre-tuned JVM options.YesNo

Business-Critical Operational Features

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.

Table 3.4. Diagnostics, Metrics, and Monitoring Feature Comparison

Diagnostics, Metrics, and Monitoring FeaturesSpringSource tc RuntimeApache Tomcat
Application deadlock detectionYesNo
Uncaught exception detectionYesNo
Garbage collection metrics, including throughput and countYesNo
SQL query time monitoring metrics.YesNo
Enhance response time monitoring metricsYesNo
Enhanced connection pool health metricsYesNo
Enhanced thread pool health metricsYesNo
Role-based customizable dashboardYesYes (via Hyperic HQ)
Automated inventory of application servers and software resourcesYesYes (via Hyperic HQ)
Real-time metric collection and monitoring of tc Runtime, Tomcat, Apache Web server, Apache ActiveMQ, underlying JVM, operating system, and other resourcesYesYes (via Hyperic HQ)
Charting and graphing performanceYesYes (via Hyperic HQ)
Advanced alerting: multi-conditional, availability, event, and recovery alerts, group-based alerting, and escalation schemes.YesYes (via Hyperic HQ)
Log file tracing, alerts on event levelsYesYes (via Hyperic HQ)
Alerts based on configuration file updatesYesYes (via Hyperic HQ)
Performance baselining for alert thresholdsYesYes (via Hyperic HQ)

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

Table 3.5. Centralized Operations and Management Feature Comparison

Centralized Operations and Management FeaturesSpringSource tc RuntimeApache Tomcat
Secure, distributed, JMX-based server managementYesNo
Create application server groupsYesYes (via Hyperic HQ)
Application server start/stop/restart from central consoleYesYes (via Hyperic HQ)
List deployed applications and current statusYesNo
Application deploy/undeploy/reload/start/stopYesNo
Security and access/authorization controlYesYes (via Hyperic HQ)
Scheduled control: maintenance activities, on-demand actions, scheduled remediation actions, or scheduled responses to alert conditionsYesYes (via Hyperic HQ)

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

Table 3.6. Scripting Feature Comparison

Scripting FeaturesSpringSource tc RuntimeApache Tomcat
List deployed servers.YesNo
Create server groups.YesNo
Add and delete servers to and from groups.YesNo
List deployed applications, including current status.YesNo
Deploy application WAR file.YesNo
Undeploy application.YesNo
Start, stop, and reload deployed applications.YesNo
Get (download) configuration files and JVM parameters from a server.YesNo
Modify configuration files on an individual server.YesNo
Set (push) configuration files and JVM parameters to a server group.YesNo
Start, stop, and restart a server or group of serversYesNo

3.3 tc Server Editions

SpringSource tc Server is available in the following editions:

Developer Edition

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:

  • springsource-tc-server-developer-2.0.X.RELEASE.zip
  • springsource-tc-server-developer-2.0.X.RELEASE.tar.gz

Standard Edition

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:

  • Standard Edition, tc Runtime package: tc Runtime component, scripts, and templates.

  • Standard Edition, tc Server Managed Node: tc Runtime package components and Hyperic HQ Agent preconfigured with the tc Server HQ plug-in. (In a separate download you will install HQ Server.)

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:

  • springsource-tc-server-node-2.0.X.RELEASE.zip
  • springsource-tc-server-node-2.0.X.RELEASE.tar.gz
  • springsource-tc-server-standard-2.0.X.RELEASE.zip
  • springsource-tc-server-standard-2.0.X.RELEASE.tar.gz

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:

  • hyperic-hq-installer-noJRE-tc-server-2.0.X.RELEASE.zip
  • hyperic-hq-installer-noJRE-tc-server-2.0.X.RELEASE.tar.gz
[Note]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:

  • springsource-tc-server-hq-plugin-server-2.0.X.RELEASE.zip
  • springsource-tc-server-hq-plugin-agent-2.0.X.RELEASE.zip

Spring Edition

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.

3.4 Supported Configurations

The sections that follow list the configurations supported by version 2.0.X of the tc Runtime component.

For the equivalent information about versions 6.0.X of tc Server, see Supported Configurations.

For supported configuration information about the HQ Server and Agent, see HQ Installation Requirements.

Supported Java EE Specifications

SpringSource tc Runtime supports:

Supported JRE Versions

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

Supported Configurations: tc Runtime

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.

Table 3.7. Supported Configurations

Operating SystemMajor VersionChip ArchitectureJVMtc Runtime Version
RedHat Enterprise Linux (RHEL)V4x86 32/64 bitSun Hotspot 1.5, 1.62.0.X
RedHat Enterprise Linux (RHEL)V5x86 32/64 bitSun Hotspot 1.5, 1.62.0.X
Debian Linux5.0x86 32 bitSun Hotspot 1.62.0.X
SUSE Linux Enterprise Server (SLES) V11x86 64 bitSun Hotspot 1.5, 1.62.0.X
Windows2008 Serverx86 32/64 bitSun Hotspot 1.5, 1.62.0.X
Windows2003 Server (SP1 and newer)x86 32/64 bitSun Hotspot 1.5, 1.62.0.X
Solaris9SparcSun Hotspot 1.5, 1.62.0.X
Solaris10
  • Sparc

  • Intel 32/64 bit

Sun Hotspot 1.5, 1.62.0.X
AIX5.3PowerPC 32/64 bitIBM JVM 1.5, 1.62.0.X
AIX6.1PowerPC 32/64 bitIBM JVM 1.5, 1.62.0.X
Mac OSX10.5x86 64 bitApple 1.52.0.X
Mac OSX10.6x86 64 bitApple 1.62.0.X

Tested Configurations: tc Runtime

The following tables list specifically tested patch update levels for the latest 2.0.X version of tc Runtime.

Table 3.8. Tested Configurations

Operating SystemMajor VersionChip Architecture (Tested)Fully Qualified of JVM Version (Tested)Version of tc Runtime (Tested)
RedHat Enterprise Linux (RHEL)V4x86 32 bit
  • Sun Hotspot 1.5.0_22

  • Sun Hotspot 1.6.0_18

2.0.4
RedHat Enterprise Linux (RHEL)V4x86 64 bit
  • Sun Hotspot 1.5.0

  • Sun Hotspot 1.6.0

2.0.4
RedHat Enterprise Linux (RHEL)V5x86 32 bit
  • Sun Hotspot 1.5.0_22

  • Sun Hotspot 1.6.0_20

2.0.4
RedHat Enterprise Linux (RHEL)V5x86 64 bit
  • Sun Hotspot 1.5.0_22

  • Sun Hotspot 1.6.0_18

2.0.4
Debian Linux5.0x86 32 bitSun Hotspot 1.6.0_18 2.0.0
SUSE Linux Enterprise Server (SLES) V11x86 64 bit
  • Sun Hotspot 1.5.0_18

  • Sun Hotspot 1.6.0_20

2.0.2
Windows2008 Serverx86 32 bit
  • Sun Hotspot 1.5.0_9

  • Sun Hotspot 1.6.0_21

  • 2.0.2 (JDK 1.5)

  • 2.0.4 (JDK 1.6)

Windows2008 Serverx86 64 bit
  • Sun Hotspot 1.5.0_09

  • Sun Hotspot 1.6.0_21

2.0.4
Windows2003 Server x86 32 bit
  • Sun Hotspot 1.5.0_09

  • Sun Hotspot 1.6.0_18

2.0.4
Windows2003 Server x86 64 bit
  • Sun Hotspot 1.5.0_17

  • Sun Hotspot 1.6.0_18

2.0.4
Solaris10Sparc
  • Sun Hotspot 1.5.0_18

  • Sun Hotspot 1.6.0_13

2.0.4
Solaris10Intel 32 bit
  • Sun Hotspot 1.5.0_20

  • Sun Hotspot 1.6.0_18

2.0.0
Solaris10Intel 64 bit
  • Sun Hotspot 1.5.0_20

  • Sun Hotspot 1.6.0_18T

2.0.4
Solaris9Sparc
  • Sun Hotspot 1.5.0

  • Sun Hotspot 1.6.0

2.0.0
AIX5.3PowerPC 32 bit
  • IBM 1.6.0

  • IBM 1.5.0

2.0.1
AIX5.3PowerPC 64 bit
  • IBM 1.6.0

  • IBM 1.5.0

2.0.2
AIX6.1PowerPC 32 bit
  • IBM 1.6.0

  • IBM 1.5.0

2.0.2
AIX6.1PowerPC 64 bit
  • IBM 1.6.0

  • IBM 1.5.0

2.0.0
Mac OSX10.5x86 64 bitApple 1.5.0_192.0.0
Mac OSX10.6x86 64 bitApple 1.6.0_20 2.0.2

3.5 How tc Server and HQ Work Together

SpringSource tc Server is available in a variety of editions, based on whether you are a developer or an administrator. The Standard and Spring editions of tc Server, because they are targeted at administrators, include the HQ management capabilities. This section shows how the runtime component of tc Server (called the tc Runtime) and the HQ components (HQ Server and HQ Agents) work together, and possible configurations that you can install on one or more computers.

The simplest scenario is where you install all components (tc Runtime, HQ Agent, and HQ Server) on the same computer. In this case, the computer acts as a host for the tc Runtime instances and their deployed applications as well as a host to the HQ Server and HQ Agent, which are used to manage the tc Runtime instances.

Figure 3.1. Installing on One Computer

Installing on One Computer


In the preceding figure, the HQ Server is managing just one tc Runtime instance. The HQ server can, of course, manage multiple instances, as well as manage other kinds of servers. Because the tc Runtime instances are all on one computer, you only need to install one HQ Agent.

Figure 3.2. Multiple tc Runtime Instances on One Computer

Multiple tc Runtime Instances on One Computer


A slightly more complicated scenario is where you create multiple tc Runtime instances on one computer, say computerA, and the HQ Server on computerB. In this case, you must install the HQ Agent on computerA so that the HQ Server is able to manage the tc Runtime instances on computerA from computerB. SpringSource refers to computerA as a managed node.

Figure 3.3. Installing on Two Computers

Installing on Two Computers


In another scenario, you host the HQ Server on computerB, but want to install tc Runtime on many computers, possibly of different platforms such as Unix and Windows. In this case you must also install the HQ Agent on each computer (managed node) that hosts the tc Runtime instances.

In the following figure, for example, computerC might be a Windows platform while all the rest of the computers are Unix. Also note that each computer has a different set of tc Runtimes installed, but only one HQ Agent. In the figure, all computers except computerB are managed nodes.

Figure 3.4. Installing on Multiple Computers

Installing on Multiple Computers


3.6 Restrictions and Licensing

Restrictions

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.

HQ Plug-Ins Licensed For Use With SpringSource tc Server

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:

  • Operating Systems: AIX, HP/UX, Linux, Solaris, Windows, Mac OSX, FreeBSD

  • Web Servers: Apache

  • Java Platform: JVM

  • Application Servers: SpringSource tc Runtime, Apache Tomcat

3.7 Links to Additional Documentation

Because tc Runtime is based on Apache Tomcat, much of the documentation about using tc Runtime itself is provided by Apache.

The HQ plug-in component of tc Server provides monitoring and management for your Web infrastructure. You can use it to streamline operations, manage infrastructure complexity, and drive service level improvements. The HQ user interface includes online-help for both generic HQ functionality, as well as tc Server related functionality. For detailed documentation about HQ:

The following links provide additional documentation for programmers who develop Web applications using the Spring Framework and standard Java EE technologies such as servlets and JSPs:

4. Release Notes

The following sections contain release-specific information about tc Server.

4.1 New Versioning Process

As of the tc Server 2.0.x release, the bundle itself will now have a version number separate from the underlying components. The 2.0 release represents the second major revision of the tc Server product bundle. Minor revisions, maintenance updates, and service releases of any set of underlying components will likewise increment the fully qualified bundle version. As of the 2.0 release, the bundle contains the following separately versioned components. The initial major version of each component is noted. Specific downloads will have fully qualified version information on each component.

  • tc Runtime: Apache Tomcat-based runtime container, major version 6.0. The fully qualified version of the tc Runtime is a combination of the underlying Apache Tomcat version and an alphabetic modifier to track maintenance updates on the same underlying Tomcat version, for example, 6.0.25.A-RELEASE .
  • tc Server HQ Plug-In: Hyperic HQ plug-in that enables advanced management and monitoring, major version 2.0.
  • Hyperic HQ Agent: Agent portion of bundle, major version 4.2.
  • Hyperic HQ Server: HQ Server, preconfigured with the tc Server HQ plug-in, major version 4.2.

4.2 What's New and Changed in This Release?

2.0.6

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.

  • Tomcat version: SprintSource tc Runtime 2.0.6 uses version 6.0.32.A of Tomcat at its core.

  • HQ version: tc Server 2.0.6 bundles version 4.2.0.8 of the HQ Server and Agent.

2.0.5.SR1

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.

2.0.5

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.

  • Tomcat version: SpringSource tc Runtime 2.0.5 uses version 6.0.29.C of Tomcat as its core.

  • HQ version: tc Server 2.0.5 bundles version 4.2.0.8 of the HQ Server and Agent.

2.0.4

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.

  • Tomcat version: SpringSource tc Runtime 2.0.4 uses version 6.0.29.A of Tomcat as its core.

  • HQ version: tc Server 2.0.4 bundles version 4.2.0.8 of the HQ Server and Agent.

2.0.3

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.

  • Tomcat version: SpringSource tc Runtime 2.0.3 uses version 6.0.29.A of Tomcat as its core.

  • HQ version: tc Server 2.0.3 bundles version 4.2.0.8 of the HQ Server and Agent.

  • HQ 4.3/4.4 Support: SpringSource tc Server 2.0.3 now supports version 4.3 and 4.4 of HQ. This means, for example, that you can now upgrade an existing 4.3 or 4.4 HQ installation so it can manage tc Runtime instances. Previously, tc Server supported upgrading only version 4.2.0.7 of HQ. For details, see Upgrading an Existing 4.2, 4.3 or 4.4 Hyperic HQ Installation to Manage tc Runtime Instances.

  • Changes in HQ 4.3 Permission Models: Due to changes in the permission model of HQ 4.3, the role assigned to non-hqadmin users who want to control tc Runtime instances might need to be updated such that the role is assigned a group that contains the Platform resource on which the tc Runtime instance runs. This change applies only to HQ 4.3 or later installations that have been upgraded with the tc Server HQ plug-in. For details, see HQ 4.3/4.4: Non-hqadmin User With Custom Role Unable to Restart tc Runtime Instance.

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

2.0.2

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.

  • Tomcat version: SpringSource tc Runtime 2.0.2 uses version 6.0.26.B of Tomcat as its core.

  • HQ version: tc Server 2.0.2 bundles version 4.2.0.7 of the HQ Server and Agent.

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

2.0.1

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.

  • Tomcat version: SpringSource tc Runtime 2.0.1 uses version 6.0.26.A of Tomcat as its core.

  • HQ version: tc Server 2.0.1 bundles version 4.2.0.7 of the HQ Server and Agent.

  • Spring Insight Update: The pre-built spring-insight-instance in the Developer Edition of tc Server now uses version 1.0.0.M3 of Spring Insight. This version of Insight includes the following major new features:

    • Integration between Google Speed Tracer and Spring Insight so that you can now see Insight Trace data interleaved with Speed Tracer's browser timings.
    • Improved graphical interface. In particular, the old Application Health tab has been replaced with the Browse Resources tab which provides a single mechanism for you to browse through all your data using a simple resource tree.
    • A set of annotations that you can use in your application to inform Insight of a particular method you want it to trace and expose. This is a way to customize Insight for your particular environment without having to write a new Insight plug-in.

    For details about all these new features and general information about using Spring Insight, see Using Spring Insight.

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

2.0 New Features

The following features are new in tc Server 2.0.0.

  • Tomcat version: SpringSource tc Runtime uses version 6.0.25.A of Tomcat as its core.

  • HQ version: tc Server bundles version 4.2.0.7 of the HQ Server and Agent.

  • Integration with Hyperic HQ 4.2: The management component of tc Server is Hyperic HQ, rather than SpringSource AMS. The tc Server-specific management features are implemented as an HQ plug-in.

  • tc Server editions: SpringSource tc Server is available in Developer, Standard, and Spring editions); the edition most suited to your needs depends on your role. See tc Server Editions.

  • Spring Insight Development Kit: Create your own Spring Insight plug-ins tailored to the needs of your application. See Using Spring Insight.

  • tc Runtime Templates: Use out-of-the-box templates to create a new tc Runtime instance and to automatically enable specific server features, such as clustering and SSL. See Creating a New tc Runtime Instance.

  • Portable tc Runtime Instances: Create tc Runtime instances that you can copy to another location and begin using immediately. See Creating Portable tc Runtime Instances.

  • Customizing tc Runtime Status Code Response: Customize the way that tc Runtime displays messages or status pages in response to a particular HTTP status code. See Reporting Status for a Deployed Application, Host, or Engine.

2.0 Changes in Functionality

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

  • Terminology Change: The application server component of tc Server that is based on Apache Tomcat is now called tc Runtime, and similarly, instances are now called tc Runtime instances, rather than tc Server instances.

  • Script name changes: The names of the instance-creation and control scripts for tc Runtime instances have changed. Old names: tcserver-instance.sh|bat and tcserver-ctl.sh|bat. New names: tcruntime-instance.sh|bat and tcruntime-ctl.sh|bat.

    If you upgrade an existing 6.0.20.C (or previous) tc Runtime instance to version 6.0.25.A-RELEASE or later, the existing tcserver-instance.sh|bat and tcserver-ctl.sh|bat scripts are deprecated. After the upgrade, you must use the tcruntime-instance.sh|bat and tcruntime-ctl.sh|bat scripts instead. Additionally, you must rename the instance-specific tcserver-ctl.sh|bat scripts to tcruntime-ctl.sh|bat; this step is describe more fully in the Upgrade and Migration Guide.

  • Installation changes: The installation of the runtime component of tc Server (tc Runtime) is now easier: you just unpack a ZIP or compressed TAR file into the home directory. See Installing tc Server.

  • Script option name change: The -tcserverdir option of the tcruntime-instance.sh|bat script (previously called tcserver-instance.sh|bat) has been renamed -tcruntimedir.

4.3 Known Issues

The following table lists the user-visible known issues in SpringSource tc Server that you might encounter while using tc Server. Where possible, a workaround is also provided.

The table indicates the version of tc Server in which the issue was found and, where appropriate, the version in which it was fixed. If the issue was specific to Hyperic HQ, then the correponding HQ JIRA is also listed, and, where appropriate, the version of HQ in which the issue was fixed.

Note: For known and resolved issues in the 6.0 release of tc Server, see the 6.0 documentation. For the HQ release notes, which include the known and resolved issues, see HQ Release Notes. The following table includes selected HQ known issues that are particularly relevant to tc Server users, although you should check the HQ release notes for the full list.

Table 4.1. Known Issues

Issue IDDescriptionFound InFixed In
TCS-153If you use the HQ user interface to add a new JDBC datasource to a tc Runtime instance, and then restart the instance, you are unable to subsequently modify that JDBC datasource. Clicking the Save button on the UI after attempting to modify the datasource has no effect.2.0.12.0.2
TCSRV-1276Upgrade only. After upgrading the AMS Server 2.0.X to HQ Server 4.2.X.X-EE, you must manually update the server.java.opts property of the HQ-SERVER-INSTALL-DIR/conf/hq-server.conf file in order to properly deploy WAR files using the upload mechanism. To the server.java.opts property, add: -Dorg.apache.catalina.STRICT_SERVLET_COMPLIANCE=false.

For example:

server.java.opts=-XX:MaxPermSize=192m -Xmx512m -Xms512m \
-XX:+HeapDumpOnOutOfMemoryError -Dorg.apache.catalina.STRICT_SERVLET_COMPLIANCE=false
2.0.0 
TCSRV-1262, HHQ-3833Each time HQ Server performs an auto-discovery, a long stack trace that starts with the following exception is logged to the log file:
2010-03-18 08:22:07,443 ERROR [Thread-27] 
   [org.hyperic.hq.autoinventory.server.session.AutoinventoryManagerEJBImpl@735] 
   Ignoring non-existent server type: Net Services 

This does not affect the functionality of the product.

2.0.0 
TCSRV-1252, HHQ-3806If you install the HQ Server on a 64-bit Solaris operating system (both Sparc and Intel), then the HQ server's startup script (hq-server.sh) forces you to also use a 64-bit JRE/JDK, even if you have set your JAVA_HOME environment variable to point to a 32-bit JRE/JDK.

Workaround: In the bin/hq-server.sh file, search for the string -d64 and manually remove it, then restart the server.

2.0.0 
TCSRV-1248, HHQ-3875, HHQ-3876Unix only. When installing the platform-specific version of the HQ Server (which includes a built-in Postgres database server) on a Unix machine with an /etc/hosts file that does not set localhost to 127.0.0.1, the installation of the Postgres database server fails. However, rather than stopping the installation of the HQ Server, the HQ Server installation continues and reports success at the end. The error message about the failure of the Postgres installation scrolls off the screen, so unless you have been monitoring the installation closely, you likely do not know that anything is wrong until you start the HQ Server, at which point it fails.

Workaround: Be sure that the /etc/hosts file sets localhost to 127.0.0.1.

2.0.0 
TCSRV-1232, HHQ-3877When you upgrade an existing AMS installation (from an existing 6.0.X tc Server installation) to Hyperic HQ 4.2, and the setup.sh HQ install script detects that an HQ Server database already exists at the JDBC connection URL you specify, the script asks what you want to do with this database. If you specify option 3 to exit the installer, the setup.sh script displays an error, even though the script does in fact exit normally without making modifications to the database. The error is as follows:
An ERROR occurred, the installation cannot continue.
FATAL EXCEPTION at /opt/hyperic-hq-...RELEASE/installer-4.2.X.X-EE/data/setup.xml:141: 
   The following error occurred while executing this line:
/opt/hyperic-hq-...RELEASE/installer-4.2.X.X-EE/data/setup-interactive.xml:15: 
   org.hyperic.util.NestedRuntimeException$NestedEx: No modifications made to 
   existing database.  Exiting installer. 
2.0.0 
TCSRV-1187,HHQ-3512Windows only. The -D Java properties configured for the HQ server via the server.java.opts property of the hq-server.conf file do not get propagated to the HQ Server when you install it as a Windows service or start it at the command line. This is particularly important if your applications do not conform to strict Servlet specification compliance and you need the org.apache.catalina.STRICT_SERVLET_COMPLIANCE property set to FALSE (which is how the property is set in the hq-server.conf file.)

Workaround: Explicitly specify the properties when you install the HQ Server as a Windows service or when you start it. For example, when installing as a Windows service:

prompt> <HQ-SERVER-INSTALL-DIR>\bin\hq-server.exe -i -D org.apache.catalina.STRICT_SERVLET_COMPLIANCE=false

Important: Note that, in this particular workaround, you are required to put a space between the -D flag and the name of the property, as shown in the preceding example.

If you have already installed the HQ Server as a service without specifying the required Java properties, you must uninstall it, then re-install it:

  1. From the Windows Services UI, find the HQ Server service, then right-click on it and click Stop. The service is listed as Hyperic HQ Server in the Windows services UI.
  2. Open a command prompt.
  3. Uninstall the HQ Server service by running the following command:
    prompt> <HQ-SERVER-INSTALL-DIR>\bin\hq-server.exe -u
  4. Reinstall the HQ Server service, specifying the Java properties:
    prompt> <HQ-SERVER-INSTALL-DIR>\bin\hq-server.exe -i -D org.apache.catalina.STRICT_SERVLET_COMPLIANCE=false
  5. From the Windows Services UI, start the HQ Server service by right-clicking on it and clicking Start.

If you do not want to install the HQ Server as a service but rather, start it from the command-line, you must explicitly specify the -D org.apache.catalina.STRICT_SERVLET_COMPLIANCE=false option. For example:

prompt> <HQ-SERVER-INSTALL-DIR>\bin\hq-server.exe -D org.apache.catalina.STRICT_SERVLET_COMPLIANCE=false start
2.0.0HQ 4.3.0
TCSRV-1179If you restart a tc Runtime instance that has one or more connection pools configured, you may see the following error in the HQ Agent log:
2010-02-01 17:49:23,058 INFO [Thread-1] [MeasurementCommandsService] Updating log_track plugin 3:10203 
    [SpringSource tc Server 6.0 Tomcat JDBC Connection Pool Global Win32]
2010-02-01 17:49:23,074 WARN [Thread-1] [MxNotificationListener] 
    tomcat.jdbc:name="jdbc/petclinic",type=ConnectionPool,class=org.apache.tomcat.jdbc.pool.DataSource: 
    Listener not found
2010-02-01 17:49:23,090 ERROR [Thread-1] [MeasurementCommandsService] 
    addNotificationListener(tomcat.jdbc:name="jdbc/petclinic",type=ConnectionPool,
    class=org.apache.tomcat.jdbc.pool.DataSource): 
    tomcat.jdbc:name="jdbc/petclinic",type=ConnectionPool,class=org.apache.tomcat.jdbc.pool.DataSource
org.hyperic.hq.product.PluginException: addNotificationListener(tomcat.jdbc:name="jdbc/petclinic",
    type=ConnectionPool,class=org.apache.tomcat.jdbc.pool.DataSource): 
    tomcat.jdbc:name="jdbc/petclinic",type=ConnectionPool,class=org.apache.tomcat.jdbc.pool.DataSource

This is a timing issue that occurs when the HQ Agent attempts to locate the MBean before it is fully instantiated.

Workaround: Update the server.xml file of your tc Runtime instance and set the attribute initialSize="0" for the <Resource> element that configures your JDBC connection pool.

This setting ensures that the initialization of the JDBC connection pool does not try to open any connections until it is being requested.

2.0.0 
TCSRV-1177When executing the tcruntime-instance.sh|bat --list option to list all the known tc Runtime instances in a particular installation, the script does not fully use the INSTANCE_BASE environment variable. In particular, the script uses INSTANCE_BASE as the location of the instances, but not the names of the instances. For the latter, the script continues to use the names from the tc Server installation directory.

Workaround: Use the -d / --tcruntimedir and -n / --instancedir options of tcruntime-instance.sh|bat to get this information.

2.0.02.0.1
TCSRV-989, HQ-2007If you deploy a Web application which has embedded ActiveMQ, the HQ Server does not auto-discover the embedded ActiveMQ server and the resource does not show up in the HQ user interface for you to add to the inventory. This is an issue with the Hyperic HQ Server.2.0.0HQ 4.3
TCS-82If you specify the -d . parameter when using the tcruntime-instance.sh|bat script to create a new tc Runtime instance, you cannot use the tcruntime-ctl.sh|bat scripts in the bin directory of the instance itself to start the instance. If you do, the script goes into an infinite loop. For example:
prompt$ cd /home/tcserver/springsource-tc-server-node
prompt$ ./tcruntime-instance.sh -s myserver -d .
prompt$ cd myserver/bin
prompt$ ./tcruntime-ctl.sh start
INFO Derived instance name: myserver
INFO Executing ./tcruntime-ctl.sh
INFO Derived instance name: myserver
INFO Executing ./tcruntime-ctl.sh
... <and so on>

Workaround: Instead of specifying a period to indicate the current directory with the -d parameter, use the full pathname of the current directory. Alternatively, use the main INSTALL-DIR/springsource-tc-server-node/tcruntime-ctl.sh|bat scripts to start the instance.

2.0.02.0.1
TCS-81When upgrading a pinned tc Runtime instance, if you specify the -m parameter of the tcruntime-instance.sh|bat script without also specifying the -v parameter, the resulting tc Runtime is still incorrectly pinned to the latest version of tc Runtime. The correct behavior is for the resulting instance to be unpinned; thus when you start the instance with tcruntime-ctl.sh|bat, the script applies the highest version of the tc Runtime it can find rather than always using a specific version.

Workaround: Manually remove the INSTANCE-DIR/conf/tomcat.version file, which results in the instance being unpinned to a specific version.

2.0.02.0.1
TCS-75When using the tcsadmin command-line interface to stop, and then start, a tc Runtime instance, you might see the following error in both the HQ Server and Agent:
2010-01-12 19:52:52,060 ERROR [JMS SessionPool Worker-13] 
   [org.hyperic.hq.control.server.session.ServerRestartHandler@73]  
   Failure re-enabling log/config tracking for entity 3:10108
org.hyperic.hq.product.PluginException: Agent error: 
   addNotificationListener(tcServer:type=Serviceability,
   name=DiagnosticsValve,engine=Catalina): 
   tcServer:type=Serviceability,name=DiagnosticsValve,engine=Catalina

The tc Runtime instance starts correctly.

2.0.0 
TCS-71The following error message is displayed on the HQ user interface dashboard when the HQ Agent is running with non-Sun JRE:
This resource is turned off or has not been configured properly.
The problem is: Invalid configuration: Plugin error: Plugin class not found: 
  com.sun.management.GarbageCollectionMXBean...
(continues)

This error is harmless and does not affect the functionality of the product.

2.0.02.0.1
TCS-61Windows only. Stopping applications that are using embedded Hibernate, MySQL, or instrumented JAR files does not work correctly. This problem occurs with both the HQ user interface and the tcsadmin command-line interface.

Workaround: Set the antiResourceLocking="true" and antiJARLocking="true" properties in the context.xml file of the application or tc Server. Subsequently, stopping and undeploying the application works correctly. See The Context Container for more information about adding or updating the context.xml file of an application or tc Server.

2.0.02.0.1
TCS-60Creating a tc Runtime instance on the Debian Linux platform using their bundle JDK results in the following error:
Exception in thread "main" java.lang.ExceptionInInitializerError
at java.lang.Class.initializeClass(libgcj.so.90)...

Workaround:Use a JDK downloaded from Sun.

2.0.02.0.1
TCS-57This problem occurs only if you have created an HQ group of two or more tc Runtime instances in which at least one is running on Windows and another is running on Unix. If you subsequently use the put-file command of the tcsadmin.bat command-line script on a Windows platform against the HQ group, and use backslashes to specify the name of the file (for example, --targetfile=conf\server.xml), when tcsadmin pushes the file to the Unix computer, it incorrectly creates a file with a name that contains the backslash (for example, a file that is actually called "conf\server.xml"), rather than pushing the file server.xml to the conf directory.

Workaround: Use forward slashes when specifying the put-file, even when running tcsadmin on a Windows platform. For example, --targetfile=conf/server.xml.

2.0.02.0.1
TCS-54When you use the HQ user interface, the calculations for the current number of tc Runtime Active and Idle Connections can be incorrect in certain circumstances.2.0.0 
TCS-51Windows only. When using the HQ user interface to change the tc Runtime configuration, if you change one of the Advanced options in the Configuration -> Server Start window and save your changes, the HQ Server overwrites the wrapper.app.parameter.1 parameter in the wrapper.conf file, which in turn prevents tc Server from starting.2.0.02.0.1
TCS-44A regression occurs in the Tomcat JSP Expression Language (EL) processing in version 6.0.25.A-RELEASE. In some cases, text that happens to look similar to a deferred expression (#{..}) can get mangled even if the EL is not active. This appears to happen only if the text in question immediately proceeds a custom tag (either a full blown custom tag or a simple .tag file tag). The initial # and { characters get removed.

For additional details, see ASF Bugzilla Bug 48668.

2.0.02.0.1
TCS-37When you use the HQ user interface to deploy or redeploy a very large WAR file, and your hard drive does not have much space left, the HQ user interface displays a confusing and unhelpful message. The tc Runtime log file displays a useful error: java.io.IOException: No space left on device.

Workaround: Check the tc Runtime log file for more useful error messages if the deploy/redeploy of a very large WAR file fails.

2.0.02.0.1
TCS-29Windows only. When you invoke tcruntime-ctl.bat help on Windows to view the list of available commands, the valid restart option is missing.

Additionally, specifying the help option prints the following erroneous error: ERROR Second parameter must be an instance command.

2.0.02.0.1
TCS-27If you run the tcruntime-instance.sh script with the force option (--force or -f) and the instance you are overwriting is running, the script still overwrites the instance without any warning or prompt.

Workaround: Restore the instance from backup.

2.0.02.0.1

4.4 Fixed Issues

The following tables list the product issues that were fixed in a given 2.0.x maintenance release, starting with 2.0.1.

Table 4.2. Issues Fixed in 2.0.6

Issue IDDescription
TCS-43JMXSocketListener in server.xml overrides java.rmi.server.hostname system property without warning. Now, a message is logged if the system property is overwritten by a different value.
TCS-1256Update the jdbc-pool to implement getConnection(username, password).
TCS-1521In the documentation, tcsadmin config refers to the .ams directory instead of .hq.
TCS-1593The tcsadmin deploy-application help text indicates that --serverid and --servername parameters are optional if the other is specified. To clarify, only one of the options should be specified.
TCS-1594The tcsadmin restart command times out occasionally waiting for the restart to complete on a heavily loaded host.
TCS-1595Cold deploy of the same application, without undeploying the previous version, is failing.
TCS-1597In HQ, attempting to create Connectors/Hosts for a service whose name includes a backslash (\) leads to a blank screen.
TCS-1598Instances created with the nio-ssl template fail to start on the IBM JVM with a java.security.NoSuchAlgorithmException: SunX509 exception. This is fixed in Tomcat 6.0.30.A.
TCS-1616Restarting an instance using a symlink to the directory where the instance was created fails.
TCS-1638A java.lang.NullPointerException occurs when attempting to use HQ to cold deploy a war.
TCS-1651The tcsadmin command does not check that the file being deployed ends with .war, which is inconsistent with the UI.
TCS-1652JMX connections between agent and a tc Server instance are leaked during application management resulting in connection timeouts and, ultimately, application management stopping working altogether.
TCS-1674On a local machine, HQ GUI is not displaying an error message when trying to cold deploy a war that has already been deployed.
TCS-1675On a server machine, HQ GUI is not displaying an error message when trying to cold deploy a war that has already been deployed.
TCS-1677Clear-text database passwords are visible in VisualVM via the tomcat.jdbc.ConnectionPool.<poolName> MBean. Although viewing the Password attribute via VisualVM appropriately displays the message "Password not available as DataSource/JMX operation", the "DbProperties" attribute shows a list of database properties including the database password in clear-text.
TCS-1698It is possible to start an instance with a slash (/) at the beginning of the instance name, but it causes problems later attempting to restart using HQ. .
TCS-1741The HQ GUI displays "Unable to make a JMX connection" when trying to cold deploy from the local machine.
TCS-1767The JMX authenticator accepts an encoded password in addition to the clear password. The authenticator should require a clear password. For more on this fixed vulnerability, see CVE-2011-0527 at the SpringSource Security Team Web site.
TCS-1768A JDBC Pool's size can become corrupted (and reported as negative) when evictions are enabled leading to maxActive connections being exceeded.
TCS-1802Unable to restart server after changing the JMX configuration from the HQ GUI.

Table 4.3. Issues Fixed in 2.0.5

Issue IDDescription
TCS-152Whitespace between the list of jdbcInterceptors in the server.xml of a tc Runtime instance results in ClassNotFoundExceptions. This attribute of the server.xml file should be more tolerant of white space.
TCS-500Error returned when running the list-servers command of the tcsadmin command-line interface together with the --platformname option. The error indicates that you must specifiy a server id or name, even though it is perfectly valid to specify only --platformname.
TCS-606When using the Hyperic user interface to manage a tc Runtime instance, and you repeatedly make changes to the Server Configuration page, then save and push the changes and restart the tc Runtime instance, the Server Configuration Web page keeps getting larger and larger rather than scaling back to an appropriate size.
TCS-608When using the Hyperic user interface to create a new Tomcat High Concurrency Data Source, the password field is pre-poulated without the user having entered anything. Although this does not actually cause any harm, it is confusing to the user.
TCS-615When using the Hyperic user interface to enable security/SSL for a tc Runtime instance, the UI does not currently force you to also enter the keystore files at the same time. This means that you will subsequently get an error when you navigate to the Application Management tab due to security being enabled but the keystore files are missing. The UI should force you to enter a keystore file at the same time you enable security.
TCS-616The error message you get in the catalina.log file when you have enabled security/SSL for the tc Runtime instance but not provided a keystore file is not very helpful. The exception is java.io.FileNotFoundException, but it doesn't indicate which file (i.e. the full pathname of the keystore file) is not being found.
TCS-617When using the Hyperic user interface to create a new Service for a tc Runtime instance, and you provide a Service name that contains a backslash, the creation appears to work, but if you try to view the new Service using the UI you get a blank screen instead of the Service details.
TCS-622The tcruntime-ctl.sh script is incorrectly interpreting the -n option as a command to stop the instance, rather than the option to specify an alternate instance directory.
TCS-674When an event happens which triggers request-related notifications, in certain situations the stuck-request diagnostic fires before the request actually completes, and the slow-request diagnostic never fires. This means that the administrator may not receive the information they need to correctly diagnose and fix the problem.
TCS-676When using the Hyperic user interface to restart a tc Runtime instance, the warning message returned if the user has only view and modify permissions (but not control permission) is not very helpful and should be improved so the user really knows what the problem is.
TCS-678When the primary server in a cluster is down, the MemberDisappeared verification error occurs twice in the log files.
TCS-740While running session replication under load for a long period of time, the server logs contain some java.lang.NullPointerException after the error SEVERE org.apache.catalina.ha.tcp.ReplicationValve.sendReplicationMessage Unable to perform replication request.
TCS-749When using the Hyperic user interface, if you try to start an already-running application, the UI does not return an error but the status message about the application in the Application Management tab is empty, resulting in potential confusion to the user about what just happened.
TCS-811The Hyperic user interface does not allow you to configure an APRLifecycleListener for a tc Runtime instance.
TCS-834The error message returned when you use the list-applications command of the tcsadmin command-line interface, but specify a non-existent group, is unhelpful and does not describe what the actual problem is.
TCS-835The error message returned when you use the list-applications command of the tcsadmin command-line interface, but specify a mixed group (not allowed) or a group of non-tc Runtime instances (also not allowed), is unhelpful and confusing and does not describe what the actual problem is.
TCS-943By default, the ROOT application is the only one listed in the Application Management view of the Hyperic user interface when you first create a tc Runtime instance and you have not yet deployed a user application. However, if you use the UI to cold-deploy a user application, the ROOT application silently disappears from the list of applications. If you then undeploy the user application, the ROOT application returns. This is incorrect: the ROOT application should always be listed unless you specifically undeploy it.
TCS-1098When using the Hyperic user interface to create an Oracle datasource, HQ uses the old deprecated JDBC driver (oracle.jdbc.driver.OracleDriver) rather than the correct one (oracle.jdbc.OracleDriver.)
TCS-1101If you use the Hyperic user interface to create a datasource that uses the Tomcat connection pool, then try to start the tc Runtime instance, you get the following error: java.sql.SQLException: READ_COMMITTED and SERIALIZABLE are the only valid transaction levels.
TCS-1169If you use the Hyperic user interface to create a datasource and you specify a name for the datasource that contains backslashes, the UI changes them to forward slashes when it writes the configuration to the server.xml file.
TCS-1321When using the Hyperic user interface to cold-deploy an application, you might occasionally get the error Application yourapp.war failed to deploy in the UI, even though the deployment might have been successful.
TCS-1323When using the Hyperic user interface to create a new tc Runtime Service, and you specify a backslash in the name, the UI converts it into a forward slash when it writes the new configuration to the server.xml file.
TCS-1396The HQ Server returns a NullPointerException when it attempts to validate the server.xml file of a tc Runtime instance which contains two Connectors with ports specified by properties that the HQ Server is unable to resolve due to the way it starts the tc Runtime instance. The HQ server determines that the Connectors have clashing port numbers, when in fact they do not.
TCS-1399If one user uses the Hyperic user interface to shut down a tc Runtime instance, and immediately after another user from a different browser window uses the Hyperic UI to attempt to cold-deploy a Web application to the same tc Runtime instance (which is in the process of being shut down), the second user receives an empty screen rather than a message that the instance is being shut down.
TCS-1408When upgrading a tc Runtime instance from version 6.0.20.A/B to 2.0.x using the tcruntime-instance.sh|bat script with the -m option, the script adds the incorrect tc-runtime-threaddumpwrapper.jar to the CLASSPATH rather than the correct threaddumpwrapper.jar,
TCS-1430When using the Hyperic user interface to manage a tc Runtime instance, and you change the name of the default localhost Host to something else, and then click on the Application Management view, the UI returns an error because it incorrectly assumes that there is always a localhost Host available.
TCS-1437When attempting to use the Hyperic user interface to cold-deploy a Web application to a group of tc Runtime instances, you get a grey screen and the following exception in the log file: java.lang.IllegalArgumentException: Cannot perform single action on a group.
TCS-1440When using the Hyperic user interface to manage a tc Runtime instance, the host name restrictions are not enforced. The restrictions on host names is that they can be comprised of only letters, numbers, and the symbol -, and they must be case insensitive. The user interface is not currently enforcing these restrictions.
TCS-1455tc Runtime instances created using 6.0.19.A do not define ARCH in wrapper.conf, however when using -m of tcruntime-instance in a 2.0.x installation to upgrade the instance, the script adds classpath entries that reference %ARCH%, causing errors on instance startup.
TCS-1458The tcruntime-ctl.sh script uses the name of an instance from its symlinked directory rather than its absolute directory name, causing problems when attempting to control the instance with the script.
TCS-1493When you cold deploy a Web application using the Hyperic user interface and you provide a context that is different from the name of the Web application, the UI ignores this context and instead deploys the Web application using the name of the WAR file as the context (which is the default behavior if you do not provide a context.)
TCS-1523The error message you get when you attempt to add a duplicate tc Runtime instance to a Hyperic group using the tcsadmin command-line interface is confusing and does not provide information about the real problem. The confusing error returned by tcsadmin in this case is: Could not execute JDBC batch update>
TCS-1524If you attempt to configure the JVM_OPTS variable (using either the tcsadmin command-line interface or the Hyperic user interface) when the existing setenv.sh does not contain the CATALINA_OPTS variable, then the end result is that the JVM_OPTS variable is removed from the setenv.sh script.
TCS-1525Error returned when you attempt to use the put-file command of the tcsadmin command-line interface together with the --servername option.
TCS-1526The error you get when you try to use the tcsadmin command-line interface to control, add a server to, or remove a server from a non-existent group is not helpful and does not describe the actual problem.
TCS-1527If you use the tcsadmin command-line interface to deploy an application, and the deployment fails for some reason, the resulting error message is not helpful and does not describe the actual problem.
TCS-1538If you use the set-jvm-options or list-jvm-options command of the tcsadmin command-line interface but specify an invalid --serverid value, the resulting error message is not helpful and does not describe the actual problem.
TCS-1539If you use the put-file or get-file command of the tcsadmin command-line interface but specify an invalid --serverid value, the resulting error message is not helpful and does not describe the actual problem.
TCS-1540If you use the put-file command of the tcsadmin command-line interface but specify an invalid --groupid value, the resulting error message is not helpful and does not describe the actual problem.
TCS-1541Attempting to use the set-jvm-options --servername command/option of the tcsadmin command-line interface returns an error because the CLI thinks the servername does not exist when in fact it does.
TCS-1555The error message returned when you attempt to use the tcsadmin command-line interface to delete a group that doesn't exist is incorrect. It includes a confusing and incorrect double-negative (Can't delete group bogusname because it doesn't not exist).
TCS-1556The error message returned when you use the list-applications command of the tcsadmin command-line interface together with an invalid --serverid value is unhelpful and does not describe the actual problem.
TCS-1564When you use the tcsadmin command-line interface with any of the commands to list/deploy/stop/start/reload/undeploy an application but you also specify an invalid --groupname value, the error message is unhelpful and does not describe the actual problem.
TCS-1565If you attempt to use the modify-server command of the tcsadmin command-line interface to rename a tc Runtime instance, but you specify an invalid --serverid, the resulting error message is unhelpful and does not describe the actual problem .
TCS-1566The error message when running the revert-to-previous-configuration command of the tcsadmin CLI but specifying an invalid server is badly written and confusing.

Table 4.4. Issues Fixed in 2.0.4

Issue IDDescription
TCS-164Specifying instance name when invoking tcruntime-ctl.bat|sh from the bin directory causes failure and displays incorrect usage information.
TCS-184Differences in session counts depending upon the replication manager that has been configured.
TCS-342Using the Quick Control to restart a tc Runtime instance does not pass the control arguments.
TCS-499tcruntime-instance.sh script fail if space in pwd.
TCS-501Unhelpful error message when attempting to list tc Runtime instances in a group that does not exist.
TCS-502Unhelpful error message when attempting to delete a group which does not exist.
TCS-503Unhelpful error message when listing applications in a group to which no applications have been deployed.
TCS-609Hidden required field stops new data source from being saved without indication of a problem.
TCS-614Read-only or read-write nature of input fields in tomcatserverconfig Web application doesn't always reflect the logged in user's permissions.
TCS-671Exception in TomcatserverconfigController.groovy.
TCS-675"Internal Server Error" when trying to restart tc Runtime instance after server configuration change.
TCS-747Enabling and Disabling garbage collection logging corrupts tc Runtime instance configuration.
TCS-753Blank screen when trying to view the created jdbc datasource whose name has a backward slash(\).
TCS-937Restarting tc Runtime instance as part of enable garbage collection takes zero time and does not show as an HQ event.

Table 4.5. Issues Fixed in 2.0.3

Issue IDDescription
TCS-106JMX Beans are not detected with auto discovery or deployment through HQ user interface.
TCS-117Preconfigured GC alert depends on GC metric which is not turned on by default.
TCS-121Default connector configuration has risk of connection exhaustion.
TCS-123Unable to view SpringSource tc Runtime 6.0 Spring Repository Method charts on the monitor tab with tc server 2.0 with Instrumented Jars based application.
TCS-145Cluster replication does not recover after a failure.
TCS-146Cluster log messages not shown correctly.
TCS-151On Windows, an instance with a pinned version does not report its Runtime version correctly.
TCS-158The tcruntime-instance help output always displays versions from the current working directory, irrespective of the installation directory supplied with the -d option.
TCS-161The tcruntime-instance usage message states that the default for -d is the current working directory, however the implementation uses the directory that contains the script.
TCS-173Inconsistent defaults for the -d and -n options between tcruntime-ctl and tcruntime-instance scripts.
TCS-174Usage message for tcruntime-ctl.bat does not describe the -d and -n options.
TCS-175Typo in outputted message when restarting an instance on Windows using tcruntime-ctl.bat.
TCS-179Inconsistent resolution of symbolic links when starting a tc Runtime instance: starting on the command line leaves the links in place, starting in the HQ UI resolves them, or in other words, the paths are made canonical.
TCS-182Enabling request diagnostics disables JMX registration of jdbc-pool.
TCS-185After logging out of the HQ UI, the tc Server configuration UI, if accessed directly, is still available, and configuration changes can be made.
TCS-204Incorrect reference to "tc Server 6.0" in HQ UI.
TCS-206Timeout of the tc Server HQ plugin differs from that of base HQ UI.
TCS-207tc Server HQ plugin: The Application management portal has broken images.
TCS-210The HQ UI sometimes times out when you use it to restart a tc Runtime instance after making a server configuration change.
TCS-216Timeout period for restarting the tc Runtime instance following the push of a configuration change does not honor the configured control action timeout period.
TCS-260Configuration changes made to "Server Defaults: jsp" are not showing up in the HQ user interface after reloading settings from tc Rumtime.
TCS-263The tcruntime-ctl.bat script fails if a you specify a relative path using the -n option.
TCS-267Unable to start the tc Runtime instance after migrating it from 6.0.20.C to 6.0.26.C.CI-398.
TCS-272Server Configuration page in the HQ user interface says that a tc Runtime instance was restarted when it actually wasn't.
TCS-274Running the tcruntime-instance.bat script on Windows returns an error due to incorrect line endings in the file.
TCS-275tc Runtime doesn't show up in HQ auto-discovery.
TCS-310Unlike tcruntime-ctl.sh, tcruntime-ctl.bat does not support the timeout parameter for stop and restart.
TCS-312Using the -d or -n options when attempting to install a tc Runtime instance as a service on Windows fails because tcruntime-ctl.bat incorrectly interprets -d or -n as the name of the account which is to run the service.
TCS-315The refresh button in session timeout of the HQ user interface is not working.
TCS-339The TomcatserverconfigController.restartServer method's timeout is separate from the actual restart operation's timeout.
TCS-340Passing a timeout value to the tcruntime-ctl.sh script for a restart is ignored.
TCS-412Access log is switching suffix with prefix in the tc Server configuration.
TCS-424Fix CVE-2010-2227.
TCS-488Obfuscating a database password in the application context file does not work correctly.
TCS-492Using the HQ user interface, you are unable to view a tc Server Service that has a space in the name.
TCS-494Unable to undeploy the ROOT application from HQ UI.
TCS-495Internal Server Error when trying to restart tc Runtime instance after a server configuration change when logged in as a user who has full permissions but is not the HQ admin user.
TCS-607Internal Server Error when trying to restart an upgraded tc Runtime instance after server configuration change.

Table 4.6. Issues Fixed in 2.0.2

Issue IDDescription
TCS-153Regression: Modifications to an existing JDBC Data Source cannot be saved.
TCS-183Controllers in server config webapp are vulnerable to DataBinding-based attack that can lead to arbitrary code execution in the JVM that's hosting the application.
TCS-424Fix CVE-2010-2227

Table 4.7. Issues Fixed in 2.0.1

Issue IDDescription
TCS-27Running tcserver-instance.sh|.bat --force succeeds even if the tc Runtime instance is running (as detected by running tcserver-ctl.sh|.bat status).
TCS-29The restart option is missing on Windows from the list of available options displayed when invoking tcserver-ctl.bat --help.
TCS-37The error message that is displayed if application deployment using the HQ user interface runs out of space is unhelpful.
TCS-41Ordering of JDBC DataSources in the HQ user interface is neither consistent nor predictable.
TCS-44Further regressions in JSP/EL processing in Tomcat 6.0.25.
TCS-46Contrary to its help message, tcruntime-instance.sh does not use the current working directory as the default value of the --instance-dir option.
TCS-51Repeated modifications to tc Runtime instance configuration using the Hyperic user interface eventually overwrites wrapper.app.parameter.1 in the wrapper.conf file, which in turn prevents the instance from starting.
TCS-56The add-server CLI command does not accept group id, only group name, which is inconsistent with other commands.
TCS-57Using the CLI command put-file on Windows to administer a mixed OS group (Windows and Linux) breaks the Linux nodes as the back slashes used by Windows are not interpreted as directory delimiters.
TCS-58The Hyperic user interface generates invalid Connector/SSL configuration in the server.xml file.
TCS-60Exception in thread "main" java.lang.ExceptionInInitializerError when creating tc Runtime instance using java version "1.5.0" gij (GNU libgcj) version 4.3.2.
TCS-61When using the Hyperic user interface and you stop and undeploy an application which results in an error, there is no way to proceed to fix the error using the UI.
TCS-71An error message is displayed on the Hyperic UI dashboard when an agent is running with a non-Sun JRE.
TCS-72Starting an application across a group reports a failure if the application was already started on one or more runtime instances in the group
TCS-76Use of environment variables versus command line switches between tcruntime-ctl and tcruntime-instance is confusing.
TCS-79Upgrade using the tcruntime-instance script shows ... patching old wrapper.conf (please verify) ...
TCS-80The catalina.home configuration property in the Hyperic user interface points to the old Tomcat binary after upgrading from 6.0.20.C-->6.0.25.A.
TCS-81Instance migration (upgrade) using the -m option behaves differently from the base tcruntime-instance script with regards to the creation of the tomcat.version file.
TCS-82A tc Runtime instance with a relative path for the install base (for example, one created with -d .) causes endless looping on status and startup.
TCS-84Password is shown in plain text in the HQ user interface when creating a new JDBC datasource.
TCS-107When the HQ Agent is in unidirectional mode, you are unable to deploy WAR files.
TCS-110Implement fix for CVE-2010-1157 vulnerability.
TCS-122The tc Runtime is missing tomcat-dbcp.jar
TCS-130JMX login succeeds if client knows to send null credentials.
TCS-135Using the HQ user interface, clicking Views --> Server Configuration --> Push changes incorrectly leads to "Unsaved Changes" dialog box.
TCS-148The README file in the HQ plugin distribution makes reference to 2.0.0, which is not the current version.

5. What Are the Main Steps Required to Get Going?

This chapter provides a roadmap to the high-level steps you perform to get tc Server up and running. Each step points to a more targeted procedure in this guide, such as installing tc Server, starting up the components, and using the HQ user interface to configure and manage a tc Runtime instance or group.

5.1 Before You Begin

You install tc Server by installing its components: the tc Runtime and the management components (HQ Server and Agent.) If you are installing only the Developer Edition of tc Server, you install only the tc Runtime. If you are installing the managed node version of the Standard Edition, you install both the tc Runtime and the HQ Agent together, as well as the HQ Server. See tc Server Editions for details about the available editions. Each edition comes in ZIP and compressed TAR formats.

When installing both the runtime and management components, you can install all components on the same computer or on multiple computers. Typically, you install a single HQ Server, and then install the tc Runtime and HQ Agent on one or more computers. You then create one or more tc Runtime instances.

[Note]Note

It is assumed in this section that you are installing tc Server for the first time. If you have already installed a previous version of tc Server, created one or more tc Runtime instances, and now want to upgrade all the components to the latest version, see Upgrade and Migration Guide.

[Note]Note

It is also assumed in most of this documentation that you will use the SpringSource layout for tc Runtime instances, rather than the standard Apache Tomcat (ASF) layout. The SpringSource layout offers many benefits over the standard ASF layout, although you can of course use the latter. For clarity, all ASF layout-specific documentation is grouped into a single appendix, Using the ASF Layout. Unless otherwise specified, the rest of the documentation assumes the SpringSource layout.

5.2 Installing tc Server and Creating a New tc Runtime Instance

In sum, this high-level installation step includes the following sub-steps:

  1. Install the tc Runtime on one or more computers. You perform this step for all editions of tc Server: Developer, Standard, and Spring. If you are installing the managed node version of the Standard Edition, then the installation automatically includes the HQ Agent.

    See Installing tc Server: Main Steps.

  2. Install the HQ Server once.

    See Installing Standard Edition (Managed Node) .

  3. Create a new tc Runtime instance on the computers on which you installed the tc Runtime.

    See Creating a New tc Runtime Instance.

5.3 Starting the Components and Doing Initial Configuration

After you install tc Server, you start the components. Depending on how you have configured tc Server, you perform the following sub-steps on the computers on which you have installed the particular components.

  1. Start the tc Runtime instance(s) on each computer on which you installed the tc Runtime.

    See Starting and Stopping tc Runtime Instances.

  2. Start the HQ Server on the computer on which you installed it.

    See Starting and Stopping the HQ Server and Agents.

  3. Start the HQ Agent on all computers on which you installed it. Typically these are the same as the computers on which you installed the tc Runtime.

    See Starting and Stopping the HQ Server and Agents.

  4. Invoke the HQ user interface in your browser, log in, and be sure it is configured for you to start managing tc Runtime instances.

    See Getting Started with the HQ User Interface.

5.4 Exploring the Features of tc Server

After you start all components of tc Server, log into the HQ user interface, and add the tc Runtime instances to the inventory, you are now ready to explore the features of tc Server.

  1. Run through the HQ tutorial which describes typical tasks you perform on tc Runtime instances, such as deploying applications, configuring servers, and creating and using HQ groups.

    See Tutorial: Using HQ to Configure and Manage tc Runtime Instances.

  2. If you are completely new to programming Web applications, and want to learn how to create a very simple one, run through the Simple Web Application tutorial.

    See Tutorial: Very Simple Web Application Development.

  3. If you installed the Developer Edition of tc Server, try out Spring Insight, which gives you real-time visibility into the behavior and performance of your existing user applications. See Using Spring Insight.

    Using the Spring Insight Development Kit, you can create your own Spring Insight plug-ins that are tailored to the specific needs of your applications. See Using Spring Insight.

  4. If you want to deploy existing Web applications without using the HQ user interface, you can use static deployment.

    See Deploying Applications to a tc Runtime Instance for details.

  5. Learn about more advanced administration tasks, such as creating and using tc Runtime clusters and using the tc Server command-line interface by reading the tc Server Administration Guide

6. Installing tc Server

This chapter describes how to install the various editions of tc Server.

6.1 Before You Begin: System Requirements

This section includes topics that discuss tc Server software requirements, such as the required Java Development Kit (JDK) or Java Runtime Environment (JRE) and database server. Read this section before you begin the tc Server installation.

For HQ Server and Agent requirements, see Installation Requirements on the Hyperic documentation Web site.

Required Software: JDK or JRE

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.

Possibly Required Software: Database Server

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.

Installing on Unix Platforms: Important Note

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.

6.2 Installing tc Server: Main Steps

This section describes how to install tc Server. It is divided into sub-sections, depending on the edition of tc Server you are going to install and the way it is packaged. Be sure to read tc Server Editions for information about each edition, what they contain, and the names of the *.zip or *.tar.gz files into which each edition is packaged.

The procedures cover both Unix and Windows installation. Most of the instructions, however, are for Unix. If you are installing on Windows, change the forward slashes (/) to back slashes (\); other differences in the installation are called out.

[Note]Note

It is assumed that you are installing tc Server for the first time. If you have already installed a previous version of tc Server, have created one or more tc Runtime instances, and now want to upgrade all the components to the latest version, see Upgrade and Migration Guide. The upgrade guide also describes how to upgrade an existing HQ installation so that it can manage tc Runtime instances.

Installing Developer Edition

  1. Download and install a JDK or JRE, if you do not already have one installed on your computer. See Before you Begin: System Requirements.

  2. Download the tc Server Developer Edition distribution from the SpringSource Download Center.

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

    • springsource-tc-server-developer-2.0.X.RELEASE.zip
    • springsource-tc-server-developer-2.0.X.RELEASE.tar.gz
  3. Open a terminal (Unix) or command window (Windows) and create the main tc Server installation directory, such as /home/tcserver. For example, on Unix:

    prompt$ mkdir /home/tcserver
  4. Unzip or untar the tc Server distribution file into the new directory.

    This creates a directory called springsource-tc-server-developer in the main tc Server installation directory that contains the tc Runtime utility scripts, the templates directory, the tomcat-version directory, and so on.

    See Overview of tc Server Directories, Variables, and Configuration Files for details.

    This directory also contains a prepackaged tc Runtime instance called spring-insight-instance that contains the Spring Insight feature.

  5. Start the prepackaged tc Runtime instance. The exact steps depend on your platform (Unix or Windows.)

    Unix: Change to the /home/tcserver/springsource-tc-server-developer directory and execute the tcruntime-ctl.sh script to start the instance. For example:

    prompt$ cd /home/tcserver/springsource-tc-server-developer
    prompt$ ./tcruntime-ctl.sh spring-insight-instance start

    Windows: Change to the c:\home\tcserver\springsource-tc-server-developer directory and execute the tcruntime-ctl.bat script to first install the tc Runtime instance as a Windows service and then start it:

    prompt> cd c:\home\tcserver\springsource-tc-server-developer
    prompt> tcruntime-ctl.bat spring-insight-instance install
    prompt> tcruntime-ctl.bat spring-insight-instance start

    Subsequently, Springsource recommends that you start and stop the tc Runtime instance by using the Windows Services console. The tc Runtime instance is displayed in the console with the name SpringSource tc Runtime - unique-name, where unique-name is a unique combination of server name and server directory.

  6. After the tc Runtime instance starts, invoke Spring Insight in your browser:

    http://host:8080/insight

    where host refers to the computer on which it is running; if this is the same computer as the browser, you can use localhost:

    http://localhost:8080/insight

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.

Installing Standard Edition (Runtime Package)

  1. Download and install a JDK or JRE, if you do not already have one installed on your computer. See Before you Begin: System Requirements.

  2. On the SpringSource Download Center page under tc Server, click the tc Server Standard Edition link and navigate to the download page.

  3. Download the Standard Edition Runtime package distribution.

    Choose the ZIP or the compressed TAR file distribution:

    • springsource-tc-server-standard-2.0.X.RELEASE.zip
    • springsource-tc-server-standard-2.0.X.RELEASE.tar.gz
  4. Open a terminal (Unix) or command window (Windows) and create the main tc Server installation directory, such as /home/tcserver. For example, on Unix:

    prompt$ mkdir /home/tcserver
  5. Unzip or untar the tc Server distribution file into the new directory.

    This creates a directory called springsource-tc-server-standard in the main tc Server installation directory that contains the tc Runtime utility scripts, the templates directory, the tomcat-version directory, and so on.

    See Overview of tc Server Directories, Variables, and Configuration Files for details.

See Next Steps for links to post-installation procedures.

Installing Standard Edition (Managed Node Package)

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:

  • Install all components on the same computer.

  • Install HQ Server on one computer and install the managed node (HQ Agent and tc Runtime) on one or more different computers.

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

  1. On the computer on which you are going to install the managed node (tc Runtime and HQ Agent), download and install a JDK or JRE, if you have not already done so. See Before You Begin: System Requirements.

  2. On the SpringSource Download Center page under tc Server, click the tc Server Standard Edition link and navigate to the download page.

  3. Download the tc Server Managed Node distribution.

    Choose the ZIP or compressed TAR file distribution:

    • springsource-tc-server-node-2.0.X.RELEASE.zip
    • springsource-tc-server-node-2.0.X.RELEASE.tar.gz
  4. Open a terminal (Unix) or command prompt (Windows) and create the main tc Server managed node installation directory, such as /home/tcserver. For example, on Unix:

    prompt$ mkdir /home/tcserver

    This directory will contain the managed node components (tc Runtime and HQ Agent).

  5. Unzip or untar the tc Server distribution file into the new directory.

    A directory called springsource-tc-server-node is created in the main tc Server installation directory that contains the tc Runtime utility scripts, the templates directory, the tomcat-version directory, and so on.

    See Overview of tc Server Directories, Variables, and Configuration Files for details.

    This directory also contains the HQ Agent that has been preconfigured with the tc Server HQ plug-in. The agent is contained in the hyperic-hq-agent-4.2.X.X-EE sub-directory (such as /home/tcserver/springsource-tc-server-node/hyperic-hq-agent-4.2.X.X-EE).

  6. On the computer on which you are going to install HQ Server, download and install a JDK or JRE, if you have not already done so. See Before you Begin: System Requirements.

  7. If you have not already done so, download and install a database server on the computer that will host HQ Server or on a remote computer that is accessible to the HQ Server host computer. See Before You Begin: System Requirements.

    Obtain the URL and username/password used to connect to your database server, because the installation program for HQ Server will ask for it.

  8. Open a terminal (Unix) or command prompt (Windows) and create the directory that will contain the HQ Server, such as /home/hyperic. For example, on Unix:

    prompt$ mkdir /home/hyperic

    If you are installing all components on the same computer, you can install the HQ Server into the same tc Server directory that you already created (/home/tcserver in our example.)

  9. From the same page that you downloaded the tc Server Managed Node distribution (step 2 and 3), download the HQ Server distribution. This version of HQ Server is platform-neutral and is preconfigured with the tc Server HQ plug-in.

    Choose the ZIP or compressed TAR file:

    • hyperic-hq-installer-noJRE-tc-server-2.0.X.RELEASE.zip
    • hyperic-hq-installer-noJRE-tc-server-2.0.X.RELEASE.tar.gz
  10. Unzip the HQ Server distribution into a temporary directory.

  11. From your terminal window or command prompt, change to this temporary directory and execute the setup.sh (Unix) or setup.bat (Windows) script. For example, on Unix:

    prompt$ cd /tmp/hyperic-hq-installer-noJRE-tc-server-2.0.X.RELEASE
    prompt$ ./setup.sh

    After accepting the terms of agreement, enter 1 to install just the HQ Server, because you installed the HQ Agent in a preceding step. The script asks a few more questions, such as information about your database and the directory into which you want to install the HQ Server (/home/hyperic or /home/tcserver in our example.)

    When the setup.sh script completes, the HQ Server will be installed in the directory /home/hyperic/server-4.2.X.X-EE.

    See Installing the Agent and Server from a Tarball or Zip Archive for additional details about the questions asked by the setup.sh script.

See Next Steps for links to post-installation procedures.

Installing Spring Edition

  1. On the SpringSource Download Center page under tc Server, click the tc Server Spring Edition link and navigate to the download page. You will see downloads for the tc Server Standard Edition Managed Node, HQ Server, and the Instrumented Spring JARs.

  2. Follow the instructions in Installing Standard Edition (Managed Node Package) to download and install the tc Server managed node and HQ Server.

  3. Download the distributions of Spring Framework, Spring Web Flow, Spring Security, and Spring Web Services that have been specifically instrumented for management with Hyperic HQ.

  4. See Spring Instrumentation Documentation for information about using these instrumented JARs with your Spring application.

Next Steps

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.

6.3 Overview of tc Server Directories, Variables, and Configuration Files

This section provides basic reference information about the tc Server installation directories and the most important configuration files.

When you install the tc Runtime component, you simply unpack the appropriate *.zip or *.tar.gz file into the main installation directory. This creates a springsource-tc-server-edition subdirectory, where edition refers to the edition of tc Server you are using: node (Standard Edition, Managed Node package), standard (Standard Edition, Runtime package), or developer (Developer Edition). Spring Edition users will have a node subdirectory. This subdirectory in turn contains all tc Server-related files and directories. In particular:

  • tomcat-version. Where version is the version of the core Apache Tomcat on which this version of the tc Runtime is based, such as tomcat-6.0.25.A-RELEASE : This is the basic Apache Tomcat CATALINA_HOME directory; users of standard Apache Tomcat will recognize its contents. The Tomcat binaries are in the bin directory, the server configuration files for the default Tomcat server instance are in the conf directory, and so on.

  • templates. Out-of-the-box templates for creating customized tc Runtime instances, such as cluster-node enabled or SSL-ready. You optionally specify one of these templates when you run the tcruntime-instance.sh|bat script to create a new tc Runtime instance.

  • tijars. JAR files used by tc Runtime that are different to standard Apache Tomcat.

  • tcruntime-instance.sh|bat. Scripts for creating new tc Runtime instances when you use the SpringSource directory layout.

    When you create a new tc Runtime instance with this script, the script creates (by default) a subdirectory of the springsource-tc-server-edition directory with the same name as the new tc Runtime instance; this new directory is the CATALINA_BASE of the tc Runtime instance. The new directory contains the instance-specific configuration files, its own Web application deployment directory, log files, and so on.

  • tcruntime-ctl.sh|bat. Scripts for controlling tc Runtime instances, such as starting or stopping them. The bin directories of individual tc Runtime instances include their own versions of these scripts that in turn call these main ones. You can also call the top-level scripts if you specify the name of the tc Runtime instance.

  • hyperic-hq-agent-version (Managed Node only). Where version is the version of the HQ Agent, such as 4.2.X.X-EE. This directory contains the HQ Agent files and binaries. The agent is preconfigured with the tc Server HQ plug-in.

tc Server Variables

The following tc Server variables are used:

  • CATALINA_HOME. Root directory of your tc Runtime installation.

    The CATALINA_HOME variable points to the directory INSTALL_DIR/springsource-tc-server-edition/tomcat-version, where INSTALL_DIR is the directory in which you installed tc Server (such as /home/tcserver), edition refers to the edition of tc Server you are using (one of node, developer, or standard), and version is the version of the core Tomcat, such as 6.0.25.A-RELEASE.

  • CATALINA_BASE. Root directory of a particular tc Runtime instance.

    This directory contains the instance-specific files, such as the conf/server.xml file that configures this particular instance. If you created a tc Runtime instance called myserver and you are using the Standard Edition (managed node), then the CATALINA_BASE of the instance is INSTALL_DIR/springsource-tc-server-node/myserver by default.

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:

  • CATALINA_OUT. Unix only. Use this environment variable to specify a file to which a tc Runtime instance writes stdout and stderr messages. If you do not explicitly set this environment variable, then the tc Runtime instance writes stdout and stderr messages to the file CATALINA_BASE/logs/catalina.out.

    For example, to specify that all the tc Runtime instance write its stdout and stderr messages to /home/tcserver/tomcat-instance-6.log, set the variable in your environment or setenv.sh as follows:

    CATALINA_OUT=/home/tcserver/tomcat-instance-6.log
  • INSTANCE_NAME. Name of the tc Runtime instance. You can use this variable to create other unique variables within configuration scripts.

    For example, on Unix platforms you can update the bin/setenv.sh file to use the name of the tc Runtime instance when defining the CATALINA_OPTS variable as follows:

    CATALINA_OPTS="-Dinstance.name=$INSTANCE_NAME"

    On Windows, the equivalent change would be to the conf/wrapper.conf file as follows:

    set CATALINA_OPTS=-Dinstance.name=%INSTANCE_NAME%
  • INSTANCE_BASE. Specifies the parent directory of the tc Runtime instance. The full pathname of the tc Runtime instance directory would be $INSTANCE_BASE/$INSTANCE_NAME.

    You can use the INSTANCE_BASE variable in the same way as the INSTANCE_NAME variable, as described in the preceding bullet.

tc Runtime Instance Directory Structure

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

  • bin. Contains the tcruntime-ctl.* scripts to start and stop tc Runtime instances, as well as the setenv.* scripts. The *.sh Unix files are functional duplicates of the *.bat Windows files.

  • conf. Contains the configuration files for the tc Runtime instance, such as server.xml, catalina.properties, web.xml, context.xml, and so on.

  • lib. Contains resources shared by all Web applications deployed to the tc Runtime instance.

  • logs. Location of the logs files.

  • webapps. Deployment directory for the Web applications deployed to the tc Runtime instance.

  • work. Temporary work directory for all deployed Web applications.

  • temp. Directory used by the JVM for temporary files.

tc Runtime Instance Configuration Files

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:

  • server.xml. Main configuration file for a tc Runtime instance. It configures the behavior of the servlet/JSP container.

    By default, the server.xml file for a tc Runtime instance uses variable substitution for configuration properties that must be unique across multiple tc Runtime instances on the computer, such as HTTP and JMX port numbers. These variables take the form ${var}. For example, the variable for the HTTP port that the tc Runtime instance listens to is ${http.port}. The specific values for these variables for a particular tc Runtime instance are stored in the catalina.properties file, in the same directory as the server.xml file.

  • catalina.properties. Properties file that contains the tc Runtime instance-specific values for variables in the server.xml file.

  • context.xml. Configures the context that is loaded by all Web applications deployed to the tc Runtime instance.

  • web.xml. Default web.xml file that is loaded by all deployed Web applications, in addition to their individual web.xml files.

  • wrapper.conf. Windows only. Configures the Java Service Wrapper from Tanuki Software used to install the tc Runtime instance as a Windows service. The Wrapper correctly handles user log outs under Windows, service dependencies, and the ability to run services that interact with the desktop.

  • jmxremote.access and jmxremote.password. Configures the JMX users and passwords.

  • logging.properties. Configures the logging system of the tc Runtime instance.

7. Post-Installation Tasks

After you install the components of tc Server on all relevant computers, you perform some or all of the following post-installation tasks, depending on the edition of tc Server: Start and run the HQ Server and agents; create and start tc Runtime instances; deploy Web applications to an instance; or invoke and use the HQ user interface to monitor and configure tc Runtime instances. (As a performance-monitoring alternative to HQ, you can install and configure Spring Insight. See Using Spring Insight.)

Your first post-installation task depends on the layout of tc Server you want to use for your tc Runtime instances, whether SpringSource or Apache Software Foundation (ASF).

  • If you want to use the SpringSource layout (recommended), you first create a tc Runtime instance, because one is not installed for you by default in the Standard Edition. The Developer Edition of tc Server includes a default tc Runtime instance preconfigured with Spring Insight. For details, see Creating a New tc Runtime Instance.

  • If you want to use the ASF layout for your tc Runtime instances, you can immediately start the default instance that is provided, deploy applications, and manage it with HQ, if you have installed HQ.

[Note]Note

It is assumed in most of this documentation that you are going to use the SpringSource layout for tc Runtime instances, rather than the ASF layout. The SpringSource layout offers many benefits over the standard ASF layout, although you can of course use the latter. For clarity, all ASF layout-specific documentation has been grouped into a single section; see Using the ASF Layout. Unless otherwise specified, the rest of the documentation assumes the SpringSource layout.

7.1 Creating a New tc Runtime Instance

The following sections describe how to create new instances of tc Runtime and provide related information:

The procedural topics cover both Unix and Windows commands. The documentation uses Unix-like forward slashes (/) for directories; if you are on a Windows platform, change these to back slashes (\).

Creating tc Runtime Instances: Typical Steps

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

  1. Open a terminal window (Unix) or command prompt (Windows).

  2. Change to the INSTALL_DIR/springsource-tc-server-edition directory, where INSTALL_DIR refers to the main tc Server installation directory, such as /home/tcserver and edition refers to the edition of tc Server you are using (either node, developer, or standard.) For example:

    prompt$ cd /home/tcserver/springsource-tc-server-node
    [Note]Note

    This step is not required, because you can run the tcruntime-instance.sh|bat script from any location. The documentation provides this step for clarity about where the scripts live.

  3. Run the tcruntime-instance.sh (Unix) or tcruntime-instance.bat (Windows) script, passing it the required -s serverName parameter. Replace serverName with the name of your new tc Runtime instance. The -s option is the only required one. See Best Practice: Naming tc Runtime Instances for tips on naming an instance.

    For example, on Unix:

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

    On Windows:

    prompt> tcruntime-instance.bat -s myserver 

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:

  • HTTP listen port: 8080

  • JMX port: 6969

  • AJP port: 8009

  • Shutdown port: -1

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.

tcruntime-instance.sh Reference

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

Table 7.1. Options of the tcruntime-instance Command Script

Option (Single Dash)Option (Double Dash)DescriptionRequired?
-c --create Creates a new tc Runtime instance.

This is the default mode of the script.

No.
-d tcRuntimeDir --tcruntimedir tcRuntimeDir Replaces tcRuntimeDir with the full pathname of the tc Server installation. Use this parameter if you are running the tcruntime-instance.sh script from a location other than its default home directory. The default value of this parameter is the tc Server installation directory, such as /home/tcserver/springsource-tc-server-node.Only required if you are not running the tcruntime-instance.sh from its default location: INSTALL_DIR/springsource-tc-server-edition, where edition refers to the Edition of tc Server you are using (either node, developer, or standard.)
-f --force Forces the script to create a new tc Runtime instance, even if one already exists. By default the script does not force the creation.

If you specify this parameter and a tc Runtime instance with the name already exists, the script replaces only the existing bin and conf directories; the script does not replace the other directories, such as lib or temp. It is assumed in this case that you want to replace only the Tomcat-specific files (typically because you're updating the Tomcat version), but do not want to touch the user-specific files, such as Web applications.

No.
-h --help Outputs information about all the available options of tcruntime-instance.sh|bat.No.
-i --interactive Tells the script to interactively ask for port numbers; use this parameter if you want to change the default port numbers, as listed in Creating tc Runtime Instances: Typical Steps.

Warning: Be sure that all tc Runtime instances on the same computer have unique port numbers.

No.
-j

-j path_to_jdk

--javahome

--javahome path_to_jdk

If specified without a path_to_jdk value, hard-codes the JAVA_HOME variable in various files of the instance, using the global JAVA_HOME environment variable value. You can also use this option to specify a different location of the JDK. In this case, replace path_to_jdk with the full pathname of the JDK.

If you do not specify this option at all, then the instance uses the JAVA_HOME global environment variable, and does not hard-code the value anywhere.

The tcruntime-instance.sh script includes options for setting the path to a JDK (i.e. JAVA_HOME) and the path to a JRE (i.e. JRE_HOME). Typically, JAVA_HOME points to any valid location of a JVM or JRE, whereas JRE_HOME points only to a JRE. For most use cases, setting the JAVA_HOME variable with this option is adequate, and you do not need to set JRE_HOME with the -r option.

Only required if you have not set the JAVA_HOME variable in your environment to point to the JDK.
-l --list Lists all tc Runtime instances known to this particular tc Server installation.

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

No.
-m --modifyver Modifies the version of tc Runtime that an existing tc Runtime instance uses when the instance is pinned to a particular tc Runtime version.

Use this option together with the -s serverName option to specify the tc Runtime instance you want to modify and with the -v version option to specify the new version of the instance. If you specify -m without specifying -v, the resulting instance is unpinned. See Pinning tc Runtime Instances to a Version.

Note: Use this option only with an existing tc Runtime instance; you cannot use this option when creating a new instance. Also, it is assumed that you have already installed the tc Runtime version to which you want to modify the existing instance.

No.
-n instanceDir --instancedir instanceDir Replace instanceDir with the full or relative pathname of the directory in which you want the new tc Runtime instance to be created. If you specify a relative directory pathname, the directory is relative to the directory from which you are running the tcruntime-instance.sh|bat script.

The default value of this option is the tc Server installation directory, which means that if you do not specify this option, the tcruntime-instance.sh|bat script creates the new instances in the INSTALL_DIR/springsource-tc-server-edition directory, where edition refers to the Edition of tc Server you are using (node, developer, or standard.)

No.
-p --ports Colon-separated list of port numbers that should be configured in the catalina.properties file. Use this option if you do not want to use the default port numbers, as listed in Creating tc Runtime Instances: Typical Steps.

This is an all-or-nothing option: you either list all four port numbers, in the correct order, or you list none at all. The order of port numbers is as follows: shutdown, http, ajp, jmx. For example, assume the following value:

--ports=8888:9999:6627:8727

The script would create the following in the catalina.properties file:

  • shutdown.port=8888

  • http.port=9999

  • ajp.port=6627

  • jmx.port=8727

Separate the four port numbers with colons.

Warning: Be sure that all tc Runtime instances on the same computer have unique port numbers.

No.
-r

-r path_to_jre

--jrehome

--jrehome path_to_jre

If specified without a path_to_jre value, hard-codes the JRE_HOME variable in various files of the instance, using the global JRE_HOME environment variable value. You can also use this option to specify a different location of the Java runtime environment (JRE.) In this case, replace path_to_jre with the full pathname of the JRE.

If you do not specify this option at all, then the instance uses the JRE_HOME global environment variable, and does not hard-code the value anywhere.

The tcruntime-instance.sh script includes options for setting the path to a JDK (i.e. JAVA_HOME) and the path to a JRE (i.e. JRE_HOME). Typically, JAVA_HOME points to any valid location of a JVM or JRE, whereas JRE_HOME points only to a JRE. For most use cases, setting the JAVA_HOME variable by using the -j option is adequate and you do not need to set JRE_HOME with this option as well.

No.
-s serverName --server serverName Replaces serverName with the name of your new tc Runtime instance. See Best Practice: Naming tc Runtime Instances for tips on naming an instance.Yes.
-t template_location --template template_location Applies a template to a newly-created tc Runtime instance.

In this context, a tc Runtime template refers to a set of customized tc Runtime files that the tcruntime-instance script copies to the instance it just created. An instance of tc Runtime itself can act as a template. The template files are organized in the standard Tomcat hierarchy; for example, configuration files are in the conf directory and binary files are in the bin directory. When the tcruntime-instance script applies the template after it has created a new instance, it might replace standard Tomcat files, depending on the contents of the template. For example, the template might replace the standard server.xml file with a new one, or copy one or more applications to the webapps directory so that they are automatically deployed on startup.

Replace the template_location argument with one of the following values:

  • Name of an existing subdirectory of the INSTALL_DIR/springsource-tc-server-edition/templates directory, where edition refers to the Edition of tc Server you are using ( node, developer, or standard.)

  • Absolute path to a directory that contains a tc Runtime template, such as /home/templates/tcserver/mytemplate.

  • Absolute path to a directory that contains a tc Runtime instance, such as /home/tcserver/springsource-tc-server-developer/spring-insight-instance.

  • File that contains a list of absolute template directories. If you specify a file, the tcruntime-instance script applies the template files in the order listed, which means if each template includes a file with the same name, the one in the last template takes priority.

For additional details and examples about this using feature, and information about creating your own templates, see Creating a tc Runtime Instance with a Template and Creating tc Runtime Templates.

No.
-v version --tomcatver version Pins the instance to the specified version of tc Runtime, such as 6.0.25.A-RELEASE. See Pinning a tc Runtime Instance to a Specific Version for a discussion of pinning.

Valid values depend on the versions of tc Runtime that you have installed. The tcruntime-instance.sh script determines the list of available versions by searching for INSTALL_DIR/tomcat-XXX directories, where XXX follows a pattern such as 6.0.25.A-RELEASE. Use the -h option of the tcruntime-instance.sh script to see the list of known tc Runtime versions; the list is outputted in the information about the -v option.

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

No.

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 

Pinning tc Runtime Instances to a Specific Version

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:

  • If you explicitly specify the -v version parameter, the tc Runtime instance is pinned to that version. This means that when you use the tcruntime-ctl.sh|bat script to start the instance, the instance always uses this tc Runtime version, even if you have installed a more recent version of the tc Runtime.

  • If you do not specify the -v version parameter, the tc Runtime instance is unpinned. This means that when you use the tcruntime-ctl.sh|bat script to start the instance, the script searches for the most recent version of tc Runtime and applies it to the instance.

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 

Best Practice: Naming tc Runtime Instances

The name of a tc Runtime instance is the name of its CATALINA_BASE directory, minus the leading directory paths. As a reminder, CATALINA_BASE is the base directory of the instance; this directory contains the instance-specific startup scripts in the bin sub-directory, the configuration files in the conf sub-directory, and so on. For example, if you create a tc Runtime instance in the /home/tcserver/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:

  • /home/tcserver1/springsource-tc-server-node/myServer

  • /home/tcserver2/springsource-tc-server-node/myServer

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:

  • /home/tcserver1/springsource-tc-server-node/myServer

  • /home/tcserver2/springsource-tc-server-node/myOtherServer

Creating a tc Runtime Instance with a Template

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

Templates Provided by tc Runtime

SpringSource tc Runtime provides a number of out-of-the-box templates. Most are server configuration related; for example, one template sets up a basic cluster node configuration and another sets up SSL.

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

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

Template NameComparison with Default tc Runtime Instance
apr-with-ssl

Differs as follows from the default tc Runtime instance:

  • A server.xml modified as follows:
    • An added APRLifecycleListener to detect the APR-based native library required to use the APR/native connector.
    • Uses the APR/native (APR) connector for HTTP.
    • An added APR HTTPS connector.
  • Sample certificate and key files for testing the SSL configuration.

    Warning: These sample certificates and key files are provided only to aid testing and debugging; they are not for production use. You must replace them with your own generated certificates and keys before moving to a production system.

NOTE: You must install the APR/native library in order to use the APR connector.

For more information, see Apache Portable Runtime (APR) based Native library for Tomcat and SSL Configuration HOW-TO on the Apache Tomcat Web site.

bio-with-ssl

Differs as follows from the default tc Runtime instance:

  • Modified server.xml that includes a Blocking IO (BIO) HTTPS connector.
  • Sample JKS keystore for testing the SSL configuration.

    Warning: The sample keystore is provided only to aid testing and debugging; it is not for production use. You must replace it with your own generated keystore before moving to a production system.

For more information, see The HTTP Connector and SSL Configuration HOW-TO on the Apache Tomcat Web site.

cluster-node

Differs as follows from the default tc Runtime instance:

  • Addition of the default Cluster configuration at the Engine level. By default, multicast discovery is used to identify other nodes in the cluster. If multicast is not enabled on the subnet or if multiple tc Runtime clusters may be present on the same subnet, reconfigure this cluster node to use static membership.
  • Addition of the jvmRoute attribute to the Engine element to uniquely identify the node. This is parameterized using ${tcserver.node}, which is defined in the CATALINA_BASE/conf/catalina.properties file.

For more information, see Clustering/Session Replication HOW-TO on the Apache Tomcat Web site.

diagnostics

Differs from the default tc Runtime instance as follows:

  • Sample JDBC resource configuration that integrates with the request diagnostics to report slow queries.
  • ThreadDiagnosticsValve has been configured at the Engine level to report on slow running requests.
jmx-over-ssl

Differs from the default tc Runtime instance as follows:

  • Modified server.xml that uses SSL for all JMX communication.
  • Sample JKS keystore that can be used to test the JMX over SSL configuration.

    Warning: The sample keystore is provided only to aid testing and debugging; it is not for production use. You must replace it with your own generated keystore before moving to a production system.

For more information, SSL Configuration HOW-TO on the Apache Tomcat Web site.

nio-with-ssl

Differs from the default tc Runtime instance as follows:

  • A modified server.xml that uses the Non-Blocking IO (NIO) connector for HTTP and includes an NIO HTTPS connector.
  • A sample JKS keystore that can be used to test the SSL configuration.

    Warning: The sample keystore is provided only to aid testing and debugging; it is not for production use. You must replace it with your own generated keystore before moving to a production system.

For more information, see The HTTP Connector and SSL Configuration HOW-TO on the Apache Tomcat Web site.


Creating tc Runtime Templates

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

  1. Create a directory in INSTALL_DIR/springsource-tc-server-edition/templates, where edition refers to the edition of tc Server you are using(node, developer or standard). Name the directory the name you will give to the template itself.

    [Note]Note

    Although not required, SpringSource recommends that you create new templates in the templates directory so you can keep all your templates together. In this procedure it is assumed that you are going to create new templates in the templates directory.

  2. For each tc Runtime file you want to customize, create the subdirectory in which it lives and then create the customized file in that subdirectory.

    For example, to create a customized server.xml, create the file in the conf subdirectory of the new template directory. If you want to add a new shell script, add it to the bin directory.

    You can also create your own subdirectories that will be copied to the new instance. You can also add application JAR files to the webapps directory if you want these applications to be automatically deployed each time you start the instance.

    Warning: Do not modify (and thus include in your template) the bin/tcruntime-ctl.sh|bat file. If you do, the template may break in future versions of tc Runtime.

  3. To use the template, specify its name at the -t option of the tcruntime-instance.sh|bat script. See examples in Creating a tc Runtime Instance Using a Template.

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

Creating Portable tc Runtime Instances

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.

Possible Exceptions to Portability of a tc Runtime Instance

If you originally specified additional options of the tcruntime-instance.sh|bat script when you created the first tc Runtime instance, the instance is not guaranteed to be portable. However, depending on the environment of the location to which you copy the instance, the copied instance might still start and work correctly without your having to update any of its configuration files. In particular:

  • If you originally specified the -j or -r options, then the tcruntime-instance.sh|bat script hardcoded the specified JDK or JRE path, respectively, in the resulting instance. If the copied instance would still use the same exact JDK or JRE path, then the instance is portable; otherwise, the instance will not start unless you modify this hardcoded JDK or JRE path.

  • Similarly, if you originally specified the -d option, the tcruntime-instance.sh|bat script hardcoded the location of the tc Server installation directory in the resulting instance. If you copy the instance to another location where the installation directory is still ../.., then the copied instance starts correctly.

  • If you specified the -v option to pin the tc Runtime instance to particular version of tc Runtime, the tcruntime-instance.sh|bat script created a file called conf/tomcat.version that specifies the version to which it is pinned. If you copy the instance to another location, it starts only if the corresponding tc Server installation also includes the exact version of the tc Runtime to which the instance is pinned.

    For example, if the file contains the string 6.0.25.A-RELEASE, then the tc Server main installation must contain a directory called tomcat-6.0.25.A-RELEASE.

7.2 Starting and Stopping tc Runtime Instances

The following sections describe how to start and stop tc Runtime instances on both Unix and Windows platforms.

On Unix platforms, you typically use shell scripts to start and stop tc Runtime instances; alternatively, you can configure your Unix boot process to start the instance automatically. On Windows, SpringSource recommends that you first install the tc Runtime instance as a Windows Service, and subsequently use the Windows Services console to start and stop it.

Unix: Starting and Stopping tc Runtime Instances Interactively Using tcruntime-ctl.sh

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:

  1. Start a terminal window and change to the CATALINA_BASE/bin directory of the tc Runtime instance you want to start or stop.

    For example, if you installed tc Server in /home/tcserver and created a new tc Runtime instance called myserver:

    prompt$ cd /home/tcserver/springsource-tc-server-node/myserver/bin

    (If you are using the Developer Edition or Standard Edition Runtime package of tc Server, the CATALINA_BASE directory path includes the springsource-tc-server-developer or springsource-tc-server-standard directory, respectively.)

  2. Start the tc Runtime instance by executing the tcruntime-ctl.sh start command. For example:

    prompt$ ./tcruntime-ctl.sh start

    This command starts the tc Runtime instance as a daemon under the current user account.

  3. Stop a currently running tc Runtime instance by executing the tcruntime-ctl.sh stop command:

    prompt$ ./tcruntime-ctl.sh stop

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

Unix: Starting tc Runtime Instances Automatically at System Boot Time

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:

  • TOMCAT_USER: Unix user account that you want the tc Runtime instance to run as.

  • TC_SERVER_HOME: Absolute pathname to the tc Runtime installation home directory. This directory will be something like /home/tcserver/springsource-tc-server-node, where /home/tcserver is the directory into which you installed tc Server. If you are using the Developer or Standard Edition Runtime package of tc Server, then the directory path instead will include springsource-tc-server-developer or springsource-tc-server-standard.

  • INSTANCE_BASE: Absolute pathname to the directory that contains your tc Runtime instance. By default, this directory is the same as the TC_SERVER_HOME directory; in this case, you can set the variable to $TC_SERVER_HOME. However, tc Runtime instances can be located anywhere, in which case you should specify the absolute pathname.

  • INSTANCE_NAME: Name of the tc Runtime instance. This name corresponds to the name of the directory in which the instance is located; this directory is relative to the INSTANCE_BASE directory.

  • JAVA_HOME: Absolute pathname of the home directory of the JDK you want the tc Runtime instance to use.

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.

Windows: Starting and Stopping tc Runtime Instances as Windows Services

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:

  1. If this is the first time that you will install and start the tc Runtime instance after creating it, start a command prompt window and continue with this procedure.

    If you have already installed the tc Runtime instance as a Windows Service, use the Windows Services control panel to start and stop it.

  2. Change to the CATALINA_BASE\bin directory of the tc Runtime instance you want to start or stop.

    For example, if you installed tc Server in c:\home\tcserver and created a new tc Runtime instance called myserver:

    prompt> cd c:\home\tcserver\springsource-tc-server-node\myserver\bin

    If you are using the Developer or Standard Edition of tc Server, the CATALINA_BASE directory will include the springsource-tc-server-developer or springsource-tc-server-standard directory, respectively.

  3. Install the tc Runtime instance as a Windows service:

    prompt> tcruntime-ctl.bat install

    The command installs the tc Runtime instance as an automatic Windows Service, which means that the tc Runtime instance starts automatically when you start the Windows computer. You can change this behavior using the Windows Service control panel.

    You should see a message indicating a successful installation:

    wrapper | SpringSource tc Runtime - tcserver-c-home-tcserver-springsource-tc-server-node-myserver installed.

  4. Now, and subsequently, start and stop the tc Runtime instance by using the Windows Services console. The tc Runtime instance is displayed in the console with the name SpringSource tc Runtime - unique-name, where unique-name is a unique combination of server name and server directory.

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.

Windows Java Service Wrapper

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:

  • ARCH

  • CATALINA_HOME

  • CATALINA_BASE

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.

tcruntime-ctl Command Reference

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.

Table 7.3. Commands of the tcruntime-ctl Script

CommandDescriptionPlatform
install run-as-userInstalls the tc Runtime instance as a Windows service. You then start and stop the service using the Windows Service console.

The optional run-as-user parameter specifies the user account that you want the tc Runtime service to actually run as when you start the service using the Windows Service console; if you do not specify this parameter, then the user account that initially installed it is used. You can specify only user accounts that have their Logon as Service right set to run a Windows service. See Setting the Logon-As- Service Right for a Windows User.

When you run this command and explicitly specify a run-as-user user, the script asks you for the password of the specified user. tc Runtime still installs the instance as a service, even if you enter an incorrect password. However, when you try to start the service, it fails with a logon error. You must uninstall the service and reinstall it with the correct password.

Windows only
uninstallUninstalls the tc Runtime instance from the Windows Service.Windows only
startStarts the tc Runtime instance as a daemon process.

On Windows, you must have previously installed the tc Runtime instance as a Windows service to be able to start it using the tcruntime-ctl.bat start command; see the documentation on the tcruntime-ctl.bat install command in this table for more information.

Unix and Windows
restart timeoutStops, and then immediately starts, a running tc Runtime instance. As with the start command, restart starts the instance as a daemon process.

On Windows, you must have previously installed the tc Runtime instance as a Windows service to be able to restart it using the tcruntime-ctl.bat restart command; see the documentation on the tcruntime-ctl.bat install command in this table for more information.

By default, the tcruntime-ctl script (when stopping the tc Runtime instance) waits for 5 seconds and checks to see if the process has exited gracefully; if it has not, then the script forces a termination of the process. Using the optional timeout parameter, you can set your own timeout value by specifying an integer option for the number of seconds. For example, to specify that you want the instance to stop after 10 seconds:

prompt$ ./tcruntime-ctl.sh restart 10

Unix and Windows
runStarts the tc Runtime instance as a foreground process.Unix and Windows
batchRuns the tc Runtime instance using the catalina.bat script as a batch job. Specifically, the script starts the tc Runtime instance by running the following command: %CATALINA_HOME%\bin\catalina.bat run.Windows only
stop timeoutStops a running tc Runtime instance. By default, the tcruntime-ctl script waits for 5 seconds and checks to see if the process has exited gracefully; if it has not, then the script forces a termination of the process.

Using the optional timeout parameter, you can set your own timeout value by specifying an integer option for the number of seconds. For example, to specify that you want the instance to stop after 10 seconds:

prompt$ ./tcruntime-ctl.sh stop 10

Unix and Windows
statusReports the status of a tc Runtime instance, such as whether it is running or stopped, as well as useful information such as the directory from which the tc Runtime instance gets its binary files, the main instance source directory, and so on.Unix and Windows

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.

Table 7.4. Options of the tcruntime-ctl Script

OptionDescription
-d tcRuntimeDirReplace tcRuntimeDir with the full pathname of the tc Server installation directory. Use this option if you are running the tcruntime-ctl.sh|bat script from a location other than its default location.

The default value of this option is the location of the tcruntime-ctl.sh|bat script.

-n instanceDirReplace instanceDir with the full pathname of parent the tc Runtime instance directory. Use this option if the tc Runtime instance directory is not in the default location (i.e. the main tc Server installation directory).

For example, if the full instance directory of a tc Runtime instance is /home/tcserver/instances/myserver, then you would specify /home/tcserver/instances for this option.

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


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

Windows: Setting the Logon-as-Service Right for a Windows User

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:

  1. From the Windows Start menu, open the Control Panel.

  2. Open Administrative Tools.

  3. Open the Local Security Policy tool.

  4. Expand the Local Policies settings.

  5. Click the User Rights Assignment.

  6. On the right side, double-click on the Log on as a service policy.

  7. Click on the Add User Or Group button and enter the user account name using the wizard.

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.

7.3 Windows: Installing the HQ Server and Agents as Windows Services

SpringSource recommends that you install both the HQ Server and all HQ Agents as Windows Services, and then start and stop them from the Service console. This section describes how to install both components. See Controlling the HQ Server and Agents for details about starting and stopping the HQ Server and Agents, particularly when starting the HQ Agent for the first time.

To install the HQ Server as a Windows Service:

  1. Open a command prompt window.

  2. Change to the HQ_SERVER_INSTALL_DIR\bin directory, where HQ_SERVER_INSTALL_DIR refers to the directory in which you installed the HQ Server, such as c:\home\tcserver\server-4.2.X.X-EE\bin:

    prompt> cd c:\home\tcserver\server-4.2.X.X-EE\bin
  3. To install the HQ Server as a Windows Service:

    prompt> hq-server.exe -i 

    Note: If you are on version 2.0.0 of tc Server, see the TCSRV-1187 known issue and follow those instructions instead.

    After a few status messages, you will see a Done. message when installation is complete.

    The command installs the HQ Server as an automatic Windows Service, which means that the server starts automatically when you start the Windows computer. You can change this behavior through the Windows Service control panel.

    Now, and subsequently, start (and stop) the HQ Server using the Windows Service control panel. The HQ Server is listed as Hyperic HQ Server.

  4. To uninstall the Windows service:

    prompt> hq-server.exe -u

    You will see a Removing 'Hyperic HQ Server' Service ... Done upon completion.

To install the HQ Agent as a Windows Service:

  1. Start a command prompt window.

  2. If you have not already done so, set the HQ_JAVA_HOME system environment variable to point to the location of your JDK or JRE. Set it as a system environment variable; if you set it as a user environment variable, the HQ Agent aborts on startup.

  3. Change to the HQ_AGENT_INSTALL_DIR\bin directory, where HQ_AGENT_INSTALL_DIR refers to the directory in which you installed the HQ Agent.

    If you installed the HQ Agent as part of the Managed Node, then HQ_AGENT_INSTALL_DIR is relative to the main tc Server node installation directory, such as c:\home\tcserver\springsource-tc-server-node\hyperic-hq-agent-4.2.X.X-EE. If, however, you installed the HQ Agent separately, then the HQ_AGENT_INSTALL_DIR might be something like c:\home\tcserver\agent-4.2.X.X-EE.

    In the following example, it is assumed that you installed the HQ Agent as part of the tc Server Managed Node installation:

    prompt> cd c:\home\tcserver\springsource-tc-server-node\hyperic-hq-agent-4.2.X.X-EE\bin 
  4. To install the HQ Agent as a Windows service:

    prompt> hq-agent.bat install

    You see a Hyperic HQ Agent installed. message upon completion.

    The preceding command installs the HQ Agent as an automatic Windows Service, which means that the agent starts automatically when you start the Windows computer. You can change this behavior using the Windows Service control panel.

    If you are starting the HQ Agent for the first time, see the procedure for starting the HQ Agents for further instructions. Subsequently, start (and stop) the HQ Agent using the Windows Service control panel. The HQ Server is listed as Hyperic HQ Server.

  5. To remove (uninstall) the Windows service:

    prompt> hq-agent.bat remove

    You will see a Hyperic HQ Agent removed. message upon completion.

7.4 Starting and Stopping the HQ Server and Agents

This section describes how to control the HQ Server and Agents, specifically starting and stopping them.

On Unix platforms, you always use shell scripts to start and stop the HQ Server and HQ Agent. On Windows, it is recommended that you first install both the server and agents as Windows Services, and subsequently use the Windows Services console to start and stop them. Using the Windows Services console, you can also specify whether the HQ Server and Agent should start automatically when the operating system itself starts. The section below describes how to install the server and agents as Windows services.

Depending on how you have configured all the components of tc Server (tc Runtime, HQ Server and HQ Agents), you might run the commands to start and stop the HQ Agent and Server on the same computer or on different computers.

[Note]Note

This section provides basic information about starting and stopping the HQ Server and Agent, just enough to get you up and running. For additional detailed information, see Hyperic documentation links:

Unix: Starting and Stopping the HQ Server and Agent

To start and stop the HQ Server:

  1. Open a new terminal window.

  2. Change to the HQ_SERVER_INSTALL_DIR/bin directory, where HQ_SERVER_INSTALL_DIR refers to the directory in which you installed the HQ Server, such as /home/tcserver/server-4.2.X.X-EE. For example:

    prompt$ cd /home/tcserver/server-4.2.X.X-EE/bin
  3. To start the HQ Server:

    prompt$ ./hq-server.sh start

    After displaying startup information, the script eventually displays HQ server booted on success.

  4. To stop the HQ Server:

    prompt$ ./hq-server.sh stop

    The server is fully stopped when you see the message HQ Server is stopped.

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:

  1. Start a new terminal window.

  2. Change to the HQ_AGENT_INSTALL_DIR/bin directory, where HQ_AGENT_INSTALL_DIR refers to the directory in which you installed the HQ Agent.

    If you installed the HQ Agent as part of the Managed Node, then HQ_AGENT_INSTALL_DIR is relative to the main tc Server node installation directory, such as /home/tcserver/springsource-tc-server-node/hyperic-hq-agent-4.2.X.X-EE. If, however, you installed the HQ Agent separately, then the HQ_AGENT_INSTALL_DIR might be something like /home/tcserver/agent-4.2.X.X-EE.

    In the following example, it is assumed that you installed the HQ Agent as part of the tc Server Managed Node installation:

    prompt$ cd /home/tcserver/springsource-tc-server-node/hyperic-hq-agent-4.2.X.X-EE/bin 
  3. To start the HQ Agent, execute the following command:

    prompt$ ./hq-agent.sh start

    The script displays Starting HQ Agent... on success.

    [Important]Important

    The first time you start the agent, the script requests information about the HQ Server to which it will communicate; this is a one-time event and subsequent starts of the agent do not require this input. See the table in the Startup and Configure the HQ Agent section of the Hyperic documentation for information about these prompts.

  4. To stop the HQ Agent, execute the following command:

    prompt$ ./hq-agent.sh stop

    The agent is fully stopped when you see the message Stopped HQ Agent.

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

Windows: Starting and Stopping the HQ Server and Agent

To start and stop the HQ Server:

  1. If you have not already done so, install the HQ Server as a Windows Service, as described in Installing the HQ Server and Agents as Windows Services.

  2. Start (and stop) the HQ Server using the Windows Service control panel. The HQ Server is listed as Hyperic 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:

  1. If you have not already done so, install the HQ Agent as a Windows Service, as described in Installing the HQ Server and Agents as Windows Services.

  2. If this is the first time you start the HQ Agent after installing it, start a command prompt window and continue with this procedure.

    Otherwise, use the Windows Service console to start (and stop) the HQ Agent. The HQ Agent is listed as the Hyperic HQ Agent.

  3. If you have not already done so, set the HQ_JAVA_HOME system environment variable to point to the location of your JDK or JRE. Note that you are required to set it as a system environment variable; if you set it as a user environment variable, the HQ Agent will abort on startup.

  4. Change to the HQ_AGENT_INSTALL_DIR\bin directory, where HQ_AGENT_INSTALL_DIR refers to the directory in which you installed the HQ Agent.

    If you installed the HQ Agent as part of the Managed Node, HQ_AGENT_INSTALL_DIR is relative to the main tc Server node installation directory, such as c:\home\tcserver\springsource-tc-server-node\hyperic-hq-agent-4.2.X.X-EE. If, however, you installed the HQ Agent separately, then the HQ_AGENT_INSTALL_DIR might be something like c:\home\tcserver\agent-4.2.X.X-EE.

    In the following example, it is assumed that you installed the HQ Agent as part of the tc Server Managed Node installation:

    prompt> cd c:\home\tcserver\springsource-tc-server-node\hyperic-hq-agent-4.2.X.X-EE\bin 
  5. The first time you start the HQ Agent, you must start it from the command line:

    prompt> hq-agent.bat start 

    The command requests information about the HQ Server to which it will communicate; this is a one-time event and subsequent starts of the HQ Agent do not require this input. See the table in the Startup and Configure the HQ Agent section of the Hyperic documentation for information about these prompts.

  6. Subsequently, start (and stop) the HQ Agent using the Windows Service console. The HQ Agent is listed as the Hyperic HQ Agent.

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

7.5 Getting Started with the HQ User Interface

After you install and start the HQ Server and all the agents on all computers that host tc Runtime instances, you invoke the HQ user interface in your browser so that you can start using it to monitor and configure tc Runtime instances, as well as other resources.

The following procedure describes how to access the HQ user interface, add a tc Runtime instance to the HQ inventory, and update the tc Runtime instance JMX configuration properties so that HQ can manage them.

  1. Invoke the HQ user interface in your browser:

    http://host:port 

    where:

    • host is the computer on which you installed the HQ Server. If your browser is running on the same computer as the HQ Server, you can use localhost or 127.0.0.1.

    • port is the TCP/IP listen port of the HQ Server, specified when you installed the server. The default value is 7080.

      The TCP/IP listen port is configured in the HQ_SERVER/conf/hq-server.conf file, where HQ_SERVER is the directory in which you installed the HQ Server. If the default listen port does not work, search this file for the actual value of the server.webapp.port property.

    For example, use the following URL if HQ server is running locally using the default listen port:

    http://localhost:7080
  2. At the login screen, enter the administrator login. The default username is hqadmin, with password hqadmin.

    The server administrator username and password are configured in the HQ_SERVER/data/hq-server-install.conf file, where HQ_SERVER is the directory in which you installed the HQ Server. If the default values do not work, search this file for the actual values of the server.admin.username and server.admin.password properties.

    Important: As is true for all default passwords, be sure to change it as soon as possible to ensure maximum security for your installation.

  3. Select a default dashboard for the administration user; this selection affects only the appearance of the HQ user interface, not its functionality. SpringSource recommends you select hqadmin then click OK. You can change the default dashboard after you log in.

  4. The following graphic displays the main HQ dashboard. Highlighted objects are ones that you always use or use when you get started; see the explanation for each object after the graphic.

    • The two Dashboard links return you to this main dashboard console page.

    • The Resources link allows you to browse the full set of resources known by HQ, quickly scan the resources that are currently down, or easily go to the resources you have most recently viewed.

    • The Auto-Discovery Portlet always shows the resources that HQ has auto-discovered but you have not yet worked with (either adding them to the HQ inventory or skipping them). For example, if you start a tc Runtime instance before logging into HQ, then the instance should automatically show up in the auto-discovery portlet. In the next step you will add these resources to HQ's inventory.

    • The Help button provides context-sensitive online help, with useful information about what tasks you can perform on each HQ user interface page.

  5. Import your operating system platform, the tc Runtime instance, and other resources running on the platform into the HQ inventory by selecting the appropriate radio buttons next to the resource in the Auto-Discovery portlet and clicking Add to Inventory, as shown in the following graphic.

    The tc Runtime instance shows up as platform-resource tc Runtime catalina-base-dir in the HQ user interface, where platform-resource refers to the computer on which the 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. The HQ Agent might also show up in the auto-discovery portlet, listed as HQ Agent 4.2.X.X-EE.

    Because of the auto-discovery feature of HQ, your operating system platform should automatically show up in the Auto-Discovery portlet on the main Dashboard screen of the HQ user interface. Other resources running on the operating system, such as other tc Runtime instances, will also show up in the portlet. This is true for all computers running HQ agents that communicate with this HQ Server.

    [Tip]Tip

    It can sometimes take a few minutes for a newly-started resource, such as the tc Runtime instance, to show up in the auto-discovery portlet.

    After you click Add to Inventory, selected resources show up in the Recently Added portlet of the main Dashboard.

  6. Click the Resources > Browse link at the top of the HQ user interface.

    This brings you to a console page from which you can view all the resources in the HQ inventory. You view the tc Runtime instances by clicking on the Servers(X) link, as shown:

  7. Click the Servers(X) link. A list of all the servers in your inventory appears in the table. The tc Runtime instances are listed as platform-resource tc Runtime catalina-base-dir .

  8. In the table, click on the tc Runtime instance you just added to the HQ inventory, as shown in the preceding graphic.

    HQ displays the configuration and management pages of a tc Runtime instance, as shown in the next graphic and ensuing explanation.

    • Monitor tab. Displays monitoring information about a tc Runtime instance and its services, such as the deadlocks detected, available heap memory, and so on. The charts show either graphical or tabular data about the metrics; click Indicators or Metric Data to view each kind of data. Click a particular service in the Services table to view diagnostic information about that particular service that is associated with the tc Runtime instance.

    • Inventory tab. View and manage the tc Runtime instance's general properties, the services hosted by the server, groups containing the server, and the server's monitoring and control configuration.

    • Alerts tab. View, configure, and create alerts for a tc Runtime instance.

    • Control tab. Start, stop, and restart this tc Runtime instance, as well as schedule one of these actions for a future date.

    • Views tab. Has two subtabs: Server Configuration and Application Deployment. Use the Server Configuration tab to configure the tc Runtime instance, such as startup JVM parameters, JSP behavior, and properties of the Catalina service, such as connectors and engines. The application deployment tab allows you to deploy Web applications to the tc Runtime instance, as well as start, stop, reload, and undeploy already deployed Web applications.

  9. Click the Inventory tab.

  10. Scroll down to the Configuration Properties section.

    The HQ user interface uses the values of the fields in this section to connect to the tc Runtime instance, control it, and so on. In particular, the Shared section specifies the JMX properties of the tc Runtime instance; HQ uses JMX to configure and manage tc Runtime instances.

    [Important]Important

    If you have not changed the JMX values in server.xml, HQ will populate these fields automatically, so the tc Runtime instance should work with HQ without change. However, if you have changed the JMX values of your tc Runtime instance by manually updating its server.xml file, then you must change the corresponding fields in the HQ user interface, as described in the following procedure.

    1. Click Edit.

    2. Update the following fields as required:

      • jmx.url: URL that the HQ user interface uses to connect to the JMX server associated with the tc Runtime instance. The format is service:jmx:rmi:///jndi/rmi://host:jmxport/jmxrmi. Be sure the value of host is the name of the computer on which the JMX server is running (you can use localhost if it is the same as the computer hosting HQ server) and that the value of jmxport is the value of the port attribute of the <Listener> element in the tc Runtime instance's server.xml file that corresponds to the com.springsource.tcserver.serviceability.rmi.JmxSocketListener class (default value is 6969).

      • jmx.username: JMX username that HQ uses to connect to the JMX server associated with the tc Runtime instance. The username is stored in the file pointed to by the passwordFile attribute of the <Listener> element in the tc Runtime instance's server.xml file that corresponds to the com.springsource.tcserver.serviceability.rmi.JmxSocketListener class; by default, the name of this file is CATALINA_BASE/conf/jmxremote.password. The default username is admin.

      • jmx.password: Password of jmx.username. The password is stored in the same file as the username, as described in the preceding bullet. The default password is springsource.

    3. Click OK.

You are now ready to monitor and configure the tc Runtime instance using Hyperic HQ. For a tutorial that describes how to perform common management and configuration tasks using HQ, see Tutorial: Using HQ to Configure and Manage tc Runtime Instances.

For detailed conceptual and task information about using HQ, click the Help button on the HQ user interface or consult the HQ Documentation.

7.6 Deploying Applications to tc Runtime Instances

Deployment refers to the process of installing a Web application into the tc Runtime instance. This section describes two ways to deploy Web applications to the tc Runtime instance.

  • Static deployment: To deploy statically, you simply copy your Web application, either as a packaged WAR file or as an uncompressed directory (also called exploded), to the deployment directory of the tc Runtime instance. This directory is specified by the appBase property of your virtual host; the default value is CATALINA_BASE/webapps. Assuming that the autoDeploy property of your host is enabled (default value), then as soon as you copy your Web application to the deployment directory, the tc Runtime instance deploys and starts it, and users can immediately start using the application. See the procedure below for details.

  • Dynamic deployment using HQ: The HQ user interface is a sophisticated GUI console with which you can deploy Web applications located on local or remote computers. You can also create groups of tc Runtime instances and then deploy a WAR file to the group; the HQ user interface then takes care of deploying the WAR file to each individual member of the group. This feature helps you avoid having to deploy to each tc Runtime instance individually, saving you much time if you have many servers in your environment.

    See Tutorial: Using HQ to Configure and Manage tc Runtime Instances for a tutorial that describes how to deploy applications to single tc Runtime instances, create tc Runtime groups, and deploy an application to the group.

It is assumed in this section that you have already created a Web application and want to deploy it to a tc Runtime instance so you can start using the application. If you do not have a Web application, see Tutorial: Very Simple Web Application Development for a tutorial that describes how to create a very simple HelloWorld application.

To deploy a Web application statically: Copy the WAR or exploded directory to the deployment directory, which by default is CATALINA_BASE/webapps. For example, if your CATALINA_BASE variable is /home/tcserver/springsource-tc-server-node/myserver, and your Web application is the exploded directory /home/apps/myApp, then you deploy it statically with the following command:

prompt$ cp /home/apps/myApp /home/tcserver/springsource-tc-server-node/myserver/webapps

If you want to use a different deployment directory than the default CATALINA_BASE/webapps, set the the appBase attribute of the <Host> element that configures the virtual host for your tc Runtime instance. For additional details about static deployment, see Tomcat Web Application Deployment.

Deploying Applications Using Tomcat Manager (Developer Edition Only)

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.

  1. Update the CATALINA_BASE/conf/tomcat-users.xml file of the tc Runtime instance by adding a manager role.

    The default tomcat-users.xml file does not include any roles or users, although examples are shown in the comments.

    An entry for the manager role would look like the following (shown in bold):

    <tomcat-users>
      <role rolename="manager" />
      ...
    </tomcat-users>
  2. In the same file, add a user with role manager. For example, to specify that the tomcat user (with password tomcat) have the manager role, add the following to the tomcat-users.xml file (shown in bold):

    <tomcat-users>
      <role rolename="manager" />
      <user username="tomcat" password="tomcat" roles="manager" />
      ...
    </tomcat-users>
  3. Restart the tc Runtime instance for the changes to take effect. For example, on Unix:

    prompt$ cd /home/tcserver/springsource-tc-server-developer
    prompt$ ./tcruntime-ctl.sh spring-insight-instance restart
  4. Invoke Tomcat Manager in your browser using the following URL:

    http://host:8080/manager/html

    where host refers to the computer on which you are running the tc Runtime instance. If it is the same as the browser, you can use localhost:

    http://localhost:8080/manager/html
  5. Enter the user and password you just configured; in our example, these are tomcat/tomcat.

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.

7.7 Uninstalling tc Server: Typical Steps

Uninstall one or more of these components as you wish:

Uninstallation of tc Server mostly entails removing the directories that contain the component files, although a few extra steps might be required, as described below.

Each section covers both Unix and Windows commands. The documentation uses Unix-like forward slashes (/) for directories; if you are on a Windows platform, change these to back slashes (\).

WARNING: The procedures in this section describe how to completely remove the components of tc Server from your computer.

Uninstalling HQ Server

To uninstall the HQ Server component of tc Server:

  1. Start a terminal window (Unix) or command prompt (Windows).

  2. If currently running, stop the HQ Server. See Starting and Stopping the HQ Server and Agents.

  3. Windows only. If you installed the HQ Server as a Windows service, change to the HQ_SERVER_INSTALL_DIR\bin directory (where HQ_SERVER_INSTALL_DIR refers to the directory in which you installed the HQ Server, such as c:\home\tcserver\server-4.2.X.X-EE) and uninstall the service using the following command:

    prompt> cd:\home\tcserver\server-4.2.X.X-EE\bin 
    prompt> hq-server.exe -u
  4. Remove the directory in which you installed the HQ Server, such as /home/tcserver/server-4.2.X.X-EE:

    prompt$ cd /home/tcserver
    prompt$ rm -rf server-4.2.X.X-EE

Uninstalling HQ Agent

To uninstall the HQ Agent component of tc Server:

  1. If the agent itself is managed by HQ, remove the platform for the agent using the HQ user interface.

  2. Start a terminal window (Unix) or command prompt (Windows).

  3. If currently running, stop the HQ Agent. See Starting and Stopping the HQ Server and Agents.

  4. Windows only. If you installed the HQ Agent as a Windows service, you should now uninstall it. Change to the HQ_AGENT_INSTALL_DIR\bin directory, where HQ_AGENT_INSTALL_DIR refers to the directory in which you installed the HQ Agent. For example, if you installed the HQ Agent as part of a managed node, then the installation directory might be something like c:\home\tcserver\springsource-tc-server-node\hyperic-hq-agent-4.2.X.X-EE). Once in this directory, uninstall the service using the hq-agent.bat remove command. For example :

    prompt> cd:\home\tcserver\springsource-tc-server-node\hyperic-hq-agent-4.2.X.X-EE\bin
    prompt> hq-agent.bat remove
  5. Remove the directory in which you installed the HQ Agent. If you installed it as part of a managed node, the directory might be something like /home/tcserver/springsource-tc-server-node/hyperic-hq-agent-4.2.X.X-EE:

    prompt$ cd /home/tcserver
    prompt$ rm -rf hyperic-hq-agent-4.2.X.X-EE

Uninstalling tc Runtime

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

  1. If currently running, stop all tc Runtime instances. See Starting and Stopping tc Runtime Instances.

  2. Start a terminal window (Unix) or command prompt (Windows).

  3. Windows only. If you installed any tc Runtime instances as Windows services, change to the CATALINA_BASE\bin directory of each instance (such as c:\home\tcserver\springsource-tc-server-node\myserver\bin) and uninstall the service using the following command:

    prompt> c:\home\tcserver\springsource-tc-server-node\myserver\bin
    prompt> tcruntime-ctl.bat uninstall
  4. Remove the main tc Server installation directory. For example, if you installed a managed node, the delete command might look something like the following:

    prompt$ rm -rf /home/tcserver/springsource-tc-server-node

    By default, the home directory of all tc Runtime instances is under the main tc Server installation directory; if you used this default location when you created the tc Runtime instances with the tcruntime-instance script, then the preceding delete command also deleted all tc Runtime instances.

  5. If you created any tc Runtime instances in locations other than the default tc Server installation directory, remove their corresponding home directories.

8. Upgrade and Migration Guide

This chapter describes how to perform the following supported upgrade and migration procedures:

8.1 Before You Begin: Installation Prerequisites and New Versioning Process

It is assumed in this chapter that you have an existing installation of tc Server, Hyperic HQ, or SpringSource ERS, and you want to upgrade or migrate to the latest version of tc Server, or upgrade your HQ installation so it can manage tc Server. If you are installing tc Server for the first time, see Installing tc Server.

As of the tc Server 2.0.x release, the bundle itself has a separate version number from the underlying components. The 2.0 release represents the second major revision of the tc Server product bundle. Minor revisions, maintenance updates, and service releases of any set of underlying components will likewise increment the fully qualified bundle version. As of the 2.0 release, the bundle contains the following separately versioned components. The initial major version of each component is noted. Specific downloads will have fully qualified version information on each component.

  • tc Runtime . Apache Tomcat-based runtime container, major version 6.0. The fully qualified version of the tc Runtime is a combination of the underlying Apache Tomcat version and an alphabetic modifier to track maintenance updates on the same underlying Tomcat version, for example, 6.0.25.A-RELEASE .
  • tc Server HQ Plug-in. Hyperic HQ plug-in that enables advanced management and monitoring, major version 2.0.
  • Hyperic HQ Agent. Agent portion of bundle, major version 4.2.
  • Hyperic HQ Server. HQ Server, preconfigured with the tc Server HQ plug-in, major version 4.2.

8.2 Upgrading a 2.0.X tc Server Installation to the Latest Version

The procedure in this section describes how to upgrade a 2.0.X tc Server installation (such as 2.0.0) to a later 2.0.X version (such as 2.0.4).

Understanding the 2.0.X tc Server Upgrade Process

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:

  • Upgrade your existing HQ Server to a later version of Hyperic HQ Server included in the 2.0.X bundle of tc Server. See the Release Notes for the current fully-qualified version of the bundled HQ Server. This HQ Server is preconfigured with the tc Server HQ plug-in.

    Note: If only the tc Server HQ plug-in inside of the HQ Server changed (in other words, the HQ Server itself did not change), then the version of the HQ server will be the same as the HQ Server included in the previous tc Server version. In this case, you do not upgrade the HQ Server itself; rather, you upgrade the tc Server HQ plug-in.

    To perform this subtask, you either download the latest tc Server-ready version of the Hyperic HQ distribution and use its setup.sh -upgrade (Unix) or setup.bat -upgrade (Windows) command script to perform the upgrade, or if the HQ Server itself did not change, you unzip the latest tc Server HQ plug-in into your existing HQ Server installation.

  • Install the latest version of HQ Agent included in version 2.0.X of tc Server (4.2.X.X-EE). You do not actually upgrade your existing HQ Agent; rather, you simply install the new HQ Agent that is preconfigured with the tc Server HQ plug-in and immediately start using it. If the version of the HQ Agent did not change, then the installation simply overwrites the existing HQ Agent directory.

    To perform this subtask, you obtain the HQ Agent from either the managed node package of the Standard Edition of tc Server, or by using the setup.sh (Unix) or setup.bat (Windows) script from the Hyperic HQ distribution. This documentation describes the former.

  • Install the 2.0.X tc Runtime on top of the previous version and upgrade existing tc Runtime instances to use the latest verison of the Runtime.

    To perform this subtask, you unzip the appropriate tc Server distribution into your existing tc Server installation directory. Then you use the tcruntime-instance.sh script to upgrade each tc Runtime instance, if necessary.

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.

tc Server 2.0.X Upgrade Procedure

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:

  1. Unix only: Read Important Note When Installing on Unix Platforms.

  2. On the computer on which you are going to upgrade the existing HQ Server:

    1. Back up your existing HQ Server installation, including any external database that you are using.

    2. Start a terminal (Unix) or command prompt (Windows).

    3. If the HQ server is running, shut it down. For example, on Unix, if you installed the HQ server in /home/tcserver:

      prompt$ cd /home/tcserver/server-4.2.0.7-EE/bin
      prompt$ ./hq-server.sh stop

      On Windows, if you installed the HQ server as a Windows service, you use the Windows Services Console to stop the server.

      See Starting and Stopping the HQ Server and Agents.

    4. Windows only. If you installed the HQ Server as a Windows service, uninstall it. For example:

      prompt> cd c:\home\tcserver\server-4.2.0.7-EE\bin
      prompt> hq-server.exe -u

      See Windows: Installing the HQ Server and Agents as Windows Services

    5. Check to see whether the version of the HQ Server itself has changed. For example, if your existing HQ Server is installed in /home/tcserver/server-4.2.0.8, and the Release Notes indicate that the version of HQ Server included in the tc Server version to which you are upgrading is 4.2.0.8, then the HQ Server itself has not changed, only the bundled tc Server HQ plug-in has changed. In this case, follow the Upgrading Only the Server-Side tc Server HQ Plug-in procedure to upgrade just the plug-in.

      If, however, the version of the HQ Server has changed (for example, from 4.2.0.7 to 4.2.0.8), follow these steps to upgrade it:

      1. Download the platform-neutral distribution of the HQ Server (preconfigured with the tc Server HQ plug-in) from the SpringSource Download Center.

        The platform-neutral tc Server-ready HQ Server is distributed as a compressed TAR file (Unix) and ZIP file (Windows); for example:

        • hyperic-hq-installer-noJRE-tc-server-2.0.4.RELEASE.tar.gz
        • hyperic-hq-installer-noJRE-tc-server-2.0.4.RELEASE.zip

        In this step, it is assumed that your existing HQ Server uses an external database, such as Postgres, rather than the database packaged with HQ Server. If you are using the built-in database (which SpringSource does not recommend for production environments), then you should download the appropriate platform-specific tc Server-ready HQ installation package (such as hyperic-hq-installer-x86-linux-tc-server-2.0.4.RELEASE.tar.gz) rather than the platform-neutral one.

      2. Unzip or untar the HQ Server distribution into a temporary directory.

        For example, if you downloaded the distribution to the /home/Downloads directory on Unix:

        prompt$ cd /home/Downloads
        prompt$ tar xvzf hyperic-hq-installer-noJRE-tc-server-2.0.4.RELEASE.tar.gz

        The unzip or tar command creates a directory called hyperic-hq-installer-noJRE-tc-server-2.0.4.RELEASE that contains the setup.sh|bat script and all the product files.

      3. If you are using an external database to store HQ data, start the database server if it is not already running. Consult your database server documentation for details.

      4. From your terminal window or command prompt, change to this directory and execute the setup.sh -upgrade (Unix) or setup.bat -upgrade (Windows) script. The -upgrade flag specifies that the script should migrate information about the existing tc Runtime instances from your existing HQ server to the new HQ Server. For example, on Unix:

        prompt$ cd /home/Downloads/hyperic-hq-installer-noJRE-tc-server-2.0.4.RELEASE
        prompt$ ./setup.sh -upgrade
      5. After accepting the terms of the agreement, enter the full pathname of the directory that contains the previous version of the HQ Server that you want to upgrade, for example /home/tcserver/server-4.2.0.7-EE.

      6. At the prompt, enter the full pathname of the directory in which you want to install the new HQ Server. If, for example, you want to install the new HQ server alongside the existing HQ server mentioned in the previous step , enter /home/tcserver.

        Note:The specified directory must already exist; the setup program does not create it for you.

        The setup script creates a new subdirectory under your inputted directory for the new HQ Server, such as /home/tcserver/server-4.2.0.8-EE. The setup script then migrates a subset of information about the existing tc Runtime instances from the old version of the HQ server to the new HQ Server.

        If the upgrade of the HQ Server completes successfully, you should see the following message:

        Setup completed.
        A copy of the output shown above has been saved to:
          /home/Downloads/hyperic-hq-installer-noJRE-tc-server-2.0.4.RELEASE/installer-4.2.0.8-EE/logs/hq-install.log

        From now on, you should use this new HQ Server; it should have basic information about the existing tc Runtime instances from your old HQ Server.

    6. Start the upgraded server using the bin/hq-server.sh start command. For example:

      prompt$ cd /home/tcserver/server-4.2.0.8-EE/bin
      prompt$ ./hq-server.sh start

      See Starting and Stopping the HQ Server and Agents for details and Windows instructions for installing the server as a service.

  3. On the computer on which you are going to install the new HQ Agent and upgrade the existing tc Runtime and its associated instances::

    1. Back up your existing HQ Agent and tc Runtime installation, including all your tc Runtime instances.

    2. Start a terminal (Unix) or command prompt (Windows.)

    3. If it is running, shut down the existing HQ Agent. If you are also planning to upgrade your tc Runtime instances at this time, shut them down as well. For example, if you installed the HQ agent and tc Runtime in /home/tcserver/springsource-tc-server-node and you have a tc Runtime instance called myserver:

      prompt$ cd /home/tcserver/springsource-tc-server-node
      prompt$ hyperic-hq-agent-4.2.0.7-EE/bin/hq-agent.sh stop
      prompt$ ./tcruntime-ctl.sh myserver stop

      If your tc Runtime instance is located in a directory other than the main tc Server installation directory, use the INSTANCE-DIR/bin/tcruntime-ctl.sh script to stop the instance; in this case, you do not specify the name of the instance as a parameter to the script. For example:

      prompt$ cd /home/tcserver/instances/myserver/bin
      prompt$ ./tcruntime-ctl.sh stop

      Windows only. If you installed the HQ Agent and tc Runtime instances as Windows services, you use the Windows Services Console to stop them both.

      See Starting and Stopping tc Runtime Instances and Starting and Stopping the HQ Server and Agents.

    4. Windows only. If you installed the HQ Agent as a Windows service, uninstall it. If you plan on upgrading your tc Runtime instances at this time, and you previously installed them as Windows services, uninstall them as well. For example, if you installed tc Server managed node in c:\home\tcserver\springsource-tc-server-node and you created a tc Runtime instance called myserver:

      prompt> cd c:\home\tcserver\springsource-tc-server-node\hyperic-hq-agent-4.2.0.7-EE\bin
      prompt> hq-agent.bat remove
      prompt> cd c:\home\tcserver\springsource-tc-server-node
      prompt> tcruntime-ctl.bat myserver uninstall

      If your tc Runtime instance is located in a directory other than the main tc Server installation directory, use the INSTANCE-DIR\bin\tcruntime-ctl.bat script to stop the instance; in this case, you do not specify the name of the instance as a parameter to the script. For example:

      prompt> cd c:\home\tcserver\instances\myserver\bin
      prompt> tcruntime-ctl.bat uninstall

      See Windows: Installing the HQ Server and Agents as Windows Services and >Windows: Starting and Stopping tc Runtime Instances as Windows Services.

    5. Download the appropriate tc Server distribution file from the SpringSource Download Center.

      Typically, you download the Standard Edition of tc Server (managed node package) in either the compressed TAR or ZIP format; for example:

      • springsource-tc-server-node-2.0.4.RELEASE.tar.gz
      • springsource-tc-server-node-2.0.4.RELEASE.zip

      It is assumed in the rest of this procedure that you have downloaded the managed node package of tc Server 2.0.X.

    6. Unzip or untar the new managed node package on top of your existing managed node directory. For example, if your existing managed node is installed in /home/tcserver/springsource-tc-server-node and you downloaded the new package into the /home/Downloads directory:

      prompt$ cd /home/tcserver
      prompt$ unzip /home/Downloads/springsource-tc-server-node-2.0.4.RELEASE.zip

      The preceding command overwrites some of your existing files, such as the tcruntime-XXX.sh|bat scripts; if the unzip or untar command asks you whether it should overwrite them, you should answer yes. The unzip or tar command also creates new directories, such as the new version of the HQ Agent (such as hyperic-hq-agent-4.2.0.8-EE and the new Tomcat directory (such as tomcat-6.0.29.A.RELEASE), which should be alongside the old versions.

    7. Start the new HQ Agent using the bin/hq-agent.sh start command. Henceforth, use this new HQ Agent and not the old HQ Agent. Following our example on Unix:

      prompt$ cd /home/tcserver/springsource-tc-server-node/hyperic-hq-agent-4.2.0.8-EE/bin
      prompt$ ./hq-agent.sh start
      [Note]Note

      The first time you start the new HQ Agent, the script requests information about the HQ Server to which it will communicate; specify the upgraded HQ Server (version 4.2.0.8 in our example.) This is a one-time event and subsequent starts of the agent do not require this input. See the table in the Configuring Agent Startup Settings Interactively section of the Hyperic documentation for information about these prompts.

      See Starting and Stopping the HQ Server and Agents for details and Windows instructions for installing the agent as a service.

    8. Upgrading pinned tc Runtime instances. This step describes how to upgrade the version of your pinned existing tc Runtime instances so that they use the latest tc Runtime as their core, such as 6.0.29.A-RELEASE. If your tc Runtime instances are unpinned, then you do not perform this step because they will automatically use the latest tc Runtime version.

      See Pinning a tc Runtime Instance to a Specific Version for more information about pinned or unpinned instances.

      From your terminal (Unix) or command window (Windows), change to the main tc Server managed node installation directory, such as /home/tcserver/springsource-tc-server-node:

      prompt$ cd /home/tcserver/springsource-tc-server-node

      For each existing pinned tc Runtime instance you want to upgrade, run the following command:

      prompt$ ./tcruntime-instance.sh -s instance -n instanceDir -m 

      where:

      • instance refers to the name of the subdirectory that contains the tc Runtime instance you want to upgrade, such as myserver
      • instanceDir refers to the full or relative pathname of the directory in which the instance lives. You do not have to specify this option if your instance directory is in the main tc Server installation directory, such as /home/tcserver/springsource-tc-server-node/myserver .

      Because you do not specify a specific tc Runtime version, the tcruntime-instance.sh|bat script unpins the instance so that it will always use the latest version of tc Runtime it can find when it starts.

      For example, to upgrade the tc Runtime instance myserver (whose instance directory is in the main tc Server installation directory) to the latest tc Runtime version:

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

      On Windows:

      prompt> tcruntime-instance.bat -s myserver -m 

      If the upgrade succeeds, you should see:

      Modifying existing instance "myserver" to tomcat-6.0.29.A-RELEASE
      Done.

      In the preceding examples, the myserver instance directory is assumed to be in the main tc Server installation, such as /home/tcserver/springsource-tc-server-node. If it is in a different directory, such as /home/tcserver/instances/myserver, then run the following command:

      prompt$ ./tcruntime-instance.sh -s myserver -n /home/tcserver/instances -m 
    9. Start the tc Runtime instances as described in Starting and Stopping tc Runtime Instances. The startup messages should indicate that the instance is now using version 6.0.29.A of Apache Tomcat as its core. For example:

      prompt$ cd /home/tcserver/springsource-tc-server-node
      prompt$ ./tcruntime-ctl.sh myserver start
      
      INFO Instance name:      myserver
      INFO Script directory:   /home/tcserver/springsource-tc-server-node
      INFO tc Runtime location:/home/tcserver/springsource-tc-server-node
      INFO Instance base:      /home/tcserver/springsource-tc-server-node
      INFO Binary dir:         /home/tcserver/springsource-tc-server-node/tomcat-6.0.29.A.RELEASE
      INFO Runtime version:    6.0.29.A.RELEASE
      INFO Script version:     2.0.4.RELEASE
      Using CATALINA_BASE:   /home/tcserver/springsource-tc-server-node/myserver
      Using CATALINA_HOME:   /home/tcserver/springsource-tc-server-node/tomcat-6.0.29.A.RELEASE
      Using CATALINA_TMPDIR: /home/tcserver/springsource-tc-server-node/myserver/temp
      Using JRE_HOME:        /home/java/jdk1.6.0_18
      Using CLASSPATH:       /home/tcserver/springsource-tc-server-node/tomcat-6.0.29.A.RELEASE/bin/bootstrap.jar

      If your tc Runtime instance is located in a directory other than the main tc Server installation directory, use the INSTANCE-DIR/bin/tcruntime-ctl.sh script to start the instance; in this case, you do not specify the name of the instance as a parameter to the script. For example:

      prompt$ cd /home/tcserver/instances/myserver/bin
      prompt$ ./tcruntime-ctl.sh start

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.

Post-Upgrade Requirements and Notes

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.

8.3 Upgrading a 6.0.X tc Server Installation to the Latest Version

The procedure in this section describes how to upgrade a tc Server installation to version 2.0.X from the following versions:

  • 6.0.19.A

  • 6.0.20.A

  • 6.0.20.B

  • 6.0.20.C

Understanding the 6.0.X tc Server Upgrade Process

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

  • Upgrade your existing AMS Server to the same (or later) fully-qualified version of Hyperic HQ Server included in the 2.0.X bundle of tc Server; see the Release Notes for the current fully-qualified version of the bundled HQ Server. This HQ Server is preconfigured with the tc Server HQ plug-in. This step migrates all the data from the previous version of the AMS server, such as discovered resources and alert settings, to the HQ Server.

    To perform this subtask, you download a platform-specific Hyperic HQ distribution and use its setup.sh (Unix) or setup.bat (Windows) command script.

  • Install the HQ Agent included in version 2.0.X of tc Server (4.2.X.X-EE). You do not actually upgrade your existing AMS Agent; rather, you simply install the new HQ Agent that is preconfigured with the tc Server HQ plug-in and immediately start using it.

    To perform this subtask, you obtain the HQ Agent from either the managed node package of the Standard Edition of tc Server, or by using the setup.sh (Unix) or setup.bat (Windows) script from the Hyperic HQ distribution.

  • Install the 2.0.X tc Runtime alongside the previous version and upgrade existing tc Runtime instances to version 2.0.X.

    To perform this subtask, you unzip the appropriate tc Server distribution into your existing tc Server installation directory. Then you use the tcruntime-instance.sh script to upgrade each tc Runtime instance.

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.

tc Server 6.0.X Upgrade Procedure

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

  1. Read tc Server Editions for a discussion of the editions of tc Server and the names of its various distribution files. When upgrading, you typically install the managed node version of the Standard Edition to get the HQ Agent and tc Runtime components. SpringSource recommends that you install the platform-specific version of the HQ Server rather than the platform-neutral; the platform-specific version includes a built-in Postgres database. This will make your upgrade process much easier.

  2. Unix only: Read Important Note When Installing on Unix Platforms.

  3. On the computer on which you are going to upgrade the existing AMS Server:

    1. Back up your existing AMS Server installation, including any external database that you are using instead of the built-in one.

    2. Start a terminal (Unix) or command prompt (Windows).

    3. If the AMS server is running, shut it down. For example, on Unix, if you installed the AMS server in /home/tcserver:

      prompt$ cd /home/tcserver/server-2.0.0.SR04/bin
      prompt$ ./ams-server.sh stop

      On Windows, if you installed the AMS server as a Windows service, you use the Windows Services Console to stop the server.

      See Starting and Stopping the AMS Server and Agents.

    4. Windows only. If you installed the AMS Server as a Windows service, uninstall it. For example:

      prompt> cd c:\home\tcserver\server-2.0.0.SR04\bin
      prompt> ams-ctl.bat uninstall

      See Starting and Stopping the AMS Server and Agents.

    5. Download the appropriate platform-specific distribution of the HQ Server (preconfigured with the tc Server HQ plug-in) from the SpringSource Download Center.

      The platform-specific, tc Server-ready HQ Server is distributed as a compressed TAR file (Unix) and ZIP file (Windows):

      • hyperic-hq-installer-unix-platform-tc-server-2.0.X.RELEASE.tar.gz
      • hyperic-hq-installer-windows-platform-tc-server-2.0.X.RELEASE.zip

      where unix-platform is something like x86-linux and windows-platform is something like win32.

    6. Unzip or untar the HQ Server distribution into a temporary directory.

      For example, if you downloaded the distribution to the /home/Downloads directory on Unix:

      prompt$ cd /home/Downloads
      prompt$ tar xvzf hyperic-hq-installer-x86-linux-tc-server-2.0.X.RELEASE.tar.gz

      The unzip or tar command creates a directory called hyperic-hq-installer-platform-tc-server-2.0.X.RELEASE that contains the setup.sh|bat script and all the product files.

    7. From your terminal window or command prompt, change to this directory and execute the setup.sh -upgrade (Unix) or setup.bat -upgrade (Windows) script. The -upgrade flag specifies that the script should migrate information about the existing tc Runtime instances from your existing AMS server to the new HQ Server. For example, on Unix:

      prompt$ cd /home/Downloads/hyperic-hq-installer-x86-linux-tc-server-2.0.X.RELEASE
      prompt$ ./setup.sh -upgrade
    8. After accepting the terms of the agreement, enter the full pathname of the directory that contains the previous version of the AMS server that you want to upgrade, for example /home/tcserver/server-2.0.0.SR04.

    9. At the prompt, enter the full pathname of the directory in which you want to install the new HQ Server. If, for example, you want to install the new HQ server alongside the existing AMS server mentioned in the previous step , enter /home/tcserver.

      Note:The specified directory must already exist; the setup program does not create it for you.

      The setup script creates a new subdirectory under the specified directory for the new HQ Server, such as /home/tcserver/server-4.2.X.X-EE. The setup script then migrates a subset of information about the existing tc Runtime instances from the old version of the AMS server to the new HQ Server.

      If the upgrade of the AMS server completes successfully, you should see the following message:

      Setup completed.
      A copy of the output shown above has been saved to:
        /home/Downloads/hyperic-hq-installer-x86-linux-tc-server-2.0.X.RELEASE/installer-4.2.X.X-EE/logs/hq-install.log
      
      Deleting temporary JRE
    10. From now on, you should use this new HQ Server; it should have basic information about the existing tc Runtime instances from your old AMS Server. To start the new server, use the bin/hq-server.sh start command. For example:

      prompt$ cd /home/tcserver/server-4.2.X.X-EE/bin
      prompt$ ./hq-server.sh start

      See Starting and Stopping the HQ Server and Agents for details and Windows instructions for installing the server as a service.

  4. On the computer on which you are going to install the new HQ Agent and upgrade the existing tc Runtime and its associated instances::

    1. Back up your existing HQ Agent and tc Runtime installation, including all your tc Runtime instances.

    2. Start a terminal (Unix) or command prompt (Windows.)

    3. If it is running, shut down the existing AMS Agent. If you are also planning to upgrade your tc Runtime instances at this time, shut them down as well. For example, if you installed the AMS agent and tc Runtime in /home/tcserver and you have a tc Runtime instance called myserver:

      prompt$ cd /home/tcserver/agent-2.0.0.SR04
      prompt$ ./ams-agent.sh stop
      prompt$ cd /home/tcserver/tcServer-6.0
      prompt$ ./tcserver-ctl.sh myserver stop

      If your tc Runtime instance is located in a directory other than the main tc Server installation directory, use the INSTANCE-DIR/bin/tcserver-ctl.sh script to stop the instance; in this case, you do not specify the name of the instance as a parameter to the script. For example:

      prompt$ cd /home/tcserver/instances/myserver/bin
      prompt$ ./tcserver-ctl.sh stop

      On Windows, if you installed the AMS Agent and tc Runtime instances as Windows services, you use the Windows Services Console to stop them both.

      See Starting and Stopping tc Runtime Instances and Starting and Stopping the AMS Server and Agents.

    4. Windows only. If you installed the AMS Agent as a Windows service, uninstall it. If you plan on upgrading your tc Runtime instances at this time, and you previously installed them as Windows services, uninstall them as well. For example, if you installed tc Server in c:\home\tcserver and you created a tc Runtime instance called myserver:

      prompt> cd c:\home\tcserver\agent-2.0.0.SR04
      prompt> ams-ctl.bat uninstall
      prompt> cd c:\home\tcserver\tcServer-6.0
      prompt> tcserver-ctl.bat myserver uninstall

      If your tc Runtime instance is located in a directory other than the main tc Server installation directory, use the INSTANCE-DIR\bin\tcserver-ctl.bat script to uninstall the instance; in this case, you do not specify the name of the instance as a parameter to the script. For example:

      prompt> cd c:\home\tcserver\instances\myserver\bin
      prompt> tcserver-ctl.bat uninstall

      See Starting and Stopping tc Runtime Instances and Starting and Stopping the AMS Server and Agents for details.

    5. Download the appropriate tc Server distribution file from the SpringSource Download Center.

      Typically, you download the Standard Edition of tc Server (managed node package) in either the compressed TAR or ZIP format:

      • springsource-tc-server-node-2.0.X.RELEASE.tar.gz
      • springsource-tc-server-node-2.0.X.RELEASE.zip

      It is assumed in the rest of this procedure that you have downloaded the managed node package of tc Server 2.0.X.

    6. Unzip all files and directories under the top-level springsource-tc-server-node directory of the distribution ZIP or TAR into your existing tc Server installation directory, such as /home/tcserver/tcServer-6.0.

      One way to execute this step is to unzip or untar the file into a temporary directory, and then copy all the files and sub-directories under the springsource-tc-server-node directory to your existing tc Server installation directory. For example, on Unix:

      prompt$ cd /home/Downloads
      prompt$ tar xvzf springsource-tc-server-node-2.0.X.RELEASE.tar.gz
      prompt$ cd springsource-tc-server-node
      prompt$ cp -r * /home/tcserver/tcServer-6.0 

      The unzipped files include new command scripts (called tcruntime-instance.sh|bat and tcruntime-ctl.sh|bat); the unzipped directories include tomcat-6.0.X.X-X, tijars, hyperic-hq-agent-4.2.X.X-EE, and templates.

      Scripts and directories

      When the unzip (or copy) completes, you should have a new subdirectory called tomcat-6.0.X.X-X (such as tomcat-6.0.25.A-RELEASE) alongside any existing tomcat-6.0.X.X-X subdirectories of your existing main tc Server directory (in our example /home/tcserver/tcServer-6.0.)

      Installing the managed node of tc Server 2.0.X in this way overwrites some of the existing JAR files in the tijars directory. This is by design. The boot.rc.template file is also overwritten with a new version of the template that references the new control script (tcruntime-ctl.sh). No other existing files or directories are overwritten.

      The new command scripts to create and control tc Runtime instances are called tcruntime-instance.sh|bat and tcruntime-ctl.sh|bat. These scripts replace the old scripts (called tcserver-instance.sh|bat and tcserver-ctl.sh|bat) which have been deprecated as of release 2.0.0 of tc Server.

      After you upgrade existing tc Runtime instances to the latest version (as described further on in this procedure), you must stop using the old tcserver-ctl.sh|bat scripts to start and stop the instances, and instead use the new tcruntime-ctl.sh|bat scripts. They work in the same way as the old ones, except for the different names. If, however, you do not upgrade your tc Runtime instances to the latest version, then continue using the tcserver-ctl.sh|bat scripts to start and stop the instance as before. SpringSource recommends that you upgrade your tc Runtime instances to the latest version so you can start using the new features and take advantage of any security fixes.

      After unzipping the managed node distribution, you will also have the new HQ Agent (preconfigured with the tc Server HQ plug-in) in your existing tc Server installation directory. If, following our example, your original tc Server install directory was /home/tcserver/tcServer-6.0, then the new HQ Agent is in the following directory:

      /home/tcserver/tcServer-6.0/hyperic-hq-agent-4.2.X.X-EE

    7. Start the new HQ Agent using the bin/hq-agent.sh start command. Henceforth, use this new HQ Agent and not the old AMS Agent. Following our example on Unix:

      prompt$ cd /home/tcserver/tcServer-6.0/hyperic-hq-agent-4.2.X.X-EE/bin
      prompt$ ./hq-agent.sh start
      [Note]Note

      The first time you start the new HQ Agent, the script requests information about the HQ Server to which it will communicate; specify the HQ Server you installed in the preceding subtask, which contains selected information from your old AMS Server. This is a one-time event and subsequent starts of the agent do not require this input. See the table in the Configuring Agent Startup Settings Interactively section of the Hyperic documentation for information about these prompts.

      See Starting and Stopping the HQ Server and Agents for details and Windows instructions for installing the agent as a service.

    8. Upgrading tc Runtime instances. The remainder of this procedure describes how to upgrade the version of your existing tc Runtime instances so that they use the latest tc Runtime as their core, such as 6.0.25.A-RELEASE.

      From your terminal (Unix) or command window (Windows), change to the tcServer-6.0 subdirectory of your existing tc Server installation directory, such as /home/tcserver/tcServer-6.0:

      prompt$ cd /home/tcserver/tcServer6.0
    9. For each existing tc Runtime instance you want to upgrade, run the following command:

      prompt$ ./tcruntime-instance.sh -s instance -n instanceDir -m 

      where:

      • instance refers to the name of the subdirectory that contains the tc Runtime instance you want to upgrade
      • instanceDir refers to the full or relative pathname of the directory in which the instance lives. You do not have to specify this option if your instance directory is in the main tc Server installation directory, such as /home/tcserver/tcServer-6.0/myserver .

      Because you do not specify a specific tc Runtime version, the tcruntime-instance.sh|bat script upgrades the instance to the latest version it can find.

      For example, to upgrade the tc Runtime instance myserver (whose instance directory is in the main tc Server installation directory) to the latest tc Runtime version::

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

      On Windows:

      prompt> tcruntime-instance.bat -s myserver -m 

      If the upgrade succeeds, you should see:

      Modifying existing instance "myserver" to tomcat-6.0.25.A-RELEASE
      ...deleted lines...
      Done.

      If you want to pin the instance to a specific version, specify the -v parameter, such as:

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

      See Pinning a tc Runtime Instance to a Specific Version for more information about pinning.

      In the preceding examples, the myserver instance directory is assumed to be in the main tc Server installation, such as /home/tcserver/tcServer-6.0. If it is in a different directory, such as /home/tcserver/instances/myserver, then run the following command:

      prompt$ ./tcruntime-instance.sh -s myserver -n /home/tcserver/instances -m 
    10. Start the upgraded instances as described in Starting and Stopping tc Runtime Instances. The startup messages should indicate that the instance is now using version 6.0.25.A of Apache Tomcat as its core. For example:

      prompt$ cd /home/tcserver/tcServer-6.0
      prompt$ ./tcruntime-ctl.sh myserver start
      INFO Instance name:      myserver
      INFO Script directory:   /home/tcserver/tcServer-6.0
      INFO Instance base:      /home/tcserver/tcServer-6.0
      INFO Binary dir:         /home/tcserver/tcServer-6.0/tomcat-6.0.25.A-RELEASE
      INFO Runtime version:    6.0.25.A-RELEASE
      INFO Script version:     6.0.25.A-RELEASE
      Using CATALINA_BASE:   /home/tcserver/tcServer-6.0/myserver
      Using CATALINA_HOME:   /home/tcserver/tcServer-6.0/tomcat-6.0.25.A-RELEASE
      Using CATALINA_TMPDIR: /home/tcserver/tcServer-6.0/myserver/temp
      Using JRE_HOME:        /home/java/jdk1.6.0_18
      Using CLASSPATH:       /home/tcserver/tcServer-6.0/tomcat-6.0.25.A-RELEASE/bin/bootstrap.jar

      If your tc Runtime instance is located in a directory other than the main tc Server installation directory, use the INSTANCE-DIR/bin/tcruntime-ctl.sh script to start the instance; in this case, you do not specify the name of the instance as a parameter to the script. For example:

      prompt$ cd /home/tcserver/instances/myserver/bin
      prompt$ ./tcruntime-ctl.sh start

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

Post-Upgrade Requirements

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]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:

8.4 Upgrading an Existing 4.2, 4.3 or 4.4 Hyperic HQ Installation to Manage tc Runtime Instances

This section describes how to upgrade an existing 4.2, 4.3, or 4.4 HQ Installation (HQ Server and Agents) so it can manage tc Runtime instances. The section applies to users who have previously installed a version of HQ Server that does not include the tc Server HQ plug-in, but now want to upgrade their server so it can manage tc Runtime instances.

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.

Understanding the Hyperic HQ Upgrade Process

The procedure consists of the following high-level tasks:

  • If you are upgrading an existing 4.2 HQ installation, you must ensure that it is at the minimum patch level required by tc Server (4.2.0.7); if it is not, upgrade HQ to this patch level, or to 4.3 or 4.4. The upgrade works with any version of 4.3 or 4.4.

  • Install the tc Server HQ plug-in on the HQ Server.

  • Either push the tc Server HQ plug-in bundle to all HQ Agents, or install the agent-side tc Server HQ plug-in into all HQ Agents. Both methods of updating the HQ Agents with the tc Server HQ plug-in are supported.

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.

Hyperic HQ Upgrade Procedure

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

  1. Stop the HQ Server and all HQ Agents. For example:

    prompt$ cd /home/hyperic/server-4.3.0.1-EE/bin
    prompt$ ./hq-server.sh stop
    prompt$ cd /home/hyperic/agent-4.3.0.1-EE/bin
    prompt$ ./hq-agent.sh stop

    On Windows, if you installed the HQ Server and Agents as Windows services, use the Windows Services Console to stop them.

    For more information, see Controlling the HQ Server and Agents.

  2. Windows only. If you installed the HQ Server and Agents as Windows services, you should remove (uninstall) them. For example:

    prompt> cd c:\home\hyperic\server-4.3.0.1-EE\bin
    prompt> hq-server.exe -u
    prompt> cd c:\home\hyperic\agent-4.3.0.1-EE\bin
    prompt> hq-agent.bat remove

    For more information, see Installing the HQ Server and Agents as Windows Services.

  3. If you are upgrading a 4.2 HQ installation, and your HQ Server and Agents are not at version 4.2.0.7 at a minimum, upgrade both server and all agents to this patch level, or to a version 4.3 or 4.4.

    Download both the HQ Server and HQ Agent packages from the Hyperic download site: Download Hyperic Systems Management Software. Then follow the upgrade instructions in the Upgrade HQ Components documentation to upgrade your existing 4.2 HQ Server and all agents.

    This step does not apply if your existing HQ installation is at version 4.3 or 4.4.

  4. To apply the server-side tc Server HQ plug-in to your existing HQ Server:

    1. Download the server-side tc Server HQ plug-in ZIP file from the SpringSource Download Center. The name of this file is:

      springsource-tc-server-hq-plugin-server-2.0.X.RELEASE.zip

    2. If you have previously installed the tc Server HQ plug-in into this HQ Server, delete the following files and directories from the old version of the plug-in:

      • HQ-SERVER-INSTALL-DIR/hq-engine/server/default/deploy/hq.ear/hq.war/hqu/tcserverclient
      • HQ-SERVER-INSTALL-DIR/hq-engine/server/default/deploy/hq.ear/hq.war/hqu/tomcatappmgmt
      • HQ-SERVER-INSTALL-DIR/hq-engine/server/default/deploy/hq.ear/hq.war/hqu/tomcatserverconfig
      • HQ-SERVER-INSTALL-DIR/hq-engine/server/default/deploy/tomcatserverconfig.war

      where HQ-SERVER-INSTALL-DIR refers to the main HQ Server installation directory, such as /home/hyperic/server-4.3.0.1-EE.

      For example:

      prompt$ cd /home/hyperic/server-4.3.0.1-EE
      prompt$ rm -r hq-engine/server/default/deploy/hq.ear/hq.war/hqu/tcserverclient
      prompt$ rm -r hq-engine/server/default/deploy/hq.ear/hq.war/hqu/tomcatappmgmt
      prompt$ rm -r hq-engine/server/default/deploy/hq.ear/hq.war/hqu/tomcatserverconfig
      prompt$ rm -r hq-engine/server/default/deploy/tomcatserverconfig.war
    3. Unzip the contents of the ZIP file into the HQ-SERVER-INSTALL-DIR/hq-engine/server/default/deploy directory, where HQ-SERVER-INSTALL-DIR refers to the main HQ Server installation directory, such as /home/hyperic/server-4.3.0.1-EE.

      For example, if you downloaded the ZIP file into the /home/Downloads directory:

      prompt$ cd /home/hyperic/server-4.3.0.1-EE/hq-engine/server/default/deploy
      prompt$ unzip /home/Downloads/springsource-tc-server-hq-plugin-server-2.0.X.RELEASE.zip
    4. Using your favorite text editor, open the HQ-SERVER-INSTALL-DIR/conf/hq-server.conf file and add the -Dorg.apache.catalina.STRICT_SERVLET_COMPLIANCE=false parameter to the parameters that already exist for the server.java.opts property. For example:

      server.java.opts=-XX:MaxPermSize=192m -Xmx512m -Xms512m -XX:+HeapDumpOnOutOfMemoryError -Dorg.apache.catalina.STRICT_SERVLET_COMPLIANCE=false

      This parameter ensures that you can properly deploy WAR files using the upload mechanism of the Hyperic user interface.

  5. To install the agent-side tc Server HQ plug-in to your existing HQ Agent(s), you can either push the tc Server HQ plug-in from the HQ server or install it by downloading and unzipping the agent-side tc Server HQ plug-in ZIP file:

    1. Download the agent-side tc Server HQ plug-in ZIP file from the SpringSource Download Center. The name of this file is:

      springsource-tc-server-hq-plugin-agent-2.0.X.RELEASE.zip

    2. If you have previously installed the tc Server HQ plug-in into this HQ Agent, delete the old version of the plug-in file (HQ-AGENT-INSTALL-DIR/bundles/agent-version/pdk/plugins/springsource-tcserver-plugin.jar), where HQ-AGENT-INSTALL-DIR refers to the main HQ Agent installation directory, such as /home/hyperic/agent-4.3.0.1-EE, and version refers to the HQ Agent version number, such as 4.3.0.1-EE-1234.

      For example:

      prompt$ cd /home/hyperic/agent-4.3.0.1-EE/bundles/agent-4.3.0.1-EE-1234
      prompt$ rm pdk/plugins/springsource-tcserver-plugin.jar
    3. Unzip the contents of the ZIP file into the HQ-AGENT-INSTALL-DIR/bundles/agent-version directory, where HQ-AGENT-INSTALL-DIR refers to the main HQ Agent installation directory, such as /home/hyperic/agent-4.3.0.1-EE, and version refers to the HQ Agent version number, such as 4.3.0.1-EE-1234.

      For example, if you downloaded the ZIP file into the /home/Downloads directory:

      prompt$ cd /home/hyperic/agent-4.3.0.1-EE/bundles/agent-4.3.0.1-EE-1234
      prompt$ unzip /home/Downloads/springsource-tc-server-hq-plugin-agent-2.0.X.RELEASE.zip
  6. Start the HQ Server and all HQ Agents. For example, assuming you are using version 4.3.0.1 of HQ:

    prompt$ cd /home/hyperic/server-4.3.0.1-EE/bin
    prompt$ ./hq-server.sh start
    prompt$ cd /home/hyperic/agent-4.3.0.1-EE/bin
    prompt$ ./hq-agent.sh start

    For more information, see Controlling the HQ Server and Agents.

    If you are on Windows and you want to install the HQ Server and Agents as Windows services, see Installing the HQ Server and Agents as Windows Services.

Post-Upgrade Notes

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.

8.5 Upgrading Only the tc Runtime Version

This section is for users who want to upgrade the version of tc Runtime in their tc Server installation, but do not want to upgrade the management components (HQ Server and Agents). The procedure first describes how to install a new version of the tomcat-XXX directory in the main tc Server directory and then how to upgrade each of your tc Runtime instances so they use the new version of the runtime.

Important: It is assumed in the procedure below that you are using version 2.0.X of tc Server. It is further assumed that you installed the Standard Edition of tc Server (Managed Node package). If you are using version 6.0.X of tc Server, then see the 6.0 version of the Getting Started with tc Server; click in the Upgrade and Migration Guide in the left frame.

  1. Shut down all currently running tc Runtime instances. For example, if you installed the Standard Edition of tc Server (managed node package) in /home/tcserver:

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

    See Starting and Stopping tc Runtime Instances.

  2. Download the Developer Edition package of tc Server that contains the version of tc Runtime to which you want to upgrade. Download from either the SpringSource Download Center or the Customer Support Portal.

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

    • springsource-tc-server-developer-2.0.X.X.zip
    • springsource-tc-server-developer-2.0.X.X.tar.gz
  3. Unzip or untar all files and directories under the top-level springsource-tc-server-developer directory of the distribution ZIP or TAR into your existing tc Server installation directory, such as /home/tcserver/springsource-tc-server-node.

    One way to execute this step is to unzip or untar the file into a temporary directory, and then copy all the files and sub-directories under the springsource-tc-server-developer directory to your existing tc Server installation directory. For example, on Unix (and assuming that you downloaded the latest Developer Edition package into /home/Downloads):

    prompt$ cd /home/Downloads
    prompt$ tar xvzf springsource-tc-server-developer-2.0.0.SR01.tar.gz
    prompt$ cd springsource-tc-server-developer
    prompt$ cp -r * /home/tcserver/springsource-tc-server-node 

    When the unzip (or copy) completes, you should have a new subdirectory called tomcat-6.0.X.X-X (such as tomcat-6.0.25.A-RELEASE) alongside any existing tomcat-6.0.X.X-X subdirectories of your existing main tc Server directory (in our example /home/tcserver/springsource-tc-server-node.) The unzip (or copy) also overwrites the tcruntime-XXX.sh|bat files, as well as some files in the tijars and templates directories; this is by design.

  4. For each tc Runtime instance you want to upgrade, run the following command:

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

    where instance-name refers to the name of the sub-directory that contains the tc Runtime instance you want to upgrade. The preceding command upgrades the instance so that it will always use the most recent version of the runtime; this means the instance is unpinned. If you want to pin the instance to a specific version of tc Runtime, specify the version with the -v parameter.

    For example, if you want to upgrade the tc Runtime instance myserver so that it always uses the latest installed version of tc Runtime, run the following command:

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

    You should see something similar to the following message:

    Modifying existing instance "myserver" to tomcat-6.0.25.A-RELEASE ...
    Done.

    To pin the tc Runtime instance myserver to version 6.0.26.A-RELEASE, for example, run the following command:

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

    In the preceding example, it is assumed that you have already installed version 6.0.25.A-RELEASE of the tc Runtime. See Pinning tc Runtime Instances to a Specific Version for more information about pinning.

    .
  5. Start the instance as described in Starting and Stopping tc Runtime Instances. The startup messages should indicate that the instance is now using the new version of tc Runtime. The messages should look similar to the following:

    prompt$ ./tcruntime-ctl.sh myserver start
    INFO Instance name:      myserver
    INFO Script directory:   /home/tcserver/springsource-tc-server-node
    INFO Instance base:      /home/tcserver/springsource-tc-server-node
    INFO Binary dir:         /home/tcserver/springsource-tc-server-node/tomcat-6.0.26.A-RELEASE
    INFO Runtime version:    6.0.26.A-RELEASE
    INFO Script version:     6.0.26.A-RELEASE
    Using CATALINA_BASE:   /home/tcserver/springsource-tc-server-node/myserver
    Using CATALINA_HOME:   /home/tcserver/springsource-tc-server-node/tomcat-6.0.26.A-RELEASE
    Using CATALINA_TMPDIR: /home/tcserver/springsource-tc-server-node/myserver/temp
    Using JRE_HOME:        /home/java/jdk1.6.0_18
    Using CLASSPATH:       /home/tcserver/springsource-tc-server-node/tomcat-6.0.26.A-RELEASE/bin/bootstrap.jar

8.6 Upgrading Only the Server-Side tc Server HQ Plug-in

You might sometimes need to upgrade only the tc Server HQ plug-in (rather than the entire HQ Server) to, for example, fix a security vulnerability that affects only the plug-in and not the rest of the HQ Server. This section describes how you perform an upgrade of only the server-side tc Server HQ plug-in.

  1. Open a terminal (Unix) or command window (Windows).

  2. Stop the HQ Server, if it is currently running. For example, if you installed the HQ Server in /home/tcserver/server-4.2.0.7-EE on Unix:

    prompt$ cd /home/tcserver/server-4.2.0.7-EE/bin
    prompt$ ./hq-server.sh stop
  3. Delete the following three directories and one file that apply to the old version of the tc Server HQ plug-in:

    • HQ-SERVER-INSTALL-DIR/hq-engine/server/default/deploy/hq.ear/hq.war/hqu/tcserverclient
    • HQ-SERVER-INSTALL-DIR/hq-engine/server/default/deploy/hq.ear/hq.war/hqu/tomcatappmgmt
    • HQ-SERVER-INSTALL-DIR/hq-engine/server/default/deploy/hq.ear/hq.war/hqu/tomcatserverconfig
    • HQ-SERVER-INSTALL-DIR/hq-engine/server/default/deploy/tomcatserverconfig.war

    where HQ-SERVER-INSTALL-DIR refers to the main HQ Server installation directory, such as /home/tcserver/server-4.2.0.7-EE. For example:

    prompt$ cd /home/tcserver/server-4.2.0.7-EE
    prompt$ rm -r hq-engine/server/default/deploy/hq.ear/hq.war/hqu/tcserverclient
    prompt$ rm -r hq-engine/server/default/deploy/hq.ear/hq.war/hqu/tomcatappmgmt
    prompt$ rm -r hq-engine/server/default/deploy/hq.ear/hq.war/hqu/tomcatserverconfig
    prompt$ rm -r hq-engine/server/default/deploy/tomcatserverconfig.war 
  4. Download the tc Server HQ plug-in ZIP file from the Customer Support Portal. The file is called:

    springsource-tc-server-hq-plugin-server-2.X.X.zip

  5. Unzip the contents of the ZIP file into the HQ-SERVER-INSTALL-DIR/hq-engine/server/default/deploy directory. For example, if you downloaded the ZIP file into the /home/Downloads directory:

    prompt$ cd /home/tcserver/server-4.2.0.7-EE/hq-engine/server/default/deploy
    prompt$ unzip /home/Downloads/springsource-tc-server-hq-plugin-server-2.0.2.SR01.zip
  6. Start the HQ Server. For example, on Unix:

    prompt$ cd /home/tcserver/server-4.2.0.7-EE/bin
    prompt$ ./hq-server.sh start

8.7 Migrating an ERS Server Instance to tc Server 2.0.x

This section is for users who want to migrate an existing ERS 4.0 instance to tc Server 2.0.X. It is assumed that you have already installed version 2.0.X of tc Server; if not, see Installing tc Server.

Understanding the ERS Migration Process

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

  • You previously installed ERS 4.0 in the /opt/ers40 directory.

  • The name of the ERS instance you want to migrate is ers-instance and its directory is currently /opt/ers40/servers/ers-instance.

  • The migrated instance will continue to be named ers-instance and live in a directory of the same name, even though the instance will be using the tc Server binaries.

  • You have previously installed the Standard Edition (managed node) of tc Server 2.0.X and its main installation directory is /home/tcserver/springsource-tc-server-node.

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.

ERS Migration Procedure

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

  1. If the ERS instance you want to migrate is running, stop it.

  2. Open a terminal (Unix) or command window (Windows).

  3. Copy the existing ERS 4.0 server instance directory to the main tc Server installation directory. For example:

    prompt$ cp -r /opt/ers40/servers/ers-instance /home/tcserver/springsource-tc-server-node
  4. Unix Only: Edit the /home/tcserver/springsource-tc-server-node/ers-instance/bin/tomcat_startup.sh file (tomcat_startup.bat on Windows)) and update the following variables to point to the new tc Server directories:

    • root_dir: Points to the tc Runtime home directory. In our example, this would be /home/tcserver/springsource-tc-server-node.

    • tomcat_dir: Points to the directory that contains the Tomcat binaries. In our example, this would be $root_dir/tomcat-6.0.25.A-RELEASE.

    • server_dir: Points to the server instance directory. In our example, this would be $root_dir/$server_name; this variable value assumes that you are not changing the name of the migrated instance, which is pointed to by the $server_name variable already set in the tomcat_startup.sh script.

  5. Windows Only: Edit the /home/tcserver/springsource-tc-server-node/ers-instance/conf/wrapper.properties file and update the following variables to point to the new tc Server directories:

    • ers.home: Points to the tc Runtime home directory. In our example, this would be /home/tcserver/springsource-tc-server-node.

    • wrapper.tomcat_home: Points to the directory that contains the Tomcat binaries. In our example, this would be $(ers.home)\tomcat-6.0.25.A-RELEASE.

    • server.home: Points to the server instance directory. In our example, this would be $(ers.home)\$(server.name); this variable value assumes that you are not changing the name of the migrated instance, which is pointed to by the server.name variable, already set in the wrapper.properties file.

  6. Start the instance using the same ERS start script you have always used (tomcat_startup.sh, located in the /home/tcserver/springsource-tc-server-node/ers-instance/bin directory.) This time, however, because you have changed the values of the variables that point to the server binaries, the instance will now use tc Runtime 6.0.25.A-RELEASE binaries.

Post-Migration Notes

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.

9. Tutorial: Using HQ to Configure and Manage tc Runtime Instances

This tutorial describes the basic steps for configuring and monitoring a tc Runtime instance with the HQ user interface and for managing applications deployed to the instance.

9.1 Before You Begin

Install and start the components of tc Server (HQ Server, HQ Agent, and at least one tc Runtime instance); invoke the HQ user interface in your browser; and log in with the administration username/password (default hqadmin/hqadmin) or with HQ user permissions to configure a tc Runtime instance. To accomplish these tasks, see:

Most HQ user interface pages have a Help link at the top-right corner. On the tc Runtime configuration pages, click the icon to the right of each field to get information about the field.

For simplicity, it is assumed in this tutorial that you are going to log in to the HQ user interface as the super-user (hqadmin). If, however, you are going to log in as a non-super-user, see User Permissions Required to Use the tc Server HQ Plugin Features for information about the required HQ user permissions to be able to use all the tc Server HQ plugin features described in this tutorial.

9.2 Restart a tc Runtime Instance

In this procedure you restart a currently running tc Runtime instance. If you need navigational help for the first few steps, see Getting Started with the HQ user interface.

  1. Click the Resources > Browse link at the top of the HQ user interface

  2. Click the Servers(X) link to see the list of servers known by HQ. To limit the number of displayed servers to only tc Runtime instances, select SpringSource tc Runtime 6.0 from the Search drop-down list, then click the green arrow to the far right.

  3. In the table, click the tc Runtime instance you want to restart. The server is listed as platform-resource tc Runtime catalina-base-dir , where

    • platform-resource is the computer hosting the tc Runtime instance.
    • catalina-base-dir is the CATALINA_BASE directory of the tc Runtime instance without the leading directory pathnames, such as myserver .
  4. Click the Control tab. You use this HQ user interface page to stop, start, and restart the current tc Runtime instance, as described in the next step.

  5. In the Quick Control section of the page, select Restart from the Control Action drop-down list, then click the arrow to the right, as shown in the following graphic.

    After you click the restart button, the Command State field in the Current Status section says In progress until the tc Runtime instance is successfully restarted. The Current Status section always displays information about the last control action; in this case the restart of the tc Runtime instance.

9.3 Reconfigure a tc Runtime Instance

In this procedure you make a few simple configuration changes to the current tc Runtime instance. You change a startup-up JVM option (maximum heap size) and change the working directory of the default virtual host for the tc Runtime instance.

It is assumed in this procedure that you have already browsed to the tc Runtime instance that you want to configure, as described in Restart a tc Runtime Instance.

  1. Click the Views > Server Configuration tab:

    The server configuration pages consist of four tabs:

    • Home: Main Server Configuration page.

      There is also an Advanced group for performing more advanced tasks, such as reloading the settings from the tc Runtime instance server.xml file (in which you lose local changes made with the HQ user interface), reverting to a previous server configuration, and uploading a new server configuration using a server.xml file.

    • Configuration: Configure tc Runtime startup options, JVM options, context information for all deployed Web applications, default behavior of JSPs and static content, and so on.

    • Resources: Create and configure JDBC datasources.

    • Services: Create and configure tc Runtime services such as virtual hosts, connectors, and so on.

  2. Click the Configuration tab, then the Server Start option in the list on the left.

  3. In the General section on the right, enter 1024 in the Max Heap Size (MB) field.

  4. Click Save at the bottom of the page.

    The message Configuration saved successfully appears at the top, as shown in the following graphic. This means that HQ has updated its in-memory cache with your changes. Additionally, a box appears at the top of the page with the heading Changes have been made locally, along with two links to either write (push) the changes to the actual tc Runtime configuration files, such as CATALINA_HOME/bin/setenv.sh (in this case) or CATALINA_BASE/conf/server.xml, or to undo the changes.

    HQ displays this box until you save or undo, although you can make additional changes before you save or undo. In this tutorial, you make another change, and then write the changes to disk.

  5. Click the Services tab. In the table, click the Catalina service. This is the default service of tc Runtime.

  6. In the list on the left, click Hosts, then in the table on the right, click the localhost virtual host.

  7. In the Host Properties section, enter new_work_dir in the Work Directory field. This specifies that the localhost will use a different work directory from the default, which is CATALINA_BASE/work. Relative work directories are created under CATALINA_BASE, such as CATALINA_BASE/new_work_dir. The tc Runtime instance uses the work directory to perform its internal work.

  8. Click Save at the bottom of the page.

    The message Configuration saved successfully appears in the top.

    [Note]Note

    When you update the tc Runtime configuration using the HQ user interface, if the property you are updating was previously specified as a variable (such as ${jmx.port}), tc Runtime replaces that variable with the actual value in the server.xml file. This means, for example, that port="${jmx.port}" would become port="6954". The variable is still set in the catalina.properties file to the old value, but the tc Runtime does not actually use it because the property is now hardcoded in the server.xml file.

  9. In the box at the top titled Changes have been made locally, click Push configuration changes to Tomcat.

  10. Click Push Changes to Server.

  11. In the box at the top, click the restarted link to restart the tc Runtime instance so that the changes take effect.

  12. Click Restart Server.

    The message Server Restarted appears at the top.

9.4 Deploy a Web Application to a tc Server Runtime Instance

In this procedure you deploy a new Web application to a tc Runtime instance, then stop and start it. It is assumed that you already have a Web application WAR file to deploy. If you do not, see Tutorial: Very Simple Web Application Development for a tutorial that shows you how to create a very simple HelloWorld Web application and package it into a WAR file.

It is also assumed that you have already browsed to the tc Runtime instance to which you want to deploy, as described in Restart a tc Runtime Instance.

  1. Click the Views > Application Management tab. You use this page to deploy and manage tc Runtime applications.

  2. If the Web application you want to deploy is physically located on the same computer from which you are running your browser, go to the Deploy Application from Local Machine section. If the Web application is actually located on the computer on which the tc Runtime instance is running, then go to the Deploy Application from Server Machine section. If you are running your browser on the same computer as tc Runtime, then you can go to either section. A typical remote machine use case is machines that use network mounted drives to which they have access.

    Enter the location of the Web application in the corresponding field. Use the Browse button to find a local Web application WAR file; you must already know the full pathname of the WAR file if you are deploying it from the tc Runtime computer. If you are deploying from a remote machine, your local machine must have access to the remote directory that contains the Web application file.

    The following graphic shows deploying from a local computer

  3. Enter hello in the Context path field.

    Optionally, check the Use cold deployment strategy if you want the tc Runtime instance to shutdown, deploy the application, and then start up again. By default (if box is unchecked), the tc Runtime instance hot-deploys the application, which means it does not shutdown then restart but simply deploys the application while the instance is still running. Use the cold deployment strategy if you want to avoid common hot deployment errors, such as running out of PermGen space. The PermGen space holds the metadata about classes that have been loaded/created in the JVM.

  4. Click Upload and deploy (for a local WAR file) or Deploy (for deploying a WAR file on the tc Runtime computer). HQ deploys the WAR file to the current tc Runtime instance. You should see the Web application listed in the Deployed Applications table.

  5. You can start, stop, reload, and undeploy a deployed Web application by selecting it in the Deployed Applications table and clicking the corresponding button.

To invoke the Web application you just deployed, enter the following URL in a browser:

http://host:port/hello

where:

  • host is the name of the computer on which the tc Runtime instance is running. If it is the same computer as your browser, you can enter localhost.

  • port is the TCP/IP port to which the tc Runtime instance listens. The default value is 8080.

For example:

http://localhost:8080/hello

You can get the host and port information of a tc Runtime instance by looking at its HTTP connector configuration from the Views > Server Configuration > Services tab.

9.5 Add tc Runtime Instances to the Favorite Resources Portlet

The main HQ dashboard includes a Favorite Resources portlet that lists the resources you most often manage. When you first install HQ, the portlet is empty. However, as you manage a particular resource, you might decide that you want to add it to your favorites portlet because you return to it frequently. In this procedure you add a tc Runtime instance to the Favorite Resources portlet.

  1. Navigate to the tc Runtime instance, as described in the first three steps of Restart a tc Runtime Instance.

  2. Click the Tools Menu in the top-left corner and choose Add to Dashboard Favorites.

  3. In the box, click the name of the user for whose dashboard the tc Runtime instance will show up as a favorite. Following our tutorial, click hqadmin, although if you logged in as another user you can enter that one.

  4. Click Add.

  5. The tc Runtime instance is displayed in the Favorite Resources portlet on the main dashboard:

9.6 Create an HQ Group of Multiple tc Runtime Instances

In this procedure you create an HQ group of multiple tc Runtime instances. You can then deploy a Web application to the group in a procedure similar to Deploy a Web Application to a tc Server Runtime Instance, and HQ does the work of deploying the Web application to each member of the group. Similarly, you can stop, start, and restart all the servers in the group with a procedure similar to Restart a tc Runtime Instance.

Using HQ groups saves a lot of time if you need to control multiple tc Runtime instances running on many different computers, as well as deploy and manage their applications.

It is assumed in this procedure that you have at least two tc Runtime instances running and that you have added them to the HQ inventory. See Creating a New tc Runtime Instance and Getting Started with the HQ User Interface.

[Tip]Tip

It might take a while for the HQ user interface to auto-detect a new tc Runtime instance after you start it. You can force a new auto-discovery to speed the process.

To force an auto-discovery, browse to the platform resource where you started the new tc Runtime instance. For example, in this tutorial the platform resource is called juliet-desktop. Then click New Auto-Discovery in the Tools Menu. In the Quick Auto-Discovery Scan section, click OK. The new tc Runtime instance should show up in the Auto-Disocvery portlet of the main Dashboard very shortly. You can then add it using the Add to Inventory button as usual.

  1. Click the Resources > Browse link at the top of the HQ user interface.

  2. Click the Servers (X) link to list all the servers in your resource inventory. The tc Runtime instances are listed as Server Type SpringSource tc Runtime 6.0.

  3. For each tc Runtime instance you want to include in the new group, check the box to the left of the instance's entry in the table.

  4. Click Group.

    The following graphic shows how to group together two tc Runtime instances called tc Runtime anotherserver and tc Runtime myserver.

  5. In the Group Manager window, click Add to New Group.

  6. In the General Properties section, enter a name for the group, such as tcserverGroup and an optional description and location, such as San Francisco.

  7. Click OK.

    Depending on the members of the group, HQ creates a Compatible Group/Cluster or Mixed Group. The first type of group consists of a single type of server, such as only tc Runtime instances. The second mixed group consists of different types of servers, such as both tc Runtime instances and Apache Tomcat servers.

To stop or restart the group of servers, and deploy an application to the group:

  1. Click Resources > Browse at the top of the HQ user interface.

  2. Click Compatible Groups/Clusters if your group consists of the same servers, or Mixed Groups if your group consists of different types of servers.

  3. In the table, click on the name of the group.

  4. To stop or start all the servers in the group, click the Control tab, then follow the steps for controlling a single server, as described in Restart a tc Runtime Instance. The breadcrumbs at the top of the console page list the group name (tcserverGroup in this case) rather than the tc Runtime instance name.

  5. To deploy and manage applications on all servers in the group, click the Views > Application Management tab, then follow the steps for deploying or managing the applications of a single server, as described in Deploy a Web Application to a tc Server Instance.

[Note]Note

In this release of tc Server, you cannot update the configuration of a group of tc Runtime instances from the Views > Server Configuration tab.

9.7 Monitoring tc Runtime Instances

As soon as you add a resource (such as a tc Runtime instance) to the HQ inventory, HQ begins collecting a variety of metrics about the resource that you can use to monitor its state and health. HQ displays the values of the metrics over a specified period of time using indicator charts or tables.

Examples of the types of metrics that HQ collects about tc Runtime include:

  • Number of thread deadlocks detected.

  • Size of the free heap memory.

  • JSP count per minute.

  • Number of servlet requests per minute.

The following procedure describes how to view the monitoring metrics for a tc Runtime instance.

  1. Navigate to the tc Runtime instance, as described in the first three steps of Restarting the tc Runtime Instance.

  2. Click the Monitor tab.

    The charts under the Indicator tab show data about the entire tc Runtime instance, such as thread deadlocks detected and size of the free heap memory and the tc Runtime instance up time. Click the Metric Data tab to see the same information in tabular form.

    The Services table to the left lists the services associated with the tc Runtime instance, such as the JSP and servlet monitors.

  3. In the Services table, click SpringSource tc Runtime Servlet Monitor. The chart on the right shows usage metrics about the servlets deployed to the tc Runtime instance.

  4. Click on other services within the Monitoring tab to view more monitoring information for the tc Runtime instance.

You can create an alert for a resource that fires when a specified condition is met, and optionally specify a control action that occurs when the alert is fired. HQ is preconfigured for a deadlock detection alert; see Manage the Preconfigured Deadlock Detected Alert to modify it.

9.8 Manage the Preconfigured Deadlock Detected Alert

HQ includes a preconfigured alert that triggers once if the Deadlocks Detected metric exceeds 0. HQ applies this alert to all auto-discovered tc Runtime instances, enables it by default, and then checks the metric every two minutes to see if the condition has been met. After triggering, HQ disables the alert until an administrator marks it as Fixed.

The following procedure describes how to view this preconfigured alert, modify it so that HQ automatically restarts the tc Runtime instance in which the alert is triggered, and then disable it.

  1. Navigate to the tc Runtime instance, as described in the first three steps of Restart a tc Runtime Instance.

  2. Click the Alert tab at the top of the page.

  3. Click the Configure button. A page is displayed with a table of alerts that have been defined for this tc Runtime instance. You should see the preconfigured Deadlocks Detected alert; by default it is active (enabled.)

  4. In the table, click Deadlocks Detected to display the Alert Definition page.

  5. Click the Control Action tab at the bottom of the page, and then click the EDIT... button.

  6. Select restart from the Control Type drop-down list.

  7. Click OK.

    You have modified the alert so that HQ automatically restarts the affected tc Runtime instance when HQ detects a thread deadlock.

  8. To disable the alert:

    1. Return to the page that contains the Alert Definitions table by clicking the Return to Alert Definitions link at the top left corner of the page.

    2. In the table, select the Deadlocks Detected alert by checking the box to the left of its name.

    3. At the bottom of the table, choose No in the Set Active drop-down list.

    4. Click the arrow to the right of the drop-down list. The Active column for the Deadlocks Detected alert changes to No.

10. Tutorial: Very Simple Helloworld Web Application

This tutorial is for beginning programmers who want to know the minimal basic information on how to create servlets and JSPs, package them into a deployable WAR file, deploy the application to a tc Runtime instance, and run the application in a browser. The tutorial uses Ant as its build framework. You can also use an IDE, such as SpringSource Tool Suite, to create the application. The tutorial shows you how to create each artifact, from the servlet source to the Ant build.xml file, from scratch.

10.1 Before You Begin

Install SpringSource tc Server and Ant. See Installing tc Server and Apache Ant Project.

10.2 Creating and Deploying the Helloworld Web Application

To create a Web application and deploy it to a tc Runtime instance:

  1. When you install Ant, add or update the following environment variables:

    • ANT_HOME: Set this variable to the location where you installed Ant, such as /usr/local/ant/apache-ant-1.7.1.

    • PATH: Update your PATH variable to include ANT_HOME/bin.

  2. Set your JAVA_HOME environment variable to the directory where your JDK is installed.

  3. Create the project directory structure that will contain the HelloWorld Web application source files.

    Create the top-level directory called helloworld. You can create the helloworld directory in any location on your computer that you have permission to update. The helloworld directory will contain the Ant build file (build.xml).

    Create two sub-directories of the helloworld directory: src that will contain the Java source file for the HelloWorld servlet and web that will contain the JSP file, static HTML file, images, and deployment descriptor.

    In the src directory, create an examples sub-directory. This directory corresponds to the package that contains the HelloWorld servlet

    In the web directory, create two subdirectories: images, which will contain any images used by the Web application, and WEB-INF, which is the standard directory that contains the Web application deployment descriptor files.

    The following graphic describes this simple project directory hierarchy:

    Figure 10.1. Directory Hierarchy of the HelloWorld Application

    Directory Hierarchy of the HelloWorld Application


  4. Create the Hello.java servlet Java source file and put it in the helloworld/src/examples directory.

    For sample Java code that you can copy and paste into your own Java file and a brief explanation of how to program a simple servlet, see Hello.java .

  5. Create the hello.jsp JSP file and put it in the helloworld/web directory.

    For sample JSP code that you can copy and paste into your own JSP file and a brief explanation of how to program a simple JSP, see hello.jsp .

  6. Create the web.xml Web application deployment descriptor and put it in the helloworld/web/WEB-INF directory.

    For sample XML that you can copy and paste into your own web.xml file and a brief explanation of the elements, see web.xml .

  7. Create the default index.html page and put it in the helloworld/web directory.

    For a sample HTML file that you can copy and paste into your own file, see index.html .

  8. Create the Ant build file (build.xml) that includes targets for compiling and packaging the Web application and put it in the helloworld directory.

    For a sample Ant build file that you can copy and paste into your own file, see build.xml .

  9. In your own build file, update the tcserver.home property to fit your environment; it should point to the CATALINA_HOME of your tc Runtime installation. For example, if you installed tc Server in the /home/tcServer directory, set the tcserver.home property in the build.xml file to something like the following:

    <property name="tcserver.home" value="/home/tcServer/springsource-tc-server-node/tomcat-6.0.25.A-RELEASE" />
  10. Right-click the following image and save it with name springsource.png to the helloworld/web/images directory.

    When you finish creating all the artifacts that make up the HelloWorld Web application, your directory structure and contents should look like the following:

    helloworld
    helloworld/build.xml
    helloworld/src
    helloworld/src/examples
    helloworld/src/examples/Hello.java
    helloworld/web
    helloworld/web/hello.jsp
    helloworld/web/images
    helloworld/web/images/springsource.png
    helloworld/web/index.html
    helloworld/web/WEB-INF
    helloworld/web/WEB-INF/web.xml 
  11. Compile and package the Helloworld Web application by opening a command window, changing to the helloworld directory, and executing the following command:

    prompt> ant all

    This ant command creates a deployable WAR file of the Helloworld application called hello.war in the helloworld/dist directory. You will see the following output from the ant command if it completes successfully:

    Buildfile: build.xml
    
    clean:
    
    prepare:
        [mkdir] Created dir: /home/samples/helloworld/dist
        [mkdir] Created dir: /home/samples/helloworld/work/WEB-INF/classes
         [copy] Copying 4 files to /home/samples/helloworld/work
    
    compile:
        [javac] Compiling 1 source file to /home/samples/helloworld/work/WEB-INF/classes
    
    dist:
          [jar] Building jar: /home/samples/helloworld/dist/hello.war
    
    all:
    
    BUILD SUCCESSFUL
    Total time: 2 seconds
  12. Start a tc Runtime instance. See Starting and Stopping tc Runtime Instances.

  13. Deploy the Web application JAR file to the tc Runtime instance. See Deploying Applications to tc Runtime Instances.

  14. Invoke the HelloWorld Web application in your browser :

    http://host:port/hello

    where:

    • host is the name of the computer that is hosting the tc Runtime instance. If it is the same as the computer hosting your browser, you can use localhost.

    • port is the port to which the tc Runtime instance listens. The default value is 8080.

    In the example, /hello is the default URL context of the Web application, which in this example is simply the name of the WAR package without the trailing .war file extension.

    For example:

    http://localhost:8080/hello

10.3 Java Source of the Hello.java Servlet

The following Java source file shows the code for the Hello.java servlet; see Description of the Hello Servlet for information about the relevant parts of the code sample.

package examples;

import java.io.IOException;
import java.io.PrintWriter;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;


/**
 * Simple Hello servlet.
 */

public final class Hello extends HttpServlet {


    /**
     * Respond to a GET request for the content produced by
     * this servlet.
     *
     * @param request The servlet request we are processing
     * @param response The servlet response we are producing
     *
     * @exception IOException if an input/output error occurs
     * @exception ServletException if a servlet error occurs
     */
    public void doGet(HttpServletRequest request,
                      HttpServletResponse response)
      throws IOException, ServletException {

        response.setContentType("text/html");
        PrintWriter writer = response.getWriter();        
        writer.println("<html>");
        writer.println("<head>");
        writer.println("<title>Sample Application Servlet Page</title>");
        writer.println("</head>");
        writer.println("<body bgcolor=white>");

        writer.println("<table border=\"0\" cellpadding=\"10\">");
        writer.println("<tr>");
        writer.println("<td>");
        writer.println("<img src=\"images/springsource.png\">");
        writer.println("</td>");
        writer.println("<td>");
        writer.println("<h1>Sample Application Servlet</h1>");
        writer.println("</td>");
        writer.println("</tr>");
        writer.println("</table>");

        writer.println("This is the output of a servlet that is part of");
        writer.println("the Hello, World application.");

        writer.println("</body>");
        writer.println("</html>");
    }
} 

Description of the Hello Servlet

In the preceding code:

  • The Hello class extends the javax.servlet.http.HttpServlet abstract class. This abstract class provides a framework for handling the HTTP protocol. When extending the HttpServlet abstract class, a programmer must override at least one method, depending on the type of requests the servlet supports, such as HTTP GET, HTTP POST, and so on.

  • The Hello servlet overrides the doGet method because it supports HTTP GET. The parameters of the method are the HTTP request and response.

  • The response.setContentType method tells the receiver of the response (such as a browser) that the response type is text/html, or simple HTML.

  • The response.getWriter method returns a PrintWriter object used to send character text to the client, in this case a browser. The writer.println lines simply build an HTML file that will be rendered by the browser that invokes the servlet.

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

10.4 JSP Source for the hello.jsp JSP

The following source shows the JSP code for the hello.jsp JSP; see Description of the hello.jsp for additional information.

  <html>
  <head>
    <title>Sample Application JSP Page</title>
  </head>

  <body bgcolor=white>

  <table border="0" cellpadding="10">
    <tr>
      <td align=center>
        <img src="images/springsource.png">
      </td>
      <td>
         <h1>Sample Application JSP Page</h1>
      </td>
    </tr>
  </table>

  <br />
  <p>This is the output of a JSP page that is part of the HelloWorld application.</p>

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

  </body>
</html> 

Description of the hello.jsp

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.

10.5 Sample web.xml File

The following sample web.xml deployment descriptor shows how to declare the HelloServlet servlet in the Helloworld Web application. See also Description of the web.xml File.

<?xml version="1.0" encoding="ISO-8859-1" ?>

<web-app xmlns="http://java.sun.com/xml/ns/j2ee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
    version="2.4">

    <display-name>HelloWorld Application</display-name>
    <description>
        This is a simple web application with a source code organization
        based on the recommendations of the Application Developer's Guide.
    </description>

    <servlet>
        <servlet-name>HelloServlet</servlet-name>
        <servlet-class>examples.Hello</servlet-class>
    </servlet>

    <servlet-mapping>
        <servlet-name>HelloServlet</servlet-name>
        <url-pattern>/hello</url-pattern>
    </servlet-mapping>

</web-app>     

Description of the web.xml File

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.

10.6 Sample Default index.html File

The following sample index.html file is the default HTML file that appears in a browser when a user invokes the Helloworld Web application. The index.html file in turn invokes both the hello.jsp JSP and HelloServlet servlet.

The index.html file invokes the JSP by simply linking to its name (hello.jsp). The HTML file invokes the servlet by linking to its URL pattern (/hello).

<html>
  <head>
    <title>Sample "Hello, World" Application</title>
  </head>
  <body bgcolor=white>

    <table border="0" cellpadding="10">
      <tr>
        <td>
          <img src="images/springsource.png">
        </td>
        <td>
          <h1>Sample "Hello, World" Application</h1>
        </td>
      </tr>
    </table>

    <p>This is the home page for the HelloWorld Web application. </p>
    <p>To prove that they work, you can execute either of the following links:
    <ul>
      <li>To a <a href="hello.jsp">JSP page</a>.
      <li>To a <a href="hello">servlet</a>.
    </ul>

  </body>
</html>

10.7 Ant Build File to Compile and Package the Example

The following sample Ant build.xml file compiles the servlet code and packages all the Web application artifacts into a deployable WAR file; see Description of the build.xml File for additional information.

<project name="My Project" default="help" basedir=".">
  <!-- Define the properties used by the build -->
  <property name="app.name"      value="hello"/>
  <property name="tcserver.home" value="/home/tcServer/springsource-tc-server-node/tomcat-6.0.25.A-RELEASE" />
  <property name="work.home"    value="${basedir}/work"/>
  <property name="dist.home"     value="${basedir}/dist"/>
  <property name="src.home"      value="${basedir}/src"/>
  <property name="web.home"      value="${basedir}/web"/>

  <target name="help">
    <echo>You can use the following targets:</echo>
    <echo> </echo>
    <echo>  help    : (default) Prints this message </echo>
    <echo>  all     : Cleans, compiles, and packages application</echo>
    <echo>  clean   : Deletes work directories</echo>
    <echo>  compile : Compiles servlets into class files</echo>
    <echo>  dist    : Packages artifacts into a deployable WAR</echo>
    <echo></echo>
    <echo>For example, to clean, compile, and package all at once, run:</echo>
    <echo>prompt> ant all </echo>
  </target>

  <!-- Define the CLASSPATH -->
  <path id="compile.classpath">
    <fileset dir="${tcserver.home}/bin">
      <include name="*.jar"/>
    </fileset>
    <pathelement location="${tcserver.home}/lib"/>
    <fileset dir="${tcserver.home}/lib">
      <include name="*.jar"/>
    </fileset>
  </path>

  <target name="all" depends="clean,compile,dist"
          description="Clean work dirs, then compile and create a WAR"/>

  <target name="clean"
          description="Delete old work and dist directories">
    <delete dir="${work.home}"/>
    <delete dir="${dist.home}"/>
  </target>

  <target name="prepare" depends="clean"
          description="Create working dirs and copy static files to work dir">
    <mkdir  dir="${dist.home}"/>
    <mkdir  dir="${work.home}/WEB-INF/classes"/>
    <!-- Copy static HTML and JSP files to work dir -->
    <copy todir="${work.home}">
      <fileset dir="${web.home}"/>
    </copy>
  </target>

  <target name="compile" depends="prepare"
          description="Compile Java sources and copy to WEB-INF/classes dir">
    <javac srcdir="${src.home}"
          destdir="${work.home}/WEB-INF/classes">
        <classpath refid="compile.classpath"/>
    </javac>
    <copy  todir="${work.home}/WEB-INF/classes">
      <fileset dir="${src.home}" excludes="**/*.java"/>
    </copy>

  </target>


  <target name="dist" depends="compile"
          description="Create WAR file for binary distribution">
    <jar jarfile="${dist.home}/${app.name}.war"
         basedir="${work.home}"/>
  </target>

</project> 

Description of the build.xml 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.

11. Troubleshooting

The following sections describe common problems and resolutions.

11.1 HQ: Resources Not Showing up in the HQ User Interface

By default, an HQ Agent checks for new resources only once a day. For example, if you start the HQ Server and HQ Agent, and then create a new tc Runtime instance and start it, you might have to wait 24 hours for the new tc Runtime instance to be auto-discovered by HQ. You can force an auto-discovery of new resources in two ways:

  • Stop and start the HQ Agent on the computer for which you want to force an auto-discovery. When the HQ Agent starts, it automatically checks for new resources. See Starting and Stopping the HQ Server and Agents for details.

  • Use the HQ user interface to force an auto-discovery:

    1. From the main dashboard, click the Resources > Browse link.

    2. Click the Platforms(XX) link.

    3. In the table, click on the name of the platform for which you want to force an auto-discovery.

    4. In the top-right Tools Menu box, click New Auto-Discovery.

    5. In the top section called Quick Auto-Discovery Scan, click OK.

    New resources show up in the Auto-Discovery portlet of the main dashboard as soon as HQ completes the scan of the platform.

11.2 HQ: Errors When Trying to Add an Auto-Discovered Resource

If you get errors when trying to add an auto-discovered resource to the HQ server using the user interface:

  1. Log onto the platform that hosts the resource that is returning errors when you try to add it using the HQ user interface.

  2. Stop the HQ Agent. See Starting and Stopping the HQ Server and Agents for details.

  3. Change to the HQ_AGENT_INSTALL_DIR directory, where HQ_AGENT_INSTALL_DIR refers to the directory in which you installed the HQ Agent, such as /home/tcserver/springsource-tc-server-node/hyperic-hq-agent-4.2.X.X-EE.

  4. Remove the data directory.

  5. Start the HQ Agent.

    Because you removed the data directory, the Agent operates as if this is a new installation, so the start script takes you through the configuration process for the Agent again. This step often clears up the auto-discovery errors and allows you to again add all new auto-discovered resources through the HQ user interface.

11.3 HQ 4.3: Non-hqadmin User With Custom Role Unable to Restart tc Runtime Instance

This troubleshooting note applies only to HQ 4.3 or later, not to HQ 4.2.

Due to changes in the permission model of HQ 4.3, the role assigned to non-hqadmin users who want to control tc Runtime instances might need to be updated such that the role is assigned a group that contains the Platform resource on which the tc Runtime instance runs. This change applies only to HQ 4.3 installations that have been upgraded with the tc Server HQ plug-in.

For example, assume that you have installed HQ 4.3 and upgraded it with the tc Server HQ plugin, as described in Upgrading an Existing 4.2 or 4.3 or 4.4 Hyperic HQ Installation to Manage tc Runtime Instances. Further assume that you have created and started a tc Runtime instance on a platform on which you have also installed the HQ Agent. Then, as the hqadmin user in the HQ user interface, you:

  1. Add the tc Runtime instance to the HQ inventory.
  2. Create an HQ group that includes the tc Runtime instance.
  3. Create a custom role and assign it the HQ group that contains the tc Runtime instance. This role has full permissions for all resource types.
  4. Create a new user and assign it to the new custom role.

Now assume that you log out as hqadmin and then log in as the new user. Because the role to which the user has been assigned, it would seem logical that you will be able to perform all configuration, deployment, and control actions on the tc Runtime instance; however, this is not true. If you try to restart the tc Runtime instance, you will get the following error:

Unable to perform auto-discovery following server restart: invalid permissions for auto-discovery scan

The solution to this problem is to:

  1. Log in to the HQ user interface as the hqadmin user, or other super-user.
  2. Create an HQ group that contains the Platform resource on which the tc Runtime is running.
  3. Update the custom role, assigning it this new group.

Now, if you log in as the new user, you will be able to restart the tc Runtime instance.

11.4 HQ Agent: Errors When Starting on Solaris

This section applies to Solaris platforms only.

If you try to start the HQ Agent on Solaris and get errors similar to the following:

prompt$ cd /home/tcserver/agent-4.2.0.7-EE/bin
prompt$ ./hq-agent.sh start

Bad string
Unable to locate any of the following binaries:
/home/tcserver/agent-4.2.0.7-EE/wrapper/sbin/../../wrapper/sbin/wrapper---32
/home/tcserver/agent-4.2.0.7-EE/wrapper/sbin/../../wrapper/sbin/wrapper---64
/home/tcserver/agent-4.2.0.7-EE/wrapper/sbin/../../wrapper/sbin/wrapper
...

make sure that you have set the locale correctly on your Solaris computer. In particular, the locale must not be set to a UTF-8 locale, such as en_US.UTF-8. The following are sample settings for the LC_CTYPE environment variable that resolve the problem:

LC_CTYPE=en_US
LC_CTYPE=en_US.ISO8859-1
LC_CTYPE=en_US.ISO8859-15

11.5 tc Runtime: Hot Redeploy/Stop/Undeploy on Windows Fails

Because of the way that file system locking works on Windows platforms, hot redeployment of a Web application on Windows can sometimes fail. Hot redeployment may also fail when you stop or undeploy a Web application on Windows. The problem can occur when you use the HQ user interface or the tcsadmin command-line interface.

To resolve the problem:

  1. Update the CATALINA_BASE/conf/context.xml file of the tc Runtime instance and set the following two attributes of the <Context> element to true:

    • antiJARLocking: When set to true, the Tomcat classloader takes extra measures to avoid JAR file locking when resources are accessed inside JARs through URLs. This action affects the startup time of applications, but is useful on platforms (such as Windows) or configurations where file locking can occur.

    • antiResourceLocking: When set to true, Tomcat prevents any file locking. This action affects startup time of applications significantly, but allows full Web application hot redeploy on platforms (such as Windows) or configurations where file locking can occur.

    The following context.xml snippet shows how to specify the attributes; only the relevant part of the file is shown:

    <Context antiJARLocking="true" antiResourceLocking="true">
    
           <WatchedResource>...
  2. Restart the tc Runtime instance for the change to take effect.

Setting antiJARLocking and antiResourceLocking to true forces tc Runtime to copy files rather than read them in place. Also, if you try to copy in a new .jsp file directly, tc Runtime does not pick it up.

If you prefer, you can set these two properties in the context.xml file of the application itself rather than in the context.xml file for the entire tc Runtime instance.

For more information and warnings about configuring the context.xml file, see The Context Container.

11.6 tc Runtime: Error When Running a Web Application on tc Runtime and Using SpringSource Tool Suite

When you use SpringSource Tool Suite (STS) with tc Server, and you try to run a Web application on the configured tc Runtime, you might get the following error:

Nov 29, 2009 7:47:29 PM com.springsource.tcserver.security.PropertyDecoder <init<
INFO: tcServer property decoder has been initialized.
Nov 29, 2009 7:47:30 PM com.springsource.tcserver.serviceability.rmi.JmxSocketListener init
INFO: Started up JMX registry on 127.0.0.1:6969
Nov 29, 2009 7:47:30 PM org.apache.coyote.http11.Http11Protocol init
SEVERE: Error initializing endpoint
java.net.SocketException: Unrecognized Windows Sockets error: 0: JVM_Bind
at java.net.PlainSocketImpl.socketBind(Native Method)
at java.net.PlainSocketImpl.bind(PlainSocketImpl.java :365)
at java.net.ServerSocket.bind(ServerSocket.java:319)
at java.net.ServerSocket.<init<(ServerSocket.java:185 )
at java.net.ServerSocket.<init<(ServerSocket.java:141 )
... and so on

STS might not have write permission to the main tc Server installation path, and the tc Runtime has to create files when it starts. Modify the path of tc Runtime in STS to use the workspace metadata.

11.7 tc Runtime: JVM Performing a Full GC

By default, tc Runtime instances have JMX turned on so that you can use Hyperic HQ to monitor and manage the instances. Specifically, tc Runtime instances enable JMX using the JmxSocketListener in the server.xml configuration file, as shown:

<Listener className="com.springsource.tcserver.serviceability.rmi.JmxSocketListener" 
          port="${jmx.port}"
          ...
/>

When JMX is enabled in this way, some JVMs (such as Sun's) that do distributed garbage collection will periodically invoke System.gc, causing a Full GC. This action can affect the performance of your deployed Web applications.

There are two ways to work around this issue:

Specify that the JVM invoke the System.gc() less often. For example, to configure the Sun JVM to invoke System.gc() at one-hour intervals, use the following JVM options:

-Dsun.rmi.dgc.client.gcInterval=3600000
-Dsun.rmi.dgc.server.gcInterval=3600000

Alternatively, disable explicit GC altogether. For example, to disable GC for the Sun JVM:

-XX:+DisableExplicitGC

In both cases, set these JVM options in the INSTANCE-DIR/bin/setenv.sh|bat file using the JVM_OPTS variable appropriate to your platform.

Appendix A. Using the ASF Layout

It is assumed in the tc Server documentation that most users create server instances that use the SpringSource layout. However, some users might prefer the Apache Standard Format (ASF) layout. This appendix provides information about the ASF layout.

A.1 Differences Between the SpringSource and ASF Layouts of tc Server

SpringSource tc Server provides two "flavors" of the tc Runtime, based on the layout of their installation directories: ASF and SpringSource. ASF uses the standard Apache Tomcat directory layout that current Apache users should instantly recognize. This directory is located in INSTALL_DIR/springsource-tc-server-edition/tomcat-version, where:

  • INSTALL_DIR is the main tc Server installation directory, such as /home/tcserver .
  • version is the version of tc Runtime such as 6.0.25.A-RELEASE .
  • edition is the edition of tc Server you are using, such as node , developer , or standard .

For example, the directory /home/tcserver/springsource-tc-server-node/tomcat-6.0.25.A-RELEASE is ready to use immediately, which means it includes a tc Runtime instance by default.

The SpringSource layout is slightly different, mostly in that it supports multiple instances of tc Runtime with a single set of binaries. This adds the following value for customers:

  • A single installation of tc Server (that uses the SpringSource layout) supports multiple running tc Runtime instances.

  • One set of binaries means easy upgrades of all the associated instances.

  • Multiple separate instances allows testing of configuration and code changes without touching the production instance.

The SpringSource layout also provides scripts for easily creating new instances of tc Runtime and quickly stopping and starting it. The SpringSource layout does not, however, provide a default server instance right after installation; you must create one using the script. (The only exception is the Developer Edition of tc Server, which includes a default instance preconfigured with Spring Insight.) See Creating tc Runtime Instance: Typical Steps.

A.2 Creating a New tc Runtime Instance Using the ASF Layout

The ASF layout includes a server instance once you install tc Server. The following procedure describes how to create a new instance in addition to the default out-of-the-box one.

This section covers both Unix and Windows commands. The documentation uses Unix-like forward slashes (/) for directories; if you are on a Windows platform, change these to back slashes (\).

  1. Open a terminal window (Unix) or command prompt (Windows).

  2. Create a new directory that will contain the new tc Runtime instance such as /home/tcserverNew. For example, on Unix:

    prompt$ mkdir /home/tcserverNew
  3. Unzip the original ZIP file into the directory you created in the preceding step. The ZIP file will be called springsource-tc-server-edition-2.0.X.RELEASE.zip, where edition refers to the Edition of tc Server you are using (either node, developer, or standard.)

    Your new ASF tc Runtime instance is in this new directory, such as /home/tcserverNew/springsource-tc-server-node/tomcat-6.0.25.A-RELEASE.

  4. If you will run this tc Runtime instance on the same computer as another tc Runtime instance, make sure that the various port numbers are unique. You configure these ports in the INSTALL_DIR/springsource-tc-server-edition/tomcat-version/conf/server.xml file, where INSTALL_DIR refers to the directory in which you just installed tc Server, edition refers to the Edition of tc Server you are using, and version refers to the version of tc Runtime, such as 6.0.25.A. In particular, make sure the following ports are unique for each server instance:

    • The port and redirectPort attributes of the HTTP <Connector> child element of the catalina <Service>. These ports are the main tc Runtime instance listen and redirect ports.

    • The port attribute of the <Listener> element with classname com.springsource.tcserver.serviceability.rmi.JmxSocketListener. This is the JMX port that HQ uses to communicate with the tc Runtime instance so that you can manage it.

    [Note]Note

    The server.xml file might use variable substitution for these ports; in this case the attribute looks something like port="${http.port}". If this is the case, edit the catalina.properties file in the same directory as the server.xml; the properties file contains actual values for the variables.

A.3 Starting and Stopping tc Runtime Instances in the ASF Layout

This section describes how to start and stop tc Runtime instances that use the ASF layout on both Windows and Unix platforms.

Unix: Starting and Stopping Instances Interactively Using tcruntime-ctl.sh

To stop and start tc Runtime instances in the ASF layout:

  1. Start a terminal window and change to the CATALINA_HOME/bin directory of the tc Runtime instance you want to start or stop.

    For example, if you installed tc Server in /home/tcserver, are using a Managed Node, and are using version 6.0.25.A-RELEASE of tc Runtime:

    prompt$ cd /home/tcserver/springsource-tc-server-node/tomcat-6.0.25.A-RELEASE/bin
  2. Start the tc Runtime instance by executing the tcruntime-ctl.sh start command:

     prompt$ ./tcruntime-ctl.sh start

    This command starts the tc Runtime instance as a daemon under the current user account.

  3. Stop a currently running tc Runtime instance by executing the tcruntime-ctl.sh stop:

    prompt$ ./tcruntime-ctl.sh stop

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

The ASF layout of tc Server also includes the standard Apache Tomcat script for starting and stopping the server: catalina.sh. This script is for users who are already familiar with Apache Tomcat and prefer to continue using the same script to start and stop the server.

[Note]Note

The two methods of starting the server (catalina.bat start and tcruntime-ctl.bat start) are essentially the same. However, the two methods of stopping the server differ in the following important way: catalina.bat stop takes into account the value of the SHUTDOWN port and if it is -1, the script does not stop the server. The tcruntime-ctl.bat stop command, however, stops the server even if its SHUTDOWN port is set to -1.

Windows: Starting and Stopping Instances as Windows Services

To stop and start tc Runtime instances in the ASF layout:

  1. Start a command prompt and change to the CATALINA_HOME\bin directory of the tc Runtime instance you want to start or stop.

    For example, if you installed tc Server in c:\home\tcserver, are using a Managed Node, and are using version 6.0.25.A-RELEASE:

    prompt$ cd c:\home\tcserver\springsource-tc-server-node\tomcat-6.0.25.A-RELEASE\bin
  2. Install the tc Runtime instance as a Windows service by executing the following command:

    prompt$ tcruntime-ctl.bat install 

    Once the instance is installed as a Windows service, you use the Services Window control panel to stop and start the service. It is displayed in the Services Window with the name SpringSource tc Runtime XXX.

  3. To uninstall the tc Runtime service:

    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 server instance manually. See tcruntime-ctl Command Reference for the full list of commands of the tcruntime-ctl script.

The ASF layout of tc Server also includes the standard Apache Tomcat script for starting and stopping the server: catalina.bat. This script is for users who are already familiar with Apache Tomcat and prefer to continue using the same script to start and stop the server.

[Note]Note

The two methods of starting the server (catalina.bat start and tcruntime-ctl.bat start) are essentially the same. However, the two methods of stopping the server differ in the following important way: catalina.bat stop takes into account the value of the SHUTDOWN port and if it is -1, the script does not stop the server. The tcruntime-ctl.bat stop command, however, stops the server even if its SHUTDOWN port is set to -1.